Deploy PuppyCompanion FastAPI 2025-06-02 09:57:27

.hf_force_rebuild

@@ -0,0 +1 @@
+# Force rebuild Lun  2 jui 2025 09:55:15 CEST

Dockerfile

@@ -0,0 +1,81 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install required system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    software-properties-common \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy configuration files first to optimize Docker cache
+COPY pyproject.toml README.md ./
+
+# Upgrade pip and install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip
+RUN pip install --no-cache-dir -e .
+
+# Check critical imports
+RUN python -c "from langchain_qdrant import QdrantVectorStore; print('✅ Qdrant successfully imported')"
+RUN python -c "from fastapi import FastAPI; print('✅ FastAPI successfully imported')"
+RUN python -c "import uvicorn; print('✅ Uvicorn successfully imported')"
+
+# Create necessary directories with correct permissions
+RUN mkdir -p /app/static && \
+    mkdir -p /tmp/qdrant_storage && \
+    mkdir -p /tmp/cache && \
+    chmod -R 777 /tmp/qdrant_storage && \
+    chmod -R 777 /tmp/cache
+
+# Copy application files
+COPY main.py .
+COPY rag_system.py .
+COPY agent_workflow.py .
+COPY embedding_models.py .
+COPY books_config.json .
+
+# Copy the static directory with the interface
+COPY static/ ./static/
+
+# Copy the chunks file to the root
+COPY all_books_preprocessed_chunks.json .
+
+# Check for the presence of the chunks file at the root
+RUN if [ -f "all_books_preprocessed_chunks.json" ]; then \
+        echo "✅ Chunks file found at all_books_preprocessed_chunks.json"; \
+        echo "📊 File size: $(du -h all_books_preprocessed_chunks.json)"; \
+    else \
+        echo "⚠️ Warning: all_books_preprocessed_chunks.json not found at root"; \
+        echo "📁 Contents of root directory:"; \
+        ls -la *.json || echo "No JSON files found"; \
+    fi
+
+# Ensure all files have correct permissions
+RUN chmod -R 755 /app
+RUN chmod +x main.py
+
+# Expose the port for FastAPI
+EXPOSE 7860
+
+# Environment variables for FastAPI and Hugging Face Spaces
+ENV PYTHONPATH="/app:$PYTHONPATH"
+ENV UVICORN_HOST="0.0.0.0"
+ENV UVICORN_PORT="7860"
+ENV UVICORN_LOG_LEVEL="info"
+
+# Variables to optimize performance
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Variables for cache management
+ENV MAX_CACHE_SIZE_MB=500
+ENV MAX_CACHE_AGE_DAYS=7
+
+# Healthcheck to verify the application is responding
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Command to launch the FastAPI application
+CMD ["python", "main.py"] 

README.md

@@ -1,10 +1,99 @@
+# Fichier README.md pour Hugging Face Spaces
+# À placer à la racine de votre Space
+
 ---
-title: Puppycompanion V3
-emoji: 🔥
-colorFrom: gray
-colorTo: green
+title: PuppyCompanion
+emoji: 🐶
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
+app_port: 7860
+---
+
+# PuppyCompanion 🐶
+
+An intelligent AI assistant specialized in puppy care and training, powered by advanced RAG (Retrieval-Augmented Generation) technology and a modern FastAPI backend.
+
+## Features
+
+- **🐕 Specialized Knowledge Base**: Expert information from professional canine care resources
+- **🧠 Smart Agent Workflow**: LangGraph-powered decision making with tool selection
+- **🔍 Dual Search System**: 
+  - RAG system for specialized puppy knowledge from preprocessed chunks
+  - Web search integration via Tavily for up-to-date information
+- **📱 Modern Mobile-like Interface**: Responsive web interface with real-time updates
+- **🔧 Real-time Debug Console**: Watch the AI's decision process in real-time
+- **⚡ FastAPI Backend**: High-performance async API with WebSocket support
+- **📊 Detailed Source Attribution**: Shows exactly which knowledge sources were used
+
+## How it Works
+
+1. **Question Analysis**: The agent workflow analyzes your question and selects appropriate tools
+2. **RAG Search**: For dog-related questions, searches the specialized knowledge base using Qdrant vector database
+3. **Quality Evaluation**: Determines if the RAG response is comprehensive enough
+4. **Web Search Fallback**: If needed, uses Tavily to search for additional current information
+5. **Response Generation**: Combines knowledge sources to provide a comprehensive answer
+6. **Real-time Updates**: All processing steps are visible in the debug console via WebSocket
+
+## Usage
+
+Simply ask any question about puppy care, training, behavior, or health. Examples:
+- "How do I house train my 8-week-old puppy?"
+- "What vaccination schedule should I follow?"
+- "How to stop my puppy from biting furniture?"
+- "Best foods for a growing German Shepherd puppy?"
+
+## Technology Stack
+
+- **FastAPI**: Modern async web framework for the API backend
+- **LangGraph**: Agent workflow orchestration and tool selection
+- **OpenAI GPT-4**: Language model for natural language processing
+- **Qdrant**: Vector database for document embeddings and similarity search
+- **OpenAI Embeddings**: Text embeddings for semantic search
+- **Tavily**: Web search integration for real-time information
+- **WebSocket**: Real-time communication for debug console
+- **Docker**: Containerized deployment for HuggingFace Spaces
+
+## Configuration
+
+The application requires these environment variables:
+
+### Required
+- `OPENAI_API_KEY`: Your OpenAI API key for LLM processing and embeddings
+
+### Optional
+- `TAVILY_API_KEY`: For web search functionality (highly recommended)
+
+**⚠️ Important**: Configure these as secrets in your HuggingFace Space settings:
+1. Go to your space settings
+2. Add the API keys in the "Repository secrets" section
+3. Never commit API keys to your repository
+
+## Knowledge Base
+
+The application uses a preprocessed knowledge base of professional puppy care resources:
+- **File**: `all_books_preprocessed_chunks.json` (2.5MB)
+- **Content**: Chunked and processed expert knowledge about puppy training, health, and behavior
+- **Vector Store**: Automatically indexed in Qdrant on first startup
+
+## API Endpoints
+
+- `GET /`: Main web interface
+- `POST /chat`: Chat API endpoint for programmatic access
+- `WebSocket /ws`: Real-time debug console connection
+- `GET /health`: Application health check
+
+## Development
+
+The application features:
+- **Async Architecture**: Full async/await support for optimal performance  
+- **Persistent Vector Store**: Qdrant storage persists between restarts
+- **Connection Management**: WebSocket connection handling for multiple users
+- **Error Handling**: Comprehensive error handling and logging
+- **Health Monitoring**: Built-in health checks and monitoring
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+*Transform the chaos of new puppy ownership into confidence with AI-powered expert assistance!* 🐾

agent_workflow.py

