🎓 Smart Tutor

A personalized AI language tutor built with n8n workflows that helps learners practice conversations in their target language through intelligent, context-aware interactions.

📋 Table of Contents

• Features
• Workflow Overview
• Requirements
• Setup Instructions
• API Usage
• Example Responses

✨ Features

• 🎯 Personalized Learning: Saves user preferences (languages, topics, teaching style)
• 🧠 Context Awareness: Remembers recent conversation history for coherent interactions
• 🤖 AI-Powered Responses: Generates intelligent responses tailored to the learner's level
• 🔊 Text-to-Speech: Converts tutor responses into audio for pronunciation practice
• 📊 Progress Tracking: Stores conversation history for learning analytics
• 🎭 Multiple AI Personalities: Choose from different teaching styles (friendly, strict, funny)

🚀 Workflow Overview

1. User Onboarding Workflow

Trigger: POST /onboarding

Purpose: Initialize user profile and preferences

Saves:

• user_id - Unique identifier for the user
• native_language - User's native language
• target_language - Language they want to learn
• topic - Preferred conversation topics
• ai_mood - Teaching personality (friendly, strict, funny, etc.)

2. Conversational Tutor Workflow

Trigger: POST /chat

Process Flow:

1. Fetch User Context: Retrieves user preferences and conversation history
2. Generate AI Response: Creates contextually appropriate responses using OpenAI
3. Save Interaction: Stores both user message and tutor response
4. Text-to-Speech: Converts tutor response to audio
5. Return Response: Sends back text and audio to the user

⚙️ Requirements

Core Dependencies

• n8n - Workflow automation platform
  • Cloud account at n8n.cloud OR
  • Local installation via Docker

API Keys

• OpenAI API Key (Required)
  • Used for AI conversation generation
  • Also provides TTS functionality
• Alternative TTS Services (Optional)
  • Google Cloud Text-to-Speech API
  • ElevenLabs API
  • Azure Speech Services
  • Hugging Face TTs

System Requirements

• Docker (for local setup)
• Node.js 16+ (if running n8n locally without Docker)

🛠️ Setup Instructions

Option 1: Docker Setup

1. Start n8n with Docker

   docker run -it --rm \
     -p 5678:5678 \
     -v ~/.n8n:/home/node/.n8n \
     n8nio/n8n

2. Access n8n Interface Open your browser and navigate to: http://localhost:5678

Option 2: n8n Cloud

1. Sign up at n8n.cloud
2. Create a new workflow instance

Workflow Configuration

1. Import Workflows

   • In the n8n UI, navigate to: Workflows → Import from File
   • Upload the .json files from the /workflow folder
   • Import both onboarding and chat workflows

2. Configure API Credentials

   • Go to: Credentials → Add Credential
   • Add your OpenAI API Key/Hugging Face API Key:
     • Credential Type: OpenAI
     • API Key: Your OpenAI API key
   • (Optional) Add additional TTS service credentials

3. Assign Credentials to Nodes

   • Open each imported workflow
   • Click on nodes that require authentication
   • Assign the appropriate credentials

4. Activate Workflows

   • Ensure both workflows are set to "Active"
   • Verify webhook URLs are accessible

📡 API Usage

User Onboarding

Endpoint: POST /webhook/onboarding

curl -X POST http://localhost:5678/webhook/onboarding \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "native_language": "English",
    "target_language": "Spanish",
    "topic": "Travel",
    "ai_mood": "friendly"
  }'

Request Parameters:

• user_id (string): Unique identifier for the user
• native_language (string): User's native language
• target_language (string): Language to learn
• topic (string): Preferred conversation topic
• ai_mood (string): Teaching style preference

Chat Interaction

Endpoint: POST /webhook/chat

curl -X POST http://localhost:5678/webhook/chat \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "message": "How do I say where is the airport?"
  }'

Request Parameters:

• user_id (string): User identifier (must match onboarding)
• message (string): User's question or conversation input

📦 Example Responses

Successful Chat Response

{
  "status": "success",
  "response_text": "You can say: '¿Dónde está el aeropuerto?' This literally means 'Where is the airport?' in Spanish. Try to practice the pronunciation: DON-deh es-TAH el ah-eh-ro-PWER-to.",
  "audio_url": "https://your-storage-service/audio/response123.mp3",
  "conversation_id": "conv_456",
  "timestamp": "2024-01-15T10:30:00Z"
}

Built with ❤️ and n8n