Deploy Worker from GitHub Actions

Dockerfile

@@ -0,0 +1,46 @@
+# Same runtime as API; runs health endpoint + Celery worker (see worker_health.py)
+FROM python:3.11-slim-bookworm
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_ROOT_USER_ACTION=ignore \
+    NO_ALBUMENTATIONS_UPDATE=1 \
+    OMP_NUM_THREADS=1 \
+    MKL_NUM_THREADS=1 \
+    OPENBLAS_NUM_THREADS=1
+
+WORKDIR /app
+ENV PYTHONPATH=/app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    pkg-config \
+    cmake \
+    libcairo2 \
+    libcairo2-dev \
+    libpango-1.0-0 \
+    libpango1.0-dev \
+    libpangocairo-1.0-0 \
+    libgdk-pixbuf-2.0-0 \
+    libffi-dev \
+    python3-dev \
+    texlive-latex-base \
+    texlive-fonts-recommended \
+    texlive-latex-extra \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --upgrade pip setuptools wheel \
+    && pip install -r requirements.txt
+
+COPY . .
+
+RUN python scripts/prewarm_models.py
+
+ENV PORT=7860
+EXPOSE 7860
+
+ENTRYPOINT []
+CMD ["sh", "-c", "exec python3 -u worker_health.py"]

README.md

@@ -0,0 +1,11 @@
+---
+title: Math Solver Worker
+emoji: 👷
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+---
+
+# Math Solver Worker
+This space hosts the Celery background worker for video rendering.

agents/geometry_agent.py

@@ -0,0 +1,120 @@
+import os
+import json
+import logging
+from openai import AsyncOpenAI
+from typing import Dict, Any
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+from app.url_utils import openai_compatible_api_key, sanitize_env
+from app.llm_client import get_llm_client
+
+
+class GeometryAgent:
+    def __init__(self):
+        self.llm = get_llm_client()
+
+    async def generate_dsl(self, semantic_data: Dict[str, Any], previous_dsl: str = None) -> str:
+        logger.info("==[GeometryAgent] Generating DSL from semantic data==")
+        if previous_dsl:
+            logger.info(f"[GeometryAgent] Using previous DSL context (len={len(previous_dsl)})")
+
+        system_prompt = """
+You are a Geometry DSL Generator. Convert semantic geometry data into a precise Geometry DSL program.
+
+=== MULTI-TURN CONTEXT ===
+If a PREVIOUS DSL is provided, your job is to UPDATE or EXTEND it.
+1. DO NOT remove existing points unless the user explicitly asks to "redefine" or "move" them.
+2. Ensure new segments/points connect correctly to existing ones.
+3. Your output should be the ENTIRE updated DSL, not just the changes.
+
+=== DSL COMMANDS ===
+POINT(A)                    — declare a point
+POINT(A, x, y, z)           — declare a point with explicit coordinates
+LENGTH(AB, 5)               — distance between A and B is 5 (2D/3D)
+ANGLE(A, 90)                — interior angle at vertex A is 90° (2D/3D)
+PARALLEL(AB, CD)            — segment AB is parallel to CD (2D/3D)
+PERPENDICULAR(AB, CD)       — segment AB is perpendicular to CD (2D/3D)
+MIDPOINT(M, AB)             — M is the midpoint of segment AB
+SECTION(E, A, C, k)         — E satisfies vector AE = k * vector AC (k is decimal)
+LINE(A, B)                  — infinite line passing through A and B
+RAY(A, B)                   — ray starting at A and passing through B
+CIRCLE(O, 5)                — circle with center O and radius 5 (2D)
+SPHERE(O, 5)                — sphere with center O and radius 5 (3D)
+SEGMENT(M, N)               — auxiliary segment MN to be drawn
+POLYGON_ORDER(A, B, C, D)   — the order in which vertices form the polygon boundary
+TRIANGLE(ABC)               — equilateral/arbitrary triangle
+PYRAMID(S_ABCD)             — pyramid with apex S and base ABCD
+PRISM(ABC_DEF)              — triangular prism
+
+=== RULES ===
+1. 3D Coordinates: Use POINT(A, x, y, z) if specific coordinates are given in the problem.
+2. Space Geometry: For pyramids/prisms, use the specialized commands.
+3. Primary Vertices: Always declare the main vertices of the shape (e.g., A, B, C, D) using POINT(X).
+4. POLYGON_ORDER: Always emit POLYGON_ORDER(...) for the main shape using ONLY these primary vertices.
+5. All Points: EVERY point mentioned (A, B, C, H, M, etc.) MUST be declared with POINT(Name) first.
+6. Altitudes/Perpendiculars: For an altitude AH to BC, use POINT(H) + PERPENDICULAR(AH, BC).
+7. Format: Output ONLY DSL lines — NO explanation, NO markdown, NO code blocks.
+
+=== SHAPE EXAMPLES ===
+
+--- Case: Square Pyramid S.ABCD with side 10, height 15 ---
+PYRAMID(S_ABCD)
+POINT(A, 0, 0, 0)
+POINT(B, 10, 0, 0)
+POINT(C, 10, 10, 0)
+POINT(D, 0, 10, 0)
+POINT(S)
+POINT(O)
+SECTION(O, A, C, 0.5)
+LENGTH(SO, 15)
+PERPENDICULAR(SO, AC)
+PERPENDICULAR(SO, AB)
+POLYGON_ORDER(A, B, C, D)
+
+--- Case: Right Triangle ABC at A, AB=3, AC=4, altitude AH ---
+POLYGON_ORDER(A, B, C)
+POINT(A)
+POINT(B)
+POINT(C)
+POINT(H)
+LENGTH(AB, 3)
+LENGTH(AC, 4)
+ANGLE(A, 90)
+PERPENDICULAR(AH, BC)
+SEGMENT(A, H)
+
+--- Case: Rectangle ABCD with AB=5, AD=10 ---
+POLYGON_ORDER(A, B, C, D)
+POINT(A)
+POINT(B)
+POINT(C)
+POINT(D)
+LENGTH(AB, 5)
+LENGTH(AD, 10)
+PERPENDICULAR(AB, AD)
+PARALLEL(AB, CD)
+PARALLEL(AD, BC)
+
+[Circle with center O radius 7]
+POINT(O)
+CIRCLE(O, 7)
+"""
+
+        user_content = f"Semantic Data: {json.dumps(semantic_data, ensure_ascii=False)}"
+        if previous_dsl:
+            user_content = f"PREVIOUS DSL:\n{previous_dsl}\n\nUPDATE WITH NEW DATA: {json.dumps(semantic_data, ensure_ascii=False)}"
+
+        logger.debug("[GeometryAgent] Calling LLM (Multi-Layer)...")
+        content = await self.llm.chat_completions_create(
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_content}
+            ]
+        )
+        dsl = content.strip() if content else ""
+        logger.info(f"[GeometryAgent] DSL generated ({len(dsl.splitlines())} lines).")
+        logger.debug(f"[GeometryAgent] DSL output:\n{dsl}")
+        return dsl

agents/knowledge_agent.py

@@ -0,0 +1,135 @@
+import logging
+from typing import Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Shape rule registry ────────────────────────────────────────────────────
+# Each entry: keyword list → augmentation function
+# Augmentation receives (values: dict, text: str) and returns updated values dict.
+
+class KnowledgeAgent:
+    """Knowledge Agent: Stores geometric theorems and common patterns to augment Parser output."""
+
+    def augment_semantic_data(self, semantic_data: Dict[str, Any]) -> Dict[str, Any]:
+        logger.info("==[KnowledgeAgent] Augmenting semantic data==")
+        text = str(semantic_data.get("input_text", "")).lower()
+        logger.debug(f"[KnowledgeAgent] Input text for matching: '{text[:200]}'")
+
+        shape_type = self._detect_shape(text, semantic_data.get("type", ""))
+        if shape_type:
+            semantic_data["type"] = shape_type
+            values = semantic_data.get("values", {})
+            values = self._augment_values(shape_type, values, text)
+            semantic_data["values"] = values
+        else:
+            logger.info("[KnowledgeAgent] No special rule matched. Returning data unchanged.")
+
+        logger.debug(f"[KnowledgeAgent] Output semantic data: {semantic_data}")
+        return semantic_data
+
+    # ─── Shape detection ────────────────────────────────────────────────────
+    def _detect_shape(self, text: str, llm_type: str) -> str | None:
+        """Detect shape from text keywords. LLM type provides a hint."""
+        checks = [
+            (["hình vuông", "square"],                      "square"),
+            (["hình chữ nhật", "rectangle"],                "rectangle"),
+            (["hình thoi", "rhombus"],                      "rhombus"),
+            (["hình bình hành", "parallelogram"],            "parallelogram"),
+            (["hình thang vuông"],                           "right_trapezoid"),
+            (["hình thang", "trapezoid", "trapezium"],       "trapezoid"),
+            (["tam giác vuông", "right triangle"],           "right_triangle"),
+            (["tam giác đều", "equilateral triangle", "equilateral"], "equilateral_triangle"),
+            (["tam giác cân", "isosceles"],                  "isosceles_triangle"),
+            (["tam giác", "triangle"],                       "triangle"),
+            (["đường tròn", "circle"],                       "circle"),
+        ]
+        for keywords, shape in checks:
+            if any(kw in text for kw in keywords):
+                logger.info(f"[KnowledgeAgent] Rule MATCH: '{shape}' detected (keyword match).")
+                return shape
+
+        # Fallback: trust LLM-detected type if it's a known type
+        known = {
+            "rectangle", "square", "rhombus", "parallelogram",
+            "trapezoid", "right_trapezoid", "triangle", "right_triangle",
+            "equilateral_triangle", "isosceles_triangle", "circle",
+        }
+        if llm_type in known:
+            logger.info(f"[KnowledgeAgent] Using LLM-detected type '{llm_type}'.")
+            return llm_type
+
+        return None
+
+    # ─── Value augmentation ──────────────────────────────────────────────────
+    def _augment_values(self, shape: str, values: dict, text: str) -> dict:
+        ab = values.get("AB")
+        ad = values.get("AD")
+        bc = values.get("BC")
+        cd = values.get("CD")
+
+        if shape == "rectangle":
+            if ab and ad:
+                values.setdefault("CD", ab)
+                values.setdefault("BC", ad)
+                values.setdefault("angle_A", 90)
+                logger.info(f"[KnowledgeAgent] Rectangle: AB=CD={ab}, AD=BC={ad}, angle_A=90°")
+            else:
+                values.setdefault("angle_A", 90)
+
+        elif shape == "square":
+            side = ab or ad or bc or cd or values.get("side")
+            if side:
+                values.update({"AB": side, "AD": side, "angle_A": 90})
+                logger.info(f"[KnowledgeAgent] Square: side={side}, angle_A=90°")
+            else:
+                values.setdefault("angle_A", 90)
+
+        elif shape == "rhombus":
+            side = ab or values.get("side")
+            if side:
+                values.update({"AB": side, "BC": side, "CD": side, "DA": side})
+                logger.info(f"[KnowledgeAgent] Rhombus: all sides={side}")
+
+        elif shape == "parallelogram":
+            if ab:
+                values.setdefault("CD", ab)
+            if ad:
+                values.setdefault("BC", ad)
+            logger.info(f"[KnowledgeAgent] Parallelogram: AB||CD, AD||BC")
+
+        elif shape == "trapezoid":
+            logger.info("[KnowledgeAgent] Trapezoid: AB||CD (bottom||top)")
+
+        elif shape == "right_trapezoid":
+            logger.info("[KnowledgeAgent] Right trapezoid: AB||CD, AD⊥AB")
+            values.setdefault("angle_A", 90)
+
+        elif shape == "equilateral_triangle":
+            side = ab or values.get("side")
+            if side:
+                values.update({"AB": side, "BC": side, "CA": side, "angle_A": 60})
+                logger.info(f"[KnowledgeAgent] Equilateral triangle: all sides={side}, angle_A=60°")
+
+        elif shape == "right_triangle":
+            # Try to infer which vertex is the right angle
+            rt_vertex = _detect_right_angle_vertex(text)
+            values.setdefault(f"angle_{rt_vertex}", 90)
+            logger.info(f"[KnowledgeAgent] Right triangle: angle_{rt_vertex}=90°")
+
+        elif shape == "isosceles_triangle":
+            logger.info("[KnowledgeAgent] Isosceles triangle: AB=AC (default, LLM may override)")
+
+        elif shape == "circle":
+            logger.info("[KnowledgeAgent] Circle detected — no side augmentation needed.")
+
+        return values
+
+
+def _detect_right_angle_vertex(text: str) -> str:
+    """Heuristic: detect which vertex is right angle from text."""
+    for vertex in ["A", "B", "C", "D"]:
+        patterns = [f"vuông tại {vertex}", f"góc {vertex} vuông", f"right angle at {vertex}"]
+        if any(p.lower() in text for p in patterns):
+            return vertex
+    return "A"  # default

agents/ocr_agent.py

@@ -0,0 +1,185 @@
+import os
+import logging
+import asyncio
+from typing import List, Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+class ImprovedOCRAgent:
+    """
+    Advanced OCR Agent using a hybrid pipeline:
+    1. YOLO for layout analysis (text vs formula).
+    2. PaddleOCR for Vietnamese text extraction.
+    3. Pix2Tex for LaTeX formula extraction.
+    4. MegaLLM for semantic correction and formatting.
+    """
+
+    def __init__(self):
+        logger.info("[ImprovedOCRAgent] Initializing engines and client...")
+
+        from app.llm_client import get_llm_client
+        self.llm = get_llm_client()
+        logger.info("[ImprovedOCRAgent] Multi-Layer LLM Client initialized.")
+
+        try:
+            from agents.torch_ultralytics_compat import allow_ultralytics_weights
+            from ultralytics import YOLO
+
+            allow_ultralytics_weights()
+            logger.info("[ImprovedOCRAgent] Loading YOLO...")
+            self.layout_model = YOLO("yolov8n.pt")
+            logger.info("[ImprovedOCRAgent] YOLO initialized.")
+        except Exception as e:
+            logger.error("[ImprovedOCRAgent] YOLO init failed: %s", e)
+            self.layout_model = None
+
+        try:
+            from paddleocr import PaddleOCR
+
+            logger.info("[ImprovedOCRAgent] Loading PaddleOCR...")
+            self.text_model = PaddleOCR(use_angle_cls=True, lang="vi")
+            logger.info("[ImprovedOCRAgent] PaddleOCR (vi) initialized.")
+        except Exception as e:
+            logger.error("[ImprovedOCRAgent] PaddleOCR init failed: %s", e)
+            self.text_model = None
+
+        try:
+            from pix2tex.cli import LatexOCR
+
+            logger.info("[ImprovedOCRAgent] Loading Pix2Tex...")
+            self.math_model = LatexOCR()
+            logger.info("[ImprovedOCRAgent] Pix2Tex initialized.")
+        except Exception as e:
+            logger.error("[ImprovedOCRAgent] Pix2Tex init failed: %s", e)
+            self.math_model = None
+
+    async def process_image(self, image_path: str) -> str:
+        logger.info("==[ImprovedOCRAgent] Processing: %s==", image_path)
+
+        if not os.path.exists(image_path):
+            return f"Error: File {image_path} not found."
+
+        raw_fragments: List[Dict[str, Any]] = []
+
+        if self.text_model:
+            logger.info("[ImprovedOCRAgent] Running PaddleOCR on %s...", image_path)
+            result = self.text_model.ocr(image_path)
+            logger.info("[ImprovedOCRAgent] PaddleOCR raw result: %s", result)
+
+            if not result:
+                logger.warning("[ImprovedOCRAgent] PaddleOCR returned no results.")
+                return ""
+
+            if isinstance(result[0], dict):
+                res_dict = result[0]
+                rec_texts = res_dict.get("rec_texts", [])
+                rec_scores = res_dict.get("rec_scores", [])
+                rec_polys = res_dict.get("rec_polys", [])
+
+                for i in range(len(rec_texts)):
+                    text = rec_texts[i]
+                    bbox = rec_polys[i]
+                    _ = rec_scores[i]
+
+                    y_top = int(min(p[1] for p in bbox)) if hasattr(bbox, "__iter__") else 0
+
+                    is_math_hint = any(
+                        c in text for c in ["\\", "^", "_", "{", "}", "=", "+", "-", "*", "/"]
+                    )
+                    if is_math_hint and self.math_model:
+                        pass
+
+                    raw_fragments.append({"y": y_top, "content": text, "type": "text"})
+            elif isinstance(result[0], list):
+                for line in result[0]:
+                    bbox = line[0]
+                    text = line[1][0]
+                    _ = line[1][1]
+
+                    y_top = bbox[0][1]
+                    raw_fragments.append({"y": y_top, "content": text, "type": "text"})
+
+        raw_fragments.sort(key=lambda x: x["y"])
+        combined_text = "\n".join([f["content"] for f in raw_fragments])
+
+        logger.info(
+            "[ImprovedOCRAgent] Raw OCR output assembled:\n---\n%s\n---", combined_text
+        )
+
+        if not combined_text.strip():
+            logger.warning("[ImprovedOCRAgent] No text detected to refine.")
+            return ""
+
+        try:
+            logger.info("[ImprovedOCRAgent] Sending to MegaLLM for refinement...")
+            refined_text = await asyncio.wait_for(
+                self.refine_with_llm(combined_text), timeout=30.0
+            )
+            return refined_text
+        except asyncio.TimeoutError:
+            logger.error("[ImprovedOCRAgent] MegaLLM refinement timed out.")
+            return combined_text
+        except Exception as e:
+            logger.error("[ImprovedOCRAgent] MegaLLM refinement failed: %s", e)
+            return combined_text
+
+    async def refine_with_llm(self, text: str) -> str:
+        if not text.strip():
+            return ""
+
+        prompt = f"""Bạn là một chuyên gia số hóa tài liệu toán học.
+Dưới đây là kết quả OCR thô từ một trang sách toán Tiếng Việt.
+Kết quả này có thể chứa lỗi chính tả, lỗi định dạng mã LaTeX, hoặc bị ngắt quãng không logic.
+
+Nhiệm vụ của bạn:
+1. Sửa lỗi chính tả tiếng Việt.
+2. Đảm bảo các công thức toán học được viết đúng định dạng LaTeX và nằm trong cặp dấu $...$.
+3. Giữ nguyên cấu trúc logic của bài toán.
+4. Trả về nội dung đã được làm sạch dưới dạng Markdown.
+
+Nội dung OCR thô:
+---
+{text}
+---
+
+Kết quả làm sạch:"""
+
+        try:
+            refined = await self.llm.chat_completions_create(
+                messages=[{"role": "user", "content": prompt}],
+                temperature=0.1,
+            )
+            logger.info("[ImprovedOCRAgent] LLM refinement complete.")
+            return refined
+        except Exception as e:
+            logger.error("[ImprovedOCRAgent] LLM refinement failed: %s", e)
+            return text
+
+    async def process_url(self, url: str) -> str:
+        import httpx
+
+        from app.url_utils import sanitize_url
+
+        url = sanitize_url(url)
+        if not url:
+            return "Error: Empty image URL after cleanup."
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.get(url)
+            if resp.status_code == 200:
+                temp_path = "temp_url_image.png"
+                with open(temp_path, "wb") as f:
+                    f.write(resp.content)
+                try:
+                    return await self.process_image(temp_path)
+                finally:
+                    if os.path.exists(temp_path):
+                        os.remove(temp_path)
+            return f"Error: Failed to fetch image from URL {url}"
+
+
+class OCRAgent(ImprovedOCRAgent):
+    """Alias for compatibility with existing code."""
+
+    pass

agents/orchestrator.py

