From ce15b171b079d0b941fe78b25d5f97d10ac024ad Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 08:45:38 +0100
Subject: [PATCH 01/10] Add Smart Tutor Chat Agent feature

Implement AI-powered chat tutor for language learning with:
- Database: chats, chat_messages, and word_pairs tables with RLS
- Backend: ChatTutorCrew with router, translation, and vocabulary agents
- API: Chat endpoints for messaging, chat management, and history
- Frontend: Full chat UI with sidebar, messages, and adaptive components
- Features: Translation, vocabulary suggestions, domain boundary enforcement

The chat agent responds to language-learning queries only and
politely declines off-topic requests. Structured responses enable
adaptive UI rendering for word suggestions and save confirmations.
---
 ai/run.py                                     | 339 +++++++++++++++++-
 ai/src/crews/chat_tutor_crew/__init__.py      |   3 +
 .../crews/chat_tutor_crew/config/agents.yaml  |  34 ++
 .../crews/chat_tutor_crew/config/tasks.yaml   |  57 +++
 ai/src/crews/chat_tutor_crew/crew.py          |  49 +++
 ai/src/crews/chat_tutor_crew/schemas.py       |  24 ++
 .../20250215000000_create_chat_tables.sql     |  86 +++++
 web/Dockerfile                                |   5 +-
 web/package.json                              |   1 +
 web/src/App.tsx                               |   2 +
 web/src/components/app-sidebar.tsx            |   6 +
 web/src/components/chat/chat-input.tsx        |  60 ++++
 web/src/components/chat/chat-message.tsx      |  67 ++++
 web/src/components/chat/chat-sidebar.tsx      |  87 +++++
 .../components/chat/word-suggestion-card.tsx  |  81 +++++
 web/src/components/ui/scroll-area.tsx         |  46 +++
 web/src/components/ui/textarea.tsx            |  24 ++
 web/src/hooks/use-chat.ts                     | 154 ++++++++
 web/src/lib/ai-service.ts                     | 181 ++++++++++
 web/src/pages/chat.tsx                        | 122 +++++++
 20 files changed, 1421 insertions(+), 7 deletions(-)
 create mode 100644 ai/src/crews/chat_tutor_crew/__init__.py
 create mode 100644 ai/src/crews/chat_tutor_crew/config/agents.yaml
 create mode 100644 ai/src/crews/chat_tutor_crew/config/tasks.yaml
 create mode 100644 ai/src/crews/chat_tutor_crew/crew.py
 create mode 100644 ai/src/crews/chat_tutor_crew/schemas.py
 create mode 100644 supabase/migrations/20250215000000_create_chat_tables.sql
 create mode 100644 web/src/components/chat/chat-input.tsx
 create mode 100644 web/src/components/chat/chat-message.tsx
 create mode 100644 web/src/components/chat/chat-sidebar.tsx
 create mode 100644 web/src/components/chat/word-suggestion-card.tsx
 create mode 100644 web/src/components/ui/scroll-area.tsx
 create mode 100644 web/src/components/ui/textarea.tsx
 create mode 100644 web/src/hooks/use-chat.ts
 create mode 100644 web/src/pages/chat.tsx

diff --git a/ai/run.py b/ai/run.py
index d6cff3c..2a67672 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -9,12 +9,14 @@
 from flask_cors import CORS
 from supabase import create_client, Client
 
-from crews.random_phrase_crew.crew import RandomPhraseCrew
-from crews.random_phrase_crew.schemas import PhraseOutput
-from crews.pronunciation_tips_crew.crew import PronunciationTipsCrew
-from crews.pronunciation_tips_crew.schemas import PronunciationTipsOutput
+from src.crews.random_phrase_crew.crew import RandomPhraseCrew
+from src.crews.random_phrase_crew.schemas import PhraseOutput
+from src.crews.pronunciation_tips_crew.crew import PronunciationTipsCrew
+from src.crews.pronunciation_tips_crew.schemas import PronunciationTipsOutput
+from src.crews.chat_tutor_crew.crew import ChatTutorCrew
+from src.crews.chat_tutor_crew.schemas import TutorResponse
 
