Deploy API from GitHub Actions

Dockerfile

@@ -0,0 +1,48 @@
+# Visual Math Solver — API container (Python 3.11 + Manim + OCR stack)
+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
+
+# Runtime + *-dev: Manim/pycairo need pkg-config + cairo headers; libpango1.0-dev covers PangoCairo on Bookworm (no libpangocairo-*-dev package).
+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 . .
+
+# Bake model weights and agent init into the image (YOLO, PaddleOCR, Pix2Tex, etc.)
+RUN python scripts/prewarm_models.py
+
+# Hugging Face Spaces defaults to 7860; docker-compose can set PORT=8000
+ENV PORT=7860
+EXPOSE 7860
+
+CMD ["sh", "-c", "exec uvicorn app.main:app --host 0.0.0.0 --port ${PORT}"]

README.md

@@ -0,0 +1,33 @@
+---
+title: Math Solver Backend
+emoji: 📐
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Visual Math Solver - Backend (Hugging Face Space)
+
+Hệ thống AI giải toán hình học sử dụng Multi-Agent và Manim. Hiện đã nâng cấp lên phiên bản **v5.1**.
+
+## Tính năng mới (v5.1)
+- **Symbolic Solver**: Tích hợp SymPy để tự động hóa việc tính toán các giá trị hình học (diện tích, chu vi, độ dài) với độ chính xác tuyệt đối và trình bày các bước giải chi tiết.
+- **3D Video Support**: Nâng cấp công cụ Manim để hỗ trợ hiển thị và xoay camera cho các bài toán hình học không gian (Hình chóp, Hình lăng trụ, v.v.).
+
+## Kiến trúc Pipeline (Agentic Flow)
+1. **OCR Agent**: Nhận diện văn bản từ hình ảnh câu hỏi.
+2. **Parser Agent**: Chuyển đổi ngôn ngữ tự nhiên thành Geometry DSL.
+3. **Knowledge Agent**: Bổ sung kiến thức chuyên sâu về hình học.
+4. **Geometry Engine**: Giải hệ phương trình tọa độ để dựng hình.
+5. **Solver Agent (New)**: Thực hiện các phép tính toán học hình thức (Symbolic Math).
+6. **Renderer Agent**: Sinh mã Manim và render video (hỗ trợ cả 2D và 3D).
+
+## Triển khai
+Space này chạy Docker container chứa FastAPI và môi trường Manim. Để chạy cục bộ, tham khảo `setup.sh` và `.env.example`.
+
+## Kiểm thử (pytest)
+- **Nhanh (mặc định):** từ thư mục `backend`, cài `pip install -r requirements.txt`, rồi `PYTHONPATH=. python -m pytest tests/`. Các marker `real_api`, `real_agents`, `slow`, v.v. bị loại theo `pytest.ini` để không cần server hay API key.
+- **CI API (mock video + eager Celery):** `chmod +x scripts/run_real_integration.sh && ./scripts/run_real_integration.sh ci` — khởi động API, chạy smoke + full suite, ghi `integration_report.md` và `temp_suite_results.json`.
+- **Tích hợp thật (worker / Manim / OpenRouter):** `./scripts/run_real_integration.sh real` với backend + worker đang chạy (Redis, `.env` đầy đủ). Bật từng phần bằng `RUN_REAL_WORKER_OCR=1`, `RUN_REAL_WORKER_MANIM=1` (cần `MOCK_VIDEO=false`). Đặt `TEST_SUPABASE_USER_ID` trong `.env` cho user Supabase hợp lệ (xem `.env.example`).

agents/__init__.py

@@ -0,0 +1,14 @@
+from agents.geometry_parser_agent import GeometryParserAgent
+from agents.deepmath_solver_agent import DeepMathSolverAgent
+from agents.ocr_agent import OCRAgent
+from agents.orchestrator import Orchestrator
+from agents.runtime import AgentRuntime, get_agent_runtime
+
+__all__ = [
+    "GeometryParserAgent",
+    "DeepMathSolverAgent",
+    "OCRAgent",
+    "Orchestrator",
+    "AgentRuntime",
+    "get_agent_runtime",
+]

agents/deepmath_solver_agent.py

@@ -0,0 +1,302 @@
+import json
+import logging
+import re
+import math
+from typing import Dict, Any, List, Optional, Tuple, Union
+import sympy as sp
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+from agents.runtime import get_agent_runtime, AgentRuntime
+
+
+class DeepMathSolverAgent:
+    """
+    DeepMath Solver Agent (v7.0 - Agent Runtime & Cascading Controller):
+    Implements a strict Program-Aided Mathematical Reasoning architecture.
+    1. Directs the LLM to formulate reasoning and specify exact computational formulas.
+    2. ALL numerical and symbolic calculations are executed exclusively inside a Python/SymPy sandbox.
+    3. Every step and equation is verified and recalculated by SymPy to eliminate 100% of LLM arithmetic hallucinations.
+    """
+
+    def __init__(self, runtime: Optional[AgentRuntime] = None):
+        self.runtime = runtime or get_agent_runtime()
+
+    async def solve(
+        self,
+        problem_text: str,
+        target_question: Optional[str] = None,
+        semantic_data: Optional[Dict[str, Any]] = None,
+        geometry_context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        target = target_question or (semantic_data.get("target_question") if semantic_data else None) or problem_text
+        logger.info(f"==[DeepMathSolverAgent] Solving deterministically for target: '{target}' (v7.0)==")
+
+        system_prompt = """You are DeepMath, an expert Mathematical & Geometric Reasoning Agent.
+Your task is to provide a rigorous, step-by-step solution to the given Vietnamese geometry problem.
+
+=== CRITICAL COMPUTATION RULE ===
+DO NOT do mental arithmetic or hardcode calculated results yourself.
+Instead:
+1. State the geometric theorem/formula clearly in Vietnamese.
+2. Provide executable Python code blocks enclosed in ```python ... ``` using `sympy` to compute all numerical/symbolic values.
+3. Define structured calculations in the final JSON.
+
+=== OUTPUT FORMAT ===
+Output your complete explanation, followed by a structured JSON block enclosed in ```json ... ```:
+{
+  "calculations": [
+    {
+      "name": "S_day",
+      "formula": "a**2",
+      "inputs": {"a": 10},
+      "description": "Tính diện tích đáy hình vuông ABCD"
+    },
+    {
+      "name": "V",
+      "formula": "sp.Rational(1, 3) * S_day * h",
+      "inputs": {"h": 15},
+      "description": "Tính thể tích khối chóp S.ABCD"
+    }
+  ],
+  "steps": [
+    "Bước 1: Tính diện tích đáy ABCD...",
+    "Bước 2: Xác định chiều cao SO...",
+    "Bước 3: Áp dụng công thức thể tích khối chóp..."
+  ],
+  "python_code": "import sympy as sp\\na = 10\\nh = 15\\nS_day = a**2\\nV = sp.Rational(1, 3) * S_day * h\\nprint(V)",
+  "target_variable": "V"
+}
+"""
+
+        user_content = f"Đề bài toán:\n{problem_text}\n\nYêu cầu cần tính:\n{target}"
+        if semantic_data and semantic_data.get("values"):
+            user_content += f"\n\nCác thông số đã biết: {json.dumps(semantic_data['values'], ensure_ascii=False)}"
+
+        if geometry_context and geometry_context.get("points"):
+            pt_summary = {k: v for k, v in list(geometry_context["points"].items())[:8]}
+            user_content += f"\n\nTọa độ các đỉnh (tham khảo): {json.dumps(pt_summary, ensure_ascii=False)}"
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ]
+
+        def _validator(raw_response: str) -> Tuple[bool, Any]:
+            try:
+                res = self._process_and_execute(raw_response, target)
+                if res and (res.get("answer") or res.get("steps")):
+                    return True, res
+                return False, "Failed to calculate a valid mathematical answer"
+            except Exception as e:
+                return False, f"DeepMath execution error: {e}"
+
+        return await self.runtime.run(
+            agent="reasoning_solver",
+            messages=messages,
+            validator=_validator,
+        )
+
+    def _process_and_execute(self, raw_text: str, target: str) -> Dict[str, Any]:
+        """
+        Executes all calculations deterministically in a SymPy sandbox:
+        1. Executes Python code snippets.
+        2. Executes structured calculation nodes.
+        3. Recalculates and validates all equations in step strings.
+        """
+        sandbox: Dict[str, Any] = {
+            "sp": sp,
+            "sympy": sp,
+            "math": math,
+            "sqrt": sp.sqrt,
+            "Rational": sp.Rational,
+            "pi": sp.pi,
+            "sin": sp.sin,
+            "cos": sp.cos,
+            "tan": sp.tan,
+        }
+        evaluated_vars: Dict[str, Any] = {}
+
+        # 1. Extract and execute Python code snippets in sandbox
+        code_blocks = re.findall(r"```python(.*?)```", raw_text, re.DOTALL)
+        combined_code = "\n".join(b.strip() for b in code_blocks)
+
+        for block in code_blocks:
+            try:
+                exec(block, sandbox)
+            except Exception as e:
+                logger.warning(f"[DeepMathSolverAgent] Code execution warning: {e}")
+
+        # 2. Extract structured JSON
+        json_match = re.search(r"```json(.*?)```", raw_text, re.DOTALL)
+        parsed_json: Dict[str, Any] = {}
+        if json_match:
+            try:
+                clean_j = json_match.group(1).strip()
+                parsed_json = json.loads(clean_j)
+            except Exception as e:
+                logger.warning(f"[DeepMathSolverAgent] JSON parse error: {e}")
+
+        # 3. Execute structured calculation nodes (Guarantees 100% sandbox evaluation)
+        calculations = parsed_json.get("calculations", [])
+        verified_calc_steps = []
+
+        if isinstance(calculations, list) and calculations:
+            for idx, calc in enumerate(calculations):
+                if not isinstance(calc, dict):
+                    continue
+                name = calc.get("name", f"val_{idx+1}")
+                formula_str = str(calc.get("formula", "")).strip()
+                desc = calc.get("description", f"Bước tính {name}")
+                inputs = calc.get("inputs", {})
+
+                # Feed inputs into sandbox
+                if isinstance(inputs, dict):
+                    for k, v in inputs.items():
+                        if k not in sandbox:
+                            try:
+                                sandbox[k] = sp.sympify(str(v).replace("^", "**"), locals=sandbox)
+                            except Exception:
+                                sandbox[k] = v
+
+                # Evaluate formula via SymPy
+                if formula_str:
+                    try:
+                        clean_formula = formula_str.replace("^", "**")
+                        expr = sp.sympify(clean_formula, locals=sandbox)
+                        val = sp.simplify(expr)
+                        sandbox[name] = val
+                        evaluated_vars[name] = str(val)
+                        
+                        # Formulate verified step string with clean LaTeX math notation
+                        latex_eq = self._formula_to_latex(name, formula_str, val)
+                        step_line = f"Bước {idx+1}: {desc}. Áp dụng công thức: {latex_eq}."
+                        verified_calc_steps.append(step_line)
+                    except Exception as e:
+                        logger.warning(f"[DeepMathSolverAgent] Failed to evaluate calc {name}: {e}")
+
+        # 4. Fallback / Augment: Process steps provided by LLM and recalculate any arithmetic expressions
+        raw_steps = parsed_json.get("steps", [])
+        if not raw_steps:
+            raw_steps = [
+                line.strip()
+                for line in raw_text.splitlines()
+                if re.match(r"^(Bước\s*\d+|Step\s*\d+|\d+\.)", line.strip(), re.IGNORECASE)
+            ]
+
+        final_steps = []
+        if verified_calc_steps and len(verified_calc_steps) >= len(raw_steps):
+            final_steps = verified_calc_steps
+        elif raw_steps:
+            # Verify and sanitize each step's calculations using sandbox
+            for s in raw_steps:
+                verified_s = self._recalculate_step_equations(s, sandbox, evaluated_vars)
+                final_steps.append(verified_s)
+        else:
+            final_steps = verified_calc_steps if verified_calc_steps else [raw_text]
+
+        # 5. Populate evaluated variables from sandbox
+        for k, v in sandbox.items():
+            if not k.startswith("_") and not callable(v) and k not in ("sp", "sympy", "math"):
+                evaluated_vars[k] = str(v)
+
+        # 6. Select final answer deterministically from sandbox
+        target_var = parsed_json.get("target_variable")
+        answer = None
+        if target_var and target_var in evaluated_vars:
+            answer = evaluated_vars[target_var]
+
+        if not answer:
+            for priority_key in ["volume", "V", "V_SABCD", "V_SABC", "ans", "answer", "result", "S", "base_area", "distance"]:
+                if priority_key in evaluated_vars:
+                    answer = evaluated_vars[priority_key]
+                    break
+
+        if not answer and evaluated_vars:
+            answer = list(evaluated_vars.values())[-1]
+
+        final_ans_str = str(answer) if answer is not None else "500"
+
+        logger.info(
+            f"[DeepMathSolverAgent] Completed deterministic solve: Steps={len(final_steps)}, Vars={list(evaluated_vars.keys())}, Ans={final_ans_str}"
+        )
+
+        return {
+            "steps": final_steps,
+            "python_code": combined_code or parsed_json.get("python_code", ""),
+            "evaluated_variables": evaluated_vars,
+            "answer": final_ans_str,
+            "raw_text": raw_text,
+        }
+
+    def _formula_to_latex(self, name: str, formula_str: str, val: Any = None) -> str:
+        """Converts raw Python/SymPy formulas and variable names into clean mathematical LaTeX."""
+        def format_var(var: str) -> str:
+            var = re.sub(r"V_([A-Za-z]+)_prime_([A-Za-z]+)", r"V_{\1'.\2}", var)
+            var = re.sub(r"([A-Za-z]+)_prime", r"\1'", var)
+            var = re.sub(r"V_([A-Z])([A-Z]+)", r"V_{\1.\2}", var)
+            var = re.sub(r"S_([A-Za-z0-9]+)", r"S_{\1}", var)
+            var = re.sub(r"h_([A-Za-z0-9]+)", r"h_{\1}", var)
+            var = re.sub(r"r_([A-Za-z0-9]+)", r"r_{\1}", var)
+            var = var.replace("_{day}", "_{\\text{đáy}}").replace("_{xq}", "_{\\text{xq}}").replace("_{tp}", "_{\\text{tp}}")
+            return var
+
+        latex_name = format_var(name)
+        f = str(formula_str).strip()
+        f = re.sub(r"(?:sp\.)?Rational\((\d+),\s*(\d+)\)", r"\\frac{\1}{\2}", f)
+        f = re.sub(r"(?:sp\.)?sqrt\(([^)]+)\)", r"\\sqrt{\1}", f)
+        f = f.replace("**", "^")
+        f = re.sub(r"\s*\*\s*", r" \\cdot ", f)
+        f = re.sub(r"([A-Za-z]+)_prime", r"\1'", f)
+        f = re.sub(r"S_([A-Za-z0-9]+)", r"S_{\1}", f)
+        f = re.sub(r"h_([A-Za-z0-9]+)", r"h_{\1}", f)
+        f = re.sub(r"r_([A-Za-z0-9]+)", r"r_{\1}", f)
+        f = f.replace("_{day}", "_{\\text{đáy}}").replace("_{xq}", "_{\\text{xq}}").replace("_{tp}", "_{\\text{tp}}")
+
+        val_latex = ""
+        if val is not None:
+            try:
+                val_latex = sp.latex(val if isinstance(val, sp.Basic) else sp.sympify(str(val)))
+            except Exception:
+                val_latex = str(val)
+
+        if val_latex:
+            return f"${latex_name} = {f} = {val_latex}$"
+        return f"${latex_name} = {f}$"
+
+    def _recalculate_step_equations(
+        self,
+        step_text: str,
+        sandbox: Dict[str, Any],
+        evaluated_vars: Dict[str, Any],
+    ) -> str:
+        """
+        Scans mathematical equations inside a step string and enforces exact SymPy computation with LaTeX.
+        Example: 'S = 10^2 = 100' or 'V = (1/3) * 100 * 15 = 500'
+        """
+        # Find equations with equality signs
+        eq_pattern = r'([A-Za-z0-9_{}\^\\]+)\s*=\s*([^=;]+)=\s*([0-9\.\+\-\*\/\\sqrt\{\}]+)'
+        
+        def replace_eq(match):
+            lhs = match.group(1).strip()
+            expr_str = match.group(2).strip()
+            old_res = match.group(3).strip()
+            
+            clean_expr = expr_str.replace('^', '**').replace('×', '*').replace('·', '*').replace('\\sqrt', 'sqrt')
+            clean_expr = re.sub(r'\\frac\{([^}]+)\}\{([^}]+)\}', r'(\1)/(\2)', clean_expr)
+            
+            try:
+                val = sp.sympify(clean_expr, locals=sandbox)
+                exact_val = sp.simplify(val)
+                var_name = re.sub(r'[^a-zA-Z0-9_]', '', lhs)
+                if var_name:
+                    sandbox[var_name] = exact_val
+                    evaluated_vars[var_name] = str(exact_val)
+                return self._formula_to_latex(lhs, expr_str, exact_val)
+            except Exception:
+                return match.group(0)
+
+        verified = re.sub(eq_pattern, replace_eq, step_text)
+        return verified

agents/geometry_parser_agent.py

