Initial HF deployment

.dockerignore

@@ -0,0 +1,36 @@
+# Ignore virtual environment
+.venv/
+venv/
+env/
+
+# Ignore git
+.git/
+.gitignore
+
+# Ignore environment files (secrets in HF Settings)
+.env
+.env.*
+
+# Ignore Python cache
+*.pyc
+*.pyo
+__pycache__/
+*.egg-info/
+.eggs/
+
+# Ignore tests and docs
+tests/
+docs/
+*.md
+!README.md
+
+# Ignore IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Ignore local files
+*.log
+*.sqlite
+.DS_Store

.env.example

@@ -0,0 +1,24 @@
+# FastAPI
+APP_ENV=local
+APP_DEBUG=true
+
+# Supabase
+SUPABASE_URL=https://xxxxx.supabase.co
+SUPABASE_ANON_KEY=your_anon_key
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
+DATABASE_URL=postgresql+asyncpg://postgres:[email protected]:5432/postgres
+
+# Neo4j
+NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
+NEO4J_USERNAME=neo4j
+NEO4J_PASSWORD=CHANGE_ME
+
+# Google AI (Gemini)
+GOOGLE_API_KEY=your_google_api_key
+
+# MegaLLM (OpenAI-compatible - DeepSeek)
+MEGALLM_API_KEY=your_megallm_api_key
+MEGALLM_BASE_URL=https://ai.megallm.io/v1
+
+# CLIP (optional - for image embeddings)
+HUGGINGFACE_API_KEY=your_hf_api_key

.gitignore

@@ -0,0 +1,8 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/

DEPLOYMENT.md

@@ -0,0 +1,45 @@
+# LocalMate HF Deployment Guide
+
+## ✅ Files Created
+- `Dockerfile` - Multi-stage build with SigLIP pre-cached
+- `.dockerignore` - Excludes .venv, tests, docs
+- `README.md` - Updated with HF Spaces header
+
+## 🚀 Deployment Checklist
+
+### Step 1: Create HF Space
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. **Name:** `LocalMate-API`
+3. **SDK:** Select **Docker**
+4. **Visibility:** Public or Private
+
+### Step 2: Configure Secrets
+Go to **Space Settings > Repository secrets** and add:
+
+| Secret | Description |
+|--------|-------------|
+| `DATABASE_URL` | `postgresql+asyncpg://user:pass@host:5432/db` |
+| `NEO4J_URI` | `neo4j+s://xxx.databases.neo4j.io` |
+| `NEO4J_USER` | `neo4j` |
+| `NEO4J_PASSWORD` | Neo4j password |
+| `MEGALLM_API_KEY` | MegaLLM API key |
+| `GOOGLE_API_KEY` | Gemini API key |
+
+### Step 3: Push Code
+```bash
+# Add HF Space as remote
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/LocalMate-API
+
+# Push to HF
+git push hf main
+```
+
+### Step 4: Verify
+- Wait for build (5-10 min for first build with torch)
+- Check: `https://YOUR_USERNAME-localmate-api.hf.space/docs`
+- Test `/api/v1/chat` endpoint
+
+## ⚠️ Notes
+- First build takes ~10 min (downloading torch + SigLIP)
+- Cold start ~30s after space sleeps
+- SigLIP model is pre-cached in Docker image

Dockerfile

