From e7e72bc15a5dd192c9f600caf0174bf0da1f84e4 Mon Sep 17 00:00:00 2001
From: youssefsoli <youssefdevelops@gmail.com>
Date: Mon, 27 Nov 2023 04:08:31 -0500
Subject: [PATCH] Cleaned up readme

---
 backend/README.md | 107 +++++++++++++++++++++++++++++++++++-----------
 1 file changed, 81 insertions(+), 26 deletions(-)

diff --git a/backend/README.md b/backend/README.md
index f7da530..f8e5e91 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,35 +1,90 @@
 
-> For the demo, language ∈ {EN_JA, EN_ZH-CN}
+# Language Learning App API Documentation
 
-POST /ai-mark {
-	question: str, 
-	user_answer: str, 
-	expected: str, 
-	chapter: str,
-	language: str
-}
--> {correct: bool, reason: str}
+This document outlines the API endpoints for a language learning application, detailing the functionalities related to AI marking, chat interactions, character interactions, and speech recognition.
 
-POST /human-chat {
-	target_name: str,
-	target_hobbies: list\[str],
-	history: list\[{from\_me: bool, msg: str}],
-	language: str
-}
--> {msg: str}
+## Endpoints
 
-> Chat histories will be stored in localStorage
+### AI Marking (`/ai-mark`)
+- **Method:** POST
+- **Description:** Marks a user's answer to a language learning question.
+- **Request Body:** `AIMarkRequest`
+  - `question`: The question posed to the user.
+  - `user_answer`: The user's response to the question.
+  - `expected`: The expected correct answer.
+  - `chapter`: The chapter from which the question is taken.
+  - `language`: The language in which the question is asked.
+- **Response:** `AIMarkResponse`
+  - `correct`: Boolean indicating if the answer is correct.
+  - `reason`: Reason for the marking.
+- **Example Request:** `{ "question": "What is your name?", "user_answer": "My name is John", "expected": "My name is [Name]", "chapter": "Introduction", "language": "English" }`
+- **Example Response:** `{ "correct": true, "reason": "The answer is grammatically correct and matches the expected pattern." }`
 
-POST /recognize (Body is an audio file)
--> {text: str}
+### Human Chat Creation (`/human-chat`)
+- **Method:** POST
+- **Description:** Creates a new chat session for language learning.
+- **Request Body:** `HumanChatCreationRequest`
+  - `user_name`: Name of the language learner.
+  - `user_hobbies`: List of hobbies of the language learner.
+  - `target_name`: Name of the target individual for the chat.
+  - `target_hobbies`: List of hobbies of the target individual.
+  - `language`: Language of the chat.
+- **Response:** `HumanChatCreationResponse`
+  - `session_id`: UUID of the newly created chat session.
+- **Example Request:** `{ "user_name": "Alice", "user_hobbies": ["reading", "writing"], "target_name": "Bob", "target_hobbies": ["gaming", "cooking"], "language": "Spanish" }`
+- **Example Response:** `{ "session_id": "123e4567-e89b-12d3-a456-426614174000" }`
 
-POST /character-chat {
-	character: str
-	history: list\[{from_me: bool, msg: str}]
-	language: str
-}
--> {msg: str, audio: UUID}
 
-GET /audio/{UUID}
+### Human Chat Message (`/human-chat/{session_id}`)
+- **Method:** POST
+- **Description:** Sends a message in a human chat session and receives a response.
+- **URL Parameter:** `session_id` - UUID of the chat session.
+- **Request Body:** `HumanChatMessageRequest`
+  - `msg`: The message sent by the user.
+- **Response:** `HumanChatMessageResponse`
+  - `msg`: The AI-generated response message.
+- **Example Request:** `{ "msg": "How is the weather today?" }`
+- **Example Response:** `{ "msg": "It's quite sunny here. Perfect for a walk!" }`
+
+### Character Chat Creation (`/character-chat`)
+- **Method:** POST
+- **Description:** Initializes a chat session with a fictional character for language learning.
+- **Request Body:** `CharacterChatCreationRequest`
+  - `character`: Name of the character for the chat session.
+  - `user_name`: Name of the user engaging in the chat.
+  - `language`: The language in which the conversation will occur.
+- **Response:** `CharacterChatCreationResponse`
+  - `session_id`: UUID of the created character chat session.
+- **Example Request:** `{ "character": "ash_pokemon", "user_name": "Alice", "language": "Japanese" }`
+- **Example Response:** `{ "session_id": "123e4567-e89b-12d3-a456-426614174000" }`
+
+### Character Chat Message (`/character-chat/{session_id}`)
+- **Method:** POST
+- **Description:** Engages in a conversation with a fictional character.
+- **URL Parameter:** `session_id` - UUID of the character chat session.
+- **Request Body:** `CharacterChatMessageRequest`
+  - `msg`: User's message to the character.
+- **Response:** `CharacterChatMessageResponse`
+  - `msg`: The character's response.
+  - `audio_id`: UUID for the audio version of the character's response.
+- **Example Request:** `{ "msg": "Tell me about your latest adventure!" }`
+- **Example Response:** `{ "msg": "I just won a gym badge in a thrilling battle!", "audio_id": "456f7890-f12a-34b5-c678-901234567890" }`
+
+### Speech Recognition (`/recognize`)
+- **Method:** POST
+- **Description:** Converts spoken words in an audio file to text.
+- **Request Body:** An audio file uploaded using `UploadFile`.
+- **Response:** `RecognizeResponse`
+  - `text`: Transcribed text from the audio file.
+- **Example Response:** `{ "text": "Hello, how can I help you today?" }`
+
+### Retrieve Audio (`/audio/{UUID}`)
+- **Method:** GET
+- **Description:** Retrieves the audio response corresponding to a given UUID.
+- **URL Parameter:** `UUID` - Unique identifier for the audio file.
+- **Response:** Streaming audio content in `audio/mpeg` format.
+- **Note:** Returns a 404 error if the audio is not found.
+
+## Development
 
 Run `openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365` to generate a self-signed certificate for HTTPS.
\ No newline at end of file