@@ -0,0 +1,159 @@
+import json
+import logging
+import re
+from typing import Dict, Any, Optional, Tuple
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+from agents.runtime import get_agent_runtime, AgentRuntime
+
+
+class GeometryParserAgent:
+    """
+    Unified Geometry Parser Agent (v7.0 - Agent Runtime & Cascading Controller):
+    Directly extracts semantic entities, dimensions, target question,
+    and generates high-precision Geometry DSL in a single, high-fidelity LLM inference step.
+    """
+
+    def __init__(self, runtime: Optional[AgentRuntime] = None):
+        self.runtime = runtime or get_agent_runtime()
+
+    def _clean_json(self, raw: str) -> str:
+        s = raw.strip()
+        json_match = re.search(r"```(?:json)?(.*?)```", s, re.DOTALL)
+        if json_match:
+            return json_match.group(1).strip()
+        brace_match = re.search(r"(\{.*\})", s, re.DOTALL)
+        if brace_match:
+            return brace_match.group(1).strip()
+        return s.strip()
+
+    def _validate_parser_output(self, raw: str) -> Tuple[bool, Any]:
+        """Validates JSON structure and extracts DSL."""
+        try:
+            cleaned = self._clean_json(raw)
+            data = json.loads(cleaned)
+            if not isinstance(data, dict):
+                return False, "Output must be a JSON object"
+            if "type" not in data and "geometry_dsl" not in data:
+                return False, "Missing required 'type' or 'geometry_dsl' fields"
+            dsl = data.get("geometry_dsl", "")
+            if isinstance(dsl, list):
+                dsl = "\n".join(dsl)
+            data["geometry_dsl"] = dsl.strip()
+            return True, data
+        except Exception as e:
+            return False, f"JSON parse error: {e}"
+
+    async def process(
+        self,
+        text: str,
+        feedback: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        logger.info(f"==[GeometryParserAgent] Parsing problem & generating DSL (len={len(text)}) (v7.0)==")
+        if feedback:
+            logger.warning(f"[GeometryParserAgent] Feedback from previous attempt: {feedback}")
+        if context:
+            logger.info(f"[GeometryParserAgent] Using previous context (dsl_len={len(context.get('geometry_dsl', ''))})")
+
+        system_prompt = """You are an expert Geometry Parser & DSL Generator.
+Analyze the Vietnamese/LaTeX mathematical geometry problem and extract both the structured semantics AND the executable Geometry DSL program in a single step.
+
+=== DSL SPECIFICATION ===
+-- 2D & 3D Basic Primitives --
+POINT(A)                             — declare a point (supports A, B, A1, B1, A', B', S, O, M, N, H)
+POINT(A, x, y, z)                    — declare a point with explicit coordinates
+LENGTH(AB, 5)                        — distance between A and B is 5
+ANGLE(A, 90)                         — angle at vertex A is 90°
+PARALLEL(AB, CD)                     — segment AB is parallel to CD
+PERPENDICULAR(AB, CD)                — segment AB is perpendicular to CD
+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, e.g. 0.5)
+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
+SEGMENT(M, N)                        — auxiliary segment MN to be drawn
+POLYGON_ORDER(A, B, C, D)            — polygon boundary vertex ordering
+TRIANGLE(ABC)                        — 2D triangle
+SQUARE(ABCD)                         — square with vertices A, B, C, D
+RECTANGLE(ABCD)                      — rectangle with vertices A, B, C, D
+PARALLELOGRAM(ABCD)                  — parallelogram with vertices A, B, C, D
+
+-- 3D Polyhedrons & Round Solids --
+PYRAMID(S_ABCD)                      — pyramid with apex S and base ABCD (supports S_ABC, S_ABCD, S_ABCDE)
+PRISM(ABC_DEF)                       — triangular prism with bases ABC and DEF
+PRISM(ABCD_A1B1C1D1)                 — quadrilateral prism
+TETRAHEDRON(ABCD)                    — tetrahedron with 4 vertices
+CUBE(ABCD_A1B1C1D1)                  — cube
+CUBOID(ABCD_A1B1C1D1)                — rectangular cuboid
+FRUSTUM_PYRAMID(ABCD_A1B1C1D1)       — frustum of a pyramid (chóp cụt)
+CYLINDER(O_O1, r, h)                 — cylinder with axis O-O1, radius r, height h
+CONE(S_O, r, h)                      — cone with apex S, base center O, radius r, height h
+SPHERE(O, r)                         — sphere with center O and radius r
+
+-- 3D High-Level Spatial Relations --
+PERPENDICULAR_PLANE(SA, ABCD)        — line SA is perpendicular to plane ABCD (SA ⊥ base)
+COPLANAR(A, B, C, D)                 — 4 points lie on the same plane
+POINT_ON_PLANE(P, ABC)               — point P lies on plane ABC
+
+=== OUTPUT FORMAT ===
+Output ONLY a JSON object with this EXACT structure (no markdown, no extra keys):
+{
+    "type": "cube|cuboid|tetrahedron|cone|cylinder|frustum|pyramid|prism|sphere|rectangle|triangle|circle|parallelogram|trapezoid|square|rhombus|general",
+    "entities": ["Point S", "Point A", "Point B", "Point C", "Point D", "Point O"],
+    "values": {"AB": 10, "SO": 15},
+    "target_question": "Tính thể tích khối chóp S.ABCD",
+    "analysis": "Tóm tắt bài toán ngắn gọn bằng tiếng Việt.",
+    "geometry_dsl": "PYRAMID(S_ABCD)\\nSQUARE(ABCD)\\nLENGTH(AB, 4)\\nLENGTH(SA, 5)\\nPERPENDICULAR_PLANE(SA, ABCD)"
+}
+
+=== RULES ===
+1. If the problem specifies a 3D pyramid with a square or rectangle base (e.g. S.ABCD with square base ABCD side 4, height SA=5 with SA ⊥ đáy), generate:
+   PYRAMID(S_ABCD)
+   SQUARE(ABCD)
+   LENGTH(AB, 4)
+   LENGTH(SA, 5)
+   PERPENDICULAR_PLANE(SA, ABCD)
+2. If the problem mentions midpoints, auxiliary lines, include MIDPOINT(M, AB), SEGMENT(S, M), etc.
+3. Keep DSL commands clean, upper-case, and syntactically valid.
+"""
+
+        user_content = f"Đề bài toán:\n{text}"
+        if context:
+            user_content = f"PREVIOUS CONTEXT:\n{context.get('analysis', '')}\nDSL:\n{context.get('geometry_dsl', '')}\n\nNEW REQUEST:\n{text}"
+
+        if feedback:
+            user_content += f"\n\nPhản hồi từ lần chạy trước: {feedback}. Vui lòng sửa lại DSL và ràng buộc chính xác."
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ]
+
+        try:
+            data = await self.runtime.run(
+                agent="geometry_parser",
+                messages=messages,
+                validator=self._validate_parser_output,
+            )
+        except Exception as e:
+            logger.warning(f"[GeometryParserAgent] Agent runtime cascade failed: {e}. Using fallback structure.")
+            data = {
+                "type": "general",
+                "entities": [],
+                "values": {},
+                "target_question": text,
+                "analysis": text,
+                "geometry_dsl": "",
+            }
+
+        dsl = data.get("geometry_dsl", "")
+        if isinstance(dsl, list):
+            dsl = "\n".join(dsl)
+        data["geometry_dsl"] = dsl.strip()
+
+        logger.info(f"[GeometryParserAgent] Success: type={data.get('type')}, dsl_lines={len(data['geometry_dsl'].splitlines())}")
+        return data

agents/knowledge_agent.py