@@ -0,0 +1,249 @@
+import json
+import logging
+from typing import Any, Dict
+
+from agents.geometry_agent import GeometryAgent
+from agents.knowledge_agent import KnowledgeAgent
+from agents.ocr_agent import OCRAgent
+from agents.parser_agent import ParserAgent
+from agents.renderer_agent import RendererAgent
+from agents.solver_agent import SolverAgent
+from app.logutil import log_step
+from solver.dsl_parser import DSLParser
+from solver.engine import GeometryEngine
+from worker.celery_app import BROKER_URL
+from worker.tasks import render_geometry_video
+
+logger = logging.getLogger(__name__)
+
+_CLIP = 2000
+
+
+def _clip(val: Any, n: int = _CLIP) -> str | None:
+    if val is None:
+        return None
+    if isinstance(val, str):
+        s = val
+    else:
+        s = json.dumps(val, ensure_ascii=False, default=str)
+    return s if len(s) <= n else s[:n] + "…"
+
+
+def _step_io(step: str, input_val: Any = None, output_val: Any = None) -> None:
+    """Debug: chỉ input/output (đã cắt), tránh dump dài dòng không cần thiết."""
+    log_step(step, input=_clip(input_val), output=_clip(output_val))
+
+
+class Orchestrator:
+    def __init__(self):
+        self.parser_agent = ParserAgent()
+        self.geometry_agent = GeometryAgent()
+        self.ocr_agent = OCRAgent()
+        self.knowledge_agent = KnowledgeAgent()
+        self.renderer_agent = RendererAgent()
+        self.solver_agent = SolverAgent()
+        self.solver_engine = GeometryEngine()
+        self.dsl_parser = DSLParser()
+
+    def _generate_step_description(self, semantic_json: Dict[str, Any], engine_result: Dict[str, Any]) -> str:
+        """Tạo mô tả từng bước vẽ dựa trên kết quả của engine."""
+        analysis = semantic_json.get("analysis", "")
+        if not analysis:
+            analysis = f"Giải bài toán về {semantic_json.get('type', 'hình học')}."
+
+        steps = ["\n\n**Các bước dựng hình:**"]
+        drawing_phases = engine_result.get("drawing_phases", [])
+        
+        for phase in drawing_phases:
+            label = phase.get("label", f"Giai đoạn {phase['phase']}")
+            points = ", ".join(phase.get("points", []))
+            segments = ", ".join([f"{s[0]}{s[1]}" for s in phase.get("segments", [])])
+            
+            step_text = f"- **{label}**:"
+            if points:
+                step_text += f" Xác định các điểm {points}."
+            if segments:
+                step_text += f" Vẽ các đoạn thẳng {segments}."
+            steps.append(step_text)
+
+        circles = engine_result.get("circles", [])
+        for c in circles:
+            steps.append(f"- **Đường tròn**: Vẽ đường tròn tâm {c['center']} bán kính {c['radius']}.")
+
+        return analysis + "\n".join(steps)
+
+    async def run(
+        self,
+        text: str,
+        image_url: str = None,
+        job_id: str = None,
+        session_id: str = None,
+        status_callback=None,
+        request_video: bool = False,
+        history: list = None,
+    ) -> Dict[str, Any]:
+        """
+        Run the full pipeline. Optional history allows context-aware solving.
+        """
+        _step_io(
+            "orchestrate_start",
+            input_val={
+                "job_id": job_id,
+                "text_len": len(text or ""),
+                "image_url": image_url,
+                "request_video": request_video,
+                "history_len": len(history or []),
+            },
+            output_val=None,
+        )
+
+        if status_callback:
+            await status_callback("processing")
+
+        # 1. Extract context from history (if any)
+        previous_context = None
+        if history:
+            # Look for the last assistant message with geometry data
+            for msg in reversed(history):
+                if msg.get("role") == "assistant" and msg.get("metadata", {}).get("geometry_dsl"):
+                    previous_context = {
+                        "geometry_dsl": msg["metadata"]["geometry_dsl"],
+                        "coordinates": msg["metadata"].get("coordinates", {}),
+                        "analysis": msg.get("content", ""),
+                    }
+                    break
+        
+        if previous_context:
+            _step_io("context_found", input_val=None, output_val={"dsl_len": len(previous_context["geometry_dsl"])})
+
+        # 2. Gather input text (OCR or direct)
+        input_text = text
+        if image_url:
+            input_text = await self.ocr_agent.process_url(image_url)
+            _step_io("step1_ocr", input_val=image_url, output_val=input_text)
+        else:
+            _step_io("step1_ocr", input_val="(no image)", output_val=text)
+
+        feedback = None
+        MAX_RETRIES = 2
+
+        for attempt in range(MAX_RETRIES + 1):
+            _step_io(
+                "attempt",
+                input_val=f"{attempt + 1}/{MAX_RETRIES + 1}",
+                output_val=None,
+            )
+            if status_callback:
+                await status_callback("solving")
+
+            # Parser with context
+            _step_io("step2_parse", input_val=f"{input_text[:50]}...", output_val=None)
+            semantic_json = await self.parser_agent.process(input_text, feedback=feedback, context=previous_context)
+            semantic_json["input_text"] = input_text
+            _step_io("step2_parse", input_val=None, output_val=semantic_json)
+
+            # Knowledge augmentation
+            _step_io("step3_knowledge", input_val=semantic_json, output_val=None)
+            semantic_json = self.knowledge_agent.augment_semantic_data(semantic_json)
+            _step_io("step3_knowledge", input_val=None, output_val=semantic_json)
+
+            # Geometry DSL with context (passing previous DSL to guide generation)
+            _step_io("step4_geometry_dsl", input_val=semantic_json, output_val=None)
+            dsl_code = await self.geometry_agent.generate_dsl(
+                semantic_json, 
+                previous_dsl=previous_context["geometry_dsl"] if previous_context else None
+            )
+            _step_io("step4_geometry_dsl", input_val=None, output_val=dsl_code)
+
+            _step_io("step5_dsl_parse", input_val=dsl_code, output_val=None)
+            points, constraints, is_3d = self.dsl_parser.parse(dsl_code)
+            _step_io(
+                "step5_dsl_parse",
+                input_val=None,
+                output_val={
+                    "points": len(points),
+                    "constraints": len(constraints),
+                    "is_3d": is_3d,
+                },
+            )
+
+            _step_io("step6_solve", input_val=f"{len(points)} pts / {len(constraints)} cons (is_3d={is_3d})", output_val=None)
+            import anyio
+            engine_result = await anyio.to_thread.run_sync(self.solver_engine.solve, points, constraints, is_3d)
+
+            if engine_result:
+                coordinates = engine_result.get("coordinates")
+                _step_io("step6_solve", input_val=None, output_val=coordinates)
+                break
+
+            feedback = "Geometry solver failed to find a valid solution for the given constraints. Parallelism or lengths might be inconsistent."
+            _step_io(
+                "step6_solve",
+                input_val=f"attempt {attempt + 1}",
+                output_val=feedback,
+            )
+            if attempt == MAX_RETRIES:
+                _step_io(
+                    "orchestrate_abort",
+                    input_val=None,
+                    output_val="solver_exhausted_retries",
+                )
+                return {
+                    "error": "Solver failed after multiple attempts.",
+                    "last_dsl": dsl_code,
+                }
+
+        status = "success"
+        if request_video:
+            try:
+                result_payload = {
+                    "geometry_dsl": dsl_code,
+                    "coordinates": coordinates,
+                    "polygon_order": engine_result.get("polygon_order", []),
+                    "drawing_phases": engine_result.get("drawing_phases", []),
+                    "circles": engine_result.get("circles", []),
+                    "lines": engine_result.get("lines", []),
+                    "rays": engine_result.get("rays", []),
+                    "semantic": semantic_json,
+                    "semantic_analysis": semantic_json.get("analysis") or semantic_json.get("input_text", ""),
+                    "session_id": session_id,
+                }
+                task = render_geometry_video.delay(job_id, result_payload)
+                status = "rendering_queued"
+                _step_io(
+                    "step7_video",
+                    input_val={"job_id": job_id, "broker": BROKER_URL.split("@")[-1] if "@" in BROKER_URL else BROKER_URL},
+                    output_val={"task_id": str(task.id), "status": status},
+                )
+            except Exception as e:
+                logger.exception("Celery queue failed for job %s", job_id)
+                _step_io("step7_video", input_val=job_id, output_val=str(e))
+                status = "success"
+        else:
+            _step_io("step7_video", input_val=request_video, output_val="skipped")
+
+        _step_io("orchestrate_done", input_val=job_id, output_val=status)
+
+        # 8. Solution calculation (New in v5.1)
+        solution = None
+        if engine_result:
+            _step_io("step8_solve_math", input_val=semantic_json.get("target_question"), output_val=None)
+            solution = await self.solver_agent.solve(semantic_json, engine_result)
+            _step_io("step8_solve_math", input_val=None, output_val=solution.get("answer"))
+
+        final_analysis = self._generate_step_description(semantic_json, engine_result)
+
+        return {
+            "status": status,
+            "job_id": job_id,
+            "geometry_dsl": dsl_code,
+            "coordinates": coordinates,
+            "polygon_order": engine_result.get("polygon_order", []),
+            "circles": engine_result.get("circles", []),
+            "lines": engine_result.get("lines", []),
+            "rays": engine_result.get("rays", []),
+            "drawing_phases": engine_result.get("drawing_phases", []),
+            "semantic": semantic_json,
+            "semantic_analysis": final_analysis,
+            "solution": solution,
+        }

agents/parser_agent.py

@@ -0,0 +1,106 @@
+import os
+import json
+import logging
+from openai import AsyncOpenAI
+from typing import Dict, Any
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+from app.url_utils import openai_compatible_api_key, sanitize_env
+
+
+from app.llm_client import get_llm_client
+
+
+class ParserAgent:
+    def __init__(self):
+        self.llm = get_llm_client()
+
+    async def process(self, text: str, feedback: str = None, context: Dict[str, Any] = None) -> Dict[str, Any]:
+        logger.info(f"==[ParserAgent] Processing input (len={len(text)})==")
+        if feedback:
+            logger.warning(f"[ParserAgent] Feedback from previous attempt: {feedback}")
+        if context:
+            logger.info(f"[ParserAgent] Using previous context (dsl_len={len(context.get('geometry_dsl', ''))})")
+
+        system_prompt = """
+        You are a Geometry Parser Agent. Extract geometric entities and constraints from Vietnamese/LaTeX math problem text.
+        
+        === CONTEXT AWARENESS ===
+        If previous context is provided, it means this is a follow-up request.
+        - Combine old entities with new ones.
+        - Update 'analysis' to reflect the entire problem state.
+        
+        Output ONLY a JSON object with this EXACT structure (no extra keys, no markdown):
+        {
+            "entities": ["Point A", "Point B", ...],
+            "type": "pyramid|prism|sphere|rectangle|triangle|circle|parallelogram|trapezoid|square|rhombus|general",
+            "values": {"AB": 5, "SO": 15, "radius": 3},
+            "target_question": "Câu hỏi cụ thể cần giải (ví dụ: 'Tính diện tích tam giác ABC'). NẾU KHÔNG CÓ CÂU HỎI THÌ ĐỂ null.",
+            "analysis": "Tóm tắt ngắn gọn toàn bộ bài toán sau khi đã cập nhật các yêu cầu mới bằng tiếng Việt."
+        }
+        Rules:
+        - "analysis" MUST be a meaningful and UP-TO-DATE summary of the problem in Vietnamese. 
+        - "target_question" must be concise.
+        - Include midpoints, auxiliary points in "entities" if mentioned.
+        - If feedback is provided, correct your previous output accordingly.
+        """
+
+        user_content = f"Text: {text}"
+        if context:
+            user_content = f"PREVIOUS ANALYSIS: {context.get('analysis')}\nNEW REQUEST: {text}"
+        
+        if feedback:
+            user_content += f"\nFeedback from previous attempt: {feedback}. Please correct the constraints."
+
+        logger.debug("[ParserAgent] Calling LLM (Multi-Layer)...")
+        raw = await self.llm.chat_completions_create(
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_content}
+            ],
+            response_format={"type": "json_object"}
+        )
+        
+        # Pre-process raw string: extract the JSON block if present
+        import re
+        clean_raw = raw.strip()
+        # Handle potential markdown code blocks
+        if clean_raw.startswith("```"):
+            import re
+            match = re.search(r"```(?:json)?\s*(.*?)\s*```", clean_raw, re.DOTALL)
+            if match:
+                clean_raw = match.group(1).strip()
+            
+        try:
+            result = json.loads(clean_raw)
+        except json.JSONDecodeError as e:
+            logger.error(f"[ParserAgent] JSON Parse Error: {e}. Attempting regex fallback...")
+            import re
+            json_match = re.search(r'(\{.*\})', clean_raw, re.DOTALL)
+            if json_match:
+                try:
+                    # Handle single quotes if present (common LLM failure)
+                    json_str = json_match.group(1)
+                    if "'" in json_str and '"' not in json_str:
+                         json_str = json_str.replace("'", '"')
+                    result = json.loads(json_str)
+                except:
+                    result = None
+            else:
+                result = None
+
+            if not result:
+                # Fallback for critical failure
+                result = {
+                    "entities": [],
+                    "type": "general",
+                    "values": {},
+                    "target_question": None,
+                    "analysis": text
+                }
+        logger.info(f"[ParserAgent] LLM response received.")
+        logger.debug(f"[ParserAgent] Parsed JSON: {json.dumps(result, ensure_ascii=False, indent=2)}")
+        return result

agents/renderer_agent.py

@@ -0,0 +1,249 @@
+import os
+import subprocess
+import glob
+import string
+from typing import Dict, Any, List
+
+
+class RendererAgent:
+    """
+    Renderer Agent — generates Manim scripts from geometry data.
+
+    Drawing happens in phases:
+      Phase 1: Main polygon (base shape with correct vertex order)
+      Phase 2: Auxiliary points and segments (midpoints, derived segments)
+      Phase 3: Labels for all points
+    """
+
+    def generate_manim_script(self, data: Dict[str, Any]) -> str:
+        coords: Dict[str, List[float]] = data.get("coordinates", {})
+        polygon_order: List[str] = data.get("polygon_order", [])
+        circles_meta: List[Dict] = data.get("circles", [])
+        lines_meta: List[List[str]] = data.get("lines", [])
+        rays_meta: List[List[str]] = data.get("rays", [])
+        drawing_phases: List[Dict] = data.get("drawing_phases", [])
+        semantic: Dict[str, Any] = data.get("semantic", {})
+        shape_type = semantic.get("type", "").lower()
+
+        # ── Detect 3D Context ────────────────────────────────────────────────
+        is_3d = False
+        for pos in coords.values():
+            if len(pos) >= 3 and abs(pos[2]) > 0.001:
+                is_3d = True
+                break
+        if shape_type in ["pyramid", "prism", "sphere"]:
+            is_3d = True
+
+        # ── Fallback: infer polygon_order from coords keys (alphabetical uppercase) ──
+        if not polygon_order:
+            base = sorted(
+                [pid for pid in coords if pid in string.ascii_uppercase],
+                key=lambda p: string.ascii_uppercase.index(p)
+            )
+            polygon_order = base
+
+        # Separate base points from derived (multi-char or lowercase)
+        base_ids = [pid for pid in polygon_order if pid in coords]
+        derived_ids = [pid for pid in coords if pid not in polygon_order]
+
+        scene_base = "ThreeDScene" if is_3d else "MovingCameraScene"
+        lines = [
+            "from manim import *",
+            "",
+            f"class GeometryScene({scene_base}):",
+            "    def construct(self):",
+        ]
+
+        if is_3d:
+            lines.append("        # 3D Setup")
+            lines.append("        self.set_camera_orientation(phi=75*DEGREES, theta=-45*DEGREES)")
+            lines.append("        axes = ThreeDAxes(axis_config={'stroke_width': 1})")
+            lines.append("        axes.set_opacity(0.3)")
+            lines.append("        self.add(axes)")
+            lines.append("        self.begin_ambient_camera_rotation(rate=0.1)")
+            lines.append("")
+
+        # ── Declare all dots and labels ───────────────────────────────────────
+        for pid, pos in coords.items():
+            x, y, z = 0, 0, 0
+            if len(pos) >= 1: x = round(pos[0], 4)
+            if len(pos) >= 2: y = round(pos[1], 4)
+            if len(pos) >= 3: z = round(pos[2], 4)
+            
+            dot_class = "Dot3D" if is_3d else "Dot"
+            lines.append(f"        p_{pid} = {dot_class}(point=[{x}, {y}, {z}], color=WHITE, radius=0.08)")
+            
+            if is_3d:
+                lines.append(
+                    f"        l_{pid} = Text('{pid}', font_size=20, color=WHITE)"
+                    f".move_to(p_{pid}.get_center() + [0.2, 0.2, 0.2])"
+                )
+                # Ensure labels follow camera in 3D (fixed orientation)
+                lines.append(f"        self.add_fixed_orientation_mobjects(l_{pid})")
+            else:
+                lines.append(
+                    f"        l_{pid} = Text('{pid}', font_size=22, color=WHITE)"
+                    f".next_to(p_{pid}, UR, buff=0.15)"
+                )
+
+        # ── 3D Shape Special: Pyramid/Prism Faces ────────────────────────────
+        if is_3d and shape_type == "pyramid" and len(base_ids) >= 3:
+            # Find apex (usually 'S')
+            apex_id = "S" if "S" in coords else derived_ids[0] if derived_ids else None
+            if apex_id:
+                # Draw base face
+                base_pts = ", ".join([f"p_{pid}.get_center()" for pid in base_ids])
+                lines.append(f"        base_face = Polygon({base_pts}, color=BLUE, fill_opacity=0.1)")
+                lines.append("        self.play(Create(base_face), run_time=1.0)")
+                
+                # Draw side faces
+                for i in range(len(base_ids)):
+                    p1 = base_ids[i]
+                    p2 = base_ids[(i+1)%len(base_ids)]
+                    face_pts = f"p_{apex_id}.get_center(), p_{p1}.get_center(), p_{p2}.get_center()"
+                    lines.append(f"        side_{i} = Polygon({face_pts}, color=BLUE, stroke_width=1, fill_opacity=0.05)")
+                    lines.append(f"        self.play(Create(side_{i}), run_time=0.5)")
+
+        # ── Circles ──────────────────────────────────────────────────────────
+        for i, c in enumerate(circles_meta):
+            center = c["center"]
+            r = c["radius"]
+            if center in coords:
+                cx, cy, cz = 0, 0, 0
+                pos = coords[center]
+                if len(pos) >= 1: cx = round(pos[0], 4)
+                if len(pos) >= 2: cy = round(pos[1], 4)
+                if len(pos) >= 3: cz = round(pos[2], 4)
+                lines.append(
+                    f"        circle_{i} = Circle(radius={r}, color=BLUE)"
+                    f".move_to([{cx}, {cy}, {cz}])"
+                )
+
+        # ── Infinite Lines & Rays ────────────────────────────────────────────
+        # (Standard Line works for 3D coordinates in Manim)
+        for i, (p1, p2) in enumerate(lines_meta):
+            if p1 in coords and p2 in coords:
+                lines.append(
+                    f"        line_ext_{i} = Line(p_{p1}.get_center(), p_{p2}.get_center(), color=GRAY_D, stroke_width=2)"
+                    f".scale(20)"
+                )
+
+        for i, (p1, p2) in enumerate(rays_meta):
+            if p1 in coords and p2 in coords:
+                lines.append(
+                    f"        ray_{i} = Line(p_{p1}.get_center(), p_{p1}.get_center() + 15 * (p_{p2}.get_center() - p_{p1}.get_center()),"
+                    f" color=GRAY_C, stroke_width=2)"
+                )
+
+        # ── Camera auto-fit group (Only for 2D) ──────────────────────────────
+        if not is_3d:
+            all_dot_names = [f"p_{pid}" for pid in coords]
+            all_names_str = ", ".join(all_dot_names)
+            lines.append(f"        _all = VGroup({all_names_str})")
+            lines.append("        self.camera.frame.set_width(max(_all.width * 2.0, 8))")
+            lines.append("        self.camera.frame.move_to(_all)")
+        lines.append("")
+
+        # ── Phase 1: Base polygon ─────────────────────────────────────────────
+        if len(base_ids) >= 3:
+            pts_str = ", ".join([f"p_{pid}.get_center()" for pid in base_ids])
+            lines.append(f"        poly = Polygon({pts_str}, color=BLUE, fill_color=BLUE, fill_opacity=0.15)")
+            lines.append("        self.play(Create(poly), run_time=1.5)")
+        elif len(base_ids) == 2:
+            p1, p2 = base_ids
+            lines.append(f"        base_line = Line(p_{p1}.get_center(), p_{p2}.get_center(), color=BLUE)")
+            lines.append("        self.play(Create(base_line), run_time=1.0)")
+
+        # Draw base points
+        if base_ids:
+            base_dots_str = ", ".join([f"p_{pid}" for pid in base_ids])
+            lines.append(f"        self.play(FadeIn(VGroup({base_dots_str})), run_time=0.5)")
+        lines.append("        self.wait(0.5)")
+
+        # ── Phase 2: Auxiliary points and segments ────────────────────────────
+        if derived_ids:
+            derived_dots_str = ", ".join([f"p_{pid}" for pid in derived_ids])
+            lines.append(f"        self.play(FadeIn(VGroup({derived_dots_str})), run_time=0.8)")
+
+        # Segments from drawing_phases
+        segment_lines = []
+        for phase in drawing_phases:
+            if phase.get("phase") == 2:
+                for seg in phase.get("segments", []):
+                    if len(seg) == 2 and seg[0] in coords and seg[1] in coords:
+                        p1, p2 = seg[0], seg[1]
+                        seg_var = f"seg_{p1}_{p2}"
+                        lines.append(
+                            f"        {seg_var} = Line(p_{p1}.get_center(), p_{p2}.get_center(),"
+                            f" color=YELLOW)"
+                        )
+                        segment_lines.append(seg_var)
+
+        if segment_lines:
+            segs_str = ", ".join([f"Create({sv})" for sv in segment_lines])
+            lines.append(f"        self.play({segs_str}, run_time=1.2)")
+
+        if derived_ids or segment_lines:
+            lines.append("        self.wait(0.5)")
+
+        # ── Phase 3: All labels ───────────────────────────────────────────────
+        all_labels_str = ", ".join([f"l_{pid}" for pid in coords])
+        lines.append(f"        self.play(FadeIn(VGroup({all_labels_str})), run_time=0.8)")
+
+        # ── Circles phase ─────────────────────────────────────────────────────
+        for i in range(len(circles_meta)):
+            lines.append(f"        self.play(Create(circle_{i}), run_time=1.5)")
+
+        # ── Lines & Rays phase ────────────────────────────────────────────────
+        if lines_meta or rays_meta:
+            lr_anims = []
+            for i in range(len(lines_meta)): lr_anims.append(f"Create(line_ext_{i})")
+            for i in range(len(rays_meta)): lr_anims.append(f"Create(ray_{i})")
+            lines.append(f"        self.play({', '.join(lr_anims)}, run_time=1.5)")
+
+        lines.append("        self.wait(2)")
+
+        return "\n".join(lines)
+
+    def run_manim(self, script_content: str, job_id: str) -> str:
+        import subprocess
+        import os
+        import glob
+
+        script_file = f"{job_id}.py"
+        with open(script_file, "w") as f:
+            f.write(script_content)
+
+        try:
+            if os.getenv("MOCK_VIDEO") == "true":
+                logger.info(f"MOCK_VIDEO is true. Skipping Manim for job {job_id}")
+                # Create a dummy file if needed, or just return a path that exists
+                dummy_path = f"videos/{job_id}.mp4"
+                os.makedirs("videos", exist_ok=True)
+                with open(dummy_path, "wb") as f:
+                    f.write(b"dummy video content")
+                return dummy_path
+
+            print(f"Running Manim for job {job_id}...")
+            result = subprocess.run(
+                ["manim", "-ql", "--media_dir", ".", "-o", f"{job_id}.mp4", script_file, "GeometryScene"],
+                capture_output=True,
+                text=True,
+            )
+            print(f"Manim STDOUT: {result.stdout}")
+            print(f"Manim STDERR: {result.stderr}")
+
+            for pattern in [f"**/videos/**/{job_id}.mp4", f"**/{job_id}*.mp4"]:
+                found = glob.glob(pattern, recursive=True)
+                if found:
+                    print(f"Manim Success: Found {found[0]}")
+                    return found[0]
+
+            print(f"Manim file not found for job {job_id}")
+            return ""
+        except Exception as e:
+            print(f"Manim Execution Error: {e}")
+            return ""
+        finally:
+            if os.path.exists(script_file):
+                os.remove(script_file)

agents/solver_agent.py

