CSC318/backend/README.md

Language Learning App API Documentation

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.

Endpoints

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." }

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" }

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:
  • audio_file: 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.