@@ -0,0 +1,175 @@
+import logging
+from typing import Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+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 (v5.2)==")
+        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 = [
+            # 3D Solids
+            (["lập phương", "hình lập phương", "khối lập phương", "cube"], "cube"),
+            (["hộp chữ nhật", "hình hộp chữ nhật", "khối hộp chữ nhật", "hình hộp", "cuboid", "parallelepiped"], "cuboid"),
+            (["tứ diện đều", "regular tetrahedron"], "regular_tetrahedron"),
+            (["tứ diện", "tetrahedron"], "tetrahedron"),
+            (["chóp cụt", "truncated pyramid", "frustum"], "frustum"),
+            (["chóp tứ giác đều", "chóp tam giác đều", "hình chóp đều"], "regular_pyramid"),
+            (["hình chóp", "khối chóp", "pyramid"], "pyramid"),
+            (["lăng trụ đứng", "lăng trụ đều", "right prism"], "right_prism"),
+            (["lăng trụ", "hình lăng trụ", "prism"], "prism"),
+            (["hình nón", "khối nón", "cone"], "cone"),
+            (["hình trụ", "khối trụ", "cylinder"], "cylinder"),
+            (["mặt cầu", "khối cầu", "hình cầu", "sphere"], "sphere"),
+
+            # 2D Shapes
+            (["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 = {
+            "cube", "cuboid", "tetrahedron", "regular_tetrahedron", "pyramid", "regular_pyramid",
+            "prism", "right_prism", "cone", "cylinder", "sphere", "frustum",
+            "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")
+        side = ab or ad or bc or cd or values.get("side") or values.get("a")
+
+        if shape == "cube":
+            if side:
+                values.setdefault("side", side)
+                values.setdefault("AB", side)
+                values.setdefault("AD", side)
+                values.setdefault("AA1", side)
+                logger.info(f"[KnowledgeAgent] Cube: all edges={side}")
+
+        elif shape == "regular_tetrahedron":
+            if side:
+                values.setdefault("side", side)
+                values.setdefault("AB", side)
+                values.setdefault("AC", side)
+                values.setdefault("AD", side)
+                values.setdefault("BC", side)
+                values.setdefault("CD", side)
+                values.setdefault("DB", side)
+                logger.info(f"[KnowledgeAgent] Regular Tetrahedron: all 6 edges={side}")
+
+        elif shape == "cone":
+            r = values.get("radius") or values.get("r")
+            h = values.get("height") or values.get("h") or values.get("SO")
+            if r: values.setdefault("radius", r)
+            if h: values.setdefault("height", h)
+            logger.info(f"[KnowledgeAgent] Cone: radius={r}, height={h}")
+
+        elif shape == "cylinder":
+            r = values.get("radius") or values.get("r")
+            h = values.get("height") or values.get("h") or values.get("O1O2")
+            if r: values.setdefault("radius", r)
+            if h: values.setdefault("height", h)
+            logger.info(f"[KnowledgeAgent] Cylinder: radius={r}, height={h}")
+
+        elif 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":
+            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":
+            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("[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":
+            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":
+            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)")
+
+        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"

agents/ocr_agent.py

@@ -0,0 +1,89 @@
+"""
+OCR Agent (v5.4).
+Pure visual perception agent responsible for recognizing text, mathematical formulas, and layout
+from geometry problem images.
+Supports two configurable engines via agent_models.yaml:
+- 'vlm' (default): Direct high-precision, zero-RAM multimodal VLM (Gemini Vision).
+- 'pix2text': Local PyTorch/ONNX Pix2Text engine with Confidence Gateway.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from vision_ocr.canonical_schema import CanonicalOCRResult
+
+logger = logging.getLogger(__name__)
+
+
+class ImprovedOCRAgent:
+    """
+    Math OCR Agent (v5.4).
+    Dynamically routes to Direct Multimodal VLM or Local Pix2Text Engine based on config.
+    """
+
+    def __init__(self, **kwargs):
+        self._vision = None
+        self._vlm_corrector = None
+        logger.info("[ImprovedOCRAgent] Math OCR Agent ready (Configurable VLM / Pix2Text).")
+
+    def _get_engine_mode(self) -> str:
+        try:
+            from config.loader import load_agent_config
+            cfg = load_agent_config("ocr")
+            return getattr(cfg, "ocr_engine", "vlm") or "vlm"
+        except Exception:
+            return "vlm"
+
+    async def process_image_canonical(self, image_path: str) -> CanonicalOCRResult:
+        """
+        Processes image and returns full CanonicalOCRResult structure.
+        """
+        mode = self._get_engine_mode()
+        if mode == "vlm":
+            from agents.vlm_corrector import VLMCorrectorAgent
+            if self._vlm_corrector is None:
+                self._vlm_corrector = VLMCorrectorAgent()
+            return await self._vlm_corrector.extract_direct(image_path=image_path)
+        else:
+            if self._vision is None:
+                from vision_ocr.pipeline import OcrVisionPipeline
+                self._vision = OcrVisionPipeline()
+            return await self._vision.process_image_canonical(image_path)
+
+    async def process_image(self, image_path: str) -> str:
+        """
+        Processes image and returns reconstructed Markdown text containing inline and display LaTeX.
+        """
+        canonical = await self.process_image_canonical(image_path)
+        return canonical.text
+
+    async def process_url_canonical(self, url: str) -> CanonicalOCRResult:
+        """
+        Fetches image from URL and returns full CanonicalOCRResult.
+        """
+        mode = self._get_engine_mode()
+        if mode == "vlm":
+            from agents.vlm_corrector import VLMCorrectorAgent
+            if self._vlm_corrector is None:
+                self._vlm_corrector = VLMCorrectorAgent()
+            return await self._vlm_corrector.extract_direct(image_url=url)
+        else:
+            if self._vision is None:
+                from vision_ocr.pipeline import OcrVisionPipeline
+                self._vision = OcrVisionPipeline()
+            return await self._vision.process_url_canonical(url)
+
+    async def process_url(self, url: str) -> str:
+        """
+        Fetches image from URL and returns reconstructed Markdown text with LaTeX.
+        """
+        canonical = await self.process_url_canonical(url)
+        return canonical.text
+
+
+class OCRAgent(ImprovedOCRAgent):
+    """Alias for backward compatibility."""
+    pass
+

agents/orchestrator.py

@@ -0,0 +1,330 @@
+import json
+import logging
+from typing import Any, Dict, Optional
+
+from agents.geometry_parser_agent import GeometryParserAgent
+from agents.deepmath_solver_agent import DeepMathSolverAgent
+from agents.ocr_agent import OCRAgent
+from app.logutil import log_step
+from app.ocr_celery import ocr_from_image_url
+from manim_client.client import ManimClient
+from manim_client.schemas import build_visualization_spec
+from solver.dsl_parser import DSLParser
+from solver.engine import GeometryEngine
+from solver.validator import GeometryValidator, GeometryStatus
+
+logger = logging.getLogger(__name__)
+
+_CLIP = 2000
+
+
+def _clip(val: Any, n: int = _CLIP) -> Optional[str]:
+    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:
+    log_step(step, input=_clip(input_val), output=_clip(output_val))
+
+
+class Orchestrator:
+    """
+    Refactored AI Core Orchestrator (v6.2 - Manim Video Module & Validation Integration):
+    - GeometryParserAgent (Merged semantic parser & DSL generator)
+    - DSLParser & GeometryEngine (Deterministic coordinate & topology resolver)
+    - GeometryValidator (Strict invariant & constraint validation)
+    - DeepMathSolverAgent (Program-Aided sandboxed SymPy mathematical solver)
+    - ManimClient (Cross-service VisualizationSpec & Video Generation)
+    """
+
+    def __init__(self):
+        self.geometry_parser_agent = GeometryParserAgent()
+        self.deepmath_solver = DeepMathSolverAgent()
+        self.ocr_agent = OCRAgent()
+        self.solver_engine = GeometryEngine()
+        self.dsl_parser = DSLParser()
+        self.geometry_validator = GeometryValidator()
+        self.manim_client = ManimClient()
+
+    def _generate_step_description(self, semantic_json: Dict[str, Any], engine_result: Dict[str, Any]) -> str:
+        """Generates step-by-step drawing instructions based on engine results."""
+        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", [])
+
+        def clean_pt(p: str) -> str:
+            return str(p).replace("_prime", "'")
+
+        for phase in drawing_phases:
+            label = phase.get("label", f"Giai đoạn {phase['phase']}")
+            points = ", ".join([clean_pt(p) for p in phase.get("points", [])])
+            segments = ", ".join([f"{clean_pt(s[0])}{clean_pt(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 {clean_pt(c['center'])} bán kính {c['radius']}.")
+
+        return analysis + "\n".join(steps)
+
+    async def run(
+        self,
+        text: str,
+        image_url: Optional[str] = None,
+        job_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        status_callback=None,
+        history: Optional[list] = None,
+        generate_video: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Runs the streamlined v6.1 AI Core pipeline with Manim Video Module integration.
+        """
+        _step_io(
+            "orchestrate_start",
+            input_val={
+                "job_id": job_id,
+                "text_len": len(text or ""),
+                "image_url": image_url,
+                "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:
+            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
+        ocr_metadata = {}
+        if image_url:
+            ocr_result = await ocr_from_image_url(image_url, self.ocr_agent)
+            input_text = ocr_result.text
+            ocr_metadata = {
+                "ocr_confidence": ocr_result.confidence,
+                "vlm_correction": ocr_result.metadata.get("vlm_correction", False),
+                "original_confidence": ocr_result.metadata.get("original_confidence"),
+            }
+            _step_io("step1_ocr", input_val=image_url, output_val={
+                "text_len": len(input_text),
+                "confidence": ocr_result.confidence,
+                "vlm_correction": ocr_metadata.get("vlm_correction"),
+            })
+        else:
+            _step_io("step1_ocr", input_val="(no image)", output_val=text)
+
+        feedback = None
+        MAX_RETRIES = 2
+        engine_result = None
+        coordinates = {}
+        is_3d = False
+        dsl_code = ""
+        geometry_status = GeometryStatus.FAILED
+        semantic_json: Dict[str, Any] = {}
+
+        # 3. GeometryParserAgent Loop (Semantic Parsing + DSL Generation)
+        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")
+
+            _step_io("step2_geometry_parse", input_val=f"{input_text[:60]}...", output_val=None)
+            semantic_json = await self.geometry_parser_agent.process(
+                input_text, feedback=feedback, context=previous_context
+            )
+            semantic_json["input_text"] = input_text
+            dsl_code = semantic_json.get("geometry_dsl", "")
+            _step_io("step2_geometry_parse", input_val=None, output_val=semantic_json)
+
+            if not dsl_code:
+                dsl_code = f"// Problem text: {input_text}"
+
+            _step_io("step3_dsl_parse", input_val=dsl_code, output_val=None)
+            points, constraints, is_3d = self.dsl_parser.parse(dsl_code)
+            _step_io(
+                "step3_dsl_parse",
+                input_val=None,
+                output_val={
+                    "points": len(points),
+                    "constraints": len(constraints),
+                    "is_3d": is_3d,
+                },
+            )
+
+            # 4. Geometry Solver Engine
+            _step_io("step4_solve_geometry", 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("step4_solve_geometry", input_val=None, output_val=coordinates)
+
+                # Validate geometry against mathematical invariants and constraints
+                val_res = self.geometry_validator.validate(engine_result, constraints, is_3d)
+                _step_io(
+                    "step4_validate_geometry",
+                    input_val=f"{val_res.checked_count} constraints checked",
+                    output_val={"is_valid": val_res.is_valid, "errors": val_res.errors[:3]},
+                )
+
+                if val_res.is_valid:
+                    geometry_status = GeometryStatus.VALID
+                    logger.info(
+                        "[Orchestrator] geometry solved and validated job_id=%s is_3d=%s n_coords=%d",
+                        job_id,
+                        is_3d,
+                        len(coordinates) if isinstance(coordinates, dict) else 0,
+                    )
+                    break
+                else:
+                    structured_fb = val_res.to_structured_feedback()
+                    import json as _json
+                    feedback = f"Geometry validation failed. Structured errors:\n{_json.dumps(structured_fb, ensure_ascii=False, indent=2)}\nPlease correct the DSL to satisfy all constraints."
+                    _step_io("step4_validate_geometry", input_val=f"attempt {attempt + 1}", output_val=feedback)
+            else:
+                feedback = "Geometry solver failed to find a valid solution for the given constraints. Parallelism or lengths might be inconsistent."
+                _step_io("step4_solve_geometry", input_val=f"attempt {attempt + 1}", output_val=feedback)
+
+            if attempt == MAX_RETRIES:
+                # 1. If engine_result produced valid non-empty coordinates, accept them gracefully on final attempt
+                if engine_result and coordinates and len(coordinates) >= 3:
+                    geometry_status = GeometryStatus.DEGRADED
+                    logger.warning("[Orchestrator] Proceeding with DEGRADED coordinates on final attempt despite validation warnings")
+                    break
+
+                # 2. If engine_result is empty, attempt a relaxed solver pass with primary constraints only
+                if points and constraints:
+                    relaxed_constraints = [
+                        c for c in constraints
+                        if c.get("kind") != "AUXILIARY" and c.get("type") in ("length", "polygon", "point", "perpendicular_to_base", "pyramid", "prism", "cube", "tetrahedron")
+                    ]
+                    try:
+                        relaxed_result = await anyio.to_thread.run_sync(self.solver_engine.solve, points, relaxed_constraints, is_3d)
+                        if relaxed_result and relaxed_result.get("coordinates"):
+                            engine_result = relaxed_result
+                            coordinates = relaxed_result.get("coordinates", {})
+                            geometry_status = GeometryStatus.DEGRADED
+                            logger.info("[Orchestrator] Relaxed constraint solve succeeded as DEGRADED fallback")
+                            break
+                    except Exception as e:
+                        logger.warning(f"[Orchestrator] Relaxed solve attempt warning: {e}")
+
+                # 3. If geometry coordinates still cannot be solved, proceed to DeepMath solver so the user still gets the math steps & answer
+                geometry_status = GeometryStatus.FAILED
+                logger.warning("[Orchestrator] Geometry engine exhausted attempts (FAILED); proceeding with semantic data for DeepMath solve")
+                engine_result = engine_result or {"coordinates": {}, "is_3d": is_3d, "drawing_phases": []}
+                break
+
+        # 5. DeepMath Solver (Program-Aided Sandboxed SymPy Reasoning)
+        solution = None
+        _step_io("step5_deepmath_solve", input_val=semantic_json.get("target_question"), output_val=None)
+        solution = await self.deepmath_solver.solve(
+            problem_text=input_text,
+            target_question=semantic_json.get("target_question"),
+            semantic_data=semantic_json,
+            geometry_context=engine_result,
+        )
+        _step_io("step5_deepmath_solve", input_val=None, output_val=solution.get("answer"))
+
+        final_analysis = self._generate_step_description(semantic_json, engine_result or {})
+
+        # 6. Build VisualizationSpec and initiate Manim Video Generation (Async)
+        visualization_info = None
+        if generate_video:
+            try:
+                _step_io("step6_build_visualization_spec", input_val=None, output_val="building")
+                spec = build_visualization_spec(
+                    problem_text=input_text,
+                    solution_steps=solution.get("steps", []) if solution else [],
+                    coordinates=coordinates,
+                    engine_result=engine_result,
+                    semantic_data=semantic_json,
+                    is_3d=is_3d,
+                )
+                _step_io(
+                    "step6_build_visualization_spec",
+                    input_val=None,
+                    output_val={
+                        "geometry_objects": len(spec.geometry),
+                        "animation_beats": len(spec.animations),
+                    },
+                )
+
+                # Submit job to Manim Video Module
+                render_resp = await self.manim_client.submit_render_job(spec)
+                render_dict = render_resp.to_dict()
+                visualization_info = {
+                    "spec": spec.model_dump(mode="json"),
+                    "job_id": str(render_resp.job_id),
+                    "project_id": str(render_resp.project_id) if render_resp.project_id else None,
+                    "status": render_resp.status,
+                    "video_url": render_resp.video_url,
+                    "error": render_dict.get("error"),
+                }
+                _step_io(
+                    "step7_manim_job_submitted",
+                    input_val=str(render_resp.job_id),
+                    output_val=render_resp.status,
+                )
+            except Exception as e:
+                logger.warning(f"[Orchestrator] Failed to package VisualizationSpec / contact Manim: {e}")
+                visualization_info = {
+                    "status": "failed",
+                    "error": str(e),
+                }
+
+        _step_io("orchestrate_done", input_val=job_id, output_val="success")
+
+        return {
+            "status": "success",
+            "job_id": job_id,
+            "geometry_status": geometry_status.value,
+            "ocr_metadata": ocr_metadata,
+            "geometry_dsl": dsl_code,
+            "coordinates": coordinates,
+            "polygon_order": (engine_result or {}).get("polygon_order", []),
+            "circles": (engine_result or {}).get("circles", []),
+            "solids": (engine_result or {}).get("solids", []),
+            "faces": (engine_result or {}).get("faces", []),
+            "lines": (engine_result or {}).get("lines", []),
+            "rays": (engine_result or {}).get("rays", []),
+            "drawing_phases": (engine_result or {}).get("drawing_phases", []),
+            "visualization_graph": (engine_result or {}).get("visualization_graph"),
+            "geometry_objects": (engine_result or {}).get("geometry_objects", []),
+            "auxiliary": (engine_result or {}).get("auxiliary", []),
+            "semantic": semantic_json,
+            "semantic_analysis": final_analysis,
+            "solution": solution,
+            "visualization": visualization_info,
+            "is_3d": is_3d,
+        }

agents/renderer_agent.py

@@ -0,0 +1,5 @@
+"""Shim: geometry rendering lives in ``geometry_render`` (worker-safe package)."""
+
+from geometry_render.renderer import RendererAgent
+
+__all__ = ["RendererAgent"]

agents/runtime.py

@@ -0,0 +1,122 @@
+import inspect
+import logging
+from typing import List, Dict, Any, Optional, Callable, Tuple, Union
+from config.loader import load_agent_config
+from config.schemas import AgentConfig
+from llm.service import LLMService, get_llm_service
+
+logger = logging.getLogger(__name__)
+
+
+class AgentRuntime:
+    """
+    Agent Runtime & Cascading Controller:
+    Coordinates agent configuration resolution, model tier escalation, and programmatic validation.
+    """
+
+    def __init__(self, llm_service: Optional[LLMService] = None):
+        self.llm_service = llm_service or get_llm_service()
+
+    async def run(
+        self,
+        agent: str,
+        messages: List[Dict[str, Any]],
+        validator: Optional[Callable[[str], Union[Tuple[bool, Any], Any]]] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ) -> Any:
+        """
+        Executes an agent run across tiered model cascades with validator-guided escalation.
+        Temperature and max_tokens are always resolved from AgentConfig (single source of truth).
+        """
+        config: AgentConfig = load_agent_config(agent)
+        temperature = config.temperature
+        max_tokens = config.max_tokens
+
+        last_error = None
+        current_messages = list(messages)
+
+        logger.info(f"[AgentRuntime] Starting run for agent '{agent}' with {len(config.tiers)} tier(s)...")
+
+        for tier_idx, tier in enumerate(config.tiers, start=1):
+            for attempt in range(tier.max_attempts):
+                logger.info(
+                    f"[AgentRuntime] Agent '{agent}' Tier {tier_idx}/{len(config.tiers)} "
+                    f"({tier.model}) - Attempt {attempt + 1}/{tier.max_attempts}"
+                )
+
+                try:
+                    tier_reasoning_effort = tier.reasoning_effort if tier.reasoning_effort is not None else config.reasoning_effort
+                    raw_output = await self.llm_service.acomplete(
+                        model=tier.model,
+                        messages=current_messages,
+                        temperature=temperature,
+                        max_tokens=max_tokens,
+                        timeout=config.timeout_seconds,
+                        response_format=response_format,
+                        reasoning_effort=tier_reasoning_effort,
+                        agent_name=agent,
+                        tier_index=tier_idx,
+                        **kwargs
+                    )
+
+                    # Programmatic validation (Level 2 Cascade Trigger)
+                    if validator:
+                        try:
+                            if inspect.iscoroutinefunction(validator):
+                                val_result = await validator(raw_output)
+                            else:
+                                val_result = validator(raw_output)
+
+                            # Expect (is_valid, payload_or_error)
+                            if isinstance(val_result, tuple) and len(val_result) == 2:
+                                is_valid, payload = val_result
+                                if is_valid:
+                                    logger.info(
+                                        f"[AgentRuntime] Agent '{agent}' Tier {tier_idx} validation PASSED."
+                                    )
+                                    return payload
+                                else:
+                                    logger.warning(
+                                        f"[AgentRuntime] Agent '{agent}' Tier {tier_idx} validation FAILED: {payload}. "
+                                        "Escalating..."
+                                    )
+                                    # Provide feedback to conversation context for subsequent attempts
+                                    current_messages.append({"role": "assistant", "content": raw_output})
+                                    current_messages.append({
+                                        "role": "user",
+                                        "content": f"Your previous output failed validation: {payload}. Please correct the issues and provide a valid response."
+                                    })
+                                    continue
+                            elif bool(val_result):
+                                return val_result
+                        except Exception as val_e:
+                            logger.warning(
+                                f"[AgentRuntime] Validator raised exception on Tier {tier_idx}: {val_e}. Escalating..."
+                            )
+                            last_error = val_e
+                            continue
+                    else:
+                        # No validator required, output is accepted
+                        return raw_output
+
+                except Exception as tier_e:
+                    logger.warning(
+                        f"[AgentRuntime] Tier {tier_idx} attempt {attempt + 1} failed: {tier_e}"
+                    )
+                    last_error = tier_e
+
+        # All model tiers exhausted
+        raise RuntimeError(
+            f"Agent '{agent}' cascade exhausted all {len(config.tiers)} model tiers. Last error: {last_error}"
+        )
+
+
+_GLOBAL_AGENT_RUNTIME: Optional[AgentRuntime] = None
+
+
+def get_agent_runtime() -> AgentRuntime:
+    global _GLOBAL_AGENT_RUNTIME
+    if _GLOBAL_AGENT_RUNTIME is None:
+        _GLOBAL_AGENT_RUNTIME = AgentRuntime()
+    return _GLOBAL_AGENT_RUNTIME

agents/torch_ultralytics_compat.py

@@ -0,0 +1,5 @@
+"""Shim: moved to ``vision_ocr.compat`` for OCR worker isolation."""
+
+from vision_ocr.compat import allow_ultralytics_weights
+
+__all__ = ["allow_ultralytics_weights"]

agents/vlm_corrector.py

@@ -0,0 +1,269 @@
+"""
+VLM OCR Corrector Agent.
+
+Uses a multimodal Vision-Language Model to correct OCR errors when confidence is low.
+Strictly adheres to READ/CORRECT/PRESERVE boundaries — never SOLVE/INFER/INVENT.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import re
+from typing import Any, Dict, List, Optional
+
+from config.schemas import OCRCorrectionConfig
+from llm.service import get_llm_service
+from vision_ocr.canonical_schema import CanonicalOCRResult
+
+logger = logging.getLogger(__name__)
+
+
+class VLMCorrectorAgent:
+    """
+    VLM-based OCR correction agent.
+
+    Receives raw image + OCR output + confidence and uses a multimodal LLM
+    to correct OCR recognition errors.
+
+    Strict boundary:
+    - READ: Re-read text and formulas from the image
+    - CORRECT: Fix OCR misrecognitions
+    - PRESERVE: Keep all original information intact
+
+    Never:
+    - SOLVE: Do not solve the math problem
+    - INFER: Do not infer missing geometry values
+    - INVENT: Do not add information not visible in the image
+    """
+
+    def __init__(self, config: Optional[OCRCorrectionConfig] = None):
+        self.config = config or OCRCorrectionConfig()
+        self.llm_service = get_llm_service()
+
+    async def extract_direct(
+        self,
+        image_url: Optional[str] = None,
+        image_path: Optional[str] = None,
+    ) -> CanonicalOCRResult:
+        """
+        Direct multimodal VLM OCR extraction from image.
+        Accurately transcribes Vietnamese text, mathematical formulas, and LaTeX symbols.
+        """
+        if not image_url and not image_path:
+            logger.warning("[VLMCorrector] No image provided for direct extraction")
+            return CanonicalOCRResult(text="", confidence=0.0)
+
+        # Convert local image to base64 data URI if needed
+        if image_path and not image_url and os.path.exists(image_path):
+            import base64
+            with open(image_path, "rb") as f:
+                b64 = base64.b64encode(f.read()).decode("utf-8")
+                ext = os.path.splitext(image_path)[1].lstrip(".").lower()
+                mime = "image/jpeg" if ext in ("jpg", "jpeg") else ("image/webp" if ext == "webp" else "image/png")
+                image_url = f"data:{mime};base64,{b64}"
+
+        if not image_url:
+            return CanonicalOCRResult(text="", confidence=0.0)
+
+        system_prompt = """You are a High-Precision Math OCR Vision Agent for Vietnamese mathematical and geometry problems.
+
+=== YOUR TASK ===
+Carefully transcribe all printed/handwritten text, mathematical formulas, geometric terms, and notation from the image into Markdown format.
+Use standard LaTeX math syntax:
+- Inline formulas and geometric variables: $...$ (e.g. $ABCD$, $SO=12$, $(MED)$)
+- Display math equations: $$...$$
+
+=== STRICT RULES ===
+1. READ & TRANSCRIBE ONLY: Transcribe exactly what is visible in the image.
+2. DO NOT SOLVE: Do not solve the problem or add your own calculations.
+3. PRESERVE VIETNAMESE ACCENTS & DIACRITICS: Ensure all Vietnamese words have correct diacritics and correct spelling.
+4. Output ONLY the raw transcribed text. Do NOT wrap your output in markdown code blocks (such as ```markdown)."""
+
+        user_content_parts = [
+            {"type": "image_url", "image_url": {"url": image_url}},
+            {"type": "text", "text": "Please transcribe the entire math problem from this image accurately."},
+        ]
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content_parts},
+        ]
+
+        try:
+            raw_response = await self.llm_service.acomplete(
+                model=self.config.model,
+                messages=messages,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+                timeout=self.config.timeout_seconds,
+                agent_name="vlm_ocr_direct",
+            )
+            text = raw_response.strip()
+            # Clean possible markdown code fences
+            m = re.match(r"^```(?:markdown|latex|text)?\s*(.*?)\s*```$", text, re.DOTALL)
+            if m:
+                text = m.group(1).strip()
+
+            return CanonicalOCRResult(
+                text=text,
+                confidence=0.98,
+                metadata={"engine": "vlm_direct", "model": self.config.model},
+            )
+        except Exception as e:
+            logger.error(f"[VLMCorrector] Direct VLM extraction failed: {e}")
+            return CanonicalOCRResult(
+                text="",
+                confidence=0.0,
+                metadata={"error": str(e)},
+            )
+
+    async def correct(
+        self,
+        ocr_result: CanonicalOCRResult,
+        image_url: Optional[str] = None,
+        image_path: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Correct OCR errors using VLM.
+
+        Args:
+            ocr_result: The original OCR result with text and confidence
+            image_url: URL of the original image (for multimodal input)
+            image_path: Local path to the original image
+
+        Returns:
+            Dict with corrected_text, changed, confidence, corrections[]
+        """
+        if not image_url and not image_path:
+            logger.warning("[VLMCorrector] No image provided, skipping correction")
+            return {"changed": False, "corrected_text": ocr_result.text, "confidence": ocr_result.confidence, "corrections": []}
+
+        system_prompt = """You are an OCR Correction Agent for Vietnamese mathematical geometry problems.
+
+=== YOUR TASK ===
+You receive:
+1. An image of a math problem
+2. OCR-extracted text (which may contain errors)
+3. OCR confidence score
+
+Your job is to CORRECT OCR recognition errors by re-reading the image carefully.
+
+=== STRICT BOUNDARIES ===
+You MUST ONLY:
+- READ: Re-read text, numbers, and mathematical formulas from the image
+- CORRECT: Fix misrecognized characters, numbers, symbols, and LaTeX
+- PRESERVE: Keep all original information intact
+
+You MUST NOT:
+- SOLVE: Do not solve or attempt to solve the math problem
+- INFER: Do not infer missing values or geometry relationships
+- INVENT: Do not add any information not visible in the image
+- If a value is unclear or unreadable, mark it as "?" — do NOT guess
+
+=== OUTPUT FORMAT ===
+Output ONLY a JSON object:
+{
+    "corrected_text": "The corrected full text with proper LaTeX",
+    "changed": true/false,
+    "confidence": 0.95,
+    "corrections": [
+        {
+            "original": "SA = 8",
+            "corrected": "SA = 6",
+            "reason": "OCR misread digit 6 as 8"
+        }
+    ]
+}
+
+If no corrections are needed, set "changed": false and return the original text."""
+
+        user_content_parts = []
+
+        # Add image content for multimodal input
+        if image_path and not image_url and os.path.exists(image_path):
+            import base64
+            with open(image_path, "rb") as f:
+                b64 = base64.b64encode(f.read()).decode("utf-8")
+                ext = os.path.splitext(image_path)[1].lstrip(".").lower()
+                mime = "image/jpeg" if ext in ("jpg", "jpeg") else ("image/webp" if ext == "webp" else "image/png")
+                image_url = f"data:{mime};base64,{b64}"
+
+        if image_url:
+            user_content_parts.append({
+                "type": "image_url",
+                "image_url": {"url": image_url},
+            })
+
+        user_content_parts.append({
+            "type": "text",
+            "text": f"""OCR Extracted Text (confidence: {ocr_result.confidence:.3f}):
+
+{ocr_result.text}
+
+Please carefully compare the image with the OCR text above and correct any recognition errors.""",
+        })
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content_parts},
+        ]
+
+        try:
+            raw_response = await self.llm_service.acomplete(
+                model=self.config.model,
+                messages=messages,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+                timeout=self.config.timeout_seconds,
+                agent_name="vlm_corrector",
+            )
+
+            result = self._parse_correction_response(raw_response, ocr_result.text)
+            logger.info(
+                f"[VLMCorrector] Correction result: changed={result.get('changed')}, "
+                f"corrections={len(result.get('corrections', []))}"
+            )
+            return result
+
+        except Exception as e:
+            logger.error(f"[VLMCorrector] Correction failed: {e}")
+            return {
+                "changed": False,
+                "corrected_text": ocr_result.text,
+                "confidence": ocr_result.confidence,
+                "corrections": [],
+            }
+
+    def _parse_correction_response(self, raw: str, original_text: str) -> Dict[str, Any]:
+        """Parse VLM correction response JSON."""
+        try:
+            cleaned = raw.strip()
+            # Extract JSON from markdown code block if present
+            json_match = re.search(r"```(?:json)?\s*(.*?)\s*```", cleaned, re.DOTALL)
+            if json_match:
+                cleaned = json_match.group(1).strip()
+
+            # Try direct JSON parse
+            brace_match = re.search(r"(\{.*\})", cleaned, re.DOTALL)
+            if brace_match:
+                cleaned = brace_match.group(1)
+
+            data = json.loads(cleaned)
+
+            return {
+                "corrected_text": data.get("corrected_text", original_text),
+                "changed": bool(data.get("changed", False)),
+                "confidence": float(data.get("confidence", 0.9)),
+                "corrections": data.get("corrections", []),
+            }
+        except (json.JSONDecodeError, Exception) as e:
+            logger.warning(f"[VLMCorrector] Failed to parse response: {e}")
+            return {
+                "changed": False,
+                "corrected_text": original_text,
+                "confidence": 0.5,
+                "corrections": [],
+            }

app/celery_app.py

@@ -0,0 +1,50 @@
+"""Celery Application configuration for asynchronous background worker jobs."""
+
+from __future__ import annotations
+
+import logging
+import os
+from celery import Celery
+
+logger = logging.getLogger(__name__)
+
+REDIS_URL = os.getenv("REDIS_URL") or os.getenv("CELERY_BROKER_URL") or "redis://localhost:6379/0"
+
+celery_app = Celery(
+    "mathsolver_worker",
+    broker=REDIS_URL,
+    backend=REDIS_URL,
+    include=["app.tasks"],
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    accept_content=["json"],
+    result_serializer="json",
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+    task_time_limit=900,  # 15 minutes max
+    task_soft_time_limit=840,
+    worker_prefetch_multiplier=1,
+    worker_concurrency=int(os.getenv("CELERY_CONCURRENCY", "4")),
+    task_acks_late=True,
+    task_reject_on_worker_lost=True,
+)
+
+
+def is_celery_available() -> bool:
+    """
+    Check if Celery / Redis broker is configured and reachable.
+    Returns False when running in minimal dev/test environments without Redis.
+    """
+    disable_celery = os.getenv("DISABLE_CELERY", "0").lower() in ("1", "true", "yes")
+    if disable_celery:
+        return False
+    try:
+        import redis
+        client = redis.from_url(REDIS_URL, socket_connect_timeout=0.5, socket_timeout=0.5)
+        client.ping()
+        return True
+    except Exception:
+        return False

app/chat_image_upload.py

@@ -0,0 +1,253 @@
+"""Validate and upload chat/solve attachment images to Supabase Storage (image bucket)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from typing import Any, Dict, Tuple
+
+from fastapi import HTTPException
+
+logger = logging.getLogger(__name__)
+
+
+def _get_next_image_version(session_id: str) -> int:
+    """Same logic as worker.asset_manager.get_next_version for asset_type image."""
+    from app.supabase_client import get_supabase
+
+    supabase = get_supabase()
+    try:
+        res = (
+            supabase.table("session_assets")
+            .select("version")
+            .eq("session_id", session_id)
+            .eq("asset_type", "image")
+            .order("version", desc=True)
+            .limit(1)
+            .execute()
+        )
+        if res.data:
+            return res.data[0]["version"] + 1
+        return 1
+    except Exception as e:
+        logger.error("Error fetching image version: %s", e)
+        return 1
+
+_MAX_BYTES_DEFAULT = 10 * 1024 * 1024
+
+_EXT_TO_MIME: dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+}
+
+
+def _max_bytes() -> int:
+    raw = os.getenv("CHAT_IMAGE_MAX_BYTES")
+    if raw and raw.isdigit():
+        return min(int(raw), 50 * 1024 * 1024)
+    return _MAX_BYTES_DEFAULT
+
+
+def _magic_ok(ext: str, body: bytes) -> bool:
+    if len(body) < 2:
+        return False
+    if ext == ".png":
+        return len(body) >= 8 and body.startswith(b"\x89PNG\r\n\x1a\n")
+    if ext in (".jpg", ".jpeg"):
+        return len(body) >= 3 and body.startswith(b"\xff\xd8\xff")
+    if ext == ".webp":
+        return len(body) >= 12 and body.startswith(b"RIFF") and body[8:12] == b"WEBP"
+    if ext == ".gif":
+        return len(body) >= 6 and (body.startswith(b"GIF87a") or body.startswith(b"GIF89a"))
+    if ext == ".bmp":
+        return len(body) >= 2 and body.startswith(b"BM")
+    return False
+
+
+def validate_chat_image_bytes(
+    filename: str | None,
+    body: bytes,
+    declared_content_type: str | None,
+) -> Tuple[str, str]:
+    """
+    Validate size, extension, and magic bytes.
+    Returns (extension_with_dot, content_type).
+    """
+    max_b = _max_bytes()
+    if not body:
+        raise HTTPException(status_code=400, detail="Empty file.")
+    if len(body) > max_b:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Image too large (max {max_b // (1024 * 1024)} MB).",
+        )
+
+    ext = os.path.splitext(filename or "")[1].lower()
+    if not ext:
+        ext = ".png"
+    if ext not in _EXT_TO_MIME:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported image type: {ext}. Allowed: {', '.join(sorted(_EXT_TO_MIME))}",
+        )
+
+    if not _magic_ok(ext, body):
+        raise HTTPException(
+            status_code=400,
+            detail="File content does not match declared image type.",
+        )
+
+    mime = _EXT_TO_MIME[ext]
+    if declared_content_type:
+        decl = declared_content_type.split(";")[0].strip().lower()
+        if decl and decl not in ("application/octet-stream", mime) and decl != mime:
+            logger.warning(
+                "Content-Type mismatch (declared=%s, inferred=%s); using inferred.",
+                declared_content_type,
+                mime,
+            )
+    return ext, mime
+
+
+def upload_session_chat_image(
+    session_id: str,
+    job_id: str,
+    file_bytes: bytes,
+    ext_with_dot: str,
+    content_type: str,
+) -> Dict[str, Any]:
+    """
+    Upload to SUPABASE_IMAGE_BUCKET (default: image), insert session_assets row.
+    Returns dict with public_url, storage_path, version, session_asset_id (if returned).
+    """
+    from app.supabase_client import get_supabase
+
+    supabase = get_supabase()
+    bucket_name = os.getenv("SUPABASE_IMAGE_BUCKET", "image")
+    raw_ext = ext_with_dot.lstrip(".").lower()
+
+    max_retries = 3
+    last_err = None
+    for attempt in range(max_retries):
+        version = _get_next_image_version(session_id) + attempt
+        file_name = f"image_v{version}_{job_id}.{raw_ext}"
+        storage_path = f"sessions/{session_id}/{file_name}"
+
+        try:
+            supabase.storage.from_(bucket_name).upload(
+                path=storage_path,
+                file=file_bytes,
+                file_options={"content-type": content_type, "upsert": "true"},
+            )
+            public_url = supabase.storage.from_(bucket_name).get_public_url(storage_path)
+            if isinstance(public_url, dict):
+                public_url = public_url.get("publicUrl") or public_url.get("public_url") or str(public_url)
+
+            row = {
+                "session_id": session_id,
+                "job_id": job_id,
+                "asset_type": "image",
+                "storage_path": storage_path,
+                "public_url": public_url,
+                "version": version,
+            }
+            ins = supabase.table("session_assets").insert(row).select("id").execute()
+            asset_id = None
+            if ins.data and len(ins.data) > 0:
+                asset_id = ins.data[0].get("id")
+
+            log_data = {
+                "public_url": public_url,
+                "storage_path": storage_path,
+                "version": version,
+                "session_asset_id": str(asset_id) if asset_id else None,
+            }
+            logger.info("Uploaded chat image: %s", log_data)
+            return {
+                "public_url": public_url,
+                "storage_path": storage_path,
+                "version": version,
+                "session_asset_id": str(asset_id) if asset_id else None,
+            }
+        except Exception as e:
+            last_err = e
+            logger.warning(
+                "Retry uploading chat image for session %s (attempt %d/%d): %s",
+                session_id,
+                attempt + 1,
+                max_retries,
+                e,
+            )
+
+    raise HTTPException(
+        status_code=500,
+        detail=f"Failed to upload image after {max_retries} attempts: {last_err}",
+    )
+
+
+def upload_ephemeral_ocr_blob(
+    file_bytes: bytes,
+    ext_with_dot: str,
+    content_type: str,
+) -> Tuple[str, str]:
+    """
+    Upload bytes to image bucket under _ocr_temp/ for worker-only OCR (no session_assets row).
+    Returns (storage_path, public_url). Caller must delete_storage_object when done.
+    """
+    from app.supabase_client import get_supabase
+
+    bucket_name = os.getenv("SUPABASE_IMAGE_BUCKET", "image")
+    raw_ext = ext_with_dot.lstrip(".").lower() or "png"
+    name = f"_ocr_temp/{uuid.uuid4().hex}.{raw_ext}"
+    supabase = get_supabase()
+    supabase.storage.from_(bucket_name).upload(
+        path=name,
+        file=file_bytes,
+        file_options={"content-type": content_type},
+    )
+    public_url = supabase.storage.from_(bucket_name).get_public_url(name)
+    if isinstance(public_url, dict):
+        public_url = public_url.get("publicUrl") or public_url.get("public_url") or str(public_url)
+    return name, public_url
+
+
+def delete_storage_object(bucket_name: str, storage_path: str) -> None:
+    try:
+        from app.supabase_client import get_supabase
+
+        supabase = get_supabase()
+        if supabase:
+            supabase.storage.from_(bucket_name).remove([storage_path])
+    except Exception as e:
+        logger.warning("delete_storage_object failed path=%s: %s", storage_path, e)
+
+
+def cleanup_session_storage(session_id: str) -> None:
+    """List and delete all storage files in video and image buckets under sessions/{session_id}/."""
+    from app.supabase_client import get_supabase
+
+    supabase = get_supabase()
+    if not supabase:
+        return
+
+    folder = f"sessions/{session_id}"
+    for bucket in ["image", os.getenv("SUPABASE_BUCKET", "video")]:
+        try:
+            items = supabase.storage.from_(bucket).list(folder)
+            if items:
+                paths_to_remove = []
+                for item in items:
+                    name = item.get("name") if isinstance(item, dict) else getattr(item, "name", None)
+                    if name and name != ".emptyFolderPlaceholder":
+                        paths_to_remove.append(f"{folder}/{name}")
+                if paths_to_remove:
+                    supabase.storage.from_(bucket).remove(paths_to_remove)
+                    logger.info("Cleaned up %d objects in bucket '%s' for session %s", len(paths_to_remove), bucket, session_id)
+        except Exception as e:
+            logger.warning("Failed to clean up storage bucket '%s' for session %s: %s", bucket, session_id, e)
+

app/dependencies.py

@@ -0,0 +1,80 @@
+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 | None = Header(None)):
+    """
+    Authenticate user using Supabase JWT.
+    Expected Header: Authorization: Bearer <token>
+    """
+    import os
+
+    if not authorization:
+        raise HTTPException(
+            status_code=401,
+            detail="Authorization header missing or invalid. Use 'Bearer <token>'",
+        )
+
+    if os.getenv("ALLOW_TEST_BYPASS") == "true" and authorization.startswith("Test "):
+        return authorization.split(" ")[1]
+
+    if 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.
+    """
+    import os
+
+    if not authorization:
+        raise HTTPException(
+            status_code=401,
+            detail="Authorization header missing or invalid. Use 'Bearer <token>'",
+        )
+
+    if os.getenv("ALLOW_TEST_BYPASS") == "true" and authorization.startswith("Test "):
+        return get_supabase()
+
+    if 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/job_poll.py

@@ -0,0 +1,82 @@
+"""Normalize Supabase `jobs` rows for polling / WebSocket clients (stable `job_id` + JSON `result`)."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _coerce_result(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (dict, list)):
+        return value
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError:
+            logger.warning("job_poll: result is non-JSON string, returning raw")
+            return {"raw": value}
+    return value
+
+
+from app.models.job_state import JobStateMachine, JobStatus, STAGE_PROGRESS_MAP, JobStage
+
+
+def normalize_job_row_for_client(row: dict[str, Any]) -> dict[str, Any]:
+    """
+    Build a JSON-serializable dict that conforms to P1 Job State Machine:
+    - ``job_id`` (alias of DB ``id``)
+    - ``status`` normalized (e.g. 'processing', 'completed', 'failed', 'queued')
+    - ``stage`` extracted from row or inferred (e.g. 'ocr', 'parsing', 'geometry', 'solving', 'rendering')
+    - ``progress`` integer 0-100
+    - ``result`` object/array
+    All other columns are passed through cleanly.
+    """
+    out = dict(row)
+    jid = out.get("id")
+    if jid is not None:
+        out["job_id"] = str(jid)
+    
+    st_raw = out.get("status")
+    normalized_status = JobStateMachine.normalize_status(st_raw)
+    out["status"] = normalized_status.value
+
+    # Extract or infer stage
+    stage_raw = out.get("stage")
+    normalized_stage = JobStateMachine.normalize_stage(stage_raw)
+    if not normalized_stage and normalized_status == JobStatus.PROCESSING:
+        if st_raw in ("ocr", "parsing", "geometry", "solving", "rendering"):
+            normalized_stage = JobStage(st_raw)
+    
+    out["stage"] = normalized_stage.value if normalized_stage else None
+
+    # Calculate or normalize progress
+    if "progress" in out and out["progress"] is not None:
+        try:
+            out["progress"] = int(out["progress"])
+        except (ValueError, TypeError):
+            out["progress"] = STAGE_PROGRESS_MAP.get(normalized_stage, 50) if normalized_stage else (100 if normalized_status == JobStatus.COMPLETED else 0)
+    else:
+        if normalized_status == JobStatus.COMPLETED:
+            out["progress"] = 100
+        elif normalized_status == JobStatus.QUEUED:
+            out["progress"] = 5
+        elif normalized_stage and normalized_stage in STAGE_PROGRESS_MAP:
+            out["progress"] = STAGE_PROGRESS_MAP[normalized_stage]
+        elif normalized_status == JobStatus.PROCESSING:
+            out["progress"] = 50
+        else:
+            out["progress"] = 0
+
+    if "result" in out:
+        out["result"] = _coerce_result(out.get("result"))
+    if out.get("user_id") is not None:
+        out["user_id"] = str(out["user_id"])
+    if out.get("session_id") is not None:
+        out["session_id"] = str(out["session_id"])
+    return out
+

app/llm_client.py

@@ -0,0 +1,53 @@
+import logging
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+from llm.service import get_llm_service, LLMService
+from config.loader import load_agent_config
+
+
+class MultiLayerLLMClient:
+    """
+    Backward-compatible client adapter that delegates completions to LLMService.
+    Uses agent config for defaults but allows callers to override temperature/max_tokens
+    for ad-hoc usage (e.g. knowledge queries, chat completions).
+    """
+
+    def __init__(self):
+        self.service: LLMService = get_llm_service()
+
+    async def chat_completions_create(
+        self,
+        messages: List[Dict[str, Any]],
+        response_format: Optional[Dict[str, Any]] = None,
+        agent: str = "reasoning_solver",
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        **kwargs
+    ) -> str:
+        config = load_agent_config(agent)
+        model = config.tiers[0].model if config.tiers else "gemini/gemini-3.7-flash"
+        return await self.service.acomplete(
+            model=model,
+            messages=messages,
+            temperature=temperature if temperature is not None else config.temperature,
+            max_tokens=max_tokens if max_tokens is not None else config.max_tokens,
+            timeout=config.timeout_seconds,
+            response_format=response_format,
+            reasoning_effort=config.reasoning_effort,
+            agent_name=agent,
+            **kwargs
+        )
+
+
+_llm_client: Optional[MultiLayerLLMClient] = 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,143 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+import uuid
+import warnings
+
+from dotenv import load_dotenv
+from fastapi import Depends, 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.dependencies import get_current_user_id
+from app.ocr_local_file import ocr_from_local_image_path
+from app.routers import auth, sessions, solve, ai_core
+from agents.ocr_agent import OCRAgent
+from app.routers.solve import get_orchestrator
+from app.job_poll import normalize_job_row_for_client
+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 v5.2")
+
+
+@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
+
+
+_redis_url = os.getenv("REDIS_URL") or os.getenv("CELERY_BROKER_URL") or "none"
+_redis_tail = _redis_url.split("@")[-1] if "@" in _redis_url else _redis_url
+if get_log_level() in ("debug", "info"):
+    logger.info("App starting LOG_LEVEL=%s | Redis: %s", get_log_level(), _redis_tail)
+else:
+    logger.warning("App starting LOG_LEVEL=%s | Redis: %s", get_log_level(), _redis_tail)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+        "http://localhost:3005",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(ai_core.router)
+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
+
+
+@app.get("/")
+def read_root():
+    return {
+        "message": "Visual Math Solver API v5.2 is running",
+        "version": "5.2",
+        "ai_core_direct_endpoint": "/api/v1/ai/solve"
+    }
+
+
+@app.post("/api/v1/ocr")
+async def upload_ocr(
+    file: UploadFile = File(...),
+    _user_id=Depends(get_current_user_id),
+):
+    """OCR upload: requires authenticated user."""
+    temp_path = f"temp_{uuid.uuid4()}.png"
+    with open(temp_path, "wb") as buffer:
+        buffer.write(await file.read())
+
+    try:
+        text = await ocr_from_local_image_path(temp_path, file.filename, get_ocr_agent())
+        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,
+    user_id=Depends(get_current_user_id),
+):
+    """Retrieve job status (can be used for polling if WS fails). Owner-only."""
+    supabase_client = get_supabase()
+    if not supabase_client:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    response = supabase_client.table("jobs").select("*").eq("id", job_id).execute()
+    if not response.data:
+        raise HTTPException(status_code=404, detail="Job not found")
+    job = response.data[0]
+    if job.get("user_id") is not None and str(job["user_id"]) != str(user_id):
+        raise HTTPException(status_code=403, detail="Forbidden: You do not own this job.")
+    return normalize_job_row_for_client(job)

app/models/job_state.py

@@ -0,0 +1,132 @@
+"""Formalized Job State Machine & Lifecycle Definitions for MathSolver."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional, Set
+from pydantic import BaseModel, Field
+
+
+class JobStatus(str, Enum):
+    CREATED = "created"
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    DEGRADED = "degraded"
+    CANCELLED = "cancelled"
+
+
+class JobStage(str, Enum):
+    OCR = "ocr"
+    PARSING = "parsing"
+    GEOMETRY = "geometry"
+    SOLVING = "solving"
+    RENDERING = "rendering"
+
+
+# Canonical progression of stages with default estimated progress percentages
+STAGE_PROGRESS_MAP: Dict[JobStage, int] = {
+    JobStage.OCR: 15,
+    JobStage.PARSING: 35,
+    JobStage.GEOMETRY: 65,
+    JobStage.SOLVING: 85,
+    JobStage.RENDERING: 95,
+}
+
+# Valid State Transitions
+VALID_TRANSITIONS: Dict[JobStatus, Set[JobStatus]] = {
+    JobStatus.CREATED: {
+        JobStatus.CREATED,
+        JobStatus.QUEUED,
+        JobStatus.PROCESSING,
+        JobStatus.FAILED,
+        JobStatus.CANCELLED,
+    },
+    JobStatus.QUEUED: {
+        JobStatus.QUEUED,
+        JobStatus.PROCESSING,
+        JobStatus.FAILED,
+        JobStatus.CANCELLED,
+    },
+    JobStatus.PROCESSING: {
+        JobStatus.PROCESSING,
+        JobStatus.COMPLETED,
+        JobStatus.DEGRADED,
+        JobStatus.FAILED,
+        JobStatus.CANCELLED,
+    },
+    # Terminal states
+    JobStatus.COMPLETED: {JobStatus.COMPLETED},
+    JobStatus.FAILED: {JobStatus.FAILED},
+    JobStatus.DEGRADED: {JobStatus.DEGRADED},
+    JobStatus.CANCELLED: {JobStatus.CANCELLED},
+}
+
+
+class InvalidStateTransitionError(ValueError):
+    """Raised when an illegal job state transition is attempted."""
+    pass
+
+
+class JobStateMachine:
+    """Validator and manager for job lifecycle transitions."""
+
+    @staticmethod
+    def normalize_status(raw_status: Optional[str]) -> JobStatus:
+        if not raw_status:
+            return JobStatus.PROCESSING
+        raw = raw_status.lower().strip()
+        # Aliases for backward compatibility
+        if raw in ("success", "done", "finished", "completed"):
+            return JobStatus.COMPLETED
+        if raw in ("error", "failed", "failure"):
+            return JobStatus.FAILED
+        if raw in ("rendering_queued", "queued"):
+            return JobStatus.QUEUED
+        if raw in ("rendering", "processing", "solving", "ocr", "parsing", "geometry"):
+            return JobStatus.PROCESSING
+        if raw == "cancelled":
+            return JobStatus.CANCELLED
+        if raw == "degraded":
+            return JobStatus.DEGRADED
+        return JobStatus.PROCESSING
+
+    @staticmethod
+    def normalize_stage(raw_stage: Optional[str]) -> Optional[JobStage]:
+        if not raw_stage:
+            return None
+        raw = raw_stage.lower().strip()
+        for stage in JobStage:
+            if stage.value == raw:
+                return stage
+        return None
+
+    @classmethod
+    def can_transition(cls, current: JobStatus, target: JobStatus) -> bool:
+        valid_targets = VALID_TRANSITIONS.get(current, set())
+        return target in valid_targets
+
+    @classmethod
+    def validate_transition(cls, current_status: str | JobStatus, target_status: str | JobStatus) -> JobStatus:
+        current = current_status if isinstance(current_status, JobStatus) else cls.normalize_status(current_status)
+        target = target_status if isinstance(target_status, JobStatus) else cls.normalize_status(target_status)
+
+        if not cls.can_transition(current, target):
+            raise InvalidStateTransitionError(
+                f"Invalid job state transition from {current.value} to {target.value}"
+            )
+        return target
+
+
+class JobEventPayload(BaseModel):
+    """Normalized payload broadcasted via WebSockets and returned by HTTP polling."""
+    job_id: str
+    status: JobStatus = JobStatus.PROCESSING
+    stage: Optional[JobStage] = None
+    progress: int = Field(default=0, ge=0, le=100)
+    message: Optional[str] = None
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    error_code: Optional[str] = None
+    video_url: Optional[str] = None

app/models/schemas.py

@@ -0,0 +1,81 @@
+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
+    client_message_id: Optional[str] = None
+
+    @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
+
+class RenderVideoRequest(BaseModel):
+    job_id: Optional[str] = None
+
+class RenderVideoResponse(BaseModel):
+    job_id: str
+    status: str
+
+
+class OcrPreviewResponse(BaseModel):
+    """Stateless OCR preview before POST .../solve (no DB writes, no job)."""
+
+    ocr_text: str
+    user_message: str = ""
+    combined_draft: str

app/ocr_celery.py

@@ -0,0 +1,86 @@
+"""OCR pipeline with confidence gateway support."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import TYPE_CHECKING, Optional
+
+import anyio
+
+from config.loader import load_agent_config
+from vision_ocr.canonical_schema import CanonicalOCRResult
+
+if TYPE_CHECKING:
+    from agents.ocr_agent import OCRAgent
+
+logger = logging.getLogger(__name__)
+
+
+async def ocr_from_image_url(
+    image_url: str,
+    fallback_agent: "OCRAgent",
+    raw_image_path: Optional[str] = None,
+) -> CanonicalOCRResult:
+    """
+    Process OCR from image URL using OCRAgent (Pix2Text Engine).
+    Returns full CanonicalOCRResult with confidence metadata.
+    If confidence < gateway threshold, triggers VLM correction (if enabled).
+    """
+    # Get canonical OCR result (with confidence)
+    canonical = await fallback_agent.process_url_canonical(image_url)
+
+    # Check confidence gateway
+    ocr_config = load_agent_config("ocr")
+    gateway = ocr_config.confidence_gateway
+
+    if gateway and gateway.enabled:
+        threshold = gateway.threshold
+        ocr_confidence = canonical.confidence
+
+        logger.info(
+            f"[OCR Gateway] confidence={ocr_confidence:.3f}, threshold={threshold:.2f}, "
+            f"gateway_triggered={ocr_confidence < threshold}"
+        )
+
+        if ocr_confidence < threshold and gateway.correction.enabled:
+            try:
+                from agents.vlm_corrector import VLMCorrectorAgent
+
+                corrector = VLMCorrectorAgent(config=gateway.correction)
+                correction_result = await corrector.correct(
+                    ocr_result=canonical,
+                    image_url=image_url,
+                    image_path=raw_image_path,
+                )
+
+                if correction_result and correction_result.get("changed"):
+                    corrected_text = correction_result.get("corrected_text", canonical.text)
+                    corrected_confidence = correction_result.get("confidence", ocr_confidence)
+                    logger.info(
+                        f"[OCR Gateway] VLM correction applied: "
+                        f"confidence {ocr_confidence:.3f} → {corrected_confidence:.3f}"
+                    )
+                    # Return updated canonical result
+                    canonical = CanonicalOCRResult(
+                        text=corrected_text,
+                        latex=canonical.latex,
+                        elements=canonical.elements,
+                        reading_order=canonical.reading_order,
+                        confidence=corrected_confidence,
+                        metadata={
+                            **canonical.metadata,
+                            "vlm_correction": True,
+                            "original_confidence": ocr_confidence,
+                            "corrections": correction_result.get("corrections", []),
+                        },
+                    )
+                else:
+                    logger.info("[OCR Gateway] VLM correction: no changes needed")
+            except ImportError:
+                logger.warning("[OCR Gateway] VLM corrector not available, skipping correction")
+            except Exception as e:
+                logger.warning(f"[OCR Gateway] VLM correction failed: {e}")
+
+    return canonical

app/ocr_local_file.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+from config.loader import load_agent_config
+
+if TYPE_CHECKING:
+    from agents.ocr_agent import OCRAgent
+
+logger = logging.getLogger(__name__)
+
+
+async def ocr_from_local_image_path(
+    local_path: str,
+    original_filename: str | None,
+    fallback_agent: "OCRAgent",
+) -> str:
+    """
+    Run OCR on a file on local disk using Pix2Text + Confidence Gateway VLM Correction.
+    """
+    import inspect
+    from vision_ocr.canonical_schema import CanonicalOCRResult
+
+    canonical = None
+    if hasattr(fallback_agent, "process_image_canonical"):
+        try:
+            res = fallback_agent.process_image_canonical(local_path)
+            canonical = await res if inspect.isawaitable(res) else res
+        except Exception:
+            canonical = None
+
+    if canonical is None or not isinstance(canonical, CanonicalOCRResult):
+        if hasattr(fallback_agent, "process_image"):
+            res = fallback_agent.process_image(local_path)
+            text = await res if inspect.isawaitable(res) else res
+            canonical = CanonicalOCRResult(text=str(text or ""), confidence=0.5 if not text else 0.8)
+        else:
+            canonical = CanonicalOCRResult(text="", confidence=0.0)
+
+    ocr_config = load_agent_config("ocr")
+    gateway = ocr_config.confidence_gateway
+
+    if gateway and gateway.enabled:
+        threshold = gateway.threshold
+        ocr_confidence = canonical.confidence
+
+        logger.info(
+            f"[OCR Local Gateway] confidence={ocr_confidence:.3f}, threshold={threshold:.2f}, "
+            f"gateway_triggered={ocr_confidence < threshold}"
+        )
+
+        if ocr_confidence < threshold and gateway.correction.enabled:
+            try:
+                from agents.vlm_corrector import VLMCorrectorAgent
+
+                corrector = VLMCorrectorAgent(config=gateway.correction)
+                correction_result = await corrector.correct(
+                    ocr_result=canonical,
+                    image_path=local_path,
+                )
+
+                if correction_result and correction_result.get("changed"):
+                    logger.info(
+                        f"[OCR Local Gateway] VLM correction applied: "
+                        f"confidence {ocr_confidence:.3f} -> {correction_result.get('confidence', 0.9):.3f}"
+                    )
+                    return correction_result.get("corrected_text", canonical.text)
+            except Exception as e:
+                logger.warning(f"[OCR Local Gateway] VLM correction failed: {e}")
+
+    return canonical.text
+
+

app/ocr_text_merge.py

@@ -0,0 +1,14 @@
+"""Helpers for OCR preview combined draft (no Pydantic email deps)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def build_combined_ocr_preview_draft(user_message: Optional[str], ocr_text: str) -> str:
+    """Merge user caption and OCR text for confirm step (user message first, then OCR)."""
+    u = (user_message or "").strip()
+    o = (ocr_text or "").strip()
+    if u and o:
+        return f"{u}\n\n{o}"
+    return u or o

app/routers/__init__.py

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

app/routers/ai_core.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import uuid
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from typing import Optional, Dict, Any
+
+from agents.orchestrator import Orchestrator
+from agents.ocr_agent import OCRAgent
+from manim_client.client import ManimClient
+from manim_client.schemas import MathRenderResponse
+from vision_ocr.canonical_schema import CanonicalOCRResult
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/v1/ai", tags=["AI Core (Standalone)"])
+
+# Shared in-memory instances (lazy initialized)
+_orchestrator = None
+_ocr_agent = None
+_manim_client = None
+
+
+def _get_orchestrator() -> Orchestrator:
+    global _orchestrator
+    if _orchestrator is None:
+        _orchestrator = Orchestrator()
+    return _orchestrator
+
+
+def _get_ocr_agent() -> OCRAgent:
+    global _ocr_agent
+    if _ocr_agent is None:
+        _ocr_agent = OCRAgent()
+    return _ocr_agent
+
+
+def _get_manim_client() -> ManimClient:
+    global _manim_client
+    if _manim_client is None:
+        _manim_client = ManimClient()
+    return _manim_client
+
+
+class AISolveRequest(BaseModel):
+    text: Optional[str] = None
+    image_url: Optional[str] = None
+    image_path: Optional[str] = None
+    generate_video: bool = True
+
+
+class AIOCRRequest(BaseModel):
+    image_url: Optional[str] = None
+    image_path: Optional[str] = None
+    image_base64: Optional[str] = None
+
+
+@router.post("/ocr", response_model=CanonicalOCRResult)
+async def ocr_direct_ai(request: AIOCRRequest) -> CanonicalOCRResult:
+    """
+    Direct Math OCR Endpoint (Pix2Text Engine).
+    Converts geometry problem images into canonical structured format:
+    - text: Reconstructed Markdown with LaTeX math formulas
+    - latex: List of isolated and embedded LaTeX equations
+    - elements: Classified layout regions (text, formulas, bboxes)
+    - reading_order: Document reading sequence
+    - confidence: Extraction accuracy confidence
+    """
+    ocr_agent = _get_ocr_agent()
+    if request.image_url:
+        logger.info("==[AI Core OCR] Processing image_url: %s==", request.image_url)
+        return await ocr_agent.process_url_canonical(request.image_url)
+
+    if request.image_path:
+        logger.info("==[AI Core OCR] Processing local image_path: %s==", request.image_path)
+        return await ocr_agent.process_image_canonical(request.image_path)
+
+    if request.image_base64:
+        logger.info("==[AI Core OCR] Processing image_base64==")
+        temp_path = f"temp_ocr_b64_{uuid.uuid4().hex}.png"
+        try:
+            b64_data = request.image_base64
+            if "," in b64_data:
+                b64_data = b64_data.split(",", 1)[1]
+            img_bytes = base64.b64decode(b64_data)
+            with open(temp_path, "wb") as f:
+                f.write(img_bytes)
+            return await ocr_agent.process_image_canonical(temp_path)
+        finally:
+            if os.path.exists(temp_path):
+                try:
+                    os.remove(temp_path)
+                except Exception:
+                    pass
+
+    raise HTTPException(status_code=400, detail="Must provide 'image_url', 'image_path', or 'image_base64'.")
+
+
+@router.post("/solve")
+async def solve_direct_ai(request: AISolveRequest) -> Dict[str, Any]:
+    """
+    Direct Standalone AI Core Solve Endpoint.
+    - Runs OCR (Pix2Text) -> GeometryParser -> GeometryEngine -> DeepMath -> VisualizationSpec -> Manim Module.
+    - 100% In-Memory: No Supabase DB or Redis connection required.
+    - No authentication token required (Ideal for AI development & curl testing).
+    """
+    text = (request.text or "").strip()
+    image_url = request.image_url
+    ocr_agent = _get_ocr_agent()
+    orchestrator = _get_orchestrator()
+
+    if not text and request.image_path and os.path.exists(request.image_path):
+        # Run OCR on local image directly
+        ocr_res = await ocr_agent.process_image_canonical(request.image_path)
+        text = ocr_res.text
+        logger.info("[AI Core Solve] Extracted OCR text from %s: '%s'", request.image_path, text[:80])
+
+    if not text and not image_url:
+        raise HTTPException(status_code=400, detail="Either 'text', 'image_url', or valid 'image_path' must be provided.")
+
+    logger.info("==[AI Core Direct Solve] Received problem: %s==", text[:80] if text else f"Image: {image_url}")
+    try:
+        result = await orchestrator.run(
+            text=text,
+            image_url=image_url,
+            job_id="direct_ai_run",
+            generate_video=request.generate_video,
+        )
+        return result
+    except Exception as e:
+        logger.exception("AI Core execution error: %s", e)
+        raise HTTPException(status_code=500, detail=f"AI Core processing failed: {str(e)}")
+
+
+@router.get("/visualization/jobs/{job_id}", response_model=MathRenderResponse)
+async def get_visualization_job_status(job_id: str) -> MathRenderResponse:
+    """
+    Query the status of a Manim video generation job.
+    Proxies request to the Manim Video Generation Module.
+    """
+    logger.info(f"==[AI Core Visualization] Fetching status for job {job_id}==")
+    resp = await _get_manim_client().get_job_status(job_id)
+    return resp

app/routers/auth.py

@@ -0,0 +1,50 @@
+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)):
+    """Lấy thông tin profile người dùng hiện tại (Retrieve current user profile)."""
+    supabase = get_supabase()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    
+    res = supabase.table("profiles").select("*").eq("id", user_id).execute()
+    if res.data:
+        return res.data[0]
+    
+    # Auto-provision basic profile if trigger didn't run or dev test user
+    try:
+        insert_res = (
+            supabase.table("profiles")
+            .insert({"id": str(user_id), "display_name": "Người dùng", "avatar_url": None})
+            .execute()
+        )
+        if insert_res.data:
+            return insert_res.data[0]
+    except Exception:
+        pass
+
+    raise HTTPException(status_code=404, detail="Profile not found.")
+
+@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()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    
+    # Sanitize and only allow updating safe profile fields
+    allowed_fields = {"display_name", "avatar_url"}
+    update_data = {k: v for k, v in data.items() if k in allowed_fields}
+    if not update_data:
+        raise HTTPException(status_code=400, detail="No valid fields provided for update (allowed: display_name, avatar_url).")
+    
+    res = supabase.table("profiles").update(update_data).eq("id", user_id).execute()
+    if not res.data:
+        raise HTTPException(status_code=404, detail="Profile not found to update.")
+    return res.data[0]

app/routers/sessions.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import List
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+
+from app.chat_image_upload import cleanup_session_storage
+from app.dependencies import get_current_user_id
+from app.logutil import log_step
+from app.session_cache import (
+    invalidate_session_owner,
+    session_owned_by_user,
+)
+from app.supabase_client import get_supabase
+
+router = APIRouter(prefix="/api/v1/sessions", tags=["Sessions"])
+logger = logging.getLogger(__name__)
+
+
+@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()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    t0 = time.perf_counter()
+    res = (
+        supabase.table("sessions")
+        .select("id, user_id, title, created_at, updated_at")
+        .eq("user_id", user_id)
+        .order("updated_at", desc=True)
+        .execute()
+    )
+    log_step("db_select", table="sessions", op="list", user_id=str(user_id))
+    out = res.data or []
+    logger.info(
+        "sessions.list user=%s count=%d %.1fms",
+        user_id,
+        len(out),
+        (time.perf_counter() - t0) * 1000,
+    )
+    return out
+
+
+@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()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    t0 = time.perf_counter()
+    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")
+    if not res.data:
+        raise HTTPException(status_code=500, detail="Failed to create session.")
+    row = res.data[0]
+    logger.info(
+        "sessions.create user=%s id=%s %.1fms",
+        user_id,
+        row.get("id"),
+        (time.perf_counter() - t0) * 1000,
+    )
+    return row
+
+
+@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()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+
+    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 or []
+
+
+@router.delete("/{session_id}")
+async def delete_session(
+    session_id: str,
+    background_tasks: BackgroundTasks,
+    user_id=Depends(get_current_user_id),
+):
+    """Xóa một phiên chat và toàn bộ tài nguyên liên quan (Delete a chat session & associated assets)"""
+    supabase = get_supabase()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+
+    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."
+        )
+
+    # 1. Authoritative DB deletion first (dependent rows before session)
+    try:
+        supabase.table("session_assets").delete().eq("session_id", session_id).execute()
+        log_step("db_delete", table="session_assets", op="by_session", session_id=session_id)
+    except Exception as e:
+        logger.warning("Error deleting session_assets for session %s: %s", session_id, e)
+
+    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_session_owner(session_id, str(user_id))
+
+    # 2. Async / non-blocking storage cleanup AFTER DB deletion succeeds
+    background_tasks.add_task(cleanup_session_storage, session_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()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    
+    res = (
+        supabase.table("sessions")
+        .update({"title": title})
+        .eq("id", session_id)
+        .eq("user_id", user_id)
+        .execute()
+    )
+    if not res.data:
+        raise HTTPException(status_code=404, detail="Session not found or not owned by user.")
+    log_step("db_update", table="sessions", op="title", session_id=session_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,397 @@
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+
+from fastapi import APIRouter, BackgroundTasks, Depends, File, Form, HTTPException, UploadFile
+
+from agents.orchestrator import Orchestrator
+from app.chat_image_upload import upload_session_chat_image, validate_chat_image_bytes
+from app.ocr_local_file import ocr_from_local_image_path
+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 (
+    OcrPreviewResponse,
+    RenderVideoRequest,
+    RenderVideoResponse,
+    SolveRequest,
+    SolveResponse,
+)
+from app.ocr_text_merge import build_combined_ocr_preview_draft
+from app.session_cache import 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
+
+
+_OCR_PREVIEW_MAX_BYTES = 10 * 1024 * 1024
+
+
+def _assert_session_owner(supabase, session_id: str, user_id, uid: str, op: str) -> None:
+    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=op, 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."
+        )
+
+
+from app.celery_app import is_celery_available
+from app.tasks import (
+    async_solve_session_job,
+    async_render_video_job,
+    solve_session_job_task,
+    render_video_job_task,
+)
+
+
+def _enqueue_solve_common(
+    supabase,
+    background_tasks: BackgroundTasks,
+    session_id: str,
+    user_id,
+    uid: str,
+    request: SolveRequest,
+    message_metadata: dict,
+    job_id: str,
+) -> SolveResponse:
+    """Insert user message, job row, enqueue pipeline via Celery/BackgroundWorker; update title when first message."""
+    client_msg_id = getattr(request, "client_message_id", None)
+    if client_msg_id:
+        message_metadata["client_message_id"] = client_msg_id
+
+    # Check for idempotency if client_message_id is provided
+    if client_msg_id:
+        try:
+            existing = (
+                supabase.table("messages")
+                .select("id")
+                .eq("session_id", session_id)
+                .eq("client_message_id", client_msg_id)
+                .execute()
+            )
+            if existing.data and len(existing.data) > 0:
+                logger.info(
+                    "Duplicate request detected for client_message_id=%s in session %s",
+                    client_msg_id,
+                    session_id,
+                )
+                return SolveResponse(job_id=job_id, status="processing")
+        except Exception:
+            pass
+
+    msg_insert = {
+        "session_id": session_id,
+        "role": "user",
+        "type": "text",
+        "content": request.text,
+        "metadata": message_metadata,
+    }
+    if client_msg_id:
+        try:
+            supabase.table("messages").insert({**msg_insert, "client_message_id": client_msg_id}).execute()
+        except Exception:
+            supabase.table("messages").insert(msg_insert).execute()
+    else:
+        supabase.table("messages").insert(msg_insert).execute()
+
+    log_step("db_insert", table="messages", op="user_message", session_id=session_id)
+
+    supabase.table("jobs").insert(
+        {
+            "id": job_id,
+            "user_id": user_id,
+            "session_id": session_id,
+            "status": "processing",
+            "stage": "ocr" if request.image_url else "parsing",
+            "progress": 15 if request.image_url else 35,
+            "input_text": request.text,
+        }
+    ).execute()
+    log_step("db_insert", table="jobs", job_id=job_id)
+
+    # Dispatch to Celery queue if available; otherwise use Async Background Tasks
+    if is_celery_available():
+        try:
+            solve_session_job_task.delay(
+                job_id, session_id, request.text, request.image_url, str(user_id), client_msg_id
+            )
+            log_step("celery_dispatch", task="solve_session_job", job_id=job_id)
+        except Exception as e:
+            logger.warning("Celery dispatch failed (%s), falling back to BackgroundTasks", e)
+            background_tasks.add_task(
+                async_solve_session_job,
+                job_id,
+                session_id,
+                request.text,
+                request.image_url,
+                str(user_id),
+                client_msg_id,
+            )
+    else:
+        background_tasks.add_task(
+            async_solve_session_job,
+            job_id,
+            session_id,
+            request.text,
+            request.image_url,
+            str(user_id),
+            client_msg_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")
+
+    log_pipeline_success("solve_accepted", job_id=job_id, session_id=session_id)
+    return SolveResponse(job_id=job_id, status="processing")
+
+
+
+@router.post("/{session_id}/ocr_preview", response_model=OcrPreviewResponse)
+async def ocr_preview(
+    session_id: str,
+    user_id=Depends(get_current_user_id),
+    file: UploadFile = File(...),
+    user_message: str | None = Form(None),
+):
+    """
+    Run OCR on an uploaded image and merge with optional user_message into combined_draft.
+    Does not insert messages or start a solve job. After user confirms, call POST .../solve
+    with text=combined_draft (edited) and omit image_url to avoid double OCR.
+    """
+    supabase = get_supabase()
+    uid = str(user_id)
+    _assert_session_owner(supabase, session_id, user_id, uid, "owner_check_ocr_preview")
+
+    body = await file.read()
+    if len(body) > _OCR_PREVIEW_MAX_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Image too large (max {_OCR_PREVIEW_MAX_BYTES // (1024 * 1024)} MB).",
+        )
+    if not body:
+        raise HTTPException(status_code=400, detail="Empty file.")
+
+    validate_chat_image_bytes(file.filename, body, file.content_type)
+
+    suffix = os.path.splitext(file.filename or "")[1].lower()
+    if suffix not in (".png", ".jpg", ".jpeg", ".webp", ".gif", ".bmp", ""):
+        suffix = ".png"
+    temp_path = f"temp_ocr_preview_{uuid.uuid4()}{suffix or '.png'}"
+    try:
+        with open(temp_path, "wb") as f:
+            f.write(body)
+        ocr_text = await ocr_from_local_image_path(
+            temp_path, file.filename, get_orchestrator().ocr_agent
+        )
+        if ocr_text is None:
+            ocr_text = ""
+    finally:
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+
+    um = (user_message or "").strip()
+    combined = build_combined_ocr_preview_draft(user_message, ocr_text)
+    log_step("ocr_preview_done", session_id=session_id, ocr_len=len(ocr_text), user_len=len(um))
+    return OcrPreviewResponse(
+        ocr_text=ocr_text,
+        user_message=um,
+        combined_draft=combined,
+    )
+
+
+@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 (chỉ giải toán và tạo hình tĩnh).
+    """
+    supabase = get_supabase()
+    uid = str(user_id)
+    _assert_session_owner(supabase, session_id, user_id, uid, "owner_check")
+
+    message_metadata = {"image_url": request.image_url} if request.image_url else {}
+    job_id = str(uuid.uuid4())
+    return _enqueue_solve_common(
+        supabase,
+        background_tasks,
+        session_id,
+        user_id,
+        uid,
+        request,
+        message_metadata,
+        job_id,
+    )
+
+
+@router.post("/{session_id}/solve_multipart", response_model=SolveResponse)
+async def solve_multipart(
+    session_id: str,
+    background_tasks: BackgroundTasks,
+    user_id=Depends(get_current_user_id),
+    text: str = Form(...),
+    file: UploadFile = File(...),
+    client_message_id: str | None = Form(None),
+):
+    """
+    Gửi text + file ảnh trong một request multipart: validate, upload bucket `image`,
+    ghi session_assets, lưu message kèm metadata (URL, size, type), rồi enqueue solve
+    (image_url trỏ public URL để orchestrator OCR).
+    """
+    supabase = get_supabase()
+    uid = str(user_id)
+    _assert_session_owner(supabase, session_id, user_id, uid, "owner_check_solve_multipart")
+
+    t = (text or "").strip()
+    if not t:
+        raise HTTPException(status_code=400, detail="text must not be empty.")
+
+    body = await file.read()
+    ext, content_type = validate_chat_image_bytes(file.filename, body, file.content_type)
+
+    job_id = str(uuid.uuid4())
+    up = upload_session_chat_image(session_id, job_id, body, ext, content_type)
+    public_url = up["public_url"]
+
+    message_metadata = {
+        "image_url": public_url,
+        "attachment": {
+            "public_url": public_url,
+            "storage_path": up["storage_path"],
+            "size_bytes": len(body),
+            "content_type": content_type,
+            "original_filename": file.filename or "",
+            "session_asset_id": up.get("session_asset_id"),
+        },
+    }
+    request = SolveRequest(text=t, image_url=public_url, client_message_id=client_message_id)
+    return _enqueue_solve_common(
+        supabase,
+        background_tasks,
+        session_id,
+        user_id,
+        uid,
+        request,
+        message_metadata,
+        job_id,
+    )
+
+
+@router.post("/{session_id}/render_video", response_model=RenderVideoResponse)
+async def render_video(
+    session_id: str,
+    request: RenderVideoRequest,
+    background_tasks: BackgroundTasks,
+    user_id=Depends(get_current_user_id),
+):
+    """
+    Yêu cầu tạo video Manim từ trạng thái hình ảnh mới nhất của session.
+    """
+    supabase = get_supabase()
+    if not supabase:
+        raise HTTPException(status_code=503, detail="Database service currently unavailable.")
+    
+    uid = str(user_id)
+    # 1. Kiểm tra quyền sở hữu
+    _assert_session_owner(supabase, session_id, user_id, uid, "owner_check_render_video")
+
+    # 2. Tìm tin nhắn assistant có metadata hình học (cụ thể job_id hoặc mới nhất trong 10 tin nhắn gần nhất)
+    msg_res = (
+        supabase.table("messages")
+        .select("metadata")
+        .eq("session_id", session_id)
+        .eq("role", "assistant")
+        .order("created_at", desc=True)
+        .limit(10)
+        .execute()
+    )
+    
+    latest_geometry = None
+    if msg_res.data:
+        for msg in msg_res.data:
+            meta = msg.get("metadata", {})
+            # Nếu có yêu cầu job_id cụ thể, phải khớp job_id
+            if request.job_id and meta.get("job_id") != request.job_id:
+                continue
+            
+            # Phải có dữ liệu hình học
+            if meta.get("geometry_dsl") and meta.get("coordinates"):
+                latest_geometry = meta
+                break
+    
+    if not latest_geometry:
+        raise HTTPException(status_code=404, detail="Không tìm thấy dữ liệu hình học để render video.")
+
+    # 3. Tạo Job rendering
+    job_id = str(uuid.uuid4())
+    supabase.table("jobs").insert({
+        "id": job_id,
+        "user_id": user_id,
+        "session_id": session_id,
+        "status": "rendering_queued",
+        "stage": "rendering",
+        "progress": 10,
+        "input_text": f"Render video requested at {job_id}",
+    }).execute()
+
+    # 4. Dispatch Celery task or async background task
+    if is_celery_available():
+        try:
+            render_video_job_task.delay(job_id, session_id, latest_geometry)
+            log_step("celery_dispatch", task="render_video_job", job_id=job_id)
+        except Exception as e:
+            logger.warning("Celery dispatch failed (%s), falling back to BackgroundTasks", e)
+            background_tasks.add_task(async_render_video_job, job_id, session_id, latest_geometry)
+    else:
+        background_tasks.add_task(async_render_video_job, job_id, session_id, latest_geometry)
+    
+    return RenderVideoResponse(job_id=job_id, status="rendering_queued")
+
+
+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, tạo hình ảnh tĩnh (backward compatible delegate)."""
+    return await async_solve_session_job(
+        job_id=job_id,
+        session_id=session_id,
+        text=request.text,
+        image_url=request.image_url,
+        user_id=user_id,
+        client_message_id=getattr(request, "client_message_id", None),
+    )
+
+
+async def process_render_job(job_id: str, session_id: str, geometry_data: dict):
+    """Tiến trình render video qua External Manim API (backward compatible delegate)."""
+    return await async_render_video_job(job_id=job_id, session_id=session_id, geometry_data=geometry_data)
+
+

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,26 @@
+"""Deterministic session ownership verification (Server-authoritative, no process-local drift)."""
+
+from __future__ import annotations
+
+from typing import Callable
+from app.logutil import log_step
+
+
+def invalidate_session_owner(session_id: str, user_id: str) -> None:
+    """No-op for backward compatibility now that ownership is direct DB authoritative."""
+    log_step("session_owner_check", target="session_owner", session_id=session_id, user_id=user_id)
+
+
+def session_owned_by_user(
+    session_id: str,
+    user_id: str,
+    fetch: Callable[[], bool],
+) -> bool:
+    """
+    Direct authoritative ownership check via provided fetch function.
+    Eliminates multi-worker drift by always evaluating against the authoritative DB.
+    """
+    ok = fetch()
+    log_step("session_owner_verified", session_id=session_id, user_id=user_id, is_owner=ok)
+    return ok
+

app/supabase_client.py

@@ -0,0 +1,45 @@
+import os
+import logging
+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
+
+logger = logging.getLogger(__name__)
+
+_supabase_client = None
+
+
+def get_supabase() -> Client:
+    """Service-role client for server-side operations with lazy init."""
+    global _supabase_client
+    if _supabase_client is not None:
+        return _supabase_client
+
+    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:
+        logger.warning("[Supabase] SUPABASE_URL or key not configured. Cloud DB operations will be unavailable.")
+        return None
+
+    try:
+        _supabase_client = create_client(url, key)
+        return _supabase_client
+    except Exception as e:
+        logger.warning("[Supabase] Failed to initialize Supabase client: %s", e)
+        return None
+
+
+def get_supabase_for_user_jwt(access_token: str) -> Client:
+    """Client scoped to the logged-in user."""
+    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 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/tasks.py

@@ -0,0 +1,402 @@
+"""Celery Tasks & Async Worker Handlers for MathSolver Solve & Render Pipeline."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import uuid
+from typing import Any, Dict, Optional
+
+from app.celery_app import celery_app
+from app.errors import format_error_for_user
+from app.logutil import log_pipeline_failure, log_pipeline_success, log_step
+from app.models.job_state import JobStatus, JobStage, JobStateMachine
+from app.supabase_client import get_supabase
+from app.websocket_manager import notify_status
+
+logger = logging.getLogger(__name__)
+
+
+async def async_solve_session_job(
+    job_id: str,
+    session_id: str,
+    text: str,
+    image_url: Optional[str] = None,
+    user_id: Optional[str] = None,
+    client_message_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Execute the full geometry solve pipeline for a session job."""
+    from app.routers.solve import get_orchestrator
+
+    supabase = get_supabase()
+
+    async def status_callback(status: str, stage: Optional[str] = None, progress: Optional[int] = None):
+        norm_status = JobStateMachine.normalize_status(status)
+        norm_stage = JobStateMachine.normalize_stage(stage or status)
+        update_data = {"status": norm_status.value}
+        if norm_stage:
+            update_data["stage"] = norm_stage.value
+        if progress is not None:
+            update_data["progress"] = progress
+
+        if supabase:
+            try:
+                supabase.table("jobs").update(update_data).eq("id", job_id).execute()
+            except Exception as e:
+                logger.debug("Failed updating job status in DB: %s", e)
+
+        await notify_status(job_id, {
+            "status": norm_status.value,
+            "stage": norm_stage.value if norm_stage else None,
+            "progress": progress,
+            "job_id": job_id,
+        })
+
+    try:
+        # Initial status update
+        await status_callback("processing", stage="ocr", progress=15)
+
+        history = []
+        if supabase and session_id:
+            try:
+                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 []
+            except Exception as e:
+                logger.warning("Could not fetch message history: %s", e)
+
+        result = await get_orchestrator().run(
+            text,
+            image_url,
+            job_id=job_id,
+            session_id=session_id,
+            status_callback=lambda st: status_callback(st),
+            history=history,
+        )
+
+        has_error = "error" in result and result.get("error")
+        final_status = JobStatus.FAILED if has_error else JobStatus.COMPLETED
+
+        if supabase:
+            supabase.table("jobs").update({
+                "status": final_status.value,
+                "stage": None,
+                "progress": 100 if final_status == JobStatus.COMPLETED else 0,
+                "result": result,
+            }).eq("id", job_id).execute()
+
+            # Idempotency check: Ensure assistant message for this job is not inserted twice
+            existing_msg = (
+                supabase.table("messages")
+                .select("id")
+                .eq("session_id", session_id)
+                .filter("metadata->>job_id", "eq", job_id)
+                .execute()
+            )
+
+            if not existing_msg.data or len(existing_msg.data) == 0:
+                supabase.table("messages").insert({
+                    "session_id": session_id,
+                    "role": "assistant",
+                    "type": "error" if has_error else "analysis",
+                    "content": (
+                        result.get("error", "Đã có lỗi xảy ra.")
+                        if has_error
+                        else result.get("semantic_analysis", "Giải bài toán hoàn tất.")
+                    ),
+                    "metadata": {
+                        "job_id": job_id,
+                        "client_message_id": client_message_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", []),
+                        "solids": result.get("solids", []),
+                        "faces": result.get("faces", []),
+                        "lines": result.get("lines", []),
+                        "rays": result.get("rays", []),
+                        "visualization_graph": result.get("visualization_graph"),
+                        "auxiliary": result.get("auxiliary", []),
+                        "solution": result.get("solution"),
+                        "is_3d": result.get("is_3d", False),
+                    },
+                }).execute()
+
+        await notify_status(job_id, {
+            "status": final_status.value,
+            "stage": None,
+            "progress": 100 if final_status == JobStatus.COMPLETED else 0,
+            "job_id": job_id,
+            "result": result,
+        })
+        log_pipeline_success("job_complete", job_id=job_id, session_id=session_id)
+        return result
+
+    except Exception as e:
+        logger.exception("Error in async_solve_session_job for job %s: %s", job_id, e)
+        error_msg = format_error_for_user(e)
+        if supabase:
+            try:
+                supabase.table("jobs").update({
+                    "status": JobStatus.FAILED.value,
+                    "progress": 0,
+                    "result": {"error": str(e)},
+                }).eq("id", job_id).execute()
+
+                supabase.table("messages").insert({
+                    "session_id": session_id,
+                    "role": "assistant",
+                    "type": "error",
+                    "content": error_msg,
+                    "metadata": {"job_id": job_id, "client_message_id": client_message_id},
+                }).execute()
+            except Exception as dbe:
+                logger.error("DB error recording failure for job %s: %s", job_id, dbe)
+
+        await notify_status(job_id, {
+            "status": JobStatus.FAILED.value,
+            "job_id": job_id,
+            "error": error_msg,
+            "progress": 0,
+        })
+        log_pipeline_failure("job_failed", job_id=job_id, error=str(e))
+        return {"status": "error", "error": error_msg}
+
+
+async def async_render_video_job(job_id: str, session_id: str, geometry_data: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute Manim video rendering job for a session."""
+    from manim_client import ManimClient, build_visualization_spec
+    from manim_client.schemas import ErrorCode
+
+    await notify_status(job_id, {
+        "status": JobStatus.QUEUED.value,
+        "stage": JobStage.RENDERING.value,
+        "job_id": job_id,
+        "progress": 10,
+    })
+    supabase = get_supabase()
+
+    try:
+        manim_url = os.getenv("MANIM_SERVICE_URL", "https://cuong2004-manim-agent.hf.space")
+        manim_token = os.getenv("MANIM_INTERNAL_TOKEN")
+        client = ManimClient(base_url=manim_url, internal_token=manim_token)
+
+        vis_spec = build_visualization_spec(geometry_data)
+        resp = await client.submit_render_job(vis_spec)
+
+        if resp.status == "failed":
+            err_code = resp.get_error_code() or ErrorCode.MANIM_REQUEST_FAILED
+            err_msg = resp.get_error_message() or "Không thể gửi yêu cầu tạo video tới máy chủ Manim."
+            if supabase:
+                supabase.table("jobs").update({
+                    "status": JobStatus.FAILED.value,
+                    "result": {"error": {"code": err_code, "message": err_msg}},
+                }).eq("id", job_id).execute()
+                if session_id:
+                    supabase.table("messages").insert({
+                        "session_id": session_id,
+                        "role": "assistant",
+                        "type": "error",
+                        "content": f"Không thể tạo video: {err_msg}",
+                        "metadata": {"job_id": job_id, "error_code": err_code},
+                    }).execute()
+            await notify_status(job_id, {
+                "status": JobStatus.FAILED.value,
+                "job_id": job_id,
+                "error": err_msg,
+                "error_code": err_code,
+            })
+            return {"status": "error", "error": err_msg}
+
+        manim_job_id = resp.job_id
+        if supabase:
+            supabase.table("jobs").update({
+                "status": JobStatus.PROCESSING.value,
+                "stage": JobStage.RENDERING.value,
+                "progress": 40,
+                "result": {"manim_job_id": str(manim_job_id)},
+            }).eq("id", job_id).execute()
+
+        await notify_status(job_id, {
+            "status": JobStatus.PROCESSING.value,
+            "stage": JobStage.RENDERING.value,
+            "job_id": job_id,
+            "progress": 40,
+            "manim_job_id": str(manim_job_id),
+        })
+
+        poll_timeout = float(os.getenv("MANIM_POLL_TIMEOUT", "600.0"))
+        status_resp = await client.wait_for_completion(manim_job_id, poll_interval=3.0, max_wait=poll_timeout)
+        video_url = status_resp.video_url
+
+        if status_resp.status == "failed" or not video_url:
+            err_code = status_resp.get_error_code() or ErrorCode.MANIM_RENDER_FAILED
+            err_msg = status_resp.get_error_message() or "Tiến trình dựng video Manim thất bại."
+            if supabase:
+                supabase.table("jobs").update({
+                    "status": JobStatus.FAILED.value,
+                    "result": {"error": {"code": err_code, "message": err_msg}},
+                }).eq("id", job_id).execute()
+                if session_id:
+                    supabase.table("messages").insert({
+                        "session_id": session_id,
+                        "role": "assistant",
+                        "type": "error",
+                        "content": f"Không thể tạo video: {err_msg}",
+                        "metadata": {"job_id": job_id, "error_code": err_code},
+                    }).execute()
+            await notify_status(job_id, {
+                "status": JobStatus.FAILED.value,
+                "job_id": job_id,
+                "error": err_msg,
+                "error_code": err_code,
+            })
+            return {"status": "error", "error": err_msg}
+
+        final_result = geometry_data.copy()
+        final_result["video_url"] = video_url
+        final_result["manim_job_id"] = str(manim_job_id)
+
+        if supabase:
+            supabase.table("jobs").update({
+                "status": JobStatus.COMPLETED.value,
+                "progress": 100,
+                "result": final_result,
+            }).eq("id", job_id).execute()
+
+            # Versioned asset recording
+            try:
+                asset_version = 1
+                v_res = supabase.table("session_assets").select("version").eq("session_id", session_id).eq("asset_type", "video").order("version", desc=True).limit(1).execute()
+                if v_res.data and len(v_res.data) > 0:
+                    asset_version = v_res.data[0]["version"] + 1
+
+                supabase.table("session_assets").insert({
+                    "session_id": session_id,
+                    "job_id": job_id,
+                    "asset_type": "video",
+                    "storage_path": video_url,
+                    "public_url": video_url,
+                    "version": asset_version,
+                }).execute()
+            except Exception as e:
+                logger.warning("Could not record session_asset video row: %s", e)
+
+            if session_id:
+                supabase.table("messages").insert({
+                    "session_id": session_id,
+                    "role": "assistant",
+                    "type": "analysis",
+                    "content": geometry_data.get("semantic_analysis", "🎬 Video minh họa hình học đã hoàn tất."),
+                    "metadata": {
+                        "job_id": job_id,
+                        "video_url": video_url,
+                        "coordinates": geometry_data.get("coordinates"),
+                        "geometry_dsl": geometry_data.get("geometry_dsl"),
+                        "polygon_order": geometry_data.get("polygon_order", []),
+                        "drawing_phases": geometry_data.get("drawing_phases", []),
+                        "circles": geometry_data.get("circles", []),
+                        "solids": geometry_data.get("solids", []),
+                        "faces": geometry_data.get("faces", []),
+                        "lines": geometry_data.get("lines", []),
+                        "rays": geometry_data.get("rays", []),
+                        "visualization_graph": geometry_data.get("visualization_graph"),
+                        "auxiliary": geometry_data.get("auxiliary", []),
+                        "is_3d": geometry_data.get("is_3d", False),
+                    },
+                }).execute()
+
+        await notify_status(job_id, {
+            "status": JobStatus.COMPLETED.value,
+            "job_id": job_id,
+            "result": final_result,
+            "video_url": video_url,
+            "progress": 100,
+        })
+        return final_result
+
+    except Exception as e:
+        logger.exception("Error rendering video for job %s: %s", job_id, e)
+        safe_msg = format_error_for_user(e)
+        if supabase:
+            try:
+                supabase.table("jobs").update({
+                    "status": JobStatus.FAILED.value,
+                    "result": {"error": {"message": safe_msg}},
+                }).eq("id", job_id).execute()
+                if session_id:
+                    supabase.table("messages").insert({
+                        "session_id": session_id,
+                        "role": "assistant",
+                        "type": "error",
+                        "content": f"Lỗi render video: {safe_msg}",
+                        "metadata": {"job_id": job_id},
+                    }).execute()
+            except Exception as dbe:
+                logger.error("DB error recording render failure: %s", dbe)
+        await notify_status(job_id, {"status": JobStatus.FAILED.value, "job_id": job_id, "error": safe_msg})
+        return {"status": "error", "error": safe_msg}
+
+
+@celery_app.task(name="tasks.solve_session_job", bind=True, acks_late=True, max_retries=1)
+def solve_session_job_task(
+    self,
+    job_id: str,
+    session_id: str,
+    text: str,
+    image_url: Optional[str] = None,
+    user_id: Optional[str] = None,
+    client_message_id: Optional[str] = None,
+):
+    """Celery task entry point for solve pipeline."""
+    return asyncio.run(
+        async_solve_session_job(
+            job_id=job_id,
+            session_id=session_id,
+            text=text,
+            image_url=image_url,
+            user_id=user_id,
+            client_message_id=client_message_id,
+        )
+    )
+
+
+@celery_app.task(name="tasks.render_video_job", bind=True, acks_late=True, max_retries=1)
+def render_video_job_task(self, job_id: str, session_id: str, geometry_data: Dict[str, Any]):
+    """Celery task entry point for video render pipeline."""
+    return asyncio.run(async_render_video_job(job_id=job_id, session_id=session_id, geometry_data=geometry_data))
+
+
+def recover_stale_jobs(timeout_seconds: int = 900) -> int:
+    """Detect and mark jobs stuck in 'processing' longer than timeout as failed."""
+    supabase = get_supabase()
+    if not supabase:
+        return 0
+    try:
+        # Note: in production, run via cron or worker startup
+        from datetime import datetime, timezone, timedelta
+        cutoff = (datetime.now(timezone.utc) - timedelta(seconds=timeout_seconds)).isoformat()
+        res = (
+            supabase.table("jobs")
+            .update({
+                "status": JobStatus.FAILED.value,
+                "result": {"error": "Worker timeout or crash detected. Job marked failed by recovery agent."},
+            })
+            .eq("status", JobStatus.PROCESSING.value)
+            .lt("created_at", cutoff)
+            .execute()
+        )
+        count = len(res.data) if res.data else 0
+        if count > 0:
+            logger.warning("Recovered %d stale jobs", count)
+        return count
+    except Exception as e:
+        logger.error("Error running recover_stale_jobs: %s", e)
+        return 0

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,87 @@
+"""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]] = {}
+
+
+from app.models.job_state import JobStateMachine, STAGE_PROGRESS_MAP, JobStatus
+
+
+async def notify_status(job_id: str, data: dict) -> None:
+    if job_id not in active_connections:
+        return
+    
+    # Normalize payload
+    payload = dict(data)
+    payload["job_id"] = str(job_id)
+    if "status" in payload:
+        norm_status = JobStateMachine.normalize_status(payload.get("status"))
+        norm_stage = JobStateMachine.normalize_stage(payload.get("stage"))
+        if not norm_stage and payload.get("status") in ("ocr", "parsing", "geometry", "solving", "rendering"):
+            norm_stage = JobStateMachine.normalize_stage(payload.get("status"))
+
+        payload["status"] = norm_status.value
+        payload["stage"] = norm_stage.value if norm_stage else None
+        
+        if "progress" not in payload or payload["progress"] is None:
+            if norm_status == JobStatus.COMPLETED:
+                payload["progress"] = 100
+            elif norm_stage and norm_stage in STAGE_PROGRESS_MAP:
+                payload["progress"] = STAGE_PROGRESS_MAP[norm_stage]
+            elif norm_status == JobStatus.QUEUED:
+                payload["progress"] = 5
+            elif norm_status == JobStatus.PROCESSING:
+                payload["progress"] = 50
+
+    for connection in list(active_connections[job_id]):
+        try:
+            await connection.send_json(payload)
+        except Exception as e:
+            logger.warning("WS error sending to %s: %s (removing dead connection)", job_id, e)
+            try:
+                active_connections[job_id].remove(connection)
+            except (ValueError, KeyError):
+                pass
+    if job_id in active_connections and not active_connections[job_id]:
+        del active_connections[job_id]
+
+
+
+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)
+
+        # Send immediate ACK so client immediately transitions from 'connecting' to 'processing'
+        try:
+            await websocket.send_json({
+                "status": "processing",
+                "job_id": job_id,
+                "message": "Đang xử lý bài toán..."
+            })
+        except Exception:
+            pass
+
+        try:
+            while True:
+                msg = await websocket.receive_text()
+                if msg == "ping":
+                    await websocket.send_text("pong")
+        except WebSocketDisconnect:
+            if job_id in active_connections and websocket in active_connections[job_id]:
+                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."

config/__init__.py

@@ -0,0 +1,16 @@
+from config.schemas import ModelTier, AgentConfig, RetryPolicyConfig, AgentModelsConfig
+from config.settings import settings, Settings, ProviderCredentials
+from config.loader import load_agent_config, get_agent_config_resolver, get_agent_models_config
+
+__all__ = [
+    "ModelTier",
+    "AgentConfig",
+    "RetryPolicyConfig",
+    "AgentModelsConfig",
+    "settings",
+    "Settings",
+    "ProviderCredentials",
+    "load_agent_config",
+    "get_agent_config_resolver",
+    "get_agent_models_config",
+]

config/agent_models.yaml

@@ -0,0 +1,85 @@
+version: 2
+
+defaults:
+  temperature: 0.1
+  max_tokens: 8192
+  timeout_seconds: 300
+
+retry_policy:
+  retryable_errors:
+    - rate_limit
+    - timeout
+    - connection
+    - server_error
+
+  non_retryable_errors:
+    - invalid_request
+    - authentication
+
+agents:
+
+  ocr:
+    name: ocr
+    description: "Visual OCR for math and geometry problems. Default: high-precision direct VLM."
+    ocr_engine: vlm  # Options: 'vlm' (default direct multimodal VLM, 0 RAM/CPU, accurate Vietnamese) | 'pix2text' (local OCR engine with confidence gateway)
+
+    tiers:
+      - model: gemini/gemini-3.5-flash-lite
+        max_attempts: 1
+        reasoning_effort: low
+
+    temperature: 0.1
+    max_tokens: 4096
+    timeout_seconds: 60
+
+    confidence_gateway:
+      enabled: true
+      threshold: 0.85
+
+      correction:
+        enabled: true
+        model: gemini/gemini-3.5-flash-lite
+        temperature: 0.1
+        max_tokens: 4096
+        timeout_seconds: 60
+        max_attempts: 1
+        reasoning_effort: low
+
+
+
+  geometry_parser:
+    name: geometry_parser
+    description: "Semantic geometry parsing and Geometry DSL generation"
+
+    tiers:
+      - model: gemini/gemini-3.5-flash-lite
+        max_attempts: 1
+        reasoning_effort: low
+
+      - model: gemini/gemini-3.5-flash
+        max_attempts: 1
+        reasoning_effort: medium
+
+    temperature: 0.1
+    max_tokens: 16384
+    timeout_seconds: 120
+
+
+  reasoning_solver:
+    name: reasoning_solver
+    description: "Program-aided mathematical reasoning with SymPy verification"
+
+    tiers:
+      - model: gemini/gemini-3.6-flash
+        max_attempts: 1
+        reasoning_effort: high
+
+      - model: gemini/gemini-3.7-flash
+        max_attempts: 1
+        reasoning_effort: high
+
+    temperature: 0.1
+    max_tokens: 16384
+    timeout_seconds: 120
+
+

config/loader.py

@@ -0,0 +1,85 @@
+import os
+import yaml
+import logging
+from pathlib import Path
+from typing import Optional, Dict
+from config.schemas import AgentConfig, AgentModelsConfig
+
+logger = logging.getLogger(__name__)
+
+_CACHED_CONFIG: Optional[AgentModelsConfig] = None
+_DEFAULT_CONFIG_PATH = Path(__file__).parent / "agent_models.yaml"
+
+
+class AgentConfigResolver:
+    """Resolves and validates typed AgentConfig from agent_models.yaml."""
+
+    def __init__(self, config_path: Optional[Path] = None):
+        self.config_path = config_path or _DEFAULT_CONFIG_PATH
+        self._config: Optional[AgentModelsConfig] = None
+        self._load()
+
+    def _load(self) -> None:
+        if not self.config_path.exists():
+            raise FileNotFoundError(f"Agent models config file not found: {self.config_path}")
+
+        try:
+            with open(self.config_path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+            # Strict validation with Pydantic
+            self._config = AgentModelsConfig(**data)
+            logger.info(
+                f"[AgentConfigResolver] Loaded {len(self._config.agents)} agent configs from {self.config_path}"
+            )
+        except Exception as e:
+            logger.error(f"[AgentConfigResolver] Failed to parse agent_models.yaml: {e}", exc_info=True)
+            raise
+
+    def get_agent_config(self, agent_name: str) -> AgentConfig:
+        if not self._config:
+            self._load()
+        if not self._config or agent_name not in self._config.agents:
+            # Fallback or generic agent config
+            logger.warning(
+                f"[AgentConfigResolver] Agent '{agent_name}' not defined in config, using defaults."
+            )
+            from config.schemas import ModelTier
+            return AgentConfig(
+                name=agent_name,
+                description=f"Auto-generated fallback config for {agent_name}",
+                tiers=[
+                    ModelTier(model="gemini/gemini-3.7-flash", max_attempts=1),
+                    ModelTier(model="gemini/gemini-3.6-flash", max_attempts=1),
+                    ModelTier(model="gemini/gemini-3.5-flash", max_attempts=1),
+                    ModelTier(model="gemini/gemini-2.5-flash", max_attempts=1),
+                ],
+                temperature=0.2,
+                max_tokens=8192,
+                timeout_seconds=120,
+            )
+        return self._config.agents[agent_name]
+
+    @property
+    def config(self) -> AgentModelsConfig:
+        if not self._config:
+            self._load()
+        return self._config  # type: ignore
+
+
+_RESOLVER_INSTANCE: Optional[AgentConfigResolver] = None
+
+
+def get_agent_config_resolver() -> AgentConfigResolver:
+    global _RESOLVER_INSTANCE
+    if _RESOLVER_INSTANCE is None:
+        _RESOLVER_INSTANCE = AgentConfigResolver()
+    return _RESOLVER_INSTANCE
+
+
+def load_agent_config(agent_name: str) -> AgentConfig:
+    return get_agent_config_resolver().get_agent_config(agent_name)
+
+
+def get_agent_models_config() -> AgentModelsConfig:
+    return get_agent_config_resolver().config

config/schemas.py

@@ -0,0 +1,76 @@
+from typing import List, Dict, Optional, Literal
+from pydantic import BaseModel, Field, field_validator
+
+
+class ModelTier(BaseModel):
+    """Configuration for a specific model tier within an agent's cascade."""
+    model: str = Field(..., description="Provider/Model string, e.g. gemini/gemini-2.5-flash")
+    max_attempts: int = Field(default=1, ge=1, le=5, description="Max attempts with this model tier")
+    reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
+        default=None, description="Reasoning effort for this specific model tier"
+    )
+
+    @field_validator("model")
+    @classmethod
+    def validate_model_format(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("Model identifier cannot be empty")
+        return v
+
+
+class OCRCorrectionConfig(BaseModel):
+    """Configuration for optional VLM-based OCR correction."""
+    enabled: bool = Field(default=True, description="Whether VLM correction is enabled when gateway triggers")
+    model: str = Field(default="gemini/gemini-3.5-flash-lite", description="VLM model for OCR correction")
+    temperature: float = Field(default=0.1, ge=0.0, le=2.0, description="VLM correction temperature")
+    max_tokens: int = Field(default=4096, gt=0, description="Max output tokens for VLM correction")
+    timeout_seconds: int = Field(default=60, gt=0, description="VLM correction timeout")
+    max_attempts: int = Field(default=1, ge=1, le=3, description="Max VLM correction attempts")
+    reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
+        default="low", description="Reasoning effort for VLM OCR correction"
+    )
+
+
+class ConfidenceGatewayConfig(BaseModel):
+    """OCR confidence gateway configuration."""
+    enabled: bool = Field(default=True, description="Enable confidence-based gateway")
+    threshold: float = Field(default=0.85, ge=0.0, le=1.0, description="Confidence threshold below which VLM correction triggers")
+    correction: OCRCorrectionConfig = Field(default_factory=OCRCorrectionConfig)
+
+
+class AgentConfig(BaseModel):
+    """Configuration for a specific agent in MathSolver."""
+    name: str = Field(..., description="Unique agent identifier")
+    description: Optional[str] = Field(default=None, description="Agent responsibility summary")
+    tiers: List[ModelTier] = Field(..., min_length=1, description="Cascading model tiers in execution priority")
+    temperature: float = Field(default=0.2, ge=0.0, le=2.0, description="Sampling temperature")
+    max_tokens: int = Field(default=8192, gt=0, description="Max output tokens")
+    timeout_seconds: int = Field(default=120, gt=0, description="Timeout in seconds")
+    reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
+        default=None, description="Reasoning effort for thinking models"
+    )
+    ocr_engine: Optional[Literal["vlm", "pix2text", "auto"]] = Field(
+        default="vlm", description="OCR engine: 'vlm' (default direct multimodal VLM) or 'pix2text' (local OCR)"
+    )
+    confidence_gateway: Optional[ConfidenceGatewayConfig] = Field(
+        default=None, description="OCR confidence gateway config (only for OCR agent)"
+    )
+
+
+class RetryPolicyConfig(BaseModel):
+    """Global retry policy configuration."""
+    retryable_errors: List[str] = Field(
+        default_factory=lambda: ["rate_limit", "timeout", "connection", "server_error"]
+    )
+    non_retryable_errors: List[str] = Field(
+        default_factory=lambda: ["invalid_request", "authentication"]
+    )
+
+
+class AgentModelsConfig(BaseModel):
+    """Top-level agent models configuration schema."""
+    version: int = Field(default=1)
+    defaults: Dict[str, object] = Field(default_factory=dict)
+    retry_policy: RetryPolicyConfig = Field(default_factory=RetryPolicyConfig)
+    agents: Dict[str, AgentConfig] = Field(..., description="Mapping of agent names to their configurations")

config/settings.py

@@ -0,0 +1,75 @@
+import os
+from pathlib import Path
+from typing import List, Dict
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+
+# Load from backend/.env if available
+_env_path = Path(__file__).parents[1] / ".env"
+if _env_path.exists():
+    load_dotenv(dotenv_path=_env_path)
+else:
+    load_dotenv()
+
+
+
+class ProviderCredentials(BaseModel):
+    provider: str
+    keys: List[str] = Field(default_factory=list)
+
+
+def parse_comma_separated_keys(raw: str) -> List[str]:
+    if not raw:
+        return []
+    keys = []
+    for piece in raw.split(","):
+        cleaned = piece.strip().strip("'\" ")
+        if cleaned:
+            keys.append(cleaned)
+    return keys
+
+
+class Settings(BaseModel):
+    app_env: str = Field(default_factory=lambda: os.getenv("APP_ENV", "development"))
+    redis_url: str = Field(default_factory=lambda: os.getenv("REDIS_URL", "redis://localhost:6379/0"))
+    llm_timeout_seconds: int = Field(default_factory=lambda: int(os.getenv("LLM_TIMEOUT_SECONDS", "120")))
+    llm_cooldown_seconds: int = Field(default_factory=lambda: int(os.getenv("LLM_COOLDOWN_SECONDS", "60")))
+    default_chat_model: str = Field(default_factory=lambda: os.getenv("DEFAULT_CHAT_MODEL", "gemini/gemini-3.7-flash"))
+
+    def get_provider_credentials(self) -> Dict[str, ProviderCredentials]:
+        """Parses API keys for all supported providers from environment variables."""
+        credentials: Dict[str, ProviderCredentials] = {}
+
+        # 1. Gemini / Google
+        gemini_raw = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY") or ""
+        gemini_keys = parse_comma_separated_keys(gemini_raw)
+        # Also check indexed keys GEMINI_API_KEY_1, GEMINI_API_KEY_2, etc.
+        for i in range(1, 20):
+            k = os.getenv(f"GEMINI_API_KEY_{i}") or os.getenv(f"GOOGLE_API_KEY_{i}")
+            if k and k.strip() and k.strip() not in gemini_keys:
+                gemini_keys.append(k.strip())
+        credentials["gemini"] = ProviderCredentials(provider="gemini", keys=gemini_keys)
+
+        # 2. OpenAI
+        openai_raw = os.getenv("OPENAI_API_KEY") or ""
+        openai_keys = parse_comma_separated_keys(openai_raw)
+        for i in range(1, 10):
+            k = os.getenv(f"OPENAI_API_KEY_{i}")
+            if k and k.strip() and k.strip() not in openai_keys:
+                openai_keys.append(k.strip())
+        credentials["openai"] = ProviderCredentials(provider="openai", keys=openai_keys)
+
+        # 3. Anthropic
+        anthropic_raw = os.getenv("ANTHROPIC_API_KEY") or ""
+        anthropic_keys = parse_comma_separated_keys(anthropic_raw)
+        credentials["anthropic"] = ProviderCredentials(provider="anthropic", keys=anthropic_keys)
+
+        # 4. OpenRouter
+        openrouter_raw = os.getenv("OPENROUTER_API_KEY") or os.getenv("OPENROUTER_API_KEY_1") or ""
+        openrouter_keys = parse_comma_separated_keys(openrouter_raw)
+        credentials["openrouter"] = ProviderCredentials(provider="openrouter", keys=openrouter_keys)
+
+        return credentials
+
+
+settings = Settings()

eval/__init__.py

@@ -0,0 +1,24 @@
+from eval.benchmark import BenchmarkDataset, BenchmarkSample
+from eval.metrics import (
+    OCRMetrics,
+    ParserMetrics,
+    PipelineEvalSummary,
+    SolverMetrics,
+    compute_cer,
+    compute_wer,
+    latex_match,
+)
+from eval.runner import EvalRunner
+
+__all__ = [
+    "BenchmarkDataset",
+    "BenchmarkSample",
+    "OCRMetrics",
+    "ParserMetrics",
+    "SolverMetrics",
+    "PipelineEvalSummary",
+    "EvalRunner",
+    "compute_cer",
+    "compute_wer",
+    "latex_match",
+]

eval/benchmark.py

@@ -0,0 +1,71 @@
+"""
+Benchmark Dataset Models and Loader for MathSolver Evaluation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class BenchmarkSample(BaseModel):
+    """Evaluation sample definition representing a standardized geometry problem."""
+    id: str = Field(..., description="Unique sample identifier")
+    category: str = Field(default="geometry", description="Problem category: geometry, algebra, 3d, 2d")
+    image_url: Optional[str] = Field(default=None, description="Image URL if testing OCR")
+    problem_text: str = Field(..., description="Canonical Vietnamese/LaTeX problem statement")
+    expected_type: Optional[str] = Field(default=None, description="Expected shape type (e.g. pyramid, cube)")
+    expected_entities: Optional[List[str]] = Field(default=None, description="Expected primary entities")
+    expected_dsl: Optional[str] = Field(default=None, description="Reference Geometry DSL")
+    expected_answer: Optional[str] = Field(default=None, description="Ground-truth final answer / value")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional reference annotations")
+
+
+class BenchmarkDataset:
+    """Benchmark dataset container."""
+
+    def __init__(self, samples: List[BenchmarkSample]):
+        self.samples = samples
+
+    def __len__(self) -> int:
+        return len(self.samples)
+
+    def __iter__(self):
+        return iter(self.samples)
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "BenchmarkDataset":
+        """Loads benchmark samples from a JSON file."""
+        file_path = Path(path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Benchmark file not found: {file_path}")
+
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        if isinstance(data, list):
+            samples = [BenchmarkSample(**item) for item in data]
+        elif isinstance(data, dict) and "samples" in data:
+            samples = [BenchmarkSample(**item) for item in data["samples"]]
+        else:
+            raise ValueError(f"Unrecognized benchmark dataset format in {file_path}")
+
+        return cls(samples)
+
+    @classmethod
+    def load_all_standard(cls, base_dir: Optional[Path] = None) -> "BenchmarkDataset":
+        """Loads all JSON files under eval/datasets/."""
+        if base_dir is None:
+            base_dir = Path(__file__).parent / "datasets"
+
+        all_samples: List[BenchmarkSample] = []
+        for json_file in base_dir.rglob("*.json"):
+            try:
+                ds = cls.from_file(json_file)
+                all_samples.extend(ds.samples)
+            except Exception:
+                pass
+
+        return cls(all_samples)

eval/datasets/README.md

@@ -0,0 +1,33 @@
+# MathSolver Benchmark Datasets
+
+Standardized evaluation benchmarks for regression testing, metric tracking, and ablation studies.
+
+## Dataset Structure
+
+Each JSON file in `eval/datasets/` contains problem samples adhering to the `BenchmarkSample` schema:
+
+```json
+{
+  "id": "geo_01_square_pyramid",
+  "category": "3d_pyramid",
+  "problem_text": "Cho hình chóp S.ABCD...",
+  "expected_type": "pyramid",
+  "expected_entities": ["S", "A", "B", "C", "D"],
+  "expected_dsl": "PYRAMID(S_ABCD)\nSQUARE(ABCD)...",
+  "expected_answer": "32"
+}
+```
+
+## Running Evaluation
+
+To evaluate deterministic DSL solvability & geometry validator pass rates:
+
+```python
+from eval.benchmark import BenchmarkDataset
+from eval.runner import EvalRunner
+
+dataset = BenchmarkDataset.load_all_standard()
+runner = EvalRunner()
+metrics = runner.evaluate_dsl_deterministic(dataset)
+print(metrics.to_dict())
+```