@@ -0,0 +1,392 @@
+# agent_workflow.py
+import logging
+from typing import Dict, List, Any, Annotated, TypedDict
+
+from langchain_openai import ChatOpenAI
+from langchain_core.documents import Document
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
+from langchain_community.tools.tavily_search import TavilySearchResults
+
+from langgraph.graph import StateGraph, START, END
+from langgraph.graph.message import add_messages
+
+# Logging configuration
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class AgentState(TypedDict):
+    """Agent state for the workflow"""
+    messages: Annotated[list, add_messages]
+    context: List[Document]
+    next_tool: str
+    question: str
+    retrieved_contexts: List[Document]
+    context_count: int   
+
+class AgentWorkflow:
+    """Agent workflow with intelligent routing logic"""
+    
+    def __init__(self, rag_tool, tavily_max_results: int = 5):
+        """ Initialize the agent workflow """
+        self.rag_tool = rag_tool
+        self.tavily_tool = TavilySearchResults(max_results=tavily_max_results)
+        
+        # LLMs for routing and evaluation
+        self.router_llm = ChatOpenAI(model="gpt-4o-mini", temperature=0, max_tokens=50)
+        self.evaluator_llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+        self.final_llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)
+        
+        # Compile the workflow
+        self.compiled_workflow = self._build_workflow()
+    
+    def evaluate_response_quality(self, question: str, response: str) -> bool:
+        """ Evaluates if the response is satisfactory """
+        prompt = f"""Evaluate if this response to "{question}" is UNSATISFACTORY:
+
+        "{response}"
+
+        UNSATISFACTORY CRITERIA (if ANY ONE is present, the response is UNSATISFACTORY):
+        1. Contains "consult experts", "specialized training", "I'm sorry"
+        2. Doesn't provide concrete steps for "how to" questions
+        3. Gives general advice rather than specific methods
+        4. Redirects the user without directly answering
+
+        Quick example:
+        Q: "How do I train my dog to sit?"
+        UNSATISFACTORY: "Consult a professional trainer."
+        SATISFACTORY: "1. Use treats... 2. Be consistent..."
+
+        Reply only "UNSATISFACTORY" or "SATISFACTORY".
+        When in doubt, choose "UNSATISFACTORY".
+        """
+        
+        evaluation = self.evaluator_llm.invoke([SystemMessage(content=prompt)])
+        result = evaluation.content.strip().upper()
+        
+        is_satisfactory = "UNSATISFACTORY" not in result
+        logger.info(f"[Evaluation] Response rated: {'SATISFACTORY' if is_satisfactory else 'UNSATISFACTORY'}")
+        
+        return is_satisfactory
+    
+    def _build_workflow(self):
+        """Builds and compiles the agent workflow"""
+        
+        # 1. Node for intelligent routing
+        def smart_router(state):
+            """Determines if the question is about dogs or not"""
+            messages = state["messages"]
+            last_message = [msg for msg in messages if isinstance(msg, HumanMessage)][-1]
+            question = last_message.content
+            
+            # Prompt using reverse logic - asking if it's NOT related to dogs
+            router_prompt = f"""Evaluate if this question is UNRELATED to dogs, puppies, or canine care:
+
+            Question: "{question}"
+
+            INDICATORS OF NON-DOG QUESTIONS (if ANY ONE is present, mark as "NOT_DOG_RELATED"):
+            1. Questions about weather, time, locations, or general information
+            2. Questions about other animals (cats, birds, etc.)
+            3. Questions about technology, politics, or human activities
+            4. Any question that doesn't explicitly mention or imply dogs/puppies/canines
+
+            Example check:
+            Q: "What is the weather in Paris today?"
+            This is NOT_DOG_RELATED (about weather)
+
+            Q: "How do I train my puppy to sit?"
+            This is DOG_RELATED (explicitly about puppy training)
+
+            Reply ONLY with "NOT_DOG_RELATED" or "DOG_RELATED".
+            When in doubt, choose "NOT_DOG_RELATED".
+            """
+            
+            router_response = self.router_llm.invoke([SystemMessage(content=router_prompt)])
+            result = router_response.content.strip().upper()
+            
+            is_dog_related = "NOT_DOG_RELATED" not in result
+            logger.info(f"[Smart Router] Question {'' if is_dog_related else 'NOT '}related to dogs")
+            
+            # If the question is not related to dogs, go directly to out_of_scope
+            if not is_dog_related:
+                return {
+                    "next_tool": "out_of_scope",
+                    "question": question
+                }
+            
+            # If the question is related to dogs, go to the RAG tool
+            return {
+                "next_tool": "rag_tool",
+                "question": question
+            }
+        
+        # 2. Node for out-of-scope questions
+        def out_of_scope(state):
+            """Informs that the assistant only answers questions about dogs"""
+            out_of_scope_message = AIMessage(
+                content="I'm sorry, but I specialize only in canine care and puppy education. I cannot answer this question as it is outside my area of expertise. Feel free to ask me any questions about dogs and puppies!"
+            )
+            
+            return {
+                "messages": [out_of_scope_message],
+                "next_tool": "final_response"
+            }
+        
+        # 3. Node for using the RAG tool
+        def use_rag_tool(state):
+            """Uses the RAG tool for dog-related questions"""
+            question = state["question"]
+            
+            # Call the RAG tool directly
+            rag_result = self.rag_tool.invoke(question)
+            rag_response = rag_result["messages"][0].content
+            context = rag_result.get("context", [])
+            sources_info = rag_result.get("sources_info", [])
+            total_chunks = rag_result.get("total_chunks", 0)
+            
+            # Evaluate the quality of the response
+            is_satisfactory = self.evaluate_response_quality(question, rag_response)
+            
+            # Format detailed source information
+            sources_text = ""
+            if sources_info:
+                sources_text = f"*Based on {total_chunks} chunk(s):*\n"
+                for source in sources_info:
+                    sources_text += f"- *Chunk {source['chunk_number']} - {source['source']} (Page: {source['page']})*\n"
+            else:
+                sources_text = "*Source: Livre \"Puppies for Dummies\"*"
+            
+            # Create an AI message with the response and detailed sources
+            response_message = AIMessage(content=f"[Using RAG tool] - {sources_text}\n{rag_response}")
+            
+            # If the response is not satisfactory, prepare to use Tavily
+            next_tool = "final_response" if is_satisfactory else "need_tavily"
+            
+            return {
+                "messages": [response_message],
+                "context": context,
+                "sources_info": sources_info,
+                "next_tool": next_tool,
+                "retrieved_contexts": context,
+                "context_count": len(context)
+            }
+        
+        # 4. Node for using the Tavily tool
+        def use_tavily_tool(state):
+            """Uses the Tavily tool as a fallback for dog-related questions"""
+            question = state["question"]
+            
+            # Call Tavily
+            tavily_result = self.tavily_tool.invoke(question)
+            
+            # Format the sources and prepare content for LLM
+            sources_text = ""
+            sources_content = ""
+            has_useful_results = False
+            
+            if tavily_result and len(tavily_result) > 0:
+                sources_text = f"*Based on {len(tavily_result[:3])} internet source(s):*\n"
+                
+                for i, result in enumerate(tavily_result[:3], 1):
+                    title = result.get('title', 'Unknown Source')
+                    url = result.get('url', '')
+                    content = result.get('content', '')
+                    
+                    if content and len(content.strip()) > 50:
+                        has_useful_results = True
+                        # Format source in italics
+                        domain = url.split('/')[2] if url and '/' in url else 'Web'
+                        sources_text += f"- *Source {i} - {domain}: {title}*\n"
+                        # Collect content for LLM processing
+                        sources_content += f"Source {i} ({title}): {content[:300]}...\n\n"
+            
+            if not has_useful_results:
+                # No useful results found
+                dont_know_message = AIMessage(
+                    content=f"[Using Tavily tool] - *No reliable internet sources found for this question.*\n\nI couldn't find specific information about '{question}' in my knowledge base or through online searches. This might be a specialized topic that requires expertise from professionals in the field of canine education."
+                )
+                return {
+                    "messages": [dont_know_message],
+                    "next_tool": "final_response"
+                }
+            
+            # Generate a proper response using LLM based on the sources
+            response_prompt = f"""Based on the following internet sources, provide a clear and helpful answer to the question: "{question}"
+
+            {sources_content}
+
+            Instructions:
+            - Provide a comprehensive answer based on the sources above
+            - Focus on practical, actionable information
+            - If the sources contain contradictory information, mention the different perspectives
+            - Keep the response clear and well-structured
+            - Do not mention the sources in your response (they will be displayed separately)
+            """
+            
+            try:
+                llm_response = self.final_llm.invoke([SystemMessage(content=response_prompt)])
+                generated_answer = llm_response.content
+            except Exception as e:
+                logger.error(f"Error generating Tavily response: {e}")
+                generated_answer = "I found some relevant information but couldn't process it properly."
+            
+            # Create the final formatted message
+            response_message = AIMessage(content=f"[Using Tavily tool] - {sources_text}\n{generated_answer}")
+            
+            return {
+                "messages": [response_message],
+                "next_tool": "final_response"
+            }
+        
+        # 5. Node for cases where no source has a satisfactory answer
+        def say_dont_know(state):
+            """Responds when no source has useful information"""
+            question = state["question"]
+            
+            dont_know_message = AIMessage(content=f"I'm sorry, but I couldn't find specific information about '{question}' in my knowledge base or through online searches. This might be a specialized topic that requires expertise from professionals in the field of canine education.")
+            
+            return {
+                "messages": [dont_know_message],
+                "next_tool": "final_response"
+            }
+        
+        # 6. Node for generating the final response
+        def generate_final_response(state):
+            """Generates a final response based on tool results"""
+            messages = state["messages"]
+            original_question = state["question"]
+            
+            # Find tool messages
+            tool_responses = [msg.content for msg in messages if isinstance(msg, AIMessage)]
+            
+            # If no tool messages, return a default response
+            if not tool_responses:
+                return {"messages": [AIMessage(content="I couldn't find information about your dog-related question.")]}
+            
+            # Take the last tool message as the main content
+            tool_content = tool_responses[-1]
+            
+            # If the tool message already contains detailed sources, return it as-is
+            if "[Using RAG tool]" in tool_content or "[Using Tavily tool]" in tool_content:
+                # Already contains detailed sources, return as-is
+                return {"messages": [AIMessage(content=tool_content)]}
+            
+            # Use an LLM to generate a coherent final response but preserve source markers
+            system_prompt = f"""Here are the search results for the dog-related question: "{original_question}"
+
+            {tool_content}
+
+            Formulate a clear, helpful, and concise response based ONLY on these results.
+            IMPORTANT: If the search results start with "[Using RAG tool]" or "[Using Tavily tool]", keep these markers exactly as they are at the beginning of your response.
+            If the search results contain useful information, include it in your response rather than saying "I don't know".
+            Say "I don't know" only if the search results contain no useful information.
+            """
+            
+            response = self.final_llm.invoke([SystemMessage(content=system_prompt)])
+            
+            return {"messages": [response]}
+        
+        # 7. Routing function
+        def route_to_next_tool(state):
+            next_tool = state["next_tool"]
+            
+            if next_tool == "rag_tool":
+                return "use_rag_tool"
+            elif next_tool == "out_of_scope": 
+                return "out_of_scope"
+            elif next_tool == "tavily_tool":
+                return "use_tavily_tool"
+            elif next_tool == "need_tavily":
+                return "use_tavily_tool"
+            elif next_tool == "say_dont_know":
+                return "say_dont_know"
+            elif next_tool == "final_response":
+                return "generate_response"
+            else:
+                return "generate_response"
+        
+        # 8. Building the LangGraph
+        workflow = StateGraph(AgentState)
+        
+        # Adding nodes
+        workflow.add_node("smart_router", smart_router)
+        workflow.add_node("out_of_scope", out_of_scope)
+        workflow.add_node("use_rag_tool", use_rag_tool)
+        workflow.add_node("use_tavily_tool", use_tavily_tool)
+        workflow.add_node("say_dont_know", say_dont_know)
+        workflow.add_node("generate_response", generate_final_response)
+        
+        # Connections
+        workflow.add_edge(START, "smart_router")
+        workflow.add_conditional_edges("smart_router", route_to_next_tool)
+        workflow.add_edge("out_of_scope", "generate_response")
+        workflow.add_conditional_edges("use_rag_tool", route_to_next_tool)
+        workflow.add_conditional_edges("use_tavily_tool", route_to_next_tool)
+        workflow.add_edge("say_dont_know", "generate_response")
+        workflow.add_edge("generate_response", END)
+        
+        # Compile the graph
+        return workflow.compile()
+    
+    def process_question(self, question: str):
+        """ Process a question with the agent workflow """
+        # Invoke the workflow
+        result = self.compiled_workflow.invoke({
+            "messages": HumanMessage(content=question),
+            "context": [],
+            "next_tool": "",
+            "question": "",
+            "retrieved_contexts": [],
+            "context_count": 0
+        })
+        
+        return result
+    
+    def get_final_response(self, result):
+        """Extract the final response from the agent result with source information."""
+        messages = result.get("messages", [])
+        
+        if not messages:
+            return "No response available."
+        
+        # Get the last AI message
+        last_message = None
+        for msg in reversed(messages):
+            if hasattr(msg, 'content') and msg.content:
+                last_message = msg
+                break
+        
+        if not last_message:
+            return "No valid response found."
+        
+        response_content = last_message.content
+        
+        # Extract and store source information in result for main.py to use
+        if "Tavily" in response_content and "Source" in response_content:
+            # Extract Tavily sources from the response content
+            tavily_sources = []
+            lines = response_content.split('\n')
+            
+            for line in lines:
+                if line.strip().startswith('- *Source') and ':' in line:
+                    # Parse line like "- *Source 1 - domain.com: Title*"
+                    try:
+                        # Extract source number, domain, and title
+                        source_part = line.split('- *Source')[1].split('*')[0]
+                        if ' - ' in source_part and ':' in source_part:
+                            parts = source_part.split(' - ', 1)
+                            source_num = parts[0].strip()
+                            domain_title = parts[1]
+                            if ':' in domain_title:
+                                domain, title = domain_title.split(':', 1)
+                                tavily_sources.append({
+                                    'source_num': source_num,
+                                    'domain': domain.strip(),
+                                    'title': title.strip()
+                                })
+                    except:
+                        continue
+            
+            # Store Tavily sources in result
+            result['tavily_sources'] = tavily_sources
+        
+        return response_content

books_config.json