@@ -0,0 +1,64 @@
+# =============================================================================
+# LocalMate Backend - Hugging Face Spaces Docker Deployment
+# =============================================================================
+# Multi-stage build with SigLIP model pre-cached for optimal cold start
+
+# Stage 1: Build dependencies
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy dependency file
+COPY pyproject.toml .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir .
+
+# =============================================================================
+# Stage 2: Production image
+# =============================================================================
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY app ./app
+
+# Pre-download SigLIP model during build (cache in image)
+# This avoids downloading on every cold start
+RUN python -c "from open_clip import create_model_and_transforms; \
+    model, _, preprocess = create_model_and_transforms('ViT-B-16-SigLIP', pretrained='webli'); \
+    print('✅ SigLIP model cached')"
+
+# Create cache directory for HF models
+RUN mkdir -p /root/.cache/huggingface
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# HF Spaces expects port 7860
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD python -c "import httpx; httpx.get('http://localhost:7860/health')" || exit 1
+
+# Run with uvicorn
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,56 @@
+---
+title: LocalMate API
+emoji: 🌴
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# LocalMate Da Nang V2
+
+Multi-Modal Contextual Agent (MMCA) API for Da Nang Tourism.
+
+## Architecture
+
+Based on **Model Context Protocol (MCP)** with 3 tools:
+- **retrieve_context_text** - RAG Text search (pgvector)
+- **retrieve_similar_visuals** - RAG Image search (CLIP)
+- **find_nearby_places** - Graph Spatial (Neo4j)
+
+## Quick Start
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Copy env file
+cp .env.example .env
+# Edit .env with your credentials
+
+# Run dev server
+pkill -f "uvicorn app.main:app"
+uvicorn app.main:app --reload --port 8000
+
+# Open Swagger UI
+open http://localhost:8000/docs
+```
+
+## Testing
+
+Use the `/api/v1/chat` endpoint in Swagger to test:
+
+```json
+{
+  "message": "Tìm quán cafe gần bãi biển Mỹ Khê"
+}
+```
+
+## Tech Stack
+
+- **Framework**: FastAPI
+- **Database**: Supabase (PostgreSQL + pgvector)
+- **Graph DB**: Neo4j Aura
+- **LLM**: Google Gemini 2.5 Flash or deepseek-ai/deepseek-v3.1-terminus
+- **Embeddings**: text-embedding-004 + CLIP

app/__init__.py

@@ -0,0 +1 @@
+"""LocalMate v2 - Multi-Modal Contextual Agent."""

app/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent module - Multi-Modal Contextual Agent."""

app/agent/mmca_agent.py

@@ -0,0 +1,478 @@
+"""Multi-Modal Contextual Agent (MMCA) - ReAct Agent with MCP Tools.
+
+Implements the Agent-Centric Orchestration pattern:
+1. Parse user intent
+2. Select appropriate MCP tool(s)
+3. Execute tool(s) with logging
+4. Synthesize final response with workflow trace
+
+Supports multiple LLM providers: Google (Gemini) and MegaLLM (DeepSeek).
+"""
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.mcp.tools import mcp_tools
+from app.shared.integrations.gemini_client import GeminiClient
+from app.shared.integrations.megallm_client import MegaLLMClient
+from app.shared.logger import agent_logger, AgentWorkflow, WorkflowStep
+
+
+# Default coordinates for Da Nang (if no location specified)
+DANANG_CENTER = (16.0544, 108.2022)
+
+# System prompt for the agent - balanced for all 3 tools
+SYSTEM_PROMPT = """Bạn là trợ lý du lịch thông minh cho Đà Nẵng. Bạn có 3 công cụ tìm kiếm:
+
+**1. retrieve_context_text** - Tìm kiếm văn bản thông minh
+   - Khi nào: Hỏi về menu, review, mô tả, đặc điểm, phong cách
+   - Ví dụ: "Phở ngon giá rẻ", "Quán cafe view đẹp", "Nơi lãng mạn hẹn hò"
+   - Đặc biệt: Tự động phát hiện category (cafe, pho, seafood...) và boost kết quả
+
+**2. retrieve_similar_visuals** - Tìm theo hình ảnh
+   - Khi nào: Người dùng gửi ảnh hoặc mô tả về không gian, decor
+   - Scene filter: food, interior, exterior, view
+   - Ví dụ: "Quán có không gian giống ảnh này"
+
+**3. find_nearby_places** - Tìm theo vị trí
+   - Khi nào: Hỏi về khoảng cách, "gần đây", "gần X", "quanh Y"
+   - Ví dụ: "Quán cafe gần Cầu Rồng", "Nhà hàng gần bãi biển Mỹ Khê"
+   - Đặc biệt: Có thể lấy chi tiết đầy đủ với photos, reviews
+
+**Quy tắc quan trọng:**
+1. Phân tích intent để chọn ĐÚNG tool (không chỉ dùng 1 tool)
+2. Với câu hỏi tổng quát ("quán cafe ngon") → dùng retrieve_context_text
+3. Với câu hỏi vị trí ("gần X", "quanh Y") → dùng find_nearby_places
+4. Với ảnh → dùng retrieve_similar_visuals
+5. Có thể kết hợp nhiều tools để có kết quả tốt nhất
+6. Trả lời tiếng Việt, thân thiện, cung cấp thông tin cụ thể (tên, rating, khoảng cách)
+"""
+
+
+@dataclass
+class ChatMessage:
+    """Chat message model."""
+    role: str  # "user" or "assistant"
+    content: str
+
+
+@dataclass
+class ToolCall:
+    """Tool call with arguments and results."""
+    tool_name: str
+    arguments: dict
+    result: list | None = None
+    duration_ms: float = 0
+
+
+@dataclass
+class ChatResult:
+    """Complete chat result with response and workflow."""
+    response: str
+    workflow: AgentWorkflow
+    tools_used: list[str] = field(default_factory=list)
+    total_duration_ms: float = 0
+
+
+class MMCAAgent:
+    """
+    Multi-Modal Contextual Agent with Logging and Workflow Tracing.
+
+    Implements ReAct (Reasoning + Acting) pattern:
+    1. Observe: Parse user message and intent
+    2. Think: Decide which tool(s) to use
+    3. Act: Execute MCP tools
+    4. Synthesize: Generate final response
+
+    Supports multiple LLM providers:
+    - Google: Gemini models
+    - MegaLLM: DeepSeek models (OpenAI-compatible)
+    """
+
+    def __init__(self, provider: str = "MegaLLM", model: str | None = None):
+        """
+        Initialize agent with LLM provider and model.
+
+        Args:
+            provider: "Google" or "MegaLLM"
+            model: Model name (uses default if None)
+        """
+        self.provider = provider
+        self.model = model
+        self.tools = mcp_tools
+        self.conversation_history: list[ChatMessage] = []
+
+        # Initialize LLM client based on provider
+        if provider == "Google":
+            self.llm_client = GeminiClient(model=model)
+        else:
+            self.llm_client = MegaLLMClient(model=model)
+        
+        agent_logger.workflow_step("Agent initialized", f"Provider: {provider}, Model: {model}")
+
+    async def chat(
+        self,
+        message: str,
+        db: AsyncSession,
+        image_url: str | None = None,
+        history: str | None = None,
+    ) -> ChatResult:
+        """
+        Process a chat message and return response with workflow trace.
+
+        Args:
+            message: User's natural language message
+            db: Database session for pgvector queries
+            image_url: Optional image URL for visual search
+            history: Optional conversation history string
+
+        Returns:
+            ChatResult with response, workflow, and metadata
+        """
+        start_time = time.time()
+        
+        # Initialize workflow tracking
+        workflow = AgentWorkflow(query=message)
+        
+        # Log incoming request
+        agent_logger.api_request(
+            endpoint="/chat",
+            method="POST",
+            body={"message": message[:100], "has_image": bool(image_url), "has_history": bool(history)}
+        )
+        
+        # Add user message to internal history
+        self.conversation_history.append(ChatMessage(role="user", content=message))
+
+        # Step 1: Analyze intent and decide tool usage
+        workflow.add_step(WorkflowStep(
+            step_name="Intent Analysis",
+            purpose="Phân tích câu hỏi để chọn tool phù hợp"
+        ))
+        
+        agent_logger.workflow_step("Step 1: Intent Analysis", message[:80])
+        intent = self._detect_intent(message, image_url)
+        workflow.intent_detected = intent
+        agent_logger.workflow_step("Intent detected", intent)
+        
+        tool_calls = await self._plan_tool_calls(message, image_url)
+        
+        workflow.add_step(WorkflowStep(
+            step_name="Tool Planning",
+            purpose=f"Chọn {len(tool_calls)} tool(s) để thực thi",
+            output_summary=", ".join([tc.tool_name for tc in tool_calls])
+        ))
+
+        # Step 2: Execute tools
+        agent_logger.workflow_step("Step 2: Execute Tools", f"{len(tool_calls)} tool(s)")
+        tool_results = []
+        
+        for tool_call in tool_calls:
+            tool_start = time.time()
+            
+            agent_logger.tool_call(tool_call.tool_name, tool_call.arguments)
+            
+            result = await self._execute_tool(tool_call, db)
+            result.duration_ms = (time.time() - tool_start) * 1000
+            
+            result_count = len(result.result) if result.result else 0
+            agent_logger.tool_result(
+                tool_call.tool_name,
+                result_count,
+                result.result[0] if result.result else None
+            )
+            
+            # Add to workflow
+            workflow.add_step(WorkflowStep(
+                step_name=f"Execute {tool_call.tool_name}",
+                tool_name=tool_call.tool_name,
+                purpose=self._get_tool_purpose(tool_call.tool_name),
+                input_summary=json.dumps(tool_call.arguments, ensure_ascii=False)[:100],
+                result_count=result_count,
+                duration_ms=result.duration_ms
+            ))
+            
+            tool_results.append(result)
+
+        # Step 3: Synthesize response with history context
+        agent_logger.workflow_step("Step 3: Synthesize Response")
+        
+        llm_start = time.time()
+        response = await self._synthesize_response(message, tool_results, image_url, history)
+        llm_duration = (time.time() - llm_start) * 1000
+        
+        agent_logger.llm_response(self.provider, response[:100], tokens=None)
+        
+        workflow.add_step(WorkflowStep(
+            step_name="LLM Synthesis",
+            purpose="Tổng hợp kết quả và tạo phản hồi",
+            duration_ms=llm_duration
+        ))
+
+        # Add assistant response to internal history
+        self.conversation_history.append(ChatMessage(role="assistant", content=response))
+        
+        # Calculate total duration
+        total_duration = (time.time() - start_time) * 1000
+        workflow.total_duration_ms = total_duration
+        
+        # Log complete
+        agent_logger.api_response("/chat", 200, {"response_len": len(response)}, total_duration)
+        
+        return ChatResult(
+            response=response,
+            workflow=workflow,
+            tools_used=workflow.tools_used,
+            total_duration_ms=total_duration
+        )
+
+    def _detect_intent(self, message: str, image_url: str | None) -> str:
+        """Detect user intent for logging."""
+        intents = []
+        
+        if image_url:
+            intents.append("visual_search")
+        
+        location_keywords = ["gần", "cách", "nearby", "gần đây", "quanh", "xung quanh"]
+        if any(kw in message.lower() for kw in location_keywords):
+            intents.append("location_search")
+        
+        if not intents:
+            intents.append("text_search")
+        
+        return " + ".join(intents)
+
+    def _get_tool_purpose(self, tool_name: str) -> str:
+        """Get human-readable purpose for tool."""
+        purposes = {
+            "retrieve_context_text": "Tìm kiếm semantic trong văn bản (review, mô tả)",
+            "retrieve_similar_visuals": "Tìm địa điểm có hình ảnh tương tự",
+            "find_nearby_places": "Tìm địa điểm gần vị trí được nhắc đến",
+        }
+        return purposes.get(tool_name, tool_name)
+
+    async def _plan_tool_calls(
+        self,
+        message: str,
+        image_url: str | None = None,
+    ) -> list[ToolCall]:
+        """
+        Analyze message and plan which tools to call.
+
+        Returns list of ToolCall objects with tool_name and arguments.
+        """
+        tool_calls = []
+
+        # If image is provided, always use visual search
+        if image_url:
+            tool_calls.append(ToolCall(
+                tool_name="retrieve_similar_visuals",
+                arguments={"image_url": image_url, "limit": 5},
+            ))
+
+        # Analyze message for location/proximity queries
+        location_keywords = ["gần", "cách", "nearby", "gần đây", "quanh", "xung quanh"]
+        if any(kw in message.lower() for kw in location_keywords):
+            # Extract location name from message
+            location = self._extract_location(message)
+            category = self._extract_category(message)
+
+            # Get coordinates for the location
+            coords = await self.tools.get_location_coordinates(location) if location else None
+            lat, lng = coords if coords else DANANG_CENTER
+
+            tool_calls.append(ToolCall(
+                tool_name="find_nearby_places",
+                arguments={
+                    "lat": lat,
+                    "lng": lng,
+                    "category": category,
+                    "max_distance_km": 3.0,
+                    "limit": 5,
+                },
+            ))
+
+        # For general queries without location keywords, use text search
+        if not tool_calls:
+            tool_calls.append(ToolCall(
+                tool_name="retrieve_context_text",
+                arguments={"query": message, "limit": 5},
+            ))
+
+        return tool_calls
+
+    async def _execute_tool(
+        self,
+        tool_call: ToolCall,
+        db: AsyncSession,
+    ) -> ToolCall:
+        """Execute a single tool and return results."""
+        try:
+            if tool_call.tool_name == "retrieve_context_text":
+                results = await self.tools.retrieve_context_text(
+                    db=db,
+                    query=tool_call.arguments.get("query", ""),
+                    limit=tool_call.arguments.get("limit", 10),
+                )
+                tool_call.result = [
+                    {
+                        "place_id": r.place_id,
+                        "name": r.name,
+                        "category": r.category,
+                        "rating": r.rating,
+                        "similarity": r.similarity,
+                        "description": r.description,
+                        "source_text": r.source_text,
+                    }
+                    for r in results
+                ]
+
+            elif tool_call.tool_name == "retrieve_similar_visuals":
+                results = await self.tools.retrieve_similar_visuals(
+                    db=db,
+                    image_url=tool_call.arguments.get("image_url"),
+                    limit=tool_call.arguments.get("limit", 10),
+                )
+                tool_call.result = [
+                    {
+                        "place_id": r.place_id,
+                        "name": r.name,
+                        "category": r.category,
+                        "rating": r.rating,
+                        "similarity": r.similarity,
+                        "matched_images": r.matched_images,
+                        "image_url": r.image_url,
+                    }
+                    for r in results
+                ]
+
+            elif tool_call.tool_name == "find_nearby_places":
+                results = await self.tools.find_nearby_places(
+                    lat=tool_call.arguments.get("lat", DANANG_CENTER[0]),
+                    lng=tool_call.arguments.get("lng", DANANG_CENTER[1]),
+                    max_distance_km=tool_call.arguments.get("max_distance_km", 5.0),
+                    category=tool_call.arguments.get("category"),
+                    limit=tool_call.arguments.get("limit", 10),
+                )
+                tool_call.result = [
+                    {
+                        "place_id": r.place_id,
+                        "name": r.name,
+                        "category": r.category,
+                        "distance_km": r.distance_km,
+                        "rating": r.rating,
+                        "description": r.description,
+                    }
+                    for r in results
+                ]
+
+        except Exception as e:
+            agent_logger.error(f"Tool execution failed: {tool_call.tool_name}", e)
+            tool_call.result = [{"error": str(e)}]
+
+        return tool_call
+
+    async def _synthesize_response(
+        self,
+        message: str,
+        tool_results: list[ToolCall],
+        image_url: str | None = None,
+        history: str | None = None,
+    ) -> str:
+        """Synthesize final response from tool results with conversation history."""
+        # Build context from tool results
+        context_parts = []
+        for tool_call in tool_results:
+            if tool_call.result:
+                context_parts.append(
+                    f"Kết quả từ {tool_call.tool_name}:\n{json.dumps(tool_call.result, ensure_ascii=False, indent=2)}"
+                )
+
+        context = "\n\n".join(context_parts) if context_parts else "Không tìm thấy kết quả phù hợp."
+
+        # Build history section if available
+        history_section = ""
+        if history:
+            history_section = f"""Lịch sử hội thoại trước đó:
+{history}
+
+---
+"""
+
+        # Generate response using LLM
+        prompt = f"""{history_section}Dựa trên kết quả tìm kiếm sau, hãy trả lời câu hỏi của người dùng một cách tự nhiên và hữu ích.
+
+Câu hỏi hiện tại: {message}
+
+{context}
+
+Hãy trả lời bằng tiếng Việt, thân thiện. Nếu có nhiều kết quả, hãy giới thiệu top 2-3 địa điểm phù hợp nhất.
+Nếu có lịch sử hội thoại, hãy cân nhắc ngữ cảnh trước đó khi trả lời."""
+
+        agent_logger.llm_call(self.provider, self.model or "default", prompt[:100])
+
+        response = await self.llm_client.generate(
+            prompt=prompt,
+            temperature=0.7,
+            system_instruction=SYSTEM_PROMPT,
+        )
+
+        return response
+
+    def _extract_location(self, message: str) -> str | None:
+        """Extract location name from message using pattern matching."""
+        known_locations = {
+            "mỹ khê": "My Khe Beach",
+            "my khe": "My Khe Beach",
+            "bãi biển mỹ khê": "My Khe Beach",
+            "cầu rồng": "Dragon Bridge",
+            "cau rong": "Dragon Bridge",
+            "dragon bridge": "Dragon Bridge",
+            "bà nà": "Ba Na Hills",
+            "ba na": "Ba Na Hills",
+            "bà nà hills": "Ba Na Hills",
+            "sơn trà": "Son Tra Peninsula",
+            "son tra": "Son Tra Peninsula",
+            "hội an": "Hoi An",
+            "hoi an": "Hoi An",
+            "ngũ hành sơn": "Marble Mountains",
+            "ngu hanh son": "Marble Mountains",
+            "marble mountains": "Marble Mountains",
+        }
+        
+        message_lower = message.lower()
+        for pattern, location in known_locations.items():
+            if pattern in message_lower:
+                return location
+        
+        return None
+
+    def _extract_category(self, message: str) -> str | None:
+        """Extract place category from message."""
+        categories = {
+            "cafe": ["cafe", "cà phê", "coffee"],
+            "restaurant": ["nhà hàng", "quán ăn", "restaurant", "ăn"],
+            "beach": ["bãi biển", "beach", "biển"],
+            "attraction": ["điểm tham quan", "du lịch", "attraction"],
+            "hotel": ["khách sạn", "hotel", "lưu trú"],
+            "bar": ["bar", "pub", "quán bar"],
+        }
+
+        message_lower = message.lower()
+        for category, keywords in categories.items():
+            if any(kw in message_lower for kw in keywords):
+                return category
+
+        return None
+
+    def clear_history(self) -> None:
+        """Clear conversation history."""
+        self.conversation_history = []
+
+
+# Default agent instance (using MegaLLM)
+mmca_agent = MMCAAgent()

app/agent/react_agent.py

@@ -0,0 +1,335 @@
+"""ReAct Agent - Multi-step reasoning and tool execution.
+
+Implements the ReAct (Reasoning + Acting) pattern:
+1. Reason about what to do next
+2. Execute a tool
+3. Observe the result
+4. Repeat until done or max steps reached
+"""
+
+import time
+import json
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.agent.state import AgentState, ReActStep
+from app.agent.reasoning import (
+    REACT_SYSTEM_PROMPT,
+    parse_reasoning_response,
+    build_reasoning_prompt,
+    get_tool_purpose,
+)
+from app.mcp.tools import mcp_tools
+from app.shared.integrations.gemini_client import GeminiClient
+from app.shared.integrations.megallm_client import MegaLLMClient
+from app.shared.logger import agent_logger, AgentWorkflow, WorkflowStep
+
+
+# Default coordinates for Da Nang
+DANANG_CENTER = (16.0544, 108.2022)
+
+
+class ReActAgent:
+    """
+    ReAct Agent with multi-step tool chaining.
+    
+    Allows LLM to reason about each step and decide which tool to call next,
+    using previous results to inform subsequent actions.
+    """
+    
+    def __init__(self, provider: str = "MegaLLM", model: str | None = None, max_steps: int = 5):
+        """
+        Initialize ReAct agent.
+        
+        Args:
+            provider: "Google" or "MegaLLM"
+            model: Model name
+            max_steps: Maximum reasoning steps (default 5)
+        """
+        self.provider = provider
+        self.model = model
+        self.max_steps = max_steps
+        self.tools = mcp_tools
+        
+        # Initialize LLM client
+        if provider == "Google":
+            self.llm_client = GeminiClient(model=model)
+        else:
+            self.llm_client = MegaLLMClient(model=model)
+        
+        agent_logger.workflow_step(
+            "ReAct Agent initialized",
+            f"Provider: {provider}, Model: {model}, MaxSteps: {max_steps}"
+        )
+    
+    async def run(
+        self,
+        query: str,
+        db: AsyncSession,
+        image_url: str | None = None,
+        history: str | None = None,
+    ) -> tuple[str, AgentState]:
+        """
+        Run the ReAct loop.
+        
+        Args:
+            query: User's query
+            db: Database session
+            image_url: Optional image for visual search
+            history: Conversation history
+            
+        Returns:
+            Tuple of (final_response, agent_state)
+        """
+        start_time = time.time()
+        
+        # Initialize state
+        state = AgentState(query=query, max_steps=self.max_steps)
+        
+        agent_logger.api_request(
+            endpoint="/chat (ReAct)",
+            method="POST",
+            body={"query": query[:100], "max_steps": self.max_steps}
+        )
+        
+        # ReAct loop
+        while state.can_continue():
+            step_start = time.time()
+            step_number = state.current_step + 1
+            
+            agent_logger.workflow_step(f"ReAct Step {step_number}", "Reasoning...")
+            
+            try:
+                # Step 1: Reason about what to do next
+                reasoning = await self._reason(state, image_url)
+                
+                agent_logger.workflow_step(
+                    f"Step {step_number} Thought",
+                    reasoning.thought[:100]
+                )
+                agent_logger.workflow_step(
+                    f"Step {step_number} Action",
+                    f"{reasoning.action} → {json.dumps(reasoning.action_input, ensure_ascii=False)[:80]}"
+                )
+                
+                # Step 2: Check if done
+                if reasoning.action == "finish":
+                    state.is_complete = True
+                    state.steps.append(ReActStep(
+                        step_number=step_number,
+                        thought=reasoning.thought,
+                        action="finish",
+                        action_input={},
+                        duration_ms=(time.time() - step_start) * 1000,
+                    ))
+                    break
+                
+                # Step 3: Execute tool
+                observation = await self._execute_tool(
+                    reasoning.action,
+                    reasoning.action_input,
+                    db,
+                    image_url,
+                )
+                
+                result_count = len(observation) if isinstance(observation, list) else 1
+                agent_logger.tool_result(reasoning.action, result_count)
+                
+                # Step 4: Add step to state
+                step = ReActStep(
+                    step_number=step_number,
+                    thought=reasoning.thought,
+                    action=reasoning.action,
+                    action_input=reasoning.action_input,
+                    observation=observation,
+                    duration_ms=(time.time() - step_start) * 1000,
+                )
+                state.add_step(step)
+                
+            except Exception as e:
+                agent_logger.error(f"ReAct step {step_number} failed", e)
+                state.error = str(e)
+                break
+        
+        # Final synthesis
+        state.total_duration_ms = (time.time() - start_time) * 1000
+        
+        if state.error:
+            final_response = f"Xin lỗi, đã xảy ra lỗi: {state.error}"
+        else:
+            final_response = await self._synthesize(state, history)
+        
+        state.final_answer = final_response
+        
+        agent_logger.api_response(
+            "/chat (ReAct)",
+            200,
+            {"steps": len(state.steps), "tools": list(state.context.keys())},
+            state.total_duration_ms,
+        )
+        
+        return final_response, state
+    
+    async def _reason(self, state: AgentState, image_url: str | None = None) -> Any:
+        """Get LLM reasoning for next step."""
+        prompt = build_reasoning_prompt(
+            query=state.query,
+            context_summary=state.get_context_summary(),
+            previous_steps=[s.to_dict() for s in state.steps],
+            image_url=image_url,
+        )
+        
+        agent_logger.llm_call(self.provider, self.model or "default", prompt[:100])
+        
+        response = await self.llm_client.generate(
+            prompt=prompt,
+            temperature=0.3,  # Lower temp for more deterministic reasoning
+            system_instruction=REACT_SYSTEM_PROMPT,
+        )
+        
+        return parse_reasoning_response(response)
+    
+    async def _execute_tool(
+        self,
+        action: str,
+        action_input: dict,
+        db: AsyncSession,
+        image_url: str | None = None,
+    ) -> Any:
+        """Execute a tool and return observation."""
+        agent_logger.tool_call(action, action_input)
+        
+        if action == "get_location_coordinates":
+            location_name = action_input.get("location_name", "")
+            coords = await self.tools.get_location_coordinates(location_name)
+            if coords:
+                return {"lat": coords[0], "lng": coords[1], "location": location_name}
+            return {"error": f"Location not found: {location_name}"}
+        
+        elif action == "find_nearby_places":
+            lat = action_input.get("lat", DANANG_CENTER[0])
+            lng = action_input.get("lng", DANANG_CENTER[1])
+            
+            # If lat/lng are from previous step context
+            if isinstance(lat, str) or isinstance(lng, str):
+                lat, lng = DANANG_CENTER
+            
+            results = await self.tools.find_nearby_places(
+                lat=lat,
+                lng=lng,
+                max_distance_km=action_input.get("max_distance_km", 3.0),
+                category=action_input.get("category"),
+                limit=action_input.get("limit", 5),
+            )
+            return [
+                {
+                    "place_id": r.place_id,
+                    "name": r.name,
+                    "category": r.category,
+                    "distance_km": r.distance_km,
+                    "rating": r.rating,
+                }
+                for r in results
+            ]
+        
+        elif action == "retrieve_context_text":
+            results = await self.tools.retrieve_context_text(
+                db=db,
+                query=action_input.get("query", ""),
+                limit=action_input.get("limit", 5),
+            )
+            return [
+                {
+                    "place_id": r.place_id,
+                    "name": r.name,
+                    "category": r.category,
+                    "rating": r.rating,
+                    "source_text": r.source_text[:100] if r.source_text else "",
+                }
+                for r in results
+            ]
+        
+        elif action == "retrieve_similar_visuals":
+            url = action_input.get("image_url") or image_url
+            if not url:
+                return {"error": "No image URL provided"}
+            
+            results = await self.tools.retrieve_similar_visuals(
+                db=db,
+                image_url=url,
+                limit=action_input.get("limit", 5),
+            )
+            return [
+                {
+                    "place_id": r.place_id,
+                    "name": r.name,
+                    "category": r.category,
+                    "similarity": r.similarity,
+                }
+                for r in results
+            ]
+        
+        else:
+            return {"error": f"Unknown tool: {action}"}
+    
+    async def _synthesize(self, state: AgentState, history: str | None = None) -> str:
+        """Synthesize final response from all collected information."""
+        # Build context from all steps
+        context_parts = []
+        for step in state.steps:
+            if step.observation and step.action != "finish":
+                context_parts.append(
+                    f"Kết quả từ {step.action}:\n{json.dumps(step.observation, ensure_ascii=False, indent=2)}"
+                )
+        
+        context = "\n\n".join(context_parts) if context_parts else "Không có kết quả."
+        
+        # Build history section
+        history_section = ""
+        if history:
+            history_section = f"Lịch sử hội thoại:\n{history}\n\n---\n"
+        
+        # Build steps summary
+        steps_summary = "\n".join([
+            f"- Bước {s.step_number}: {s.thought[:60]}... → {get_tool_purpose(s.action)}"
+            for s in state.steps
+        ])
+        
+        prompt = f"""{history_section}Dựa trên các bước suy luận và tìm kiếm sau:
+
+{steps_summary}
+
+Và kết quả thu thập được:
+{context}
+
+Hãy trả lời câu hỏi của user một cách tự nhiên và hữu ích:
+"{state.query}"
+
+Trả lời tiếng Việt, thân thiện. Giới thiệu top 2-3 địa điểm phù hợp nhất với thông tin cụ thể."""
+
+        response = await self.llm_client.generate(
+            prompt=prompt,
+            temperature=0.7,
+            system_instruction="Bạn là trợ lý du lịch thông minh cho Đà Nẵng. Trả lời ngắn gọn, hữu ích.",
+        )
+        
+        return response
+    
+    def to_workflow(self, state: AgentState) -> AgentWorkflow:
+        """Convert AgentState to AgentWorkflow for response."""
+        workflow = AgentWorkflow(query=state.query)
+        workflow.intent_detected = "react_multi_step"
+        workflow.total_duration_ms = state.total_duration_ms
+        workflow.tools_used = list(state.context.keys())
+        
+        for step in state.steps:
+            workflow.add_step(WorkflowStep(
+                step_name=f"Step {step.step_number}: {step.thought[:50]}...",
+                tool_name=step.action if step.action != "finish" else None,
+                purpose=get_tool_purpose(step.action),
+                result_count=len(step.observation) if isinstance(step.observation, list) else 0,
+                duration_ms=step.duration_ms,
+            ))
+        
+        return workflow

app/agent/reasoning.py

@@ -0,0 +1,162 @@
+"""ReAct Reasoning Module - Prompts and parsing for multi-step reasoning."""
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from app.shared.logger import agent_logger
+
+
+# System prompt for ReAct mode
+REACT_SYSTEM_PROMPT = """Bạn là agent du lịch thông minh cho Đà Nẵng với khả năng suy luận multi-step.
+
+**Tools có sẵn:**
+1. `get_location_coordinates` - Lấy tọa độ từ tên địa điểm
+   - Input: {"location_name": "Dragon Bridge"}
+   - Output: {"lat": 16.06, "lng": 108.22}
+
+2. `find_nearby_places` - Tìm địa điểm gần vị trí
+   - Input: {"lat": 16.06, "lng": 108.22, "category": "cafe", "max_distance_km": 3}
+   - Output: [{name, category, distance_km, rating}]
+
+3. `retrieve_context_text` - Tìm semantic trong reviews/descriptions
+   - Input: {"query": "cafe view đẹp", "limit": 5}
+   - Output: [{name, category, rating, source_text}]
+
+4. `retrieve_similar_visuals` - Tìm địa điểm có hình ảnh tương tự
+   - Input: {"image_url": "..."}
+   - Output: [{name, similarity, image_url}]
+
+**Quy trình:**
+Với mỗi bước, bạn phải:
+1. **Thought**: Suy nghĩ về bước tiếp theo cần làm
+2. **Action**: Chọn tool hoặc "finish" nếu đủ thông tin
+3. **Action Input**: JSON parameters cho tool
+
+**Trả lời CHÍNH XÁC theo format JSON:**
+```json
+{
+  "thought": "Suy nghĩ của bạn...",
+  "action": "tool_name hoặc finish",
+  "action_input": {"param1": "value1"}
+}
+```
+
+**Quan trọng:**
+- Nếu cần biết vị trí → dùng get_location_coordinates trước
+- Nếu tìm theo khoảng cách → dùng find_nearby_places
+- Nếu cần lọc theo đặc điểm (view, không gian, giá) → dùng retrieve_context_text
+- Khi đủ thông tin → action = "finish"
+"""
+
+
+@dataclass
+class ReasoningResult:
+    """Result from LLM reasoning step."""
+    
+    thought: str
+    action: str
+    action_input: dict
+    raw_response: str
+    parse_error: str | None = None
+
+
+def parse_reasoning_response(response: str) -> ReasoningResult:
+    """
+    Parse LLM response into thought/action/action_input.
+    
+    Handles various formats:
+    - Clean JSON
+    - JSON in markdown code blocks
+    - Partial/malformed JSON
+    """
+    raw = response.strip()
+    
+    # Try to extract JSON from code blocks
+    json_match = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', raw, re.DOTALL)
+    if json_match:
+        raw = json_match.group(1)
+    
+    # Try to find JSON object
+    json_start = raw.find('{')
+    json_end = raw.rfind('}')
+    if json_start != -1 and json_end != -1:
+        raw = raw[json_start:json_end + 1]
+    
+    try:
+        data = json.loads(raw)
+        return ReasoningResult(
+            thought=data.get("thought", ""),
+            action=data.get("action", "finish"),
+            action_input=data.get("action_input", {}),
+            raw_response=response,
+        )
+    except json.JSONDecodeError as e:
+        agent_logger.error(f"Failed to parse reasoning response", e)
+        
+        # Fallback: try to extract key fields with regex
+        thought_match = re.search(r'"thought"\s*:\s*"([^"]*)"', raw)
+        action_match = re.search(r'"action"\s*:\s*"([^"]*)"', raw)
+        
+        thought = thought_match.group(1) if thought_match else "Parse error"
+        action = action_match.group(1) if action_match else "finish"
+        
+        return ReasoningResult(
+            thought=thought,
+            action=action,
+            action_input={},
+            raw_response=response,
+            parse_error=str(e),
+        )
+
+
+def build_reasoning_prompt(
+    query: str,
+    context_summary: str,
+    previous_steps: list[dict],
+    image_url: str | None = None,
+) -> str:
+    """Build the prompt for the next reasoning step."""
+    
+    # Previous steps summary
+    steps_text = ""
+    if previous_steps:
+        steps_text = "\n**Các bước đã thực hiện:**\n"
+        for step in previous_steps:
+            steps_text += f"- Step {step['step']}: {step['thought'][:80]}...\n"
+            steps_text += f"  Action: {step['action']} → {len(step.get('observation', [])) if isinstance(step.get('observation'), list) else 'done'} kết quả\n"
+    
+    # Image context
+    image_text = ""
+    if image_url:
+        image_text = "\n**Lưu ý:** User đã gửi kèm ảnh. Có thể dùng retrieve_similar_visuals nếu cần.\n"
+    
+    prompt = f"""**Câu hỏi của user:** {query}
+{image_text}
+{context_summary}
+{steps_text}
+**Bước tiếp theo là gì?**
+
+Trả lời theo format JSON:
+```json
+{{
+  "thought": "...",
+  "action": "tool_name hoặc finish",
+  "action_input": {{...}}
+}}
+```"""
+    
+    return prompt
+
+
+def get_tool_purpose(action: str) -> str:
+    """Get human-readable purpose for a tool."""
+    purposes = {
+        "get_location_coordinates": "Lấy tọa độ địa điểm",
+        "find_nearby_places": "Tìm địa điểm gần vị trí",
+        "retrieve_context_text": "Tìm theo văn bản (reviews, mô tả)",
+        "retrieve_similar_visuals": "Tìm theo hình ảnh tương tự",
+        "finish": "Hoàn thành và tổng hợp kết quả",
+    }
+    return purposes.get(action, action)

app/agent/state.py

@@ -0,0 +1,96 @@
+"""Agent State Models - State management for ReAct multi-step reasoning."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class ReActStep:
+    """A single step in the ReAct reasoning loop."""
+    
+    step_number: int
+    thought: str  # LLM's reasoning about what to do
+    action: str  # Tool name or "finish"
+    action_input: dict  # Tool arguments
+    observation: Any = None  # Tool result
+    duration_ms: float = 0
+    timestamp: datetime = field(default_factory=datetime.now)
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for serialization."""
+        return {
+            "step": self.step_number,
+            "thought": self.thought,
+            "action": self.action,
+            "action_input": self.action_input,
+            "observation": self._truncate_observation(),
+            "duration_ms": round(self.duration_ms, 1),
+        }
+    
+    def _truncate_observation(self, max_items: int = 3) -> Any:
+        """Truncate observation for display."""
+        if isinstance(self.observation, list) and len(self.observation) > max_items:
+            return self.observation[:max_items] + [f"... and {len(self.observation) - max_items} more"]
+        return self.observation
+
+
+@dataclass
+class AgentState:
+    """Complete state for a ReAct agent session."""
+    
+    query: str
+    steps: list[ReActStep] = field(default_factory=list)
+    context: dict = field(default_factory=dict)  # Accumulated context from tools
+    current_step: int = 0
+    max_steps: int = 5
+    is_complete: bool = False
+    final_answer: str = ""
+    total_duration_ms: float = 0
+    error: str | None = None
+    
+    def add_step(self, step: ReActStep) -> None:
+        """Add a completed step to the state."""
+        self.steps.append(step)
+        self.current_step += 1
+        
+        # Add tool result to context
+        if step.action != "finish" and step.observation:
+            self.context[step.action] = step.observation
+    
+    def can_continue(self) -> bool:
+        """Check if agent can continue reasoning."""
+        return (
+            not self.is_complete
+            and self.current_step < self.max_steps
+            and self.error is None
+        )
+    
+    def get_context_summary(self) -> str:
+        """Get a summary of accumulated context for LLM."""
+        if not self.context:
+            return "Chưa có kết quả từ các tools trước đó."
+        
+        summary_parts = []
+        for tool_name, result in self.context.items():
+            if isinstance(result, list):
+                summary_parts.append(f"- {tool_name}: {len(result)} kết quả")
+            elif isinstance(result, dict):
+                summary_parts.append(f"- {tool_name}: {result}")
+            else:
+                summary_parts.append(f"- {tool_name}: {str(result)[:100]}")
+        
+        return "Kết quả từ các bước trước:\n" + "\n".join(summary_parts)
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for API response."""
+        return {
+            "query": self.query,
+            "total_steps": len(self.steps),
+            "max_steps": self.max_steps,
+            "is_complete": self.is_complete,
+            "steps": [s.to_dict() for s in self.steps],
+            "tools_used": list(self.context.keys()),
+            "total_duration_ms": round(self.total_duration_ms, 1),
+            "error": self.error,
+        }

app/api/__init__.py

@@ -0,0 +1 @@
+"""API module."""

app/api/router.py

@@ -0,0 +1,469 @@
+"""API Router with /chat endpoint for Swagger testing."""
+
+from enum import Enum
+from pydantic import BaseModel, Field
+from fastapi import APIRouter, Depends, UploadFile, File, Query, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.agent.mmca_agent import MMCAAgent
+from app.agent.react_agent import ReActAgent
+from app.shared.db.session import get_db
+from app.core.config import settings
+from app.mcp.tools import mcp_tools
+from app.shared.chat_history import chat_history
+
+
+router = APIRouter()
+
+
+class LLMProvider(str, Enum):
+    """Available LLM providers."""
+
+    GOOGLE = "Google"
+    MEGALLM = "MegaLLM"
+
+
+class ChatRequest(BaseModel):
+    """Chat request model."""
+
+    message: str = Field(
+        ...,
+        description="User message in natural language",
+        examples=["Tìm quán cafe gần bãi biển Mỹ Khê"],
+    )
+    user_id: str = Field(
+        default="anonymous",
+        description="User ID for session management",
+        examples=["user_123", "anonymous"],
+    )
+    session_id: str | None = Field(
+        None,
+        description="Session ID (optional, uses 'default' if not provided)",
+        examples=["session_abc", "default"],
+    )
+    image_url: str | None = Field(
+        None,
+        description="Optional image URL for visual similarity search",
+        examples=["https://example.com/cafe.jpg"],
+    )
+    provider: LLMProvider = Field(
+        default=LLMProvider.MEGALLM,
+        description="LLM provider to use: Google or MegaLLM",
+    )
+    model: str | None = Field(
+        None,
+        description=f"Model name. Defaults: Google={settings.default_gemini_model}, MegaLLM={settings.default_megallm_model}",
+        examples=["gemini-2.0-flash", "deepseek-r1-distill-llama-70b"],
+    )
+    react_mode: bool = Field(
+        default=False,
+        description="Enable ReAct multi-step reasoning mode",
+    )
+    max_steps: int = Field(
+        default=5,
+        description="Maximum reasoning steps for ReAct mode",
+        ge=1,
+        le=10,
+    )
+
+
+class WorkflowStepResponse(BaseModel):
+    """Workflow step info."""
+
+    step: str = Field(..., description="Step name")
+    tool: str | None = Field(None, description="Tool used")
+    purpose: str = Field(default="", description="Purpose of this step")
+    results: int = Field(default=0, description="Number of results")
+
+
+class WorkflowResponse(BaseModel):
+    """Workflow trace for debugging."""
+
+    query: str = Field(..., description="Original query")
+    intent_detected: str = Field(..., description="Detected intent")
+    tools_used: list[str] = Field(default_factory=list, description="Tools used")
+    steps: list[WorkflowStepResponse] = Field(default_factory=list, description="Workflow steps")
+    total_duration_ms: float = Field(..., description="Total processing time")
+
+
+class ChatResponse(BaseModel):
+    """Chat response model with workflow trace."""
+
+    response: str = Field(..., description="Agent's response")
+    status: str = Field(default="success", description="Response status")
+    provider: str = Field(..., description="LLM provider used")
+    model: str = Field(..., description="Model used")
+    user_id: str = Field(..., description="User ID")
+    session_id: str = Field(..., description="Session ID used")
+    workflow: WorkflowResponse | None = Field(None, description="Workflow trace for debugging")
+    tools_used: list[str] = Field(default_factory=list, description="MCP tools used")
+    duration_ms: float = Field(default=0, description="Total processing time in ms")
+
+
+class NearbyRequest(BaseModel):
+    """Nearby places request model."""
+
+    lat: float = Field(..., description="Latitude", examples=[16.0626442])
+    lng: float = Field(..., description="Longitude", examples=[108.2462143])
+    max_distance_km: float = Field(
+        default=5.0,
+        description="Maximum distance in kilometers",
+        examples=[5.0, 18.72],
+    )
+    category: str | None = Field(
+        None,
+        description="Category filter (cafe, restaurant, attraction, etc.)",
+        examples=["cafe", "restaurant"],
+    )
+    limit: int = Field(default=10, description="Maximum results", examples=[10, 20])
+
+
+class PlaceResponse(BaseModel):
+    """Place response model."""
+
+    place_id: str
+    name: str
+    category: str | None = None
+    lat: float | None = None
+    lng: float | None = None
+    distance_km: float | None = None
+    rating: float | None = None
+    description: str | None = None
+
+
+class NearbyResponse(BaseModel):
+    """Nearby places response model."""
+
+    places: list[PlaceResponse]
+    count: int
+    query: dict
+
+
+class ClearHistoryRequest(BaseModel):
+    """Clear history request model."""
+
+    user_id: str = Field(..., description="User ID to clear history for")
+    session_id: str | None = Field(
+        None,
+        description="Session ID to clear (clears all if not provided)",
+    )
+
+
+class HistoryResponse(BaseModel):
+    """Chat history response model."""
+
+    user_id: str
+    sessions: list[str]
+    current_session: str | None
+    message_count: int
+
+
+@router.post(
+    "/nearby",
+    response_model=NearbyResponse,
+    summary="Find nearby places (Neo4j)",
+    description="""
+Find places near a given location using Neo4j spatial query.
+
+This endpoint directly tests the `find_nearby_places` MCP tool.
+
+## Test Cases
+- Case 1: lat=16.0626442, lng=108.2462143, max_distance_km=18.72
+- Case 2: lat=16.0623184, lng=108.2306049, max_distance_km=17.94
+""",
+)
+async def find_nearby(request: NearbyRequest) -> NearbyResponse:
+    """
+    Find nearby places using Neo4j graph database.
+
+    Directly calls the find_nearby_places MCP tool.
+    """
+    places = await mcp_tools.find_nearby_places(
+        lat=request.lat,
+        lng=request.lng,
+        max_distance_km=request.max_distance_km,
+        category=request.category,
+        limit=request.limit,
+    )
+
+    return NearbyResponse(
+        places=[
+            PlaceResponse(
+                place_id=p.place_id,
+                name=p.name,
+                category=p.category,
+                lat=p.lat,
+                lng=p.lng,
+                distance_km=p.distance_km,
+                rating=p.rating,
+                description=p.description,
+            )
+            for p in places
+        ],
+        count=len(places),
+        query={
+            "lat": request.lat,
+            "lng": request.lng,
+            "max_distance_km": request.max_distance_km,
+            "category": request.category,
+        },
+    )
+
+
+@router.post(
+    "/chat",
+    response_model=ChatResponse,
+    summary="Chat with LocalMate Agent",
+    description="""
+Chat with the Multi-Modal Contextual Agent (MMCA).
+
+## Session Management
+- Each user can have up to **3 sessions** stored
+- Provide `user_id` and optional `session_id` to maintain conversation history
+- History is automatically injected into the agent prompt
+
+## LLM Providers
+- **Google**: Gemini models (gemini-2.0-flash, etc.)
+- **MegaLLM**: DeepSeek models (deepseek-r1-distill-llama-70b, etc.)
+
+## Examples
+- "Tìm quán cafe gần bãi biển Mỹ Khê"
+- "Nhà hàng hải sản nào gần Cầu Rồng?"
+""",
+)
+async def chat(
+    request: ChatRequest,
+    db: AsyncSession = Depends(get_db),
+) -> ChatResponse:
+    """
+    Chat endpoint with per-user history support.
+
+    Send a natural language message, select provider and model.
+    The agent will analyze your intent, query relevant data sources,
+    and return a synthesized response with conversation context.
+    """
+    # Determine model to use
+    if request.model:
+        model = request.model
+    elif request.provider == LLMProvider.GOOGLE:
+        model = settings.default_gemini_model
+    else:
+        model = settings.default_megallm_model
+
+    # Get session ID
+    session_id = request.session_id or "default"
+
+    # Get conversation history for context
+    history = chat_history.get_history(
+        user_id=request.user_id,
+        session_id=session_id,
+        max_messages=6,  # Last 3 exchanges (6 messages)
+    )
+
+    # Add user message to history
+    chat_history.add_message(
+        user_id=request.user_id,
+        role="user",
+        content=request.message,
+        session_id=session_id,
+    )
+
+    # Choose agent based on react_mode
+    if request.react_mode:
+        # ReAct multi-step agent
+        agent = ReActAgent(
+            provider=request.provider.value,
+            model=model,
+            max_steps=request.max_steps,
+        )
+        response_text, agent_state = await agent.run(
+            query=request.message,
+            db=db,
+            image_url=request.image_url,
+            history=history,
+        )
+        
+        # Convert state to workflow
+        workflow = agent.to_workflow(agent_state)
+        workflow_data = workflow.to_dict()
+        
+        # Add assistant response to history
+        chat_history.add_message(
+            user_id=request.user_id,
+            role="assistant",
+            content=response_text,
+            session_id=session_id,
+        )
+        
+        workflow_response = WorkflowResponse(
+            query=workflow_data["query"],
+            intent_detected=workflow_data["intent_detected"],
+            tools_used=workflow_data["tools_used"],
+            steps=[WorkflowStepResponse(**s) for s in workflow_data["steps"]],
+            total_duration_ms=workflow_data["total_duration_ms"],
+        )
+        
+        return ChatResponse(
+            response=response_text,
+            status="success",
+            provider=request.provider.value,
+            model=model,
+            user_id=request.user_id,
+            session_id=session_id,
+            workflow=workflow_response,
+            tools_used=workflow.tools_used,
+            duration_ms=agent_state.total_duration_ms,
+        )
+    
+    else:
+        # Single-step agent (original behavior)
+        agent = MMCAAgent(provider=request.provider.value, model=model)
+
+        # Pass history to agent
+        result = await agent.chat(
+            message=request.message,
+            db=db,
+            image_url=request.image_url,
+            history=history,
+        )
+
+        # Add assistant response to history
+        chat_history.add_message(
+            user_id=request.user_id,
+            role="assistant",
+            content=result.response,
+            session_id=session_id,
+        )
+
+        # Build workflow response
+        workflow_data = result.workflow.to_dict()
+        workflow_response = WorkflowResponse(
+            query=workflow_data["query"],
+            intent_detected=workflow_data["intent_detected"],
+            tools_used=workflow_data["tools_used"],
+            steps=[WorkflowStepResponse(**s) for s in workflow_data["steps"]],
+            total_duration_ms=workflow_data["total_duration_ms"],
+        )
+
+        return ChatResponse(
+            response=result.response,
+            status="success",
+            provider=request.provider.value,
+            model=model,
+            user_id=request.user_id,
+            session_id=session_id,
+            workflow=workflow_response,
+            tools_used=result.tools_used,
+            duration_ms=result.total_duration_ms,
+        )
+
+
+@router.post(
+    "/chat/clear",
+    summary="Clear chat history",
+    description="Clears the conversation history for a specific user/session.",
+)
+async def clear_chat(request: ClearHistoryRequest):
+    """Clear conversation history for a user."""
+    if request.session_id:
+        chat_history.clear_session(request.user_id, request.session_id)
+        message = f"Session '{request.session_id}' cleared for user '{request.user_id}'"
+    else:
+        chat_history.clear_all_sessions(request.user_id)
+        message = f"All sessions cleared for user '{request.user_id}'"
+
+    return {"status": "success", "message": message}
+
+
+@router.get(
+    "/chat/history/{user_id}",
+    response_model=HistoryResponse,
+    summary="Get chat history info",
+    description="Get information about user's chat sessions.",
+)
+async def get_history_info(user_id: str) -> HistoryResponse:
+    """Get chat history information for a user."""
+    sessions = chat_history.get_session_ids(user_id)
+    messages = chat_history.get_messages(user_id)
+
+    return HistoryResponse(
+        user_id=user_id,
+        sessions=sessions,
+        current_session="default" if "default" in sessions else (sessions[0] if sessions else None),
+        message_count=len(messages),
+    )
+
+
+class ImageSearchResult(BaseModel):
+    """Image search result model."""
+
+    place_id: str
+    name: str
+    category: str | None = None
+    rating: float | None = None
+    similarity: float
+    matched_images: int = 1
+    image_url: str | None = None
+
+
+class ImageSearchResponse(BaseModel):
+    """Image search response model."""
+
+    results: list[ImageSearchResult]
+    total: int
+
+
+@router.post(
+    "/search/image",
+    response_model=ImageSearchResponse,
+    summary="Search places by image",
+    description="""
+Upload an image to find visually similar places.
+
+Uses image embeddings stored in Supabase pgvector.
+""",
+)
+async def search_by_image(
+    image: UploadFile = File(..., description="Image file to search"),
+    limit: int = Query(10, ge=1, le=50, description="Maximum results"),
+    db: AsyncSession = Depends(get_db),
+) -> ImageSearchResponse:
+    """
+    Search places by uploading an image.
+
+    Uses visual embeddings to find similar places.
+    """
+    try:
+        # Read image bytes
+        image_bytes = await image.read()
+
+        if len(image_bytes) > 10 * 1024 * 1024:  # 10MB limit
+            raise HTTPException(status_code=400, detail="Image too large (max 10MB)")
+
+        # Search using visual tool
+        results = await mcp_tools.search_by_image_bytes(
+            db=db,
+            image_bytes=image_bytes,
+            limit=limit,
+        )
+
+        return ImageSearchResponse(
+            results=[
+                ImageSearchResult(
+                    place_id=r.place_id,
+                    name=r.name,
+                    category=r.category,
+                    rating=r.rating,
+                    similarity=r.similarity,
+                    matched_images=r.matched_images,
+                    image_url=r.image_url,
+                )
+                for r in results
+            ],
+            total=len(results),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Image search error: {str(e)}")
+

app/core/__init__.py

@@ -0,0 +1 @@
+"""Core module."""

app/core/config.py

@@ -0,0 +1,45 @@
+"""Core configuration for LocalMate v2."""
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment."""
+
+    # App
+    app_env: str = "local"
+    app_debug: bool = True
+
+    # Supabase
+    supabase_url: str
+    supabase_anon_key: str
+    supabase_service_role_key: str
+    database_url: str
+
+    # Neo4j
+    neo4j_uri: str
+    neo4j_username: str
+    neo4j_password: str
+
+    # Google AI
+    google_api_key: str
+
+    # MegaLLM (OpenAI-compatible)
+    megallm_api_key: str | None = None
+    megallm_base_url: str = "https://ai.megallm.io/v1"
+
+    # Optional: CLIP for image embeddings
+    huggingface_api_key: str | None = None
+
+    # Default model configs (can be overridden per request)
+    default_gemini_model: str = "gemini-2.0-flash"
+    default_megallm_model: str = "deepseek-ai/deepseek-v3.1-terminus"
+    embedding_model: str = "text-embedding-004"
+
+    class Config:
+        env_file = ".env"
+        extra = "ignore"
+
+
+settings = Settings()
+

app/main.py

@@ -0,0 +1,101 @@
+"""
+LocalMate Da Nang V2 - Multi-Modal Contextual Agent API.
+
+FastAPI application entry point with /chat endpoint for testing.
+"""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.router import router as api_router
+from app.planner.router import router as planner_router
+from app.shared.db.session import engine
+from app.shared.integrations.neo4j_client import neo4j_client
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan handler for startup/shutdown."""
+    # Startup - preload SigLIP model
+    try:
+        from app.shared.integrations.siglip_client import get_siglip_client
+        siglip = get_siglip_client()
+        print(f"✅ SigLIP ready: {siglip.is_loaded}")
+    except Exception as e:
+        print(f"⚠️ SigLIP not loaded (image search disabled): {e}")
+    
+    yield
+    
+    # Shutdown
+    await neo4j_client.close()
+    await engine.dispose()
+
+
+app = FastAPI(
+    title="LocalMate Da Nang V2",
+    description="""
+## Multi-Modal Contextual Agent (MMCA) API
+
+Intelligent travel assistant for Da Nang with 3 MCP tools + Trip Planner:
+
+### Tools Available:
+1. **retrieve_context_text** - Semantic search in text descriptions (reviews, menus)
+2. **retrieve_similar_visuals** - Image similarity search (find similar vibes)
+3. **find_nearby_places** - Spatial search (find places near a location)
+
+### Trip Planner:
+- Create plans and add places
+- Optimize route with TSP algorithm
+- Reorder, replace, and manage places
+
+### Examples:
+- "Tìm quán cafe gần bãi biển Mỹ Khê"
+- "Nhà hàng hải sản nào được review tốt?"
+- "Quán nào có không gian xanh mát?" (with image_url)
+""",
+    version="0.2.1",
+    lifespan=lifespan,
+)
+
+# CORS middleware - allow all for demo
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include API routers
+app.include_router(api_router, prefix="/api/v1", tags=["Chat"])
+app.include_router(planner_router, prefix="/api/v1", tags=["Trip Planner"])
+
+
+@app.get("/health", tags=["System"])
+async def health_check():
+    """
+    Health check endpoint.
+
+    Returns status of the application and connected services.
+    """
+    neo4j_ok = await neo4j_client.verify_connectivity()
+    return {
+        "status": "healthy",
+        "version": "0.2.0",
+        "services": {
+            "neo4j": "connected" if neo4j_ok else "disconnected",
+        },
+    }
+
+
+@app.get("/", tags=["System"])
+async def root():
+    """Root endpoint with API info."""
+    return {
+        "name": "LocalMate Da Nang V2 - MMCA API",
+        "version": "0.2.0",
+        "docs": "/docs",
+        "description": "Multi-Modal Contextual Agent for Da Nang Tourism",
+    }

app/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP module - Model Context Protocol tools."""

app/mcp/tools/__init__.py

@@ -0,0 +1,118 @@
+"""MCP Tools Package - Model Context Protocol tools for the agent.
+
+Tools:
+1. retrieve_context_text - Text search via pgvector + places_metadata
+2. retrieve_similar_visuals - Image search via pgvector + places_metadata  
+3. find_nearby_places - Neo4j spatial search + place details
+"""
+
+from app.mcp.tools.text_tool import (
+    TextSearchResult,
+    retrieve_context_text,
+    detect_category_intent,
+    TOOL_DEFINITION as TEXT_TOOL_DEFINITION,
+    CATEGORY_KEYWORDS,
+    CATEGORY_TO_DB,
+)
+from app.mcp.tools.visual_tool import (
+    ImageSearchResult,
+    retrieve_similar_visuals,
+    search_by_image_url,
+    search_by_image_bytes,
+    TOOL_DEFINITION as VISUAL_TOOL_DEFINITION,
+)
+from app.mcp.tools.graph_tool import (
+    PlaceResult,
+    PlaceDetails,
+    NearbyPlace,
+    Review,
+    AVAILABLE_CATEGORIES,
+    find_nearby_places,
+    get_place_details,
+    get_nearby_by_relationship,
+    get_same_category_places,
+    geocode_location,
+    get_location_coordinates,
+    TOOL_DEFINITION as GRAPH_TOOL_DEFINITION,
+)
+
+
+# Combined tool definitions for agent
+TOOL_DEFINITIONS = [
+    TEXT_TOOL_DEFINITION,
+    VISUAL_TOOL_DEFINITION,
+    GRAPH_TOOL_DEFINITION,
+]
+
+
+class MCPTools:
+    """
+    MCP Tools container implementing the 3 core tools for MMCA Agent.
+    """
+
+    TOOL_DEFINITIONS = TOOL_DEFINITIONS
+    AVAILABLE_CATEGORIES = AVAILABLE_CATEGORIES
+
+    # Text Tool
+    async def retrieve_context_text(self, db, query, limit=10, threshold=0.3):
+        """Semantic search in text descriptions."""
+        return await retrieve_context_text(db, query, limit, threshold)
+
+    # Visual Tool
+    async def retrieve_similar_visuals(self, db, image_url=None, image_bytes=None, limit=10, threshold=0.2):
+        """Visual similarity search using image embeddings."""
+        return await retrieve_similar_visuals(db, image_url, image_bytes, limit, threshold)
+
+    async def search_by_image_url(self, db, image_url, limit=10):
+        """Search places by image URL."""
+        return await search_by_image_url(db, image_url, limit)
+
+    async def search_by_image_bytes(self, db, image_bytes, limit=10):
+        """Search places by uploading image bytes."""
+        return await search_by_image_bytes(db, image_bytes, limit)
+
+    # Graph Tool
+    async def find_nearby_places(self, lat, lng, max_distance_km=5.0, category=None, limit=10):
+        """Find nearby places using Neo4j spatial query."""
+        return await find_nearby_places(lat, lng, max_distance_km, category, limit)
+
+    async def get_place_details(self, place_id, include_nearby=True, include_same_category=True, nearby_limit=5):
+        """Get complete place details with photos, reviews, and relationships."""
+        return await get_place_details(place_id, include_nearby, include_same_category, nearby_limit)
+
+    async def get_same_category_places(self, place_id, limit=5):
+        """Get other places in the same category."""
+        return await get_same_category_places(place_id, limit)
+
+    async def geocode_location(self, location_name, country="Vietnam"):
+        """Geocode a location using OpenStreetMap Nominatim."""
+        return await geocode_location(location_name, country)
+
+    async def get_location_coordinates(self, location_name):
+        """Get coordinates for a location (Neo4j + OSM fallback)."""
+        return await get_location_coordinates(location_name)
+
+
+# Global MCP tools instance
+mcp_tools = MCPTools()
+
+
+# Re-export for convenience
+__all__ = [
+    "MCPTools",
+    "mcp_tools",
+    "TextSearchResult",
+    "ImageSearchResult",
+    "PlaceResult",
+    "PlaceDetails",
+    "NearbyPlace",
+    "Review",
+    "retrieve_context_text",
+    "retrieve_similar_visuals",
+    "find_nearby_places",
+    "get_place_details",
+    "geocode_location",
+    "get_location_coordinates",
+    "TOOL_DEFINITIONS",
+    "AVAILABLE_CATEGORIES",
+]

app/mcp/tools/graph_tool.py

@@ -0,0 +1,433 @@
+"""Graph Tool - Neo4j spatial search with place details, relationships, and OSM geocoding.
+
+Features:
+- Spatial search (find nearby places by coordinates)
+- Place details with photos and reviews
+- Same category relationships
+- OpenStreetMap geocoding fallback
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Any
+
+import httpx
+
+from app.shared.integrations.neo4j_client import neo4j_client
+
+
+@dataclass
+class PlaceResult:
+    """Result from nearby places search."""
+
+    place_id: str
+    name: str
+    category: str
+    lat: float
+    lng: float
+    distance_km: float | None = None
+    rating: float | None = None
+    description: str | None = None
+
+
+@dataclass
+class NearbyPlace:
+    """Nearby place with distance."""
+
+    place_id: str
+    name: str
+    category: str
+    rating: float
+    distance_km: float
+
+
+@dataclass
+class Review:
+    """Place review."""
+
+    text: str
+    rating: int
+    reviewer: str
+
+
+@dataclass
+class PlaceDetails:
+    """Complete place details from Neo4j."""
+
+    place_id: str
+    name: str
+    category: str
+    rating: float
+    address: str
+    phone: str | None = None
+    website: str | None = None
+    google_maps_url: str | None = None
+    description: str | None = None
+    specialty: str | None = None
+    price_range: str | None = None
+    coordinates: dict[str, float] = field(default_factory=dict)
+    photos_count: int = 0
+    reviews_count: int = 0
+    photos: list[str] = field(default_factory=list)
+    reviews: list[Review] = field(default_factory=list)
+    nearby_places: list[NearbyPlace] = field(default_factory=list)
+    same_category: list[dict[str, Any]] = field(default_factory=list)
+
+
+# Available categories in Neo4j
+AVAILABLE_CATEGORIES = [
+    "Asian restaurant", "Athletic club", "Badminton court", "Bakery", "Bar",
+    "Bistro", "Board game club", "Breakfast restaurant", "Cafe",
+    "Cantonese restaurant", "Chicken restaurant", "Chinese restaurant",
+    "Cocktail bar", "Coffee shop", "Country food restaurant", "Deli",
+    "Dessert shop", "Disco club", "Dumpling restaurant", "Espresso bar",
+    "Family restaurant", "Fine dining restaurant", "Fitness center",
+    "Food court", "French restaurant", "Game store", "Gym",
+    "Hamburger restaurant", "Holiday apartment rental", "Hot pot restaurant",
+    "Hotel", "Ice cream shop", "Indian restaurant", "Irish pub",
+    "Italian restaurant", "Izakaya restaurant", "Japanese restaurant",
+    "Korean barbecue restaurant", "Korean restaurant", "Live music bar",
+    "Malaysian restaurant", "Mexican restaurant", "Movie theater",
+    "Musical club", "Noodle shop", "Pho restaurant", "Pickleball court",
+    "Pizza restaurant", "Ramen restaurant", "Restaurant", "Restaurant or cafe",
+    "Rice cake shop", "Sandwich shop", "Seafood restaurant", "Soccer field",
+    "Soup shop", "Sports bar", "Sports club", "Sports complex", "Steak house",
+    "Sushi restaurant", "Takeout Restaurant", "Tennis court", "Tiffin center",
+    "Udon noodle restaurant", "Vegan restaurant", "Vegetarian restaurant",
+    "Vietnamese restaurant",
+]
+
+
+# Tool definition for agent
+TOOL_DEFINITION = {
+    "name": "find_nearby_places",
+    "description": """Tìm địa điểm gần một vị trí hoặc lấy chi tiết địa điểm.
+
+Dùng khi:
+- Người dùng hỏi về vị trí, khoảng cách, "gần đây", "gần X"
+- Cần tìm quán xung quanh một landmark (Cầu Rồng, Mỹ Khê, Bà Nà)
+- Lấy chi tiết đầy đủ về một địa điểm cụ thể
+
+Categories: Restaurant, Coffee shop, Cafe, Bar, Hotel, Seafood restaurant, 
+Japanese restaurant, Korean restaurant, Gym, Fitness center, v.v.""",
+    "parameters": {
+        "location": "Tên địa điểm trung tâm (VD: 'Bãi biển Mỹ Khê', 'Cầu Rồng')",
+        "category": "Loại địa điểm: restaurant, coffee, hotel, bar, seafood, gym, etc.",
+        "max_distance_km": "Khoảng cách tối đa tính theo km (mặc định 5)",
+        "limit": "Số kết quả tối đa (mặc định 10)",
+    },
+}
+
+
+async def find_nearby_places(
+    lat: float,
+    lng: float,
+    max_distance_km: float = 5.0,
+    category: str | None = None,
+    limit: int = 10,
+) -> list[PlaceResult]:
+    """
+    Find nearby places using Neo4j spatial query.
+
+    Args:
+        lat: Center latitude
+        lng: Center longitude
+        max_distance_km: Maximum distance in kilometers
+        category: Optional category filter
+        limit: Maximum results
+
+    Returns:
+        List of nearby places ordered by distance
+    """
+    category_filter = ""
+    if category:
+        category_filter = "AND toLower(p.category) CONTAINS toLower($category)"
+
+    query = f"""
+    MATCH (p:Place)
+    WITH p, point.distance(
+        point({{latitude: p.latitude, longitude: p.longitude}}),
+        point({{latitude: $lat, longitude: $lng}})
+    ) / 1000 as distance_km
+    WHERE distance_km <= $max_distance {category_filter}
+    RETURN 
+        p.id as place_id,
+        p.name as name,
+        p.category as category,
+        p.latitude as lat,
+        p.longitude as lng,
+        distance_km,
+        p.rating as rating,
+        p.description as description
+    ORDER BY distance_km
+    LIMIT $limit
+    """
+
+    params = {
+        "lat": lat,
+        "lng": lng,
+        "max_distance": max_distance_km,
+        "limit": limit,
+    }
+    if category:
+        params["category"] = category
+
+    results = await neo4j_client.run_cypher(query, params)
+
+    return [
+        PlaceResult(
+            place_id=r["place_id"],
+            name=r["name"],
+            category=r["category"] or '',
+            lat=r["lat"] or 0.0,
+            lng=r["lng"] or 0.0,
+            distance_km=r.get("distance_km"),
+            rating=r.get("rating"),
+            description=r.get("description"),
+        )
+        for r in results
+    ]
+
+
+async def get_place_details(
+    place_id: str,
+    include_nearby: bool = True,
+    include_same_category: bool = True,
+    nearby_limit: int = 5,
+) -> PlaceDetails | None:
+    """
+    Get complete place details including photos, reviews, and relationships.
+
+    Args:
+        place_id: The place identifier
+        include_nearby: Whether to include nearby places
+        include_same_category: Whether to include same category places
+        nearby_limit: Limit for nearby/related results
+
+    Returns:
+        PlaceDetails or None if not found
+    """
+    # Main place query with photos and reviews
+    query = """
+    MATCH (p:Place {id: $place_id})
+    OPTIONAL MATCH (p)-[:HAS_PHOTO]->(photo:Photo)
+    OPTIONAL MATCH (p)-[:HAS_REVIEW]->(review:Review)
+    RETURN p,
+           collect(DISTINCT photo.path) as photos,
+           collect(DISTINCT {
+               text: review.text,
+               rating: review.rating,
+               reviewer: review.reviewer
+           }) as reviews
+    """
+
+    results = await neo4j_client.run_cypher(query, {"place_id": place_id})
+
+    if not results or not results[0].get('p'):
+        return None
+
+    record = results[0]
+    place = record['p']
+
+    details = PlaceDetails(
+        place_id=place.get('id', place_id),
+        name=place.get('name', 'Unknown'),
+        category=place.get('category', ''),
+        rating=float(place.get('rating', 0) or 0),
+        address=place.get('address', ''),
+        phone=place.get('phone'),
+        website=place.get('website'),
+        google_maps_url=place.get('google_maps_url'),
+        description=place.get('description'),
+        specialty=place.get('specialty'),
+        price_range=place.get('price_range'),
+        coordinates={
+            'lat': float(place.get('latitude', 0) or 0),
+            'lng': float(place.get('longitude', 0) or 0)
+        },
+        photos_count=int(place.get('photos_count', 0) or 0),
+        reviews_count=int(place.get('reviews_count', 0) or 0),
+        photos=record.get('photos', [])[:10],
+        reviews=[
+            Review(
+                text=r['text'] or '',
+                rating=int(r['rating'] or 0),
+                reviewer=r['reviewer'] or ''
+            )
+            for r in record.get('reviews', [])[:5]
+            if r.get('text')
+        ]
+    )
+
+    # Get nearby places
+    if include_nearby:
+        details.nearby_places = await get_nearby_by_relationship(place_id, nearby_limit)
+
+    # Get same category places
+    if include_same_category:
+        details.same_category = await get_same_category_places(place_id, nearby_limit)
+
+    return details
+
+
+async def get_nearby_by_relationship(
+    place_id: str,
+    limit: int = 5,
+    max_distance_km: float = 2.0
+) -> list[NearbyPlace]:
+    """
+    Get places near a given place using NEAR relationship.
+
+    Args:
+        place_id: The source place identifier
+        limit: Maximum number of results
+        max_distance_km: Maximum distance in km
+
+    Returns:
+        List of NearbyPlace objects
+    """
+    query = """
+    MATCH (p:Place {id: $place_id})-[n:NEAR]-(other:Place)
+    WHERE n.distance_km <= $max_distance
+    RETURN other.id as place_id,
+           other.name as name,
+           other.category as category,
+           other.rating as rating,
+           n.distance_km as distance_km
+    ORDER BY n.distance_km
+    LIMIT $limit
+    """
+
+    results = await neo4j_client.run_cypher(query, {
+        "place_id": place_id,
+        "max_distance": max_distance_km,
+        "limit": limit
+    })
+
+    return [
+        NearbyPlace(
+            place_id=r['place_id'],
+            name=r['name'],
+            category=r['category'] or '',
+            rating=float(r['rating'] or 0),
+            distance_km=round(float(r['distance_km'] or 0), 2)
+        )
+        for r in results
+    ]
+
+
+async def get_same_category_places(
+    place_id: str,
+    limit: int = 5
+) -> list[dict[str, Any]]:
+    """
+    Get other places in the same category.
+
+    Args:
+        place_id: The source place identifier
+        limit: Maximum number of results
+
+    Returns:
+        List of places in same category, ordered by rating
+    """
+    query = """
+    MATCH (p:Place {id: $place_id})-[:IN_CATEGORY]->(c:Category)<-[:IN_CATEGORY]-(other:Place)
+    WHERE other.id <> $place_id
+    RETURN other.id as place_id,
+           other.name as name,
+           other.category as category,
+           other.rating as rating,
+           other.address as address
+    ORDER BY other.rating DESC
+    LIMIT $limit
+    """
+
+    results = await neo4j_client.run_cypher(query, {
+        "place_id": place_id,
+        "limit": limit
+    })
+
+    return [
+        {
+            'place_id': r['place_id'],
+            'name': r['name'],
+            'category': r['category'] or '',
+            'rating': float(r['rating'] or 0),
+            'address': r['address'] or ''
+        }
+        for r in results
+    ]
+
+
+async def geocode_location(location_name: str, country: str = "Vietnam") -> tuple[float, float] | None:
+    """
+    Geocode a location name using OpenStreetMap Nominatim API.
+
+    Args:
+        location_name: Name of the place (e.g., "Cầu Rồng", "Bãi biển Mỹ Khê")
+        country: Country to bias search (default: Vietnam)
+
+    Returns:
+        (lat, lng) tuple or None if not found
+    """
+    search_query = f"{location_name}, Da Nang, {country}"
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            response = await client.get(
+                "https://nominatim.openstreetmap.org/search",
+                params={
+                    "q": search_query,
+                    "format": "json",
+                    "limit": 1,
+                    "addressdetails": 0,
+                },
+                headers={
+                    "User-Agent": "LocalMate-DaNang/1.0 (travel assistant app)",
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if data and len(data) > 0:
+                lat = float(data[0]["lat"])
+                lng = float(data[0]["lon"])
+                return (lat, lng)
+
+    except Exception:
+        pass
+
+    return None
+
+
+async def get_location_coordinates(location_name: str) -> tuple[float, float] | None:
+    """
+    Get coordinates for a location name.
+
+    First tries Neo4j, then falls back to OpenStreetMap Nominatim.
+
+    Args:
+        location_name: Name of the place (e.g., "Khách sạn Rex", "Cầu Rồng")
+
+    Returns:
+        (lat, lng) tuple or None if not found
+    """
+    # Try Neo4j first
+    try:
+        query = """
+        MATCH (p:Place)
+        WHERE toLower(p.name) CONTAINS toLower($name)
+        RETURN p.latitude as lat, p.longitude as lng
+        LIMIT 1
+        """
+        results = await neo4j_client.run_cypher(query, {"name": location_name})
+        if results and results[0].get("lat") and results[0].get("lng"):
+            return (results[0]["lat"], results[0]["lng"])
+    except Exception:
+        pass
+
+    # Fallback to OpenStreetMap Nominatim
+    osm_result = await geocode_location(location_name)
+    if osm_result:
+        return osm_result
+
+    return None

app/mcp/tools/text_tool.py

@@ -0,0 +1,173 @@
+"""Text RAG Tool - Semantic search in text descriptions using pgvector.
+
+Schema: place_text_embeddings (place_id, embedding, content_type, source_text, metadata)
+        places_metadata (place_id, name, category, rating, raw_data)
+"""
+
+from dataclasses import dataclass, field
+from collections import defaultdict
+from typing import Optional
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.shared.integrations.embedding_client import embedding_client
+
+
+@dataclass
+class TextSearchResult:
+    """Result from text context search."""
+
+    place_id: str
+    name: str
+    category: str
+    rating: float
+    similarity: float
+    description: str = ""
+    source_text: str = ""
+    content_type: str = ""
+
+
+# Category keywords for intent detection
+CATEGORY_KEYWORDS = {
+    'cafe': ['cafe', 'cà phê', 'coffee', 'caphe', 'caphê'],
+    'pho': ['phở', 'pho'],
+    'banh_mi': ['bánh mì', 'banh mi', 'bread'],
+    'seafood': ['hải sản', 'hai san', 'seafood', 'cá', 'tôm', 'cua'],
+    'restaurant': ['nhà hàng', 'restaurant', 'quán ăn', 'ăn'],
+    'bar': ['bar', 'pub', 'cocktail', 'beer', 'bia'],
+    'hotel': ['hotel', 'khách sạn', 'resort', 'villa'],
+    'japanese': ['nhật', 'japan', 'sushi', 'ramen'],
+    'korean': ['hàn', 'korea', 'bbq'],
+}
+
+CATEGORY_TO_DB = {
+    'cafe': ['Coffee shop', 'Cafe', 'Coffee house', 'Espresso bar'],
+    'pho': ['Pho restaurant', 'Bistro', 'Restaurant', 'Vietnamese restaurant'],
+    'banh_mi': ['Bakery', 'Tiffin center', 'Restaurant'],
+    'seafood': ['Seafood restaurant', 'Restaurant', 'Asian restaurant'],
+    'restaurant': ['Restaurant', 'Vietnamese restaurant', 'Asian restaurant'],
+    'bar': ['Bar', 'Cocktail bar', 'Pub', 'Night club', 'Live music bar'],
+    'hotel': ['Hotel', 'Resort', 'Apartment', 'Villa', 'Holiday apartment rental'],
+    'japanese': ['Japanese restaurant', 'Sushi restaurant', 'Ramen restaurant'],
+    'korean': ['Korean restaurant', 'Korean barbecue restaurant'],
+}
+
+
+# Tool definition for agent
+TOOL_DEFINITION = {
+    "name": "retrieve_context_text",
+    "description": """Tìm kiếm thông tin địa điểm dựa trên văn bản, mô tả, đánh giá.
+
+Dùng khi:
+- Người dùng hỏi về menu, review, mô tả địa điểm
+- Tìm kiếm theo đặc điểm: "quán cafe view đẹp", "phở ngon giá rẻ"
+- Tìm theo không khí: "nơi lãng mạn", "chỗ yên tĩnh làm việc"
+
+Hỗ trợ: Vietnamese + English""",
+    "parameters": {
+        "query": "Câu query tìm kiếm tự nhiên (VD: 'quán phở nước dùng đậm đà')",
+        "limit": "Số kết quả tối đa (mặc định 10)",
+    },
+}
+
+
+def detect_category_intent(query: str) -> Optional[str]:
+    """Detect if query is asking for specific category."""
+    query_lower = query.lower()
+
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        if any(kw in query_lower for kw in keywords):
+            return category
+    return None
+
+
+async def retrieve_context_text(
+    db: AsyncSession,
+    query: str,
+    limit: int = 10,
+    threshold: float = 0.3,
+) -> list[TextSearchResult]:
+    """
+    Semantic search in text descriptions using pgvector.
+
+    Uses place_text_embeddings table with JOIN to places_metadata.
+
+    Args:
+        db: Database session
+        query: Natural language query
+        limit: Maximum results
+        threshold: Minimum similarity threshold
+
+    Returns:
+        List of places with similarity scores
+    """
+    # Generate embedding for query
+    query_embedding = await embedding_client.embed_text(query)
+    
+    # Convert to PostgreSQL vector format
+    embedding_str = "[" + ",".join(str(x) for x in query_embedding) + "]"
+
+    # Detect category intent for boosting
+    category_intent = detect_category_intent(query)
+    category_filter = CATEGORY_TO_DB.get(category_intent, []) if category_intent else []
+
+    # Search with JOIN to places_metadata
+    # Note: Use format string for embedding since SQLAlchemy param binding 
+    # doesn't work correctly with ::vector type casting
+    sql = text(f"""
+        SELECT DISTINCT ON (e.place_id)
+            e.place_id,
+            e.content_type,
+            e.source_text,
+            1 - (e.embedding <=> '{embedding_str}'::vector) as similarity,
+            m.name,
+            m.category,
+            m.rating,
+            m.raw_data
+        FROM place_text_embeddings e
+        JOIN places_metadata m ON e.place_id = m.place_id
+        WHERE 1 - (e.embedding <=> '{embedding_str}'::vector) > :threshold
+          AND m.name IS NOT NULL 
+          AND m.name != ''
+        ORDER BY e.place_id, e.embedding <=> '{embedding_str}'::vector
+    """)
+
+    results = await db.execute(sql, {
+        "threshold": threshold,
+    })
+
+    rows = results.fetchall()
+
+    # Process and score results with category boosting
+    scored_results = []
+    for r in rows:
+        score = float(r.similarity)
+        
+        # Category boost (15%)
+        if category_filter and r.category in category_filter:
+            score += 0.15
+        
+        # Rating boost (5% for >= 4.5)
+        if r.rating and r.rating >= 4.5:
+            score += 0.05
+        elif r.rating and r.rating >= 4.0:
+            score += 0.02
+        
+        raw_data = r.raw_data or {}
+        
+        scored_results.append((score, TextSearchResult(
+            place_id=r.place_id,
+            name=r.name or '',
+            category=r.category or '',
+            rating=float(r.rating) if r.rating else 0.0,
+            similarity=round(score, 4),
+            description=raw_data.get('description', '')[:300] if isinstance(raw_data, dict) else '',
+            source_text=r.source_text[:300] if r.source_text else '',
+            content_type=r.content_type or '',
+        )))
+
+    # Sort by score and limit
+    scored_results.sort(key=lambda x: x[0], reverse=True)
+    
+    return [r for _, r in scored_results[:limit]]

app/mcp/tools/visual_tool.py

@@ -0,0 +1,169 @@
+"""Visual RAG Tool - Image similarity search using local SigLIP embeddings.
+
+Schema: place_image_embeddings (place_id, embedding, image_url, metadata)
+        places_metadata (place_id, name, category, rating, raw_data)
+        
+Uses local SigLIP model (ViT-B-16-SigLIP) for generating 768-dim image embeddings.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.shared.integrations.siglip_client import get_siglip_client
+
+
+@dataclass
+class ImageSearchResult:
+    """Result from visual similarity search."""
+
+    place_id: str
+    name: str
+    category: str
+    rating: float
+    similarity: float
+    matched_images: int = 1
+    image_url: str = ""
+
+
+# Tool definition for agent
+TOOL_DEFINITION = {
+    "name": "retrieve_similar_visuals",
+    "description": """Tìm địa điểm có hình ảnh tương tự.
+
+Dùng khi:
+- Người dùng gửi ảnh và muốn tìm nơi tương tự
+- Mô tả về không gian, decor, view
+- "Tìm quán có view như này", "Nơi nào có không gian giống ảnh này"
+""",
+    "parameters": {
+        "image_url": "URL của ảnh cần tìm kiếm tương tự",
+        "limit": "Số kết quả tối đa (mặc định 10)",
+    },
+}
+
+
+async def retrieve_similar_visuals(
+    db: AsyncSession,
+    image_url: str | None = None,
+    image_bytes: bytes | None = None,
+    limit: int = 10,
+    threshold: float = 0.2,
+) -> list[ImageSearchResult]:
+    """
+    Visual similarity search using local SigLIP embeddings.
+
+    Uses place_image_embeddings table with JOIN to places_metadata.
+
+    Args:
+        db: Database session
+        image_url: URL of the query image
+        image_bytes: Raw image bytes (alternative to URL)
+        limit: Maximum results
+        threshold: Minimum similarity threshold
+
+    Returns:
+        List of places with visual similarity scores
+    """
+    # Get SigLIP client (singleton)
+    siglip = get_siglip_client()
+    
+    # Generate image embedding using local model
+    if image_bytes:
+        image_embedding = siglip.embed_image_bytes(image_bytes)
+    elif image_url:
+        image_embedding = siglip.embed_image_url(image_url)
+    else:
+        return []
+
+    if image_embedding is None:
+        return []
+
+    # Convert numpy array to PostgreSQL vector format
+    embedding_str = "[" + ",".join(str(x) for x in image_embedding.tolist()) + "]"
+
+    # Search with JOIN to places_metadata
+    sql = text(f"""
+        SELECT 
+            e.place_id,
+            e.image_url,
+            1 - (e.embedding <=> '{embedding_str}'::vector) as similarity,
+            m.name,
+            m.category,
+            m.rating
+        FROM place_image_embeddings e
+        JOIN places_metadata m ON e.place_id = m.place_id
+        WHERE 1 - (e.embedding <=> '{embedding_str}'::vector) > :threshold
+          AND m.name IS NOT NULL 
+          AND m.name != ''
+        ORDER BY e.embedding <=> '{embedding_str}'::vector
+        LIMIT 100
+    """)
+
+    results = await db.execute(sql, {
+        "threshold": threshold,
+    })
+
+    rows = results.fetchall()
+
+    # Aggregate by place (multiple images per place)
+    place_scores: dict = {}
+
+    for r in rows:
+        pid = r.place_id
+
+        if pid not in place_scores:
+            place_scores[pid] = {
+                'total_score': 0.0,
+                'count': 0,
+                'data': r,
+                'best_image': r.image_url,
+            }
+
+        place_scores[pid]['total_score'] += float(r.similarity)
+        place_scores[pid]['count'] += 1
+        
+        # Keep best matching image
+        if float(r.similarity) > place_scores[pid]['total_score'] / place_scores[pid]['count']:
+            place_scores[pid]['best_image'] = r.image_url
+
+    # Sort by average similarity
+    sorted_places = sorted(
+        place_scores.items(),
+        key=lambda x: x[1]['total_score'] / x[1]['count'],
+        reverse=True
+    )[:limit]
+
+    # Build results
+    return [
+        ImageSearchResult(
+            place_id=pid,
+            name=data['data'].name or '',
+            category=data['data'].category or '',
+            rating=float(data['data'].rating or 0),
+            similarity=round(data['total_score'] / data['count'], 4),
+            matched_images=data['count'],
+            image_url=data['best_image'] or '',
+        )
+        for pid, data in sorted_places
+    ]
+
+
+async def search_by_image_url(
+    db: AsyncSession,
+    image_url: str,
+    limit: int = 10,
+) -> list[ImageSearchResult]:
+    """Search places by image URL."""
+    return await retrieve_similar_visuals(db=db, image_url=image_url, limit=limit)
+
+
+async def search_by_image_bytes(
+    db: AsyncSession,
+    image_bytes: bytes,
+    limit: int = 10,
+) -> list[ImageSearchResult]:
+    """Search places by uploading image bytes."""
+    return await retrieve_similar_visuals(db=db, image_bytes=image_bytes, limit=limit)

app/planner/__init__.py

@@ -0,0 +1 @@
+"""Trip Planner Package - Plan your Da Nang trip with TSP optimization."""

app/planner/models.py

@@ -0,0 +1,100 @@
+"""Trip Planner Models - Pydantic schemas for Plan and PlanItem."""
+
+from datetime import datetime
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class PlaceInput(BaseModel):
+    """Place data for adding to plan."""
+    
+    place_id: str = Field(..., description="Unique place identifier")
+    name: str = Field(..., description="Place name")
+    category: str = Field(default="", description="Place category")
+    lat: float = Field(..., description="Latitude")
+    lng: float = Field(..., description="Longitude")
+    rating: Optional[float] = Field(None, description="Rating 0-5")
+    description: Optional[str] = Field(None, description="Place description")
+
+
+class PlanItem(BaseModel):
+    """A place in the plan with order and metadata."""
+    
+    item_id: str = Field(..., description="Unique item identifier")
+    place_id: str = Field(..., description="Reference to place")
+    name: str = Field(..., description="Place name")
+    category: str = Field(default="", description="Category")
+    lat: float = Field(..., description="Latitude")
+    lng: float = Field(..., description="Longitude")
+    order: int = Field(..., description="Order in plan (1-indexed)")
+    added_at: datetime = Field(default_factory=datetime.now)
+    notes: Optional[str] = Field(None, description="User notes")
+    rating: Optional[float] = None
+    distance_from_prev_km: Optional[float] = Field(None, description="Distance from previous item")
+
+
+class Plan(BaseModel):
+    """A trip plan containing multiple places."""
+    
+    plan_id: str = Field(..., description="Unique plan identifier")
+    user_id: str = Field(..., description="Owner user ID")
+    name: str = Field(default="My Trip", description="Plan name")
+    items: list[PlanItem] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    total_distance_km: Optional[float] = Field(None, description="Total route distance")
+    estimated_duration_min: Optional[int] = Field(None, description="Estimated duration")
+    is_optimized: bool = Field(default=False, description="Route has been optimized")
+
+
+# Request/Response Models
+
+class CreatePlanRequest(BaseModel):
+    """Request to create a new plan."""
+    
+    name: str = Field(default="My Trip", description="Plan name")
+
+
+class CreatePlanResponse(BaseModel):
+    """Response after creating a plan."""
+    
+    plan_id: str
+    name: str
+    message: str
+
+
+class AddPlaceRequest(BaseModel):
+    """Request to add a place to plan."""
+    
+    place: PlaceInput
+    notes: Optional[str] = None
+
+
+class ReorderRequest(BaseModel):
+    """Request to reorder places in plan."""
+    
+    new_order: list[str] = Field(..., description="List of item_ids in new order")
+
+
+class ReplaceRequest(BaseModel):
+    """Request to replace a place."""
+    
+    new_place: PlaceInput
+
+
+class OptimizeResponse(BaseModel):
+    """Response from route optimization."""
+    
+    plan_id: str
+    items: list[PlanItem]
+    total_distance_km: float
+    estimated_duration_min: int
+    distance_saved_km: Optional[float] = None
+    message: str
+
+
+class PlanResponse(BaseModel):
+    """Full plan response."""
+    
+    plan: Plan
+    message: str

app/planner/router.py

@@ -0,0 +1,253 @@
+"""Trip Planner Router - API endpoints for plan management."""
+
+from fastapi import APIRouter, HTTPException, Query
+
+from app.planner.models import (
+    Plan,
+    PlanItem,
+    CreatePlanRequest,
+    CreatePlanResponse,
+    AddPlaceRequest,
+    ReorderRequest,
+    ReplaceRequest,
+    OptimizeResponse,
+    PlanResponse,
+)
+from app.planner.service import planner_service
+
+
+router = APIRouter(prefix="/planner", tags=["Trip Planner"])
+
+
+@router.post(
+    "/create",
+    response_model=CreatePlanResponse,
+    summary="Create a new trip plan",
+    description="Creates an empty trip plan for the user.",
+)
+async def create_plan(
+    request: CreatePlanRequest,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> CreatePlanResponse:
+    """Create a new empty plan."""
+    plan = planner_service.create_plan(user_id=user_id, name=request.name)
+    
+    return CreatePlanResponse(
+        plan_id=plan.plan_id,
+        name=plan.name,
+        message=f"Created plan '{plan.name}'",
+    )
+
+
+@router.get(
+    "/{plan_id}",
+    response_model=PlanResponse,
+    summary="Get a trip plan",
+    description="Retrieves a plan by ID.",
+)
+async def get_plan(
+    plan_id: str,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> PlanResponse:
+    """Get a plan by ID."""
+    plan = planner_service.get_plan(user_id=user_id, plan_id=plan_id)
+    
+    if not plan:
+        raise HTTPException(status_code=404, detail="Plan not found")
+    
+    return PlanResponse(plan=plan, message="Plan retrieved")
+
+
+@router.get(
+    "/user/plans",
+    response_model=list[Plan],
+    summary="Get all user plans",
+    description="Retrieves all plans for a user.",
+)
+async def get_user_plans(
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> list[Plan]:
+    """Get all plans for a user."""
+    return planner_service.get_user_plans(user_id)
+
+
+@router.post(
+    "/{plan_id}/add",
+    response_model=PlanItem,
+    summary="Add a place to plan",
+    description="Adds a new place to the end of the plan.",
+)
+async def add_place(
+    plan_id: str,
+    request: AddPlaceRequest,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> PlanItem:
+    """Add a place to the plan."""
+    # Try to find existing plan or create default
+    plan = planner_service.get_plan(user_id, plan_id)
+    if not plan:
+        # Auto-create plan if it doesn't exist
+        plan = planner_service.create_plan(user_id=user_id)
+    
+    item = planner_service.add_place(
+        user_id=user_id,
+        plan_id=plan.plan_id,
+        place=request.place,
+        notes=request.notes,
+    )
+    
+    if not item:
+        raise HTTPException(status_code=404, detail="Plan not found")
+    
+    return item
+
+
+@router.delete(
+    "/{plan_id}/remove/{item_id}",
+    summary="Remove a place from plan",
+    description="Removes a place from the plan by item ID.",
+)
+async def remove_place(
+    plan_id: str,
+    item_id: str,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> dict:
+    """Remove a place from the plan."""
+    success = planner_service.remove_place(
+        user_id=user_id,
+        plan_id=plan_id,
+        item_id=item_id,
+    )
+    
+    if not success:
+        raise HTTPException(status_code=404, detail="Item not found")
+    
+    return {"status": "success", "message": f"Removed item {item_id}"}
+
+
+@router.put(
+    "/{plan_id}/reorder",
+    response_model=PlanResponse,
+    summary="Reorder places in plan",
+    description="Manually reorder places by providing new order of item IDs.",
+)
+async def reorder_places(
+    plan_id: str,
+    request: ReorderRequest,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> PlanResponse:
+    """Reorder places in the plan."""
+    success = planner_service.reorder_places(
+        user_id=user_id,
+        plan_id=plan_id,
+        new_order=request.new_order,
+    )
+    
+    if not success:
+        raise HTTPException(
+            status_code=400, 
+            detail="Invalid order. Ensure all item IDs are included."
+        )
+    
+    plan = planner_service.get_plan(user_id, plan_id)
+    return PlanResponse(plan=plan, message="Plan reordered")
+
+
+@router.post(
+    "/{plan_id}/optimize",
+    response_model=OptimizeResponse,
+    summary="Optimize route (TSP)",
+    description="""
+Optimizes the route using TSP (Traveling Salesman Problem) algorithm.
+
+Uses Nearest Neighbor heuristic with 2-opt improvement.
+Minimizes total travel distance.
+""",
+)
+async def optimize_route(
+    plan_id: str,
+    user_id: str = Query(default="anonymous", description="User ID"),
+    start_index: int = Query(default=0, description="Index of starting place"),
+) -> OptimizeResponse:
+    """Optimize the route using TSP."""
+    # Get original distance for comparison
+    plan = planner_service.get_plan(user_id, plan_id)
+    if not plan:
+        raise HTTPException(status_code=404, detail="Plan not found")
+    
+    if len(plan.items) < 2:
+        return OptimizeResponse(
+            plan_id=plan_id,
+            items=plan.items,
+            total_distance_km=0,
+            estimated_duration_min=0,
+            message="Need at least 2 places to optimize",
+        )
+    
+    original_distance = plan.total_distance_km or 0
+    
+    # Optimize
+    optimized_plan = planner_service.optimize_plan(
+        user_id=user_id,
+        plan_id=plan_id,
+        start_index=start_index,
+    )
+    
+    if not optimized_plan:
+        raise HTTPException(status_code=404, detail="Plan not found")
+    
+    # Calculate savings
+    distance_saved = original_distance - optimized_plan.total_distance_km if original_distance > 0 else None
+    
+    return OptimizeResponse(
+        plan_id=plan_id,
+        items=optimized_plan.items,
+        total_distance_km=optimized_plan.total_distance_km,
+        estimated_duration_min=optimized_plan.estimated_duration_min,
+        distance_saved_km=round(distance_saved, 2) if distance_saved else None,
+        message=f"Route optimized! Total: {optimized_plan.total_distance_km}km, ~{optimized_plan.estimated_duration_min}min",
+    )
+
+
+@router.put(
+    "/{plan_id}/replace/{item_id}",
+    response_model=PlanItem,
+    summary="Replace a place in plan",
+    description="Replaces an existing place with a new one.",
+)
+async def replace_place(
+    plan_id: str,
+    item_id: str,
+    request: ReplaceRequest,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> PlanItem:
+    """Replace a place in the plan."""
+    item = planner_service.replace_place(
+        user_id=user_id,
+        plan_id=plan_id,
+        item_id=item_id,
+        new_place=request.new_place,
+    )
+    
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    
+    return item
+
+
+@router.delete(
+    "/{plan_id}",
+    summary="Delete a plan",
+    description="Deletes an entire plan.",
+)
+async def delete_plan(
+    plan_id: str,
+    user_id: str = Query(default="anonymous", description="User ID"),
+) -> dict:
+    """Delete a plan."""
+    success = planner_service.delete_plan(user_id=user_id, plan_id=plan_id)
+    
+    if not success:
+        raise HTTPException(status_code=404, detail="Plan not found")
+    
+    return {"status": "success", "message": f"Deleted plan {plan_id}"}

app/planner/service.py

@@ -0,0 +1,297 @@
+"""Trip Planner Service - Business logic and in-memory storage."""
+
+import uuid
+from datetime import datetime
+from typing import Optional
+from collections import defaultdict
+
+from app.planner.models import Plan, PlanItem, PlaceInput
+from app.planner.tsp import optimize_route, estimate_duration, haversine
+
+
+class PlannerService:
+    """
+    Service for managing trip plans.
+    
+    Uses in-memory storage per user_id (session-based).
+    Plans persist during server lifetime.
+    """
+    
+    def __init__(self):
+        """Initialize with in-memory storage."""
+        # {user_id: {plan_id: Plan}}
+        self._plans: dict[str, dict[str, Plan]] = defaultdict(dict)
+    
+    def create_plan(self, user_id: str, name: str = "My Trip") -> Plan:
+        """
+        Create a new empty plan.
+        
+        Args:
+            user_id: Owner's user ID
+            name: Plan name
+            
+        Returns:
+            Created Plan object
+        """
+        plan_id = f"plan_{uuid.uuid4().hex[:12]}"
+        
+        plan = Plan(
+            plan_id=plan_id,
+            user_id=user_id,
+            name=name,
+            items=[],
+            created_at=datetime.now(),
+            updated_at=datetime.now(),
+        )
+        
+        self._plans[user_id][plan_id] = plan
+        return plan
+    
+    def get_plan(self, user_id: str, plan_id: str) -> Optional[Plan]:
+        """Get a plan by ID."""
+        return self._plans.get(user_id, {}).get(plan_id)
+    
+    def get_user_plans(self, user_id: str) -> list[Plan]:
+        """Get all plans for a user."""
+        return list(self._plans.get(user_id, {}).values())
+    
+    def get_or_create_default_plan(self, user_id: str) -> Plan:
+        """Get user's first plan or create one."""
+        plans = self.get_user_plans(user_id)
+        if plans:
+            return plans[0]
+        return self.create_plan(user_id)
+    
+    def add_place(
+        self,
+        user_id: str,
+        plan_id: str,
+        place: PlaceInput,
+        notes: Optional[str] = None
+    ) -> Optional[PlanItem]:
+        """
+        Add a place to a plan.
+        
+        Args:
+            user_id: Owner's user ID
+            plan_id: Target plan ID
+            place: Place data
+            notes: Optional user notes
+            
+        Returns:
+            Created PlanItem or None if plan not found
+        """
+        plan = self.get_plan(user_id, plan_id)
+        if not plan:
+            return None
+        
+        # Create new item
+        item_id = f"item_{uuid.uuid4().hex[:8]}"
+        order = len(plan.items) + 1
+        
+        item = PlanItem(
+            item_id=item_id,
+            place_id=place.place_id,
+            name=place.name,
+            category=place.category,
+            lat=place.lat,
+            lng=place.lng,
+            order=order,
+            added_at=datetime.now(),
+            notes=notes,
+            rating=place.rating,
+        )
+        
+        plan.items.append(item)
+        plan.updated_at = datetime.now()
+        plan.is_optimized = False
+        
+        # Update distance if there are multiple items
+        self._update_distances(plan)
+        
+        return item
+    
+    def remove_place(self, user_id: str, plan_id: str, item_id: str) -> bool:
+        """
+        Remove a place from plan.
+        
+        Returns:
+            True if removed, False if not found
+        """
+        plan = self.get_plan(user_id, plan_id)
+        if not plan:
+            return False
+        
+        # Find and remove item
+        original_len = len(plan.items)
+        plan.items = [item for item in plan.items if item.item_id != item_id]
+        
+        if len(plan.items) < original_len:
+            # Reorder remaining items
+            for i, item in enumerate(plan.items):
+                item.order = i + 1
+            
+            plan.updated_at = datetime.now()
+            plan.is_optimized = False
+            self._update_distances(plan)
+            return True
+        
+        return False
+    
+    def reorder_places(self, user_id: str, plan_id: str, new_order: list[str]) -> bool:
+        """
+        Reorder places in plan.
+        
+        Args:
+            user_id: Owner's user ID
+            plan_id: Plan ID
+            new_order: List of item_ids in new order
+            
+        Returns:
+            True if reordered, False if invalid
+        """
+        plan = self.get_plan(user_id, plan_id)
+        if not plan:
+            return False
+        
+        # Validate all item_ids exist
+        existing_ids = {item.item_id for item in plan.items}
+        if set(new_order) != existing_ids:
+            return False
+        
+        # Create id -> item mapping
+        item_map = {item.item_id: item for item in plan.items}
+        
+        # Reorder
+        plan.items = [item_map[item_id] for item_id in new_order]
+        for i, item in enumerate(plan.items):
+            item.order = i + 1
+        
+        plan.updated_at = datetime.now()
+        plan.is_optimized = False
+        self._update_distances(plan)
+        
+        return True
+    
+    def replace_place(
+        self,
+        user_id: str,
+        plan_id: str,
+        item_id: str,
+        new_place: PlaceInput
+    ) -> Optional[PlanItem]:
+        """
+        Replace a place in plan with a new one.
+        
+        Args:
+            user_id: Owner's user ID
+            plan_id: Plan ID
+            item_id: Item to replace
+            new_place: New place data
+            
+        Returns:
+            Updated PlanItem or None if not found
+        """
+        plan = self.get_plan(user_id, plan_id)
+        if not plan:
+            return None
+        
+        # Find item to replace
+        for i, item in enumerate(plan.items):
+            if item.item_id == item_id:
+                # Update with new place data
+                item.place_id = new_place.place_id
+                item.name = new_place.name
+                item.category = new_place.category
+                item.lat = new_place.lat
+                item.lng = new_place.lng
+                item.rating = new_place.rating
+                
+                plan.updated_at = datetime.now()
+                plan.is_optimized = False
+                self._update_distances(plan)
+                
+                return item
+        
+        return None
+    
+    def optimize_plan(self, user_id: str, plan_id: str, start_index: int = 0) -> Optional[Plan]:
+        """
+        Optimize the route for a plan using TSP.
+        
+        Args:
+            user_id: Owner's user ID
+            plan_id: Plan ID
+            start_index: Index of starting place
+            
+        Returns:
+            Optimized Plan or None if not found
+        """
+        plan = self.get_plan(user_id, plan_id)
+        if not plan or len(plan.items) < 2:
+            return plan
+        
+        # Calculate original distance for comparison
+        original_distance = plan.total_distance_km or 0
+        
+        # Convert items to places format for TSP
+        places = [
+            {'lat': item.lat, 'lng': item.lng}
+            for item in plan.items
+        ]
+        
+        # Run TSP optimization
+        optimized_order, total_distance = optimize_route(places, start_index)
+        
+        # Reorder items according to optimized order
+        original_items = plan.items.copy()
+        plan.items = [original_items[i] for i in optimized_order]
+        
+        # Update orders
+        for i, item in enumerate(plan.items):
+            item.order = i + 1
+        
+        # Update plan metadata
+        plan.total_distance_km = total_distance
+        plan.estimated_duration_min = estimate_duration(total_distance)
+        plan.is_optimized = True
+        plan.updated_at = datetime.now()
+        
+        # Calculate distances between consecutive items
+        self._update_distances(plan)
+        
+        return plan
+    
+    def _update_distances(self, plan: Plan) -> None:
+        """Update total distance and per-item distances."""
+        if len(plan.items) < 2:
+            plan.total_distance_km = 0
+            plan.estimated_duration_min = 0
+            if plan.items:
+                plan.items[0].distance_from_prev_km = None
+            return
+        
+        total = 0.0
+        plan.items[0].distance_from_prev_km = None
+        
+        for i in range(1, len(plan.items)):
+            prev = plan.items[i - 1]
+            curr = plan.items[i]
+            
+            dist = haversine(prev.lat, prev.lng, curr.lat, curr.lng)
+            curr.distance_from_prev_km = round(dist, 2)
+            total += dist
+        
+        plan.total_distance_km = round(total, 2)
+        plan.estimated_duration_min = estimate_duration(total)
+    
+    def delete_plan(self, user_id: str, plan_id: str) -> bool:
+        """Delete a plan."""
+        if plan_id in self._plans.get(user_id, {}):
+            del self._plans[user_id][plan_id]
+            return True
+        return False
+
+
+# Global singleton instance
+planner_service = PlannerService()

app/planner/tsp.py

@@ -0,0 +1,200 @@
+"""TSP Algorithm - Nearest Neighbor + 2-opt optimization.
+
+Optimizes route for a list of places to minimize total travel distance.
+Uses Haversine formula for distance calculation.
+"""
+
+from math import radians, sin, cos, sqrt, atan2
+
+
+def haversine(lat1: float, lng1: float, lat2: float, lng2: float) -> float:
+    """
+    Calculate distance between 2 points on Earth in kilometers.
+    
+    Uses the Haversine formula for great-circle distance.
+    
+    Args:
+        lat1, lng1: First point coordinates
+        lat2, lng2: Second point coordinates
+        
+    Returns:
+        Distance in kilometers
+    """
+    R = 6371  # Earth's radius in km
+    
+    dlat = radians(lat2 - lat1)
+    dlng = radians(lng2 - lng1)
+    
+    a = sin(dlat/2)**2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(dlng/2)**2
+    c = 2 * atan2(sqrt(a), sqrt(1-a))
+    
+    return R * c
+
+
+def calculate_distance_matrix(places: list[dict]) -> list[list[float]]:
+    """
+    Build NxN distance matrix for all place pairs.
+    
+    Args:
+        places: List of places with 'lat' and 'lng' keys
+        
+    Returns:
+        NxN matrix where matrix[i][j] is distance from place i to j
+    """
+    n = len(places)
+    matrix = [[0.0] * n for _ in range(n)]
+    
+    for i in range(n):
+        for j in range(n):
+            if i != j:
+                matrix[i][j] = haversine(
+                    places[i]['lat'], places[i]['lng'],
+                    places[j]['lat'], places[j]['lng']
+                )
+    
+    return matrix
+
+
+def nearest_neighbor(matrix: list[list[float]], start: int = 0) -> list[int]:
+    """
+    Greedy nearest neighbor heuristic for TSP.
+    
+    Builds tour by always visiting the closest unvisited city.
+    O(n²) complexity.
+    
+    Args:
+        matrix: Distance matrix
+        start: Starting city index
+        
+    Returns:
+        List of city indices in visit order
+    """
+    n = len(matrix)
+    visited = [False] * n
+    tour = [start]
+    visited[start] = True
+    
+    for _ in range(n - 1):
+        current = tour[-1]
+        nearest = -1
+        min_dist = float('inf')
+        
+        for j in range(n):
+            if not visited[j] and matrix[current][j] < min_dist:
+                min_dist = matrix[current][j]
+                nearest = j
+        
+        if nearest != -1:
+            tour.append(nearest)
+            visited[nearest] = True
+    
+    return tour
+
+
+def two_opt(tour: list[int], matrix: list[list[float]]) -> list[int]:
+    """
+    2-opt local search improvement for TSP.
+    
+    Iteratively reverses segments to reduce total distance.
+    Continues until no improvement is found.
+    
+    Args:
+        tour: Initial tour (list of indices)
+        matrix: Distance matrix
+        
+    Returns:
+        Improved tour
+    """
+    n = len(tour)
+    if n < 4:
+        return tour
+    
+    improved = True
+    tour = tour.copy()
+    
+    while improved:
+        improved = False
+        for i in range(1, n - 1):
+            for j in range(i + 1, n):
+                if j == n - 1:
+                    # Handle edge case for last element
+                    d1 = matrix[tour[i-1]][tour[i]] + matrix[tour[j]][tour[0]]
+                    d2 = matrix[tour[i-1]][tour[j]] + matrix[tour[i]][tour[0]]
+                else:
+                    d1 = matrix[tour[i-1]][tour[i]] + matrix[tour[j]][tour[j+1]]
+                    d2 = matrix[tour[i-1]][tour[j]] + matrix[tour[i]][tour[j+1]]
+                
+                if d2 < d1 - 0.0001:  # Small epsilon to avoid floating point issues
+                    # Reverse segment [i, j]
+                    tour[i:j+1] = tour[i:j+1][::-1]
+                    improved = True
+    
+    return tour
+
+
+def calculate_total_distance(tour: list[int], matrix: list[list[float]]) -> float:
+    """Calculate total distance of a tour."""
+    total = 0.0
+    for i in range(len(tour) - 1):
+        total += matrix[tour[i]][tour[i+1]]
+    return total
+
+
+def optimize_route(places: list[dict], start_index: int = 0) -> tuple[list[int], float]:
+    """
+    Main TSP optimization function.
+    
+    Uses Nearest Neighbor heuristic followed by 2-opt improvement.
+    Suitable for up to ~50 places.
+    
+    Args:
+        places: List of places with 'lat' and 'lng' keys
+        start_index: Index of starting place (default: first place)
+        
+    Returns:
+        Tuple of (optimized_order, total_distance_km)
+        - optimized_order: List of indices in visit order
+        - total_distance_km: Total route distance
+    """
+    n = len(places)
+    
+    # Handle edge cases
+    if n == 0:
+        return [], 0.0
+    if n == 1:
+        return [0], 0.0
+    if n == 2:
+        dist = haversine(
+            places[0]['lat'], places[0]['lng'],
+            places[1]['lat'], places[1]['lng']
+        )
+        return [0, 1], dist
+    
+    # Build distance matrix
+    matrix = calculate_distance_matrix(places)
+    
+    # Get initial tour using nearest neighbor
+    tour = nearest_neighbor(matrix, start_index)
+    
+    # Improve with 2-opt
+    tour = two_opt(tour, matrix)
+    
+    # Calculate total distance
+    total = calculate_total_distance(tour, matrix)
+    
+    return tour, round(total, 2)
+
+
+def estimate_duration(distance_km: float, avg_speed_kmh: float = 30) -> int:
+    """
+    Estimate travel duration in minutes.
+    
+    Args:
+        distance_km: Total distance in km
+        avg_speed_kmh: Average speed (default: 30 km/h for city driving)
+        
+    Returns:
+        Estimated duration in minutes
+    """
+    hours = distance_km / avg_speed_kmh
+    return int(hours * 60)

app/shared/__init__.py

@@ -0,0 +1 @@
+"""Shared module - integrations, DB, models."""

app/shared/chat_history.py

@@ -0,0 +1,161 @@
+"""Chat history manager for per-user conversation storage."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from collections import defaultdict
+
+
+@dataclass
+class ChatMessage:
+    """Single chat message."""
+
+    role: str  # "user" or "assistant"
+    content: str
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class ChatSession:
+    """Chat session with history."""
+
+    session_id: str
+    messages: list[ChatMessage] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def add_message(self, role: str, content: str) -> None:
+        """Add a message to this session."""
+        self.messages.append(ChatMessage(role=role, content=content))
+
+    def get_history_text(self, max_messages: int = 10) -> str:
+        """Get formatted history for prompt injection."""
+        recent = self.messages[-max_messages:] if len(self.messages) > max_messages else self.messages
+        if not recent:
+            return ""
+
+        lines = []
+        for msg in recent:
+            prefix = "User" if msg.role == "user" else "Assistant"
+            lines.append(f"{prefix}: {msg.content}")
+
+        return "\n".join(lines)
+
+
+class ChatHistoryManager:
+    """
+    Manages chat history per user with multiple sessions.
+
+    Each user can have up to max_sessions active sessions.
+    Oldest sessions are removed when limit is exceeded.
+    """
+
+    def __init__(self, max_sessions_per_user: int = 3, max_messages_per_session: int = 20):
+        """
+        Initialize the chat history manager.
+
+        Args:
+            max_sessions_per_user: Maximum sessions to keep per user (default 3)
+            max_messages_per_session: Maximum messages per session (default 20)
+        """
+        self.max_sessions = max_sessions_per_user
+        self.max_messages = max_messages_per_session
+        self._sessions: dict[str, dict[str, ChatSession]] = defaultdict(dict)
+
+    def get_or_create_session(self, user_id: str, session_id: str | None = None) -> ChatSession:
+        """
+        Get existing session or create a new one.
+
+        Args:
+            user_id: User identifier
+            session_id: Optional session ID (uses "default" if not provided)
+
+        Returns:
+            ChatSession instance
+        """
+        session_id = session_id or "default"
+        user_sessions = self._sessions[user_id]
+
+        if session_id not in user_sessions:
+            # Create new session
+            user_sessions[session_id] = ChatSession(session_id=session_id)
+
+            # Enforce max sessions limit
+            if len(user_sessions) > self.max_sessions:
+                # Remove oldest session
+                oldest_id = min(
+                    user_sessions.keys(),
+                    key=lambda k: user_sessions[k].created_at
+                )
+                del user_sessions[oldest_id]
+
+        return user_sessions[session_id]
+
+    def add_message(
+        self,
+        user_id: str,
+        role: str,
+        content: str,
+        session_id: str | None = None,
+    ) -> None:
+        """
+        Add a message to user's session.
+
+        Args:
+            user_id: User identifier
+            role: "user" or "assistant"
+            content: Message content
+            session_id: Optional session ID
+        """
+        session = self.get_or_create_session(user_id, session_id)
+        session.add_message(role, content)
+
+        # Enforce max messages per session
+        if len(session.messages) > self.max_messages:
+            session.messages = session.messages[-self.max_messages:]
+
+    def get_history(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+        max_messages: int = 10,
+    ) -> str:
+        """
+        Get formatted chat history for prompt.
+
+        Args:
+            user_id: User identifier
+            session_id: Optional session ID
+            max_messages: Maximum messages to include
+
+        Returns:
+            Formatted history string
+        """
+        session = self.get_or_create_session(user_id, session_id)
+        return session.get_history_text(max_messages)
+
+    def get_messages(
+        self,
+        user_id: str,
+        session_id: str | None = None,
+    ) -> list[ChatMessage]:
+        """Get all messages for a session."""
+        session = self.get_or_create_session(user_id, session_id)
+        return session.messages
+
+    def clear_session(self, user_id: str, session_id: str | None = None) -> None:
+        """Clear a specific session."""
+        session_id = session_id or "default"
+        if user_id in self._sessions and session_id in self._sessions[user_id]:
+            del self._sessions[user_id][session_id]
+
+    def clear_all_sessions(self, user_id: str) -> None:
+        """Clear all sessions for a user."""
+        if user_id in self._sessions:
+            self._sessions[user_id].clear()
+
+    def get_session_ids(self, user_id: str) -> list[str]:
+        """Get all session IDs for a user."""
+        return list(self._sessions.get(user_id, {}).keys())
+
+
+# Global chat history manager instance
+chat_history = ChatHistoryManager(max_sessions_per_user=3, max_messages_per_session=20)

app/shared/db/__init__.py

@@ -0,0 +1 @@
+"""Database module."""

app/shared/db/session.py

@@ -0,0 +1,30 @@
+"""Database session and engine configuration."""
+
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import settings
+
+# Create async engine
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,  # Disable SQL logging (embedding vectors are too verbose)
+    pool_pre_ping=True,
+)
+
+# Session factory
+async_session_maker = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """Dependency for getting database session."""
+    async with async_session_maker() as session:
+        try:
+            yield session
+        finally:
+            await session.close()

app/shared/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integrations module."""

app/shared/integrations/embedding_client.py

@@ -0,0 +1,120 @@
+"""Embedding client for text and image embeddings.
+
+Supports:
+- Text: Google text-embedding-004 (768-dim)
+- Image: HuggingFace CLIP/SigLIP (512/768-dim)
+"""
+
+import httpx
+from io import BytesIO
+from google import genai
+
+from app.core.config import settings
+
+# Initialize Google GenAI client
+client = genai.Client(api_key=settings.google_api_key)
+
+
+class EmbeddingClient:
+    """Client for generating text and image embeddings."""
+
+    def __init__(self):
+        """Initialize embedding client."""
+        self.text_model = settings.embedding_model
+        self.hf_api_key = settings.huggingface_api_key
+
+    async def embed_text(self, text: str) -> list[float]:
+        """
+        Generate text embedding using text-embedding-004.
+
+        Args:
+            text: Text to embed
+
+        Returns:
+            768-dimensional embedding vector
+        """
+        response = client.models.embed_content(
+            model=self.text_model,
+            contents=text,
+        )
+        return response.embeddings[0].values
+
+    async def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of embedding vectors
+        """
+        response = client.models.embed_content(
+            model=self.text_model,
+            contents=texts,
+        )
+        return [emb.values for emb in response.embeddings]
+
+    async def embed_image(self, image_url: str) -> list[float] | None:
+        """
+        Generate image embedding using CLIP via HuggingFace.
+
+        Args:
+            image_url: URL of the image
+
+        Returns:
+            512-dimensional embedding vector, or None if failed
+        """
+        if not self.hf_api_key:
+            return None
+
+        try:
+            async with httpx.AsyncClient() as http_client:
+                # Use CLIP model via HuggingFace Inference API
+                response = await http_client.post(
+                    "https://api-inference.huggingface.co/models/openai/clip-vit-base-patch32",
+                    headers={"Authorization": f"Bearer {self.hf_api_key}"},
+                    json={"inputs": {"image": image_url}},
+                    timeout=30.0,
+                )
+                if response.status_code == 200:
+                    return response.json()
+                return None
+        except Exception:
+            return None
+
+    async def embed_image_bytes(self, image_bytes: bytes) -> list[float] | None:
+        """
+        Generate image embedding from raw image bytes.
+
+        Args:
+            image_bytes: Raw image bytes (JPEG, PNG, etc.)
+
+        Returns:
+            512-dimensional embedding vector, or None if failed
+        """
+        if not self.hf_api_key:
+            return None
+
+        try:
+            import base64
+            # Convert bytes to base64 data URL
+            b64_image = base64.b64encode(image_bytes).decode('utf-8')
+            data_url = f"data:image/jpeg;base64,{b64_image}"
+
+            async with httpx.AsyncClient() as http_client:
+                response = await http_client.post(
+                    "https://api-inference.huggingface.co/models/openai/clip-vit-base-patch32",
+                    headers={"Authorization": f"Bearer {self.hf_api_key}"},
+                    json={"inputs": {"image": data_url}},
+                    timeout=30.0,
+                )
+                if response.status_code == 200:
+                    return response.json()
+                return None
+        except Exception:
+            return None
+
+
+# Global embedding client instance
+embedding_client = EmbeddingClient()

app/shared/integrations/gemini_client.py

@@ -0,0 +1,127 @@
+"""Gemini client for LLM operations using Google GenAI."""
+
+import json
+import re
+
+from google import genai
+
+from app.core.config import settings
+
+# Initialize Google GenAI client
+client = genai.Client(api_key=settings.google_api_key)
+
+
+class GeminiClient:
+    """Client for Gemini LLM operations."""
+
+    def __init__(self, model: str | None = None):
+        """Initialize with optional model override."""
+        self.model = model or settings.default_gemini_model
+
+    async def chat(
+        self,
+        messages: list[dict],
+        temperature: float = 0.7,
+        system_instruction: str | None = None,
+    ) -> str:
+        """
+        Generate chat completion using Gemini.
+
+        Args:
+            messages: List of message dicts with 'role' and 'parts'
+            temperature: Sampling temperature (0.0 - 1.0)
+            system_instruction: Optional system prompt
+
+        Returns:
+            Generated text response
+        """
+        config = {"temperature": temperature}
+        if system_instruction:
+            config["system_instruction"] = system_instruction
+
+        response = client.models.generate_content(
+            model=self.model,
+            contents=messages,
+            config=config,
+        )
+        return response.text
+
+    async def generate(
+        self,
+        prompt: str,
+        temperature: float = 0.7,
+        system_instruction: str | None = None,
+    ) -> str:
+        """
+        Simple text generation.
+
+        Args:
+            prompt: Text prompt
+            temperature: Sampling temperature
+            system_instruction: Optional system prompt
+
+        Returns:
+            Generated text
+        """
+        config = {"temperature": temperature}
+        if system_instruction:
+            config["system_instruction"] = system_instruction
+
+        response = client.models.generate_content(
+            model=self.model,
+            contents=prompt,
+            config=config,
+        )
+        return response.text
+
+    async def parse_tool_calls(self, user_message: str, available_tools: list[dict]) -> dict:
+        """
+        Parse user message to determine which MCP tools to call.
+
+        Args:
+            user_message: User's natural language query
+            available_tools: List of available tool definitions
+
+        Returns:
+            Dict with tool_name and arguments
+        """
+        tools_desc = "\n".join([
+            f"- {t['name']}: {t['description']}" for t in available_tools
+        ])
+
+        prompt = f'''Bạn là AI assistant phân tích intent. Xác định công cụ cần gọi.
+
+Các công cụ có sẵn:
+{tools_desc}
+
+Query của người dùng: "{user_message}"
+
+Trả về JSON (chỉ JSON, không giải thích):
+{{
+    "tool_name": "tên_tool_cần_gọi",
+    "arguments": {{...}},
+    "reasoning": "lý do chọn tool này"
+}}
+
+Nếu không cần gọi tool, trả về:
+{{"tool_name": null, "arguments": {{}}, "reasoning": "..."}}'''
+
+        response = await self.generate(prompt, temperature=0.3)
+
+        try:
+            json_match = re.search(r'\{[^{}]*\}', response, re.DOTALL)
+            if json_match:
+                return json.loads(json_match.group())
+            return json.loads(response)
+        except json.JSONDecodeError:
+            return {"tool_name": None, "arguments": {}, "reasoning": "Failed to parse"}
+
+
+def get_gemini_client(model: str | None = None) -> GeminiClient:
+    """Factory function to create Gemini client with specified model."""
+    return GeminiClient(model=model)
+
+
+# Global Gemini client instance (with default model)
+gemini_client = GeminiClient()
+

app/shared/integrations/megallm_client.py

@@ -0,0 +1,133 @@
+"""MegaLLM client using OpenAI-compatible API with retry logic."""
+
+import httpx
+
+from app.core.config import settings
+
+# Timeout configuration for DeepSeek reasoning models (can take longer)
+REQUEST_TIMEOUT = httpx.Timeout(
+    connect=30.0,      # Connection timeout
+    read=300.0,        # Read timeout (5 minutes for reasoning models)
+    write=30.0,        # Write timeout
+    pool=30.0,         # Pool timeout
+)
+
+
+class MegaLLMClient:
+    """Client for MegaLLM (OpenAI-compatible API) operations."""
+
+    def __init__(self, model: str | None = None):
+        """Initialize with optional model override."""
+        self.model = model or settings.default_megallm_model
+        self.api_key = settings.megallm_api_key
+        self.base_url = settings.megallm_base_url
+
+    async def generate(
+        self,
+        prompt: str,
+        temperature: float = 0.7,
+        system_instruction: str | None = None,
+        max_retries: int = 2,
+    ) -> str:
+        """
+        Generate text using MegaLLM (OpenAI-compatible API).
+
+        Args:
+            prompt: Text prompt
+            temperature: Sampling temperature
+            system_instruction: Optional system prompt
+            max_retries: Number of retries on timeout
+
+        Returns:
+            Generated text
+        """
+        if not self.api_key:
+            raise ValueError("MEGALLM_API_KEY is not configured")
+
+        messages = []
+        if system_instruction:
+            messages.append({"role": "system", "content": system_instruction})
+        messages.append({"role": "user", "content": prompt})
+
+        last_error = None
+        for attempt in range(max_retries + 1):
+            try:
+                async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
+                    response = await client.post(
+                        f"{self.base_url}/chat/completions",
+                        headers={
+                            "Authorization": f"Bearer {self.api_key}",
+                            "Content-Type": "application/json",
+                        },
+                        json={
+                            "model": self.model,
+                            "messages": messages,
+                            "temperature": temperature,
+                        },
+                    )
+                    response.raise_for_status()
+                    data = response.json()
+                    return data["choices"][0]["message"]["content"]
+            except httpx.ReadTimeout as e:
+                last_error = e
+                if attempt < max_retries:
+                    continue  # Retry
+                raise
+            except Exception as e:
+                last_error = e
+                raise
+
+        # This shouldn't be reached, but just in case
+        raise last_error if last_error else RuntimeError("Unknown error")
+
+    async def chat(
+        self,
+        messages: list[dict],
+        temperature: float = 0.7,
+        system_instruction: str | None = None,
+    ) -> str:
+        """
+        Generate chat completion using MegaLLM.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content'
+            temperature: Sampling temperature
+            system_instruction: Optional system prompt
+
+        Returns:
+            Generated text response
+        """
+        if not self.api_key:
+            raise ValueError("MEGALLM_API_KEY is not configured")
+
+        chat_messages = []
+        if system_instruction:
+            chat_messages.append({"role": "system", "content": system_instruction})
+
+        # Convert messages to OpenAI format
+        for msg in messages:
+            role = msg.get("role", "user")
+            content = msg.get("content") or msg.get("parts", [""])[0]
+            chat_messages.append({"role": role, "content": content})
+
+        async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
+            response = await client.post(
+                f"{self.base_url}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                },
+                json={
+                    "model": self.model,
+                    "messages": chat_messages,
+                    "temperature": temperature,
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+            return data["choices"][0]["message"]["content"]
+
+
+def get_megallm_client(model: str | None = None) -> MegaLLMClient:
+    """Factory function to create MegaLLM client with specified model."""
+    return MegaLLMClient(model=model)

app/shared/integrations/neo4j_client.py

@@ -0,0 +1,52 @@
+"""Neo4j client for graph database operations."""
+
+from neo4j import AsyncGraphDatabase
+
+from app.core.config import settings
+
+
+class Neo4jClient:
+    """Async Neo4j client for spatial and graph queries."""
+
+    def __init__(self, uri: str, user: str, password: str):
+        """Initialize Neo4j driver."""
+        self._driver = AsyncGraphDatabase.driver(uri, auth=(user, password))
+
+    async def close(self) -> None:
+        """Close the driver connection."""
+        await self._driver.close()
+
+    async def run_cypher(
+        self,
+        query: str,
+        params: dict | None = None,
+    ) -> list[dict]:
+        """
+        Execute a Cypher query and return results.
+
+        Args:
+            query: Cypher query string
+            params: Optional query parameters
+
+        Returns:
+            List of result records as dictionaries
+        """
+        async with self._driver.session() as session:
+            result = await session.run(query, params or {})
+            return await result.data()
+
+    async def verify_connectivity(self) -> bool:
+        """Verify connection to Neo4j."""
+        try:
+            await self._driver.verify_connectivity()
+            return True
+        except Exception:
+            return False
+
+
+# Global Neo4j client instance
+neo4j_client = Neo4jClient(
+    settings.neo4j_uri,
+    settings.neo4j_username,
+    settings.neo4j_password,
+)

app/shared/integrations/siglip_client.py

@@ -0,0 +1,146 @@
+"""SigLIP Image Embedding Client - Local model for image embeddings.
+
+Uses open_clip with ViT-B-16-SigLIP model for generating 768-dim image embeddings.
+Model is loaded once at startup and reused for all requests.
+"""
+
+import io
+from typing import Optional
+import numpy as np
+from PIL import Image
+
+
+class SigLIPClient:
+    """
+    Local SigLIP model client for image embeddings.
+    
+    Model: ViT-B-16-SigLIP (pretrained on WebLI)
+    Output: 768-dimensional normalized embedding vector
+    """
+    
+    _instance: Optional["SigLIPClient"] = None
+    _initialized: bool = False
+    
+    def __new__(cls):
+        """Singleton pattern - only one model instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+    
+    def __init__(self):
+        """Initialize SigLIP model (only once)."""
+        if SigLIPClient._initialized:
+            return
+        
+        self.model = None
+        self.preprocess = None
+        self.device = None
+        self._load_model()
+        SigLIPClient._initialized = True
+    
+    def _load_model(self):
+        """Load SigLIP model."""
+        try:
+            import torch
+            import open_clip
+            
+            print("🔄 Loading SigLIP model (ViT-B-16-SigLIP)...")
+            
+            self.model, _, self.preprocess = open_clip.create_model_and_transforms(
+                "ViT-B-16-SigLIP", pretrained="webli"
+            )
+            self.model.eval()
+            
+            # Use CUDA if available, else CPU
+            self.device = "cuda" if torch.cuda.is_available() else "cpu"
+            self.model.to(self.device)
+            
+            print(f"✅ SigLIP model loaded on {self.device}")
+            
+        except ImportError as e:
+            print(f"⚠️ SigLIP dependencies not installed: {e}")
+            print("   Install with: pip install torch open_clip_torch pillow")
+            raise
+        except Exception as e:
+            print(f"❌ Failed to load SigLIP model: {e}")
+            raise
+    
+    def embed_image(self, image: Image.Image) -> np.ndarray:
+        """
+        Generate embedding for a PIL Image.
+        
+        Args:
+            image: PIL Image object
+            
+        Returns:
+            Normalized 768-dim embedding vector
+        """
+        import torch
+        
+        # Ensure RGB
+        if image.mode != 'RGB':
+            image = image.convert('RGB')
+        
+        # Preprocess and embed
+        image_tensor = self.preprocess(image).unsqueeze(0).to(self.device)
+        
+        with torch.no_grad():
+            image_features = self.model.encode_image(image_tensor)
+            image_features = image_features / image_features.norm(dim=-1, keepdim=True)
+        
+        return image_features.cpu().numpy()[0]
+    
+    def embed_image_bytes(self, image_bytes: bytes) -> np.ndarray:
+        """
+        Generate embedding from raw image bytes.
+        
+        Args:
+            image_bytes: Raw image bytes (JPEG, PNG, etc.)
+            
+        Returns:
+            Normalized 768-dim embedding vector
+        """
+        image = Image.open(io.BytesIO(image_bytes)).convert('RGB')
+        return self.embed_image(image)
+    
+    def embed_image_url(self, image_url: str) -> Optional[np.ndarray]:
+        """
+        Download and embed image from URL.
+        
+        Args:
+            image_url: URL to image
+            
+        Returns:
+            Embedding vector or None if failed
+        """
+        import httpx
+        
+        try:
+            response = httpx.get(image_url, timeout=30.0)
+            response.raise_for_status()
+            return self.embed_image_bytes(response.content)
+        except Exception as e:
+            print(f"⚠️ Failed to embed image from URL: {e}")
+            return None
+    
+    @property
+    def is_loaded(self) -> bool:
+        """Check if model is loaded."""
+        return self.model is not None
+
+
+# Lazy initialization - model loads on first use
+_siglip_client: Optional[SigLIPClient] = None
+
+
+def get_siglip_client() -> SigLIPClient:
+    """Get or create SigLIP client singleton."""
+    global _siglip_client
+    if _siglip_client is None:
+        _siglip_client = SigLIPClient()
+    return _siglip_client
+
+
+# For convenience: pre-initialized client (loads model on import)
+# Uncomment below to load model on app startup:
+# siglip_client = get_siglip_client()

app/shared/integrations/supabase_client.py

@@ -0,0 +1,11 @@
+"""Supabase client for database and auth operations."""
+
+from supabase import create_client
+
+from app.core.config import settings
+
+# Initialize Supabase client
+supabase = create_client(
+    settings.supabase_url,
+    settings.supabase_service_role_key,
+)

app/shared/logger.py

@@ -0,0 +1,208 @@
+"""Logger utility for LocalMate - Structured logging for debugging.
+
+Provides colored console logging with structured output for:
+- API request/response
+- Tool execution
+- LLM calls
+- Workflow tracing
+"""
+
+import logging
+import json
+import sys
+from datetime import datetime
+from typing import Any
+from dataclasses import dataclass, field, asdict
+
+
+# Configure root logger
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+    datefmt="%H:%M:%S",
+    stream=sys.stdout,
+)
+
+# Color codes for terminal
+COLORS = {
+    "RESET": "\033[0m",
+    "BOLD": "\033[1m",
+    "CYAN": "\033[36m",
+    "GREEN": "\033[32m",
+    "YELLOW": "\033[33m",
+    "MAGENTA": "\033[35m",
+    "BLUE": "\033[34m",
+    "RED": "\033[31m",
+}
+
+
+def colorize(text: str, color: str) -> str:
+    """Add color to text for terminal output."""
+    return f"{COLORS.get(color, '')}{text}{COLORS['RESET']}"
+
+
+class LocalMateLogger:
+    """Structured logger for LocalMate with colored output."""
+    
+    def __init__(self, name: str):
+        self.logger = logging.getLogger(name)
+        self.name = name
+    
+    def _format_data(self, data: Any, max_len: int = 500) -> str:
+        """Format data for logging, truncating if needed."""
+        if data is None:
+            return "None"
+        
+        if isinstance(data, (dict, list)):
+            try:
+                formatted = json.dumps(data, ensure_ascii=False, default=str)
+                if len(formatted) > max_len:
+                    return formatted[:max_len] + "..."
+                return formatted
+            except:
+                return str(data)[:max_len]
+        
+        text = str(data)
+        return text[:max_len] + "..." if len(text) > max_len else text
+    
+    def api_request(self, endpoint: str, method: str, params: dict = None, body: Any = None):
+        """Log API request."""
+        msg = f"{colorize('→ REQUEST', 'CYAN')} {colorize(method, 'BOLD')} {endpoint}"
+        if params:
+            msg += f"\n  Params: {self._format_data(params)}"
+        if body:
+            msg += f"\n  Body: {self._format_data(body)}"
+        self.logger.info(msg)
+    
+    def api_response(self, endpoint: str, status: int, data: Any = None, duration_ms: float = None):
+        """Log API response."""
+        status_color = "GREEN" if status < 400 else "RED"
+        msg = f"{colorize('← RESPONSE', status_color)} {endpoint} [{status}]"
+        if duration_ms:
+            msg += f" ({duration_ms:.0f}ms)"
+        if data:
+            msg += f"\n  Data: {self._format_data(data)}"
+        self.logger.info(msg)
+    
+    def tool_call(self, tool_name: str, arguments: dict):
+        """Log tool call start."""
+        msg = f"{colorize('🔧 TOOL', 'MAGENTA')} {colorize(tool_name, 'BOLD')}"
+        msg += f"\n  Args: {self._format_data(arguments)}"
+        self.logger.info(msg)
+    
+    def tool_result(self, tool_name: str, result_count: int, sample: Any = None):
+        """Log tool result."""
+        msg = f"{colorize('✓ RESULT', 'GREEN')} {tool_name} → {result_count} results"
+        if sample:
+            msg += f"\n  Sample: {self._format_data(sample, max_len=200)}"
+        self.logger.info(msg)
+    
+    def llm_call(self, provider: str, model: str, prompt_preview: str = None):
+        """Log LLM call."""
+        msg = f"{colorize('🤖 LLM', 'BLUE')} {provider}/{model}"
+        if prompt_preview:
+            preview = prompt_preview[:100] + "..." if len(prompt_preview) > 100 else prompt_preview
+            msg += f"\n  Prompt: {preview}"
+        self.logger.info(msg)
+    
+    def llm_response(self, provider: str, response_preview: str = None, tokens: int = None):
+        """Log LLM response."""
+        msg = f"{colorize('💬 LLM RESPONSE', 'BLUE')} {provider}"
+        if tokens:
+            msg += f" ({tokens} tokens)"
+        if response_preview:
+            preview = response_preview[:150] + "..." if len(response_preview) > 150 else response_preview
+            msg += f"\n  Response: {preview}"
+        self.logger.info(msg)
+    
+    def workflow_step(self, step: str, details: str = None):
+        """Log workflow step."""
+        msg = f"{colorize('▶', 'YELLOW')} {step}"
+        if details:
+            msg += f": {details}"
+        self.logger.info(msg)
+    
+    def error(self, message: str, error: Exception = None):
+        """Log error."""
+        msg = f"{colorize('❌ ERROR', 'RED')} {message}"
+        if error:
+            msg += f"\n  {type(error).__name__}: {str(error)}"
+        self.logger.error(msg)
+    
+    def debug(self, message: str, data: Any = None):
+        """Log debug info."""
+        msg = f"{colorize('DEBUG', 'CYAN')} {message}"
+        if data:
+            msg += f": {self._format_data(data)}"
+        self.logger.debug(msg)
+
+
+@dataclass
+class WorkflowStep:
+    """A step in the agent workflow."""
+    
+    step_name: str
+    tool_name: str | None = None
+    purpose: str = ""
+    input_summary: str = ""
+    output_summary: str = ""
+    result_count: int = 0
+    duration_ms: float = 0
+
+
+@dataclass
+class AgentWorkflow:
+    """Complete workflow trace for a chat request."""
+    
+    query: str
+    intent_detected: str = ""
+    steps: list[WorkflowStep] = field(default_factory=list)
+    total_duration_ms: float = 0
+    tools_used: list[str] = field(default_factory=list)
+    
+    def add_step(self, step: WorkflowStep):
+        """Add a step to the workflow."""
+        self.steps.append(step)
+        if step.tool_name and step.tool_name not in self.tools_used:
+            self.tools_used.append(step.tool_name)
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "query": self.query,
+            "intent_detected": self.intent_detected,
+            "tools_used": self.tools_used,
+            "steps": [
+                {
+                    "step": s.step_name,
+                    "tool": s.tool_name,
+                    "purpose": s.purpose,
+                    "results": s.result_count,
+                }
+                for s in self.steps
+            ],
+            "total_duration_ms": round(self.total_duration_ms, 1),
+        }
+    
+    def to_summary(self) -> str:
+        """Generate human-readable workflow summary."""
+        lines = [f"📊 **Workflow Summary**"]
+        lines.append(f"- Query: \"{self.query[:50]}{'...' if len(self.query) > 50 else ''}\"")
+        lines.append(f"- Intent: {self.intent_detected}")
+        lines.append(f"- Tools: {', '.join(self.tools_used) or 'None'}")
+        
+        if self.steps:
+            lines.append("\n**Steps:**")
+            for i, step in enumerate(self.steps, 1):
+                tool_info = f" ({step.tool_name})" if step.tool_name else ""
+                results_info = f" → {step.result_count} results" if step.result_count else ""
+                lines.append(f"{i}. {step.step_name}{tool_info}{results_info}")
+        
+        lines.append(f"\n⏱️ Total: {self.total_duration_ms:.0f}ms")
+        return "\n".join(lines)
+
+
+# Global logger instances
+agent_logger = LocalMateLogger("agent")
+api_logger = LocalMateLogger("api")
+tool_logger = LocalMateLogger("tools")

app/shared/models/__init__.py

@@ -0,0 +1 @@
+"""Models module."""

app/shared/models/base.py

@@ -0,0 +1,26 @@
+"""Base model classes."""
+
+from datetime import datetime
+
+from sqlalchemy import func
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    """Base class for all models."""
+
+    pass
+
+
+class TimestampMixin:
+    """Mixin for created_at and updated_at timestamps."""
+
+    created_at: Mapped[datetime] = mapped_column(
+        default=func.now(),
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        default=func.now(),
+        onupdate=func.now(),
+        nullable=False,
+    )

docs/TRIP_PLANNER_PLAN.md

@@ -0,0 +1,426 @@
+# Trip Planner Feature - Technical Design Document
+
+**Version**: 1.0  
+**Date**: 2025-12-15  
+**Status**: Draft
+
+---
+
+## 📋 Overview
+
+Tính năng Trip Planner cho phép user lên kế hoạch chuyến đi bằng cách:
+1. Chat với AI để tìm địa điểm
+2. Thêm địa điểm vào Plan Box
+3. Tối ưu lộ trình bằng thuật toán TSP
+4. Chỉnh sửa/thay thế địa điểm
+
+---
+
+## 🎯 User Flow
+
+```mermaid
+flowchart TD
+    A[User Chat] --> B{AI Response}
+    B --> C[Place Cards với 'Add to Plan']
+    C --> |Click Add| D[Plan Box]
+    D --> E{User Actions}
+    E --> |Optimize| F[TSP Algorithm]
+    E --> |Drag & Drop| G[Reorder Places]
+    E --> |Replace| H[AI hỏi criteria mới]
+    H --> I[Suggest Alternatives]
+    I --> D
+    F --> D
+```
+
+---
+
+## 🏗️ Architecture
+
+### Backend Components
+
+```
+app/
+├── planner/
+│   ├── __init__.py
+│   ├── models.py          # Plan, PlanItem schemas
+│   ├── router.py          # API endpoints
+│   ├── service.py         # Business logic
+│   └── tsp.py             # TSP optimization algorithm
+└── mcp/tools/
+    └── graph_tool.py      # Neo4j + OSM (có sẵn)
+```
+
+### API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/planner/create` | Tạo plan mới |
+| GET | `/planner/{plan_id}` | Lấy plan |
+| POST | `/planner/{plan_id}/add` | Thêm place vào plan |
+| DELETE | `/planner/{plan_id}/remove/{item_id}` | Xóa place |
+| PUT | `/planner/{plan_id}/reorder` | Sắp xếp lại thứ tự |
+| POST | `/planner/{plan_id}/optimize` | Chạy TSP |
+| POST | `/planner/{plan_id}/replace/{item_id}` | Thay thế place |
+
+---
+
+## 📦 Data Models
+
+### Plan
+
+```python
+@dataclass
+class Plan:
+    plan_id: str
+    user_id: str
+    name: str
+    items: list[PlanItem]
+    created_at: datetime
+    updated_at: datetime
+    total_distance_km: float | None
+    estimated_duration_min: int | None
+```
+
+### PlanItem
+
+```python
+@dataclass
+class PlanItem:
+    item_id: str
+    place_id: str
+    name: str
+    category: str
+    lat: float
+    lng: float
+    order: int  # Thứ tự trong plan
+    added_at: datetime
+    notes: str | None
+```
+
+---
+
+## 🧮 TSP Algorithm
+
+### Approach: Nearest Neighbor + 2-opt Optimization
+
+```python
+# app/planner/tsp.py
+
+from math import radians, sin, cos, sqrt, atan2
+
+def haversine(lat1, lng1, lat2, lng2) -> float:
+    """Calculate distance between 2 points in km."""
+    R = 6371  # Earth's radius in km
+    dlat = radians(lat2 - lat1)
+    dlng = radians(lng2 - lng1)
+    a = sin(dlat/2)**2 + cos(radians(lat1)) * cos(radians(lat2)) * sin(dlng/2)**2
+    return 2 * R * atan2(sqrt(a), sqrt(1-a))
+
+
+def calculate_distance_matrix(places: list[dict]) -> list[list[float]]:
+    """Build NxN distance matrix."""
+    n = len(places)
+    matrix = [[0.0] * n for _ in range(n)]
+    for i in range(n):
+        for j in range(n):
+            if i != j:
+                matrix[i][j] = haversine(
+                    places[i]['lat'], places[i]['lng'],
+                    places[j]['lat'], places[j]['lng']
+                )
+    return matrix
+
+
+def nearest_neighbor(matrix: list[list[float]], start: int = 0) -> list[int]:
+    """Greedy nearest neighbor heuristic."""
+    n = len(matrix)
+    visited = [False] * n
+    tour = [start]
+    visited[start] = True
+    
+    for _ in range(n - 1):
+        current = tour[-1]
+        nearest = -1
+        min_dist = float('inf')
+        for j in range(n):
+            if not visited[j] and matrix[current][j] < min_dist:
+                min_dist = matrix[current][j]
+                nearest = j
+        tour.append(nearest)
+        visited[nearest] = True
+    
+    return tour
+
+
+def two_opt(tour: list[int], matrix: list[list[float]]) -> list[int]:
+    """2-opt local search improvement."""
+    improved = True
+    while improved:
+        improved = False
+        for i in range(1, len(tour) - 1):
+            for j in range(i + 1, len(tour)):
+                # Calculate improvement
+                d1 = matrix[tour[i-1]][tour[i]] + matrix[tour[j-1]][tour[j]]
+                d2 = matrix[tour[i-1]][tour[j-1]] + matrix[tour[i]][tour[j]]
+                if d2 < d1:
+                    # Reverse segment
+                    tour[i:j] = tour[i:j][::-1]
+                    improved = True
+    return tour
+
+
+def optimize_route(places: list[dict], start_index: int = 0) -> tuple[list[int], float]:
+    """
+    Main TSP optimization function.
+    
+    Args:
+        places: List of places with 'lat', 'lng' keys
+        start_index: Index of starting place
+        
+    Returns:
+        (optimized_order, total_distance_km)
+    """
+    if len(places) <= 2:
+        return list(range(len(places))), 0.0
+    
+    matrix = calculate_distance_matrix(places)
+    tour = nearest_neighbor(matrix, start_index)
+    tour = two_opt(tour, matrix)
+    
+    # Calculate total distance
+    total = sum(matrix[tour[i]][tour[i+1]] for i in range(len(tour)-1))
+    
+    return tour, total
+```
+
+### Complexity
+
+- **Nearest Neighbor**: O(n²)
+- **2-opt**: O(n²) per iteration, ~O(n³) worst case
+- **Suitable for**: Up to ~50 places (typical trip size)
+
+---
+
+## 🔄 Replace Flow
+
+### Workflow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant F as Frontend
+    participant B as Backend
+    participant AI as LLM Agent
+    
+    U->>F: Click Replace on Place X
+    F->>B: POST /chat {"message": "replace_context", "place_id": X}
+    B->>AI: "User muốn thay thế [Place X]. Hỏi họ muốn tìm địa điểm như nào?"
+    AI->>B: "Bạn muốn tìm địa điểm thay thế như thế nào? (VD: gần hơn, rẻ hơn, khác loại...)"
+    B->>F: Response
+    F->>U: Display AI question
+    U->>F: "Tìm quán cafe yên tĩnh hơn"
+    F->>B: POST /chat with context
+    B->>AI: Search for alternatives
+    AI->>B: Return alternatives as Place Cards
+    B->>F: Place Cards
+    U->>F: Select replacement
+    F->>B: PUT /planner/{plan_id}/replace/{item_id}
+    B->>F: Updated Plan
+```
+
+### API Request
+
+```json
+// POST /planner/{plan_id}/replace/{item_id}
+{
+    "new_place_id": "cafe_xyz_123",
+    "new_place": {
+        "name": "Cafe XYZ",
+        "lat": 16.0544,
+        "lng": 108.2480,
+        "category": "Coffee shop"
+    }
+}
+```
+
+---
+
+## 🎨 Frontend Integration
+
+### Chat Response Format
+
+```json
+{
+    "response": "Đây là một số quán cafe gần Cầu Rồng:",
+    "places": [
+        {
+            "place_id": "sound_cafe",
+            "name": "Sound Cafe",
+            "category": "Coffee shop",
+            "lat": 16.0611,
+            "lng": 108.2272,
+            "rating": 4.7,
+            "description": "Quán cafe âm nhạc acoustic...",
+            "distance_km": 1.75,
+            "actions": ["add_to_plan", "view_details"]
+        }
+    ],
+    "plan_context": {
+        "plan_id": "plan_abc123",
+        "item_count": 3
+    }
+}
+```
+
+### Plan Box State
+
+```typescript
+interface PlanState {
+    planId: string;
+    items: PlanItem[];
+    isOptimized: boolean;
+    totalDistanceKm: number;
+    estimatedDurationMin: number;
+}
+
+interface PlanItem {
+    itemId: string;
+    placeId: string;
+    name: string;
+    category: string;
+    lat: number;
+    lng: number;
+    order: number;
+}
+```
+
+---
+
+## 📐 Implementation Plan
+
+### Phase 1: Core API (Week 1)
+
+- [ ] Create `app/planner/` module
+- [ ] Implement `models.py` with Pydantic schemas
+- [ ] Implement `tsp.py` with optimization algorithm
+- [ ] Create `router.py` with basic CRUD endpoints
+- [ ] Add session-based plan storage
+
+### Phase 2: Chat Integration (Week 2)
+
+- [ ] Modify chat response format to include `places` array
+- [ ] Add `add_to_plan` action handling in agent
+- [ ] Implement replace flow with context tracking
+- [ ] Store plan context per user session
+
+### Phase 3: TSP & Optimization (Week 3)
+
+- [ ] Implement `/optimize` endpoint
+- [ ] Add distance matrix calculation using graph_tool
+- [ ] Integrate with Neo4j for real distances (optional: OSRM for road distances)
+- [ ] Return optimized order with total distance
+
+### Phase 4: Frontend (Week 4)
+
+- [ ] Create Place Card component with actions
+- [ ] Implement Plan Box with drag-drop (react-beautiful-dnd)
+- [ ] Add Optimize button with loading state
+- [ ] Implement Replace flow UI
+
+---
+
+## 🔧 Technical Considerations
+
+### Storage Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| In-memory (Redis) | Fast, simple | Lost on restart |
+| Supabase | Persistent, user-linked | Requires auth |
+| Session-based | No auth needed | Client-side storage |
+
+**Recommendation**: Start with session-based (in-memory per user_id), migrate to Supabase later.
+
+### Distance Calculation
+
+| Method | Accuracy | Speed |
+|--------|----------|-------|
+| Haversine | ~95% | Very fast |
+| OSRM API | ~99% (road) | Slower |
+| Graph (Neo4j) | ~95% | Fast |
+
+**Recommendation**: Use Haversine for MVP, add OSRM for production.
+
+### Rate Limits
+
+- OpenStreetMap Nominatim: 1 req/sec
+- OSRM: Self-hosted or 10 req/min (demo server)
+
+---
+
+## 📝 Example Usage
+
+### 1. User Chat
+
+```
+User: "Tìm quán cafe và nhà hàng hải sản gần Mỹ Khê"
+```
+
+### 2. AI Response with Place Cards
+
+```
+AI: "Đây là một số gợi ý cho bạn:
+
+☕ **Cafe**
+- [Nia Coffee] - 4.3★ - 1.2km [Add to Plan]
+- [Sound Cafe] - 4.7★ - 1.8km [Add to Plan]
+
+🦐 **Hải sản**
+- [My Hanh Seafood] - 4.8★ - 0.5km [Add to Plan]
+- [Bé Ni 2] - 4.8★ - 0.6km [Add to Plan]
+"
+```
+
+### 3. Plan Box
+
+```
+📍 Your Plan (4 places)
+┌──────────────────────────────┐
+│ 1. Nia Coffee      [✏️] [🔄] │
+│ 2. Sound Cafe      [✏️] [🔄] │
+│ 3. My Hanh Seafood [✏️] [🔄] │
+│ 4. Bé Ni 2         [✏️] [🔄] │
+└───────────────────���──────────┘
+Total: 8.2km | ~45min
+
+[🔀 Optimize Route] [📤 Export]
+```
+
+### 4. After Optimization
+
+```
+📍 Your Plan (Optimized ✓)
+┌──────────────────────────────┐
+│ 1. My Hanh Seafood (start)   │
+│ 2. Bé Ni 2         (+0.3km)  │
+│ 3. Sound Cafe      (+1.2km)  │
+│ 4. Nia Coffee      (+0.8km)  │
+└──────────────────────────────┘
+Total: 2.3km | ~15min (Saved 5.9km!)
+```
+
+---
+
+## 🔗 Related Files
+
+- [`app/mcp/tools/graph_tool.py`](file:///Volumes/WorkSpace/Project/LocalMate/localmate-danang-backend-v2/app/mcp/tools/graph_tool.py) - Existing geocoding/spatial search
+- [`app/shared/chat_history.py`](file:///Volumes/WorkSpace/Project/LocalMate/localmate-danang-backend-v2/app/shared/chat_history.py) - Session management
+- [`app/agent/mmca_agent.py`](file:///Volumes/WorkSpace/Project/LocalMate/localmate-danang-backend-v2/app/agent/mmca_agent.py) - Chat agent
+
+---
+
+## ✅ Success Metrics
+
+- User can add 5+ places to plan in < 2 minutes
+- TSP optimization runs in < 500ms for 20 places
+- Replace flow completes in < 3 exchanges with AI

docs/neo4j_test_report.md

@@ -0,0 +1,88 @@
+# Neo4j Category Filter Test Report
+
+**Date**: 2025-12-15
+
+## Test Coordinates
+
+| Test Case | Latitude | Longitude | Max Distance (km) |
+|-----------|----------|-----------|-------------------|
+| Case 1 | 16.0626442 | 108.2462143 | 18.72 |
+| Case 2 | 16.0623184 | 108.2306049 | 17.94 |
+
+## Results by Category
+
+| Category | Case 1 | Case 2 |
+|----------|:------:|:------:|
+| restaurant | 10 | 10 |
+| coffee | 10 | 10 |
+| bar | 10 | 10 |
+| seafood | 4 | 4 |
+| steak | 3 | 3 |
+| gym | 3 | 3 |
+| hotel | 1 | 1 |
+| attraction | 0 | 0 |
+| spa | 0 | 0 |
+
+---
+
+## All Available Categories (69 total)
+
+### 🍜 Ăn uống (Food & Drink)
+| Category | Category | Category |
+|----------|----------|----------|
+| Asian restaurant | Bakery | Bar |
+| Bistro | Breakfast restaurant | Cafe |
+| Cantonese restaurant | Chicken restaurant | Chinese restaurant |
+| Cocktail bar | Coffee shop | Country food restaurant |
+| Deli | Dessert shop | Dumpling restaurant |
+| Espresso bar | Family restaurant | Fine dining restaurant |
+| Food court | French restaurant | Hamburger restaurant |
+| Hot pot restaurant | Ice cream shop | Indian restaurant |
+| Irish pub | Italian restaurant | Izakaya restaurant |
+| Japanese restaurant | Korean BBQ restaurant | Korean restaurant |
+| Live music bar | Malaysian restaurant | Mexican restaurant |
+| Noodle shop | Pho restaurant | Pizza restaurant |
+| Ramen restaurant | Restaurant | Restaurant or cafe |
+| Rice cake shop | Sandwich shop | Seafood restaurant |
+| Soup shop | Sports bar | Steak house |
+| Sushi restaurant | Takeout Restaurant | Tiffin center |
+| Udon noodle restaurant | Vegan restaurant | Vegetarian restaurant |
+| Vietnamese restaurant | | |
+
+### 🏨 Lưu trú (Accommodation)
+- Hotel
+- Holiday apartment rental
+
+### 🏃 Thể thao (Sports)
+- Athletic club
+- Badminton court
+- Fitness center
+- Gym
+- Pickleball court
+- Soccer field
+- Sports club
+- Sports complex
+- Tennis court
+
+### 🎮 Giải trí (Entertainment)
+- Board game club
+- Disco club
+- Game store
+- Movie theater
+- Musical club
+
+---
+
+## API Usage
+
+```bash
+POST /api/v1/nearby
+{
+  "lat": 16.0626442,
+  "lng": 108.2462143,
+  "max_distance_km": 5,
+  "category": "coffee"
+}
+```
+
+> **Note**: Category filter sử dụng `CONTAINS` nên chỉ cần keyword (vd: `coffee` match `Coffee shop`).

docs/phase1.md

@@ -0,0 +1,86 @@
+# ĐỀ XUẤT GIẢI PHÁP: HỆ THỐNG MULTI-MODAL CONTEXTUAL AGENT (MMCA)
+
+## 1. Tổng quan (Executive Summary)
+Dự án nhằm mục tiêu xây dựng một **Intelligent Agent (Tác nhân thông minh)** có khả năng xử lý đa phương thức (văn bản, hình ảnh) và dữ liệu không gian (địa điểm).
+
+Giải pháp sử dụng kiến trúc **Model Context Protocol (MCP)** để tiêu chuẩn hóa kết nối giữa Agent và các công cụ dữ liệu. Hệ thống kết hợp sức mạnh của **Vector Database (Supabase/pgvector)** cho việc tìm kiếm ngữ nghĩa/hình ảnh và **Graph Database (Neo4j)** cho việc truy vấn các mối quan hệ địa lý phức tạp.
+
+## 2. Kiến trúc Hệ thống (Architecture)
+
+
+
+Hệ thống hoạt động theo mô hình **Agent-Centric Orchestration**, trong đó Agent chính đóng vai trò là nhạc trưởng, phân tích intent (ý định) của người dùng để gọi đúng công cụ (Tool) thông qua giao thức MCP.
+
+### Các thành phần chính (Tech Stack):
+1.  **Orchestrator (Agent):** LLM (Large Language Model) có khả năng Function Calling.
+2.  **MCP Server:** Middleware chứa logic của 3 tools.
+3.  **Vector Store:** **Supabase** với extension **pgvector**.
+4.  **Knowledge Graph:** **Neo4j** (hỗ trợ Spatial & Graph algorithms).
+
+---
+
+## 3. Chi tiết các Công cụ MCP (MCP Tools Definition)
+
+Agent sẽ được kết nối với một MCP Server expose ra 3 tools chính sau đây:
+
+### Tool 1: `retrieve_context_text` (RAG Text)
+* **Mục đích:** Tìm kiếm thông tin chi tiết, mô tả, đánh giá hoặc menu từ kho dữ liệu văn bản.
+* **Công nghệ:** **Supabase + pgvector**.
+* **Cơ chế:**
+    1.  Input query được chuyển đổi thành vector (embedding).
+    2.  Thực hiện Similarity Search (Cosine Similarity) trên bảng `text_embeddings` trong Supabase.
+    3.  Trả về các đoạn text (chunks) có độ tương đồng cao nhất.
+* **Use-case:** "Tìm các quán có món Phở được review là nước dùng đậm đà."
+
+### Tool 2: `retrieve_similar_visuals` (RAG Image)
+* **Mục đích:** Tìm kiếm các địa điểm hoặc vật thể có đặc điểm hình ảnh tương đồng với ảnh đầu vào (Vibe search/Visual search).
+* **Công nghệ:** **Supabase + pgvector** (Lưu trữ Image Embeddings - ví dụ dùng model CLIP).
+* **Cơ chế:**
+    1.  Ảnh input được đưa qua model embedding để lấy vector.
+    2.  Truy vấn pgvector để tìm các ảnh đã lưu trữ có vector gần nhất.
+    3.  Map từ ID ảnh sang thông tin thực thể (ví dụ: tìm quán cafe có phong cách decor giống ảnh này).
+* **Use-case:** "Tìm chỗ nào có không gian giống trong bức ảnh này."
+
+### Tool 3: `find_nearby_places` (Graph Spatial)
+* **Mục đích:** Tìm kiếm địa điểm dựa trên vị trí địa lý và loại hình dịch vụ (POIs).
+* **Công nghệ:** **Neo4j** (Spatial capabilities & Relationship traversal).
+* **Cơ chế:**
+    1.  Sử dụng Point data type trong Neo4j để lưu tọa độ.
+    2.  Query Cypher để tìm các node `Place` có quan hệ `NEAR` hoặc tính khoảng cách Euclidean/Haversine từ điểm input.
+    3.  Filter theo Label/Property (ví dụ: `Type: 'Cafe'`, `Type: 'Restaurant'`).
+* **Use-case:** "Tìm quán cafe gần khách sạn Hilton nhất."
+
+---
+
+## 4. Luồng xử lý của Agent (Agent Prompting & Workflow)
+
+Agent sẽ được cấu hình với **System Prompt** đặc thù để có khả năng "ReAct" (Reasoning + Acting):
+
+> **System Prompt Strategy:**
+> *"Bạn là một trợ lý du lịch thông minh. Bạn có quyền truy cập vào 3 công cụ qua MCP.
+> - Khi người dùng hỏi về vị trí, khoảng cách, hoặc 'gần đây', hãy ưu tiên dùng `find_nearby_places`.
+> - Khi người dùng đưa ra một bức ảnh hoặc mô tả về màu sắc, phong cách hình ảnh, hãy dùng `retrieve_similar_visuals`.
+> - Khi người dùng hỏi chi tiết về nội dung, menu, đánh giá, hãy dùng `retrieve_context_text`.
+> Lưu ý: Bạn có thể cần gọi nhiều tools tuần tự hoặc song song để tổng hợp câu trả lời cuối cùng."*
+
+### Kịch bản ví dụ (User Journey):
+**User Input:** *"Tìm cho tôi quán cafe nào gần khách sạn Rex, có không gian xanh mát giống như bức ảnh tôi gửi này và xem menu có bán Bạc Xỉu không?"*
+
+**Agent Execution Plan:**
+1.  **Step 1 (Graph):** Gọi `find_nearby_places(location="Rex Hotel", type="Cafe", radius=500m)`.
+    * *Result:* List [Cafe A, Cafe B, Cafe C].
+2.  **Step 2 (RAG Image):** Với danh sách trên, gọi `retrieve_similar_visuals(image=input_img, filter_ids=[A, B, C])`.
+    * *Result:* Cafe B có điểm tương đồng cao nhất (về không gian xanh).
+3.  **Step 3 (RAG Text):** Gọi `retrieve_context_text(query="menu Bạc Xỉu", entity_id="Cafe B")`.
+    * *Result:* Tìm thấy text "Cafe B nổi tiếng với món Bạc Xỉu cốt dừa".
+4.  **Final Response:** "Tôi tìm thấy **Cafe B** cách khách sạn Rex 200m. Quán có không gian vườn xanh rất giống ảnh bạn gửi và trong menu có món Bạc Xỉu được đánh giá cao."
+
+---
+
+## 5. Tại sao chọn Tech Stack này? (Justification)
+
+| Công nghệ | Vai trò | Tại sao chọn? |
+| :--- | :--- | :--- |
+| **MCP (Model Context Protocol)** | Giao tiếp | Chuẩn hóa việc kết nối LLM với các nguồn dữ liệu rời rạc, dễ dàng mở rộng thêm tool sau này mà không cần sửa code Agent quá nhiều. |
+| **Neo4j** | Graph DB | Xử lý truy vấn không gian (Spatial) và các mối quan hệ (ví dụ: "quán cafe gần rạp phim") tốt hơn và trực quan hơn nhiều so với SQL truyền thống. |
+| **Supabase + pgvector** | Vector DB | Giải pháp Open-source mạnh mẽ, tích hợp sẵn PostgreSQL, chi phí thấp và hiệu năng cao cho việc lưu trữ embeddings văn bản và hình ảnh. |

docs/schema_supabase.txt

@@ -0,0 +1,110 @@
+-- WARNING: This schema is for context only and is not meant to be run.
+-- Table order and constraints may not be valid for execution.
+
+CREATE TABLE public.bookings (
+  id uuid NOT NULL DEFAULT uuid_generate_v4(),
+  user_id uuid NOT NULL,
+  itinerary_id uuid,
+  stop_id uuid,
+  provider text NOT NULL,
+  type text NOT NULL,
+  external_id text NOT NULL,
+  status text NOT NULL DEFAULT 'pending'::text,
+  price numeric,
+  currency text NOT NULL DEFAULT 'VND'::text,
+  place_id text,
+  raw_request jsonb,
+  raw_response jsonb,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  updated_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT bookings_pkey PRIMARY KEY (id),
+  CONSTRAINT bookings_user_id_fkey FOREIGN KEY (user_id) REFERENCES public.profiles(id),
+  CONSTRAINT bookings_itinerary_id_fkey FOREIGN KEY (itinerary_id) REFERENCES public.itineraries(id),
+  CONSTRAINT bookings_stop_id_fkey FOREIGN KEY (stop_id) REFERENCES public.itinerary_stops(id)
+);
+CREATE TABLE public.itineraries (
+  id uuid NOT NULL DEFAULT uuid_generate_v4(),
+  user_id uuid NOT NULL,
+  title text NOT NULL,
+  start_date date,
+  end_date date,
+  total_days integer NOT NULL CHECK (total_days >= 1),
+  total_budget numeric,
+  currency text NOT NULL DEFAULT 'VND'::text,
+  meta jsonb,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  updated_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT itineraries_pkey PRIMARY KEY (id),
+  CONSTRAINT itineraries_user_id_fkey FOREIGN KEY (user_id) REFERENCES public.profiles(id)
+);
+CREATE TABLE public.itinerary_stops (
+  id uuid NOT NULL DEFAULT uuid_generate_v4(),
+  itinerary_id uuid NOT NULL,
+  day_index integer NOT NULL CHECK (day_index >= 1),
+  order_index integer NOT NULL CHECK (order_index >= 1),
+  place_id text NOT NULL,
+  arrival_time timestamp with time zone,
+  stay_minutes integer,
+  notes text,
+  tags ARRAY,
+  snapshot jsonb,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  updated_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT itinerary_stops_pkey PRIMARY KEY (id),
+  CONSTRAINT itinerary_stops_itinerary_id_fkey FOREIGN KEY (itinerary_id) REFERENCES public.itineraries(id)
+);
+CREATE TABLE public.place_image_embeddings (
+  id uuid NOT NULL DEFAULT uuid_generate_v4(),
+  place_id text NOT NULL,
+  embedding USER-DEFINED,
+  image_url text,
+  metadata jsonb,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT place_image_embeddings_pkey PRIMARY KEY (id)
+);
+CREATE TABLE public.place_text_embeddings (
+  id uuid NOT NULL DEFAULT uuid_generate_v4(),
+  place_id text NOT NULL,
+  embedding USER-DEFINED,
+  content_type text,
+  source_text text,
+  metadata jsonb,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT place_text_embeddings_pkey PRIMARY KEY (id)
+);
+CREATE TABLE public.places_metadata (
+  place_id text NOT NULL,
+  name text NOT NULL,
+  name_vi text,
+  category text,
+  address text,
+  rating numeric,
+  price_min numeric,
+  price_max numeric,
+  tags ARRAY DEFAULT '{}'::text[],
+  coordinates USER-DEFINED,
+  raw_data jsonb DEFAULT '{}'::jsonb,
+  created_at timestamp with time zone DEFAULT now(),
+  updated_at timestamp with time zone DEFAULT now(),
+  CONSTRAINT places_metadata_pkey PRIMARY KEY (place_id)
+);
+CREATE TABLE public.profiles (
+  id uuid NOT NULL,
+  full_name text NOT NULL DEFAULT ''::text,
+  phone text,
+  role text NOT NULL DEFAULT 'tourist'::text CHECK (role = ANY (ARRAY['tourist'::text, 'driver'::text, 'admin'::text])),
+  locale text NOT NULL DEFAULT 'vi_VN'::text,
+  avatar_url text,
+  created_at timestamp with time zone NOT NULL DEFAULT now(),
+  updated_at timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT profiles_pkey PRIMARY KEY (id),
+  CONSTRAINT profiles_id_fkey FOREIGN KEY (id) REFERENCES auth.users(id)
+);
+CREATE TABLE public.spatial_ref_sys (
+  srid integer NOT NULL CHECK (srid > 0 AND srid <= 998999),
+  auth_name character varying,
+  auth_srid integer,
+  srtext character varying,
+  proj4text character varying,
+  CONSTRAINT spatial_ref_sys_pkey PRIMARY KEY (srid)
+);

pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "localmate-backend-v2"
+version = "0.2.0"
+description = "LocalMate Da Nang - Multi-Modal Contextual Agent API"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "sqlalchemy>=2.0.0",
+    "asyncpg>=0.30.0",
+    "greenlet>=3.0.0",
+    "pydantic>=2.10.0",
+    "pydantic-settings>=2.6.0",
+    "supabase>=2.10.0",
+    "neo4j>=5.26.0",
+    "google-genai>=1.0.0",
+    "pgvector>=0.3.0",
+    "python-dotenv>=1.0.0",
+    "httpx>=0.28.0",
+    "python-multipart>=0.0.9",
+    # Image embedding (SigLIP local)
+    "torch>=2.0.0",
+    "open_clip_torch>=2.24.0",
+    "pillow>=10.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.28.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+asyncio_default_fixture_loop_scope = "function"

tests/react_comparison_report.md

@@ -0,0 +1,85 @@
+# LocalMate Agent Test Report
+
+**Generated:** 2025-12-17 05:11:43
+
+## Summary
+
+| Metric | Single Mode | ReAct Mode |
+|--------|-------------|------------|
+| Total Tests | 1 | 1 |
+| Success | 1 | 1 |
+| Avg Duration | 10653ms | 13297ms |
+
+---
+
+## Detailed Results
+
+### Test Case 1: Simple text search - no location
+
+**Query:** `Quán cafe view đẹp`
+
+#### Single Mode
+
+- **Status:** ✅ Success
+- **Duration:** 10653ms
+- **Tools Used:** retrieve_context_text
+
+**Workflow:**
+  - Intent Analysis
+    Tool: `None` | Results: 0
+  - Tool Planning
+    Tool: `None` | Results: 0
+  - Execute retrieve_context_text
+    Tool: `retrieve_context_text` | Results: 5
+  - LLM Synthesis
+    Tool: `None` | Results: 0
+
+**Response Preview:**
+> Chào bạn! Dựa trên yêu cầu "quán cafe view đẹp" của bạn, mình gợi ý một số địa điểm nổi bật ở Đà Nẵng sau đây nhé:
+
+☕ **Top 3 quán cafe view đẹp đáng thử:**
+
+1. **Nhớ Một Người**  
+   - Địa chỉ: 06 Tr...
+
+#### ReAct Mode
+
+- **Status:** ✅ Success
+- **Duration:** 13297ms
+- **Tools Used:** retrieve_context_text
+- **Steps:** 3
+- **Intent Detected:** react_multi_step
+
+**Workflow Steps:**
+  - Step 1: User đang tìm quán cafe có view đẹp ở Đà Nẵng. Đây...
+    Tool: `retrieve_context_text` | Results: 10
+  - Step 2: User đang tìm quán cafe có view đẹp ở Đà Nẵng. Tôi...
+    Tool: `retrieve_context_text` | Results: 10
+  - Step 3: Tôi đã có tổng cộng 10 kết quả từ hai lần gọi retr...
+    Tool: `None` | Results: 0
+
+**Response Preview:**
+> Chào bạn! Dưới đây là một số quán cafe có view đẹp tại Đà Nẵng mà bạn có thể tham khảo:
+
+☕ **Nhớ Một Người**  
+- Địa chỉ: 06 Trường Thi 5, Hòa Thuận Tây, Hải Châu  
+- Rating: 4.9/5 ⭐  
+- Đặc điểm: Khô...
+
+---
+
+## Analysis
+
+### Tool Usage Comparison
+
+| Test | Single Mode Tools | ReAct Mode Tools | ReAct Steps |
+|------|-------------------|------------------|-------------|
+| 1 | retrieve_context_text | retrieve_context_text | 3 |
+
+
+### Key Observations
+
+1. **Multi-tool queries**: ReAct mode can chain multiple tools for complex queries
+2. **Single-tool queries**: Both modes perform similarly for simple queries
+3. **Reasoning steps**: ReAct mode shows explicit reasoning before each tool call
+

tests/test_react_comparison.py

@@ -0,0 +1,346 @@
+"""
+LocalMate Agent Test Script - Single vs ReAct Mode Comparison
+
+Tests 10 queries in both modes:
+- Single mode: configurable delay between queries
+- ReAct mode: configurable delay between queries  
+- Configurable delay between modes
+
+Generates detailed report with all step inputs/outputs.
+"""
+
+import asyncio
+import json
+import time
+from datetime import datetime
+import httpx
+
+# =============================================================================
+# CONFIGURATION - Adjust these values as needed
+# =============================================================================
+
+# API Settings
+API_BASE = "http://localhost:8000/api/v1"
+USER_ID = "test_comparison"
+
+# Delay Settings (in seconds)
+SINGLE_MODE_DELAY = 10       # Delay between queries in single mode
+REACT_MODE_DELAY = 60       # Delay between queries in ReAct mode
+MODE_SWITCH_DELAY = 60      # Delay between switching modes
+REQUEST_TIMEOUT = 120       # Timeout for each API request
+
+# =============================================================================
+
+# Test Cases - 10 queries covering different scenarios
+TEST_CASES = [
+    {
+        "id": 1,
+        "query": "Quán cafe view đẹp",
+        "description": "Simple text search - no location",
+        "expected_tools": ["retrieve_context_text"],
+    },
+    # {
+    #     "id": 2,
+    #     "query": "Nhà hàng gần bãi biển Mỹ Khê",
+    #     "description": "Location-based search",
+    #     "expected_tools": ["find_nearby_places"],
+    # },
+    # {
+    #     "id": 3,
+    #     "query": "Quán cafe có không gian xanh mát gần Cầu Rồng",
+    #     "description": "Complex: location + feature (should use multiple tools in ReAct)",
+    #     "expected_tools": ["find_nearby_places", "retrieve_context_text"],
+    # },
+    # {
+    #     "id": 4,
+    #     "query": "Phở ngon giá rẻ",
+    #     "description": "Food-specific text search",
+    #     "expected_tools": ["retrieve_context_text"],
+    # },
+    # {
+    #     "id": 5,
+    #     "query": "Địa điểm checkin đẹp gần Bà Nà",
+    #     "description": "Location + activity type",
+    #     "expected_tools": ["find_nearby_places"],
+    # },
+    # {
+    #     "id": 6,
+    #     "query": "Quán ăn hải sản có view sông gần trung tâm",
+    #     "description": "Complex: location + category + feature",
+    #     "expected_tools": ["find_nearby_places", "retrieve_context_text"],
+    # },
+    # {
+    #     "id": 7,
+    #     "query": "Khách sạn 5 sao gần biển",
+    #     "description": "Hotel + location search",
+    #     "expected_tools": ["find_nearby_places"],
+    # },
+    # {
+    #     "id": 8,
+    #     "query": "Quán bar có view đẹp về đêm",
+    #     "description": "Nightlife text search",
+    #     "expected_tools": ["retrieve_context_text"],
+    # },
+    # {
+    #     "id": 9,
+    #     "query": "Cafe rooftop gần Sơn Trà có coffee ngon",
+    #     "description": "Complex: location + feature + quality",
+    #     "expected_tools": ["find_nearby_places", "retrieve_context_text"],
+    # },
+    # {
+    #     "id": 10,
+    #     "query": "Nhà hàng Việt Nam authentic gần Rex Hotel",
+    #     "description": "Specific location + category + style",
+    #     "expected_tools": ["find_nearby_places", "retrieve_context_text"],
+    # },
+]
+
+
+async def run_test(client: httpx.AsyncClient, test_case: dict, react_mode: bool) -> dict:
+    """Run a single test case and return results."""
+    start_time = time.time()
+    
+    try:
+        response = await client.post(
+            f"{API_BASE}/chat",
+            json={
+                "message": test_case["query"],
+                "user_id": USER_ID,
+                "provider": "MegaLLM",
+                "react_mode": react_mode,
+                "max_steps": 5,
+            },
+            timeout=float(REQUEST_TIMEOUT),
+        )
+        
+        duration = (time.time() - start_time) * 1000
+        
+        if response.status_code == 200:
+            data = response.json()
+            return {
+                "success": True,
+                "test_id": test_case["id"],
+                "query": test_case["query"],
+                "description": test_case["description"],
+                "react_mode": react_mode,
+                "response": data.get("response", "")[:300],
+                "workflow": data.get("workflow", {}),
+                "tools_used": data.get("tools_used", []),
+                "api_duration_ms": data.get("duration_ms", 0),
+                "total_duration_ms": duration,
+            }
+        else:
+            return {
+                "success": False,
+                "test_id": test_case["id"],
+                "query": test_case["query"],
+                "react_mode": react_mode,
+                "error": f"HTTP {response.status_code}: {response.text[:200]}",
+                "total_duration_ms": duration,
+            }
+    
+    except Exception as e:
+        return {
+            "success": False,
+            "test_id": test_case["id"],
+            "query": test_case["query"],
+            "react_mode": react_mode,
+            "error": str(e),
+            "total_duration_ms": (time.time() - start_time) * 1000,
+        }
+
+
+def format_workflow_steps(workflow: dict) -> str:
+    """Format workflow steps for report."""
+    steps = workflow.get("steps", [])
+    if not steps:
+        return "No steps recorded"
+    
+    lines = []
+    for step in steps:
+        tool = step.get("tool", "N/A")
+        purpose = step.get("purpose", "")
+        results = step.get("results", 0)
+        lines.append(f"  - {step.get('step', 'Unknown')}")
+        lines.append(f"    Tool: `{tool}` | Results: {results}")
+    
+    return "\n".join(lines)
+
+
+def generate_report(single_results: list, react_results: list) -> str:
+    """Generate detailed markdown report."""
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    
+    report = f"""# LocalMate Agent Test Report
+
+**Generated:** {timestamp}
+
+## Summary
+
+| Metric | Single Mode | ReAct Mode |
+|--------|-------------|------------|
+| Total Tests | {len(single_results)} | {len(react_results)} |
+| Success | {sum(1 for r in single_results if r.get('success'))} | {sum(1 for r in react_results if r.get('success'))} |
+| Avg Duration | {sum(r.get('api_duration_ms', 0) for r in single_results if r.get('success')) / max(1, sum(1 for r in single_results if r.get('success'))):.0f}ms | {sum(r.get('api_duration_ms', 0) for r in react_results if r.get('success')) / max(1, sum(1 for r in react_results if r.get('success'))):.0f}ms |
+
+---
+
+## Detailed Results
+
+"""
+    
+    for i, (single, react) in enumerate(zip(single_results, react_results)):
+        test_id = single.get("test_id", i + 1)
+        query = single.get("query", "N/A")
+        description = single.get("description", "")
+        
+        report += f"""### Test Case {test_id}: {description}
+
+**Query:** `{query}`
+
+#### Single Mode
+
+"""
+        if single.get("success"):
+            report += f"""- **Status:** ✅ Success
+- **Duration:** {single.get('api_duration_ms', 0):.0f}ms
+- **Tools Used:** {', '.join(single.get('tools_used', [])) or 'None'}
+
+**Workflow:**
+{format_workflow_steps(single.get('workflow', {}))}
+
+**Response Preview:**
+> {single.get('response', 'N/A')[:200]}...
+
+"""
+        else:
+            report += f"""- **Status:** ❌ Failed
+- **Error:** {single.get('error', 'Unknown')}
+
+"""
+        
+        report += """#### ReAct Mode
+
+"""
+        if react.get("success"):
+            workflow = react.get("workflow", {})
+            report += f"""- **Status:** ✅ Success
+- **Duration:** {react.get('api_duration_ms', 0):.0f}ms
+- **Tools Used:** {', '.join(react.get('tools_used', [])) or 'None'}
+- **Steps:** {len(workflow.get('steps', []))}
+- **Intent Detected:** {workflow.get('intent_detected', 'N/A')}
+
+**Workflow Steps:**
+{format_workflow_steps(workflow)}
+
+**Response Preview:**
+> {react.get('response', 'N/A')[:200]}...
+
+"""
+        else:
+            report += f"""- **Status:** ❌ Failed
+- **Error:** {react.get('error', 'Unknown')}
+
+"""
+        
+        report += "---\n\n"
+    
+    # Comparison analysis
+    report += """## Analysis
+
+### Tool Usage Comparison
+
+| Test | Single Mode Tools | ReAct Mode Tools | ReAct Steps |
+|------|-------------------|------------------|-------------|
+"""
+    
+    for single, react in zip(single_results, react_results):
+        test_id = single.get("test_id", "?")
+        single_tools = ", ".join(single.get("tools_used", [])) if single.get("success") else "❌"
+        react_tools = ", ".join(react.get("tools_used", [])) if react.get("success") else "❌"
+        react_steps = len(react.get("workflow", {}).get("steps", [])) if react.get("success") else 0
+        report += f"| {test_id} | {single_tools} | {react_tools} | {react_steps} |\n"
+    
+    report += """
+
+### Key Observations
+
+1. **Multi-tool queries**: ReAct mode can chain multiple tools for complex queries
+2. **Single-tool queries**: Both modes perform similarly for simple queries
+3. **Reasoning steps**: ReAct mode shows explicit reasoning before each tool call
+
+"""
+    
+    return report
+
+
+async def main():
+    """Main test runner."""
+    print("=" * 60)
+    print("LocalMate Agent Mode Comparison Test")
+    print("=" * 60)
+    print()
+    
+    single_results = []
+    react_results = []
+    
+    async with httpx.AsyncClient() as client:
+        # Test Single Mode
+        print(f"📌 Running Single Mode Tests ({SINGLE_MODE_DELAY}s delay)...")
+        print("-" * 40)
+        
+        for test in TEST_CASES:
+            print(f"  Test {test['id']}: {test['query'][:40]}...")
+            result = await run_test(client, test, react_mode=False)
+            single_results.append(result)
+            
+            status = "✅" if result.get("success") else "❌"
+            tools = ", ".join(result.get("tools_used", [])) or "None"
+            print(f"    {status} Tools: {tools} | {result.get('api_duration_ms', 0):.0f}ms")
+            
+            if test["id"] < len(TEST_CASES):
+                await asyncio.sleep(SINGLE_MODE_DELAY)
+        
+        print()
+        print(f"⏸️  Waiting {MODE_SWITCH_DELAY}s before ReAct mode...")
+        await asyncio.sleep(MODE_SWITCH_DELAY)
+        
+        # Test ReAct Mode
+        print()
+        print(f"🧠 Running ReAct Mode Tests ({REACT_MODE_DELAY}s delay)...")
+        print("-" * 40)
+        
+        for test in TEST_CASES:
+            print(f"  Test {test['id']}: {test['query'][:40]}...")
+            result = await run_test(client, test, react_mode=True)
+            react_results.append(result)
+            
+            status = "✅" if result.get("success") else "❌"
+            tools = ", ".join(result.get("tools_used", [])) or "None"
+            steps = len(result.get("workflow", {}).get("steps", []))
+            print(f"    {status} Tools: {tools} | Steps: {steps} | {result.get('api_duration_ms', 0):.0f}ms")
+            
+            if test["id"] < len(TEST_CASES):
+                await asyncio.sleep(REACT_MODE_DELAY)
+    
+    # Generate report
+    print()
+    print("📝 Generating report...")
+    report = generate_report(single_results, react_results)
+    
+    # Use absolute path based on script location
+    import os
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    report_path = os.path.join(script_dir, "react_comparison_report.md")
+    with open(report_path, "w", encoding="utf-8") as f:
+        f.write(report)
+    
+    print(f"✅ Report saved to: {report_path}")
+    print()
+    print("=" * 60)
+    print("Test Complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())