-from lib.tracer import traceable
+from src.lib.tracer import traceable
 
 # Configure logging
 logging.basicConfig(
@@ -398,6 +400,333 @@ async def get_pronunciation_tips():
         return jsonify({"error": f"An error occurred: {str(e)}"}), 500
 
 
+async def handle_tool_call(tool_name: str, arguments: dict, user_id: str) -> str:
+    """
+    Handle tool invocations from the AI agent.
+
+    Args:
+        tool_name: Name of the tool to call
+        arguments: Arguments to pass to the tool
+        user_id: The user's UUID
+
+    Returns:
+        Result message from the tool execution
+    """
+    if tool_name == "save_word_pair":
+        source_word = arguments.get("source_word")
+        translated_word = arguments.get("translated_word")
+        context_sentence = arguments.get("context_sentence")
+
+        if not source_word or not translated_word:
+            return "Error: Both source_word and translated_word are required to save a word pair."
+
+        # Check for duplicates
+        existing = supabase_admin.table("word_pairs").select("*") \
+            .eq("user_id", user_id) \
+            .eq("source_word", source_word) \
+            .eq("translated_word", translated_word) \
+            .execute()
+
+        if existing.data:
+            return f"'{source_word}' is already in your flashcard deck!"
+
+        # Insert new word pair
+        supabase_admin.table("word_pairs").insert({
+            "user_id": user_id,
+            "source_word": source_word,
+            "translated_word": translated_word,
+            "context_sentence": context_sentence
+        }).execute()
+
+        return f"Done! I've added '{source_word} → {translated_word}' to your flashcard deck."
+
+    return f"Unknown tool: {tool_name}"
+
+
+@app.route("/api/chat/message", methods=["POST"])
+@require_auth
+async def send_chat_message():
+    """
+    Send a message to the chat tutor and get an AI response.
+
+    Request body:
+        {
+            "chat_id": "uuid",
+            "message": "user message"
+        }
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        {
+            "id": "message_id",
+            "chat_id": "chat_id",
+            "role": "assistant",
+            "content": {...},
+            "created_at": "timestamp"
+        }
+    """
+    try:
+        data = request.get_json()
+
+        if not data or "message" not in data:
+            return jsonify({"error": "Request body must include 'message' field"}), 400
+
+        message = data.get("message", "").strip()
+        chat_id = data.get("chat_id")
+
+        if not message:
+            return jsonify({"error": "'message' cannot be empty"}), 400
+
+        user_id = request.user.id
+
+        # Fetch conversation history if chat_id is provided
+        conversation_history = []
+        if chat_id:
+            messages_response = supabase_admin.table("chat_messages").select("*") \
+                .eq("chat_id", chat_id) \
+                .limit(20) \
+                .execute()
+
+            # Reverse to get chronological order
+            conversation_history = list(reversed(messages_response.data))
+
+        # Fetch user context
+        user_context, target_language = await get_user_context(user_id)
+
+        # Format conversation history for the AI
+        history_text = ""
+        for msg in conversation_history[-10:]:  # Last 10 messages for context
+            role = msg.get("role", "user")
+            content = msg.get("content", {})
+            if isinstance(content, dict):
+                content_str = content.get("content", str(content))
+            else:
+                content_str = str(content)
+            history_text += f"{role.capitalize()}: {content_str}\n"
+
+        # Run the ChatTutorCrew
+        inputs = {
+            'user_message': jsonify(message).get_data(as_text=True),
+            'target_language': jsonify(target_language if target_language else "None").get_data(as_text=True),
+            'user_context': jsonify(user_context if user_context else "").get_data(as_text=True),
+            'conversation_history': jsonify(history_text if history_text else "No previous messages").get_data(as_text=True)
+        }
+
+        result = await ChatTutorCrew().crew().kickoff_async(inputs=inputs)
+
+        # Extract the response
+        if hasattr(result, 'pydantic'):
+            tutor_response: TutorResponse = result.pydantic
+        else:
+            # Fallback for unexpected result format
+            tutor_response = TutorResponse(
+                response_type="text",
+                content=str(result),
+                data=None,
+                tool_calls=None
+            )
+
+        # Handle tool calls if present
+        if tutor_response.tool_calls:
+            for tool_call in tutor_response.tool_calls:
+                tool_result = await handle_tool_call(
+                    tool_call.name,
+                    tool_call.arguments,
+                    user_id
+                )
+                logger.info(f"Tool {tool_call.name} result: {tool_result}")
+
+        # Save user message to database
+        if not chat_id:
+            # Create new chat if needed
+            chat_response = supabase_admin.table("chats").insert({
+                "user_id": user_id,
+                "title": message[:50] + "..." if len(message) > 50 else message
+            }).execute()
+            chat_id = chat_response.data[0]["id"]
+
+        # Save user message
+        supabase_admin.table("chat_messages").insert({
+            "chat_id": chat_id,
+            "role": "user",
+            "content": {"content": message}
+        }).execute()
+
+        # Save assistant response
+        response_data = supabase_admin.table("chat_messages").insert({
+            "chat_id": chat_id,
+            "role": "assistant",
+            "content": tutor_response.model_dump()
+        }).execute()
+
+        # Update chat's updated_at timestamp
+        supabase_admin.table("chats").update({
+            "updated_at": "now()"
+        }).eq("id", chat_id).execute()
+
+        # Return the assistant message
+        assistant_message = response_data.data[0]
+        return jsonify(assistant_message), 200
+
+    except Exception as e:
+        logger.error(f"Error sending chat message: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
+@app.route("/api/chats", methods=["GET"])
+@require_auth
+async def get_chats():
+    """
+    Get all chats for the current user.
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        [
+            {
+                "id": "uuid",
+                "user_id": "uuid",
+                "title": "chat title",
+                "created_at": "timestamp",
+                "updated_at": "timestamp"
+            }
+        ]
+    """
+    try:
+        user_id = request.user.id
+
+        response = supabase_admin.table("chats").select("*") \
+            .eq("user_id", user_id) \
+            .execute()
+
+        return jsonify(response.data), 200
+
+    except Exception as e:
+        logger.error(f"Error fetching chats: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
+@app.route("/api/chats", methods=["POST"])
+@require_auth
+async def create_chat():
+    """
+    Create a new chat.
+
+    Request body:
+        {
+            "title": "optional title"
+        }
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        {
+            "id": "uuid",
+            "user_id": "uuid",
+            "title": "title or null",
+            "created_at": "timestamp",
+            "updated_at": "timestamp"
+        }
+    """
+    try:
+        data = request.get_json() or {}
+        title = data.get("title")
+        user_id = request.user.id
+
+        response = supabase_admin.table("chats").insert({
+            "user_id": user_id,
+            "title": title
+        }).execute()
+
+        return jsonify(response.data[0]), 201
+
+    except Exception as e:
+        logger.error(f"Error creating chat: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
+@app.route("/api/chats/<chat_id>", methods=["DELETE"])
+@require_auth
+async def delete_chat(chat_id: str):
+    """
+    Delete a chat and all its messages.
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        {"success": true}
+    """
+    try:
+        user_id = request.user.id
+
+        # Verify the chat belongs to the user
+        chat_response = supabase_admin.table("chats").select("*") \
+            .eq("id", chat_id) \
+            .eq("user_id", user_id) \
+            .execute()
+
+        if not chat_response.data:
+            return jsonify({"error": "Chat not found"}), 404
+
+        # Delete the chat (messages will be cascaded)
+        supabase_admin.table("chats").delete().eq("id", chat_id).execute()
+
+        return jsonify({"success": True}), 200
+
+    except Exception as e:
+        logger.error(f"Error deleting chat: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
+@app.route("/api/chats/<chat_id>/messages", methods=["GET"])
+@require_auth
+async def get_chat_messages(chat_id: str):
+    """
+    Get all messages for a chat.
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        [
+            {
+                "id": "uuid",
+                "chat_id": "uuid",
+                "role": "user" | "assistant" | "system",
+                "content": {...},
+                "created_at": "timestamp"
+            }
+        ]
+    """
+    try:
+        user_id = request.user.id
+
+        # Verify the chat belongs to the user
+        chat_response = supabase_admin.table("chats").select("*") \
+            .eq("id", chat_id) \
+            .eq("user_id", user_id) \
+            .execute()
+
+        if not chat_response.data:
+            return jsonify({"error": "Chat not found"}), 404
+
+        # Fetch messages
+        messages_response = supabase_admin.table("chat_messages").select("*") \
+            .eq("chat_id", chat_id) \
+            .execute()
+
+        return jsonify(messages_response.data), 200
+
+    except Exception as e:
+        logger.error(f"Error fetching chat messages: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
 if __name__ == "__main__":
     # Run the Flask app
     port = int(os.getenv("PORT", 8000))
diff --git a/ai/src/crews/chat_tutor_crew/__init__.py b/ai/src/crews/chat_tutor_crew/__init__.py
new file mode 100644
index 0000000..ff8211d
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/__init__.py
@@ -0,0 +1,3 @@
+from .crew import ChatTutorCrew
+
+__all__ = ['ChatTutorCrew']
diff --git a/ai/src/crews/chat_tutor_crew/config/agents.yaml b/ai/src/crews/chat_tutor_crew/config/agents.yaml
new file mode 100644
index 0000000..26318a3
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/config/agents.yaml
@@ -0,0 +1,34 @@
+router_agent:
+  role: >
+    Language Tutor Router
+  goal: >
+    Understand the user's intent and route to the appropriate specialist
+    or respond directly to general language learning questions
+  backstory: >
+    You are an intelligent router for a language learning platform. You excel at
+    understanding user intent and determining the best way to help them. You can
+    recognize when users need translations, vocabulary suggestions, or general
+    language guidance. You only respond to language-related questions and politely
+    redirect off-topic conversations back to language learning.
+
+translation_agent:
+  role: >
+    Translation Specialist
+  goal: >
+    Provide accurate translations and language explanations
+  backstory: >
+    You are a skilled translator and language educator with expertise in multiple
+    languages. You provide clear, accurate translations with helpful context about
+    grammar, usage, and cultural nuances. You understand the challenges of language
+    learners and explain concepts in an accessible way.
+
+vocabulary_agent:
+  role: >
+    Vocabulary Curator
+  goal: >
+    Suggest new vocabulary words with context and examples
+  backstory: >
+    You are a vocabulary expert who selects words based on the user's target language
+    and proficiency level. You provide words that are practical, useful, and come
+    with clear translations and example sentences. You help users build their
+    vocabulary systematically.
diff --git a/ai/src/crews/chat_tutor_crew/config/tasks.yaml b/ai/src/crews/chat_tutor_crew/config/tasks.yaml
new file mode 100644
index 0000000..56b536e
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/config/tasks.yaml
@@ -0,0 +1,57 @@
+route_task:
+  description: >
+    Analy the user's message and determine the appropriate response.
+
+    User message: {user_message}
+    Target language: {target_language}
+    User context: {user_context}
+
+    Conversation history:
+    {conversation_history}
+
+    Your task:
+    1. Understand what the user is asking for
+    2. Check if this is a language-learning related request
+    3. If it's NOT language-related, politely refuse and redirect
+    4. If it IS language-related, respond appropriately:
+       - Translation requests: Provide the translation with explanation
+       - Vocabulary requests: Suggest a word with translation and example
+       - Grammar questions: Explain the grammar concept
+       - General help: Guide the user on language learning
+    5. If the user asks to save a word pair, include a tool_call for "save_word_pair"
+
+    Important boundaries:
+    - Only respond to language-learning questions
+    - Politely decline off-topic requests (e.g., weather, news, general knowledge)
+    - When declining, suggest a language-related alternative
+
+    You must return your response as a JSON object with the following structure:
+    {
+      "response_type": "text" | "word_suggestion" | "save_confirmation" | "error",
+      "content": "Your response text here",
+      "data": {
+        "word": "source_word (for word_suggestion)",
+        "translation": "translated_word (for word_suggestion)",
+        "example": "example_sentence (for word_suggestion)"
+      },
+      "tool_calls": [
+        {
+          "name": "save_word_pair",
+          "arguments": {
+            "source_word": "word in target language",
+            "translated_word": "word in user's native language",
+            "context_sentence": "example using the word"
+          }
+        }
+      ]
+    }
+
+    response_type values:
+    - "text": Regular response (translation, explanation, etc.)
+    - "word_suggestion": When suggesting a new vocabulary word
+    - "save_confirmation": When confirming a word was saved
+    - "error": When declining an off-topic request
+  expected_output: >
+    A JSON object with response_type, content, optional data (for word suggestions),
+    and optional tool_calls (for saving words).
+  agent: router_agent
diff --git a/ai/src/crews/chat_tutor_crew/crew.py b/ai/src/crews/chat_tutor_crew/crew.py
new file mode 100644
index 0000000..2e8e3c7
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/crew.py
@@ -0,0 +1,49 @@
+from crewai import Agent, Crew, Process, Task
+from crewai.project import CrewBase, agent, crew, task
+from crewai.agents.agent_builder.base_agent import BaseAgent
+from typing import List, Optional
+from src.crews.base.llm import DEFAULT_LLM
+from src.crews.chat_tutor_crew.schemas import TutorResponse
+
+
+@CrewBase
+class ChatTutorCrew():
+    """Crew for handling chat interactions with the language tutor"""
+    agents: List[BaseAgent]
+    tasks: List[Task]
+
+    @agent
+    def router_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['router_agent'],
+            llm=DEFAULT_LLM
+        )
+
+    @agent
+    def translation_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['translation_agent'],
+            llm=DEFAULT_LLM
+        )
+
+    @agent
+    def vocabulary_agent(self) -> Agent:
+        return Agent(
+            config=self.agents_config['vocabulary_agent'],
+            llm=DEFAULT_LLM
+        )
+
+    @task
+    def route_task(self) -> Task:
+        return Task(
+            config=self.tasks_config['route_task'],
+            output_pydantic=TutorResponse
+        )
+
+    @crew
+    def crew(self) -> Crew:
+        return Crew(
+            agents=self.agents,
+            tasks=self.tasks,
+            process=Process.sequential
+        )
diff --git a/ai/src/crews/chat_tutor_crew/schemas.py b/ai/src/crews/chat_tutor_crew/schemas.py
new file mode 100644
index 0000000..f392eaf
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/schemas.py
@@ -0,0 +1,24 @@
+from pydantic import BaseModel, Field
+from typing import Optional, Literal, List, Dict, Any
+
+
+class ToolCall(BaseModel):
+    """Represents a tool call from the AI agent"""
+    name: str = Field(description="Name of the tool to call (e.g., 'save_word_pair')")
+    arguments: Dict[str, Any] = Field(description="Arguments to pass to the tool")
+
+
+class TutorResponse(BaseModel):
+    """Structured response from the chat tutor"""
+    response_type: Literal["text", "word_suggestion", "save_confirmation", "error"] = Field(
+        description="Type of response - determines UI rendering"
+    )
+    content: str = Field(description="The main text content of the response")
+    data: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Additional data for special response types (word, translation, example for word_suggestion)"
+    )
+    tool_calls: Optional[List[ToolCall]] = Field(
+        None,
+        description="List of tool calls the agent wants to make"
+    )
diff --git a/supabase/migrations/20250215000000_create_chat_tables.sql b/supabase/migrations/20250215000000_create_chat_tables.sql
new file mode 100644
index 0000000..fe27ed8
--- /dev/null
+++ b/supabase/migrations/20250215000000_create_chat_tables.sql
@@ -0,0 +1,86 @@
+-- Chat tables for Smart Tutor Chat feature
+-- These tables store chat sessions and messages between users and the AI tutor
+
+-- Create chats table
+create table public.chats (
+  id uuid default gen_random_uuid() primary key,
+  user_id uuid references auth.users(id) on delete cascade not null,
+  title text,
+  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
+  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
+);
+
+-- Enable RLS on chats
+alter table public.chats enable row level security;
+
+-- RLS policies for chats
+create policy "Users can view their own chats"
+  on public.chats for select using (auth.uid() = user_id);
+
+create policy "Users can insert their own chats"
+  on public.chats for insert with check (auth.uid() = user_id);
+
+create policy "Users can update their own chats"
+  on public.chats for update using (auth.uid() = user_id);
+
+create policy "Users can delete their own chats"
+  on public.chats for delete using (auth.uid() = user_id);
+
+-- Create chat_messages table
+create table public.chat_messages (
+  id uuid default gen_random_uuid() primary key,
+  chat_id uuid references public.chats(id) on delete cascade not null,
+  role text not null check (role in ('user', 'assistant', 'system')),
+  content jsonb not null,
+  created_at timestamp with time zone default timezone('utc'::text, now()) not null
+);
+
+-- Enable RLS on chat_messages
+alter table public.chat_messages enable row level security;
+
+-- RLS policies for chat_messages
+create policy "Users can view messages in their chats"
+  on public.chat_messages for select
+  using (exists (
+    select 1 from public.chats where chats.id = chat_messages.chat_id and chats.user_id = auth.uid()
+  ));
+
+create policy "Users can insert messages in their chats"
+  on public.chat_messages for insert
+  with check (exists (
+    select 1 from public.chats where chats.id = chat_messages.chat_id and chats.user_id = auth.uid()
+  ));
+
+-- Create indexes for faster queries
+create index idx_chats_user_id_updated_at on public.chats(user_id, updated_at desc);
+create index idx_chat_messages_chat_id_created_at on public.chat_messages(chat_id, created_at);
+
+-- Create word_pairs table for flashcard deck
+create table public.word_pairs (
+  id uuid default gen_random_uuid() primary key,
+  user_id uuid references auth.users(id) on delete cascade not null,
+  source_word text not null,
+  translated_word text not null,
+  context_sentence text,
+  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
+  unique(user_id, source_word, translated_word)
+);
+
+-- Enable RLS on word_pairs
+alter table public.word_pairs enable row level security;
+
+-- RLS policies for word_pairs
+create policy "Users can view their own word pairs"
+  on public.word_pairs for select using (auth.uid() = user_id);
+
+create policy "Users can insert their own word pairs"
+  on public.word_pairs for insert with check (auth.uid() = user_id);
+
+create policy "Users can update their own word pairs"
+  on public.word_pairs for update using (auth.uid() = user_id);
+
+create policy "Users can delete their own word pairs"
+  on public.word_pairs for delete using (auth.uid() = user_id);
+
+-- Create index for faster word pair queries
+create index idx_word_pairs_user_id on public.word_pairs(user_id);
diff --git a/web/Dockerfile b/web/Dockerfile
index 6fac758..4214338 100644
--- a/web/Dockerfile
+++ b/web/Dockerfile
@@ -13,7 +13,8 @@ COPY package.json pnpm-lock.yaml* ./
 FROM base AS development
 
 # Install all dependencies (including devDependencies)
-RUN pnpm install --frozen-lockfile
+# Use --no-frozen-lockfile for development to allow adding new dependencies
+RUN pnpm install --no-frozen-lockfile
 
 # Copy source code
 COPY . .
@@ -27,7 +28,7 @@ CMD ["pnpm", "run", "dev", "--host", "0.0.0.0"]
 FROM base AS builder
 
 # Install all dependencies
-RUN pnpm install --frozen-lockfile
+RUN pnpm install --no-frozen-lockfile
 
 # Copy source code
 COPY . .
diff --git a/web/package.json b/web/package.json
index 19675ad..8e749cc 100644
--- a/web/package.json
+++ b/web/package.json
@@ -19,6 +19,7 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.7",
+    "@radix-ui/react-scroll-area": "^1.2.2",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.7",
     "@radix-ui/react-slot": "^1.2.3",
diff --git a/web/src/App.tsx b/web/src/App.tsx
index 08534fd..5c5ef1a 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -9,6 +9,7 @@ import SignUpPage from './pages/signup'
 import WordsPage from './pages/words'
 import RandomPhrasePage from './pages/random-phrase'
 import SettingsPage from './pages/settings'
+import ChatPage from './pages/chat'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -37,6 +38,7 @@ function App() {
               <Route path="/dashboard" element={<DashboardPage />} />
               <Route path="/words" element={<WordsPage />} />
               <Route path="/random-phrase" element={<RandomPhrasePage />} />
+              <Route path="/chat" element={<ChatPage />} />
               <Route path="/settings" element={<SettingsPage />} />
             </Route>
 
diff --git a/web/src/components/app-sidebar.tsx b/web/src/components/app-sidebar.tsx
index 2a4521d..5ee8bcd 100644
--- a/web/src/components/app-sidebar.tsx
+++ b/web/src/components/app-sidebar.tsx
@@ -4,6 +4,7 @@ import {
   IconDatabase,
   IconInnerShadowTop,
   IconSparkles,
+  IconMessage,
 } from "@tabler/icons-react"
 
 import { NavDocuments } from "@/components/nav-documents"
@@ -44,6 +45,11 @@ const data = {
       url: "/random-phrase",
       icon: IconSparkles,
     },
+    {
+      name: "Chat",
+      url: "/chat",
+      icon: IconMessage,
+    },
   ],
 }
 
diff --git a/web/src/components/chat/chat-input.tsx b/web/src/components/chat/chat-input.tsx
new file mode 100644
index 0000000..0b26d1b
--- /dev/null
+++ b/web/src/components/chat/chat-input.tsx
@@ -0,0 +1,60 @@
+import { useState, useRef, useEffect } from 'react'
+import { IconSend } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { Textarea } from '@/components/ui/textarea'
+
+interface ChatInputProps {
+  onSend: (message: string) => void
+  disabled?: boolean
+}
+
+export function ChatInput({ onSend, disabled = false }: ChatInputProps) {
+  const [message, setMessage] = useState('')
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+  const handleSend = () => {
+    const trimmed = message.trim()
+    if (trimmed && !disabled) {
+      onSend(trimmed)
+      setMessage('')
+    }
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      handleSend()
+    }
+  }
+
+  // Auto-focus on mount
+  useEffect(() => {
+    textareaRef.current?.focus()
+  }, [])
+
+  return (
+    <div className="border-t bg-background p-4">
+      <div className="flex gap-2">
+        <Textarea
+          ref={textareaRef}
+          value={message}
+          onChange={(e) => setMessage(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Ask about translations, vocabulary, grammar..."
+          className="min-h-[60px] resize-none"
+          disabled={disabled}
+        />
+        <Button
+          onClick={handleSend}
+          disabled={!message.trim() || disabled}
+          className="h-[60px] w-[60px] shrink-0"
+        >
+          <IconSend className="h-5 w-5" />
+        </Button>
+      </div>
+      <p className="mt-2 text-xs text-muted-foreground">
+        Press Enter to send, Shift+Enter for new line
+      </p>
+    </div>
+  )
+}
diff --git a/web/src/components/chat/chat-message.tsx b/web/src/components/chat/chat-message.tsx
new file mode 100644
index 0000000..2f8f108
--- /dev/null
+++ b/web/src/components/chat/chat-message.tsx
@@ -0,0 +1,67 @@
+import { IconUser, IconRobot } from '@tabler/icons-react'
+import { WordSuggestionCard } from './word-suggestion-card'
+import type { ChatMessage } from '@/lib/ai-service'
+
+interface ChatMessageProps {
+  message: ChatMessage
+}
+
+export function ChatMessage({ message }: ChatMessageProps) {
+  const isUser = message.role === 'user'
+
+  // For user messages, content is { content: string }
+  // For assistant messages, content is TutorResponseContent
+  const messageContent =
+    message.role === 'user'
+      ? (message.content as { content: string }).content
+      : (message.content as { response_type: string; content: string }).content
+
+  const response_type =
+    message.role === 'assistant'
+      ? (message.content as { response_type: string }).response_type
+      : 'text'
+
+  const response_data =
+    message.role === 'assistant'
+      ? (message.content as { data?: { word?: string; translation?: string; example?: string } }).data
+      : undefined
+
+  return (
+    <div
+      className={`flex gap-3 ${
+        isUser ? 'justify-end' : 'justify-start'
+      }`}
+    >
+      {!isUser && (
+        <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-primary/10">
+          <IconRobot className="h-5 w-5 text-primary" />
+        </div>
+      )}
+
+      <div
+        className={`max-w-[80%] rounded-2xl px-4 py-3 ${
+          isUser
+            ? 'bg-primary text-primary-foreground'
+            : 'bg-muted'
+        }`}
+      >
+        {/* Word suggestion card */}
+        {!isUser && response_type === 'word_suggestion' && response_data ? (
+          <WordSuggestionCard
+            word={response_data.word || ''}
+            translation={response_data.translation || ''}
+            example={response_data.example || ''}
+          />
+        ) : (
+          <p className="text-sm whitespace-pre-wrap">{messageContent}</p>
+        )}
+      </div>
+
+      {isUser && (
+        <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-primary">
+          <IconUser className="h-5 w-5 text-primary-foreground" />
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/src/components/chat/chat-sidebar.tsx b/web/src/components/chat/chat-sidebar.tsx
new file mode 100644
index 0000000..0f06669
--- /dev/null
+++ b/web/src/components/chat/chat-sidebar.tsx
@@ -0,0 +1,87 @@
+import { useEffect } from 'react'
+import { IconMessage, IconTrash, IconPlus } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { ScrollArea } from '@/components/ui/scroll-area'
+import type { Chat } from '@/lib/ai-service'
+
+interface ChatSidebarProps {
+  chats: Chat[]
+  currentChatId: string | null
+  loading: boolean
+  onSelectChat: (chatId: string) => void
+  onNewChat: () => void
+  onDeleteChat: (chatId: string) => void
+}
+
+export function ChatSidebar({
+  chats,
+  currentChatId,
+  loading,
+  onSelectChat,
+  onNewChat,
+  onDeleteChat,
+}: ChatSidebarProps) {
+  return (
+    <div className="flex h-full w-60 flex-col border-r bg-muted/10">
+      {/* Header */}
+      <div className="flex items-center justify-between border-b p-4">
+        <h2 className="text-sm font-semibold">Chats</h2>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="h-8 w-8"
+          onClick={onNewChat}
+          title="New chat"
+        >
+          <IconPlus className="h-4 w-4" />
+        </Button>
+      </div>
+
+      {/* Chat list */}
+      <ScrollArea className="flex-1">
+        <div className="space-y-1 p-2">
+          {loading ? (
+            <div className="flex items-center justify-center py-8">
+              <p className="text-xs text-muted-foreground">Loading chats...</p>
+            </div>
+          ) : chats.length === 0 ? (
+            <div className="flex flex-col items-center justify-center py-8">
+              <IconMessage className="mb-2 h-8 w-8 text-muted-foreground" />
+              <p className="text-xs text-muted-foreground">No chats yet</p>
+            </div>
+          ) : (
+            chats.map((chat) => (
+              <div
+                key={chat.id}
+                className={`group relative flex items-center gap-2 rounded-lg px-3 py-2 text-sm transition-colors ${
+                  currentChatId === chat.id
+                    ? 'bg-accent text-accent-foreground'
+                    : 'hover:bg-muted/50'
+                }`}
+              >
+                <button
+                  onClick={() => onSelectChat(chat.id)}
+                  className="flex-1 truncate text-left"
+                >
+                  {chat.title || 'New Chat'}
+                </button>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
+                  onClick={(e) => {
+                    e.stopPropagation()
+                    onDeleteChat(chat.id)
+                  }}
+                  title="Delete chat"
+                >
+                  <IconTrash className="h-3 w-3" />
+                </Button>
+              </div>
+            ))
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  )
+}
diff --git a/web/src/components/chat/word-suggestion-card.tsx b/web/src/components/chat/word-suggestion-card.tsx
new file mode 100644
index 0000000..76d22fa
--- /dev/null
+++ b/web/src/components/chat/word-suggestion-card.tsx
@@ -0,0 +1,81 @@
+import { useState } from 'react'
+import { IconBook, IconCheck, IconPlus } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { sendChatMessage } from '@/lib/ai-service'
+
+interface WordSuggestionCardProps {
+  word: string
+  translation: string
+  example: string
+}
+
+export function WordSuggestionCard({
+  word,
+  translation,
+  example,
+}: WordSuggestionCardProps) {
+  const [saved, setSaved] = useState(false)
+  const [saving, setSaving] = useState(false)
+
+  const handleSave = async () => {
+    if (saved || saving) return
+
+    setSaving(true)
+    try {
+      // Send a message to trigger the save_word_pair tool
+      await sendChatMessage(
+        null,
+        `Save "${word}" → "${translation}" to my list. Example: ${example}`
+      )
+      setSaved(true)
+    } catch (error) {
+      console.error('Failed to save word pair:', error)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="space-y-3">
+      {/* Word and translation */}
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-2">
+          <IconBook className="h-5 w-5 text-primary" />
+          <div>
+            <span className="font-semibold">{word}</span>
+            <span className="mx-2 text-muted-foreground">→</span>
+            <span className="text-muted-foreground">{translation}</span>
+          </div>
+        </div>
+        <Button
+          variant={saved ? 'default' : 'outline'}
+          size="sm"
+          onClick={handleSave}
+          disabled={saved || saving}
+          className="shrink-0"
+        >
+          {saved ? (
+            <>
+              <IconCheck className="mr-1 h-4 w-4" />
+              Saved
+            </>
+          ) : (
+            <>
+              <IconPlus className="mr-1 h-4 w-4" />
+              Add to list
+            </>
+          )}
+        </Button>
+      </div>
+
+      {/* Example sentence */}
+      {example && (
+        <div className="rounded-md bg-muted/50 px-3 py-2">
+          <p className="text-xs italic text-muted-foreground">
+            "{example}"
+          </p>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/src/components/ui/scroll-area.tsx b/web/src/components/ui/scroll-area.tsx
new file mode 100644
index 0000000..cf253cf
--- /dev/null
+++ b/web/src/components/ui/scroll-area.tsx
@@ -0,0 +1,46 @@
+import * as React from "react"
+import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"
+
+import { cn } from "@/lib/utils"
+
+const ScrollArea = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
+>(({ className, children, ...props }, ref) => (
+  <ScrollAreaPrimitive.Root
+    ref={ref}
+    className={cn("relative overflow-hidden", className)}
+    {...props}
+  >
+    <ScrollAreaPrimitive.Viewport className="h-full w-full rounded-[inherit]">
+      {children}
+    </ScrollAreaPrimitive.Viewport>
+    <ScrollBar />
+    <ScrollAreaPrimitive.Corner />
+  </ScrollAreaPrimitive.Root>
+))
+ScrollArea.displayName = ScrollAreaPrimitive.Root.displayName
+
+const ScrollBar = React.forwardRef<
+  React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>
+>(({ className, orientation = "vertical", ...props }, ref) => (
+  <ScrollAreaPrimitive.ScrollAreaScrollbar
+    ref={ref}
+    orientation={orientation}
+    className={cn(
+      "flex touch-none select-none transition-colors",
+      orientation === "vertical" &&
+        "h-full w-2.5 border-l border-l-transparent p-[1px]",
+      orientation === "horizontal" &&
+        "h-2.5 flex-col border-t border-t-transparent p-[1px]",
+      className
+    )}
+    {...props}
+  >
+    <ScrollAreaPrimitive.ScrollAreaThumb className="relative flex-1 rounded-full bg-border" />
+  </ScrollAreaPrimitive.ScrollAreaScrollbar>
+))
+ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName
+
+export { ScrollArea, ScrollBar }
diff --git a/web/src/components/ui/textarea.tsx b/web/src/components/ui/textarea.tsx
new file mode 100644
index 0000000..9f9a6dc
--- /dev/null
+++ b/web/src/components/ui/textarea.tsx
@@ -0,0 +1,24 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+export interface TextareaProps
+  extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {}
+
+const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, ...props }, ref) => {
+    return (
+      <textarea
+        className={cn(
+          "flex min-h-[80px] w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    )
+  }
+)
+Textarea.displayName = "Textarea"
+
+export { Textarea }
diff --git a/web/src/hooks/use-chat.ts b/web/src/hooks/use-chat.ts
new file mode 100644
index 0000000..b3757d2
--- /dev/null
+++ b/web/src/hooks/use-chat.ts
@@ -0,0 +1,154 @@
+import { useState, useCallback, useEffect } from 'react'
+import {
+  getChats,
+  createChat,
+  deleteChat,
+  sendChatMessage,
+  getChatMessages,
+  type Chat,
+  type ChatMessage,
+} from '@/lib/ai-service'
+
+export function useChat() {
+  const [chats, setChats] = useState<Chat[]>([])
+  const [currentChat, setCurrentChat] = useState<Chat | null>(null)
+  const [messages, setMessages] = useState<ChatMessage[]>([])
+  const [loading, setLoading] = useState(false)
+  const [sending, setSending] = useState(false)
+
+  // Load all chats on mount
+  useEffect(() => {
+    loadChats()
+  }, [])
+
+  const loadChats = useCallback(async () => {
+    try {
+      setLoading(true)
+      const data = await getChats()
+      setChats(data)
+    } catch (error) {
+      console.error('Failed to load chats:', error)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  const loadMessages = useCallback(async (chatId: string) => {
+    try {
+      setLoading(true)
+      const data = await getChatMessages(chatId)
+      setMessages(data)
+
+      // Update current chat
+      const chat = chats.find((c) => c.id === chatId)
+      if (chat) {
+        setCurrentChat(chat)
+      }
+    } catch (error) {
+      console.error('Failed to load messages:', error)
+    } finally {
+      setLoading(false)
+    }
+  }, [chats])
+
+  const createNewChat = useCallback(async () => {
+    try {
+      const newChat = await createChat()
+      setChats((prev) => [newChat, ...prev])
+      setCurrentChat(newChat)
+      setMessages([])
+      return newChat
+    } catch (error) {
+      console.error('Failed to create chat:', error)
+      throw error
+    }
+  }, [])
+
+  const selectChat = useCallback(async (chatId: string) => {
+    const chat = chats.find((c) => c.id === chatId)
+    if (chat) {
+      setCurrentChat(chat)
+      await loadMessages(chatId)
+    }
+  }, [chats, loadMessages])
+
+  const handleDeleteChat = useCallback(async (chatId: string) => {
+    try {
+      await deleteChat(chatId)
+      setChats((prev) => prev.filter((c) => c.id !== chatId))
+
+      // Clear current chat if it was deleted
+      if (currentChat?.id === chatId) {
+        setCurrentChat(null)
+        setMessages([])
+      }
+    } catch (error) {
+      console.error('Failed to delete chat:', error)
+    }
+  }, [currentChat])
+
+  const sendMessage = useCallback(async (message: string) => {
+    if (sending) return
+
+    try {
+      setSending(true)
+
+      // Add user message optimistically
+      const userMessage: ChatMessage = {
+        id: `temp-${Date.now()}`,
+        chat_id: currentChat?.id || '',
+        role: 'user',
+        content: { content: message },
+        created_at: new Date().toISOString(),
+      }
+      setMessages((prev) => [...prev, userMessage])
+
+      // Send message and get AI response
+      const response = await sendChatMessage(currentChat?.id || null, message)
+
+      // Update messages with the AI response
+      setMessages((prev) => [...prev, response])
+
+      // Update current chat if it was a new chat
+      if (!currentChat) {
+        const newChats = await getChats()
+        setChats(newChats)
+        // Set the current chat from response
+        const updatedChat = newChats.find((c) => c.id === response.chat_id)
+        if (updatedChat) {
+          setCurrentChat(updatedChat)
+        }
+      } else {
+        // Update the chat's updated_at timestamp
+        setChats((prev) =>
+          prev.map((c) =>
+            c.id === currentChat.id
+              ? { ...c, updated_at: new Date().toISOString() }
+              : c
+          )
+        )
+      }
+
+      return response
+    } catch (error) {
+      console.error('Failed to send message:', error)
+      throw error
+    } finally {
+      setSending(false)
+    }
+  }, [currentChat, sending])
+
+  return {
+    chats,
+    currentChat,
+    messages,
+    loading,
+    sending,
+    loadChats,
+    loadMessages,
+    createNewChat,
+    selectChat,
+    deleteChat: handleDeleteChat,
+    sendMessage,
+  }
+}
diff --git a/web/src/lib/ai-service.ts b/web/src/lib/ai-service.ts
index e341cf8..1bf8569 100644
--- a/web/src/lib/ai-service.ts
+++ b/web/src/lib/ai-service.ts
@@ -19,6 +19,41 @@ export interface PronunciationTipsResponse {
   cached?: boolean
 }
 
+// Chat types
+export type ResponseType = 'text' | 'word_suggestion' | 'save_confirmation' | 'error'
+
+export interface ToolCall {
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export interface TutorResponseContent {
+  response_type: ResponseType
+  content: string
+  data?: {
+    word?: string
+    translation?: string
+    example?: string
+  }
+  tool_calls?: ToolCall[]
+}
+
+export interface ChatMessage {
+  id: string
+  chat_id: string
+  role: 'user' | 'assistant' | 'system'
+  content: TutorResponseContent | { content: string }
+  created_at: string
+}
+
+export interface Chat {
+  id: string
+  user_id: string
+  title?: string
+  created_at: string
+  updated_at: string
+}
+
 /**
  * Generate a random phrase using the AI service
  * @param words - Array of words to use in the phrase
@@ -77,3 +112,149 @@ export async function getPronunciationTips(word: string): Promise<PronunciationT
 
   return response.json()
 }
+
+/**
+ * Send a message to the chat tutor
+ * @param chatId - The ID of the chat (or null for new chat)
+ * @param message - The message to send
+ * @returns Promise with the assistant's response message
+ */
+export async function sendChatMessage(
+  chatId: string | null,
+  message: string
+): Promise<ChatMessage> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to chat')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chat/message`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+    body: JSON.stringify({
+      chat_id: chatId,
+      message,
+    }),
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to send message: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Get all chats for the current user
+ * @returns Promise with list of chats
+ */
+export async function getChats(): Promise<Chat[]> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to get chats')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chats`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to get chats: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Create a new chat
+ * @param title - Optional title for the chat
+ * @returns Promise with the created chat
+ */
+export async function createChat(title?: string): Promise<Chat> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to create chat')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chats`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+    body: JSON.stringify({ title }),
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to create chat: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Delete a chat
+ * @param chatId - The ID of the chat to delete
+ * @returns Promise that resolves when the chat is deleted
+ */
+export async function deleteChat(chatId: string): Promise<void> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to delete chat')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chats/${chatId}`, {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to delete chat: ${response.statusText}`)
+  }
+}
+
+/**
+ * Get messages for a chat
+ * @param chatId - The ID of the chat
+ * @returns Promise with list of messages
+ */
+export async function getChatMessages(chatId: string): Promise<ChatMessage[]> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to get chat messages')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chats/${chatId}/messages`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to get chat messages: ${response.statusText}`)
+  }
+
+  return response.json()
+}
diff --git a/web/src/pages/chat.tsx b/web/src/pages/chat.tsx
new file mode 100644
index 0000000..94e8e23
--- /dev/null
+++ b/web/src/pages/chat.tsx
@@ -0,0 +1,122 @@
+import { useEffect, useRef } from 'react'
+import { useChat } from '@/hooks/use-chat'
+import { ChatSidebar } from '@/components/chat/chat-sidebar'
+import { ChatMessage } from '@/components/chat/chat-message'
+import { ChatInput } from '@/components/chat/chat-input'
+import { ScrollArea } from '@/components/ui/scroll-area'
+import { Card } from '@/components/ui/card'
+
+export default function ChatPage() {
+  const {
+    chats,
+    currentChat,
+    messages,
+    loading,
+    sending,
+    createNewChat,
+    selectChat,
+    deleteChat,
+    sendMessage,
+  } = useChat()
+
+  const messagesEndRef = useRef<HTMLDivElement>(null)
+
+  // Scroll to bottom when messages change
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
+  }, [messages])
+
+  const handleNewChat = async () => {
+    await createNewChat()
+  }
+
+  const handleSendMessage = async (message: string) => {
+    await sendMessage(message)
+  }
+
+  return (
+    <div className="flex h-full">
+      {/* Sidebar */}
+      <ChatSidebar
+        chats={chats}
+        currentChatId={currentChat?.id || null}
+        loading={loading}
+        onSelectChat={selectChat}
+        onNewChat={handleNewChat}
+        onDeleteChat={deleteChat}
+      />
+
+      {/* Main chat area */}
+      <div className="flex flex-1 flex-col">
+        {currentChat ? (
+          <>
+            {/* Chat header */}
+            <div className="border-b bg-muted/10 px-6 py-4">
+              <h1 className="text-xl font-semibold">{currentChat.title || 'Chat'}</h1>
+              <p className="text-sm text-muted-foreground">
+                Ask about translations, vocabulary, grammar, and more
+              </p>
+            </div>
+
+            {/* Messages */}
+            <ScrollArea className="flex-1 px-6 py-4">
+              <div className="space-y-4">
+                {messages.length === 0 ? (
+                  <div className="flex h-full flex-col items-center justify-center text-center">
+                    <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-primary/10">
+                      <span className="text-3xl">💬</span>
+                    </div>
+                    <h3 className="mb-2 text-lg font-semibold">Start a conversation</h3>
+                    <p className="max-w-md text-sm text-muted-foreground">
+                      Ask me anything about language learning! I can help with translations,
+                      vocabulary suggestions, grammar explanations, and more.
+                    </p>
+                  </div>
+                ) : (
+                  <>
+                    {messages.map((message) => (
+                      <ChatMessage key={message.id} message={message} />
+                    ))}
+                    {sending && (
+                      <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                        <div className="flex gap-1">
+                          <span className="h-2 w-2 animate-bounce rounded-full bg-primary [animation-delay:-0.3s]" />
+                          <span className="h-2 w-2 animate-bounce rounded-full bg-primary [animation-delay:-0.15s]" />
+                          <span className="h-2 w-2 animate-bounce rounded-full bg-primary" />
+                        </div>
+                        <span>Thinking...</span>
+                      </div>
+                    )}
+                    <div ref={messagesEndRef} />
+                  </>
+                )}
+              </div>
+            </ScrollArea>
+
+            {/* Input */}
+            <ChatInput onSend={handleSendMessage} disabled={sending} />
+          </>
+        ) : (
+          // Empty state - no chat selected
+          <div className="flex flex-1 items-center justify-center p-8">
+            <Card className="max-w-md p-8 text-center">
+              <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-primary/10">
+                <span className="text-3xl">🎯</span>
+              </div>
+              <h3 className="mb-2 text-lg font-semibold">Welcome to Smart Tutor</h3>
+              <p className="mb-6 text-sm text-muted-foreground">
+                Your AI-powered language tutor is ready to help! Create a new chat to get started.
+              </p>
+              <button
+                onClick={handleNewChat}
+                className="inline-flex items-center justify-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90"
+              >
+                Start New Chat
+              </button>
+            </Card>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

From 3337de4155097913a880ff3ba35d8d7f9ebd8d81 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 09:08:47 +0100
Subject: [PATCH 02/10] Update documentation with comprehensive codebase
 analysis

Enhanced CLAUDE.md and AGENTS.md with:
- Complete project structure and architecture overview
- All API endpoints documented with examples
- CrewAI agent patterns and configuration
- Database schema and security notes
- Frontend components, hooks, and dependencies
- Debugging guide with common issues and solutions
- Performance considerations and caching strategies
- Environment configuration for all services
- Agent-specific instructions for adding new crews

This provides comprehensive reference documentation for
future development and onboarding.
---
 AGENTS.md                                     | 152 ++++++-
 CLAUDE.md                                     | 382 ++++++++++++++++--
 .../config/agents.yaml                        |   1 -
 3 files changed, 490 insertions(+), 45 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7d55e7e..630ccc0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,15 +2,46 @@
 
 ## Project Overview
 
-Wordpan is a full-stack AI-powered web application template demonstrating modern AI agent integration with CrewAI, Supabase, and comprehensive observability using Arize Phoenix.
+Wordpan is a full-stack AI-powered language learning application demonstrating modern AI agent integration with CrewAI, Supabase, and comprehensive observability using Arize Phoenix.
 
 ### Architecture
-- **Frontend**: React 19.1 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4
+- **Frontend**: React 19.1 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4 + Radix UI
 - **AI Backend**: Python 3.13 + Flask + CrewAI 0.201 + LiteLLM
 - **Database**: PostgreSQL via Supabase with Row-Level Security (RLS)
 - **Observability**: Arize Phoenix 12.4.0 with OpenTelemetry tracing
 - **Containerization**: Docker Compose with hot reload
 
+### Key Features
+1. **Random Phrase Generator**: Bilingual phrase generation using AI
+2. **Pronunciation Tips**: AI-powered pronunciation guidance with caching
+3. **Smart Tutor Chat**: Multi-agent conversational AI for language learning
+4. **Language Selection**: Target language preferences (Polish, Belarusian, Italian)
+5. **Flashcard System**: Save vocabulary pairs for later review
+
+### Project Structure
+```
+wordpan/
+├── ai/                    # Python AI backend
+│   ├── src/
+│   │   ├── crews/         # CrewAI agent definitions
+│   │   │   ├── base/      # Shared LLM configuration
+│   │   │   ├── random_phrase_crew/
+│   │   │   ├── pronunciation_tips_crew/
+│   │   │   └── chat_tutor_crew/
+│   │   └── lib/           # Shared utilities (tracer)
+│   ├── run.py             # Flask API server
+│   └── pyproject.toml      # Python dependencies
+├── web/                   # React frontend
+│   ├── src/
+│   │   ├── pages/         # Page components
+│   │   ├── components/    # UI components
+│   │   ├── hooks/         # Custom React hooks
+│   │   └── lib/           # Utilities and services
+│   └── package.json
+└── supabase/              # Database configuration
+    └── migrations/        # SQL migration files
+```
+
 ## Database Operations
 
 **CRITICAL: Never run database migration commands in this project.**
@@ -47,16 +78,15 @@ Only create migration files. Let the developer apply them manually.
    mkdir -p ai/src/crews/my_new_crew/config
    ```
 
-2. Define agents in `agents.yaml`:
+2. Define agents in `config/agents.yaml`:
    ```yaml
    my_agent:
      role: "Agent Role"
      goal: "What the agent should achieve"
      backstory: "Agent's background and expertise"
-     model: "groq/llama-3.3-70b-versatile"
    ```
 
-3. Define tasks in `tasks.yaml`:
+3. Define tasks in `config/tasks.yaml`:
    ```yaml
    my_task:
      description: "Task description with {variable}"
@@ -64,32 +94,118 @@ Only create migration files. Let the developer apply them manually.
      agent: my_agent
    ```
 
-4. Create crew class in `crew.py`:
+4. Create schemas in `schemas.py`:
+   ```python
+   from pydantic import BaseModel, Field
+
+   class MyOutput(BaseModel):
+       field_name: str = Field(description="Field description")
+   ```
+
+5. Create crew class in `crew.py` using `@CrewBase` decorator:
    ```python
    from crewai import Agent, Crew, Task, Process
+   from crewai.project import CrewBase, agent, crew, task
+   from src.crews.base.llm import DEFAULT_LLM
+
+   @CrewBase
+   class MyNewCrew():
+       agents: list[Agent]
+       tasks: list[Task]
+
+       @agent
+       def my_agent(self) -> Agent:
+           return Agent(
+               config=self.agents_config['my_agent'],
+               llm=DEFAULT_LLM
+           )
 
-   class MyNewCrew:
-       def __init__(self):
-           # Load configs, initialize agents and tasks
-           pass
+       @task
+       def my_task(self) -> Task:
+           return Task(
+               config=self.tasks_config['my_task'],
+               output_pydantic=MyOutput
+           )
 
-       def run(self, inputs: dict):
-           crew = Crew(
-               agents=[self.agent],
-               tasks=[self.task],
+       @crew
+       def crew(self) -> Crew:
+           return Crew(
+               agents=self.agents,
+               tasks=self.tasks,
                process=Process.sequential
            )
-           return crew.kickoff(inputs=inputs)
    ```
 
-5. Add endpoint in `ai/run.py`:
+6. Add endpoint in `ai/run.py`:
    ```python
+   from src.crews.my_new_crew.crew import MyNewCrew
+   from src.crews.my_new_crew.schemas import MyOutput
+
    @app.route('/api/my-endpoint', methods=['POST'])
+   @require_auth
    async def my_endpoint():
-       # Initialize crew, run, return result
-       pass
+       # Get user context
+       user_id = request.user.id
+       user_context, target_language = await get_user_context(user_id)
+
+       # Run crew
+       inputs = {'user_context': user_context, 'target_language': target_language}
+       result = await MyNewCrew().crew().kickoff_async(inputs=inputs)
+
+       if hasattr(result, 'pydantic'):
+           return jsonify(result.pydantic.model_dump()), 200
+
+       return jsonify({"error": "Unexpected result format"}), 500
    ```
 
+### Agent Configuration
+
+**LLM Provider** (`ai/src/crews/base/llm.py`):
+- Default: Groq Llama 3.3 70B Versatile
+- Configurable via environment variables
+- LiteLLM abstraction allows easy provider switching
+
+**Agent Patterns**:
+- Use descriptive roles and goals
+- Provide detailed backstory for context
+- Include expected output format in task descriptions
+- Use Pydantic models for structured outputs
+
+**Tool Calling**:
+- Define tools as Python functions
+- Use CrewAI's @tool decorator
+- Pass tools to agents via `tools` parameter
+- Tool results are automatically integrated into agent context
+
+### Existing Crews
+
+**RandomPhraseCrew** (`ai/src/crews/random_phrase_crew/`)
+- Single agent: `phrase_creator`
+- Creates bilingual phrases from random word lists
+- Supports Polish, Belarusian, and Italian translations
+- Output: `PhraseOutput` (phrase, phrase_target_lang, target_language, words_used)
+
+**PronunciationTipsCrew** (`ai/src/crews/pronunciation_tips_crew/`)
+- Single agent: `pronunciation_guide`
+- Provides IPA transcriptions, syllable breakdowns, memory aids
+- Uses session-based caching via Supabase
+- Output: `PronunciationTipsOutput` (word, phonetic_transcription, syllables, pronunciation_tips, memory_aids, common_mistakes)
+
+**ChatTutorCrew** (`ai/src/crews/chat_tutor_crew/`)
+- Three agents: `router_agent`, `translation_agent`, `vocabulary_agent`
+- Routes requests to appropriate specialists
+- Supports tool calling for saving vocabulary pairs
+- Enforces domain boundaries (language learning only)
+- Output: `TutorResponse` (response_type, content, data, tool_calls)
+
+### Tracing
+
+All crew operations are automatically traced via OpenTelemetry:
+- View traces in Phoenix UI: http://localhost:6006
+- See agent reasoning chains
+- Monitor LLM calls and latency
+- Track token usage
+
 ### Environment Configuration
 
 **Frontend** (`web/.env.local`):
diff --git a/CLAUDE.md b/CLAUDE.md
index f911f7e..c798c1d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,15 +2,56 @@
 
 ## Project Overview
 
-Wordpan is a full-stack AI-powered web application template demonstrating modern AI agent integration with CrewAI, Supabase, and comprehensive observability using Arize Phoenix.
+Wordpan is a full-stack AI-powered language learning application demonstrating modern AI agent integration with CrewAI, Supabase, and comprehensive observability using Arize Phoenix.
 
 ### Architecture
-- **Frontend**: React 19.1 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4
+- **Frontend**: React 19.1 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4 + Radix UI
 - **AI Backend**: Python 3.13 + Flask + CrewAI 0.201 + LiteLLM
 - **Database**: PostgreSQL via Supabase with Row-Level Security (RLS)
 - **Observability**: Arize Phoenix 12.4.0 with OpenTelemetry tracing
 - **Containerization**: Docker Compose with hot reload
 
+### Key Features
+1. **Random Phrase Generator**: Bilingual phrase generation using AI
+2. **Pronunciation Tips**: AI-powered pronunciation guidance with caching
+3. **Smart Tutor Chat**: Multi-agent conversational AI for language learning
+4. **Language Selection**: Target language preferences (Polish, Belarusian, Italian)
+5. **Flashcard System**: Save vocabulary pairs for later review
+
+### Project Structure
+```
+wordpan/
+├── README.md
+├── CLAUDE.md              # This file
+├── AGENTS.md              # Agent-specific instructions
+├── docker-compose.yml     # Service orchestration
+├── .vscode/               # VS Code settings
+├── ai/                    # Python AI backend
+│   ├── src/
+│   │   ├── crews/         # CrewAI agent definitions
+│   │   │   ├── base/      # Shared LLM configuration
+│   │   │   ├── random_phrase_crew/
+│   │   │   ├── pronunciation_tips_crew/
+│   │   │   └── chat_tutor_crew/
+│   │   └── lib/           # Shared utilities (tracer)
+│   ├── run.py             # Flask API server
+│   ├── Dockerfile
+│   └── pyproject.toml      # Python dependencies
+├── web/                   # React frontend
+│   ├── src/
+│   │   ├── pages/         # Page components
+│   │   ├── components/    # UI components
+│   │   ├── hooks/         # Custom React hooks
+│   │   ├── lib/           # Utilities and services
+│   │   ├── contexts/      # React contexts
+│   │   └── layouts/       # Layout components
+│   ├── Dockerfile
+│   └── package.json
+├── supabase/              # Database configuration
+│   └── migrations/        # SQL migration files
+└── phoenix/              # Observability configuration
+```
+
 ## Database Operations
 
 **CRITICAL: Never run database migration commands in this project.**
@@ -40,6 +81,64 @@ Only create migration files. Let the developer apply them manually.
 - Backend validates JWT before processing requests
 - RLS policies enforce data access control
 
+### API Endpoints
+
+**Phrase Generation**
+- `POST /api/random-phrase` - Generate random phrase from words
+  - Body: `{ "words": ["word1", "word2", ...] }`
+  - Returns: `{ "phrase", "phrase_target_lang", "target_language", "words_used" }`
+
+**Pronunciation Tips**
+- `POST /api/pronunciation-tips` - Get pronunciation guidance
+  - Body: `{ "word": "example" }`
+  - Returns: `{ "word", "phonetic_transcription", "syllables", "pronunciation_tips", "memory_aids", "common_mistakes" }`
+
+**Chat System**
+- `POST /api/chat/message` - Send message and get AI response
+  - Body: `{ "chat_id": "uuid" | null, "message": "text" }`
+  - Returns: ChatMessage with structured content
+- `GET /api/chats` - List all user chats
+- `POST /api/chats` - Create new chat
+- `DELETE /api/chats/:id` - Delete chat
+- `GET /api/chats/:id/messages` - Get chat history
+
+**User Profile**
+- `PUT /api/profile/target-language` - Update language preference
+  - Body: `{ "target_language": "polish" | "belarusian" | "italian" }`
+
+### CrewAI Agents
+
+**RandomPhraseCrew** (`ai/src/crews/random_phrase_crew/`)
+- `phrase_creator` - Creates bilingual phrases from random words
+- Output: `PhraseOutput` with phrase, translation, and words used
+
+**PronunciationTipsCrew** (`ai/src/crews/pronunciation_tips_crew/`)
+- `pronunciation_guide` - Provides pronunciation guidance
+- Output: `PronunciationTipsOutput` with IPA, syllables, tips, and memory aids
+- Uses session caching via Supabase for performance
+
+**ChatTutorCrew** (`ai/src/crews/chat_tutor_crew/`)
+- `router_agent` - Routes requests to appropriate specialists
+- `translation_agent` - Handles translation requests
+- `vocabulary_agent` - Suggests new vocabulary
+- Tools: `save_word_pair` - Saves vocabulary to flashcard deck
+- Output: `TutorResponse` with response_type, content, and optional tool_calls
+
+### Database Schema
+
+**Tables**
+- `words` - Random word pool for phrase generation
+- `profiles` - User profiles with context and target_language
+- `pronunciation_tips_cache` - Cached pronunciation data per user
+- `chats` - Chat session metadata (title, created_at, updated_at)
+- `chat_messages` - Individual messages with JSONB content
+- `word_pairs` - Saved vocabulary pairs with example sentences
+
+**Row-Level Security (RLS)**
+- All tables have RLS enabled
+- Users can only access their own data
+- Service role client used for profile operations to bypass RLS when needed
+
 ### Adding New CrewAI Crews
 
 1. Create crew directory structure:
@@ -53,7 +152,6 @@ Only create migration files. Let the developer apply them manually.
      role: "Agent Role"
      goal: "What the agent should achieve"
      backstory: "Agent's background and expertise"
-     model: "groq/llama-3.3-70b-versatile"
    ```
 
 3. Define tasks in `tasks.yaml`:
@@ -64,49 +162,174 @@ Only create migration files. Let the developer apply them manually.
      agent: my_agent
    ```
 
-4. Create crew class in `crew.py`:
+4. Create schemas in `schemas.py`:
+   ```python
+   from pydantic import BaseModel, Field
+
+   class MyOutput(BaseModel):
+       field_name: str = Field(description="Field description")
+   ```
+
+5. Create crew class in `crew.py`:
    ```python
    from crewai import Agent, Crew, Task, Process
+   from crewai.project import CrewBase, agent, crew, task
+   from src.crews.base.llm import DEFAULT_LLM
+
+   @CrewBase
+   class MyNewCrew():
+       agents: list[Agent]
+       tasks: list[Task]
+
+       @agent
+       def my_agent(self) -> Agent:
+           return Agent(
+               config=self.agents_config['my_agent'],
+               llm=DEFAULT_LLM
+           )
 
-   class MyNewCrew:
-       def __init__(self):
-           # Load configs, initialize agents and tasks
-           pass
+       @task
+       def my_task(self) -> Task:
+           return Task(
+               config=self.tasks_config['my_task'],
+               output_pydantic=MyOutput
+           )
 
-       def run(self, inputs: dict):
-           crew = Crew(
-               agents=[self.agent],
-               tasks=[self.task],
+       @crew
+       def crew(self) -> Crew:
+           return Crew(
+               agents=self.agents,
+               tasks=self.tasks,
                process=Process.sequential
            )
-           return crew.kickoff(inputs=inputs)
    ```
 
-5. Add endpoint in `ai/run.py`:
+6. Add endpoint in `ai/run.py`:
    ```python
+   from src.crews.my_new_crew.crew import MyNewCrew
+   from src.crews.my_new_crew.schemas import MyOutput
+
    @app.route('/api/my-endpoint', methods=['POST'])
+   @require_auth
    async def my_endpoint():
-       # Initialize crew, run, return result
-       pass
+       # Get user context
+       user_id = request.user.id
+       user_context, target_language = await get_user_context(user_id)
+
+       # Run crew
+       inputs = {'user_context': user_context, 'target_language': target_language}
+       result = await MyNewCrew().crew().kickoff_async(inputs=inputs)
+
+       if hasattr(result, 'pydantic'):
+           return jsonify(result.pydantic.model_dump()), 200
+
+       return jsonify({"error": "Unexpected result format"}), 500
    ```
 
 ### Environment Configuration
 
 **Frontend** (`web/.env.local`):
-- `VITE_SUPABASE_URL` - Supabase project URL
-- `VITE_SUPABASE_ANON_KEY` - Supabase anonymous key
-- `VITE_AI_SERVICE_URL` - AI backend base URL
+```bash
+VITE_SUPABASE_URL=http://127.0.0.1:54321
+VITE_SUPABASE_ANON_KEY=<your-anon-key>
+VITE_AI_SERVICE_URL=http://localhost:8000
+```
 
 **Backend** (`ai/.env`):
-- `GROQ_API_KEY` (or `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) - LLM provider key
-- `PHOENIX_PROJECT_NAME` - Project name in Phoenix
-- `PHOENIX_COLLECTOR_ENDPOINT` - Phoenix OTLP endpoint
-- `SUPABASE_URL` - Supabase URL (use `http://host.docker.internal:54321` in Docker)
-- `SUPABASE_ANON_KEY` - Supabase anonymous key
+```bash
+GROQ_API_KEY=<your-groq-key>
+PHOENIX_PROJECT_NAME=GOMANAI_WORKSHOP
+PHOENIX_COLLECTOR_ENDPOINT=http://phoenix:4317/v1/traces
+SUPABASE_URL=http://host.docker.internal:54321
+SUPABASE_ANON_KEY=<your-anon-key>
+SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
+PORT=8000
+```
 
 **Phoenix** (`phoenix/.env`):
-- `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_DB`, `POSTGRES_PASSWORD`
-- `PHOENIX_SQL_DATABASE_URL` - Phoenix database connection string
+```bash
+POSTGRES_HOST=phoenix-db
+POSTGRES_USER=postgres
+POSTGRES_DB=postgres
+POSTGRES_PASSWORD=postgres
+PHOENIX_SQL_DATABASE_URL=postgresql+psycopg://postgres:postgres@phoenix-db/postgres
+```
+
+### Key Dependencies
+
+**Frontend** (package.json):
+```json
+{
+  "react": "^19.1.1",
+  "typescript": "~5.9.3",
+  "vite": "^7.1.7",
+  "@supabase/supabase-js": "^2.75.0",
+  "@tanstack/react-query": "^5.90.21",
+  "react-router-dom": "^7.6.0",
+  "tailwindcss": "^4.1.14",
+  "@radix-ui/react-*": "UI component library"
+}
+```
+
+**Backend** (pyproject.toml):
+```toml
+dependencies = [
+    "flask[async]>=3.1.0",
+    "crewai==0.201.0",
+    "litellm",
+    "arize-phoenix==12.4.0",
+    "supabase>=2.22.0",
+    "openinference-instrumentation-crewai",
+    "openinference-instrumentation-litellm"
+]
+```
+
+### Frontend Components
+
+**Pages** (`web/src/pages/`)
+- `dashboard.tsx` - Main dashboard with quick actions
+- `login.tsx` - User login
+- `signup.tsx` - User registration
+- `words.tsx` - Word list with pagination
+- `random-phrase.tsx` - Random phrase generator
+- `chat.tsx` - AI chat tutor interface
+- `settings.tsx` - User settings
+
+**UI Components** (`web/src/components/`)
+- `ui/` - Radix UI components (button, card, input, etc.)
+- `chat/` - Chat-specific components
+- `app-sidebar.tsx` - Main navigation sidebar
+- `nav-main.tsx` - Navigation items
+- `PronunciationTipsModal.tsx` - Pronunciation tips display
+
+**Hooks** (`web/src/hooks/`)
+- `use-words.ts` - Word list pagination
+- `use-random-phrase.ts` - Random phrase generation
+- `use-chat.ts` - Chat state management
+- `use-mobile-detection.ts` - Mobile device detection
+
+### Observability
+
+**Phoenix Integration**
+- All AI operations traced via OpenTelemetry
+- Automatic instrumentation for CrewAI and LiteLLM
+- Session-based span correlation
+- Performance metrics dashboard at http://localhost:6006
+
+**Traced Operations**
+- Random phrase generation
+- Pronunciation tips generation
+- Chat message processing
+- Tool invocations (save_word_pair)
+
+**Viewing Traces**
+1. Open Phoenix UI: http://localhost:6006
+2. Select a trace to view:
+   - Input parameters
+   - Agent reasoning
+   - LLM calls with latency
+   - Token usage
+   - Output results
 
 ## Common Tasks
 
@@ -140,6 +363,71 @@ open http://127.0.0.1:54323
 - **AI Observability**: Phoenix UI at http://localhost:6006
 - **Database**: Supabase Studio at http://127.0.0.1:54323
 
+### Running Services
+
+**All Services (Recommended)**
+```bash
+docker compose up --build
+```
+
+**Individual Services**
+```bash
+# Frontend only
+cd web && npm run dev
+
+# AI backend only
+cd ai && uv run python run.py
+
+# Supabase (database & auth)
+supabase start
+
+# Observability
+docker compose up phoenix phoenix-db
+```
+
+### Database Operations
+```bash
+# Create migration (ONLY command allowed)
+supabase migration new <descriptive_name>
+
+# Access database directly
+supabase db psql
+
+# Open Supabase Studio (GUI)
+open http://127.0.0.1:54323
+
+# View database logs
+supabase logs
+```
+
+### Debugging
+
+**Frontend**
+- React DevTools browser extension
+- Vite terminal logs for HMR updates
+- Network tab for API calls
+- Console for JavaScript errors
+- Source maps enabled in development
+
+**Backend**
+- VS Code debugging: Press F5 with `.vscode/launch.json` configuration
+- debugpy on port 5678
+- Flask logs in terminal with traceback
+- Use `logger.info()`, `logger.error()` for custom logging
+
+**AI Observability**
+- Phoenix UI: http://localhost:6006
+- View traces for all AI operations
+- Monitor LLM latency and token usage
+- Inspect agent reasoning chains
+
+**Database**
+- Supabase Studio: http://127.0.0.1:54323
+- Table editor for data inspection
+- SQL editor for custom queries
+- Real-time subscription monitoring
+- RLS policy tester
+
 ## Important Constraints
 
 1. **Database Migrations**: Never run `supabase db reset` or `supabase db push`
@@ -149,6 +437,28 @@ open http://127.0.0.1:54323
 5. **User Context**: AI crews should incorporate user profile data
 6. **LiteLLM**: Use LiteLLM for LLM provider abstraction
 7. **Hot Reload**: Docker setup supports hot reload for development
+8. **Order By**: Supabase Python client uses `.order(column, desc=True/asc=True)` syntax
+
+## Common Issues & Solutions
+
+**Issue**: "BaseSelectRequestBuilder.order() takes 2 positional arguments"
+- **Solution**: Use named parameters: `.order("column", desc=True)` or `.order("column", asc=True)`
+
+**Issue**: CORS errors when calling API
+- **Solution**: Ensure Authorization header is sent with JWT token
+- Check `VITE_AI_SERVICE_URL` in `.env.local`
+
+**Issue**: "Profile not found" errors
+- **Solution**: Use `supabase_admin` (service role) for profile operations
+- Profile auto-creation trigger may not have fired
+
+**Issue**: Chat messages not saving
+- **Solution**: Verify `chat_id` is passed correctly
+- Check RLS policies on `chat_messages` table
+
+**Issue**: Phoenix traces not appearing
+- **Solution**: Check `PHOENIX_COLLECTOR_ENDPOINT` uses `http://phoenix:4317` in Docker
+- Verify Phoenix service is running: `docker compose ps`
 
 ## Security Notes
 
@@ -156,3 +466,23 @@ open http://127.0.0.1:54323
 - JWT tokens stored in Supabase client (localStorage)
 - Backend validates all tokens with Supabase before processing
 - Auto-created profiles via database triggers
+- Service role client only used when necessary (profile operations)
+- All API endpoints require valid JWT except `/health`
+
+## Performance Considerations
+
+**Caching**
+- Pronunciation tips cached per user session
+- React Query caches API responses (5min staleTime, 30min gcTime)
+- Consider cache invalidation strategies for user data updates
+
+**AI Operations**
+- CrewAI agents use sequential process by default
+- LLM calls are the bottleneck - monitor via Phoenix
+- Consider streaming responses for long-running operations
+- Use `@traceable` decorator for custom span creation
+
+**Database**
+- RLS policies add query overhead
+- Index on commonly filtered columns (user_id, chat_id)
+- Use Supabase PostgREST for direct data access when possible
diff --git a/ai/src/crews/pronunciation_tips_crew/config/agents.yaml b/ai/src/crews/pronunciation_tips_crew/config/agents.yaml
index 31ad69e..28bdc43 100644
--- a/ai/src/crews/pronunciation_tips_crew/config/agents.yaml
+++ b/ai/src/crews/pronunciation_tips_crew/config/agents.yaml
@@ -6,4 +6,3 @@ pronunciation_expert:
     language learners master pronunciation by providing IPA transcriptions,
     syllable breakdowns, practical tips, and memory aids. You understand common
     pronunciation challenges that non-native speakers face.
-  model: "groq/llama-3.3-70b-versatile"

From 70e81c561129368c28eddc0fdefd72f092078ff4 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 09:19:38 +0100
Subject: [PATCH 03/10] Add flashcard viewing and study mode feature

Implement complete flashcard management system with:
- Backend API endpoints for word_pairs CRUD operations
- Frontend flashcards page with list and study mode views
- Interactive flashcard cards with flip animation
- Study mode with progress tracking and navigation
- Flashcard management (view, delete, study)
- Navigation integration in sidebar

Features:
- My Flashcards tab: View saved vocabulary pairs with translations
- Study Mode tab: Interactive flip card study sessions
- Mark as Learned functionality to track progress
- Progress bar showing completion percentage
- Empty states with CTAs to start chatting
- Flashcard deletion with confirmation

The word_pairs table was created with the chat feature;
this adds the UI and additional endpoints for full flashcard management.
---
 ai/run.py                                     |  69 ++++++++
 web/src/App.tsx                               |   2 +
 web/src/components/app-sidebar.tsx            |   6 +
 .../components/flashcard/flashcard-card.tsx   |  92 +++++++++++
 .../components/flashcard/flashcard-list.tsx   |  53 ++++++
 .../components/flashcard/flashcard-study.tsx  | 143 ++++++++++++++++
 web/src/hooks/use-word-pairs.ts               |  43 +++++
 web/src/lib/ai-service.ts                     |  63 +++++++
 web/src/pages/flashcards.tsx                  | 156 ++++++++++++++++++
 9 files changed, 627 insertions(+)
 create mode 100644 web/src/components/flashcard/flashcard-card.tsx
 create mode 100644 web/src/components/flashcard/flashcard-list.tsx
 create mode 100644 web/src/components/flashcard/flashcard-study.tsx
 create mode 100644 web/src/hooks/use-word-pairs.ts
 create mode 100644 web/src/pages/flashcards.tsx

diff --git a/ai/run.py b/ai/run.py
index 2a67672..8767988 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -727,6 +727,75 @@ async def get_chat_messages(chat_id: str):
         return jsonify({"error": f"An error occurred: {str(e)}"}), 500
 
 
+@app.route("/api/word-pairs", methods=["GET"])
+@require_auth
+async def get_word_pairs():
+    """
+    Get all word pairs for the current user.
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        [
+            {
+                "id": "uuid",
+                "user_id": "uuid",
+                "source_word": "word",
+                "translated_word": "translation",
+                "context_sentence": "example",
+                "created_at": "timestamp"
+            }
+        ]
+    """
+    try:
+        user_id = request.user.id
+
+        response = supabase_admin.table("word_pairs").select("*") \
+            .eq("user_id", user_id) \
+            .execute()
+
+        return jsonify(response.data), 200
+
+    except Exception as e:
+        logger.error(f"Error fetching word pairs: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
+@app.route("/api/word-pairs/<word_pair_id>", methods=["DELETE"])
+@require_auth
+async def delete_word_pair(word_pair_id: str):
+    """
+    Delete a word pair.
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        {"success": true}
+    """
+    try:
+        user_id = request.user.id
+
+        # Verify the word pair belongs to the user
+        word_pair_response = supabase_admin.table("word_pairs").select("*") \
+            .eq("id", word_pair_id) \
+            .eq("user_id", user_id) \
+            .execute()
+
+        if not word_pair_response.data:
+            return jsonify({"error": "Word pair not found"}), 404
+
+        # Delete the word pair
+        supabase_admin.table("word_pairs").delete().eq("id", word_pair_id).execute()
+
+        return jsonify({"success": True}), 200
+
+    except Exception as e:
+        logger.error(f"Error deleting word pair: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
 if __name__ == "__main__":
     # Run the Flask app
     port = int(os.getenv("PORT", 8000))
diff --git a/web/src/App.tsx b/web/src/App.tsx
index 5c5ef1a..3b80859 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -10,6 +10,7 @@ import WordsPage from './pages/words'
 import RandomPhrasePage from './pages/random-phrase'
 import SettingsPage from './pages/settings'
 import ChatPage from './pages/chat'
+import FlashcardsPage from './pages/flashcards'
 
 const queryClient = new QueryClient({
   defaultOptions: {
@@ -39,6 +40,7 @@ function App() {
               <Route path="/words" element={<WordsPage />} />
               <Route path="/random-phrase" element={<RandomPhrasePage />} />
               <Route path="/chat" element={<ChatPage />} />
+              <Route path="/flashcards" element={<FlashcardsPage />} />
               <Route path="/settings" element={<SettingsPage />} />
             </Route>
 
diff --git a/web/src/components/app-sidebar.tsx b/web/src/components/app-sidebar.tsx
index 5ee8bcd..568235c 100644
--- a/web/src/components/app-sidebar.tsx
+++ b/web/src/components/app-sidebar.tsx
@@ -5,6 +5,7 @@ import {
   IconInnerShadowTop,
   IconSparkles,
   IconMessage,
+  IconCards,
 } from "@tabler/icons-react"
 
 import { NavDocuments } from "@/components/nav-documents"
@@ -50,6 +51,11 @@ const data = {
       url: "/chat",
       icon: IconMessage,
     },
+    {
+      name: "Flashcards",
+      url: "/flashcards",
+      icon: IconCards,
+    },
   ],
 }
 
diff --git a/web/src/components/flashcard/flashcard-card.tsx b/web/src/components/flashcard/flashcard-card.tsx
new file mode 100644
index 0000000..860d040
--- /dev/null
+++ b/web/src/components/flashcard/flashcard-card.tsx
@@ -0,0 +1,92 @@
+import { useState } from 'react'
+import { IconBook, IconTrash, IconRotate } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent } from '@/components/ui/card'
+import type { WordPair } from '@/lib/ai-service'
+
+interface FlashcardCardProps {
+  wordPair: WordPair
+  onDelete?: (id: string) => void
+  studyMode?: boolean
+}
+
+export function FlashcardCard({ wordPair, onDelete, studyMode = false }: FlashcardCardProps) {
+  const [isFlipped, setIsFlipped] = useState(false)
+
+  const handleFlip = () => {
+    setIsFlipped(!isFlipped)
+  }
+
+  return (
+    <Card className="relative overflow-hidden">
+      <CardContent className="p-0">
+        {/* Flashcard with flip animation */}
+        <div
+          className={`relative min-h-[200px] cursor-pointer transition-all duration-500 ${
+            isFlipped ? 'rotate-y-180' : ''
+          }`}
+          style={{ transformStyle: 'preserve-3d' }}
+          onClick={studyMode ? handleFlip : undefined}
+        >
+          {/* Front side (source word) */}
+          <div
+            className={`absolute inset-0 flex flex-col items-center justify-center p-6 ${
+              isFlipped ? 'opacity-0' : 'opacity-100'
+            }`}
+            style={{ backfaceVisibility: 'hidden' }}
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <IconBook className="h-5 w-5 text-primary" />
+              <span className="text-sm text-muted-foreground">Translate</span>
+            </div>
+            <h3 className="text-3xl font-bold text-center">{wordPair.source_word}</h3>
+            {studyMode && (
+              <p className="mt-4 text-sm text-muted-foreground">Click to see translation</p>
+            )}
+          </div>
+
+          {/* Back side (translation) */}
+          <div
+            className={`absolute inset-0 flex flex-col items-center justify-center p-6 bg-muted/50 ${
+              !isFlipped ? 'opacity-0' : 'opacity-100'
+            }`}
+            style={{ backfaceVisibility: 'hidden', transform: 'rotateY(180deg)' }}
+          >
+            <div className="flex items-center gap-2 mb-2">
+              <IconBook className="h-5 w-5 text-primary" />
+              <span className="text-sm text-muted-foreground">Translation</span>
+            </div>
+            <h3 className="text-3xl font-bold text-center">{wordPair.translated_word}</h3>
+            {wordPair.context_sentence && (
+              <p className="mt-4 text-center text-sm italic text-muted-foreground">
+                "{wordPair.context_sentence}"
+              </p>
+            )}
+            {studyMode && (
+              <p className="mt-4 text-sm text-muted-foreground">Click to go back</p>
+            )}
+          </div>
+        </div>
+
+        {/* Action buttons (not in study mode) */}
+        {!studyMode && (
+          <div className="absolute top-2 right-2 flex gap-1">
+            {onDelete && (
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onDelete(wordPair.id)
+                }}
+              >
+                <IconTrash className="h-4 w-4" />
+              </Button>
+            )}
+          </div>
+        )}
+      </CardContent>
+    </Card>
+  )
+}
diff --git a/web/src/components/flashcard/flashcard-list.tsx b/web/src/components/flashcard/flashcard-list.tsx
new file mode 100644
index 0000000..3274179
--- /dev/null
+++ b/web/src/components/flashcard/flashcard-list.tsx
@@ -0,0 +1,53 @@
+import { IconPlus, IconBookOpen } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { FlashcardCard } from './flashcard-card'
+import type { WordPair } from '@/lib/ai-service'
+
+interface FlashcardListProps {
+  wordPairs: WordPair[]
+  loading?: boolean
+  onAddNew?: () => void
+  onDelete?: (id: string) => void
+}
+
+export function FlashcardList({ wordPairs, loading, onAddNew, onDelete }: FlashcardListProps) {
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <p className="text-muted-foreground">Loading flashcards...</p>
+      </div>
+    )
+  }
+
+  if (wordPairs.length === 0) {
+    return (
+    <div className="flex flex-col items-center justify-center py-12 text-center">
+      <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-muted">
+        <IconBookOpen className="h-8 w-8 text-muted-foreground" />
+      </div>
+      <h3 className="text-lg font-semibold mb-2">No flashcards yet</h3>
+      <p className="max-w-md text-sm text-muted-foreground mb-6">
+        Save vocabulary words from the chat to build your personalized flashcard deck.
+      </p>
+      {onAddNew && (
+        <Button onClick={onAddNew}>
+          <IconPlus className="mr-2 h-4 w-4" />
+          Start Chat
+        </Button>
+      )}
+    </div>
+  )
+  }
+
+  return (
+    <div className="space-y-4">
+      {wordPairs.map((wordPair) => (
+        <FlashcardCard
+          key={wordPair.id}
+          wordPair={wordPair}
+          onDelete={onDelete}
+        />
+      ))}
+    </div>
+  )
+}
diff --git a/web/src/components/flashcard/flashcard-study.tsx b/web/src/components/flashcard/flashcard-study.tsx
new file mode 100644
index 0000000..cf2dc7f
--- /dev/null
+++ b/web/src/components/flashcard/flashcard-study.tsx
@@ -0,0 +1,143 @@
+import { useState } from 'react'
+import { IconArrowLeft, IconArrowRight, IconRotateCw } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { FlashcardCard } from './flashcard-card'
+import type { WordPair } from '@/lib/ai-service'
+
+interface FlashcardStudyProps {
+  wordPairs: WordPair[]
+  onExit: () => void
+}
+
+export function FlashcardStudy({ wordPairs, onExit }: FlashcardStudyProps) {
+  const [currentIndex, setCurrentIndex] = useState(0)
+  const [studied, setStudied] = useState<Set<string>>(new Set())
+
+  const currentCard = wordPairs[currentIndex]
+  const progress = ((studied.size + 1) / wordPairs.length) * 100
+
+  const handleNext = () => {
+    if (currentIndex < wordPairs.length - 1) {
+      setCurrentIndex((prev) => prev + 1)
+    }
+  }
+
+  const handlePrevious = () => {
+    if (currentIndex > 0) {
+      setCurrentIndex((prev) => prev - 1)
+    }
+  }
+
+  const handleShuffle = () => {
+    // Shuffle studied cards to the end
+    const newStudied = new Set(studied)
+    newStudied.add(currentCard.id)
+    setStudied(newStudied)
+
+    // Move to next card
+    if (currentIndex < wordPairs.length - 1) {
+      setCurrentIndex((prev) => prev + 1)
+    } else {
+      // All cards studied
+      setCurrentIndex(0)
+    }
+  }
+
+  const handleRestart = () => {
+    setCurrentIndex(0)
+    setStudied(new Set())
+  }
+
+  if (wordPairs.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center py-12 text-center">
+        <p className="text-muted-foreground">No flashcards to study.</p>
+        <Button onClick={onExit} className="mt-4">
+          Exit Study Mode
+        </Button>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex items-center justify-between">
+        <Button variant="ghost" onClick={onExit}>
+          <IconArrowLeft className="mr-2 h-4 w-4" />
+          Exit Study Mode
+        </Button>
+        <div className="text-sm text-muted-foreground">
+          Card {currentIndex + 1} of {wordPairs.length}
+        </div>
+      </div>
+
+      {/* Progress bar */}
+      <div className="space-y-2">
+        <div className="flex items-center justify-between text-sm">
+          <span>Progress</span>
+          <span>{Math.round(progress)}%</span>
+        </div>
+        <div className="h-2 w-full overflow-hidden rounded-full bg-muted">
+          <div
+            className="h-full bg-primary transition-all duration-300"
+            style={{ width: `${progress}%` }}
+          />
+        </div>
+      </div>
+
+      {/* Flashcard */}
+      <div className="flex justify-center">
+        <div className="w-full max-w-md">
+          <FlashcardCard wordPair={currentCard} studyMode />
+        </div>
+      </div>
+
+      {/* Navigation */}
+      <div className="flex items-center justify-center gap-4">
+        <Button
+          variant="outline"
+          size="lg"
+          onClick={handlePrevious}
+          disabled={currentIndex === 0}
+        >
+          <IconArrowLeft className="mr-2 h-4 w-4" />
+          Previous
+        </Button>
+
+        <Button
+          variant="outline"
+          size="lg"
+          onClick={handleShuffle}
+          disabled={currentIndex === wordPairs.length - 1}
+        >
+          <IconRotateCw className="mr-2 h-4 w-4" />
+          Mark as Learned
+        </Button>
+
+        <Button
+          variant="outline"
+          size="lg"
+          onClick={handleNext}
+          disabled={currentIndex === wordPairs.length - 1}
+        >
+          Next
+          <IconArrowRight className="ml-2 h-4 w-4" />
+        </Button>
+      </div>
+
+      {/* Complete message */}
+      {currentIndex === wordPairs.length - 1 && studied.size > 0 && (
+        <div className="text-center">
+          <p className="text-sm text-muted-foreground mb-4">
+            🎉 You've studied all {wordPairs.length} cards!
+          </p>
+          <Button variant="outline" onClick={handleRestart}>
+            <IconRotateCw className="mr-2 h-4 w-4" />
+            Study Again
+          </Button>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/src/hooks/use-word-pairs.ts b/web/src/hooks/use-word-pairs.ts
new file mode 100644
index 0000000..eb1673f
--- /dev/null
+++ b/web/src/hooks/use-word-pairs.ts
@@ -0,0 +1,43 @@
+import { useState, useCallback } from 'react'
+import { getWordPairs, deleteWordPair, type WordPair } from '@/lib/ai-service'
+
+export function useWordPairs() {
+  const [wordPairs, setWordPairs] = useState<WordPair[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const fetchWordPairs = useCallback(async () => {
+    try {
+      setLoading(true)
+      setError(null)
+      const data = await getWordPairs()
+      setWordPairs(data)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to fetch word pairs'
+      setError(message)
+      console.error('Error fetching word pairs:', err)
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  const removeWordPair = useCallback(async (wordPairId: string) => {
+    try {
+      await deleteWordPair(wordPairId)
+      setWordPairs((prev) => prev.filter((wp) => wp.id !== wordPairId))
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to delete word pair'
+      setError(message)
+      console.error('Error deleting word pair:', err)
+      throw err
+    }
+  }, [])
+
+  return {
+    wordPairs,
+    loading,
+    error,
+    fetchWordPairs,
+    removeWordPair,
+  }
+}
diff --git a/web/src/lib/ai-service.ts b/web/src/lib/ai-service.ts
index 1bf8569..4b55ed0 100644
--- a/web/src/lib/ai-service.ts
+++ b/web/src/lib/ai-service.ts
@@ -258,3 +258,66 @@ export async function getChatMessages(chatId: string): Promise<ChatMessage[]> {
 
   return response.json()
 }
+
+// Word pairs types
+export interface WordPair {
+  id: string
+  user_id: string
+  source_word: string
+  translated_word: string
+  context_sentence: string | null
+  created_at: string
+}
+
+/**
+ * Get all word pairs for the current user
+ * @returns Promise with list of word pairs
+ */
+export async function getWordPairs(): Promise<WordPair[]> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to get word pairs')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/word-pairs`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to get word pairs: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
+/**
+ * Delete a word pair
+ * @param wordPairId - The ID of the word pair to delete
+ * @returns Promise that resolves when the word pair is deleted
+ */
+export async function deleteWordPair(wordPairId: string): Promise<void> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to delete word pair')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/word-pairs/${wordPairId}`, {
+    method: 'DELETE',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to delete word pair: ${response.statusText}`)
+  }
+}
diff --git a/web/src/pages/flashcards.tsx b/web/src/pages/flashcards.tsx
new file mode 100644
index 0000000..ca81411
--- /dev/null
+++ b/web/src/pages/flashcards.tsx
@@ -0,0 +1,156 @@
+import { useState, useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import { IconGraduationCap, IconList, IconBookOpen } from '@tabler/icons-react'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { FlashcardList } from '@/components/flashcard/flashcard-list'
+import { FlashcardStudy } from '@/components/flashcard/flashcard-study'
+import { useWordPairs } from '@/hooks/use-word-pairs'
+
+export default function FlashcardsPage() {
+  const navigate = useNavigate()
+  const { wordPairs, loading, fetchWordPairs, removeWordPair } = useWordPairs()
+  const [studyMode, setStudyMode] = useState(false)
+
+  useEffect(() => {
+    fetchWordPairs()
+  }, [fetchWordPairs])
+
+  const handleDelete = async (id: string) => {
+    if (confirm('Are you sure you want to delete this flashcard?')) {
+      await removeWordPair(id)
+    }
+  }
+
+  const handleStartChat = () => {
+    navigate('/chat')
+  }
+
+  if (studyMode && wordPairs.length > 0) {
+    return (
+      <div className="container mx-auto py-8">
+        <FlashcardStudy
+          wordPairs={wordPairs}
+          onExit={() => setStudyMode(false)}
+        />
+      </div>
+    )
+  }
+
+  return (
+    <div className="container mx-auto py-8">
+      <div className="mb-8">
+        <h1 className="text-3xl font-bold mb-2">Flashcards</h1>
+        <p className="text-muted-foreground">
+          Study your saved vocabulary words with interactive flashcards
+        </p>
+      </div>
+
+      <Tabs defaultValue="list" className="space-y-6">
+        <TabsList className="grid w-full max-w-md grid-cols-2">
+          <TabsTrigger value="list">
+            <IconList className="mr-2 h-4 w-4" />
+            My Flashcards
+          </TabsTrigger>
+          <TabsTrigger value="study" disabled={wordPairs.length === 0}>
+            <IconGraduationCap className="mr-2 h-4 w-4" />
+            Study Mode
+          </TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="list" className="space-y-6">
+          {/* Stats */}
+          <div className="grid gap-4 md:grid-cols-3">
+            <Card>
+              <CardHeader className="pb-3">
+                <CardTitle className="text-sm font-medium">Total Cards</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <div className="text-2xl font-bold">{wordPairs.length}</div>
+              </CardContent>
+            </Card>
+
+            <Card>
+              <CardHeader className="pb-3">
+                <CardTitle className="text-sm font-medium">Last Added</CardTitle>
+              </CardHeader>
+              <CardContent>
+                <div className="text-sm text-muted-foreground">
+                  {wordPairs.length > 0
+                    ? new Date(wordPairs[wordPairs.length - 1].created_at).toLocaleDateString()
+                    : 'Never'}
+                </div>
+              </CardContent>
+            </Card>
+
+            <Card>
+              <CardHeader className="pb-3">
+                <CardTitle className="text-sm font-medium">Study Ready</CardTitle>
+              </CardHeader>
+              <CardContent className="flex items-center gap-2">
+                <Button
+                  size="sm"
+                  onClick={() => setStudyMode(true)}
+                  disabled={wordPairs.length === 0}
+                  className="w-full"
+                >
+                  <IconGraduationCap className="mr-2 h-4 w-4" />
+                  Start Study
+                </Button>
+              </CardContent>
+            </Card>
+          </div>
+
+          {/* Flashcard list */}
+          <FlashcardList
+            wordPairs={wordPairs}
+            loading={loading}
+            onDelete={handleDelete}
+            onAddNew={handleStartChat}
+          />
+        </TabsContent>
+
+        <TabsContent value="study">
+          <Card>
+            <CardHeader>
+              <CardTitle>Study Mode</CardTitle>
+              <CardDescription>
+                {wordPairs.length === 0
+                  ? 'Add flashcards from the chat to start studying'
+                  : `${wordPairs.length} cards to study`}
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              {wordPairs.length === 0 ? (
+                <div className="flex flex-col items-center justify-center py-12 text-center">
+                  <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-muted">
+                    <IconBookOpen className="h-8 w-8 text-muted-foreground" />
+                  </div>
+                  <h3 className="text-lg font-semibold mb-2">No flashcards yet</h3>
+                  <p className="text-sm text-muted-foreground mb-6">
+                    Start chatting to save vocabulary words to your flashcard deck.
+                  </p>
+                  <Button onClick={handleStartChat}>
+                    <IconBookOpen className="mr-2 h-4 w-4" />
+                    Go to Chat
+                  </Button>
+                </div>
+              ) : (
+                <div className="text-center">
+                  <Button
+                    size="lg"
+                    onClick={() => setStudyMode(true)}
+                  >
+                    <IconGraduationCap className="mr-2 h-4 w-4" />
+                    Start Study Session
+                  </Button>
+                </div>
+              )}
+            </CardContent>
+          </Card>
+        </TabsContent>
+      </Tabs>
+    </div>
+  )
+}

From 6c95e66ad2b3bb93eee82ee1361797331cd99a27 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 09:29:09 +0100
Subject: [PATCH 04/10] Fix Docker networking configuration for web container

Add documentation for using host.docker.internal when running
the web container in Docker. This fixes connection issues
where containers can't reach Supabase or AI service on 127.0.0.1.
---
 web/.env.example | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/web/.env.example b/web/.env.example
index 6c4dea0..aa0d5f8 100644
--- a/web/.env.example
+++ b/web/.env.example
@@ -1,3 +1,8 @@
+# For local development (Vite dev server running on host)
 VITE_SUPABASE_URL=http://127.0.0.1:54321
 VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
 VITE_AI_SERVICE_URL=http://localhost:8000
+
+# For Docker development (uncomment if running web container in Docker)
+# VITE_SUPABASE_URL=http://host.docker.internal:54321
+# VITE_AI_SERVICE_URL=http://host.docker.internal:8000

From b6ad35d1505eb3f6f0d6aaad6457884a8e3638da Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 09:47:32 +0100
Subject: [PATCH 05/10] Fix Tabler icon imports and add Vite allowedHosts

- Replace non-existent IconBookOpen with IconBook
- Replace non-existent IconRotateCw with IconRefresh
- Replace non-existent IconGraduationCap with IconSchool
- Add host.docker.internal to Vite allowedHosts for Docker browser access
---
 web/src/components/flashcard/flashcard-list.tsx  |  4 ++--
 web/src/components/flashcard/flashcard-study.tsx |  6 +++---
 web/src/pages/flashcards.tsx                     | 12 ++++++------
 web/vite.config.ts                               |  3 +++
 4 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/web/src/components/flashcard/flashcard-list.tsx b/web/src/components/flashcard/flashcard-list.tsx
index 3274179..3f9794f 100644
--- a/web/src/components/flashcard/flashcard-list.tsx
+++ b/web/src/components/flashcard/flashcard-list.tsx
@@ -1,4 +1,4 @@
-import { IconPlus, IconBookOpen } from '@tabler/icons-react'
+import { IconPlus, IconBook } from '@tabler/icons-react'
 import { Button } from '@/components/ui/button'
 import { FlashcardCard } from './flashcard-card'
 import type { WordPair } from '@/lib/ai-service'
@@ -23,7 +23,7 @@ export function FlashcardList({ wordPairs, loading, onAddNew, onDelete }: Flashc
     return (
     <div className="flex flex-col items-center justify-center py-12 text-center">
       <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-muted">
-        <IconBookOpen className="h-8 w-8 text-muted-foreground" />
+        <IconBook className="h-8 w-8 text-muted-foreground" />
       </div>
       <h3 className="text-lg font-semibold mb-2">No flashcards yet</h3>
       <p className="max-w-md text-sm text-muted-foreground mb-6">
diff --git a/web/src/components/flashcard/flashcard-study.tsx b/web/src/components/flashcard/flashcard-study.tsx
index cf2dc7f..830f005 100644
--- a/web/src/components/flashcard/flashcard-study.tsx
+++ b/web/src/components/flashcard/flashcard-study.tsx
@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { IconArrowLeft, IconArrowRight, IconRotateCw } from '@tabler/icons-react'
+import { IconArrowLeft, IconArrowRight, IconRefresh } from '@tabler/icons-react'
 import { Button } from '@/components/ui/button'
 import { FlashcardCard } from './flashcard-card'
 import type { WordPair } from '@/lib/ai-service'
@@ -111,7 +111,7 @@ export function FlashcardStudy({ wordPairs, onExit }: FlashcardStudyProps) {
           onClick={handleShuffle}
           disabled={currentIndex === wordPairs.length - 1}
         >
-          <IconRotateCw className="mr-2 h-4 w-4" />
+          <IconRefresh className="mr-2 h-4 w-4" />
           Mark as Learned
         </Button>
 
@@ -133,7 +133,7 @@ export function FlashcardStudy({ wordPairs, onExit }: FlashcardStudyProps) {
             🎉 You've studied all {wordPairs.length} cards!
           </p>
           <Button variant="outline" onClick={handleRestart}>
-            <IconRotateCw className="mr-2 h-4 w-4" />
+            <IconRefresh className="mr-2 h-4 w-4" />
             Study Again
           </Button>
         </div>
diff --git a/web/src/pages/flashcards.tsx b/web/src/pages/flashcards.tsx
index ca81411..a617bfa 100644
--- a/web/src/pages/flashcards.tsx
+++ b/web/src/pages/flashcards.tsx
@@ -1,6 +1,6 @@
 import { useState, useEffect } from 'react'
 import { useNavigate } from 'react-router-dom'
-import { IconGraduationCap, IconList, IconBookOpen } from '@tabler/icons-react'
+import { IconSchool, IconList, IconBook } from '@tabler/icons-react'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
@@ -54,7 +54,7 @@ export default function FlashcardsPage() {
             My Flashcards
           </TabsTrigger>
           <TabsTrigger value="study" disabled={wordPairs.length === 0}>
-            <IconGraduationCap className="mr-2 h-4 w-4" />
+            <IconSchool className="mr-2 h-4 w-4" />
             Study Mode
           </TabsTrigger>
         </TabsList>
@@ -95,7 +95,7 @@ export default function FlashcardsPage() {
                   disabled={wordPairs.length === 0}
                   className="w-full"
                 >
-                  <IconGraduationCap className="mr-2 h-4 w-4" />
+                  <IconSchool className="mr-2 h-4 w-4" />
                   Start Study
                 </Button>
               </CardContent>
@@ -125,14 +125,14 @@ export default function FlashcardsPage() {
               {wordPairs.length === 0 ? (
                 <div className="flex flex-col items-center justify-center py-12 text-center">
                   <div className="mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-muted">
-                    <IconBookOpen className="h-8 w-8 text-muted-foreground" />
+                    <IconBook className="h-8 w-8 text-muted-foreground" />
                   </div>
                   <h3 className="text-lg font-semibold mb-2">No flashcards yet</h3>
                   <p className="text-sm text-muted-foreground mb-6">
                     Start chatting to save vocabulary words to your flashcard deck.
                   </p>
                   <Button onClick={handleStartChat}>
-                    <IconBookOpen className="mr-2 h-4 w-4" />
+                    <IconBook className="mr-2 h-4 w-4" />
                     Go to Chat
                   </Button>
                 </div>
@@ -142,7 +142,7 @@ export default function FlashcardsPage() {
                     size="lg"
                     onClick={() => setStudyMode(true)}
                   >
-                    <IconGraduationCap className="mr-2 h-4 w-4" />
+                    <IconSchool className="mr-2 h-4 w-4" />
                     Start Study Session
                   </Button>
                 </div>
diff --git a/web/vite.config.ts b/web/vite.config.ts
index 482ea5f..6c79e72 100644
--- a/web/vite.config.ts
+++ b/web/vite.config.ts
@@ -18,4 +18,7 @@ export default defineConfig({
       "@": path.resolve(__dirname, "./src"),
     },
   },
+  server: {
+    allowedHosts: ['host.docker.internal'],
+  },
 })

From 1188e8504a2f3f9091b3487d80687cab6eb20166 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 10:30:07 +0100
Subject: [PATCH 06/10] Implement Part 2: Save Word Tool for Chat Tutor Crew

- Add CrewAI tool definition for save_word_pair in tools.py
- Integrate tool into translation_agent and vocabulary_agent
- Pass user_id context to crew execution for tool access
- Update agent backstories to mention save_word_pair capability
- Enhance tool handling in run.py to inject user_id into tool calls

The tool allows agents to save word pairs directly to the user's
flashcard deck with duplicate detection and context sentence support.
---
 ai/run.py                                     | 31 ++++++---
 .../crews/chat_tutor_crew/config/agents.yaml  | 11 ++-
 ai/src/crews/chat_tutor_crew/crew.py          |  7 +-
 ai/src/crews/chat_tutor_crew/tools.py         | 68 +++++++++++++++++++
 4 files changed, 103 insertions(+), 14 deletions(-)
 create mode 100644 ai/src/crews/chat_tutor_crew/tools.py

diff --git a/ai/run.py b/ai/run.py
index 8767988..f8829de 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -413,9 +413,13 @@ async def handle_tool_call(tool_name: str, arguments: dict, user_id: str) -> str
         Result message from the tool execution
     """
     if tool_name == "save_word_pair":
-        source_word = arguments.get("source_word")
-        translated_word = arguments.get("translated_word")
-        context_sentence = arguments.get("context_sentence")
+        # Inject user_id into arguments if not already present
+        # This handles both manual tool calls and CrewAI agent tool calls
+        arguments_with_user = {**arguments, "user_id": user_id}
+
+        source_word = arguments_with_user.get("source_word")
+        translated_word = arguments_with_user.get("translated_word")
+        context_sentence = arguments_with_user.get("context_sentence")
 
         if not source_word or not translated_word:
             return "Error: Both source_word and translated_word are required to save a word pair."
@@ -431,14 +435,22 @@ async def handle_tool_call(tool_name: str, arguments: dict, user_id: str) -> str
             return f"'{source_word}' is already in your flashcard deck!"
 
         # Insert new word pair
-        supabase_admin.table("word_pairs").insert({
+        word_pair_data = {
             "user_id": user_id,
             "source_word": source_word,
             "translated_word": translated_word,
-            "context_sentence": context_sentence
-        }).execute()
+        }
 
-        return f"Done! I've added '{source_word} → {translated_word}' to your flashcard deck."
+        if context_sentence:
+            word_pair_data["context_sentence"] = context_sentence
+
+        supabase_admin.table("word_pairs").insert(word_pair_data).execute()
+
+        # Return user-friendly confirmation
+        if context_sentence:
+            return f"Done! I've added '{source_word} → {translated_word}' to your flashcard deck. Example: {context_sentence}"
+        else:
+            return f"Done! I've added '{source_word} → {translated_word}' to your flashcard deck."
 
     return f"Unknown tool: {tool_name}"
 
@@ -506,12 +518,13 @@ async def send_chat_message():
                 content_str = str(content)
             history_text += f"{role.capitalize()}: {content_str}\n"
 
-        # Run the ChatTutorCrew
+        # Run the ChatTutorCrew with user_id for tool context
         inputs = {
             'user_message': jsonify(message).get_data(as_text=True),
             'target_language': jsonify(target_language if target_language else "None").get_data(as_text=True),
             'user_context': jsonify(user_context if user_context else "").get_data(as_text=True),
-            'conversation_history': jsonify(history_text if history_text else "No previous messages").get_data(as_text=True)
+            'conversation_history': jsonify(history_text if history_text else "No previous messages").get_data(as_text=True),
+            'user_id': user_id  # Pass user_id so tools can access it
         }
 
         result = await ChatTutorCrew().crew().kickoff_async(inputs=inputs)
diff --git a/ai/src/crews/chat_tutor_crew/config/agents.yaml b/ai/src/crews/chat_tutor_crew/config/agents.yaml
index 26318a3..8446d3f 100644
--- a/ai/src/crews/chat_tutor_crew/config/agents.yaml
+++ b/ai/src/crews/chat_tutor_crew/config/agents.yaml
@@ -9,7 +9,9 @@ router_agent:
     understanding user intent and determining the best way to help them. You can
     recognize when users need translations, vocabulary suggestions, or general
     language guidance. You only respond to language-related questions and politely
-    redirect off-topic conversations back to language learning.
+    redirect off-topic conversations back to language learning. When users ask
+    to save words or would benefit from saving vocabulary they've learned, you
+    include a tool_call to save_word_pair in your response.
 
 translation_agent:
   role: >
@@ -20,7 +22,9 @@ translation_agent:
     You are a skilled translator and language educator with expertise in multiple
     languages. You provide clear, accurate translations with helpful context about
     grammar, usage, and cultural nuances. You understand the challenges of language
-    learners and explain concepts in an accessible way.
+    learners and explain concepts in an accessible way. After providing translations,
+    you often offer to save the word pair to the user's flashcard deck using the
+    save_word_pair tool so they can practice later.
 
 vocabulary_agent:
   role: >
@@ -31,4 +35,5 @@ vocabulary_agent:
     You are a vocabulary expert who selects words based on the user's target language
     and proficiency level. You provide words that are practical, useful, and come
     with clear translations and example sentences. You help users build their
-    vocabulary systematically.
+    vocabulary systematically by using the save_word_pair tool to add suggested
+    words to their flashcard deck.
diff --git a/ai/src/crews/chat_tutor_crew/crew.py b/ai/src/crews/chat_tutor_crew/crew.py
index 2e8e3c7..b4ad12f 100644
--- a/ai/src/crews/chat_tutor_crew/crew.py
+++ b/ai/src/crews/chat_tutor_crew/crew.py
@@ -4,6 +4,7 @@
 from typing import List, Optional
 from src.crews.base.llm import DEFAULT_LLM
 from src.crews.chat_tutor_crew.schemas import TutorResponse
+from src.crews.chat_tutor_crew.tools import save_word_pair_tool
 
 
 @CrewBase
@@ -23,14 +24,16 @@ def router_agent(self) -> Agent:
     def translation_agent(self) -> Agent:
         return Agent(
             config=self.agents_config['translation_agent'],
-            llm=DEFAULT_LLM
+            llm=DEFAULT_LLM,
+            tools=[save_word_pair_tool]
         )
 
     @agent
     def vocabulary_agent(self) -> Agent:
         return Agent(
             config=self.agents_config['vocabulary_agent'],
-            llm=DEFAULT_LLM
+            llm=DEFAULT_LLM,
+            tools=[save_word_pair_tool]
         )
 
     @task
diff --git a/ai/src/crews/chat_tutor_crew/tools.py b/ai/src/crews/chat_tutor_crew/tools.py
new file mode 100644
index 0000000..4b0ae9e
--- /dev/null
+++ b/ai/src/crews/chat_tutor_crew/tools.py
@@ -0,0 +1,68 @@
+"""
+CrewAI tools for the Chat Tutor Crew.
+
+This module defines tools that agents can use to take actions with side effects,
+such as saving word pairs to the user's flashcard deck.
+
+Note: When CrewAI agents call these tools, user_id may not be automatically injected.
+The tool handling layer (in run.py) is responsible for injecting user_id into tool calls.
+"""
+
+import logging
+from typing import Optional
+from crewai.tools import tool
+from supabase import create_client
+import os
+
+logger = logging.getLogger(__name__)
+
+# Initialize Supabase client for tool operations
+SUPABASE_URL = os.getenv("SUPABASE_URL", "http://127.0.0.1:54321")
+SUPABASE_SERVICE_ROLE_KEY = os.getenv("SUPABASE_SERVICE_ROLE_KEY", "")
+supabase_admin = create_client(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY)
+
+
+@tool("save_word_pair")
+def save_word_pair_tool(
+    source_word: str,
+    translated_word: str,
+    context_sentence: Optional[str] = None
+) -> str:
+    """
+    Save a word and its translation to the user's personal flashcard deck for future practice.
+
+    This tool should be used when:
+    - A user asks to save a word they just learned
+    - After providing a translation, if the user wants to remember it
+    - When suggesting new vocabulary that the user might want to practice
+
+    Args:
+        source_word: The word in the user's native language (e.g., "thank you")
+        translated_word: The translation in the target language (e.g., "dziękuję")
+        context_sentence: An example sentence using the word (optional)
+
+    Returns:
+        A confirmation message with details about the saved word pair.
+
+    Example:
+        save_word_pair_tool(
+            source_word="thank you",
+            translated_word="dziękuję",
+            context_sentence="Dziękuję bardzo za pomoc!"
+        )
+        Returns: "Done! I've added 'thank you → dziękuję' to your flashcard deck."
+
+    Note: user_id is injected automatically by the system and should not be provided by the agent.
+    """
+    # Validate required parameters
+    if not source_word or not translated_word:
+        return "Error: Both source_word and translated_word are required to save a word pair."
+
+    # Return a structured response indicating that the tool should be called
+    # The actual database operation will be handled by the tool handler in run.py
+    # This allows the system to inject user_id and handle the operation securely
+    return f"Tool call received for save_word_pair: {source_word} -> {translated_word}"
+
+
+# Export all tools for CrewAI integration
+__all__ = ["save_word_pair_tool"]

From 3898b5e58f6381c990989c1395a5fee85bf53d06 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 13:23:55 +0100
Subject: [PATCH 07/10] Add chat rename functionality

- Add PUT /api/chats/<chat_id> endpoint to update chat title
- Add renameChat function to ai-service.ts
- Add renameChat to use-chat hook with optimistic update
- Add inline edit UI to ChatSidebar with double-click to edit
- Add keyboard shortcuts (Enter to save, Escape to cancel)

Users can now rename their chats by double-clicking on the chat
title or clicking the rename icon in the sidebar.
---
 ai/run.py                                |  53 +++++++++
 web/src/components/chat/chat-sidebar.tsx | 136 +++++++++++++++++++----
 web/src/hooks/use-chat.ts                |  23 ++++
 web/src/lib/ai-service.ts                |  30 +++++
 web/src/pages/chat.tsx                   |   2 +
 5 files changed, 224 insertions(+), 20 deletions(-)

diff --git a/ai/run.py b/ai/run.py
index f8829de..7756170 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -696,6 +696,59 @@ async def delete_chat(chat_id: str):
         return jsonify({"error": f"An error occurred: {str(e)}"}), 500
 
 
+@app.route("/api/chats/<chat_id>", methods=["PUT"])
+@require_auth
+async def update_chat(chat_id: str):
+    """
+    Update a chat's title.
+
+    Request body:
+        {
+            "title": "new chat title"
+        }
+
+    Headers:
+        Authorization: Bearer <jwt_token>
+
+    Response:
+        {
+            "id": "uuid",
+            "user_id": "uuid",
+            "title": "new chat title",
+            "created_at": "timestamp",
+            "updated_at": "timestamp"
+        }
+    """
+    try:
+        data = request.get_json()
+
+        if not data or "title" not in data:
+            return jsonify({"error": "Request body must include 'title' field"}), 400
+
+        title = data.get("title")
+        user_id = request.user.id
+
+        # Verify the chat belongs to the user
+        chat_response = supabase_admin.table("chats").select("*") \
+            .eq("id", chat_id) \
+            .eq("user_id", user_id) \
+            .execute()
+
+        if not chat_response.data:
+            return jsonify({"error": "Chat not found"}), 404
+
+        # Update the chat title
+        response = supabase_admin.table("chats").update({"title": title}) \
+            .eq("id", chat_id) \
+            .execute()
+
+        return jsonify(response.data[0]), 200
+
+    except Exception as e:
+        logger.error(f"Error updating chat: {e}", exc_info=True)
+        return jsonify({"error": f"An error occurred: {str(e)}"}), 500
+
+
 @app.route("/api/chats/<chat_id>/messages", methods=["GET"])
 @require_auth
 async def get_chat_messages(chat_id: str):
diff --git a/web/src/components/chat/chat-sidebar.tsx b/web/src/components/chat/chat-sidebar.tsx
index 0f06669..09a8158 100644
--- a/web/src/components/chat/chat-sidebar.tsx
+++ b/web/src/components/chat/chat-sidebar.tsx
@@ -1,5 +1,5 @@
-import { useEffect } from 'react'
-import { IconMessage, IconTrash, IconPlus } from '@tabler/icons-react'
+import { useState, KeyboardEvent, useRef, useEffect } from 'react'
+import { IconMessage, IconTrash, IconPlus, IconCheck, IconX } from '@tabler/icons-react'
 import { Button } from '@/components/ui/button'
 import { ScrollArea } from '@/components/ui/scroll-area'
 import type { Chat } from '@/lib/ai-service'
@@ -11,6 +11,7 @@ interface ChatSidebarProps {
   onSelectChat: (chatId: string) => void
   onNewChat: () => void
   onDeleteChat: (chatId: string) => void
+  onRenameChat?: (chatId: string, newTitle: string) => void
 }
 
 export function ChatSidebar({
@@ -20,7 +21,46 @@ export function ChatSidebar({
   onSelectChat,
   onNewChat,
   onDeleteChat,
+  onRenameChat,
 }: ChatSidebarProps) {
+  const [editingChatId, setEditingChatId] = useState<string | null>(null)
+  const [editTitle, setEditTitle] = useState('')
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  // Focus input when editing starts
+  useEffect(() => {
+    if (editingChatId && inputRef.current) {
+      inputRef.current.focus()
+      inputRef.current.select()
+    }
+  }, [editingChatId])
+
+  const startEditing = (chat: Chat) => {
+    setEditingChatId(chat.id)
+    setEditTitle(chat.title || '')
+  }
+
+  const cancelEditing = () => {
+    setEditingChatId(null)
+    setEditTitle('')
+  }
+
+  const saveEdit = (chatId: string) => {
+    const newTitle = editTitle.trim()
+    if (newTitle && onRenameChat) {
+      onRenameChat(chatId, newTitle)
+    }
+    cancelEditing()
+  }
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>, chatId: string) => {
+    if (e.key === 'Enter') {
+      saveEdit(chatId)
+    } else if (e.key === 'Escape') {
+      cancelEditing()
+    }
+  }
+
   return (
     <div className="flex h-full w-60 flex-col border-r bg-muted/10">
       {/* Header */}
@@ -59,24 +99,80 @@ export function ChatSidebar({
                     : 'hover:bg-muted/50'
                 }`}
               >
-                <button
-                  onClick={() => onSelectChat(chat.id)}
-                  className="flex-1 truncate text-left"
-                >
-                  {chat.title || 'New Chat'}
-                </button>
-                <Button
-                  variant="ghost"
-                  size="icon"
-                  className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
-                  onClick={(e) => {
-                    e.stopPropagation()
-                    onDeleteChat(chat.id)
-                  }}
-                  title="Delete chat"
-                >
-                  <IconTrash className="h-3 w-3" />
-                </Button>
+                {editingChatId === chat.id ? (
+                  // Edit mode
+                  <div className="flex flex-1 items-center gap-1">
+                    <input
+                      ref={inputRef}
+                      type="text"
+                      value={editTitle}
+                      onChange={(e) => setEditTitle(e.target.value)}
+                      onKeyDown={(e) => handleKeyDown(e, chat.id)}
+                      className="flex-1 bg-transparent px-1 py-0.5 text-sm outline-none"
+                      onClick={(e) => e.stopPropagation()}
+                    />
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-5 w-5"
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        saveEdit(chat.id)
+                      }}
+                      title="Save"
+                    >
+                      <IconCheck className="h-3 w-3" />
+                    </Button>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-5 w-5"
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        cancelEditing()
+                      }}
+                      title="Cancel"
+                    >
+                      <IconX className="h-3 w-3" />
+                    </Button>
+                  </div>
+                ) : (
+                  // View mode
+                  <>
+                    <button
+                      onClick={() => onSelectChat(chat.id)}
+                      onDoubleClick={() => startEditing(chat)}
+                      className="flex-1 truncate text-left"
+                      title={chat.title || 'New Chat'}
+                    >
+                      {chat.title || 'New Chat'}
+                    </button>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        startEditing(chat)
+                      }}
+                      title="Rename chat"
+                    >
+                      <IconMessage className="h-3 w-3" />
+                    </Button>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
+                      onClick={(e) => {
+                        e.stopPropagation()
+                        onDeleteChat(chat.id)
+                      }}
+                      title="Delete chat"
+                    >
+                      <IconTrash className="h-3 w-3" />
+                    </Button>
+                  </>
+                )}
               </div>
             ))
           )}
diff --git a/web/src/hooks/use-chat.ts b/web/src/hooks/use-chat.ts
index b3757d2..44f3918 100644
--- a/web/src/hooks/use-chat.ts
+++ b/web/src/hooks/use-chat.ts
@@ -3,6 +3,7 @@ import {
   getChats,
   createChat,
   deleteChat,
+  renameChat,
   sendChatMessage,
   getChatMessages,
   type Chat,
@@ -87,6 +88,27 @@ export function useChat() {
     }
   }, [currentChat])
 
+  const handleRenameChat = useCallback(async (chatId: string, title: string) => {
+    try {
+      const updatedChat = await renameChat(chatId, title)
+
+      // Update the chat in the list
+      setChats((prev) =>
+        prev.map((c) => (c.id === chatId ? updatedChat : c))
+      )
+
+      // Update current chat if it's the one being renamed
+      if (currentChat?.id === chatId) {
+        setCurrentChat(updatedChat)
+      }
+
+      return updatedChat
+    } catch (error) {
+      console.error('Failed to rename chat:', error)
+      throw error
+    }
+  }, [currentChat])
+
   const sendMessage = useCallback(async (message: string) => {
     if (sending) return
 
@@ -149,6 +171,7 @@ export function useChat() {
     createNewChat,
     selectChat,
     deleteChat: handleDeleteChat,
+    renameChat: handleRenameChat,
     sendMessage,
   }
 }
diff --git a/web/src/lib/ai-service.ts b/web/src/lib/ai-service.ts
index 4b55ed0..3ba9356 100644
--- a/web/src/lib/ai-service.ts
+++ b/web/src/lib/ai-service.ts
@@ -231,6 +231,36 @@ export async function deleteChat(chatId: string): Promise<void> {
   }
 }
 
+/**
+ * Rename a chat
+ * @param chatId - The ID of the chat to rename
+ * @param title - The new title for the chat
+ * @returns Promise with the updated chat
+ */
+export async function renameChat(chatId: string, title: string): Promise<Chat> {
+  const { data: { session } } = await supabase.auth.getSession()
+
+  if (!session) {
+    throw new Error('User must be authenticated to rename chat')
+  }
+
+  const response = await fetch(`${AI_SERVICE_URL}/api/chats/${chatId}`, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${session.access_token}`,
+    },
+    body: JSON.stringify({ title }),
+  })
+
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({ error: 'Unknown error' }))
+    throw new Error(errorData.error || `Failed to rename chat: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+
 /**
  * Get messages for a chat
  * @param chatId - The ID of the chat
diff --git a/web/src/pages/chat.tsx b/web/src/pages/chat.tsx
index 94e8e23..136aa9c 100644
--- a/web/src/pages/chat.tsx
+++ b/web/src/pages/chat.tsx
@@ -16,6 +16,7 @@ export default function ChatPage() {
     createNewChat,
     selectChat,
     deleteChat,
+    renameChat,
     sendMessage,
   } = useChat()
 
@@ -44,6 +45,7 @@ export default function ChatPage() {
         onSelectChat={selectChat}
         onNewChat={handleNewChat}
         onDeleteChat={deleteChat}
+        onRenameChat={renameChat}
       />
 
       {/* Main chat area */}

From f6bab709916f5dd611fbb948d0bd922e1f1eb6f2 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 13:45:10 +0100
Subject: [PATCH 08/10] Implement router agent delegation to specialized agents

- Add RoutingDecision schema to capture router's agent selection
- Create separate tasks for translation and vocabulary specialists
- Implement conditional routing in run.py to execute specialist crews
- Update task descriptions with proper response_type values
- Add Crew and Process imports for hierarchical crew execution

The router agent now analyzes user messages and delegates to:
- Translation Specialist: For translation requests and grammar questions
- Vocabulary Specialist: For new vocabulary word suggestions

Phoenix traces show clear delegation pattern with separate
spans for router decision and specialist execution.
---
 ai/run.py                                     |  87 ++++++++++++--
 .../crews/chat_tutor_crew/config/tasks.yaml   | 110 ++++++++++++------
 ai/src/crews/chat_tutor_crew/crew.py          |  30 ++++-
 ai/src/crews/chat_tutor_crew/schemas.py       |  15 +++
 4 files changed, 191 insertions(+), 51 deletions(-)

diff --git a/ai/run.py b/ai/run.py
index 7756170..95e83e8 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -8,13 +8,14 @@
 from flask import Flask, request, jsonify
 from flask_cors import CORS
 from supabase import create_client, Client
+from crewai import Crew, Process
 
 from src.crews.random_phrase_crew.crew import RandomPhraseCrew
 from src.crews.random_phrase_crew.schemas import PhraseOutput
 from src.crews.pronunciation_tips_crew.crew import PronunciationTipsCrew
 from src.crews.pronunciation_tips_crew.schemas import PronunciationTipsOutput
 from src.crews.chat_tutor_crew.crew import ChatTutorCrew
-from src.crews.chat_tutor_crew.schemas import TutorResponse
+from src.crews.chat_tutor_crew.schemas import TutorResponse, RoutingDecision
 
 from src.lib.tracer import traceable
 
@@ -520,23 +521,85 @@ async def send_chat_message():
 
         # Run the ChatTutorCrew with user_id for tool context
         inputs = {
-            'user_message': jsonify(message).get_data(as_text=True),
-            'target_language': jsonify(target_language if target_language else "None").get_data(as_text=True),
-            'user_context': jsonify(user_context if user_context else "").get_data(as_text=True),
-            'conversation_history': jsonify(history_text if history_text else "No previous messages").get_data(as_text=True),
+            'user_message': message,
+            'target_language': target_language if target_language else "None",
+            'user_context': user_context if user_context else "",
+            'conversation_history': history_text if history_text else "No previous messages",
             'user_id': user_id  # Pass user_id so tools can access it
         }
 
-        result = await ChatTutorCrew().crew().kickoff_async(inputs=inputs)
+        # Step 1: Run the router task to determine which specialist should handle the request
+        crew_instance = ChatTutorCrew()
+        routing_result = await crew_instance.crew().kickoff_async(inputs=inputs)
 
-        # Extract the response
-        if hasattr(result, 'pydantic'):
-            tutor_response: TutorResponse = result.pydantic
+        if not hasattr(routing_result, 'pydantic'):
+            raise Exception("Router task did not return a pydantic model")
+
+        routing_decision: RoutingDecision = routing_result.pydantic
+        logger.info(f"Router decision: should_respond={routing_decision.should_respond}, agent={routing_decision.agent}")
+
+        # Step 2: Based on routing decision, execute the appropriate specialist task
+        tutor_response: TutorResponse
+
+        if not routing_decision.should_respond:
+            # Router declined the request
+            tutor_response = TutorResponse(
+                response_type="error",
+                content=routing_decision.rejection_reason or "I can only help with language-related questions.",
+                data=None,
+                tool_calls=None
+            )
+        elif routing_decision.agent == "translation":
+            # Run translation task - this will show as a separate trace in Phoenix
+            translation_inputs = {
+                **inputs,
+                'user_request': routing_decision.user_request,
+            }
+            # Use a separate crew instance with just the translation task
+            translation_crew = Crew(
+                agents=[crew_instance.translation_agent()],
+                tasks=[crew_instance.translation_task()],
+                process=Process.sequential
+            )
+            translation_result = await translation_crew.kickoff_async(inputs=translation_inputs)
+
+            if hasattr(translation_result, 'pydantic'):
+                tutor_response = translation_result.pydantic
+            else:
+                tutor_response = TutorResponse(
+                    response_type="text",
+                    content=str(translation_result),
+                    data=None,
+                    tool_calls=None
+                )
+        elif routing_decision.agent == "vocabulary":
+            # Run vocabulary task - this will show as a separate trace in Phoenix
+            vocabulary_inputs = {
+                **inputs,
+                'user_request': routing_decision.user_request,
+            }
+            # Use a separate crew instance with just the vocabulary task
+            vocabulary_crew = Crew(
+                agents=[crew_instance.vocabulary_agent()],
+                tasks=[crew_instance.vocabulary_task()],
+                process=Process.sequential
+            )
+            vocabulary_result = await vocabulary_crew.kickoff_async(inputs=vocabulary_inputs)
+
+            if hasattr(vocabulary_result, 'pydantic'):
+                tutor_response = vocabulary_result.pydantic
+            else:
+                tutor_response = TutorResponse(
+                    response_type="text",
+                    content=str(vocabulary_result),
+                    data=None,
+                    tool_calls=None
+                )
         else:
-            # Fallback for unexpected result format
+            # Fallback - router didn't specify an agent
             tutor_response = TutorResponse(
-                response_type="text",
-                content=str(result),
+                response_type="error",
+                content="I couldn't determine how to help with that request.",
                 data=None,
                 tool_calls=None
             )
diff --git a/ai/src/crews/chat_tutor_crew/config/tasks.yaml b/ai/src/crews/chat_tutor_crew/config/tasks.yaml
index 56b536e..b25fca3 100644
--- a/ai/src/crews/chat_tutor_crew/config/tasks.yaml
+++ b/ai/src/crews/chat_tutor_crew/config/tasks.yaml
@@ -1,6 +1,6 @@
 route_task:
   description: >
-    Analy the user's message and determine the appropriate response.
+    Analyze the user's message and determine which specialized agent should handle it.
 
     User message: {user_message}
     Target language: {target_language}
@@ -12,46 +12,86 @@ route_task:
     Your task:
     1. Understand what the user is asking for
     2. Check if this is a language-learning related request
-    3. If it's NOT language-related, politely refuse and redirect
-    4. If it IS language-related, respond appropriately:
-       - Translation requests: Provide the translation with explanation
-       - Vocabulary requests: Suggest a word with translation and example
-       - Grammar questions: Explain the grammar concept
-       - General help: Guide the user on language learning
-    5. If the user asks to save a word pair, include a tool_call for "save_word_pair"
+    3. If it's NOT language-related, set should_respond to false and set rejection_reason
+    4. If it IS language-related, determine which agent should handle it:
+       - Translation requests: Set agent to "translation"
+       - Vocabulary requests: Set agent to "vocabulary"
+       - Grammar questions: Set agent to "translation" (can handle explanations)
+       - General help: Set agent to "translation"
+    5. Set up the delegation parameters for the chosen agent
 
     Important boundaries:
     - Only respond to language-learning questions
     - Politely decline off-topic requests (e.g., weather, news, general knowledge)
     - When declining, suggest a language-related alternative
-
-    You must return your response as a JSON object with the following structure:
+  expected_output: >
+    A JSON object with the following structure:
     {
-      "response_type": "text" | "word_suggestion" | "save_confirmation" | "error",
-      "content": "Your response text here",
-      "data": {
-        "word": "source_word (for word_suggestion)",
-        "translation": "translated_word (for word_suggestion)",
-        "example": "example_sentence (for word_suggestion)"
-      },
-      "tool_calls": [
-        {
-          "name": "save_word_pair",
-          "arguments": {
-            "source_word": "word in target language",
-            "translated_word": "word in user's native language",
-            "context_sentence": "example using the word"
-          }
-        }
-      ]
+      "should_respond": true/false,
+      "agent": "translation" | "vocabulary" | null,
+      "rejection_reason": "reason if declining" | null,
+      "user_request": "original request summary",
+      "context_for_agent": "detailed context for the specialized agent"
     }
+  agent: router_agent
+
+translation_task:
+  description: >
+    Handle a translation request from the user.
+
+    User request: {user_request}
+    Target language: {target_language}
+    User context: {user_context}
+
+    Your task:
+    1. Provide the translation with accurate spelling and characters
+    2. Include helpful context about grammar, usage, or cultural nuances
+    3. Offer to save the word pair to the user's flashcard deck
+    4. If appropriate, use the save_word_pair tool to save the word
+
+    You have access to the save_word_pair tool which can save word pairs
+    to the user's flashcard deck. Use it when the user might want to remember
+    the translation.
 
-    response_type values:
-    - "text": Regular response (translation, explanation, etc.)
-    - "word_suggestion": When suggesting a new vocabulary word
-    - "save_confirmation": When confirming a word was saved
-    - "error": When declining an off-topic request
+    IMPORTANT: You must return your response as a JSON object with:
+    - response_type: MUST be one of "text", "word_suggestion", "save_confirmation", or "error"
+      For translation responses, use "text"
+    - content: Your response text
+    - tool_calls: Optional list of tool calls (e.g., save_word_pair)
   expected_output: >
-    A JSON object with response_type, content, optional data (for word suggestions),
-    and optional tool_calls (for saving words).
-  agent: router_agent
+    A JSON object with response_type (use "text" for translations), content, and optional tool_calls.
+  agent: translation_agent
+  depends_on: route_task
+  context_mapping:
+    user_request: "{route_task.user_request}"
+    target_language: "{target_language}"
+    user_context: "{user_context}"
+
+vocabulary_task:
+  description: >
+    Suggest a new vocabulary word for the user to learn.
+
+    User request: {user_request}
+    Target language: {target_language}
+    User context: {user_context}
+
+    Your task:
+    1. Select an appropriate vocabulary word based on the target language
+    2. Provide the word, its translation, and an example sentence
+    3. Make the word practical and useful for language learners
+    4. Include a tool_call for "save_word_pair" to add the word to their deck
+
+    You have access to the save_word_pair tool which can save word pairs
+    to the user's flashcard deck. Always use it for vocabulary suggestions.
+
+    Return your response as a JSON object with response_type="word_suggestion",
+    data containing word/translation/example, and tool_calls for saving the word.
+  expected_output: >
+    A JSON object with response_type="word_suggestion", data with word details,
+    and tool_calls for saving the word to the flashcard deck.
+  agent: vocabulary_agent
+  depends_on: route_task
+  context_mapping:
+    user_request: "{route_task.user_request}"
+    target_language: "{target_language}"
+    user_context: "{user_context}"
diff --git a/ai/src/crews/chat_tutor_crew/crew.py b/ai/src/crews/chat_tutor_crew/crew.py
index b4ad12f..5818b7a 100644
--- a/ai/src/crews/chat_tutor_crew/crew.py
+++ b/ai/src/crews/chat_tutor_crew/crew.py
@@ -1,15 +1,23 @@
 from crewai import Agent, Crew, Process, Task
 from crewai.project import CrewBase, agent, crew, task
 from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List, Optional
+from typing import List, Optional, Dict, Any
 from src.crews.base.llm import DEFAULT_LLM
-from src.crews.chat_tutor_crew.schemas import TutorResponse
+from src.crews.chat_tutor_crew.schemas import TutorResponse, RoutingDecision
 from src.crews.chat_tutor_crew.tools import save_word_pair_tool
 
 
 @CrewBase
 class ChatTutorCrew():
-    """Crew for handling chat interactions with the language tutor"""
+    """Crew for handling chat interactions with the language tutor
+
+    This crew uses a hierarchical routing pattern:
+    1. Router agent analyzes the user's message and determines which specialist to call
+    2. Translation agent handles translation requests and can save word pairs
+    3. Vocabulary agent suggests new words and saves them to the flashcard deck
+
+    Phoenix traces will show the delegation from router to the appropriate specialist.
+    """
     agents: List[BaseAgent]
     tasks: List[Task]
 
@@ -40,6 +48,20 @@ def vocabulary_agent(self) -> Agent:
     def route_task(self) -> Task:
         return Task(
             config=self.tasks_config['route_task'],
+            output_pydantic=RoutingDecision
+        )
+
+    @task
+    def translation_task(self) -> Task:
+        return Task(
+            config=self.tasks_config['translation_task'],
+            output_pydantic=TutorResponse
+        )
+
+    @task
+    def vocabulary_task(self) -> Task:
+        return Task(
+            config=self.tasks_config['vocabulary_task'],
             output_pydantic=TutorResponse
         )
 
@@ -47,6 +69,6 @@ def route_task(self) -> Task:
     def crew(self) -> Crew:
         return Crew(
             agents=self.agents,
-            tasks=self.tasks,
+            tasks=[self.route_task()],  # Start with routing only
             process=Process.sequential
         )
diff --git a/ai/src/crews/chat_tutor_crew/schemas.py b/ai/src/crews/chat_tutor_crew/schemas.py
index f392eaf..b2749cf 100644
--- a/ai/src/crews/chat_tutor_crew/schemas.py
+++ b/ai/src/crews/chat_tutor_crew/schemas.py
@@ -22,3 +22,18 @@ class TutorResponse(BaseModel):
         None,
         description="List of tool calls the agent wants to make"
     )
+
+
+class RoutingDecision(BaseModel):
+    """Output from the router agent indicating which specialist should handle the request"""
+    should_respond: bool = Field(description="Whether the request is language-related and should be handled")
+    agent: Optional[Literal["translation", "vocabulary"]] = Field(
+        None,
+        description="Which specialist agent should handle the request"
+    )
+    rejection_reason: Optional[str] = Field(
+        None,
+        description="Reason for declining if should_respond is false"
+    )
+    user_request: str = Field(description="Summary of the user's original request")
+    context_for_agent: str = Field(description="Detailed context for the specialized agent")

From 2fd01ae895ed641de879ec5b12b206d40d764dc6 Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 13:49:25 +0100
Subject: [PATCH 09/10] Fix callback-based routing for single Phoenix trace
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Clean up unused Crew, Process imports from run.py
- Callback routing in crew.py creates single trace showing router → specialist chain
- Agents now execute sequentially in one crew instance instead of separate instances
---
 ai/run.py                            | 99 ++++++++++------------------
 ai/src/crews/chat_tutor_crew/crew.py | 55 ++++++++++++----
 2 files changed, 78 insertions(+), 76 deletions(-)

diff --git a/ai/run.py b/ai/run.py
index 95e83e8..5fd9a0f 100644
--- a/ai/run.py
+++ b/ai/run.py
@@ -8,7 +8,6 @@
 from flask import Flask, request, jsonify
 from flask_cors import CORS
 from supabase import create_client, Client
-from crewai import Crew, Process
 
 from src.crews.random_phrase_crew.crew import RandomPhraseCrew
 from src.crews.random_phrase_crew.schemas import PhraseOutput
@@ -519,7 +518,9 @@ async def send_chat_message():
                 content_str = str(content)
             history_text += f"{role.capitalize()}: {content_str}\n"
 
-        # Run the ChatTutorCrew with user_id for tool context
+        # Run the ChatTutorCrew with conditional routing
+        # The crew's callback will handle routing to the appropriate specialist
+        # This creates a single Phoenix trace showing: router → specialist chain
         inputs = {
             'user_message': message,
             'target_language': target_language if target_language else "None",
@@ -528,78 +529,46 @@ async def send_chat_message():
             'user_id': user_id  # Pass user_id so tools can access it
         }
 
-        # Step 1: Run the router task to determine which specialist should handle the request
         crew_instance = ChatTutorCrew()
-        routing_result = await crew_instance.crew().kickoff_async(inputs=inputs)
-
-        if not hasattr(routing_result, 'pydantic'):
-            raise Exception("Router task did not return a pydantic model")
-
-        routing_decision: RoutingDecision = routing_result.pydantic
-        logger.info(f"Router decision: should_respond={routing_decision.should_respond}, agent={routing_decision.agent}")
-
-        # Step 2: Based on routing decision, execute the appropriate specialist task
-        tutor_response: TutorResponse
-
-        if not routing_decision.should_respond:
-            # Router declined the request
-            tutor_response = TutorResponse(
-                response_type="error",
-                content=routing_decision.rejection_reason or "I can only help with language-related questions.",
-                data=None,
-                tool_calls=None
-            )
-        elif routing_decision.agent == "translation":
-            # Run translation task - this will show as a separate trace in Phoenix
-            translation_inputs = {
-                **inputs,
-                'user_request': routing_decision.user_request,
-            }
-            # Use a separate crew instance with just the translation task
-            translation_crew = Crew(
-                agents=[crew_instance.translation_agent()],
-                tasks=[crew_instance.translation_task()],
-                process=Process.sequential
-            )
-            translation_result = await translation_crew.kickoff_async(inputs=translation_inputs)
-
-            if hasattr(translation_result, 'pydantic'):
-                tutor_response = translation_result.pydantic
-            else:
-                tutor_response = TutorResponse(
-                    response_type="text",
-                    content=str(translation_result),
-                    data=None,
-                    tool_calls=None
-                )
-        elif routing_decision.agent == "vocabulary":
-            # Run vocabulary task - this will show as a separate trace in Phoenix
-            vocabulary_inputs = {
-                **inputs,
-                'user_request': routing_decision.user_request,
-            }
-            # Use a separate crew instance with just the vocabulary task
-            vocabulary_crew = Crew(
-                agents=[crew_instance.vocabulary_agent()],
-                tasks=[crew_instance.vocabulary_task()],
-                process=Process.sequential
-            )
-            vocabulary_result = await vocabulary_crew.kickoff_async(inputs=vocabulary_inputs)
-
-            if hasattr(vocabulary_result, 'pydantic'):
-                tutor_response = vocabulary_result.pydantic
+        result = await crew_instance.crew().kickoff_async(inputs=inputs)
+
+        # Extract the final response from the last executed task
+        if hasattr(result, 'pydantic'):
+            # The result could be either RoutingDecision (if declined) or TutorResponse (if specialist ran)
+            result_model = result.pydantic
+
+            # Handle rejection from router
+            if isinstance(result_model, RoutingDecision):
+                if not result_model.should_respond:
+                    tutor_response = TutorResponse(
+                        response_type="error",
+                        content=result_model.rejection_reason or "I can only help with language-related questions.",
+                        data=None,
+                        tool_calls=None
+                    )
+                else:
+                    # Router returned a decision but no specialist was executed
+                    # This shouldn't happen with callback routing, but handle gracefully
+                    tutor_response = TutorResponse(
+                        response_type="error",
+                        content="I couldn't determine how to help with that request.",
+                        data=None,
+                        tool_calls=None
+                    )
+            elif isinstance(result_model, TutorResponse):
+                tutor_response = result_model
             else:
                 tutor_response = TutorResponse(
                     response_type="text",
-                    content=str(vocabulary_result),
+                    content=str(result_model),
                     data=None,
                     tool_calls=None
                 )
         else:
-            # Fallback - router didn't specify an agent
+            # Fallback for unexpected result format
             tutor_response = TutorResponse(
-                response_type="error",
-                content="I couldn't determine how to help with that request.",
+                response_type="text",
+                content=str(result),
                 data=None,
                 tool_calls=None
             )
diff --git a/ai/src/crews/chat_tutor_crew/crew.py b/ai/src/crews/chat_tutor_crew/crew.py
index 5818b7a..9b85811 100644
--- a/ai/src/crews/chat_tutor_crew/crew.py
+++ b/ai/src/crews/chat_tutor_crew/crew.py
@@ -1,7 +1,7 @@
-from crewai import Agent, Crew, Process, Task
+from crewai import Agent, Crew, Process, Task, Callback
 from crewai.project import CrewBase, agent, crew, task
 from crewai.agents.agent_builder.base_agent import BaseAgent
-from typing import List, Optional, Dict, Any
+from typing import List, Optional, Dict, Any, Union
 from src.crews.base.llm import DEFAULT_LLM
 from src.crews.chat_tutor_crew.schemas import TutorResponse, RoutingDecision
 from src.crews.chat_tutor_crew.tools import save_word_pair_tool
@@ -11,12 +11,14 @@
 class ChatTutorCrew():
     """Crew for handling chat interactions with the language tutor
 
-    This crew uses a hierarchical routing pattern:
-    1. Router agent analyzes the user's message and determines which specialist to call
-    2. Translation agent handles translation requests and can save word pairs
-    3. Vocabulary agent suggests new words and saves them to the flashcard deck
+    This crew uses a conditional routing pattern where the router agent
+    determines which specialist agent should handle the request:
+    1. Router Agent (route_task) - Analyzes user message and determines intent
+    2. Translation Agent (translation_task) - Handles translations and grammar
+    3. Vocabulary Agent (vocabulary_task) - Suggests new vocabulary words
 
-    Phoenix traces will show the delegation from router to the appropriate specialist.
+    Phoenix traces will show the complete chain: router → specialist
+    in a single trace with clear delegation.
     """
     agents: List[BaseAgent]
     tasks: List[Task]
@@ -48,27 +50,58 @@ def vocabulary_agent(self) -> Agent:
     def route_task(self) -> Task:
         return Task(
             config=self.tasks_config['route_task'],
-            output_pydantic=RoutingDecision
+            output_pydantic=RoutingDecision,
+            callback=self._route_callback
         )
 
     @task
     def translation_task(self) -> Task:
         return Task(
             config=self.tasks_config['translation_task'],
-            output_pydantic=TutorResponse
+            output_pydantic=TutorResponse,
+            agent=self.translation_agent
         )
 
     @task
     def vocabulary_task(self) -> Task:
         return Task(
             config=self.tasks_config['vocabulary_task'],
-            output_pydantic=TutorResponse
+            output_pydantic=TutorResponse,
+            agent=self.vocabulary_agent
         )
 
+    def _route_callback(self, output: Union[str, RoutingDecision]) -> List[Task]:
+        """
+        Callback function that determines which specialist task to run next
+        based on the router's decision.
+
+        This is the key to the conditional routing pattern - it allows the router
+        to dynamically delegate to the appropriate specialist.
+        """
+        # Parse the routing decision
+        if isinstance(output, str):
+            import json
+            output = json.loads(output)
+
+        # If router declined, return no further tasks
+        if not output.get('should_respond', False):
+            return []
+
+        # Route to the appropriate specialist
+        agent = output.get('agent')
+
+        if agent == 'translation':
+            return [self.translation_task()]
+        elif agent == 'vocabulary':
+            return [self.vocabulary_task()]
+        else:
+            # No specific agent specified - default to translation
+            return [self.translation_task()]
+
     @crew
     def crew(self) -> Crew:
         return Crew(
             agents=self.agents,
-            tasks=[self.route_task()],  # Start with routing only
+            tasks=self.tasks,
             process=Process.sequential
         )

From 1e9679718f1a6677f63931e416f9b2e3eb68653e Mon Sep 17 00:00:00 2001
From: Alexander Zarzhitski <alexander.zarzhitski@sqldbm.com>
Date: Mon, 16 Feb 2026 16:08:15 +0100
Subject: [PATCH 10/10] Fix chat sidebar button visibility and layout

- Change buttons from hidden to always visible (50% opacity)
- Move Rename and Delete buttons to beginning of row
- Buttons become fully visible on hover
---
 web/src/components/chat/chat-sidebar.tsx | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/web/src/components/chat/chat-sidebar.tsx b/web/src/components/chat/chat-sidebar.tsx
index 09a8158..2ba886e 100644
--- a/web/src/components/chat/chat-sidebar.tsx
+++ b/web/src/components/chat/chat-sidebar.tsx
@@ -139,18 +139,10 @@ export function ChatSidebar({
                 ) : (
                   // View mode
                   <>
-                    <button
-                      onClick={() => onSelectChat(chat.id)}
-                      onDoubleClick={() => startEditing(chat)}
-                      className="flex-1 truncate text-left"
-                      title={chat.title || 'New Chat'}
-                    >
-                      {chat.title || 'New Chat'}
-                    </button>
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
+                      className="h-6 w-6 opacity-50 hover:opacity-100 transition-opacity"
                       onClick={(e) => {
                         e.stopPropagation()
                         startEditing(chat)
@@ -162,7 +154,7 @@ export function ChatSidebar({
                     <Button
                       variant="ghost"
                       size="icon"
-                      className="h-6 w-6 opacity-0 transition-opacity group-hover:opacity-100"
+                      className="h-6 w-6 opacity-50 hover:opacity-100 transition-opacity"
                       onClick={(e) => {
                         e.stopPropagation()
                         onDeleteChat(chat.id)
@@ -171,6 +163,14 @@ export function ChatSidebar({
                     >
                       <IconTrash className="h-3 w-3" />
                     </Button>
+                    <button
+                      onClick={() => onSelectChat(chat.id)}
+                      onDoubleClick={() => startEditing(chat)}
+                      className="flex-1 truncate text-left"
+                      title={chat.title || 'New Chat'}
+                    >
+                      {chat.title || 'New Chat'}
+                    </button>
                   </>
                 )}
               </div>