@@ -0,0 +1,46 @@
+{
+  "books": [
+    {
+      "filename": "HowtoRaisethePerfectDog.pdf",
+      "start_page": 15,
+      "end_page": 94,
+      "title": "How to Raise the Perfect Dog",
+      "description": "Guide for raising the perfect dog"
+    },
+    {
+      "filename": "OnTalkingTermsWithDogsCalmingSignal.pdf",
+      "start_page": 6,
+      "end_page": 169,
+      "title": "On Talking Terms With Dogs - Calming Signals",
+      "description": "Dog communication and calming signals"
+    },
+    {
+      "filename": "PerfectPuppyin7Days.pdf",
+      "start_page": 15,
+      "end_page": 260,
+      "title": "Perfect Puppy in 7 Days",
+      "description": "Guide for perfect puppy in 7 days"
+    },
+    {
+      "filename": "PuppiesForDummies.pdf",
+      "start_page": 9,
+      "end_page": 385,
+      "title": "Puppies For Dummies",
+      "description": "Complete guide for puppies"
+    },
+    {
+      "filename": "TheDoNoHarm DogTrainingandBehaviorHanbook.pdf",
+      "start_page": 34,
+      "end_page": 381,
+      "title": "The Do No Harm Dog Training and Behavior Handbook",
+      "description": "Non-violent dog training and behavior manual"
+    },
+    {
+      "filename": "DoNotShoottheDog.pdf",
+      "start_page": 6,
+      "end_page": 169,
+      "title": "Don't Shoot the Dog",
+      "description": "Positive training methods"
+    }
+  ]
+}

embedding_models.py

@@ -0,0 +1,236 @@
+# embedding_models.py
+import hashlib
+import logging
+import os
+import shutil
+import time
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from langchain_openai import OpenAIEmbeddings
+from langchain_core.documents import Document
+from langchain_qdrant import QdrantVectorStore
+from langchain.storage import LocalFileStore
+from langchain.embeddings import CacheBackedEmbeddings
+import qdrant_client
+from qdrant_client.http.models import Distance, VectorParams
+
+# Logging configuration
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class CacheManager:
+    """Cache manager with limits for Hugging Face Spaces"""
+    
+    def __init__(self, cache_directory: str = "./cache", max_size_mb: int = 500, max_age_days: int = 7):
+        self.cache_directory = Path(cache_directory)
+        self.max_size_bytes = max_size_mb * 1024 * 1024  # Convert to bytes
+        self.max_age_seconds = max_age_days * 24 * 60 * 60  # Convert to seconds
+        
+    def get_cache_size(self) -> int:
+        """Compute the total cache size in bytes"""
+        total_size = 0
+        if self.cache_directory.exists():
+            for file_path in self.cache_directory.rglob('*'):
+                if file_path.is_file():
+                    total_size += file_path.stat().st_size
+        return total_size
+    
+    def get_cache_size_mb(self) -> float:
+        """Return the cache size in MB"""
+        return self.get_cache_size() / (1024 * 1024)
+    
+    def clean_old_files(self):
+        """Delete cache files that are too old"""
+        if not self.cache_directory.exists():
+            return
+            
+        current_time = time.time()
+        deleted_count = 0
+        
+        for file_path in self.cache_directory.rglob('*'):
+            if file_path.is_file():
+                file_age = current_time - file_path.stat().st_mtime
+                if file_age > self.max_age_seconds:
+                    try:
+                        file_path.unlink()
+                        deleted_count += 1
+                    except Exception as e:
+                        logger.warning(f"Unable to delete {file_path}: {e}")
+        
+        if deleted_count > 0:
+            logger.info(f"🧹 Cache cleaned: {deleted_count} old files deleted")
+    
+    def clear_cache_if_too_large(self):
+        """Completely clear the cache if it exceeds the size limit"""
+        current_size_mb = self.get_cache_size_mb()
+        
+        if current_size_mb > (self.max_size_bytes / (1024 * 1024)):
+            logger.warning(f"Cache too large ({current_size_mb:.1f}MB > {self.max_size_bytes/(1024*1024)}MB)")
+            try:
+                if self.cache_directory.exists():
+                    shutil.rmtree(self.cache_directory)
+                    self.cache_directory.mkdir(parents=True, exist_ok=True)
+                    logger.info("Cache fully cleared to save disk space")
+            except Exception as e:
+                logger.error(f"Error while clearing cache: {e}")
+    
+    def cleanup_cache(self):
+        """Smart cache cleanup"""
+        # 1. Clean old files
+        self.clean_old_files()
+        
+        # 2. Check size after cleaning
+        current_size_mb = self.get_cache_size_mb()
+        
+        # 3. If still too large, clear completely
+        if current_size_mb > (self.max_size_bytes / (1024 * 1024)):
+            self.clear_cache_if_too_large()
+        else:
+            logger.info(f"Cache size: {current_size_mb:.1f}MB (OK)")
+
+
+class OpenAIEmbeddingModel:
+    """OpenAI embedding model with smart caching for Hugging Face Spaces"""
+    
+    def __init__(self, model_name: str = "text-embedding-3-small", persist_directory: str = "./vector_stores", 
+                 max_cache_size_mb: int = 500, max_cache_age_days: int = 7):
+        self.name = "OpenAI Embeddings (Smart Cache)"
+        self.description = f"OpenAI embedding model {model_name} with smart caching for HF Spaces"
+        self.model_name = model_name
+        self.vector_dim = 1536  # Dimension of OpenAI vectors
+        
+        # Setup directories
+        self.persist_directory = Path(persist_directory)
+        self.persist_directory.mkdir(parents=True, exist_ok=True)
+        self.cache_directory = Path("./cache")
+        self.cache_directory.mkdir(parents=True, exist_ok=True)
+        
+        # Initialize cache manager with limits for HF Spaces
+        self.cache_manager = CacheManager(
+            cache_directory=str(self.cache_directory),
+            max_size_mb=max_cache_size_mb,
+            max_age_days=max_cache_age_days
+        )
+        
+        # Initialize components
+        self.client = None
+        self.vector_store = None
+        self.retriever = None
+        self.embeddings = None
+        
+        self._setup_embeddings()
+    
+    def _setup_embeddings(self):
+        """Setup OpenAI embeddings with smart caching"""
+        # Clean cache before starting
+        logger.info("🔍 Checking cache state...")
+        self.cache_manager.cleanup_cache()
+        
+        # Create base OpenAI embeddings
+        base_embeddings = OpenAIEmbeddings(model=self.model_name)
+        
+        # Create cached version
+        namespace_key = f"openai_{self.model_name}"
+        safe_namespace = hashlib.md5(namespace_key.encode()).hexdigest()
+        
+        # Setup local file store for caching
+        store = LocalFileStore(str(self.cache_directory))
+        
+        # Create cached embeddings
+        self.embeddings = CacheBackedEmbeddings.from_bytes_store(
+            base_embeddings, 
+            store, 
+            namespace=safe_namespace,
+            batch_size=32
+        )
+        
+        cache_size = self.cache_manager.get_cache_size_mb()
+        logger.info(f"[{self.name}] Embeddings configured with smart cache (Size: {cache_size:.1f}MB)")
+    
+    def _collection_exists(self, collection_name: str) -> bool:
+        """Check if a collection already exists"""
+        try:
+            collections = self.client.get_collections()
+            return any(collection.name == collection_name for collection in collections.collections)
+        except Exception as e:
+            logger.warning(f"Error while checking collection {collection_name}: {e}")
+            return False
+    
+    def create_vector_store(self, documents: List[Document], collection_name: str, k: int = 5) -> None:
+        """Create the vector store for documents"""
+        # Path for persistent Qdrant storage - model-specific subdirectory
+        qdrant_path = self.persist_directory / "qdrant_db" / "openai_cached"
+        qdrant_path.mkdir(parents=True, exist_ok=True)
+        
+        # Initialize Qdrant client with persistent storage
+        self.client = qdrant_client.QdrantClient(path=str(qdrant_path))
+        
+        # Check if the collection already exists
+        if self._collection_exists(collection_name):
+            logger.info(f"[{self.name}] Collection '{collection_name}' already exists, loading...")
+            # Load the existing vector store
+            self.vector_store = QdrantVectorStore(
+                client=self.client,
+                collection_name=collection_name,
+                embedding=self.embeddings,
+            )
+        else:
+            logger.info(f"[{self.name}] Creating new collection '{collection_name}'...")
+            # Create a collection
+            self.client.create_collection(
+                collection_name=collection_name,
+                vectors_config=VectorParams(size=self.vector_dim, distance=Distance.COSINE)
+            )
+            
+            # Create the vector store
+            self.vector_store = QdrantVectorStore(
+                client=self.client,
+                collection_name=collection_name,
+                embedding=self.embeddings,
+            )
+            
+            # Add documents (caching will happen automatically)
+            logger.info(f"[{self.name}] Adding {len(documents)} documents (with embedding cache)...")
+            self.vector_store.add_documents(documents=documents)
+            logger.info(f"[{self.name}] Vector store created successfully")
+        
+        # Create the retriever
+        self.retriever = self.vector_store.as_retriever(search_kwargs={"k": k})
+        
+        # Check cache size after adding documents
+        cache_size = self.cache_manager.get_cache_size_mb()
+        if cache_size > 100:  # Alert if > 100MB
+            logger.warning(f"Large cache: {cache_size:.1f}MB - consider cleaning soon")
+    
+    def get_retriever(self):
+        """Returns the retriever"""
+        if self.retriever is None:
+            raise ValueError("The vector store has not been initialized")
+        return self.retriever
+    
+    def get_cache_info(self) -> Dict[str, Any]:
+        """Return information about the cache state"""
+        return {
+            "cache_size_mb": self.cache_manager.get_cache_size_mb(),
+            "max_size_mb": self.cache_manager.max_size_bytes / (1024 * 1024),
+            "max_age_days": self.cache_manager.max_age_seconds / (24 * 60 * 60),
+            "cache_directory": str(self.cache_directory)
+        }
+    
+    def manual_cache_cleanup(self):
+        """Manual cache cleanup"""
+        logger.info("🧹 Manual cache cleanup requested...")
+        self.cache_manager.cleanup_cache()
+
+
+def create_embedding_model(persist_directory: str = "./vector_stores", 
+                          max_cache_size_mb: int = 500, 
+                          max_cache_age_days: int = 7) -> OpenAIEmbeddingModel:
+    
+    logger.info(f"Creating optimized OpenAI model (Max cache: {max_cache_size_mb}MB, Max age: {max_cache_age_days}d)")
+    return OpenAIEmbeddingModel(
+        persist_directory=persist_directory,
+        max_cache_size_mb=max_cache_size_mb,
+        max_cache_age_days=max_cache_age_days
+    )

main.py