@@ -0,0 +1,107 @@
+import json
+import logging
+import sympy as sp
+from typing import Dict, Any, List
+from app.llm_client import get_llm_client
+
+logger = logging.getLogger(__name__)
+
+class SolverAgent:
+    def __init__(self):
+        self.llm = get_llm_client()
+
+    async def solve(self, semantic_data: Dict[str, Any], engine_result: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Solves the geometric problem based on coordinates and the target question.
+        Returns a 'solution' dictionary with answer, steps, and symbolic_expression.
+        """
+        target_question = semantic_data.get("target_question")
+        if not target_question:
+            # If no question, just return an empty solution structure
+            return {
+                "answer": None,
+                "steps": [],
+                "symbolic_expression": None
+            }
+
+        logger.info(f"==[SolverAgent] Solving for: '{target_question}'==")
+
+        input_text = semantic_data.get("input_text", "")
+        coordinates = engine_result.get("coordinates", {})
+        
+        # We provide the coordinates and semantic context to the LLM to help it reason.
+        # The LLM is tasked with generating the solution structure directly.
+        
+        system_prompt = """
+        You are a Geometry Solver Agent. Your goal is to provide a step-by-step solution for a specific geometric question.
+        
+        === DATA PROVIDED ===
+        1. Target Question: The specific question to answer.
+        2. Geometry Data: Entities and values extracted from the problem.
+        3. Coordinates: Calculated coordinates for all points.
+        
+        === REQUIREMENTS ===
+        - Provide the solution in the SAME LANGUAGE as the user's input.
+        - Use SymPy concepts if appropriate.
+        - Steps should be clear, concise, and logical.
+        - The final answer should be numerically or symbolically accurate based on the coordinates and geometric properties.
+        - For geometric proofs (e.g., "Is AB perpendicular to AC?"), explain the reasoning based on the data.
+        
+        Output ONLY a JSON object with this structure:
+        {
+            "answer": "Chuỗi văn bản kết quả cuối cùng (kèm đơn vị nếu có)",
+            "steps": [
+                "Bước 1: ...",
+                "Bước 2: ...",
+                ...
+            ],
+            "symbolic_expression": "Biểu thức toán học rút gọn (LaTeX format optional)"
+        }
+        """
+
+        user_content = f"""
+        INPUT_TEXT: {input_text}
+        TARGET_QUESTION: {target_question}
+        SEMANTIC_DATA: {json.dumps(semantic_data, ensure_ascii=False)}
+        COORDINATES: {json.dumps(coordinates)}
+        """
+
+        logger.debug("[SolverAgent] Requesting solution from LLM...")
+        try:
+            raw = await self.llm.chat_completions_create(
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_content}
+                ],
+                response_format={"type": "json_object"}
+            )
+            
+            clean_raw = raw.strip()
+            # Handle potential markdown code blocks if the response_format wasn't strictly honored
+            if clean_raw.startswith("```"):
+                import re
+                match = re.search(r"```(?:json)?\s*(.*?)\s*```", clean_raw, re.DOTALL)
+                if match:
+                    clean_raw = match.group(1).strip()
+            
+            try:
+                solution = json.loads(clean_raw)
+            except json.JSONDecodeError:
+                # Last resort: try to find anything between { and }
+                import re
+                json_match = re.search(r'(\{.*\})', clean_raw, re.DOTALL)
+                if json_match:
+                    solution = json.loads(json_match.group(1))
+                else:
+                    raise
+            
+            logger.info("[SolverAgent] Solution generated successfully.")
+            return solution
+        except Exception as e:
+            logger.error(f"[SolverAgent] Error generating solution: {e}")
+            logger.debug(f"[SolverAgent] Raw LLM output was: \n{raw if 'raw' in locals() else 'N/A'}")
+            return {
+                "answer": "Không thể tính toán lời giải tại thời điểm này.",
+                "steps": ["Đã xảy ra lỗi trong quá trình xử lý lời giải."],
+                "symbolic_expression": None
+            }

agents/torch_ultralytics_compat.py

@@ -0,0 +1,33 @@
+"""PyTorch 2.6+ defaults weights_only=True; Ultralytics YOLO .pt checkpoints unpickle full nn graphs (trusted official weights)."""
+
+from __future__ import annotations
+
+import functools
+
+_torch_load_patched = False
+
+
+def allow_ultralytics_weights() -> None:
+    """
+    Official yolov8n.pt is a trusted checkpoint. PyTorch 2.6+ safe unpickling would require
+    allowlisting many torch.nn globals; loading with weights_only=False matches Ultralytics
+    upstream behavior for local .pt files.
+    """
+    global _torch_load_patched
+    if _torch_load_patched:
+        return
+    try:
+        import torch
+
+        _orig = torch.load
+
+        @functools.wraps(_orig)
+        def _load(*args, **kwargs):
+            if "weights_only" not in kwargs:
+                kwargs["weights_only"] = False
+            return _orig(*args, **kwargs)
+
+        torch.load = _load
+        _torch_load_patched = True
+    except Exception:
+        pass

app/dependencies.py

@@ -0,0 +1,62 @@
+from fastapi import HTTPException, Header
+
+from app.supabase_client import get_supabase, get_supabase_for_user_jwt
+
+
+async def get_current_user_id(authorization: str = Header(...)):
+    """
+    Authenticate user using Supabase JWT.
+    Expected Header: Authorization: Bearer <token>
+    """
+    import os
+    if os.getenv("ALLOW_TEST_BYPASS") == "true" and authorization.startswith("Test "):
+        return authorization.split(" ")[1]
+
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail="Authorization header missing or invalid. Use 'Bearer <token>'",
+        )
+
+    token = authorization.split(" ")[1]
+    supabase = get_supabase()
+
+    try:
+        user_response = supabase.auth.get_user(token)
+        if not user_response or not user_response.user:
+            raise HTTPException(status_code=401, detail="Invalid session or token.")
+
+        return user_response.user.id
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=f"Authentication failed: {str(e)}")
+
+
+async def get_authenticated_supabase(authorization: str = Header(...)):
+    """
+    Supabase client that carries the user's JWT (anon key + Authorization header).
+    Use for routes that should respect Row Level Security; pair with app logic as needed.
+    """
+    if not authorization or not authorization.startswith("Bearer "):
+        raise HTTPException(
+            status_code=401,
+            detail="Authorization header missing or invalid. Use 'Bearer <token>'",
+        )
+
+    token = authorization.split(" ")[1]
+    supabase = get_supabase()
+
+    try:
+        user_response = supabase.auth.get_user(token)
+        if not user_response or not user_response.user:
+            raise HTTPException(status_code=401, detail="Invalid session or token.")
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=f"Authentication failed: {str(e)}")
+
+    try:
+        return get_supabase_for_user_jwt(token)
+    except RuntimeError as e:
+        raise HTTPException(status_code=503, detail=str(e))

app/errors.py

@@ -0,0 +1,59 @@
+"""Map exceptions to short, user-visible messages (avoid leaking HTML bodies from 404 proxies)."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _looks_like_html(text: str) -> bool:
+    t = text.lstrip()[:500].lower()
+    return t.startswith("<!doctype") or t.startswith("<html") or "<html" in t[:200]
+
+
+def format_error_for_user(exc: BaseException) -> str:
+    """
+    Produce a safe message for chat/UI. Full detail stays in server logs via logger.exception.
+    """
+    # httpx: wrong URL often returns 404 HTML; don't show body
+    try:
+        import httpx
+
+        if isinstance(exc, httpx.HTTPStatusError):
+            req = exc.request
+            code = exc.response.status_code
+            url_hint = ""
+            try:
+                url_hint = str(req.url.host) if req and req.url else ""
+            except Exception:
+                pass
+            logger.warning(
+                "HTTPStatusError %s for %s (response not shown to user)",
+                code,
+                url_hint or "?",
+            )
+            return (
+                "Kiểm tra URL API, khóa bí mật và biến môi trường (OpenRouter/Supabase/Redis)."
+            )
+
+        if isinstance(exc, httpx.RequestError):
+            return "Không kết nối được tới dịch vụ ngoài (mạng hoặc URL sai)."
+    except ImportError:
+        pass
+
+    raw = str(exc).strip()
+    if not raw:
+        return "Đã xảy ra lỗi không xác định."
+
+    if _looks_like_html(raw):
+        logger.warning("Suppressed HTML error body from user-facing message")
+        return (
+            "Dịch vụ trả về trang lỗi (thường là URL API sai hoặc endpoint không tồn tại — HTTP 404). "
+            "Kiểm tra OPENROUTER_MODEL và khóa API trên server."
+        )
+
+    if len(raw) > 800:
+        return raw[:800] + "…"
+
+    return raw

app/llm_client.py

@@ -0,0 +1,104 @@
+import os
+import json
+import asyncio
+import logging
+from openai import AsyncOpenAI
+from typing import List, Dict, Any, Optional
+from app.url_utils import openai_compatible_api_key, sanitize_env
+
+logger = logging.getLogger(__name__)
+
+class MultiLayerLLMClient:
+    def __init__(self):
+        # 1. OpenRouter (Primary with Rotation)
+        self.openrouter_model = os.getenv("OPENROUTER_MODEL", "google/gemini-2.0-flash-001")
+        self.keys = []
+        for i in range(1, 6):
+            key = os.getenv(f"OPENROUTER_API_KEY_{i}")
+            if key:
+                self.keys.append(key)
+        
+        if not self.keys:
+            # Fallback to single key if exists (legacy)
+            single_key = os.getenv("OPENROUTER_API_KEY")
+            if single_key:
+                self.keys.append(single_key)
+
+        self.clients = [
+            AsyncOpenAI(
+                api_key=openai_compatible_api_key(k),
+                base_url="https://openrouter.ai/api/v1",
+                timeout=120.0,
+                default_headers={
+                    "HTTP-Referer": "https://mathsolver.ai",
+                    "X-Title": "MathSolver Backend",
+                }
+            ) for k in self.keys
+        ]
+        self.current_index = 0
+
+    async def chat_completions_create(
+        self, 
+        messages: List[Dict[str, str]], 
+        response_format: Optional[Dict[str, str]] = None,
+        **kwargs
+    ) -> str:
+        """
+        Rotates through OpenRouter API keys on every attempt (success or failure).
+        Tries up to 2 retries (total 3 attempts), with 0s delay.
+        """
+        MAX_RETRIES = 2
+        RETRY_DELAY = 0 # seconds
+        
+        if not self.clients:
+            logger.error("[LLM] No OpenRouter API keys found.")
+            raise ValueError("No API keys configured.")
+
+        for attempt in range(1, MAX_RETRIES + 2): # Up to 3 attempts total
+            client = self.clients[self.current_index]
+            key_id = self.current_index + 1
+            
+            try:
+                logger.info(f"[LLM] Attempt {attempt}/{MAX_RETRIES + 1} using Key #{key_id} ({self.openrouter_model})...")
+                response = await client.chat.completions.create(
+                    model=self.openrouter_model,
+                    messages=messages,
+                    response_format=response_format,
+                    **kwargs
+                )
+                
+                if not response or not getattr(response, "choices", None):
+                     raise ValueError("Invalid response structure from OpenRouter")
+
+                content = response.choices[0].message.content
+                if content:
+                    logger.info(f"[LLM] SUCCESS on attempt {attempt} (Key #{key_id}).")
+                    # Luôn xoay sang key tiếp theo sau khi thành công để chuẩn bị cho request tới
+                    self.current_index = (self.current_index + 1) % len(self.clients)
+                    return content
+                
+                raise ValueError("Empty content from OpenRouter")
+
+            except Exception as e:
+                err_msg = f"{type(e).__name__}: {str(e)}"
+                logger.warning(f"[LLM] FAILED on attempt {attempt} (Key #{key_id}): {err_msg}")
+                
+                # Xoay key kể cả khi thất bại để attempt tiếp theo dùng key khác
+                old_index = self.current_index
+                self.current_index = (self.current_index + 1) % len(self.clients)
+                
+                if attempt <= MAX_RETRIES:
+                    logger.info(f"[LLM] Switching from Key #{old_index + 1} to #{self.current_index + 1}. Retrying in {RETRY_DELAY}s...")
+                    await asyncio.sleep(RETRY_DELAY)
+                else:
+                    logger.error(f"[LLM] FINAL FAILURE after {attempt} attempts.")
+                    raise e
+
+# Global instance for easy reuse (singleton-ish)
+_llm_client = None
+
+def get_llm_client() -> MultiLayerLLMClient:
+    global _llm_client
+    if _llm_client is None:
+        _llm_client = MultiLayerLLMClient()
+    return _llm_client

app/logging_setup.py

@@ -0,0 +1,112 @@
+"""Logging theo một biến LOG_LEVEL: debug | info | warning | error."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Final
+
+_SETUP_DONE = False
+
+PIPELINE_LOGGER_NAME: Final = "app.pipeline"
+CACHE_LOGGER_NAME: Final = "app.cache"
+STEPS_LOGGER_NAME: Final = "app.steps"
+ACCESS_LOGGER_NAME: Final = "app.access"
+
+
+def _normalize_level() -> str:
+    raw = os.getenv("LOG_LEVEL", "info").strip().lower()
+    if raw in ("debug", "info", "warning", "error"):
+        return raw
+    return "info"
+
+
+def setup_application_logging() -> None:
+    """Idempotent; gọi khi khởi động process (uvicorn, celery, worker_health)."""
+    global _SETUP_DONE
+    if _SETUP_DONE:
+        return
+    _SETUP_DONE = True
+
+    mode = _normalize_level()
+
+    level_map = {
+        "debug": logging.DEBUG,
+        "info": logging.INFO,
+        "warning": logging.WARNING,
+        "error": logging.ERROR,
+    }
+    root_level = level_map[mode]
+
+    fmt_named = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+    fmt_short = "%(asctime)s | %(levelname)-8s | %(message)s"
+
+    logging.basicConfig(
+        level=root_level,
+        format=fmt_named if mode == "debug" else fmt_short,
+        datefmt="%H:%M:%S",
+        force=True,
+    )
+
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("openai").setLevel(logging.WARNING)
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("uvicorn.error").setLevel(logging.INFO)
+    # HTTP/2 stack (httpx/httpcore) — khi LOG_LEVEL=debug root=DEBUG sẽ tràn log hpack; không cần cho debug app
+    for _name in ("hpack", "h2", "hyperframe", "urllib3"):
+        logging.getLogger(_name).setLevel(logging.WARNING)
+
+    if mode == "debug":
+        logging.getLogger("agents").setLevel(logging.DEBUG)
+        logging.getLogger("solver").setLevel(logging.DEBUG)
+        logging.getLogger("app").setLevel(logging.DEBUG)
+        logging.getLogger(CACHE_LOGGER_NAME).setLevel(logging.DEBUG)
+        logging.getLogger(STEPS_LOGGER_NAME).setLevel(logging.DEBUG)
+        logging.getLogger(PIPELINE_LOGGER_NAME).setLevel(logging.INFO)
+        logging.getLogger(ACCESS_LOGGER_NAME).setLevel(logging.INFO)
+        logging.getLogger("app.main").setLevel(logging.INFO)
+        logging.getLogger("worker").setLevel(logging.INFO)
+    elif mode == "info":
+        # Chỉ HTTP access (app.access) + startup; ẩn chi tiết agents/orchestrator/pipeline SUCCESS
+        logging.getLogger("agents").setLevel(logging.INFO)
+        logging.getLogger("solver").setLevel(logging.WARNING)
+        logging.getLogger("app").setLevel(logging.INFO)
+        logging.getLogger(CACHE_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(STEPS_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(PIPELINE_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(ACCESS_LOGGER_NAME).setLevel(logging.INFO)
+        logging.getLogger("app.main").setLevel(logging.INFO)
+        logging.getLogger("worker").setLevel(logging.WARNING)
+    elif mode == "warning":
+        logging.getLogger("agents").setLevel(logging.WARNING)
+        logging.getLogger("solver").setLevel(logging.WARNING)
+        logging.getLogger("app.routers").setLevel(logging.WARNING)
+        logging.getLogger(CACHE_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(STEPS_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(PIPELINE_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger(ACCESS_LOGGER_NAME).setLevel(logging.WARNING)
+        logging.getLogger("app.main").setLevel(logging.WARNING)
+        logging.getLogger("worker").setLevel(logging.WARNING)
+    else:  # error
+        logging.getLogger("agents").setLevel(logging.ERROR)
+        logging.getLogger("solver").setLevel(logging.ERROR)
+        logging.getLogger("app.routers").setLevel(logging.ERROR)
+        logging.getLogger(CACHE_LOGGER_NAME).setLevel(logging.ERROR)
+        logging.getLogger(STEPS_LOGGER_NAME).setLevel(logging.ERROR)
+        logging.getLogger(PIPELINE_LOGGER_NAME).setLevel(logging.ERROR)
+        logging.getLogger(ACCESS_LOGGER_NAME).setLevel(logging.ERROR)
+        logging.getLogger("app.main").setLevel(logging.ERROR)
+        logging.getLogger("worker").setLevel(logging.ERROR)
+
+    logging.getLogger(__name__).debug(
+        "LOG_LEVEL=%s root=%s", mode, logging.getLevelName(root_level)
+    )
+
+
+def get_log_level() -> str:
+    return _normalize_level()
+
+
+def is_debug_level() -> bool:
+    return _normalize_level() == "debug"

app/logutil.py

@@ -0,0 +1,67 @@
+"""log_step (debug), pipeline (debug), access log ở middleware."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from app.logging_setup import PIPELINE_LOGGER_NAME, STEPS_LOGGER_NAME
+
+_pipeline = logging.getLogger(PIPELINE_LOGGER_NAME)
+_steps = logging.getLogger(STEPS_LOGGER_NAME)
+
+
+def is_debug_mode() -> bool:
+    """Chi tiết từng bước chỉ khi LOG_LEVEL=debug."""
+    return os.getenv("LOG_LEVEL", "info").strip().lower() == "debug"
+
+
+def _truncate(val: Any, max_len: int = 2000) -> Any:
+    if val is None:
+        return None
+    if isinstance(val, (int, float, bool)):
+        return val
+    s = str(val)
+    if len(s) > max_len:
+        return s[:max_len] + f"... (+{len(s) - max_len} chars)"
+    return s
+
+
+def log_step(step: str, **fields: Any) -> None:
+    """Chỉ khi LOG_LEVEL=debug: DB / cache / orchestrator."""
+    if not is_debug_mode():
+        return
+    safe = {k: _truncate(v) for k, v in fields.items()}
+    try:
+        payload = json.dumps(safe, ensure_ascii=False, default=str)
+    except Exception:
+        payload = str(safe)
+    _steps.debug("[step:%s] %s", step, payload)
+
+
+def log_pipeline_success(operation: str, **fields: Any) -> None:
+    """Chỉ hiện khi debug (pipeline SUCCESS không dùng ở info — đã có app.access)."""
+    if not is_debug_mode():
+        return
+    safe = {k: _truncate(v, 500) for k, v in fields.items()}
+    _pipeline.info(
+        "SUCCESS %s %s",
+        operation,
+        json.dumps(safe, ensure_ascii=False, default=str),
+    )
+
+
+def log_pipeline_failure(operation: str, error: str | None = None, **fields: Any) -> None:
+    """Thất bại pipeline: luôn dùng WARNING để vẫn thấy khi LOG_LEVEL=warning."""
+    if is_debug_mode():
+        safe = {k: _truncate(v, 500) for k, v in fields.items()}
+        _pipeline.warning(
+            "FAIL %s err=%s %s",
+            operation,
+            _truncate(error, 300),
+            json.dumps(safe, ensure_ascii=False, default=str),
+        )
+    else:
+        _pipeline.warning("FAIL %s", operation)

app/main.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+import uuid
+import warnings
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, File, HTTPException, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+
+load_dotenv()
+
+from app.runtime_env import apply_runtime_env_defaults
+
+apply_runtime_env_defaults()
+
+os.environ["NO_ALBUMENTATIONS_UPDATE"] = "1"
+warnings.filterwarnings("ignore", category=UserWarning, module="pydantic")
+warnings.filterwarnings("ignore", category=UserWarning, module="albumentations")
+
+from app.logging_setup import ACCESS_LOGGER_NAME, get_log_level, setup_application_logging
+
+setup_application_logging()
+
+# Routers (after logging)
+from app.routers import auth, sessions, solve
+from agents.ocr_agent import OCRAgent
+from app.routers.solve import get_orchestrator
+from app.supabase_client import get_supabase
+from app.websocket_manager import register_websocket_routes
+
+logger = logging.getLogger("app.main")
+_access = logging.getLogger(ACCESS_LOGGER_NAME)
+
+app = FastAPI(title="Visual Math Solver API v4.0")
+
+
+@app.middleware("http")
+async def access_log_middleware(request: Request, call_next):
+    """LOG_LEVEL=info/debug: mọi request; warning: chỉ 4xx/5xx; error: chỉ 4xx/5xx ở mức error."""
+    start = time.perf_counter()
+    response = await call_next(request)
+    ms = (time.perf_counter() - start) * 1000
+    mode = get_log_level()
+    method = request.method
+    path = request.url.path
+    status = response.status_code
+
+    if mode in ("debug", "info"):
+        _access.info("%s %s -> %s (%.0fms)", method, path, status, ms)
+    elif mode == "warning":
+        if status >= 500:
+            _access.error("%s %s -> %s (%.0fms)", method, path, status, ms)
+        elif status >= 400:
+            _access.warning("%s %s -> %s (%.0fms)", method, path, status, ms)
+    elif mode == "error":
+        if status >= 400:
+            _access.error("%s %s -> %s", method, path, status)
+
+    return response
+
+
+from worker.celery_app import BROKER_URL
+
+_broker_tail = BROKER_URL.split("@")[-1] if "@" in BROKER_URL else BROKER_URL
+if get_log_level() in ("debug", "info"):
+    logger.info("App starting LOG_LEVEL=%s | Redis: %s", get_log_level(), _broker_tail)
+else:
+    logger.warning(
+        "App starting LOG_LEVEL=%s | Redis: %s", get_log_level(), _broker_tail
+    )
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(auth.router)
+app.include_router(sessions.router)
+app.include_router(solve.router)
+
+register_websocket_routes(app)
+
+
+def get_ocr_agent() -> OCRAgent:
+    """Same OCR instance as the solve pipeline (no duplicate model load)."""
+    return get_orchestrator().ocr_agent
+
+
+supabase_client = get_supabase()
+
+
+@app.get("/")
+def read_root():
+    return {"message": "Visual Math Solver API v4.0 is running"}
+
+
+@app.post("/api/v1/ocr")
+async def upload_ocr(file: UploadFile = File(...)):
+    """Legacy OCR endpoint (retained for now as it's stateless)"""
+    temp_path = f"temp_{uuid.uuid4()}.png"
+    with open(temp_path, "wb") as buffer:
+        buffer.write(await file.read())
+
+    try:
+        text = await get_ocr_agent().process_image(temp_path)
+        return {"text": text}
+    finally:
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+
+
+@app.get("/api/v1/solve/{job_id}")
+async def get_job_status(job_id: str):
+    """Retrieve job status (can be used for polling if WS fails)"""
+    response = supabase_client.table("jobs").select("*").eq("id", job_id).execute()
+    if not response.data:
+        raise HTTPException(status_code=404, detail="Job not found")
+    return response.data[0]

app/models/schemas.py

@@ -0,0 +1,66 @@
+from pydantic import BaseModel, EmailStr, field_validator
+from typing import Optional, List, Any, Dict
+from datetime import datetime
+import uuid
+
+from app.url_utils import sanitize_url
+
+# --- Auth Schemas ---
+class UserProfile(BaseModel):
+    id: uuid.UUID
+    display_name: Optional[str] = None
+    avatar_url: Optional[str] = None
+    created_at: datetime
+
+class User(BaseModel):
+    id: uuid.UUID
+    email: EmailStr
+
+# --- Session Schemas ---
+class SessionBase(BaseModel):
+    title: str = "Bài toán mới"
+
+class SessionCreate(SessionBase):
+    pass
+
+class Session(SessionBase):
+    id: uuid.UUID
+    user_id: uuid.UUID
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+# --- Message Schemas ---
+class MessageBase(BaseModel):
+    role: str
+    type: str = "text"
+    content: str
+    metadata: Dict[str, Any] = {}
+
+class MessageCreate(MessageBase):
+    session_id: uuid.UUID
+
+class Message(MessageBase):
+    id: uuid.UUID
+    session_id: uuid.UUID
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+# --- Solve Job Schemas ---
+class SolveRequest(BaseModel):
+    text: str
+    image_url: Optional[str] = None
+    request_video: bool = False
+
+    @field_validator("image_url", mode="before")
+    @classmethod
+    def _clean_image_url(cls, v):
+        return sanitize_url(v) if v is not None else None
+
+class SolveResponse(BaseModel):
+    job_id: str
+    status: str

app/routers/__init__.py

@@ -0,0 +1 @@
+from . import auth, sessions, solve

app/routers/auth.py

@@ -0,0 +1,23 @@
+from fastapi import APIRouter, Depends, HTTPException
+from app.dependencies import get_current_user_id
+from app.supabase_client import get_supabase
+from app.models.schemas import UserProfile
+import uuid
+
+router = APIRouter(prefix="/api/v1/auth", tags=["Auth"])
+
+@router.get("/me")
+async def get_me(user_id=Depends(get_current_user_id)):
+    """获取当前登录用户的信息 (Retrieve current user profile)"""
+    supabase = get_supabase()
+    res = supabase.table("profiles").select("*").eq("id", user_id).execute()
+    if not res.data:
+        raise HTTPException(status_code=404, detail="Profile not found.")
+    return res.data[0]
+
+@router.patch("/me")
+async def update_me(data: dict, user_id=Depends(get_current_user_id)):
+    """Cập nhật profile hiện tại (Update current profile)"""
+    supabase = get_supabase()
+    res = supabase.table("profiles").update(data).eq("id", user_id).execute()
+    return res.data[0]

app/routers/sessions.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from typing import List
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from app.dependencies import get_current_user_id
+from app.logutil import log_step
+from app.session_cache import (
+    get_sessions_list_cached,
+    invalidate_for_user,
+    invalidate_session_owner,
+    session_owned_by_user,
+)
+from app.supabase_client import get_supabase
+
+router = APIRouter(prefix="/api/v1/sessions", tags=["Sessions"])
+
+
+@router.get("", response_model=List[dict])
+async def list_sessions(user_id=Depends(get_current_user_id)):
+    """Danh sách các phiên chat của người dùng (List user's chat sessions)"""
+    supabase = get_supabase()
+
+    def fetch() -> list:
+        res = (
+            supabase.table("sessions")
+            .select("*")
+            .eq("user_id", user_id)
+            .order("updated_at", desc=True)
+            .execute()
+        )
+        log_step("db_select", table="sessions", op="list", user_id=str(user_id))
+        return res.data
+
+    return get_sessions_list_cached(str(user_id), fetch)
+
+
+@router.post("", response_model=dict)
+async def create_session(user_id=Depends(get_current_user_id)):
+    """Tạo một phiên chat mới (Create a new chat session)"""
+    supabase = get_supabase()
+    res = supabase.table("sessions").insert(
+        {"user_id": user_id, "title": "Bài toán mới"}
+    ).execute()
+    log_step("db_insert", table="sessions", op="create")
+    invalidate_for_user(str(user_id))
+    return res.data[0]
+
+
+@router.get("/{session_id}/messages", response_model=List[dict])
+async def get_session_messages(session_id: str, user_id=Depends(get_current_user_id)):
+    """Lấy toàn bộ lịch sử tin nhắn của một phiên (Get chat history for a session)"""
+    supabase = get_supabase()
+
+    def owns() -> bool:
+        res = (
+            supabase.table("sessions")
+            .select("id")
+            .eq("id", session_id)
+            .eq("user_id", user_id)
+            .execute()
+        )
+        log_step("db_select", table="sessions", op="owner_check", session_id=session_id)
+        return bool(res.data)
+
+    if not session_owned_by_user(session_id, str(user_id), owns):
+        raise HTTPException(
+            status_code=403, detail="Forbidden: You do not own this session."
+        )
+
+    res = (
+        supabase.table("messages")
+        .select("*")
+        .eq("session_id", session_id)
+        .order("created_at", desc=False)
+        .execute()
+    )
+    log_step("db_select", table="messages", op="list", session_id=session_id)
+    return res.data
+
+
+@router.delete("/{session_id}")
+async def delete_session(session_id: str, user_id=Depends(get_current_user_id)):
+    """Xóa một phiên chat (Delete a chat session)"""
+    supabase = get_supabase()
+
+    def owns() -> bool:
+        res = (
+            supabase.table("sessions")
+            .select("id")
+            .eq("id", session_id)
+            .eq("user_id", user_id)
+            .execute()
+        )
+        return bool(res.data)
+
+    if not session_owned_by_user(session_id, str(user_id), owns):
+        raise HTTPException(
+            status_code=403, detail="Forbidden: You do not own this session."
+        )
+
+    # jobs.session_id FK must be cleared before sessions row
+    supabase.table("jobs").delete().eq("session_id", session_id).eq("user_id", user_id).execute()
+    log_step("db_delete", table="jobs", op="by_session", session_id=session_id)
+    supabase.table("messages").delete().eq("session_id", session_id).execute()
+    log_step("db_delete", table="messages", op="by_session", session_id=session_id)
+    res = (
+        supabase.table("sessions")
+        .delete()
+        .eq("id", session_id)
+        .eq("user_id", user_id)
+        .execute()
+    )
+    log_step("db_delete", table="sessions", session_id=session_id)
+    invalidate_for_user(str(user_id))
+    invalidate_session_owner(session_id, str(user_id))
+    return {"status": "ok", "deleted_id": session_id}
+
+
+@router.patch("/{session_id}/title")
+async def update_session_title(title: str, session_id: str, user_id=Depends(get_current_user_id)):
+    """Cập nhật tiêu đề phiên chat (Rename a chat session)"""
+    supabase = get_supabase()
+    res = (
+        supabase.table("sessions")
+        .update({"title": title})
+        .eq("id", session_id)
+        .eq("user_id", user_id)
+        .execute()
+    )
+    log_step("db_update", table="sessions", op="title", session_id=session_id)
+    invalidate_for_user(str(user_id))
+    return res.data[0]
+
+
+@router.get("/{session_id}/assets", response_model=List[dict])
+async def get_session_assets(session_id: str, user_id=Depends(get_current_user_id)):
+    """Lấy danh sách video đã render trong session (Get versioned assets for a session)"""
+    supabase = get_supabase()
+
+    def owns() -> bool:
+        res = (
+            supabase.table("sessions")
+            .select("id")
+            .eq("id", session_id)
+            .eq("user_id", user_id)
+            .execute()
+        )
+        return bool(res.data)
+
+    if not session_owned_by_user(session_id, str(user_id), owns):
+        raise HTTPException(
+            status_code=403, detail="Forbidden: You do not own this session."
+        )
+
+    res = (
+        supabase.table("session_assets")
+        .select("*")
+        .eq("session_id", session_id)
+        .order("version", desc=True)
+        .execute()
+    )
+    log_step("db_select", table="session_assets", op="list", session_id=session_id)
+    return res.data

app/routers/solve.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import logging
+import uuid
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+
+from agents.orchestrator import Orchestrator
+from app.dependencies import get_current_user_id
+from app.errors import format_error_for_user
+from app.logutil import log_pipeline_failure, log_pipeline_success, log_step
+from app.models.schemas import SolveRequest, SolveResponse
+from app.session_cache import invalidate_for_user, session_owned_by_user
+from app.supabase_client import get_supabase
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/v1/sessions", tags=["Solve"])
+
+# Eager init: all agents and models load at import time (also run in Docker build via scripts/prewarm_models.py).
+ORCHESTRATOR = Orchestrator()
+
+
+def get_orchestrator() -> Orchestrator:
+    return ORCHESTRATOR
+
+
+@router.post("/{session_id}/solve", response_model=SolveResponse)
+async def solve_problem(
+    session_id: str,
+    request: SolveRequest,
+    background_tasks: BackgroundTasks,
+    user_id=Depends(get_current_user_id),
+):
+    """
+    Gửi câu hỏi giải toán trong một session (Submit geometry problem in a session).
+    Lưu câu hỏi vào history và bắt đầu tiến trình giải.
+    """
+    supabase = get_supabase()
+    uid = str(user_id)
+
+    def owns() -> bool:
+        res = (
+            supabase.table("sessions")
+            .select("id")
+            .eq("id", session_id)
+            .eq("user_id", user_id)
+            .execute()
+        )
+        log_step("db_select", table="sessions", op="owner_check", session_id=session_id)
+        return bool(res.data)
+
+    if not session_owned_by_user(session_id, uid, owns):
+        log_pipeline_failure("solve_request", error="forbidden", session_id=session_id)
+        raise HTTPException(
+            status_code=403, detail="Forbidden: You do not own this session."
+        )
+
+    # NEW: Giới hạn 5 queries mỗi session
+    msg_count_res = (
+        supabase.table("messages")
+        .select("id", count="exact")
+        .eq("session_id", session_id)
+        .eq("role", "user")
+        .execute()
+    )
+    current_count = msg_count_res.count if msg_count_res.count is not None else 0
+    import os
+    if current_count >= 5 and os.getenv("ALLOW_TEST_BYPASS") != "true":
+        raise HTTPException(
+            status_code=400, 
+            detail="Bạn đã đạt giới hạn 5 câu hỏi cho phiên này. (Session limit reached: 5/5)"
+        )
+
+    supabase.table("messages").insert(
+        {
+            "session_id": session_id,
+            "role": "user",
+            "type": "text",
+            "content": request.text,
+            "metadata": {"image_url": request.image_url} if request.image_url else {},
+        }
+    ).execute()
+    log_step("db_insert", table="messages", op="user_message", session_id=session_id)
+
+    job_id = str(uuid.uuid4())
+    supabase.table("jobs").insert(
+        {
+            "id": job_id,
+            "user_id": user_id,
+            "session_id": session_id,
+            "status": "processing",
+            "input_text": request.text,
+        }
+    ).execute()
+    log_step("db_insert", table="jobs", job_id=job_id)
+
+    background_tasks.add_task(process_session_job, job_id, session_id, request, user_id)
+
+    title_check = supabase.table("sessions").select("title").eq("id", session_id).execute()
+    if title_check.data and title_check.data[0]["title"] == "Bài toán mới":
+        new_title = request.text[:50] + ("..." if len(request.text) > 50 else "")
+        supabase.table("sessions").update({"title": new_title}).eq("id", session_id).execute()
+        log_step("db_update", table="sessions", op="title_from_first_message")
+        invalidate_for_user(uid)
+
+    log_pipeline_success("solve_accepted", job_id=job_id, session_id=session_id)
+    return SolveResponse(job_id=job_id, status="processing")
+
+
+async def process_session_job(
+    job_id: str, session_id: str, request: SolveRequest, user_id: str
+):
+    """Tiến trình giải toán ngầm, cập nhật cả bảng jobs và bảng messages (history)."""
+    from app.websocket_manager import notify_status
+
+    async def status_update(status: str):
+        await notify_status(job_id, {"status": status})
+
+    supabase = get_supabase()
+    try:
+        # Fetch full history for the session
+        history_res = (
+            supabase.table("messages")
+            .select("*")
+            .eq("session_id", session_id)
+            .order("created_at", desc=False)
+            .execute()
+        )
+        history = history_res.data if history_res.data else []
+
+        result = await get_orchestrator().run(
+            request.text,
+            request.image_url,
+            job_id=job_id,
+            session_id=session_id,
+            status_callback=status_update,
+            request_video=request.request_video,
+            history=history,
+        )
+
+        status = result.get("status", "error") if "error" not in result else "error"
+
+        supabase.table("jobs").update({"status": status, "result": result}).eq(
+            "id", job_id
+        ).execute()
+        log_step("db_update", table="jobs", job_id=job_id, status=status)
+
+        if status != "rendering_queued":
+            supabase.table("messages").insert(
+                {
+                    "session_id": session_id,
+                    "role": "assistant",
+                    "type": "analysis" if "error" not in result else "error",
+                    "content": (
+                        result.get("semantic_analysis", "Đã có lỗi xảy ra.")
+                        if "error" not in result
+                        else result["error"]
+                    ),
+                    "metadata": {
+                        "job_id": job_id,
+                        "coordinates": result.get("coordinates"),
+                        "geometry_dsl": result.get("geometry_dsl"),
+                        "polygon_order": result.get("polygon_order", []),
+                        "drawing_phases": result.get("drawing_phases", []),
+                        "circles": result.get("circles", []),
+                        "lines": result.get("lines", []),
+                        "rays": result.get("rays", []),
+                        "video_url": result.get("video_url"),
+                        "solution": result.get("solution"),
+                    },
+                }
+            ).execute()
+            log_step("db_insert", table="messages", op="assistant", job_id=job_id)
+
+        await notify_status(job_id, {"status": status, "result": result})
+
+        if "error" in result:
+            log_pipeline_failure(
+                "solve_job", error=result.get("error"), job_id=job_id, session_id=session_id
+            )
+        else:
+            log_pipeline_success(
+                "solve_job", job_id=job_id, session_id=session_id, status=status
+            )
+
+    except Exception as e:
+        logger.exception("Error processing session job %s", job_id)
+        safe = format_error_for_user(e)
+        supabase.table("jobs").update(
+            {"status": "error", "result": {"error": safe}}
+        ).eq("id", job_id).execute()
+
+        supabase.table("messages").insert(
+            {
+                "session_id": session_id,
+                "role": "assistant",
+                "type": "error",
+                "content": f"Lỗi hệ thống: {safe}",
+                "metadata": {"job_id": job_id},
+            }
+        ).execute()
+
+        await notify_status(job_id, {"status": "error", "message": safe})
+        log_pipeline_failure("solve_job", error=safe, job_id=job_id, session_id=session_id)

app/runtime_env.py

@@ -0,0 +1,12 @@
+"""Default process env vars (Paddle/OpenMP). Call as early as possible after load_dotenv."""
+
+from __future__ import annotations
+
+import os
+
+
+def apply_runtime_env_defaults() -> None:
+    # Paddle respects OMP_NUM_THREADS at import; setdefault loses if platform already set 2+
+    os.environ["OMP_NUM_THREADS"] = "1"
+    os.environ["MKL_NUM_THREADS"] = "1"
+    os.environ["OPENBLAS_NUM_THREADS"] = "1"

app/session_cache.py

@@ -0,0 +1,48 @@
+"""TTL in-memory cache để giảm truy vấn Supabase lặp lại (list session, quyền sở hữu session)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from cachetools import TTLCache
+
+from app.logutil import log_step
+
+_session_list: TTLCache[str, list[Any]] = TTLCache(maxsize=512, ttl=45)
+_session_owner: TTLCache[tuple[str, str], bool] = TTLCache(maxsize=4096, ttl=45)
+
+
+def invalidate_for_user(user_id: str) -> None:
+    """Xoá cache list session của user (sau create / delete / rename / solve đổi title)."""
+    _session_list.pop(user_id, None)
+    log_step("cache_invalidate", target="session_list", user_id=user_id)
+
+
+def invalidate_session_owner(session_id: str, user_id: str) -> None:
+    _session_owner.pop((session_id, user_id), None)
+    log_step("cache_invalidate", target="session_owner", session_id=session_id, user_id=user_id)
+
+
+def get_sessions_list_cached(user_id: str, fetch: Callable[[], list[Any]]) -> list[Any]:
+    if user_id in _session_list:
+        log_step("cache_hit", kind="session_list", user_id=user_id)
+        return _session_list[user_id]
+    log_step("cache_miss", kind="session_list", user_id=user_id)
+    data = fetch()
+    _session_list[user_id] = data
+    return data
+
+
+def session_owned_by_user(
+    session_id: str,
+    user_id: str,
+    fetch: Callable[[], bool],
+) -> bool:
+    key = (session_id, user_id)
+    if key in _session_owner:
+        log_step("cache_hit", kind="session_owner", session_id=session_id)
+        return _session_owner[key]
+    log_step("cache_miss", kind="session_owner", session_id=session_id)
+    ok = fetch()
+    _session_owner[key] = ok
+    return ok

app/supabase_client.py

@@ -0,0 +1,37 @@
+import os
+from supabase import Client, ClientOptions, create_client
+from supabase_auth import SyncMemoryStorage
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from app.url_utils import sanitize_env
+
+
+def get_supabase() -> Client:
+    """Service-role client for server-side operations (bypasses RLS when policies expect service role)."""
+    url = sanitize_env(os.getenv("SUPABASE_URL"))
+    key = sanitize_env(os.getenv("SUPABASE_SERVICE_ROLE_KEY") or os.getenv("SUPABASE_KEY"))
+    if not url or not key:
+        raise RuntimeError(
+            "SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY (or SUPABASE_KEY) must be set"
+        )
+    return create_client(url, key)
+
+
+def get_supabase_for_user_jwt(access_token: str) -> Client:
+    """
+    Client scoped to the logged-in user: PostgREST sends the user's JWT so RLS applies.
+    Use SUPABASE_ANON_KEY (publishable), not the service role key.
+    """
+    url = sanitize_env(os.getenv("SUPABASE_URL"))
+    anon = sanitize_env(os.getenv("SUPABASE_ANON_KEY") or os.getenv("NEXT_PUBLIC_SUPABASE_ANON_KEY"))
+    if not url or not anon:
+        raise RuntimeError(
+            "SUPABASE_URL and SUPABASE_ANON_KEY (or NEXT_PUBLIC_SUPABASE_ANON_KEY) must be set "
+            "for user-scoped Supabase access"
+        )
+    base_opts = ClientOptions(storage=SyncMemoryStorage())
+    merged_headers = {**dict(base_opts.headers), "Authorization": f"Bearer {access_token}"}
+    opts = ClientOptions(storage=SyncMemoryStorage(), headers=merged_headers)
+    return create_client(url, anon, opts)

app/url_utils.py

@@ -0,0 +1,23 @@
+"""Normalize URLs / env strings (HF secrets and copy-paste often include trailing newlines)."""
+
+
+def sanitize_url(value: str | None) -> str | None:
+    if value is None:
+        return None
+    s = value.strip().replace("\r", "").replace("\n", "").replace("\t", "")
+    return s or None
+
+
+def sanitize_env(value: str | None) -> str | None:
+    """Strip whitespace and line breaks from environment-backed strings."""
+    return sanitize_url(value)
+
+
+# OpenAI SDK (>=1.x) requires a non-empty api_key at client construction (Docker build / prewarm has no secrets).
+_OPENAI_API_KEY_BUILD_PLACEHOLDER = "build-placeholder-openrouter-not-for-production"
+
+
+def openai_compatible_api_key(raw: str | None) -> str:
+    """Return sanitized API key, or a placeholder so AsyncOpenAI() can be constructed without env at build time."""
+    k = sanitize_env(raw)
+    return k if k else _OPENAI_API_KEY_BUILD_PLACEHOLDER

app/websocket_manager.py

@@ -0,0 +1,40 @@
+"""WebSocket connection registry and job status notifications (avoid circular imports with main)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List
+
+from fastapi import WebSocket, WebSocketDisconnect
+
+logger = logging.getLogger(__name__)
+
+active_connections: Dict[str, List[WebSocket]] = {}
+
+
+async def notify_status(job_id: str, data: dict) -> None:
+    if job_id not in active_connections:
+        return
+    for connection in list(active_connections[job_id]):
+        try:
+            await connection.send_json(data)
+        except Exception as e:
+            logger.error("WS error sending to %s: %s", job_id, e)
+
+
+def register_websocket_routes(app) -> None:
+    """Attach websocket endpoint to the FastAPI app."""
+
+    @app.websocket("/ws/{job_id}")
+    async def websocket_endpoint(websocket: WebSocket, job_id: str) -> None:
+        await websocket.accept()
+        if job_id not in active_connections:
+            active_connections[job_id] = []
+        active_connections[job_id].append(websocket)
+        try:
+            while True:
+                await websocket.receive_text()
+        except WebSocketDisconnect:
+            active_connections[job_id].remove(websocket)
+            if not active_connections[job_id]:
+                del active_connections[job_id]

clean_ports.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Script to kill all project-related processes for a clean restart
+
+echo "🧹 Cleaning up project processes..."
+
+# Kill things on ports 8000 (Backend) and 3000 (Frontend)
+PORTS="8000 3000 11020"
+for PORT in $PORTS; do
+    PIDS=$(lsof -ti :$PORT)
+    if [ ! -z "$PIDS" ]; then
+        echo "Killing processes on port $PORT: $PIDS"
+        kill -9 $PIDS 2>/dev/null
+    fi
+done
+
+# Kill by process name
+echo "Killing any remaining Celery, Uvicorn, or Manim processes..."
+pkill -9 -f "celery" 2>/dev/null
+pkill -9 -f "uvicorn" 2>/dev/null
+pkill -9 -f "manim" 2>/dev/null
+
+echo "✅ Done. You can now restart your Backend, Worker, and Frontend."

migrations/v4_migration.sql

@@ -0,0 +1,95 @@
+-- ============================================================
+-- MATHSOLVER v4.0 - Migration Script (Multi-Session & History)
+-- ============================================================
+
+-- 1. Profiles Table (Extends Supabase Auth)
+CREATE TABLE IF NOT EXISTS public.profiles (
+    id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
+    display_name TEXT,
+    avatar_url TEXT,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Function to handle new user signup and auto-create profile
+CREATE OR REPLACE FUNCTION public.handle_new_user()
+RETURNS TRIGGER AS $$
+BEGIN
+    INSERT INTO public.profiles (id, display_name, avatar_url)
+    VALUES (
+        NEW.id, 
+        COALESCE(NEW.raw_user_meta_data->>'full_name', NEW.email),
+        NEW.raw_user_meta_data->>'avatar_url'
+    );
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+
+-- Trigger for profile creation
+DROP TRIGGER IF EXISTS on_auth_user_created ON auth.users;
+CREATE TRIGGER on_auth_user_created
+    AFTER INSERT ON auth.users
+    FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
+
+-- 2. Sessions Table
+CREATE TABLE IF NOT EXISTS public.sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    title TEXT DEFAULT 'Bài toán mới',
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Index for sessions
+CREATE INDEX IF NOT EXISTS idx_sessions_user_id ON public.sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_updated_at ON public.sessions(updated_at DESC);
+
+-- 3. Messages Table
+CREATE TABLE IF NOT EXISTS public.messages (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id UUID NOT NULL REFERENCES public.sessions(id) ON DELETE CASCADE,
+    role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
+    type TEXT NOT NULL DEFAULT 'text',
+    content TEXT NOT NULL,
+    metadata JSONB DEFAULT '{}'::jsonb,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- Index for messages
+CREATE INDEX IF NOT EXISTS idx_messages_session_id ON public.messages(session_id);
+CREATE INDEX IF NOT EXISTS idx_messages_created_at ON public.messages(session_id, created_at);
+
+-- 4. Update Jobs Table
+ALTER TABLE public.jobs ADD COLUMN IF NOT EXISTS user_id UUID REFERENCES auth.users(id);
+ALTER TABLE public.jobs ADD COLUMN IF NOT EXISTS session_id UUID REFERENCES public.sessions(id);
+
+-- 5. Row Level Security (RLS)
+ALTER TABLE public.profiles ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.sessions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.messages ENABLE ROW LEVEL SECURITY;
+
+-- Polices for public.profiles
+DROP POLICY IF EXISTS "Users view own profile" ON public.profiles;
+CREATE POLICY "Users view own profile" ON public.profiles FOR SELECT USING (auth.uid() = id);
+DROP POLICY IF EXISTS "Users update own profile" ON public.profiles;
+CREATE POLICY "Users update own profile" ON public.profiles FOR UPDATE USING (auth.uid() = id);
+
+-- Policies for public.sessions
+DROP POLICY IF EXISTS "Users manage own sessions" ON public.sessions;
+CREATE POLICY "Users manage own sessions" ON public.sessions FOR ALL USING (auth.uid() = user_id);
+
+-- Policies for public.messages
+DROP POLICY IF EXISTS "Users view own messages" ON public.messages;
+CREATE POLICY "Users view own messages" ON public.messages FOR ALL USING (
+    session_id IN (SELECT id FROM public.sessions WHERE user_id = auth.uid())
+);
+
+-- Policies for public.jobs
+DROP POLICY IF EXISTS "Users view own jobs" ON public.jobs;
+CREATE POLICY "Users view own jobs" ON public.jobs FOR ALL USING (auth.uid() = user_id OR user_id IS NULL);
+
+-- Grant permissions to public/authenticated
+GRANT ALL ON public.profiles TO authenticated;
+GRANT ALL ON public.sessions TO authenticated;
+GRANT ALL ON public.messages TO authenticated;
+GRANT ALL ON public.jobs TO authenticated;

requirements.txt

@@ -0,0 +1,34 @@
+# Target: Python 3.11 (see Dockerfile). Used by: FastAPI API, Celery worker, Manim render, OCR/vision stack.
+# Install: pip install -r requirements.txt
+
+# --- HTTP API ---
+cachetools>=5.3
+fastapi>=0.115,<1
+uvicorn[standard]>=0.30
+python-multipart>=0.0.9
+python-dotenv>=1.0
+pydantic[email]>=2.4
+email-validator>=2
+
+# --- Auth / data / queue ---
+openai>=1.40
+supabase>=2.0
+celery>=5.3
+redis>=5
+httpx>=0.27
+websockets>=12
+
+# --- Math & symbolic solver ---
+sympy>=1.12
+numpy>=1.26,<2
+scipy>=1.11
+opencv-python-headless>=4.8,<4.10
+
+# --- Video (GeometryScene via CLI) ---
+manim>=0.18,<0.20
+
+# --- OCR & vision (orchestrator / legacy /ocr) ---
+pix2tex>=0.1.4
+paddleocr==2.7.3
+paddlepaddle==2.6.2
+ultralytics==8.2.2

run_api_test.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+
+LOG_FILE="api_test_results.log"
+echo "=== Starting API E2E Test Suite ($(date)) ===" > $LOG_FILE
+
+# 1. Start BE Server in background
+echo "[INFO] Starting Backend Server..." | tee -a $LOG_FILE
+export ALLOW_TEST_BYPASS=true
+export LOG_LEVEL=info
+PYTHONPATH=. venv/bin/python -m uvicorn app.main:app --port 8000 > server_debug.log 2>&1 &
+SERVER_PID=$!
+
+# 2. Wait for server to be ready
+echo "[INFO] Waiting for server (PID: $SERVER_PID) on port 8000..." | tee -a $LOG_FILE
+MAX_RETRIES=15
+READY=0
+for i in $(seq 1 $MAX_RETRIES); do
+    if curl -s http://localhost:8000/ > /dev/null; then
+        READY=1
+        break
+    fi
+    sleep 2
+done
+
+if [ $READY -eq 0 ]; then
+    echo "[ERROR] Server failed to start in time. Check server_debug.log" | tee -a $LOG_FILE
+    kill $SERVER_PID
+    exit 1
+fi
+echo "[INFO] Server is READY." | tee -a $LOG_FILE
+
+# 3. Prepare Test Data
+echo "[INFO] Preparing fresh test data..." | tee -a $LOG_FILE
+PREP_OUTPUT=$(PYTHONPATH=. venv/bin/python scripts/prepare_api_test.py)
+echo "$PREP_OUTPUT" >> $LOG_FILE
+
+export TEST_USER_ID=$(echo "$PREP_OUTPUT" | grep "RESULT:USER_ID=" | cut -d'=' -f2)
+export TEST_SESSION_ID=$(echo "$PREP_OUTPUT" | grep "RESULT:SESSION_ID=" | cut -d'=' -f2)
+
+if [ -z "$TEST_USER_ID" ] || [ -z "$TEST_SESSION_ID" ]; then
+    echo "[ERROR] Failed to prepare test data." | tee -a $LOG_FILE
+    kill $SERVER_PID
+    exit 1
+fi
+
+echo "[INFO] Test Data: User=$TEST_USER_ID, Session=$TEST_SESSION_ID" | tee -a $LOG_FILE
+
+# 4. Run Pytest
+echo "[INFO] Running API E2E Tests..." | tee -a $LOG_FILE
+PYTHONPATH=. venv/bin/python -m pytest tests/test_api_real_e2e.py -s >> $LOG_FILE 2>&1
+TEST_EXIT_CODE=$?
+
+# 5. Cleanup
+echo "[INFO] Shutting down Server..." | tee -a $LOG_FILE
+kill $SERVER_PID
+
+echo "==========================================" | tee -a $LOG_FILE
+if [ $TEST_EXIT_CODE -eq 0 ]; then
+    echo "FINAL RESULT: ✅ ALL API TESTS PASSED" | tee -a $LOG_FILE
+else
+    echo "FINAL RESULT: ❌ SOME API TESTS FAILED (Code: $TEST_EXIT_CODE)" | tee -a $LOG_FILE
+fi
+echo "==========================================" | tee -a $LOG_FILE
+
+exit $TEST_EXIT_CODE

run_full_api_test.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+# Configuration and Cleanup
+LOG_FILE="full_api_suite.log"
+REPORT_FILE="full_api_test_report.md"
+JSON_RESULTS="temp_suite_results.json"
+
+echo "=== Starting Full API Suite Test ($(date)) ===" > $LOG_FILE
+
+# Cleanup on exit
+trap 'echo "[INFO] Cleaning up processes..."; kill $SERVER_PID 2>/dev/null; sleep 1' EXIT
+
+# 1. Start Server in EAGER MODE + MOCK VIDEO (no Redis/Worker needed)
+echo "[INFO] Starting Backend Server (EAGER + MOCK_VIDEO)..." | tee -a $LOG_FILE
+export ALLOW_TEST_BYPASS=true
+export LOG_LEVEL=info
+export CELERY_TASK_ALWAYS_EAGER=true
+export CELERY_RESULT_BACKEND=rpc://
+export MOCK_VIDEO=true
+PYTHONPATH=. venv/bin/python -m uvicorn app.main:app --port 8000 > server_debug.log 2>&1 &
+SERVER_PID=$!
+
+# 2. Wait for server
+echo "[INFO] Waiting for server (PID: $SERVER_PID)..." | tee -a $LOG_FILE
+for i in {1..20}; do
+    if curl -s http://localhost:8000/ > /dev/null; then
+        echo "[INFO] Server is READY." | tee -a $LOG_FILE
+        break
+    fi
+    sleep 2
+done
+
+# 3. Prepare Test Data
+echo "[INFO] Preparing fresh test data..." | tee -a $LOG_FILE
+PREP_OUTPUT=$(PYTHONPATH=. venv/bin/python scripts/prepare_api_test.py)
+export TEST_USER_ID=$(echo "$PREP_OUTPUT" | grep "RESULT:USER_ID=" | cut -d'=' -f2)
+export TEST_SESSION_ID=$(echo "$PREP_OUTPUT" | grep "RESULT:SESSION_ID=" | cut -d'=' -f2)
+
+if [ -z "$TEST_USER_ID" ]; then
+    echo "[ERROR] Failed to prepare test data." | tee -a $LOG_FILE
+    exit 1
+fi
+
+# 4. Run Pytest Suite
+echo "[INFO] Executing Full API Suite..." | tee -a $LOG_FILE
+PYTHONPATH=. venv/bin/python -m pytest tests/test_api_full_suite.py -s >> $LOG_FILE 2>&1
+TEST_EXIT_CODE=$?
+
+# 5. Shut down server
+echo "[INFO] Shutting down processes..." | tee -a $LOG_FILE
+
+# 6. Generate Markdown Report
+echo "[INFO] Generating Markdown Report..." | tee -a $LOG_FILE
+PYTHONPATH=. venv/bin/python scripts/generate_report.py "$JSON_RESULTS" "$REPORT_FILE"
+
+echo "==========================================" | tee -a $LOG_FILE
+echo "DONE. Check $REPORT_FILE for results." | tee -a $LOG_FILE
+echo "==========================================" | tee -a $LOG_FILE
+
+exit $TEST_EXIT_CODE

scripts/backend_test_suite.py

@@ -0,0 +1,97 @@
+import requests
+import time
+import json
+import sys
+
+BASE_URL = "http://localhost:8000/api/v1"
+
+TEST_CASES = [
+    {
+        "name": "Equilateral Triangle",
+        "payload": {"text": "Vẽ tam giác đều cạnh 5.", "request_video": True}
+    },
+    {
+        "name": "Right Triangle (3-4-5)",
+        "payload": {"text": "Cho tam giác ABC vuông tại A có AB=3, AC=4. Tính BC.", "request_video": True}
+    },
+    {
+        "name": "Isosceles Triangle",
+        "payload": {"text": "Cho tam giác ABC cân tại A có AB=5, BC=6.", "request_video": False}
+    },
+    {
+        "name": "Square",
+        "payload": {"text": "Vẽ hình vuông ABCD cạnh 4.", "request_video": True}
+    },
+    {
+        "name": "Invalid Input",
+        "payload": {"text": "abcxyz", "request_video": False}
+    }
+]
+
+def run_test(test_case):
+    print(f"\n[TEST] Running: {test_case['name']}...")
+    try:
+        start_time = time.time()
+        # Create job
+        response = requests.post(f"{BASE_URL}/solve", json=test_case['payload'])
+        if response.status_code != 200:
+            print(f"  [FAIL] Initial request failed: {response.text}")
+            return False
+        
+        job_id = response.json().get("job_id")
+        print(f"  [INFO] Job ID: {job_id}")
+        
+        # Poll for completion
+        status = "processing"
+        max_attempts = 40
+        attempts = 0
+        while status in ["processing", "solving", "rendering_queued", "rendering"] and attempts < max_attempts:
+            time.sleep(5)
+            res = requests.get(f"{BASE_URL}/solve/{job_id}")
+            data = res.json()
+            status = data.get("status")
+            print(f"  [INFO] Status: {status} (Attempt {attempts+1})")
+            if status == "success":
+                duration = time.time() - start_time
+                print(f"  [SUCCESS] Completed in {duration:.2f}s")
+                if test_case['payload'].get('request_video'):
+                    video_url = data.get("result", {}).get("video_url")
+                    if video_url:
+                        print(f"  [INFO] Video URL: {video_url}")
+                    else:
+                        print("  [WARNING] Video requested but no URL found in result.")
+                return True
+            if status == "error":
+                print(f"  [FAIL] Solver error: {data.get('result', {}).get('error')}")
+                return False
+            attempts += 1
+            
+        if attempts >= max_attempts:
+            print("  [FAIL] Timeout reached.")
+            return False
+            
+    except Exception as e:
+        print(f"  [ERROR] Exception: {str(e)}")
+        return False
+
+if __name__ == "__main__":
+    results = []
+    print("=== MathSolver Backend Test Suite ===")
+    for tc in TEST_CASES:
+        success = run_test(tc)
+        results.append((tc['name'], success))
+    
+    print("\n" + "="*40)
+    print("FINAL REPORT:")
+    all_passed = True
+    for name, success in results:
+        status_str = "PASS" if success else "FAIL"
+        print(f"- {name}: {status_str}")
+        if not success: all_passed = False
+    
+    if all_passed:
+        print("\nALL TESTS PASSED! 🎉")
+        sys.exit(0)
+    else:
+        print("\nSOME TESTS FAILED. ❌")
+        sys.exit(1)

scripts/generate_report.py

@@ -0,0 +1,73 @@
+import json
+import os
+import sys
+from datetime import datetime
+
+def generate_report(json_path, report_path):
+    try:
+        with open(json_path, 'r') as f:
+            data = json.load(f)
+        
+        with open(report_path, 'w') as f:
+            f.write('# Báo cáo Kiểm thử API Toàn diện (Full Suite API Report)\n\n')
+            f.write(f'**Thời gian chạy:** {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}\n')
+            f.write(f'**Kết quả chung:** {"✅ PASS" if all(r.get("success", False) for r in data) else "❌ FAIL"}\n\n')
+            
+            f.write('| ID | Câu hỏi (Query) | Trạng thái | Thời gian (s) | Kết quả / Lỗi |\n')
+            f.write('| :--- | :--- | :--- | :--- | :--- |\n')
+            for r in data:
+                status = "✅ PASS" if r.get("success") else "❌ FAIL"
+                elapsed = f"{r.get('elapsed', 0):.2f}"
+                query = r.get('query', '-')
+                
+                # Extract analysis or error
+                res = r.get('result', {})
+                if not isinstance(res, dict):
+                    res = {}
+                
+                analysis = res.get('semantic_analysis', '-')
+                if not r.get("success"):
+                    analysis = f"**Lỗi:** {r.get('error', '-')}"
+                
+                # Truncate long analysis for table
+                short_analysis = (analysis[:100] + '...') if len(analysis) > 100 else analysis
+                
+                f.write(f'| {r["id"]} | {query} | {status} | {elapsed} | {short_analysis} |\n')
+            
+            f.write('\n---\n**Chi tiết Output (DSL & Analysis):**\n')
+            for r in data:
+                if r.get('success'):
+                    res = r.get('result', {})
+                    if not isinstance(res, dict):
+                        continue
+                        
+                    f.write(f"\n### Case {r['id']}: {r.get('query')}\n")
+                    f.write(f"**Semantic Analysis:**\n{res.get('semantic_analysis', '-')}\n\n")
+                    f.write(f"**Geometry DSL:**\n```\n{res.get('geometry_dsl', '-')}\n```\n")
+                    
+                    # v5.1 Solution info
+                    sol = res.get('solution')
+                    if sol and isinstance(sol, dict):
+                        f.write("**Solution (v5.1):**\n")
+                        f.write(f"- **Answer:** {sol.get('answer', 'N/A')}\n")
+                        f.write("- **Steps:**\n")
+                        steps = sol.get('steps', [])
+                        if steps:
+                            for step in steps:
+                                f.write(f"  - {step}\n")
+                        else:
+                            f.write("  - (Không có bước giải cụ thể)\n")
+                        
+                        if sol.get('symbolic_expression'):
+                            f.write(f"- **Symbolic:** `{sol.get('symbolic_expression')}`\n")
+                        f.write("\n")
+            
+        print(f'Report generated: {report_path}')
+    except Exception as e:
+        print(f'Error generating report: {e}')
+
+if __name__ == "__main__":
+    if len(sys.argv) < 3:
+        print("Usage: python generate_report.py <json_results> <report_output>")
+        sys.exit(1)
+    generate_report(sys.argv[1], sys.argv[2])

scripts/prepare_api_test.py

@@ -0,0 +1,31 @@
+import uuid
+import sys
+import os
+
+# Add parent dir to path to import app modules
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.supabase_client import get_supabase
+
+def prepare():
+    supabase = get_supabase()
+    # Use existing valid user to avoid foreign key violation on sessions.user_id
+    user_id = "8cd3adb0-7964-4575-949c-d0cadcd8b679"
+    session_id = str(uuid.uuid4())
+    
+    print(f"Using existing test user: {user_id}")
+    
+    print(f"Creating fresh test session: {session_id}")
+    # Insert session
+    supabase.table("sessions").insert({
+        "id": session_id,
+        "user_id": user_id,
+        "title": f"Fresh API Test {session_id[:8]}"
+    }).execute()
+    
+    # Return IDs for the test script
+    print(f"RESULT:USER_ID={user_id}")
+    print(f"RESULT:SESSION_ID={session_id}")
+
+if __name__ == "__main__":
+    prepare()

scripts/prewarm_models.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""
+Download and load all heavy models during Docker build (YOLO, PaddleOCR, Pix2Tex, agents).
+Fails the image build if initialization fails.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+# Ensure imports work when run as `python scripts/prewarm_models.py` from WORKDIR
+_APP_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _APP_ROOT not in sys.path:
+    sys.path.insert(0, _APP_ROOT)
+
+os.chdir(_APP_ROOT)
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from app.runtime_env import apply_runtime_env_defaults
+
+apply_runtime_env_defaults()
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s | %(message)s")
+
+logger = logging.getLogger("prewarm")
+
+
+def main() -> None:
+    from agents.orchestrator import Orchestrator
+
+    logger.info("Constructing Orchestrator (full agent + model load)...")
+    Orchestrator()
+    logger.info("Prewarm finished successfully.")
+
+
+if __name__ == "__main__":
+    main()

scripts/test_engine_direct.py

@@ -0,0 +1,36 @@
+import asyncio
+import os
+import json
+import logging
+import sys
+
+# Add root directory to path to import app and agents
+sys.path.append("/Volumes/WorkSpace/Project/MathSolver/backend")
+
+# Configure logging to stdout
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+from agents.orchestrator import Orchestrator
+
+async def main():
+    orch = Orchestrator()
+    text = "Vẽ tam giác đều cạnh 5."
+    job_id = "test_direct_equilateral"
+    
+    print(f"\n--- Testing Orchestrator Direct: {text} ---")
+    
+    async def status_cb(status):
+        print(f"  [STATUS] {status}")
+        
+    try:
+        result = await orch.run(text, job_id=job_id, status_callback=status_cb, request_video=False)
+        print("\n--- Final Result ---")
+        print(json.dumps(result, indent=2))
+    except Exception as e:
+        print(f"\n--- ERROR ---")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    asyncio.run(main())

setup.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# MathSolver v3.1 Setup Script for macOS
+
+echo "🚀 Starting Environment Setup..."
+
+# 1. System Dependencies (Homebrew)
+if command -v brew >/dev/null 2>&1; then
+    echo "📦 Installing system dependencies via Homebrew..."
+    brew install pango pkg-config glib librsvg
+else
+    echo "⚠️ Homebrew not found. Please install it first: https://brew.sh/"
+    exit 1
+fi
+
+# 2. Python SSL Certificates
+PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')
+CERT_FILE="/Applications/Python ${PYTHON_VERSION}/Install Certificates.command"
+
+if [ -f "$CERT_FILE" ]; then
+    echo "🔐 Installing Python SSL certificates..."
+    sh "$CERT_FILE"
+else
+    echo "ℹ️ SSL certificate installer not found at $CERT_FILE. Skipping..."
+fi
+
+# 3. Virtual Environment
+echo "🐍 Setting up Python Virtual Environment..."
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+
+# 4. Pip packages
+echo "📦 Installing Python packages..."
+pip install --upgrade pip
+pip install -r requirements.txt
+
+# 5. Fix ManimPango (Crucial for macOS arm64)
+echo "🛠️ Rebuilding ManimPango from source to ensure library linking..."
+pip install --no-cache-dir --force-reinstall --no-binary manimpango manimpango
+
+echo "✅ Setup Complete!"
+echo "To start the backend, run: source venv/bin/activate && uvicorn app.main:app --reload"

solver/dsl_parser.py

@@ -0,0 +1,210 @@
+import re
+import logging
+from typing import List, Tuple, Dict, Any
+from .models import Point, Constraint
+
+logger = logging.getLogger(__name__)
+
+
+class DSLParser:
+    def parse(self, text: str) -> Tuple[List[Point], List[Constraint], bool]:
+        """Parse DSL text into points and constraints. Stateless per call."""
+        points: Dict[str, Point] = {}
+        explicit_point_ids: List[str] = []
+        constraints: List[Constraint] = []
+        polygon_order: List[str] = []
+        circles: List[Dict[str, Any]] = []
+        segments: List[List[str]] = []
+        lines_ext: List[List[str]] = []
+        rays: List[List[str]] = []
+        is_3d = False
+
+        logger.info("==[DSLParser] Parsing DSL input==")
+        logger.debug(f"[DSLParser] Raw DSL:\n{text}")
+
+        lines = text.strip().split('\n')
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith('//') or line.startswith('#'):
+                continue
+
+            # POINT(A) or POINT(A, 0, 0, 5)
+            m = re.match(r'POINT\((\w+)(?:,\s*([\d\.-]+),\s*([\d\.-]+)(?:,\s*([\d\.-]+))?)?\)', line)
+            if m:
+                name = m.group(1)
+                x = float(m.group(2)) if m.group(2) else None
+                y = float(m.group(3)) if m.group(3) else None
+                z = float(m.group(4)) if m.group(4) else None
+                if z is not None:
+                    is_3d = True
+                points[name] = Point(id=name, x=x, y=y, z=z)
+                if name not in explicit_point_ids:
+                    explicit_point_ids.append(name)
+                logger.debug(f"[DSLParser]   + POINT: {name} ({x}, {y}, {z})")
+                continue
+
+            # LENGTH(AB, 5)
+            m = re.match(r'LENGTH\((\w+),\s*([\d\.]+)\)', line)
+            if m:
+                target, value = m.group(1), float(m.group(2))
+                pts = [target[i:i+1] for i in range(len(target))]
+                constraints.append(Constraint(type='length', targets=pts, value=value))
+                logger.debug(f"[DSLParser]   + LENGTH: {pts} = {value}")
+                continue
+
+            # ANGLE(A, 90) or ANGLE(A, 90deg)
+            m = re.match(r'ANGLE\((\w+),\s*([\d\.]+)(?:deg)?\)', line)
+            if m:
+                target, value = m.group(1), float(m.group(2))
+                constraints.append(Constraint(type='angle', targets=[target], value=value))
+                logger.debug(f"[DSLParser]   + ANGLE: vertex={target}, degrees={value}")
+                continue
+
+            # PARALLEL(AB, CD)
+            m = re.match(r'PARALLEL\((\w+),\s*(\w+)\)', line)
+            if m:
+                seg1, seg2 = m.group(1), m.group(2)
+                constraints.append(Constraint(type='parallel', targets=list(seg1) + list(seg2), value=0))
+                logger.debug(f"[DSLParser]   + PARALLEL: {seg1} || {seg2}")
+                continue
+
+            # PERPENDICULAR(AB, CD)
+            m = re.match(r'PERPENDICULAR\((\w+),\s*(\w+)\)', line)
+            if m:
+                seg1, seg2 = m.group(1), m.group(2)
+                constraints.append(Constraint(type='perpendicular', targets=list(seg1) + list(seg2), value=0))
+                logger.debug(f"[DSLParser]   + PERPENDICULAR: {seg1} _|_ {seg2}")
+                continue
+
+            # MIDPOINT(M, AB)  — M is midpoint of AB
+            m = re.match(r'MIDPOINT\((\w+),\s*(\w+)\)', line)
+            if m:
+                mid, seg = m.group(1), m.group(2)
+                if mid not in points:
+                    points[mid] = Point(id=mid)
+                pts = [mid] + [seg[i:i+1] for i in range(len(seg))]
+                constraints.append(Constraint(type='midpoint', targets=pts, value=0))
+                logger.debug(f"[DSLParser]   + MIDPOINT: {mid} = mid({seg})")
+                continue
+
+            # SECTION(E, A, C, 0.66)  — E lies on AC s.t. AE = 0.66 * AC
+            m = re.match(r'SECTION\((\w+),\s*(\w+),\s*(\w+),\s*([\d\.-]+)\)', line)
+            if m:
+                target, p1, p2, k = m.group(1), m.group(2), m.group(3), float(m.group(4))
+                if target not in points:
+                    points[target] = Point(id=target)
+                constraints.append(Constraint(type='section', targets=[target, p1, p2], value=k))
+                logger.debug(f"[DSLParser]   + SECTION: {target} = {p1} + {k}({p2}-{p1})")
+                continue
+
+            # CIRCLE(O, r)
+            m = re.match(r'CIRCLE\((\w+),\s*([\d\.]+)\)', line)
+            if m:
+                center, radius = m.group(1), float(m.group(2))
+                if center not in points:
+                    points[center] = Point(id=center)
+                constraints.append(Constraint(type='circle', targets=[center], value=radius))
+                circles.append({"center": center, "radius": radius})
+                logger.debug(f"[DSLParser]   + CIRCLE: center={center}, r={radius}")
+                continue
+
+            # POLYGON_ORDER(A, B, C, D) — thứ tự nối điểm để vẽ đa giác
+            m = re.match(r'POLYGON_ORDER\(([^)]+)\)', line)
+            if m:
+                polygon_order = [p.strip() for p in m.group(1).split(',')]
+                logger.debug(f"[DSLParser]   + POLYGON_ORDER: {polygon_order}")
+                continue
+
+            # SEGMENT(M, N) — đoạn thẳng phụ cần vẽ
+            m = re.match(r'SEGMENT\((\w+),\s*(\w+)\)', line)
+            if m:
+                p1, p2 = m.group(1), m.group(2)
+                segments.append([p1, p2])
+                constraints.append(Constraint(type='segment', targets=[p1, p2], value=0))
+                logger.debug(f"[DSLParser]   + SEGMENT: {p1}—{p2}")
+                continue
+
+            # LINE(A, B) — infinite line
+            m = re.match(r'LINE\((\w+),\s*(\w+)\)', line)
+            if m:
+                p1, p2 = m.group(1), m.group(2)
+                lines_ext.append([p1, p2])
+                constraints.append(Constraint(type='line', targets=[p1, p2], value=0))
+                logger.debug(f"[DSLParser]   + LINE: {p1}-{p2}")
+                continue
+
+            # RAY(A, B) — ray AB starting at A
+            m = re.match(r'RAY\((\w+),\s*(\w+)\)', line)
+            if m:
+                p1, p2 = m.group(1), m.group(2)
+                rays.append([p1, p2])
+                constraints.append(Constraint(type='ray', targets=[p1, p2], value=0))
+                logger.debug(f"[DSLParser]   + RAY: {p1}->{p2}")
+                continue
+
+            # TRIANGLE(ABC) / PYRAMID(S_ABCD) / PRISM(ABC_DEF)
+            m = re.match(r'(TRIANGLE|PYRAMID|PRISM)\(([^)]+)\)', line)
+            if m:
+                pt_type = m.group(1)
+                targets = m.group(2)
+                if pt_type in ["PYRAMID", "PRISM"]:
+                    is_3d = True
+                if pt_type == "TRIANGLE":
+                    if not polygon_order: polygon_order = list(targets)
+                elif pt_type == "PYRAMID":
+                    # S_ABCD -> S is apex, ABCD is base
+                    if "_" in targets:
+                        apex, base = targets.split("_")
+                        # Add segments from apex to all base points
+                        for p in base:
+                            segments.append([apex, p])
+                            constraints.append(Constraint(type='segment', targets=[apex, p], value=0))
+                        if not polygon_order: polygon_order = list(base)
+                elif pt_type == "PRISM":
+                    # ABC_DEF -> two bases
+                    if "_" in targets:
+                        b1, b2 = targets.split("_")
+                        for p1, p2 in zip(b1, b2):
+                            segments.append([p1, p2])
+                            constraints.append(Constraint(type='segment', targets=[p1, p2], value=0))
+                logger.debug(f"[DSLParser]   + {pt_type}: {targets}")
+                continue
+
+            # SPHERE(O, r)
+            m = re.match(r'SPHERE\((\w+),\s*([\d\.]+)\)', line)
+            if m:
+                is_3d = True
+                center, radius = m.group(1), float(m.group(2))
+                if center not in points:
+                    points[center] = Point(id=center)
+                constraints.append(Constraint(type='sphere', targets=[center], value=radius))
+                logger.debug(f"[DSLParser]   + SPHERE: center={center}, r={radius}")
+                continue
+
+            logger.warning(f"[DSLParser]   ? Unrecognized DSL line: '{line}'")
+
+        logger.info(f"[DSLParser] Parsed {len(points)} points, {len(constraints)} constraints.")
+
+        # Safety sweep: Ensure all points referenced in constraints actually exist in the points dictionary
+        for c in constraints:
+            for pid in c.targets:
+                # Some targets might be values or comma-separated strings (handled elsewhere), 
+                # but most are single-character point IDs.
+                if isinstance(pid, str) and len(pid) == 1 and pid not in points:
+                    points[pid] = Point(id=pid)
+                    logger.debug(f"[DSLParser]   ! Auto-declared missing point from constraint: {pid}")
+
+        # Attach metadata to a synthetic constraint for downstream use
+        if polygon_order:
+            constraints.append(Constraint(type='polygon_order', targets=polygon_order, value=0))
+        elif explicit_point_ids:
+            # Re-use polygon_order as a carrier for explicit points IF no real order was specified
+            constraints.append(Constraint(type='explicit_points', targets=explicit_point_ids, value=0))
+
+        # Add auxiliary metadata for lines and rays
+        if lines_ext:
+            constraints.append(Constraint(type='lines_metadata', targets=[",".join(l) for l in lines_ext], value=0))
+        if rays:
+            constraints.append(Constraint(type='rays_metadata', targets=[",".join(l) for l in rays], value=0))
+
+        return list(points.values()), constraints, is_3d

solver/engine.py

@@ -0,0 +1,426 @@
+import sympy as sp
+import numpy as np
+import logging
+import string
+from typing import List, Dict, Any
+from .models import Point, Constraint
+
+logger = logging.getLogger(__name__)
+
+
+class GeometryEngine:
+    def solve(self, points: List[Point], constraints: List[Constraint], is_3d: bool = False) -> Dict[str, Any] | None:
+        if not points:
+            logger.error("[GeometryEngine] No points to solve.")
+            return None
+
+        logger.info(f"==[GeometryEngine] Starting solve with {len(points)} points, {len(constraints)} constraints (is_3d={is_3d})==")
+
+        # ── Separate metadata constraints from real ones ──────────────────────
+        polygon_order: List[str] = []
+        circles_meta: List[Dict] = []
+        segments_meta: List[List[str]] = []
+        real_constraints: List[Constraint] = []
+
+        for c in constraints:
+            if c.type == 'polygon_order':
+                polygon_order = list(c.targets)
+            elif c.type == 'explicit_points' and not polygon_order:
+                polygon_order = list(c.targets)
+            elif c.type == 'circle':
+                circles_meta.append({"center": c.targets[0], "radius": float(c.value)})
+                real_constraints.append(c)
+            elif c.type == 'segment':
+                segments_meta.append(list(c.targets))
+                # don't add to equations — pure drawing annotation
+            elif c.type == 'lines_metadata':
+                lines_meta_list = [t.split(',') for t in c.targets]
+                real_constraints.append(c) # for passing to builder? or just keep here
+            elif c.type == 'rays_metadata':
+                rays_meta_list = [t.split(',') for t in c.targets]
+                real_constraints.append(c)
+            else:
+                real_constraints.append(c)
+
+        # ── Setup symbols ─────────────────────────────────────────────────────
+        point_vars: Dict[str, tuple] = {}
+        equations = []
+
+        # Convert to list for stable indexing and to handle both Dict and List inputs
+        pt_list = list(points.values()) if isinstance(points, dict) else points
+
+        for p in pt_list:
+            x = sp.Symbol(f"{p.id}_x")
+            y = sp.Symbol(f"{p.id}_y")
+            z = sp.Symbol(f"{p.id}_z")
+            point_vars[p.id] = (x, y, z)
+            logger.debug(f"[GeometryEngine]   Symbol: ({p.id}_x, {p.id}_y, {p.id}_z)")
+            
+            # If 2D problem, pin all z to 0 immediately
+            if not is_3d:
+                equations.append(z)
+
+        # ── Anchor logic to fix translation + rotation DOF ────────────────────
+        # Skip anchoring if points already have explicit coordinates that fix DOFs
+        
+        if len(pt_list) > 0:
+            p1 = pt_list[0]
+            # Translation: fix p1 at (0,0) or (0,0,0)
+            if p1.x is None: equations.append(point_vars[p1.id][0]); logger.debug(f"Anchor {p1.id}_x=0")
+            if p1.y is None: equations.append(point_vars[p1.id][1]); logger.debug(f"Anchor {p1.id}_y=0")
+            if is_3d and p1.z is None: 
+                equations.append(point_vars[p1.id][2]); logger.debug(f"Anchor {p1.id}_z=0")
+
+            if len(pt_list) > 1:
+                p2 = pt_list[1]
+                # Rotation: fix p2 on X-axis (y=0)
+                if p2.y is None: equations.append(point_vars[p2.id][1]); logger.debug(f"Anchor {p2.id}_y=0")
+                if is_3d and p2.z is None:
+                    equations.append(point_vars[p2.id][2]); logger.debug(f"Anchor {p2.id}_z=0")
+                
+            if is_3d and len(pt_list) > 2:
+                p3 = pt_list[2]
+                # Planar rotation: fix p3 on XY-plane (z=0)
+                if p3.z is None: equations.append(point_vars[p3.id][2]); logger.debug(f"Anchor {p3.id}_z=0")
+
+        # ── Build equations from explicit point coordinates ──────────────────
+        for p in pt_list:
+            if p.x is not None:
+                equations.append(point_vars[p.id][0] - p.x)
+            if p.y is not None:
+                equations.append(point_vars[p.id][1] - p.y)
+            if p.z is not None:
+                equations.append(point_vars[p.id][2] - p.z)
+
+        # ── Build equations from constraints ──────────────────────────────────
+        for c in real_constraints:
+            logger.debug(f"[GeometryEngine]   Processing constraint: type={c.type}, targets={c.targets}, value={c.value}")
+
+            if c.type == 'length' and len(c.targets) == 2:
+                p1, p2 = c.targets
+                if p1 not in point_vars or p2 not in point_vars:
+                    logger.warning(f"[GeometryEngine]   Skip length: {c.targets} not in symbols.")
+                    continue
+                v1, v2 = point_vars[p1], point_vars[p2]
+                # 3D distance
+                eq = (v2[0]-v1[0])**2 + (v2[1]-v1[1])**2 + (v2[2]-v1[2])**2 - float(c.value)**2
+                equations.append(eq)
+                logger.debug(f"[GeometryEngine]     -> Length eq (3D): |{p1}{p2}|² = {c.value}²")
+
+            elif c.type == 'angle' and len(c.targets) >= 1:
+                # In 3D, 'angle' usually refers to the angle between two vectors (e.g., ∠BAC)
+                v_name = c.targets[0]
+                if v_name not in point_vars:
+                    continue
+                # For simplicity, we assume the next two points in targets or fallback to first 2 others
+                if len(c.targets) >= 3:
+                    p1_name, p2_name = c.targets[1], c.targets[2]
+                else:
+                    other_pts = [p.id for p in pt_list if p.id != v_name][:2]
+                    if len(other_pts) < 2: continue
+                    p1_name, p2_name = other_pts
+                
+                pV = point_vars[v_name]
+                p1_vars = point_vars[p1_name]
+                p2_vars = point_vars[p2_name]
+                
+                # Vectors V1 and V2
+                v1 = [p1_vars[i] - pV[i] for i in range(3)]
+                v2 = [p2_vars[i] - pV[i] for i in range(3)]
+                
+                # Dot product relation: v1.v2 = |v1||v2| cos(theta)
+                # But we use the tangent relation or square it to avoid sqrt if possible
+                # If 90 deg: dot product = 0
+                if abs(float(c.value) - 90.0) < 1e-9:
+                    eq = sum(v1[i]*v2[i] for i in range(3))
+                    logger.debug(f"[GeometryEngine]     -> Angle eq at {v_name} (90° dot=0)")
+                else:
+                    # Generic angle using law of cosines (squared)
+                    cos_val = np.cos(np.deg2rad(float(c.value)))
+                    d1_sq = sum(v1[i]**2 for i in range(3))
+                    d2_sq = sum(v2[i]**2 for i in range(3))
+                    dot = sum(v1[i]*v2[i] for i in range(3))
+                    eq = dot**2 - (cos_val**2) * d1_sq * d2_sq
+                    # Note: this allows theta and 180-theta. 
+                    # Better: dot - cos(theta) * sqrt(d1_sq * d2_sq) = 0, but that has sqrt.
+                    logger.debug(f"[GeometryEngine]     -> Angle eq at {v_name} ({c.value}° cos² relation)")
+                equations.append(eq)
+
+            elif c.type == 'parallel' and len(c.targets) == 4:
+                pA, pB, pC, pD = c.targets
+                if any(t not in point_vars for t in [pA, pB, pC, pD]): continue
+                va, vb, vc, vd = point_vars[pA], point_vars[pB], point_vars[pC], point_vars[pD]
+                # AB || CD means vector(AB) = lambda * vector(CD)
+                # In 3D, cross product = 0. (b-a) x (d-c) = 0
+                v1 = [vb[i]-va[i] for i in range(3)]
+                v2 = [vd[i]-vc[i] for i in range(3)]
+                # Cross product components:
+                equations.append(v1[1]*v2[2] - v1[2]*v2[1])
+                equations.append(v1[2]*v2[0] - v1[0]*v2[2])
+                equations.append(v1[0]*v2[1] - v1[1]*v2[0])
+                logger.debug(f"[GeometryEngine]     -> Parallel eq (3D cross=0): {pA}{pB} || {pC}{pD}")
+
+            elif c.type == 'perpendicular' and len(c.targets) == 4:
+                pA, pB, pC, pD = c.targets
+                if any(t not in point_vars for t in [pA, pB, pC, pD]): continue
+                va, vb, vc, vd = point_vars[pA], point_vars[pB], point_vars[pC], point_vars[pD]
+                # Dot product = 0
+                dot = sum((vb[i]-va[i])*(vd[i]-vc[i]) for i in range(3))
+                equations.append(dot)
+                logger.debug(f"[GeometryEngine]     -> Perpendicular eq (3D dot=0): {pA}{pB} ⊥ {pC}{pD}")
+
+            elif c.type == 'midpoint' and len(c.targets) == 3:
+                pM, pA, pB = c.targets
+                if any(t not in point_vars for t in [pM, pA, pB]): continue
+                vM, vA, vB = point_vars[pM], point_vars[pA], point_vars[pB]
+                for i in range(3):
+                    equations.append(2*vM[i] - vA[i] - vB[i])
+                logger.debug(f"[GeometryEngine]     -> Midpoint eq (3D): {pM} = mid({pA},{pB})")
+
+            elif c.type == 'section' and len(c.targets) == 3:
+                pE, pA, pC = c.targets
+                if any(t not in point_vars for t in [pE, pA, pC]): continue
+                vE, vA, vC = point_vars[pE], point_vars[pA], point_vars[pC]
+                k = float(c.value)
+                for i in range(3):
+                    equations.append(vE[i] - (vA[i] + k * (vC[i] - vA[i])))
+                logger.debug(f"[GeometryEngine]     -> Section eq (3D): {pE} = {pA} + {k}({pC}-{pA})")
+
+            elif c.type == 'circle':
+                # Circle doesn't add position constraints for center (already a point)
+                logger.debug(f"[GeometryEngine]     -> Circle: center={c.targets[0]}, r={c.value} (meta only)")
+
+        all_vars = []
+        for v in point_vars.values():
+            all_vars.extend(v)
+
+        n_eqs = len(equations)
+        n_vars = len(all_vars)
+        logger.info(f"[GeometryEngine] Built {n_eqs} equations for {n_vars} unknowns.")
+
+        # ── Strategy 1: SymPy symbolic ───────────────────────────────────────
+        coords = self._try_symbolic(equations, all_vars, point_vars)
+        
+        # Extract lines/rays from constraints for builder
+        lines_ext = []
+        rays_ext = []
+        for c in constraints:
+            if c.type == 'lines_metadata':
+                lines_ext = [t.split(',') for t in c.targets]
+            if c.type == 'rays_metadata':
+                rays_ext = [t.split(',') for t in c.targets]
+
+        if coords:
+            return self._build_result(coords, polygon_order, circles_meta, segments_meta, lines_ext, rays_ext, pt_list)
+
+        # ── Strategy 2: Numerical nsolve ─────────────────────────────────────
+        if n_eqs == n_vars:
+            coords = self._try_nsolve(equations, all_vars, point_vars, n_vars)
+            if coords:
+                return self._build_result(coords, polygon_order, circles_meta, segments_meta, lines_ext, rays_ext, pt_list)
+
+        # ── Strategy 3: Scipy least-squares ─────────────────────────────────
+        coords = self._try_lsq(equations, all_vars, point_vars, n_vars)
+        if coords:
+            return self._build_result(coords, polygon_order, circles_meta, segments_meta, lines_ext, rays_ext, pt_list)
+
+        # ── Strategy 4: Differential evolution ──────────────────────────────
+        coords = self._try_global(equations, all_vars, point_vars, n_vars)
+        if coords:
+            return self._build_result(coords, polygon_order, circles_meta, segments_meta, lines_ext, rays_ext, pt_list)
+
+        logger.error("[GeometryEngine] All strategies exhausted.")
+        return None
+
+    # ─── Solving strategies ──────────────────────────────────────────────────
+
+    def _try_symbolic(self, equations, all_vars, point_vars):
+        # Optimization: SymPy's symbolic solver becomes extremely slow for many variables.
+        # For 3D problems (usually 12-18+ variables), we prefer using numerical methods directly.
+        if len(all_vars) > 10:
+            logger.info(f"[GeometryEngine] Strategy 1: Skipping symbolic solve due to high variable count ({len(all_vars)}).")
+            return None
+
+        try:
+            solution = sp.solve(equations, all_vars, dict=True)
+            if solution:
+                res = solution[0]
+                logger.info("[GeometryEngine] Strategy 1 (SymPy symbolic): SUCCESS.")
+                logger.debug(f"[GeometryEngine] Symbolic solution: {res}")
+                return {pid: [float(res.get(vx, 0.0)), float(res.get(vy, 0.0)), float(res.get(vz, 0.0))]
+                        for pid, (vx, vy, vz) in point_vars.items()}
+            else:
+                logger.warning("[GeometryEngine] Strategy 1 returned no solution. Trying numerical...")
+        except Exception as e:
+            logger.warning(f"[GeometryEngine] Strategy 1 threw exception: {e}. Trying numerical...")
+        return None
+
+    def _try_nsolve(self, equations, all_vars, point_vars, n_vars):
+        MAX_NSOLVE_ATTEMPTS = 15
+        logger.info(f"[GeometryEngine] Strategy 2 (nsolve): square system ({n_vars}x{n_vars}). Trying {MAX_NSOLVE_ATTEMPTS} random starts...")
+        import random
+        for attempt in range(MAX_NSOLVE_ATTEMPTS):
+            try:
+                # Use varying scales for the random guesses to handle different problem sizes
+                scale = 10 if attempt < 5 else (100 if attempt < 10 else 1)
+                guesses = [random.uniform(-scale, scale) for _ in all_vars]
+                sol_vals = sp.nsolve(equations, all_vars, guesses, tol=1e-6, maxsteps=1000)
+                res = {var: float(val) for var, val in zip(all_vars, sol_vals)}
+                logger.info(f"[GeometryEngine] Strategy 2 (nsolve): SUCCESS on attempt {attempt + 1}.")
+                return {pid: [float(res.get(vx, 0.0)), float(res.get(vy, 0.0)), float(res.get(vz, 0.0))]
+                        for pid, (vx, vy, vz) in point_vars.items()}
+            except Exception as e:
+                logger.debug(f"[GeometryEngine]   nsolve attempt {attempt + 1} failed: {e}")
+        return None
+
+    def _try_lsq(self, equations, all_vars, point_vars, n_vars):
+        logger.info("[GeometryEngine] Strategy 3 (scipy least-squares): minimizing residuals...")
+        try:
+            from scipy.optimize import minimize
+            eq_funcs = [sp.lambdify(all_vars, eq, 'numpy') for eq in equations]
+
+            def objective(x):
+                return sum(float(f(*x))**2 for f in eq_funcs)
+
+            best_res, best_val = None, float('inf')
+            # Increase restarts for better coverage of local minima
+            for i in range(12):
+                if i == 0:
+                    x0 = [1.0]*n_vars
+                elif i < 4:
+                    x0 = [np.random.uniform(-10, 10) for _ in range(n_vars)]
+                else:
+                    x0 = [np.random.uniform(-100, 100) for _ in range(n_vars)]
+                
+                res = minimize(objective, x0, method='L-BFGS-B')
+                if res.fun < best_val:
+                    best_val, best_res = res.fun, res
+                if best_val < 1e-6:
+                    break
+
+            TOLERANCE = 1e-4
+            logger.info(f"[GeometryEngine] Strategy 3: best residual = {best_val:.2e} (tol={TOLERANCE})")
+            if best_val < TOLERANCE:
+                res = {var: float(val) for var, val in zip(all_vars, best_res.x)}
+                logger.info("[GeometryEngine] Strategy 3 (least-squares): SUCCESS.")
+                return {pid: [float(res.get(vx, 0)), float(res.get(vy, 0)), float(res.get(vz, 0))]
+                        for pid, (vx, vy, vz) in point_vars.items()}
+            else:
+                logger.warning(f"[GeometryEngine] Strategy 3 failed: residual {best_val:.2e} > {TOLERANCE}")
+        except Exception as e:
+            logger.error(f"[GeometryEngine] Strategy 3 threw exception: {e}")
+        return None
+
+    def _try_global(self, equations, all_vars, point_vars, n_vars):
+        logger.info("[GeometryEngine] Strategy 4 (Differential Evolution): global search...")
+        try:
+            from scipy.optimize import differential_evolution
+            bounds = [(-20, 20)] * n_vars
+            eq_funcs = [sp.lambdify(all_vars, eq, 'numpy') for eq in equations]
+
+            def obj(x):
+                s = 0.0
+                for f in eq_funcs:
+                    try:
+                        s += float(f(*x))**2
+                    except:
+                        s += 1e6
+                return s
+
+            result = differential_evolution(obj, bounds, maxiter=500, popsize=15, mutation=(0.5, 1), recombination=0.7)
+            TOLERANCE = 1e-3
+            logger.info(f"[GeometryEngine] Strategy 4: best residual = {result.fun:.2e} (tol={TOLERANCE})")
+            if result.fun < TOLERANCE:
+                res = {var: float(val) for var, val in zip(all_vars, result.x)}
+                logger.info("[GeometryEngine] Strategy 4 (global opt): SUCCESS.")
+                return {pid: [float(res.get(vx, 0)), float(res.get(vy, 0)), float(res.get(vz, 0))]
+                        for pid, (vx, vy, vz) in point_vars.items()}
+        except Exception as e:
+            logger.error(f"[GeometryEngine] Strategy 4 threw exception: {e}")
+        return None
+
+    # ─── Result builder ──────────────────────────────────────────────────────
+
+    def _build_result(
+        self,
+        coords: Dict[str, List[float]],
+        polygon_order: List[str],
+        circles_meta: List[Dict],
+        segments_meta: List[List[str]],
+        lines_meta: List[List[str]],
+        rays_meta: List[List[str]],
+        pt_list: List[Point],
+    ) -> Dict[str, Any]:
+        """
+        Build structured result including drawing phases for the renderer.
+
+        drawing_phases:
+          Phase 1 — Base shape (main polygon)
+          Phase 2 — Auxiliary/derived points and segments
+        """
+        all_ids = [p.id for p in pt_list]
+
+        # 1. Infer/clean polygon_order
+        if not polygon_order:
+            # Fallback: use all declared point IDs sorted by conventional uppercase order.
+            # This is far safer than only looking for A/B/C/D.
+            base_pts = sorted(
+                all_ids,
+                key=lambda p: (string.ascii_uppercase.index(p) if p in string.ascii_uppercase else 100, p)
+            )
+            polygon_order = base_pts
+
+        base_ids = [pid for pid in polygon_order if pid in all_ids]
+        derived_ids = [pid for pid in all_ids if pid not in polygon_order]
+
+        # 2. Collect unique segments to avoid redundancy (AB == BA)
+        drawn_segments = set()
+
+        def add_segment(p1, p2, target_list):
+            if p1 == p2:
+                return
+            s = frozenset([p1, p2])
+            if s not in drawn_segments:
+                drawn_segments.add(s)
+                target_list.append([p1, p2])
+
+        # Phase 1: Main polygon boundary
+        phase1_segments = []
+        if len(base_ids) >= 2:
+            # Connect in sequence: A-B, B-C, etc.
+            for i in range(len(base_ids) - 1):
+                add_segment(base_ids[i], base_ids[i+1], phase1_segments)
+            
+            # ONLY close the loop if we have 3 or more points (a real polygon)
+            if len(base_ids) > 2:
+                add_segment(base_ids[-1], base_ids[0], phase1_segments)
+
+        # Phase 2: Auxiliary segments from DSL
+        phase2_segments = []
+        for p1, p2 in segments_meta:
+            add_segment(p1, p2, phase2_segments)
+
+        drawing_phases = [
+            {
+                "phase": 1,
+                "label": "Hình cơ bản",
+                "points": base_ids,
+                "segments": phase1_segments,
+            }
+        ]
+        if derived_ids or phase2_segments:
+            drawing_phases.append({
+                "phase": 2,
+                "label": "Điểm và đoạn phụ",
+                "points": derived_ids,
+                "segments": phase2_segments,
+            })
+
+        return {
+            "coordinates": coords,
+            "polygon_order": polygon_order,
+            "circles": circles_meta,
+            "lines": lines_meta,
+            "rays": rays_meta,
+            "drawing_phases": drawing_phases,
+        }

solver/models.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+from typing import List, Dict, Union, Optional
+
+class Point(BaseModel):
+    id: str
+    x: Optional[float] = None
+    y: Optional[float] = None
+    z: Optional[float] = None
+
+class Constraint(BaseModel):
+    type: str # 'length', 'angle', 'parallel', etc.
+    targets: List[str]
+    value: Union[float, str]

tests/test_3d_solver.py

@@ -0,0 +1,85 @@
+import pytest
+from solver.dsl_parser import DSLParser
+from solver.engine import GeometryEngine
+from solver.models import Point, Constraint
+
+def test_solve_square_pyramid():
+    """
+    Test solving for a square pyramid S.ABCD.
+    Base ABCD is a square with side 10.
+    Height SO = 15, where O is the center of ABCD.
+    """
+    dsl = """
+    POINT(A, 0, 0, 0)
+    POINT(B, 10, 0, 0)
+    POINT(C, 10, 10, 0)
+    POINT(D, 0, 10, 0)
+    POINT(S)
+    POINT(O)
+    MIDPOINT(M1, AB)
+    MIDPOINT(M2, AC)
+    SECTION(O, A, C, 0.5)
+    LENGTH(SO, 15)
+    PERPENDICULAR(SO, AC)
+    PERPENDICULAR(SO, AB)
+    PYRAMID(S_ABCD)
+    """
+    parser = DSLParser()
+    engine = GeometryEngine()
+    
+    points, constraints = parser.parse(dsl)
+    result = engine.solve(points, constraints)
+    
+    assert result is not None
+    coords = result["coordinates"]
+    
+    # Check base points
+    assert coords["A"] == [0.0, 0.0, 0.0]
+    assert coords["B"] == [10.0, 0.0, 0.0]
+    assert coords["C"] == [10.0, 10.0, 0.0]
+    assert coords["D"] == [0.0, 10.0, 0.0]
+    
+    # Check center O (should be (5, 5, 0))
+    assert coords["O"][0] == pytest.approx(5.0)
+    assert coords["O"][1] == pytest.approx(5.0)
+    assert coords["O"][2] == pytest.approx(0.0)
+    
+    # Check apex S (should be (5, 5, 15) or (5, 5, -15))
+    assert coords["S"][0] == pytest.approx(5.0)
+    assert coords["S"][1] == pytest.approx(5.0)
+    assert abs(coords["S"][2]) == pytest.approx(15.0)
+
+def test_solve_prism():
+    """
+    Triangular prism ABC_DEF.
+    Base ABC is right triangle at A. AB=3, AC=4.
+    Height AD=10.
+    """
+    dsl = """
+    POINT(A, 0, 0, 0)
+    POINT(B, 3, 0, 0)
+    POINT(C, 0, 4, 0)
+    POINT(D)
+    POINT(E)
+    POINT(F)
+    LENGTH(AD, 10)
+    PERPENDICULAR(AD, AB)
+    PERPENDICULAR(AD, AC)
+    PRISM(ABC_DEF)
+    """
+    parser = DSLParser()
+    engine = GeometryEngine()
+    
+    points, constraints = parser.parse(dsl)
+    result = engine.solve(points, constraints)
+    
+    assert result is not None
+    coords = result["coordinates"]
+    
+    # D should be (0, 0, 10)
+    assert coords["D"][0] == pytest.approx(0.0)
+    assert coords["D"][1] == pytest.approx(0.0)
+    assert abs(coords["D"][2]) == pytest.approx(10.0)
+
+if __name__ == "__main__":
+    pytest.main([__file__])

tests/test_advanced_geometry.py

@@ -0,0 +1,102 @@
+import pytest
+import asyncio
+import logging
+from solver.dsl_parser import DSLParser
+from solver.engine import GeometryEngine
+
+logging.basicConfig(level=logging.DEBUG)
+
+@pytest.mark.asyncio
+async def test_section_internal():
+    print("\n--- Test: Section Point (Internal AE=2/3 AC) ---")
+    dsl = """
+    POINT(A)
+    POINT(B)
+    POINT(C)
+    LENGTH(AB, 6)
+    LENGTH(BC, 6)
+    ANGLE(B, 90)
+    SECTION(E, A, C, 0.6667)
+    """
+    parser = DSLParser()
+    engine = GeometryEngine()
+    
+    pts, constraints = parser.parse(dsl)
+    result = engine.solve(pts, constraints)
+    
+    if result:
+        coords = result['coordinates']
+        print(f"  A: {coords['A']}")
+        print(f"  C: {coords['C']}")
+        print(f"  E: {coords['E']}")
+        
+        # Verify AE = 0.6667 * AC
+        import math
+        def dist(p1, p2): return math.sqrt((p1[0]-p2[0])**2 + (p1[1]-p2[1])**2)
+        
+        d_ac = dist(coords['A'], coords['C'])
+        d_ae = dist(coords['A'], coords['E'])
+        ratio = d_ae / d_ac
+        print(f"  Calculated Ratio AE/AC: {ratio:.4f} (Expected: 0.6667)")
+        assert abs(ratio - 0.6667) < 1e-4
+    else:
+        print("  ❌ Solve failed")
+
+@pytest.mark.asyncio
+async def test_section_external():
+    print("\n--- Test: Section Point (External AE=2*AC) ---")
+    dsl = """
+    POINT(A)
+    POINT(C)
+    LENGTH(AC, 5)
+    SECTION(E, A, C, 2.0)
+    """
+    parser = DSLParser()
+    engine = GeometryEngine()
+    
+    pts, constraints = parser.parse(dsl)
+    result = engine.solve(pts, constraints)
+    
+    if result:
+        coords = result['coordinates']
+        print(f"  A: {coords['A']}")
+        print(f"  C: {coords['C']}")
+        print(f"  E: {coords['E']}")
+        
+        import math
+        def dist(p1, p2): return math.sqrt((p1[0]-p2[0])**2 + (p1[1]-p2[1])**2)
+        d_ac = dist(coords['A'], coords['C'])
+        d_ae = dist(coords['A'], coords['E'])
+        print(f"  AE: {d_ae}, AC: {d_ac}, Ratio: {d_ae/d_ac}")
+        assert abs(d_ae/d_ac - 2.0) < 1e-4
+    else:
+        print("  ❌ Solve failed")
+
+@pytest.mark.asyncio
+async def test_line_ray_metadata():
+    print("\n--- Test: Line and Ray Metadata ---")
+    dsl = """
+    POINT(A)
+    POINT(B)
+    LINE(A, B)
+    RAY(A, B)
+    """
+    parser = DSLParser()
+    engine = GeometryEngine()
+    
+    pts, constraints = parser.parse(dsl)
+    result = engine.solve(pts, constraints)
+    
+    if result:
+        print(f"  Lines: {result.get('lines')}")
+        print(f"  Rays: {result.get('rays')}")
+        assert ['A', 'B'] in result.get('lines', [])
+        assert ['A', 'B'] in result.get('rays', [])
+        print("  ✅ Metadata present")
+    else:
+        print("  ❌ Solve failed")
+
+if __name__ == "__main__":
+    asyncio.run(test_section_internal())
+    asyncio.run(test_section_external())
+    asyncio.run(test_line_ray_metadata())

tests/test_api_full_suite.py

@@ -0,0 +1,237 @@
+import os
+import httpx
+import time
+import asyncio
+import pytest
+import logging
+import json
+
+# Configuration
+BASE_URL = os.getenv("TEST_BASE_URL", "http://localhost:8000")
+USER_ID = os.getenv("TEST_USER_ID")
+SESSION_ID = os.getenv("TEST_SESSION_ID")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+QUERIES = [
+    {
+        "id": "Q1",
+        "text": "Cho hình chữ nhật ABCD có AB bằng 5 và AD bằng 10",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q2",
+        "text": "Tam giác ABC có AB=6, BC=8, AC=10",
+        "expect_pts": ["A", "B", "C"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q3",
+        "text": "Cho hình chữ nhật ABCD có AB bằng 10 và AD bằng 20. Vẽ điểm M là trung điểm của AB và N là trung điểm của AD.",
+        "expect_pts": ["A", "B", "C", "D", "M", "N"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q4",
+        "text": "Cho hình thang ABCD vuông tại A và D. AB=4, CD=8, AD=5.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q5",
+        "text": "Cho hình vuông ABCD có cạnh bằng 6.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q6",
+        "text": "Cho tam giác ABC vuông tại A. AB=3, AC=4. Vẽ đường cao AH.",
+        "expect_pts": ["A", "B", "C", "H"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q7",
+        "text": "Cho hình thoi ABCD có cạnh bằng 5 và góc A bằng 60 độ.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q8",
+        "text": "Cho đường tròn tâm O bán kính bằng 7.",
+        "expect_pts": ["O"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q9",
+        "text": "Cho hình bình hành ABCD có AB=8, AD=6. Gọi E là trung điểm của CD. Vẽ đoạn thẳng AE.",
+        "expect_pts": ["A", "B", "C", "D", "E"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q10-Step1",
+        "text": "Cho hình chữ nhật ABCD có AB=10, AD=5.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q11-Video",
+        "text": "Cho tam giác ABC đều cạnh 5. Vẽ đường tròn ngoại tiếp tam giác.",
+        "expect_pts": ["A", "B", "C"],
+        "expect_phases": 2,
+        "request_video": True
+    },
+    {
+        "id": "Q12-3D",
+        "text": "Cho hình chóp S.ABCD có đáy ABCD là hình vuông cạnh 10, đường cao SO=15 với O là tâm đáy.",
+        "expect_pts": ["S", "A", "B", "C", "D", "O"],
+        "expect_phases": 2,
+    }
+]
+
+Q10_FOLLOW_UP = {
+    "id": "Q10-Step2",
+    "text": "Vẽ thêm đường chéo AC.", 
+    "expect_pts": ["A", "B", "C", "D"],
+    "expect_phases": 2,
+}
+
+test_stats = []
+
+async def run_single_api_query(client, q, headers):
+    print(f"\n🚀 [RUNNING] {q['id']}: {q['text']}")
+    start_time = time.time()
+    
+    # 1. Submit Request
+    payload = {
+        "text": q["text"],
+        "request_video": q.get("request_video", False)
+    }
+    
+    try:
+        if q.get("isolate", True):
+            # Create a fresh session for isolation
+            session_resp = await client.post("/api/v1/sessions", headers=headers)
+            if session_resp.status_code != 200:
+                return {"id": q["id"], "query": q["text"], "success": False, "error": f"Session creation failed: {session_resp.text}"}
+            session_id = session_resp.json()["id"]
+        else:
+            session_id = q.get("session_id", SESSION_ID)
+
+        res = await client.post(f"/api/v1/sessions/{session_id}/solve", json=payload, headers=headers)
+        if res.status_code != 200:
+            print(f"   ❌ FAILED: Status {res.status_code} - {res.text}")
+            return {"id": q["id"], "query": q["text"], "success": False, "error": f"HTTP {res.status_code}: {res.text}"}
+        
+        job_id = res.json()["job_id"]
+        print(f"   ✅ Job Created: {job_id}")
+
+        # 2. Polling result
+        max_attempts = 45 # Increased for video rendering
+        result_data = None
+        for i in range(max_attempts):
+            await asyncio.sleep(4)
+            res = await client.get(f"/api/v1/solve/{job_id}", headers=headers)
+            data = res.json()
+            status = data.get("status")
+            print(f"      - Polling ({i+1}): {status}")
+            
+            if status == "success":
+                result_data = data["result"]
+                break
+            if status == "error":
+                print(f"   ❌ ERROR: {data.get('result', {}).get('error')}")
+                return {"id": q["id"], "query": q["text"], "success": False, "error": data.get("result", {}).get("error")}
+            
+            if i == max_attempts - 1:
+                print("   ❌ TIMEOUT")
+                return {"id": q["id"], "query": q["text"], "success": False, "error": "Timeout"}
+
+        # 3. Strict Validation
+        elapsed = time.time() - start_time
+        errors = []
+        
+        # Validation: Coordinates
+        coords = result_data.get("coordinates", {})
+        for pt in q["expect_pts"]:
+            if pt not in coords:
+                errors.append(f"Missing point {pt}")
+        
+        # Validation: Non-zero coords (generic check)
+        # Only fail if there are MULTIPLE points and all are at origin. 
+        # A single point (like a circle center) at origin is perfectly valid.
+        if coords and len(coords) > 1 and all(v == [0,0,0] for v in coords.values()):
+            errors.append("All points are at [0,0,0]")
+
+        # Validation: Drawing Phases
+        phases = result_data.get("drawing_phases", [])
+        if len(phases) < q["expect_phases"]:
+            errors.append(f"Expected {q['expect_phases']} phases, got {len(phases)}")
+
+        # Validation: Video URL if requested
+        if q.get("request_video") and not result_data.get("video_url"):
+            # We allow video fail if it's environment issue, but log it
+            print("      ⚠️ Video requested but no URL found (Expected in some test envs)")
+            # errors.append("Video URL missing")
+
+        if errors:
+            print(f"   ❌ VALIDATION FAILED: {', '.join(errors)}")
+            return {"id": q["id"], "query": q["text"], "success": False, "error": "; ".join(errors), "elapsed": elapsed, "result": result_data}
+        
+        print(f"   ✅ PASS ({elapsed:.2f}s)")
+        return {"id": q['id'], "query": q["text"], "success": True, "elapsed": elapsed, "job_id": job_id, "result": result_data}
+
+    except Exception as e:
+        print(f"   ❌ EXCEPTION: {str(e)}")
+        return {"id": q["id"], "query": q["text"], "success": False, "error": str(e)}
+
+@pytest.mark.asyncio
+async def test_full_api_suite():
+    if not USER_ID or not SESSION_ID:
+        pytest.fail("TEST_USER_ID and TEST_SESSION_ID must be set")
+
+    headers = {"Authorization": f"Test {USER_ID}"}
+    
+    async with httpx.AsyncClient(base_url=BASE_URL, timeout=60.0) as client:
+        # Run standard queries
+        import uuid
+        for q in QUERIES:
+            if q["id"] == "Q10-Step1": continue
+            # Isolated by default
+            res = await run_single_api_query(client, q, headers)
+            test_stats.append(res)
+
+        # Run Multi-turn Q10
+        print("\n--- Testing Multi-turn API Flow (Q10) ---")
+        # Create a shared session for Q10
+        shared_session_resp = await client.post("/api/v1/sessions", headers=headers)
+        shared_session = shared_session_resp.json()["id"]
+        
+        q10_1 = next(q for q in QUERIES if q["id"] == "Q10-Step1")
+        q10_1["session_id"] = shared_session
+        q10_1["isolate"] = False
+        res10_1 = await run_single_api_query(client, q10_1, headers)
+        test_stats.append(res10_1)
+
+        if res10_1["success"]:
+            Q10_FOLLOW_UP["session_id"] = shared_session
+            Q10_FOLLOW_UP["isolate"] = False
+            res10_2 = await run_single_api_query(client, Q10_FOLLOW_UP, headers)
+            
+            # Additional check for Q10-Step2: check if DSL contains combined logic
+            if res10_2["success"]:
+                dsl = res10_2["result"].get("geometry_dsl", "")
+                if "POLYGON_ORDER" not in dsl or "SEGMENT" not in dsl:
+                    res10_2["success"] = False
+                    res10_2["error"] = "DSL did not merge history correctly"
+            
+            test_stats.append(res10_2)
+
+    # Save Results to JSON for the runner script to generate Markdown
+    with open("temp_suite_results.json", "w") as f:
+        json.dump(test_stats, f)
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(test_full_api_suite())

tests/test_api_metadata_real.py

@@ -0,0 +1,56 @@
+import pytest
+import asyncio
+import uuid
+import time
+from app.routers.solve import process_session_job
+from app.models.schemas import SolveRequest
+from app.supabase_client import get_supabase
+
+@pytest.mark.asyncio
+async def test_metadata_persistence():
+    session_id = "81f87517-88f2-40bd-96a9-7b34f1d14b6a"
+    user_id = "8cd3adb0-7964-4575-949c-d0cadcd8b679"
+    job_id = str(uuid.uuid4())
+    
+    print(f"🚀 Starting sub-pipeline test for job {job_id}...")
+    
+    request = SolveRequest(
+        text="Cho hình chữ nhật ABCD có AB=10, AD=20. Vẽ đường thẳng d đi qua A và B.",
+        request_video=False
+    )
+    
+    # Trigger the process_session_job directly
+    await process_session_job(job_id, session_id, request, user_id)
+    
+    print("⏳ Waiting for database sync (3s)...")
+    await asyncio.sleep(3)
+    
+    # Verify the results in Supabase
+    supabase = get_supabase()
+    res = supabase.table("messages") \
+        .select("metadata, created_at") \
+        .eq("session_id", session_id) \
+        .eq("role", "assistant") \
+        .order("created_at", desc=True) \
+        .limit(1) \
+        .execute()
+    
+    if not res.data:
+        print("❌ FAIL: No assistant message found in database.")
+        return
+    
+    metadata = res.data[0].get("metadata", {})
+    required_fields = ["job_id", "coordinates", "polygon_order", "drawing_phases", "circles", "lines", "rays"]
+    missing = [f for f in required_fields if f not in metadata]
+    
+    if not missing:
+        print("✅ SUCCESS: All metadata fields (including lines/rays) persisted correctly.")
+        print(f"   job_id: {metadata.get('job_id')}")
+        print(f"   polygon_order: {metadata.get('polygon_order')}")
+        print(f"   lines: {metadata.get('lines')}")
+        print(f"   phases: {len(metadata.get('drawing_phases', []))}")
+    else:
+        print(f"❌ FAIL: Missing fields in metadata: {missing}")
+
+if __name__ == "__main__":
+    asyncio.run(test_metadata_persistence())

tests/test_api_real_e2e.py

@@ -0,0 +1,75 @@
+import os
+import httpx
+import time
+import pytest
+import logging
+
+# Configuration from environment
+BASE_URL = os.getenv("TEST_BASE_URL", "http://localhost:8000")
+USER_ID = os.getenv("TEST_USER_ID")
+SESSION_ID = os.getenv("TEST_SESSION_ID")
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+@pytest.mark.asyncio
+async def test_api_e2e_flow():
+    if not USER_ID or not SESSION_ID:
+        pytest.fail("TEST_USER_ID and TEST_SESSION_ID must be set")
+
+    auth_headers = {"Authorization": f"Test {USER_ID}"}
+    
+    async with httpx.AsyncClient(base_url=BASE_URL, timeout=30.0) as client:
+        # 1. Health check
+        print("\n[1/3] Checking API Health...")
+        res = await client.get("/")
+        assert res.status_code == 200
+        assert "running" in res.json()["message"].lower()
+        print("   ✅ Health check passed")
+
+        # 2. Submit Solve Request
+        print(f"\n[2/3] Submitting solve request for session {SESSION_ID}...")
+        payload = {
+            "text": "Cho hình chữ nhật ABCD có AB=5, AD=10. Tính diện tích.",
+            "request_video": False
+        }
+        res = await client.post(f"/api/v1/sessions/{SESSION_ID}/solve", json=payload, headers=auth_headers)
+        
+        if res.status_code != 200:
+            print(f"   ❌ FAILED: {res.text}")
+            assert res.status_code == 200
+            
+        data = res.json()
+        job_id = data["job_id"]
+        assert job_id is not None
+        print(f"   ✅ Request accepted. Job ID: {job_id}")
+
+        # 3. Polling Job Status
+        print("\n[3/3] Polling job status...")
+        max_attempts = 15
+        for i in range(max_attempts):
+            time.sleep(2) # Simple sleep between polls
+            res = await client.get(f"/api/v1/solve/{job_id}")
+            assert res.status_code == 200
+            job_data = res.json()
+            status = job_data["status"]
+            print(f"   Attempt {i+1}: Status = {status}")
+            
+            if status == "success":
+                print("   ✅ SUCCESS: API pipeline completed successfully.")
+                result = job_data.get("result", {})
+                assert "coordinates" in result
+                assert "geometry_dsl" in result
+                return
+            
+            if status == "error":
+                error_msg = job_data.get("result", {}).get("error", "Unknown error")
+                pytest.fail(f"Job failed with error: {error_msg}")
+            
+            if i == max_attempts - 1:
+                pytest.fail("Timeout waiting for job completion")
+
+if __name__ == "__main__":
+    # This allows running the script directly if needed
+    import asyncio
+    asyncio.run(test_api_e2e_flow())

tests/test_direct_task.py

@@ -0,0 +1,70 @@
+import os
+import sys
+import json
+from dotenv import load_dotenv
+
+# Ensure we can import from backend
+sys.path.append(os.getcwd())
+
+from app.supabase_client import get_supabase
+from worker.tasks import render_geometry_video
+
+def test_celery_task_directly():
+    load_dotenv()
+    
+    # Mock data for a square
+    data = {
+        "session_id": "88888888-8888-8888-8888-888888888888", # Fake uuid
+        "coordinates": {
+            "A": [0, 0],
+            "B": [5, 0],
+            "C": [5, 5],
+            "D": [0, 5]
+        },
+        "polygon_order": ["A", "B", "C", "D"],
+        "drawing_phases": [
+            {
+                "phase": 1,
+                "label": "Base",
+                "points": ["A", "B", "C", "D"],
+                "segments": [["A","B"],["B","C"],["C","D"],["D","A"]]
+            }
+        ],
+        "semantic_analysis": "Test squere video rendering."
+    }
+    
+    job_id = f"manual-direct-test-{int(os.time.time()) if hasattr(os, 'time') else 123}"
+    # Just use a static ID or similar
+    import time
+    job_id = f"manual-test-{int(time.time())}"
+
+    print(f"🚀 Running render_geometry_video directly for job {job_id}...")
+    
+    try:
+        # We need to mock Supabase calls if we don't want to actually hit the DB,
+        # but here we WANT to test the real task logic.
+        # This will fail on DB update if job_id doesn't exist in 'jobs' table.
+        # So let's create a dummy job first.
+        supabase = get_supabase()
+        supabase.table("jobs").insert({
+            "id": job_id,
+            "user_id": None,
+            "status": "processing",
+            "type": "solve"
+        }).execute()
+        
+        # Run the task function directly (not via .delay)
+        video_url = render_geometry_video(job_id, data)
+        
+        if video_url:
+            print(f"✅ SUCCESS! Video URL: {video_url}")
+        else:
+            print("❌ FAIL: No video URL returned.")
+            
+    except NameError as e:
+        print(f"❌ NameError Caught: {e}")
+    except Exception as e:
+        print(f"❌ Error during manual task execution: {e}")
+
+if __name__ == "__main__":
+    test_celery_task_directly()

tests/test_full_pipeline.py

@@ -0,0 +1,237 @@
+import asyncio
+import logging
+import json
+import os
+import math
+import time
+from dotenv import load_dotenv
+
+from app.logging_setup import setup_application_logging
+setup_application_logging()
+logging.getLogger("agents").setLevel(logging.DEBUG)
+logging.getLogger("solver").setLevel(logging.DEBUG)
+logging.getLogger("app").setLevel(logging.DEBUG)
+
+from agents.orchestrator import Orchestrator
+from app.supabase_client import get_supabase
+
+QUERIES = [
+    {
+        "id": "Q1",
+        "text": "Cho hình chữ nhật ABCD có AB bằng 5 và AD bằng 10",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q2",
+        "text": "Tam giác ABC có AB=6, BC=8, AC=10",
+        "expect_pts": ["A", "B", "C"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q3",
+        "text": "Cho hình chữ nhật ABCD có AB bằng 10 và AD bằng 20. Vẽ điểm M là trung điểm của AB và N là trung điểm của AD.",
+        "expect_pts": ["A", "B", "C", "D", "M", "N"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q4",
+        "text": "Cho hình thang ABCD vuông tại A và D. AB=4, CD=8, AD=5.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q5",
+        "text": "Cho hình vuông ABCD có cạnh bằng 6.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q6",
+        "text": "Cho tam giác ABC vuông tại A. AB=3, AC=4. Vẽ đường cao AH.",
+        "expect_pts": ["A", "B", "C", "H"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q7",
+        "text": "Cho hình thoi ABCD có cạnh bằng 5 và góc A bằng 60 độ.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q8",
+        "text": "Cho đường tròn tâm O bán kính bằng 7.",
+        "expect_pts": ["O"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q9",
+        "text": "Cho hình bình hành ABCD có AB=8, AD=6. Gọi E là trung điểm của CD. Vẽ đoạn thẳng AE.",
+        "expect_pts": ["A", "B", "C", "D", "E"],
+        "expect_phases": 2,
+    },
+    {
+        "id": "Q10-Step1",
+        "text": "Cho hình chữ nhật ABCD có AB=10, AD=5.",
+        "expect_pts": ["A", "B", "C", "D"],
+        "expect_phases": 1,
+    },
+    {
+        "id": "Q11-Video",
+        "text": "Cho tam giác ABC đều cạnh 5. Vẽ đường tròn ngoại tiếp tam giác.",
+        "expect_pts": ["A", "B", "C"],
+        "expect_phases": 2,
+        "request_video": True
+    }
+]
+
+# Q10-Step2 is a follow-up to Q10-Step1
+Q10_FOLLOW_UP = {
+    "id": "Q10-Step2",
+    "text": "Vẽ thêm đường chéo AC.", 
+    "expect_pts": ["A", "B", "C", "D"],
+    "expect_phases": 2, # Main polygon + diagonal segment
+}
+
+def dist(p1, p2):
+    return math.sqrt((p1[0]-p2[0])**2 + (p1[1]-p2[1])**2)
+
+async def run_query(orchestrator, q, history=None):
+    print(f"\n{'='*60}")
+    print(f"[{q['id']}] {q['text']}")
+    if history:
+        print(f"  (With history context of {len(history)} messages)")
+    if q.get("request_video"):
+        print("  🎥 VIDEO RENDERING REQUESTED")
+    print('='*60)
+    try:
+        result = await orchestrator.run(
+            text=q["text"],
+            job_id=f"test-{q['id']}-{int(time.time())}",
+            request_video=q.get("request_video", False),
+            history=history,
+        )
+
+        if "error" in result:
+            print(f"  ❌ PIPELINE ERROR: {result['error']}")
+            return None
+
+        # Check 1: semantic_analysis != original query
+        analysis = result.get("semantic_analysis", "")
+        if analysis.strip() == q["text"].strip():
+            print(f"  ❌ FAIL: semantic_analysis is identical to input query")
+        else:
+            print(f"  ✅ semantic_analysis: {analysis[:100]}...")
+
+        # Check 2: all expected points are in coordinates
+        coords = result.get("coordinates", {})
+        missing = [pt for pt in q["expect_pts"] if pt not in coords]
+        if missing:
+            print(f"  ❌ FAIL: Missing points in coordinates: {missing}")
+        else:
+            print(f"  ✅ All expected points present: {list(coords.keys())}")
+
+        # Check 4: drawing_phases
+        phases = result.get("drawing_phases", [])
+        if len(phases) >= q["expect_phases"]:
+            print(f"  ✅ drawing_phases: {len(phases)} phase(s)")
+        else:
+            print(f"  ❌ FAIL: expected {q['expect_phases']} drawing phase(s), got {len(phases)}")
+
+        # Check 5: Video Polling (if requested)
+        if q.get("request_video"):
+            job_id = result.get("job_id")
+            if not job_id:
+                print("  ❌ FAIL: Video requested but no job_id returned")
+                return None
+            
+            print(f"  ⏳ Waiting for Manim video (job_id: {job_id})...")
+            supabase = get_supabase()
+            max_retries = 24 # 2 minutes (24 * 5s)
+            success = False
+            for _ in range(max_retries):
+                job_res = supabase.table("jobs").select("*").eq("id", job_id).execute()
+                if job_res.data:
+                    job_data = job_res.data[0]
+                    status = job_data.get("status")
+                    if status == "success":
+                        video_url = job_data.get("result", {}).get("video_url")
+                        if video_url:
+                            print(f"  ✅ VIDEO READY: {video_url}")
+                            result["video_url"] = video_url
+                            success = True
+                            break
+                        else:
+                            print("  ❌ FAIL: Job success but no video_url in result")
+                            return None
+                    elif status == "failed":
+                        print(f"  ❌ FAIL: Manim worker job failed")
+                        return None
+                await asyncio.sleep(5)
+            
+            if not success:
+                print("  ❌ FAIL: Timeout waiting for video rendering")
+                return None
+
+        dsl = result.get('geometry_dsl', '')
+        print(f"  DSL ({len(dsl.splitlines())} lines):\n{dsl}")
+        
+        # Specific check for Q10-Step2: must contain BOTH ABCD and AC segment
+        if q["id"] == "Q10-Step2":
+            if "POLYGON_ORDER(A, B, C, D)" in dsl and "SEGMENT(A, C)" in dsl:
+                 print(f"  ✅ Multi-turn Success: DSL merged correctly.")
+            else:
+                 print(f"  ❌ Multi-turn Fail: DSL missing component.")
+
+        return result
+
+    except Exception as e:
+        import traceback
+        print(f"  ❌ EXCEPTION: {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return None
+
+async def main():
+    load_dotenv()
+    orchestrator = Orchestrator()
+
+    results = []
+    # Run Q1 to Q9 and Q11 (Video)
+    queries_to_test = QUERIES[:-1] + [QUERIES[-1]] # All except Step1
+    
+    # Actually let's just iterate over all and handle Q10 special
+    for q in QUERIES:
+        if q["id"] == "Q10-Step1":
+            continue
+        res = await run_query(orchestrator, q)
+        results.append((q["id"], res is not None))
+
+    # Run Q10 Flow (Multi-turn)
+    print("\n--- Starting Multi-turn Flow (Q10) ---")
+    q10_1 = next(q for q in QUERIES if q["id"] == "Q10-Step1")
+    res10_1 = await run_query(orchestrator, q10_1)
+    results.append((q10_1["id"], res10_1 is not None))
+
+    if res10_1:
+        # Construct message history to pass to step 2
+        history = [
+            {"role": "user", "content": q10_1["text"]},
+            {
+                "role": "assistant", 
+                "content": res10_1["semantic_analysis"],
+                "metadata": {
+                    "geometry_dsl": res10_1["geometry_dsl"],
+                    "coordinates": res10_1["coordinates"]
+                }
+            }
+        ]
+        res10_2 = await run_query(orchestrator, Q10_FOLLOW_UP, history=history)
+        results.append((Q10_FOLLOW_UP["id"], res10_2 is not None))
+
+    print(f"\n{'='*60}")
+    print("SUMMARY:")
+    for qid, ok in results:
+        print(f"  [{qid}] {'✅ PASS' if ok else '❌ FAIL'}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/test_openrouter.py

@@ -0,0 +1,92 @@
+import os
+import httpx
+import json
+import time
+from dotenv import load_dotenv
+
+# Load môi trường từ backend/.env
+load_dotenv(dotenv_path="./backend/.env")
+
+MODELS = [
+    "nvidia/nemotron-3-super-120b-a12b:free",
+    "meta-llama/llama-3.3-70b-instruct:free",
+    "openai/gpt-oss-120b:free",
+    "z-ai/glm-4.5-air:free",
+    "minimax/minimax-m2.5:free",
+    "google/gemma-4-26b-a4b-it:free",
+    "google/gemma-4-31b-it:free",
+]
+
+PROMPT = "Cho hình chữ nhật ABCD có AB bằng 5 và AD bằng 10. Gọi E là điểm nằm trong đoạn CD sao cho CE = 2ED. Vẽ đoạn thẳng AE. Vẽ thêm P là điểm nằm trên đường thẳng BC sao cho BP = 2PC, tính chu vi tam giác PEA"
+
+def test_models():
+    api_key = os.getenv("OPENROUTER_API_KEY_1")
+    base_url = "https://openrouter.ai/api/v1/chat/completions"
+
+    if not api_key:
+        print("❌ Lỗi: Không tìm thấy OPENROUTER_API_KEY trong file .env")
+        return
+
+    print("🚀 Bắt đầu benchmark các model OpenRouter...")
+    print(f"📝 Prompt: {PROMPT}\n")
+    
+    results = []
+
+    for model in MODELS:
+        print(f"📡 Đang gọi model: {model}...", end="", flush=True)
+        
+        headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://mathsolver.io",
+            "X-Title": "MathSolver Benchmark Tool"
+        }
+
+        payload = {
+            "model": model,
+            "messages": [{"role": "user", "content": PROMPT}]
+        }
+
+        start_time = time.time()
+        try:
+            with httpx.Client(timeout=60.0) as client:
+                response = client.post(base_url, headers=headers, json=payload)
+                response.raise_for_status()
+                
+                duration = time.time() - start_time
+                data = response.json()
+                answer = data['choices'][0]['message']['content']
+                
+                results.append({
+                    "model": model,
+                    "duration": duration,
+                    "answer": answer,
+                    "status": "success"
+                })
+                print(f" ✅ DONE ({duration:.2f}s)")
+                
+        except Exception as e:
+            duration = time.time() - start_time
+            print(f" ❌ FAILED ({duration:.2f}s)")
+            results.append({
+                "model": model,
+                "duration": duration,
+                "error": str(e),
+                "status": "error"
+            })
+
+    print("\n" + "="*80)
+    print("📊 BÁO CÁO CHI TIẾT BENCHMARK")
+    print("="*80)
+
+    for res in results:
+        print(f"\n🔹 MODEL: {res['model']}")
+        print(f"⏱ Thời gian: {res['duration']:.2f} giây")
+        if res['status'] == "success":
+            print(f"🤖 Phản hồi:\n{res['answer']}")
+        else:
+            print(f"❌ Lỗi: {res.get('error')}")
+        print("-" * 40)
+
+if __name__ == "__main__":
+    test_models()

tests/test_real_llm.py

@@ -0,0 +1,30 @@
+import pytest
+import asyncio
+import os
+import logging
+from dotenv import load_dotenv
+from app.llm_client import get_llm_client
+
+# Setup logging to see the fallback process
+logging.basicConfig(level=logging.INFO)
+load_dotenv()
+
+@pytest.mark.asyncio
+async def test_real_llm():
+    client = get_llm_client()
+    
+    print("\n--- Testing LLM Call (Complex Prompt) ---")
+    try:
+        content = await client.chat_completions_create(
+            messages=[
+                {"role": "system", "content": "You are a Geometry Expert. Formulate a step-by-step reasoning for calculating the distance between two points M and N where M is the midpoint of AB (len=10) and N is the midpoint of AD (len=20) in a rectangle ABCD. Use LaTeX for formulas."},
+                {"role": "user", "content": "Solve it carefully."}
+            ]
+        )
+        print(f"\nResponse: {content}")
+        print("\n--- Test Completed Successfully ---")
+    except Exception as e:
+        print(f"\n--- Test Failed: {type(e).__name__}: {e} ---")
+
+if __name__ == "__main__":
+    asyncio.run(test_real_llm())

tests/test_solver.py

@@ -0,0 +1,44 @@
+import sys
+import os
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+
+from solver.engine import GeometryEngine
+from solver.models import Point, Constraint
+
+def test_triangle_abc():
+    engine = GeometryEngine()
+    
+    # Triangle ABC: AB=5, AC=7, angle A=60
+    points = [
+        Point(id="A"),
+        Point(id="B"),
+        Point(id="C")
+    ]
+    
+    constraints = [
+        Constraint(type="length", targets=["A", "B"], value=5.0),
+        Constraint(type="length", targets=["A", "C"], value=7.0),
+        Constraint(type="angle", targets=["A"], value=60.0) # Angle at A
+    ]
+    
+    print("Solving for Triangle ABC (AB=5, AC=7, angle A=60)...")
+    results = engine.solve(points, constraints)
+    
+    if results:
+        coords = results["coordinates"]
+        print("Success! Coordinates:")
+        for pid, c in coords.items():
+            print(f"Point {pid}: {c}")
+            
+        # Verify distance AB
+        dist_ab = ((coords["B"][0] - coords["A"][0])**2 + (coords["B"][1] - coords["A"][1])**2)**0.5
+        print(f"Verified AB distance: {dist_ab:.2f}")
+        
+        # Verify distance AC
+        dist_ac = ((coords["C"][0] - coords["A"][0])**2 + (coords["C"][1] - coords["A"][1])**2)**0.5
+        print(f"Verified AC distance: {dist_ac:.2f}")
+    else:
+        print("Solver failed.")
+
+if __name__ == "__main__":
+    test_triangle_abc()