@@ -0,0 +1,444 @@
+# main.py - FastAPI version of PuppyCompanion
+import os
+import logging
+import json
+import asyncio
+from datetime import datetime
+from typing import List, Dict, Any
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import HTMLResponse, FileResponse
+from pydantic import BaseModel
+from dotenv import load_dotenv
+
+# Import your existing modules
+from rag_system import RAGSystem
+from agent_workflow import AgentWorkflow
+
+# Load environment variables
+load_dotenv()
+
+# Logging configuration
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# Global variables
+global_agent = None
+global_qdrant_client = None
+global_retriever = None
+global_documents = None
+initialization_completed = False
+
+# Path to preprocessed data
+PREPROCESSED_CHUNKS_PATH = "all_books_preprocessed_chunks.json"
+
+# Pydantic models
+class QuestionRequest(BaseModel):
+    question: str
+
+class ChatResponse(BaseModel):
+    response: str
+    sources: List[Dict[str, Any]] = []
+    tool_used: str = ""
+
+# WebSocket connection manager
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: List[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)
+
+    async def send_log(self, message: str, log_type: str = "info"):
+        timestamp = datetime.now().strftime("%H:%M:%S")
+        log_data = {
+            "timestamp": timestamp,
+            "message": message,
+            "type": log_type
+        }
+        
+        for connection in self.active_connections:
+            try:
+                await connection.send_text(json.dumps(log_data))
+            except:
+                pass
+
+manager = ConnectionManager()
+
+def load_preprocessed_chunks(file_path="all_books_preprocessed_chunks.json"):
+    """Load preprocessed chunks from a JSON file."""
+    global global_documents
+    
+    if global_documents is not None:
+        logger.info("Using cached document chunks")
+        return global_documents
+        
+    logger.info(f"Loading preprocessed chunks from {file_path}")
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+            
+        from langchain_core.documents import Document
+        documents = []
+        for item in data:
+            doc = Document(
+                page_content=item['page_content'],
+                metadata=item['metadata']
+            )
+            documents.append(doc)
+            
+        logger.info(f"Loaded {len(documents)} document chunks")
+        global_documents = documents
+        return documents
+    except Exception as e:
+        logger.error(f"Error loading preprocessed chunks: {str(e)}")
+        raise
+
+def initialize_retriever(documents):
+    """Create a retriever from documents using a shared Qdrant client."""
+    global global_qdrant_client, global_retriever
+    
+    # Return existing retriever if already initialized
+    if global_retriever is not None:
+        logger.info("Using existing global retriever")
+        return global_retriever
+        
+    logger.info("Creating retriever from documents")
+    try:
+        # Use langchain_qdrant to create a vector store
+        from qdrant_client import QdrantClient
+        from langchain_qdrant import QdrantVectorStore
+        from langchain_openai import OpenAIEmbeddings
+        
+        # Create embedding object
+        embeddings = OpenAIEmbeddings()
+        logger.info("Created OpenAI embeddings object")
+        
+        # Create a persistent path for embeddings storage
+        qdrant_path = "/tmp/qdrant_storage"
+        logger.info(f"Using persistent Qdrant storage path: {qdrant_path}")
+        
+        # Create directory for Qdrant storage
+        os.makedirs(qdrant_path, exist_ok=True)
+        
+        # Create or reuse global Qdrant client
+        if global_qdrant_client is None:
+            client = QdrantClient(path=qdrant_path)
+            global_qdrant_client = client
+            logger.info("Created new global Qdrant client with persistent storage")
+        else:
+            client = global_qdrant_client
+            logger.info("Using existing global Qdrant client")
+        
+        # Check if collection already exists
+        try:
+            collections = client.get_collections()
+            collection_exists = any(collection.name == "puppies" for collection in collections.collections)
+            logger.info(f"Collection 'puppies' exists: {collection_exists}")
+        except Exception as e:
+            collection_exists = False
+            logger.info(f"Could not check collections, assuming none exist: {e}")
+        
+        # OpenAI embeddings dimension
+        embedding_dim = 1536
+        
+        # Create collection only if it doesn't exist
+        if not collection_exists:
+            from qdrant_client.http import models
+            client.create_collection(
+                collection_name="puppies",
+                vectors_config=models.VectorParams(
+                    size=embedding_dim,
+                    distance=models.Distance.COSINE
+                )
+            )
+            logger.info("Created new collection 'puppies'")
+        else:
+            logger.info("Using existing collection 'puppies'")
+        
+        # Create vector store
+        vector_store = QdrantVectorStore(
+            client=client,
+            collection_name="puppies",
+            embedding=embeddings
+        )
+        
+        # Add documents only if collection was just created (to avoid duplicates)
+        if not collection_exists:
+            vector_store.add_documents(documents)
+            logger.info(f"Added {len(documents)} documents to vector store")
+        else:
+            logger.info("Using existing embeddings in vector store")
+        
+        # Create retriever
+        retriever = vector_store.as_retriever(search_kwargs={"k": 5})
+        logger.info("Created retriever")
+        
+        # Store global retriever
+        global_retriever = retriever
+        
+        return retriever
+    except Exception as e:
+        logger.error(f"Error creating retriever: {str(e)}")
+        raise
+
+async def initialize_system():
+    """Initialize the RAG system and agent"""
+    global global_agent, initialization_completed
+    
+    if initialization_completed:
+        return global_agent
+    
+    await manager.send_log("Starting system initialization...", "info")
+    
+    try:
+        # Load documents
+        await manager.send_log("Loading document chunks...", "info")
+        documents = load_preprocessed_chunks()
+        await manager.send_log(f"Loaded {len(documents)} document chunks", "success")
+        
+        # Create retriever
+        await manager.send_log("Creating retriever...", "info")
+        retriever = initialize_retriever(documents)
+        await manager.send_log("Retriever ready", "success")
+        
+        # Create RAG system
+        await manager.send_log("Setting up RAG system...", "info")
+        rag_system = RAGSystem(retriever)
+        rag_tool = rag_system.create_rag_tool()
+        await manager.send_log("RAG system ready", "success")
+        
+        # Create agent workflow
+        await manager.send_log("Initializing agent workflow...", "info")
+        agent = AgentWorkflow(rag_tool)
+        await manager.send_log("Agent workflow ready", "success")
+        
+        global_agent = agent
+        initialization_completed = True
+        
+        await manager.send_log("System initialization completed!", "success")
+        return agent
+        
+    except Exception as e:
+        await manager.send_log(f"Error during initialization: {str(e)}", "error")
+        raise
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifespan"""
+    # Startup
+    try:
+        await initialize_system()
+        logger.info("System initialized successfully")
+    except Exception as e:
+        logger.error(f"Failed to initialize system: {e}")
+        raise  # ⚠️ IMPORTANT: Arrêter l'application si l'initialisation échoue
+    
+    yield
+    
+    # Shutdown - cleanup if needed
+    logger.info("Application shutdown")
+
+# FastAPI app with lifespan
+app = FastAPI(
+    title="PuppyCompanion", 
+    description="AI Assistant for Puppy Care",
+    lifespan=lifespan
+)
+
+@app.get("/", response_class=HTMLResponse)
+async def get_index():
+    """Serve the main HTML page"""
+    return FileResponse("static/index.html")
+
+@app.get("/favicon.ico")
+async def get_favicon():
+    """Return a 204 No Content for favicon to avoid 404 errors"""
+    from fastapi import Response
+    return Response(status_code=204)
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    """WebSocket endpoint for real-time logs"""
+    await manager.connect(websocket)
+    try:
+        while True:
+            # Keep connection alive
+            await asyncio.sleep(1)
+    except WebSocketDisconnect:
+        manager.disconnect(websocket)
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(request: QuestionRequest):
+    """Main chat endpoint"""
+    global global_agent
+    
+    if not initialization_completed or not global_agent:
+        await manager.send_log("System not initialized, starting initialization...", "warning")
+        try:
+            global_agent = await initialize_system()
+        except Exception as e:
+            raise HTTPException(status_code=500, detail="System initialization failed")
+    
+    question = request.question
+    await manager.send_log(f"New question: {question}", "info")
+    
+    try:
+        # Process question with agent
+        await manager.send_log("Processing with agent workflow...", "info")
+        result = global_agent.process_question(question)
+        
+        # Extract response and metadata
+        response_content = global_agent.get_final_response(result)
+        
+        # Parse tool usage and send detailed info to debug console
+        tool_used = "Unknown"
+        sources = []
+        
+        if "[Using RAG tool]" in response_content:
+            tool_used = "RAG Tool"
+            await manager.send_log("Used RAG tool - Knowledge base search", "tool")
+            
+            # Send detailed RAG chunks to debug console
+            if "context" in result:
+                await manager.send_log(f"Retrieved {len(result['context'])} chunks from knowledge base:", "info")
+                for i, doc in enumerate(result["context"], 1):
+                    source_name = doc.metadata.get('source', 'Unknown')
+                    page = doc.metadata.get('page', 'N/A')
+                    chapter = doc.metadata.get('chapter', '')
+                    
+                    # Create detailed chunk info for console
+                    if chapter:
+                        chunk_header = f"Chunk {i} - {source_name} (Chapter: {chapter}, Page: {page})"
+                    else:
+                        chunk_header = f"Chunk {i} - {source_name} (Page: {page})"
+                    
+                    await manager.send_log(chunk_header, "source")
+                    
+                    # Send chunk content preview
+                    content_preview = doc.page_content[:200] + "..." if len(doc.page_content) > 200 else doc.page_content
+                    await manager.send_log(f"Content: {content_preview}", "chunk")
+                    
+                    # Collect for sources array (minimal info)
+                    source_info = {
+                        "chunk": i,
+                        "source": source_name,
+                        "page": page,
+                        "chapter": chapter
+                    }
+                    sources.append(source_info)
+                    
+        elif "[Using Tavily tool]" in response_content:
+            tool_used = "Tavily Tool"
+            await manager.send_log("Used Tavily tool - Web search", "tool")
+            
+            # Extract Tavily sources from response content and send to debug console
+            lines = response_content.split('\n')
+            tavily_sources_count = 0
+            
+            for line in lines:
+                line_stripped = line.strip()
+                # Look for Tavily source lines like "- *Source 1 - domain.com: Title*"
+                if (line_stripped.startswith('- *Source') and ':' in line_stripped):
+                    tavily_sources_count += 1
+                    # Extract and format for debug console
+                    try:
+                        # Remove markdown formatting for clean display
+                        clean_source = line_stripped.replace('- *', '').replace('*', '')
+                        await manager.send_log(f"{clean_source}", "source")
+                    except:
+                        await manager.send_log(f"{line_stripped}", "source")
+                        
+            if tavily_sources_count > 0:
+                await manager.send_log(f"Found {tavily_sources_count} web sources", "info")
+            else:
+                await manager.send_log("Searched the web for current information", "source")
+            
+        elif "out of scope" in response_content.lower():
+            tool_used = "Out of Scope"
+            await manager.send_log("Question outside scope (not dog-related)", "warning")
+        
+        # Clean response content - REMOVE ALL source references for mobile interface
+        clean_response = response_content
+        
+        # Remove tool markers
+        clean_response = clean_response.replace("[Using RAG tool]", "").replace("[Using Tavily tool]", "").strip()
+        
+        # Remove ALL source-related lines with comprehensive patterns
+        lines = clean_response.split('\n')
+        cleaned_lines = []
+        for line in lines:
+            line_stripped = line.strip()
+            # Skip lines that are source references (comprehensive patterns)
+            skip_line = False
+            
+            # Pattern 1: Lines starting with * containing Source/Chunk/Based on
+            if (line_stripped.startswith('*') and 
+                ('Chunk' in line or 'Source' in line or 'Based on' in line or 'Basé sur' in line)):
+                skip_line = True
+            
+            # Pattern 2: Lines starting with - * containing Source/Chunk/Based on  
+            if (line_stripped.startswith('- *') and 
+                ('Chunk' in line or 'Source' in line or 'Based on' in line or 'Basé sur' in line)):
+                skip_line = True
+                
+            # Pattern 3: Lines that are just chunk references like "- *Chunk 1 - filename*"
+            if (line_stripped.startswith('- *Chunk') and line_stripped.endswith('*')):
+                skip_line = True
+                
+            # Pattern 4: Lines that start with "- *Based on" 
+            if line_stripped.startswith('- *Based on'):
+                skip_line = True
+                
+            # Add line only if it's not a source reference and not empty
+            if not skip_line and line_stripped:
+                cleaned_lines.append(line)
+        
+        # Final clean response for mobile interface
+        final_response = '\n'.join(cleaned_lines).strip()
+        
+        # Additional cleanup - remove any remaining source markers at start
+        while final_response.startswith('- *') or final_response.startswith('*'):
+            # Find the end of the line to remove
+            if '\n' in final_response:
+                final_response = final_response.split('\n', 1)[1].strip()
+            else:
+                final_response = ""
+                break
+        
+        # Ensure we have a response
+        if not final_response:
+            final_response = "I apologize, but I couldn't generate a proper response to your question."
+        
+        await manager.send_log(f"Clean response ready for mobile interface", "success")
+        
+        return ChatResponse(
+            response=final_response,
+            sources=sources,  # Minimal info for API, detailed info already sent to debug console
+            tool_used=tool_used
+        )
+        
+    except Exception as e:
+        await manager.send_log(f"Error processing question: {str(e)}", "error")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "initialized": initialization_completed,
+        "timestamp": datetime.now().isoformat()
+    }
+
+# Mount static files
+app.mount("/static", StaticFiles(directory="static"), name="static")
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

pyproject.toml

@@ -0,0 +1,126 @@
+[project]
+name = "puppycompanion-fastapi"
+version = "0.2.0"
+description = "PuppyCompanion - Assistant IA pour l'éducation canine avec interface FastAPI moderne"
+readme = "README.md"
+authors = [
+    {name = "jthomazo", email = "[email protected]"},
+]
+dependencies = [
+    # FastAPI et serveur web
+    "fastapi>=0.104.1",
+    "uvicorn[standard]>=0.24.0",
+    "websockets>=12.0",
+    "aiofiles>=23.2.1",
+    
+    # LangChain core
+    "langchain>=0.0.300",
+    "langchain-community>=0.0.16", 
+    "langchain-core>=0.1.0",
+    "langchain-openai>=0.0.5",
+    "langgraph>=0.0.17",
+    
+    # Vector databases et embeddings
+    "langchain-qdrant>=0.0.1",
+    "qdrant-client>=1.6.0",
+    "langchain-huggingface>=0.0.1",
+    "sentence-transformers>=2.7.0",
+    "transformers>=4.40.0",
+    "torch>=2.3.0",
+    
+    # APIs et recherche web
+    "openai>=1.6.0",
+    "tavily-python>=0.2.4",
+    
+    # Utilitaires core
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.7.0",
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    "tiktoken>=0.7.0",
+    
+    # Processing et évaluation
+    "ragas>=0.1.1",
+    "scikit-learn>=1.4.0",
+    "tqdm>=4.66.0",
+    
+    # Document processing (si nécessaire pour preprocessing)
+    "pymupdf>=1.22.0",
+    "pypdf>=3.15.1",
+    "unstructured>=0.11.0",
+    "pdf2image>=1.16.0",
+    "pdfminer.six>=20221105",
+    
+    # Monitoring et debug
+    "nest-asyncio>=1.5.6",
+    "matplotlib>=3.7.0",
+    "seaborn>=0.12.0",
+    
+    # Support images (si nécessaire)
+    "pillow>=10.0.0",
+    "pi-heif>=0.12.0",
+    "wrapt>=1.15.0",
+]
+requires-python = ">=3.9,<4.0"
+license = "MIT"
+
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+py-modules = [
+    "main",
+    "rag_system",
+    "agent_workflow", 
+    "embedding_models",
+]
+
+[tool.setuptools.packages.find]
+exclude = [
+    "data*", 
+    "metrics*", 
+    "venv_dev_312*", 
+    "doc*", 
+    ".venv*", 
+    "__pycache__*", 
+    "*.egg-info*",
+    "static*",
+    "backup_chainlit*"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 100
+target-version = ['py39']
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+select = ["E", "F", "I"]
+
+[project.optional-dependencies]
+dev = [
+    "black>=23.10.0",
+    "isort>=5.12.0",
+    "mypy>=1.6.1",
+    "pytest>=7.4.3",
+    "ruff>=0.0.270",
+    "httpx>=0.25.0",  # Pour tester l'API FastAPI
+]
+
+[project.scripts]
+puppycompanion = "main:main"
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true

rag_system.py

@@ -0,0 +1,124 @@
+# rag_system.py
+import logging
+from typing import Dict, List, Optional, TypedDict
+
+from langchain_openai import ChatOpenAI
+from langchain_core.documents import Document
+from langchain_core.messages import HumanMessage
+from langchain.prompts import ChatPromptTemplate
+from langchain_core.tools import tool
+
+from langgraph.graph import StateGraph, START, END
+
+# Logging configuration
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# RAG prompt for puppy-related questions
+RAG_PROMPT =    """
+                You are an assistant specialized in puppy education and care.
+                Your role is to help new puppy owners by answering their questions with accuracy and kindness.
+                Use only the information provided in the context to formulate your answers.
+                If you cannot find the information in the context, just say "I don't know".
+
+                ### Question
+                {question}
+
+                ### Context
+                {context}
+                """
+
+class State(TypedDict):
+    question: str
+    context: List[Document]
+    response: str
+
+class RAGSystem:
+    """RAG system for puppy-related questions"""
+    
+    def __init__(self, retriever, model_name: str = "gpt-4o-mini"):
+        self.retriever = retriever
+        self.llm = ChatOpenAI(model=model_name)
+        self.rag_prompt = ChatPromptTemplate.from_template(RAG_PROMPT)
+        self.graph_rag = self._build_graph()
+    
+    def _build_graph(self):
+        """Builds the RAG graph"""
+        
+        def retrieve(state):
+            retrieved_docs = self.retriever.invoke(state["question"])
+            return {"context": retrieved_docs}
+
+        def generate(state):
+            docs_content = "\n\n".join([doc.page_content for doc in state["context"]])
+            messages = self.rag_prompt.format_messages(
+                question=state["question"], 
+                context=docs_content
+            )
+            response = self.llm.invoke(messages)
+            return {"response": response.content}
+
+        # Build the graph
+        graph_builder = StateGraph(State).add_sequence([retrieve, generate])
+        graph_builder.add_edge(START, "retrieve")
+        return graph_builder.compile()
+    
+    def process_query(self, question: str) -> Dict:
+        """ Processes a query and returns the response with context """
+        result = self.graph_rag.invoke({"question": question})
+        
+        # Format detailed source information
+        sources_info = []
+        for i, doc in enumerate(result["context"], 1):
+            metadata = doc.metadata
+            # Extract useful metadata information
+            source_name = metadata.get('source', 'Unknown')
+            page = metadata.get('page', 'N/A')
+            chapter = metadata.get('chapter', '')
+            
+            # Create a detailed source description
+            if chapter:
+                source_desc = f"Chunk {i} - {source_name} (Chapter: {chapter}, Page: {page})"
+            else:
+                source_desc = f"Chunk {i} - {source_name} (Page: {page})"
+                
+            sources_info.append({
+                'chunk_number': i,
+                'description': source_desc,
+                'source': source_name,
+                'page': page,
+                'chapter': chapter,
+                'content_preview': doc.page_content[:100] + "..." if len(doc.page_content) > 100 else doc.page_content
+            })
+        
+        return {
+            "response": result["response"],
+            "context": result["context"],
+            "sources_info": sources_info,
+            "total_chunks": len(result["context"])
+        }
+    
+    def create_rag_tool(self):
+        """Creates a RAG tool for the agent"""
+        
+        # Reference to the current instance to use it in the tool
+        rag_system = self
+        
+        @tool
+        def ai_rag_tool(question: str) -> Dict:
+            """MANDATORY for all questions about puppies, their behavior, education or training.
+            This tool accesses a specialized knowledge base on puppies with expert and reliable information.
+            Any question regarding puppy care, education, behavior or health MUST be processed by this tool.
+            The input must be a complete question."""
+            
+            # Invoke the RAG graph
+            result = rag_system.process_query(question)
+            
+            return {
+                "messages": [HumanMessage(content=result["response"])],
+                "context": result["context"],
+                "sources_info": result["sources_info"],
+                "total_chunks": result["total_chunks"]
+            }
+        
+        return ai_rag_tool

requirements.txt

@@ -0,0 +1,31 @@
+# FastAPI and web framework dependencies
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+websockets==12.0
+
+# Existing LangChain dependencies
+langchain-openai==0.1.0
+langchain-core==0.2.0
+langchain-community==0.2.0
+langchain-qdrant==0.1.0
+langgraph==0.1.0
+
+# Vector database and embeddings
+qdrant-client==1.8.0
+sentence-transformers==2.7.0
+
+# Web search
+tavily-python==0.3.0
+
+# Core dependencies
+python-dotenv==1.0.0
+pydantic==2.7.0
+pandas==2.2.0
+numpy==1.26.0
+scikit-learn==1.4.0
+transformers==4.40.0
+torch==2.3.0
+tiktoken==0.7.0
+
+# Additional utilities
+aiofiles==23.2.1

static/_index.html

@@ -0,0 +1,655 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PuppyCompanion - AI Assistant</title>
+    <!-- Marked.js for Markdown rendering -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/4.3.0/marked.min.js"></script>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            height: 100vh;
+            overflow: hidden;
+        }
+
+        .container {
+            display: flex;
+            height: 100vh;
+            max-width: 1400px;
+            margin: 0 auto;
+            background: rgba(255, 255, 255, 0.1);
+            backdrop-filter: blur(10px);
+            border-radius: 20px;
+            overflow: hidden;
+            box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
+        }
+
+        /* Mobile Interface (Left) */
+        .mobile-interface {
+            flex: 1;
+            max-width: 400px;
+            background: linear-gradient(to bottom, #1e1e1e, #2d2d2d);
+            display: flex;
+            flex-direction: column;
+            position: relative;
+            border-radius: 20px 0 0 20px;
+            overflow: hidden;
+        }
+
+        .mobile-header {
+            background: rgba(0, 0, 0, 0.3);
+            padding: 20px;
+            text-align: center;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .mobile-header h1 {
+            color: #ffffff;
+            font-size: 1.5rem;
+            font-weight: 600;
+            margin-bottom: 5px;
+        }
+
+        .mobile-header p {
+            color: #a0a0a0;
+            font-size: 0.9rem;
+        }
+
+        .chat-container {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            padding: 20px;
+            overflow: hidden;
+        }
+
+        .messages {
+            flex: 1;
+            overflow-y: auto;
+            margin-bottom: 20px;
+            padding-right: 5px;
+        }
+
+        .messages::-webkit-scrollbar {
+            width: 4px;
+        }
+
+        .messages::-webkit-scrollbar-track {
+            background: rgba(255, 255, 255, 0.1);
+            border-radius: 2px;
+        }
+
+        .messages::-webkit-scrollbar-thumb {
+            background: rgba(255, 255, 255, 0.3);
+            border-radius: 2px;
+        }
+
+        .message {
+            margin-bottom: 15px;
+            animation: slideIn 0.3s ease-out;
+        }
+
+        @keyframes slideIn {
+            from {
+                opacity: 0;
+                transform: translateY(20px);
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+
+        .message.user {
+            text-align: right;
+        }
+
+        .message.bot {
+            text-align: left;
+        }
+
+        .message-content {
+            display: inline-block;
+            max-width: 85%;
+            padding: 12px 16px;
+            border-radius: 18px;
+            word-wrap: break-word;
+            line-height: 1.4;
+        }
+
+        .message.user .message-content {
+            background: linear-gradient(135deg, #007AFF, #0051D5);
+            color: white;
+        }
+
+        .message.bot .message-content {
+            background: rgba(255, 255, 255, 0.1);
+            color: #ffffff;
+            border: 1px solid rgba(255, 255, 255, 0.2);
+        }
+
+        /* Markdown styling for bot messages */
+        .message.bot .message-content h1,
+        .message.bot .message-content h2,
+        .message.bot .message-content h3 {
+            color: #ffffff;
+            margin: 8px 0 4px 0;
+            font-weight: 600;
+        }
+
+        .message.bot .message-content h1 {
+            font-size: 1.2em;
+        }
+
+        .message.bot .message-content h2 {
+            font-size: 1.1em;
+        }
+
+        .message.bot .message-content h3 {
+            font-size: 1em;
+        }
+
+        .message.bot .message-content ul,
+        .message.bot .message-content ol {
+            margin: 8px 0;
+            padding-left: 20px;
+        }
+
+        .message.bot .message-content li {
+            margin: 2px 0;
+        }
+
+        .message.bot .message-content p {
+            margin: 6px 0;
+            line-height: 1.4;
+        }
+
+        .message.bot .message-content strong {
+            color: #ffffff;
+            font-weight: 600;
+        }
+
+        .message.bot .message-content em {
+            font-style: italic;
+            color: rgba(255, 255, 255, 0.9);
+        }
+
+        .message.bot .message-content code {
+            background: rgba(0, 0, 0, 0.3);
+            padding: 2px 4px;
+            border-radius: 3px;
+            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+            font-size: 0.9em;
+        }
+
+        .message.bot .message-content blockquote {
+            border-left: 3px solid rgba(255, 255, 255, 0.3);
+            margin: 8px 0;
+            padding-left: 12px;
+            font-style: italic;
+            color: rgba(255, 255, 255, 0.8);
+        }
+
+        .input-container {
+            display: flex;
+            gap: 10px;
+            padding: 15px;
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 25px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .input-container input {
+            flex: 1;
+            background: transparent;
+            border: none;
+            color: white;
+            font-size: 16px;
+            outline: none;
+            padding: 10px 15px;
+        }
+
+        .input-container input::placeholder {
+            color: rgba(255, 255, 255, 0.6);
+        }
+
+        .input-container button {
+            background: linear-gradient(135deg, #007AFF, #0051D5);
+            border: none;
+            color: white;
+            padding: 10px 20px;
+            border-radius: 20px;
+            cursor: pointer;
+            font-weight: 600;
+            transition: all 0.3s ease;
+        }
+
+        .input-container button:hover {
+            transform: scale(1.05);
+            box-shadow: 0 5px 15px rgba(0, 122, 255, 0.4);
+        }
+
+        .input-container button:disabled {
+            opacity: 0.6;
+            cursor: not-allowed;
+            transform: none;
+        }
+
+        .loading {
+            display: none;
+            text-align: center;
+            color: rgba(255, 255, 255, 0.7);
+            font-style: italic;
+            margin: 10px 0;
+        }
+
+        .loading.show {
+            display: block;
+        }
+
+        /* Debug Terminal (Right) */
+        .debug-terminal {
+            flex: 1;
+            background: #1a1a1a;
+            display: flex;
+            flex-direction: column;
+            border-radius: 0 20px 20px 0;
+        }
+
+        .terminal-header {
+            background: #2d2d2d;
+            padding: 15px 20px;
+            border-bottom: 1px solid #404040;
+            display: flex;
+            align-items: center;
+            gap: 10px;
+        }
+
+        .terminal-dots {
+            display: flex;
+            gap: 6px;
+        }
+
+        .dot {
+            width: 12px;
+            height: 12px;
+            border-radius: 50%;
+        }
+
+        .dot.red { background: #ff5f56; }
+        .dot.yellow { background: #ffbd2e; }
+        .dot.green { background: #27ca3f; }
+
+        .terminal-title {
+            color: #ffffff;
+            font-weight: 600;
+            margin-left: 10px;
+        }
+
+        .terminal-content {
+            flex: 1;
+            overflow-y: auto;
+            padding: 20px;
+            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+            font-size: 13px;
+            line-height: 1.5;
+        }
+
+        .terminal-content::-webkit-scrollbar {
+            width: 8px;
+        }
+
+        .terminal-content::-webkit-scrollbar-track {
+            background: #2d2d2d;
+        }
+
+        .terminal-content::-webkit-scrollbar-thumb {
+            background: #555;
+            border-radius: 4px;
+        }
+
+        .log-item {
+            margin-bottom: 8px;
+            padding: 8px 12px;
+            border-radius: 6px;
+            border-left: 3px solid #666;
+            font-size: 12px;
+            animation: logSlide 0.3s ease-out;
+        }
+
+        @keyframes logSlide {
+            from {
+                opacity: 0;
+                transform: translateX(-20px);
+            }
+            to {
+                opacity: 1;
+                transform: translateX(0);
+            }
+        }
+
+        .log-content {
+            display: flex;
+            align-items: flex-start;
+            gap: 8px;
+        }
+
+        .log-timestamp {
+            flex-shrink: 0;
+            color: #888;
+            font-size: 11px;
+            min-width: 60px;
+        }
+
+        .log-message {
+            flex: 1;
+            word-wrap: break-word;
+        }
+
+        /* Status indicator */
+        .status-indicator {
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            padding: 8px 16px;
+            background: rgba(0, 0, 0, 0.8);
+            color: white;
+            border-radius: 20px;
+            font-size: 12px;
+            z-index: 1000;
+            transition: all 0.3s ease;
+        }
+
+        .status-indicator.connected {
+            background: rgba(39, 174, 96, 0.9);
+        }
+
+        .status-indicator.disconnected {
+            background: rgba(231, 76, 60, 0.9);
+        }
+
+        /* Responsive */
+        @media (max-width: 768px) {
+            .container {
+                flex-direction: column;
+                border-radius: 0;
+            }
+            
+            .mobile-interface {
+                max-width: none;
+                border-radius: 0;
+            }
+            
+            .debug-terminal {
+                border-radius: 0;
+                height: 40vh;
+            }
+        }
+
+        /* Smooth transitions */
+        * {
+            transition: background-color 0.3s ease;
+        }
+    </style>
+</head>
+<body>
+    <div class="status-indicator" id="status">Connecting...</div>
+    
+    <div class="container">
+        <!-- Mobile Interface -->
+        <div class="mobile-interface">
+            <div class="mobile-header">
+                <h1>PuppyCompanion</h1>
+                <p>Your AI assistant for puppy care</p>
+            </div>
+            
+            <div class="chat-container">
+                <div class="messages" id="messages">
+                    <div class="message bot">
+                        <div class="message-content">
+                            Hello! I'm your AI assistant specialized in puppy care and training. Ask me anything about your furry friend!
+                        </div>
+                    </div>
+                </div>
+                
+                <div class="loading" id="loading">
+                    <div>Thinking...</div>
+                </div>
+                
+                <div class="input-container">
+                    <input type="text" id="messageInput" placeholder="Ask about puppy training, care, behavior..." maxlength="500">
+                    <button id="sendButton" onclick="sendMessage()">Send</button>
+                </div>
+            </div>
+        </div>
+        
+        <!-- Debug Terminal -->
+        <div class="debug-terminal">
+            <div class="terminal-header">
+                <div class="terminal-dots">
+                    <div class="dot red"></div>
+                    <div class="dot yellow"></div>
+                    <div class="dot green"></div>
+                </div>
+                <div class="terminal-title">Debug Console</div>
+            </div>
+            <div class="terminal-content" id="logContainer">
+                <div class="log-item" style="border-left-color: #10b981; background: rgba(16, 185, 129, 0.1);">
+                    <div class="log-content">
+                        <span class="log-timestamp">00:00:00</span>
+                        <span class="log-message" style="color: #10b981;">System ready - Connecting to backend...</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        let ws = null;
+        let isConnected = false;
+        
+        function connectWebSocket() {
+            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsUrl = `${protocol}//${window.location.host}/ws`;
+            
+            ws = new WebSocket(wsUrl);
+            
+            ws.onopen = function(event) {
+                isConnected = true;
+                updateStatus('Connected', 'connected');
+                addLogMessage(getCurrentTime(), 'WebSocket connected to debug console', 'success');
+            };
+            
+            ws.onmessage = function(event) {
+                const data = JSON.parse(event.data);
+                addLogMessage(data.timestamp, data.message, data.type);
+            };
+            
+            ws.onclose = function(event) {
+                isConnected = false;
+                updateStatus('Disconnected', 'disconnected');
+                addLogMessage(getCurrentTime(), 'WebSocket connection closed', 'error');
+                
+                // Reconnect after 3 seconds
+                setTimeout(connectWebSocket, 3000);
+            };
+            
+            ws.onerror = function(error) {
+                addLogMessage(getCurrentTime(), 'WebSocket error occurred', 'error');
+            };
+        }
+        
+        function updateStatus(text, className) {
+            const status = document.getElementById('status');
+            status.textContent = text;
+            status.className = `status-indicator ${className}`;
+        }
+        
+        function getCurrentTime() {
+            return new Date().toLocaleTimeString('en-US', { hour12: false });
+        }
+        
+        function addLogMessage(timestamp, message, type) {
+            const logContainer = document.getElementById('logContainer');
+            const logItem = document.createElement('div');
+            logItem.className = 'log-item';
+            
+            let icon, color, bgColor;
+            switch(type) {
+                case 'success':
+                    icon = '✅';
+                    color = '#10b981';
+                    bgColor = 'rgba(16, 185, 129, 0.1)';
+                    break;
+                case 'error':
+                    icon = '❌';
+                    color = '#ef4444';
+                    bgColor = 'rgba(239, 68, 68, 0.1)';
+                    break;
+                case 'warning':
+                    icon = '⚠️';
+                    color = '#f59e0b';
+                    bgColor = 'rgba(245, 158, 11, 0.1)';
+                    break;
+                case 'tool':
+                    icon = '🔧';
+                    color = '#3b82f6';
+                    bgColor = 'rgba(59, 130, 246, 0.1)';
+                    break;
+                case 'source':
+                    icon = '📄';
+                    color = '#8b5cf6';
+                    bgColor = 'rgba(139, 92, 246, 0.1)';
+                    break;
+                case 'chunk':
+                    icon = '📝';
+                    color = '#06b6d4';
+                    bgColor = 'rgba(6, 182, 212, 0.1)';
+                    break;
+                default:
+                    icon = 'ℹ️';
+                    color = '#6b7280';
+                    bgColor = 'rgba(107, 114, 128, 0.1)';
+            }
+            
+            logItem.style.borderLeft = `3px solid ${color}`;
+            logItem.style.backgroundColor = bgColor;
+            
+            logItem.innerHTML = `
+                <div class="log-content">
+                    <span class="log-icon">${icon}</span>
+                    <span class="log-timestamp">${timestamp}</span>
+                    <span class="log-message" style="color: ${color};">${message}</span>
+                </div>
+            `;
+            
+            logContainer.appendChild(logItem);
+            logContainer.scrollTop = logContainer.scrollHeight;
+        }
+        
+        function addMessage(content, isUser = false) {
+            const messages = document.getElementById('messages');
+            const messageDiv = document.createElement('div');
+            messageDiv.className = `message ${isUser ? 'user' : 'bot'}`;
+            
+            const contentDiv = document.createElement('div');
+            contentDiv.className = 'message-content';
+            
+            if (isUser) {
+                // User messages as plain text
+                contentDiv.textContent = content;
+            } else {
+                // Bot messages rendered as Markdown
+                try {
+                    contentDiv.innerHTML = marked.parse(content);
+                } catch (error) {
+                    // Fallback to plain text if Markdown parsing fails
+                    contentDiv.textContent = content;
+                }
+            }
+            
+            messageDiv.appendChild(contentDiv);
+            messages.appendChild(messageDiv);
+            messages.scrollTop = messages.scrollHeight;
+        }
+        
+        async function sendMessage() {
+            const input = document.getElementById('messageInput');
+            const sendButton = document.getElementById('sendButton');
+            const loading = document.getElementById('loading');
+            
+            const question = input.value.trim();
+            if (!question) return;
+            
+            // Add user message
+            addMessage(question, true);
+            
+            // Clear input and disable form
+            input.value = '';
+            sendButton.disabled = true;
+            loading.classList.add('show');
+            
+            try {
+                const response = await fetch('/chat', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({ question: question })
+                });
+                
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                
+                const data = await response.json();
+                
+                // Add bot response
+                addMessage(data.response);
+                
+            } catch (error) {
+                console.error('Error:', error);
+                addMessage('Sorry, there was an error processing your question. Please try again.');
+            } finally {
+                sendButton.disabled = false;
+                loading.classList.remove('show');
+                input.focus();
+            }
+        }
+        
+        // Event listeners
+        document.getElementById('messageInput').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                sendMessage();
+            }
+        });
+        
+        // Initialize
+        document.addEventListener('DOMContentLoaded', function() {
+            // Check if marked.js loaded and configure it
+            if (typeof marked !== 'undefined') {
+                marked.setOptions({
+                    breaks: true,      // Convert \n to <br>
+                    gfm: true,         // GitHub Flavored Markdown
+                    sanitize: false,   // Allow HTML (we trust our backend)
+                    smartLists: true,  // Better list handling
+                    smartypants: true  // Smart quotes and dashes
+                });
+            } else {
+                console.warn('Marked.js not loaded, falling back to plain text');
+            }
+            
+            connectWebSocket();
+            document.getElementById('messageInput').focus();
+        });
+    </script>
+</body>
+</html>

static/index.html

@@ -0,0 +1,638 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PuppyCompanion - AI Assistant</title>
+    <!-- Marked.js for Markdown rendering -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/4.3.0/marked.min.js"></script>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+            background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 50%, #cbd5e1 100%);
+            height: 100vh;
+            overflow: hidden;
+        }
+
+        .container {
+            display: flex;
+            height: 100vh;
+            max-width: 1400px;
+            margin: 0 auto;
+            background: rgba(255, 255, 255, 0.1);
+            backdrop-filter: blur(10px);
+            border-radius: 20px;
+            overflow: hidden;
+            box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
+            gap: 15px;
+            padding: 15px;
+        }
+
+        /* Mobile Interface (Left) */
+        .mobile-interface {
+            flex: 1;
+            max-width: 400px;
+            background: linear-gradient(to bottom, #1e1e1e, #2d2d2d);
+            display: flex;
+            flex-direction: column;
+            position: relative;
+            border-radius: 20px;
+            overflow: hidden;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+        }
+
+        .mobile-header {
+            background: linear-gradient(135deg, #FF8A65 0%, #FFAB91 50%, #FFCCBC 100%);
+            padding: 20px;
+            text-align: center;
+            border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .mobile-header h1 {
+            color: #ffffff;
+            font-size: 1.5rem;
+            font-weight: 600;
+            margin-bottom: 5px;
+        }
+
+        .mobile-header p {
+            color: #a0a0a0;
+            font-size: 0.9rem;
+        }
+
+        .chat-container {
+            flex: 1;
+            display: flex;
+            flex-direction: column;
+            padding: 20px;
+            overflow: hidden;
+        }
+
+        .messages {
+            flex: 1;
+            overflow-y: auto;
+            margin-bottom: 20px;
+            padding-right: 5px;
+        }
+
+        .messages::-webkit-scrollbar {
+            width: 4px;
+        }
+
+        .messages::-webkit-scrollbar-track {
+            background: rgba(255, 255, 255, 0.1);
+            border-radius: 2px;
+        }
+
+        .messages::-webkit-scrollbar-thumb {
+            background: rgba(255, 255, 255, 0.3);
+            border-radius: 2px;
+        }
+
+        .message {
+            margin-bottom: 15px;
+            animation: slideIn 0.3s ease-out;
+        }
+
+        @keyframes slideIn {
+            from {
+                opacity: 0;
+                transform: translateY(20px);
+            }
+            to {
+                opacity: 1;
+                transform: translateY(0);
+            }
+        }
+
+        .message.user {
+            text-align: right;
+        }
+
+        .message.bot {
+            text-align: left;
+        }
+
+        .message-content {
+            display: inline-block;
+            max-width: 85%;
+            padding: 12px 16px;
+            border-radius: 18px;
+            word-wrap: break-word;
+            line-height: 1.4;
+        }
+
+        .message.user .message-content {
+            background: linear-gradient(135deg, #FF7043, #FF8A65);
+            color: white;
+        }
+
+        .message.bot .message-content {
+            background: rgba(255, 255, 255, 0.1);
+            color: #ffffff;
+            border: 1px solid rgba(255, 255, 255, 0.2);
+        }
+
+        /* Markdown styling for bot messages */
+        .message.bot .message-content h1,
+        .message.bot .message-content h2,
+        .message.bot .message-content h3 {
+            color: #ffffff;
+            margin: 8px 0 4px 0;
+            font-weight: 600;
+        }
+
+        .message.bot .message-content h1 {
+            font-size: 1.2em;
+        }
+
+        .message.bot .message-content h2 {
+            font-size: 1.1em;
+        }
+
+        .message.bot .message-content h3 {
+            font-size: 1em;
+        }
+
+        .message.bot .message-content ul,
+        .message.bot .message-content ol {
+            margin: 8px 0;
+            padding-left: 20px;
+        }
+
+        .message.bot .message-content li {
+            margin: 2px 0;
+        }
+
+        .message.bot .message-content p {
+            margin: 6px 0;
+            line-height: 1.4;
+        }
+
+        .message.bot .message-content strong {
+            color: #ffffff;
+            font-weight: 600;
+        }
+
+        .message.bot .message-content em {
+            font-style: italic;
+            color: rgba(255, 255, 255, 0.9);
+        }
+
+        .message.bot .message-content code {
+            background: rgba(0, 0, 0, 0.3);
+            padding: 2px 4px;
+            border-radius: 3px;
+            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+            font-size: 0.9em;
+        }
+
+        .message.bot .message-content blockquote {
+            border-left: 3px solid rgba(255, 255, 255, 0.3);
+            margin: 8px 0;
+            padding-left: 12px;
+            font-style: italic;
+            color: rgba(255, 255, 255, 0.8);
+        }
+
+        .input-container {
+            display: flex;
+            gap: 10px;
+            padding: 15px;
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 25px;
+            border: 1px solid rgba(255, 255, 255, 0.1);
+        }
+
+        .input-container input {
+            flex: 1;
+            background: transparent;
+            border: none;
+            color: white;
+            font-size: 16px;
+            outline: none;
+            padding: 10px 15px;
+        }
+
+        .input-container input::placeholder {
+            color: rgba(255, 255, 255, 0.6);
+        }
+
+        .input-container button {
+            background: linear-gradient(135deg, #FF7043, #FF8A65);
+            border: none;
+            color: white;
+            padding: 10px 20px;
+            border-radius: 20px;
+            cursor: pointer;
+            font-weight: 600;
+            transition: all 0.3s ease;
+        }
+
+        .input-container button:hover {
+            transform: scale(1.05);
+            box-shadow: 0 5px 15px rgba(255, 112, 67, 0.4);
+        }
+
+        .input-container button:disabled {
+            opacity: 0.6;
+            cursor: not-allowed;
+            transform: none;
+        }
+
+        .loading {
+            display: none;
+            text-align: center;
+            color: rgba(255, 255, 255, 0.7);
+            font-style: italic;
+            margin: 10px 0;
+        }
+
+        .loading.show {
+            display: block;
+        }
+
+        /* Debug Terminal (Right) */
+        .debug-terminal {
+            flex: 1;
+            background: #1a1a1a;
+            display: flex;
+            flex-direction: column;
+            border-radius: 20px;
+            overflow: hidden;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+        }
+
+        .terminal-header {
+            background: #2d2d2d;
+            padding: 15px 20px;
+            border-bottom: 1px solid #404040;
+            display: flex;
+            align-items: center;
+        }
+
+        .terminal-title {
+            color: #ffffff;
+            font-weight: 600;
+        }
+
+        .terminal-content {
+            flex: 1;
+            overflow-y: auto;
+            padding: 20px;
+            font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+            font-size: 13px;
+            line-height: 1.5;
+        }
+
+        .terminal-content::-webkit-scrollbar {
+            width: 8px;
+        }
+
+        .terminal-content::-webkit-scrollbar-track {
+            background: #2d2d2d;
+        }
+
+        .terminal-content::-webkit-scrollbar-thumb {
+            background: #555;
+            border-radius: 4px;
+        }
+
+        .log-item {
+            margin-bottom: 8px;
+            padding: 8px 12px;
+            border-radius: 6px;
+            border-left: 3px solid #666;
+            font-size: 12px;
+            animation: logSlide 0.3s ease-out;
+        }
+
+        @keyframes logSlide {
+            from {
+                opacity: 0;
+                transform: translateX(-20px);
+            }
+            to {
+                opacity: 1;
+                transform: translateX(0);
+            }
+        }
+
+        .log-content {
+            display: flex;
+            align-items: flex-start;
+            gap: 8px;
+        }
+
+        .log-timestamp {
+            flex-shrink: 0;
+            color: #888;
+            font-size: 11px;
+            min-width: 60px;
+        }
+
+        .log-message {
+            flex: 1;
+            word-wrap: break-word;
+        }
+
+        /* Status indicator */
+        .status-indicator {
+            position: fixed;
+            top: 20px;
+            right: 20px;
+            padding: 8px 16px;
+            background: rgba(0, 0, 0, 0.8);
+            color: white;
+            border-radius: 20px;
+            font-size: 12px;
+            z-index: 1000;
+            transition: all 0.3s ease;
+        }
+
+        .status-indicator.connected {
+            background: rgba(39, 174, 96, 0.9);
+        }
+
+        .status-indicator.disconnected {
+            background: rgba(231, 76, 60, 0.9);
+        }
+
+        /* Responsive */
+        @media (max-width: 768px) {
+            .container {
+                flex-direction: column;
+                border-radius: 0;
+            }
+            
+            .mobile-interface {
+                max-width: none;
+                border-radius: 0;
+            }
+            
+            .debug-terminal {
+                border-radius: 0;
+                height: 40vh;
+            }
+        }
+
+        /* Smooth transitions */
+        * {
+            transition: background-color 0.3s ease;
+        }
+    </style>
+</head>
+<body>
+    <div class="status-indicator" id="status">Connecting...</div>
+    
+    <div class="container">
+        <!-- Mobile Interface -->
+        <div class="mobile-interface">
+            <div class="mobile-header">
+                <h1>🐶 PuppyCompanion</h1>
+                <p>Your AI assistant for puppy care</p>
+            </div>
+            
+            <div class="chat-container">
+                <div class="messages" id="messages">
+                    <div class="message bot">
+                        <div class="message-content">
+                            Hello! I'm your AI assistant specialized in puppy care and training. Ask me anything about your furry friend! 🐾
+                        </div>
+                    </div>
+                </div>
+                
+                <div class="loading" id="loading">
+                    <div>Thinking...</div>
+                </div>
+                
+                <div class="input-container">
+                    <input type="text" id="messageInput" placeholder="Ask me about your puppy" maxlength="500">
+                    <button id="sendButton" onclick="sendMessage()">Send</button>
+                </div>
+            </div>
+        </div>
+        
+        <!-- Debug Terminal -->
+        <div class="debug-terminal">
+            <div class="terminal-header">
+                <div class="terminal-title">Debug Console</div>
+            </div>
+            <div class="terminal-content" id="logContainer">
+                <div class="log-item" style="border-left-color: #10b981; background: rgba(16, 185, 129, 0.1);">
+                    <div class="log-content">
+                        <span class="log-timestamp">00:00:00</span>
+                        <span class="log-message" style="color: #10b981;">System ready - Connecting to backend...</span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        let ws = null;
+        let isConnected = false;
+        
+        function connectWebSocket() {
+            const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsUrl = `${protocol}//${window.location.host}/ws`;
+            
+            ws = new WebSocket(wsUrl);
+            
+            ws.onopen = function(event) {
+                isConnected = true;
+                updateStatus('Connected', 'connected');
+                addLogMessage(getCurrentTime(), 'WebSocket connected to debug console', 'success');
+            };
+            
+            ws.onmessage = function(event) {
+                const data = JSON.parse(event.data);
+                addLogMessage(data.timestamp, data.message, data.type);
+            };
+            
+            ws.onclose = function(event) {
+                isConnected = false;
+                updateStatus('Disconnected', 'disconnected');
+                addLogMessage(getCurrentTime(), 'WebSocket connection closed', 'error');
+                
+                // Reconnect after 3 seconds
+                setTimeout(connectWebSocket, 3000);
+            };
+            
+            ws.onerror = function(error) {
+                addLogMessage(getCurrentTime(), 'WebSocket error occurred', 'error');
+            };
+        }
+        
+        function updateStatus(text, className) {
+            const status = document.getElementById('status');
+            status.textContent = text;
+            status.className = `status-indicator ${className}`;
+        }
+        
+        function getCurrentTime() {
+            return new Date().toLocaleTimeString('en-US', { hour12: false });
+        }
+        
+        function addLogMessage(timestamp, message, type) {
+            const logContainer = document.getElementById('logContainer');
+            const logItem = document.createElement('div');
+            logItem.className = 'log-item';
+            
+            let icon, color, bgColor;
+            switch(type) {
+                case 'success':
+                    icon = '✅';
+                    color = '#10b981';
+                    bgColor = 'rgba(16, 185, 129, 0.1)';
+                    break;
+                case 'error':
+                    icon = '❌';
+                    color = '#ef4444';
+                    bgColor = 'rgba(239, 68, 68, 0.1)';
+                    break;
+                case 'warning':
+                    icon = '⚠️';
+                    color = '#f59e0b';
+                    bgColor = 'rgba(245, 158, 11, 0.1)';
+                    break;
+                case 'tool':
+                    icon = '🔧';
+                    color = '#3b82f6';
+                    bgColor = 'rgba(59, 130, 246, 0.1)';
+                    break;
+                case 'source':
+                    icon = '📄';
+                    color = '#8b5cf6';
+                    bgColor = 'rgba(139, 92, 246, 0.1)';
+                    break;
+                case 'chunk':
+                    icon = '📝';
+                    color = '#06b6d4';
+                    bgColor = 'rgba(6, 182, 212, 0.1)';
+                    break;
+                default:
+                    icon = 'ℹ️';
+                    color = '#6b7280';
+                    bgColor = 'rgba(107, 114, 128, 0.1)';
+            }
+            
+            logItem.style.borderLeft = `3px solid ${color}`;
+            logItem.style.backgroundColor = bgColor;
+            
+            logItem.innerHTML = `
+                <div class="log-content">
+                    <span class="log-icon">${icon}</span>
+                    <span class="log-timestamp">${timestamp}</span>
+                    <span class="log-message" style="color: ${color};">${message}</span>
+                </div>
+            `;
+            
+            logContainer.appendChild(logItem);
+            logContainer.scrollTop = logContainer.scrollHeight;
+        }
+        
+        function addMessage(content, isUser = false) {
+            const messages = document.getElementById('messages');
+            const messageDiv = document.createElement('div');
+            messageDiv.className = `message ${isUser ? 'user' : 'bot'}`;
+            
+            const contentDiv = document.createElement('div');
+            contentDiv.className = 'message-content';
+            
+            if (isUser) {
+                // User messages as plain text
+                contentDiv.textContent = content;
+            } else {
+                // Bot messages rendered as Markdown
+                try {
+                    contentDiv.innerHTML = marked.parse(content);
+                } catch (error) {
+                    // Fallback to plain text if Markdown parsing fails
+                    contentDiv.textContent = content;
+                }
+            }
+            
+            messageDiv.appendChild(contentDiv);
+            messages.appendChild(messageDiv);
+            messages.scrollTop = messages.scrollHeight;
+        }
+        
+        async function sendMessage() {
+            const input = document.getElementById('messageInput');
+            const sendButton = document.getElementById('sendButton');
+            const loading = document.getElementById('loading');
+            
+            const question = input.value.trim();
+            if (!question) return;
+            
+            // Add user message
+            addMessage(question, true);
+            
+            // Clear input and disable form
+            input.value = '';
+            sendButton.disabled = true;
+            loading.classList.add('show');
+            
+            try {
+                const response = await fetch('/chat', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({ question: question })
+                });
+                
+                if (!response.ok) {
+                    throw new Error(`HTTP error! status: ${response.status}`);
+                }
+                
+                const data = await response.json();
+                
+                // Add bot response
+                addMessage(data.response);
+                
+            } catch (error) {
+                console.error('Error:', error);
+                addMessage('Sorry, there was an error processing your question. Please try again.');
+            } finally {
+                sendButton.disabled = false;
+                loading.classList.remove('show');
+                input.focus();
+            }
+        }
+        
+        // Event listeners
+        document.getElementById('messageInput').addEventListener('keypress', function(e) {
+            if (e.key === 'Enter') {
+                sendMessage();
+            }
+        });
+        
+        // Initialize
+        document.addEventListener('DOMContentLoaded', function() {
+            // Check if marked.js loaded and configure it
+            if (typeof marked !== 'undefined') {
+                marked.setOptions({
+                    breaks: true,      // Convert \n to <br>
+                    gfm: true,         // GitHub Flavored Markdown
+                    sanitize: false,   // Allow HTML (we trust our backend)
+                    smartLists: true,  // Better list handling
+                    smartypants: true  // Smart quotes and dashes
+                });
+            } else {
+                console.warn('Marked.js not loaded, falling back to plain text');
+            }
+            
+            connectWebSocket();
+            document.getElementById('messageInput').focus();
+        });
+    </script>
+</body>
+</html>