Upload 57 files

Initial Commit For Deployment.

Dockerfile

@@ -0,0 +1,42 @@
+# Use an official Python runtime as a parent image
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE 1
+ENV PYTHONUNBUFFERED 1
+ENV PORT 7860
+ENV HOME=/home/user
+ENV TRANSFORMERS_CACHE=$HOME/.cache
+
+# Create a non-root user
+RUN useradd -m -u 1000 user
+USER user
+WORKDIR $HOME/app
+
+# Set path
+ENV PATH="/home/user/.local/bin:${PATH}"
+
+# Install system dependencies (as root)
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+USER user
+
+# Install Python dependencies
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Pre-download the embedding model
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('BAAI/bge-small-en-v1.5')"
+
+# Copy the rest of the backend code
+COPY --chown=user . .
+
+# Expose the port the app runs on
+EXPOSE 7860
+
+# Run the application
+CMD ["uvicorn", "core.app:app", "--host", "0.0.0.0", "--port", "7860"]

add_what_happened_column.py

@@ -0,0 +1,54 @@
+import asyncio
+from repositories.postgres_repo import get_pool
+
+
+async def _column_exists(conn, table: str, column: str) -> bool:
+    return bool(
+        await conn.fetchval(
+            """
+            SELECT EXISTS (
+                SELECT 1
+                FROM information_schema.columns
+                WHERE table_schema = current_schema()
+                  AND table_name = $1
+                  AND column_name = $2
+            )
+            """,
+            table,
+            column,
+        )
+    )
+
+
+async def main():
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        has_pre_thinking = await _column_exists(conn, "messages", "pre_thinking")
+        has_what_happened = await _column_exists(conn, "messages", "what_happened")
+
+        if has_what_happened and not has_pre_thinking:
+            await conn.execute(
+                "ALTER TABLE messages RENAME COLUMN what_happened TO pre_thinking"
+            )
+            print("Renamed messages.what_happened to messages.pre_thinking")
+        elif has_what_happened and has_pre_thinking:
+            await conn.execute(
+                """
+                UPDATE messages
+                SET pre_thinking = COALESCE(pre_thinking, what_happened)
+                WHERE what_happened IS NOT NULL
+                """
+            )
+            await conn.execute("ALTER TABLE messages DROP COLUMN what_happened")
+            print("Merged data into pre_thinking and dropped what_happened")
+        elif not has_pre_thinking:
+            await conn.execute(
+                "ALTER TABLE messages ADD COLUMN pre_thinking JSONB DEFAULT NULL"
+            )
+            print("Added messages.pre_thinking")
+        else:
+            print("messages.pre_thinking already present; no changes needed")
+    await pool.close()
+
+
+asyncio.run(main())

agents/__init__.py

@@ -0,0 +1,38 @@
+# Agents module — re-exports agent graph builders and node functions
+from agents.convo_agent import (
+    get_tool_agent_graph,
+    agent_node,
+    tool_node,
+    should_continue,
+    run_tool_agent_stream,
+)
+from agents.orchestrator_agent import (
+    get_deep_research_graph,
+    deep_research_node,
+    parallel_researchers_node,
+    aggregator_node,
+    critic_node,
+)
+from agents.debate_agent import (
+    get_agent_a_persona,
+    get_agent_b_persona,
+    get_verifier_persona,
+    get_debate_model,
+    create_proposer_agent,
+    create_critic_agent,
+    create_verifier_agent,
+)
+from agents.coding_agent import (
+    code_planner_node,
+    parallel_coders_node,
+    code_aggregator_node,
+    code_reviewer_node,
+    should_retry,
+    format_output_node,
+    get_node_coords,
+)
+from agents.smart_orchestrator import (
+    classify_query,
+    get_standard_node_coords,
+    get_deep_research_node_coords,
+)

agents/coding_agent.py

@@ -0,0 +1,410 @@
+import json
+import asyncio
+import re
+from typing import Any, Callable
+from core.llm_engine import get_llm
+from core.config import AgentConfig
+from schemas.schema import CodingAgentState, CodingSubtask
+from langchain_core.messages import HumanMessage, SystemMessage
+from utils.json_helpers import (
+    sanitize_fenced_json,
+    extract_first_json_object,
+    load_json_object,
+    clamp_score,
+    normalize_text,
+    normalize_errors,
+    normalize_serious_mistakes,
+)
+from utils.graph_nodes import get_coding_node_coords
+
+
+# ─── Node Coordinates (for frontend graph) ────────────────────────────────────
+
+NODE_COORDS = get_coding_node_coords()
+
+
+def get_node_coords() -> dict:
+    """Return the node coordinate map for frontend graph rendering."""
+    return NODE_COORDS
+
+
+# ─── Code Planner Node ───────────────────────────────────────────────────────
+
+async def code_planner_node(state: CodingAgentState) -> dict:
+    """Decomposes the task into coding subtasks with shared interface."""
+    llm = get_llm(temperature=AgentConfig.CodingAgent.PLANNER_TEMPERATURE, instant=True)
+    task = state["original_task"]
+
+    prompt = f"""You are a senior software architect. Given the following coding task, break it into multiple independent subtasks that can be implemented in parallel.
+
+            Task: {task}
+
+            INSTRUCTIONS:
+            - Analyze what the task requires (could be any language: Python, HTML/CSS/JS, Java, etc.)
+            - Break it into Multiple logical, independent subtasks
+            - Each subtask should have a clear description of what it implements
+            - Include file names if the task naturally produces multiple files.
+            - The shared_contract should describe the overall structure/interfaces that all agents must respect
+
+            Respond in EXACTLY this JSON format (no other text):
+            {{
+            "subtasks": [
+                {{
+                "id": 1,
+                "description": "Clear description of what this subtask implements",
+                "signatures": ["Describe the key elements/functions this subtask should produce"]
+                }},
+                {{
+                "id": 2,
+                "description": "Clear description of what this subtask implements",
+                "signatures": ["Describe the key elements/functions this subtask should produce"]
+                }},
+                {{
+                "id": 3,
+                "description": "Clear description of what this subtask implements",
+                "signatures": ["Describe the key elements/functions this subtask should produce"]
+                }}
+            ],
+            "shared_contract": "Overall structure and interfaces that all agents must respect"
+            }}
+
+            Each subtask should be independently implementable. The shared_contract must describe the overall structure so each coder knows how their work fits with others."""
+
+    response = await llm.ainvoke([
+        SystemMessage(content="You are a software architect. Output only valid JSON."),
+        HumanMessage(content=prompt),
+    ])
+
+    try:
+        content = response.content.strip()
+        if "```json" in content:
+            content = content.split("```json")[1].split("```")[0].strip()
+        elif "```" in content:
+            content = content.split("```")[1].split("```")[0].strip()
+        parsed = json.loads(content)
+        subtasks = parsed.get("subtasks", [])
+        shared_contract = parsed.get("shared_contract", "")
+    except Exception:
+        subtasks = [
+            {"id": 1, "description": f"Implement core data structures for: {task}", "signatures": ["Core structures and data types"]},
+            {"id": 2, "description": f"Implement main algorithm/logic for: {task}", "signatures": ["Main logic and algorithms"]},
+            {"id": 3, "description": f"Implement helper functions and utilities for: {task}", "signatures": ["Helper functions and utilities"]},
+        ]
+        shared_contract = "All agents should implement their assigned parts with clear interfaces."
+
+    while len(subtasks) < 3:
+        subtasks.append({"id": len(subtasks) + 1, "description": f"Additional implementation for: {task}", "signatures": []})
+
+    coding_subtasks: list[CodingSubtask] = []
+    for st in subtasks[:3]:
+        coding_subtasks.append({
+            "id": st.get("id", len(coding_subtasks) + 1),
+            "description": st.get("description", ""),
+            "signatures": st.get("signatures", []),
+            "result": None,
+        })
+
+    return {
+        "subtasks": coding_subtasks,
+        "shared_contract": shared_contract,
+    }
+
+
+# ─── Parallel Coders Node ──────���─────────────────────────────────────────────
+
+async def parallel_coders_node(state: CodingAgentState) -> dict:
+    """Runs 3 coding agents in parallel, each implementing its subtask."""
+    subtasks = state["subtasks"]
+    shared_contract = state["shared_contract"]
+    original_task = state["original_task"]
+
+    async def run_coder(subtask: CodingSubtask, coder_idx: int) -> str:
+        llm = get_llm(temperature=AgentConfig.CodingAgent.CODER_TEMPERATURE, change=False)
+        signatures_text = "\n".join(subtask.get("signatures", []))
+
+        prompt = f"""You are Coding Agent {coder_idx + 1}. You are part of a team implementing: {original_task}
+
+        YOUR SPECIFIC TASK:
+        {subtask['description']}
+
+        YOUR KEY ELEMENTS TO IMPLEMENT:
+        {signatures_text}
+
+        SHARED CONTRACT (overall structure all agents must respect):
+        {shared_contract}
+
+        IMPORTANT RULES:
+        1. Only implement the parts assigned to you
+        2. Follow the shared contract for naming, structure, and interfaces
+        3. Do NOT implement parts assigned to other agents — just reference them if needed
+        4. Write clean, well-documented code in whatever language best fits the task
+        5. Include comments explaining complex logic
+        6. After your code os written, provide a Detailed explanation separated by "---"
+
+        OUTPUT FORMAT:
+        Write your code first, then after a line with "---", write a brief explanation of what your code does and how it works.
+
+        Write your implementation:"""
+
+        response = await llm.ainvoke([
+            SystemMessage(content="You are a coding agent. Write clean, well-documented code in whatever language best fits the task. After your code, provide a brief explanation."),
+            HumanMessage(content=prompt),
+        ])
+        return response.content
+
+    tasks = [run_coder(subtasks[i], i) for i in range(min(3, len(subtasks)))]
+    results = await asyncio.gather(*tasks)
+
+    cleaned_results = []
+    for result in results:
+        cleaned = re.sub(r'```\w*\n', '', result)
+        cleaned = cleaned.replace('```', '').strip()
+        cleaned_results.append(cleaned)
+    results = cleaned_results
+
+    while len(results) < 3:
+        results.append("# No implementation provided")
+
+    return {"coder_results": list(results)}
+
+
+# ─── Code Aggregator Node ─────────────────────────────────────────────────────
+
+async def code_aggregator_node(state: CodingAgentState) -> dict:
+    """Merges 3 coder outputs into one coherent codebase."""
+    llm = get_llm(temperature=AgentConfig.CodingAgent.AGGREGATOR_TEMPERATURE, change=True)
+    coder_results = state["coder_results"]
+    shared_contract = state["shared_contract"]
+    original_task = state["original_task"]
+    review_errors = state.get("review_errors", [])
+
+    coder_sections = "\n\n".join(
+        f"--- Coder {i+1} Output ---\n{result}" for i, result in enumerate(coder_results)
+    )
+
+    error_section = ""
+    if review_errors:
+        error_section = f"""
+                CRITICAL: The previous version had these errors that MUST be fixed:
+                {chr(10).join(f'- {e}' for e in review_errors)}
+
+                You MUST address all of these errors in your merged output.
+                """
+
+    prompt = f"""You are a senior code aggregator. Your job is to merge 3 coding agent outputs into a working, production-ready codebase.
+
+                Original Task: {original_task}
+
+                Shared Contract (overall structure all agents agreed on):
+                {shared_contract}
+
+                Coder Outputs (each coder includes code + explanation separated by "---"):
+                {coder_sections}
+                {error_section}
+                
+                CRITICAL INSTRUCTIONS:
+                1. Output MULTIPLE files if the task naturally requires it
+                2. Use this EXACT format to separate files — NO markdown fences, ONLY use the file separator:
+                # === FILE: filename ===
+                [raw code content here, NO fences]
+                
+                # === FILE: another_file ===
+                [raw code content here, NO fences]
+
+                3. Preserve the explanations from each coder. Write them in response in such manner that it preserve the Explantions as well as the Flow.
+                4. Do NOT add new functionality — only merge, fix references, and ensure interoperability
+                5. ABSOLUTELY DO NOT use markdown code fences (```) — output raw code only.
+
+                Merged code:"""
+
+    response = await llm.ainvoke([HumanMessage(content=prompt)])
+    return {"merged_code": response.content}
+
+
+# ─── Code Reviewer Node ───────────────────────────────────────────────────────
+
+async def code_reviewer_node(state: CodingAgentState) -> dict:
+    """Reviews merged code for correctness and returns scores + errors."""
+    llm = get_llm(temperature=AgentConfig.CodingAgent.REVIEWER_TEMPERATURE, change=True)
+    merged_code = state["merged_code"]
+    original_task = state["original_task"]
+    retry_count = state.get("retry_count", 0)
+
+    prompt = f"""You are a strict code reviewer and quality gate.
+
+            Evaluate the merged code against the original task and report only concrete, high-value findings.
+
+            SCORING RUBRIC (integer 0-100):
+            - confidence: Correctness and production readiness of the implementation.
+              0-39 = fundamentally broken/incomplete; 40-69 = partially correct with major gaps;
+              70-89 = mostly correct with manageable issues; 90-100 = robust, correct, and production-ready.
+            - consistency: Internal coherence and contract alignment across files/interfaces.
+              0-39 = contradictory/incompatible; 40-69 = mixed integration quality;
+              70-89 = coherent with minor integration issues; 90-100 = cleanly integrated and consistent.
+
+            ISSUE CRITERIA:
+            - "errors": blocker defects that must be fixed before acceptance.
+            - "serious_mistakes": security vulnerabilities, requirement misses, data-loss risks,
+              broken interfaces, or logic errors with high user impact.
+            Every issue must be specific and actionable.
+
+            Original Task: {original_task}
+
+            Code to Review:
+            {merged_code}
+
+            Output contract (STRICT JSON ONLY; no markdown/backticks/preamble):
+            {{
+            "confidence": 0,
+            "consistency": 0,
+            "friendly_feedback": "2-4 sentence summary with concrete next steps.",
+            "errors": ["Actionable blocker 1", "Actionable blocker 2"],
+            "serious_mistakes": [
+                {{
+                "severity": "high|critical",
+                "description": "What is wrong and where it appears.",
+                "action": "Specific fix to apply."
+                }}
+            ]
+            }}
+            If there are no blockers, return "errors": [].
+            If there are no serious mistakes, return "serious_mistakes": []."""
+
+    response = await llm.ainvoke([
+        SystemMessage(content="You are a data-formatting agent. Output raw JSON only."),
+        HumanMessage(content=prompt)
+    ])
+    parse_error = ""
+    parsed: dict[str, Any] = {}
+    try:
+        parsed = load_json_object(response.content if isinstance(response.content, str) else str(response.content))
+    except ValueError as exc:
+        parse_error = str(exc)
+
+    confidence_default = 25 if parse_error else 70
+    consistency_default = 25 if parse_error else 70
+    confidence = clamp_score(parsed.get("confidence"), default=confidence_default)
+    consistency = clamp_score(
+        parsed.get("consistency", parsed.get("logical_consistency", parsed.get("consistency_score"))),
+        default=consistency_default,
+    )
+    errors = normalize_errors(parsed.get("errors", parsed.get("review_errors", [])))
+    if parse_error and not errors:
+        errors = [
+            "Reviewer output was not valid JSON. Re-run merge/review and verify every requirement explicitly."
+        ]
+
+    feedback = normalize_text(parsed.get("friendly_feedback", parsed.get("critic_feedback")))
+    if not feedback:
+        feedback = (
+            "Reviewer output failed strict JSON validation; a conservative failure response was applied."
+            if parse_error
+            else "Review complete. Address blockers and rerun the reviewer."
+        )
+
+    serious_mistakes = normalize_serious_mistakes(parsed.get("serious_mistakes", []))
+    if parse_error and not serious_mistakes:
+        serious_mistakes = [
+            {
+                "severity": "high",
+                "description": "Reviewer response was not valid JSON, reducing trust in the quality gate.",
+                "action": "Regenerate reviewer output with strict JSON-only compliance.",
+            }
+        ]
+
+    return {
+        "confidence_score": confidence,
+        "logical_consistency": consistency,
+        "review_errors": errors,
+        "critic_feedback": feedback,
+        "serious_mistakes": serious_mistakes,
+        "retry_count": retry_count + 1,
+    }
+
+
+# ─── Retry Logic ──────────────────────────────────────────────────────────────
+
+def should_retry(state: CodingAgentState) -> str:
+    """Decide whether to retry aggregation or format final output."""
+    if state.get("review_errors") and state["retry_count"] < 2:
+        return "code_aggregator"
+    return "format_output"
+
+
+# ─── Format Output Node ───────────────────────────────────────────────────────
+
+def detect_language(content: str) -> str:
+    """Detect the programming language from code content."""
+    content_lower = content.lower().strip()
+    if "<!doctype html>" in content_lower or "<html" in content_lower or "<form" in content_lower or "<div" in content_lower:
+        return "html"
+    if content.strip().startswith(("body {", ".class", "#id", "@keyframes", "@media")) or "{ color:" in content or "{ background:" in content:
+        return "css"
+    if "function " in content or "const " in content or "let " in content or "var " in content or "document." in content or "addEventListener" in content:
+        return "javascript"
+    if "public class " in content or "public static void main" in content or "import java." in content:
+        return "java"
+    if "def " in content or "import " in content or "class " in content or "print(" in content:
+        return "python"
+    return "python"
+
+
+async def format_output_node(state: CodingAgentState) -> dict:
+    """Parses merged code into a structured list of {filename, content, language} dicts."""
+    merged_code = state["merged_code"]
+
+    # Strip any stray markdown fences first
+    if "```" in merged_code:
+        fenced_blocks = re.findall(r'```(\w*)\n(.*?)```', merged_code, re.DOTALL)
+        if fenced_blocks:
+            merged_code = "\n\n".join(block_content.strip() for _, block_content in fenced_blocks)
+        else:
+            merged_code = re.sub(r'```\w*\n?', '', merged_code).replace('```', '').strip()
+
+    parsed_files = []
+    file_separator = "# === FILE:"
+
+    if file_separator in merged_code:
+        file_blocks = merged_code.split(file_separator)
+        for file_block in file_blocks:
+            file_block = file_block.strip()
+            if not file_block:
+                continue
+            lines = file_block.split("\n")
+            filename = lines[0].strip().replace("===", "").strip()
+            if not filename:
+                continue
+            full_content = "\n".join(lines[1:])
+            # Strip explanation after "---"
+            file_content = full_content
+            if "\n---\n" in full_content:
+                file_content = re.split(r'\n---\n', full_content, maxsplit=1)[0].strip()
+            if file_content:
+                parsed_files.append({
+                    "filename": filename,
+                    "content": file_content,
+                    "language": detect_language(file_content),
+                })
+    else:
+        all_blocks = re.findall(r'```(\w*)\n(.*?)```', merged_code, re.DOTALL)
+        ext_map = {"html": "index.html", "css": "styles.css", "javascript": "script.js", "python": "main.py", "java": "Main.java"}
+        if len(all_blocks) > 1:
+            for idx, (lang_hint, block_content) in enumerate(all_blocks):
+                block_content = block_content.strip()
+                if not block_content:
+                    continue
+                lang = lang_hint if lang_hint else detect_language(block_content)
+                filename = ext_map.get(lang, f"file_{idx + 1}.{lang or 'txt'}")
+                parsed_files.append({"filename": filename, "content": block_content, "language": lang})
+        else:
+            # Single file fallback
+            code_content = merged_code.split("\n---\n", 1)[0].strip() if "\n---\n" in merged_code else merged_code
+            lang = detect_language(code_content)
+            parsed_files.append({
+                "filename": ext_map.get(lang, "output.txt"),
+                "content": code_content,
+                "language": lang,
+            })
+
+    return {"parsed_files": parsed_files}
+

agents/convo_agent.py

@@ -0,0 +1,189 @@
+import logging
+from typing import AsyncGenerator
+from core.llm_engine import get_llm
+from utils.tools import get_tools_list, get_tools_map
+from schemas.schema import AgentState
+from langchain_core.messages import HumanMessage, ToolMessage, AIMessage
+from langgraph.graph import StateGraph, END
+
+logger = logging.getLogger(__name__)
+
+
+def agent_node(state: AgentState):
+    """LLM agent node: binds tools and invokes the model."""
+    llm = get_llm().bind_tools(get_tools_list())
+    response = llm.invoke(state["messages"])
+    return {"messages": [response]}
+
+
+def tool_node(state: AgentState):
+    """Execute tool calls from the last agent message."""
+    last_msg = state["messages"][-1]
+    tool_messages = []
+    for tc in last_msg.tool_calls:
+        tool_fn = get_tools_map().get(tc["name"])
+        if tool_fn:
+            try:
+                result = tool_fn.invoke(tc["args"])
+                tool_messages.append(
+                    ToolMessage(content=str(result), tool_call_id=tc["id"])
+                )
+            except Exception as e:
+                logger.error(f"[tool_node] Error invoking {tc['name']}: {e}")
+                tool_messages.append(
+                    ToolMessage(content=f"Tool execution failed: {str(e)}", tool_call_id=tc["id"])
+                )
+        else:
+            tool_messages.append(
+                ToolMessage(content="Tool not found.", tool_call_id=tc["id"])
+            )
+    return {"messages": tool_messages}
+
+
+def should_continue(state: AgentState):
+    """Route to tools if the agent made tool calls, otherwise end."""
+    last_msg = state["messages"][-1]
+    if hasattr(last_msg, "tool_calls") and last_msg.tool_calls:
+        return "tools"
+    return END
+
+
+# ─── Build Graph ──────────────────────────────────────────────────────────────
+
+
+def _build_graph():
+    graph = StateGraph(AgentState)
+    graph.add_node("agent", agent_node)
+    graph.add_node("tools", tool_node)
+    graph.set_entry_point("agent")
+    graph.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
+    graph.add_edge("tools", "agent")
+    return graph.compile()
+
+
+_graph = _build_graph()
+
+
+def get_tool_agent_graph():
+    """Return the compiled LangGraph tool-calling agent graph."""
+    return _graph
+
+
+# ─── Streaming Execution (3-Phase Async Generator) ───────────────────────────
+
+
+async def run_tool_agent_stream(
+    messages: list,
+) -> AsyncGenerator[dict, None]:
+    """
+    Execute the tool-calling agent with real-time streaming (3-phase).
+
+    Yields event dicts:
+        {"type": "token", "content": "...", "phase": "initial"|"final"}
+        {"type": "tool_start", "tool_name": "...", "tool_args": {...}}
+        {"type": "tool_end", "tool_name": "...", "tool_output": "..."}
+        {"type": "complete", "answer": "...", "tools_used": [...], "messages": [...]}
+
+    3-Phase flow:
+      Phase 1: Stream the initial LLM response (text tokens or tool call decision)
+      Phase 2: Execute any tool calls locally
+      Phase 3: Stream the final LLM summary after tool results
+    """
+    llm = get_llm().bind_tools(get_tools_list())
+
+    # ── Phase 1: Stream the initial response ──────────────────────────────
+    logger.info("[convo_agent] Phase 1: Streaming initial LLM response...")
+    first_response = None
+
+    for chunk in llm.stream(messages):
+        if first_response is None:
+            first_response = chunk
+        else:
+            first_response += chunk
+
+        if chunk.content:
+            yield {"type": "token", "content": chunk.content, "phase": "initial"}
+
+    messages.append(first_response)
+    has_tool_calls = bool(first_response.tool_calls)
+    logger.info(f"[convo_agent] Phase 1 complete. Tool calls: {has_tool_calls}")
+
+    # ── Phase 2: Execute tools if needed ──────────────────────────────────
+    tools_used = []
+    if has_tool_calls:
+        logger.info(
+            f"[convo_agent] Phase 2: Executing {len(first_response.tool_calls)} tool call(s)..."
+        )
+        for tc in first_response.tool_calls:
+            tool_name = tc["name"]
+            tool_args = tc["args"]
+            logger.info(
+                f"[convo_agent]   Executing tool: {tool_name} with args: {tool_args}"
+            )
+
+            yield {
+                "type": "tool_start",
+                "tool_name": tool_name,
+                "tool_args": tool_args,
+            }
+
+            tool_fn = get_tools_map().get(tool_name)
+            if tool_fn:
+                try:
+                    tool_output = tool_fn.invoke(tool_args)
+                    logger.info(
+                        f"[convo_agent]   Tool {tool_name} returned: {str(tool_output)[:200]}..."
+                    )
+                    messages.append(
+                        ToolMessage(content=str(tool_output), tool_call_id=tc["id"])
+                    )
+                    tools_used.append({"tool": tool_name, "args": tool_args})
+
+                    yield {
+                        "type": "tool_end",
+                        "tool_name": tool_name,
+                        "tool_output": str(tool_output),
+                    }
+                except Exception as e:
+                    logger.error(f"[convo_agent] Tool {tool_name} execution error: {e}")
+                    error_msg = f"Tool execution failed: {str(e)}"
+                    messages.append(
+                        ToolMessage(content=error_msg, tool_call_id=tc["id"])
+                    )
+                    yield {
+                        "type": "tool_end",
+                        "tool_name": tool_name,
+                        "tool_output": error_msg,
+                    }
+            else:
+                error_msg = f"Tool not found: {tool_name}"
+                logger.warning(f"[convo_agent]   {error_msg}")
+                messages.append(ToolMessage(content=error_msg, tool_call_id=tc["id"]))
+
+    # ── Phase 3: Final stream (summary after tool results) ────────────────
+    initial_answer = first_response.content if first_response.content else ""
+    final_answer = ""
+    if has_tool_calls:
+        logger.info("[convo_agent] Phase 3: Streaming final LLM summary...")
+        for chunk in llm.stream(messages):
+            if chunk.content:
+                final_answer += chunk.content
+                yield {"type": "token", "content": chunk.content, "phase": "final"}
+        logger.info(
+            f"[convo_agent] Phase 3 complete. Final answer length: {len(final_answer)}"
+        )
+    else:
+        final_answer = initial_answer
+        logger.info(
+            f"[convo_agent] No tool calls needed. Answer length: {len(final_answer)}"
+        )
+
+    # Combine initial + final answer for complete response
+    complete_answer = initial_answer + final_answer if has_tool_calls else final_answer
+    
+    yield {
+        "type": "complete",
+        "answer": complete_answer,
+        "tools_used": tools_used,
+        "messages": messages,
+    }

agents/debate_agent.py

@@ -0,0 +1,64 @@
+from typing import Any
+from autogen_agentchat.agents import AssistantAgent
+from core import get_autogen_groq_client
+
+MODEL = "openai/gpt-oss-20b"
+
+AGENT_A_PERSONA = """You are Agent Proposer, a confident debater who argues FOR the given topic.
+You present compelling arguments, use evidence, and directly counter your opponent's points.
+Be assertive but intellectually rigorous. Keep responses to 3-4 sentences max."""
+
+AGENT_B_PERSONA = """You are Agent Critic, a sharp debater who argues AGAINST the given topic.
+You challenge assumptions, present counterarguments, and expose weaknesses in opposing views.
+Be direct and incisive. Keep responses to 3-4 sentences max."""
+
+VERIFIER_PERSONA = """You are Agent Verifier, an impartial debate judge.
+Evaluate both sides using argument quality, evidence quality, and internal consistency.
+Return a concise verdict in 6-7 sentences, clearly stating which side argued better and why."""
+
+
+def get_agent_a_persona() -> str:
+    """Return the Proposer persona."""
+    return AGENT_A_PERSONA
+
+
+def get_agent_b_persona() -> str:
+    """Return the Critic persona."""
+    return AGENT_B_PERSONA
+
+
+def get_debate_model() -> str:
+    """Return the debate model name."""
+    return MODEL
+
+
+def get_verifier_persona() -> str:
+    """Return the verifier persona."""
+    return VERIFIER_PERSONA
+
+
+def create_proposer_agent() -> Any:
+    """Create a proposer debate agent using AutoGen."""
+    return AssistantAgent(
+        name="agent_proposer",
+        model_client=get_autogen_groq_client(model=MODEL, temperature=0.7),
+        system_message=AGENT_A_PERSONA,
+    )
+
+
+def create_critic_agent() -> Any:
+    """Create a critic debate agent using AutoGen."""
+    return AssistantAgent(
+        name="agent_critic",
+        model_client=get_autogen_groq_client(model=MODEL, temperature=0.7),
+        system_message=AGENT_B_PERSONA,
+    )
+
+
+def create_verifier_agent() -> Any:
+    """Create a verifier debate agent using AutoGen."""
+    return AssistantAgent(
+        name="agent_verifier",
+        model_client=get_autogen_groq_client(model=MODEL, temperature=0.3),
+        system_message=VERIFIER_PERSONA,
+    )

agents/orchestrator_agent.py

@@ -0,0 +1,299 @@
+import asyncio
+import json
+from typing import Any
+from core.llm_engine import get_llm
+from core.config import AgentConfig
+from schemas.schema import OrchestratorState
+from langchain_core.messages import HumanMessage, SystemMessage
+from langgraph.graph import StateGraph, END
+from utils.json_helpers import (
+    sanitize_fenced_json,
+    extract_first_json_object,
+    load_json_object,
+    clamp_score,
+    normalize_text,
+    normalize_serious_mistakes,
+)
+
+
+# ─── Parallel Orchestrator (2 Researchers + Aggregator) ──────────────────────
+
+def deep_research_node(state: OrchestratorState):
+    """Analyzes the task and creates 2 researcher subtasks with different perspectives + 1 aggregator."""
+    task = state["original_task"]
+    llm = get_llm(temperature=AgentConfig.OrchestratorAgent.DECOMPOSER_TEMPERATURE)
+
+    prompt = f"""You are a task decomposer. Your job is to analyze the given task and break it into exactly 2 research assignments with different perspectives, plus 1 aggregation task.
+
+IMPORTANT RULES:
+- The context provided is ONLY for your background understanding. Do NOT include it in your output.
+- Each researcher gets a DIFFERENT angle/perspective on the task.
+- Researcher 1 should focus on facts, data, core concepts, and established knowledge.
+- Researcher 2 should focus on alternative viewpoints, debates, controversies, and edge cases.
+- Keep descriptions concise but specific to each researcher's angle.
+- Output ONLY valid JSON.
+
+Task: {task}
+
+Respond in EXACTLY this JSON format (no markdown, no backticks):
+{{
+  "researcher_1": "Specific research assignment for Researcher 1 focusing on core facts and data",
+  "researcher_2": "Specific research assignment for Researcher 2 focusing on alternative perspectives and debates"
+}}"""
+
+    response = llm.invoke([
+        SystemMessage(content="You are a task decomposer. Output only valid JSON."),
+        HumanMessage(content=prompt),
+    ])
+
+    try:
+        content = response.content.strip()
+        if content.startswith("```json"):
+            content = content.replace("```json", "", 1)
+        if content.endswith("```"):
+            content = content[:-3]
+        content = content.strip()
+        parsed = json.loads(content)
+        r1_desc = parsed.get("researcher_1", f"Comprehensive research on: {task}")
+        r2_desc = parsed.get("researcher_2", f"Alternative perspectives on: {task}")
+    except Exception:
+        r1_desc = f"Comprehensive research on: {task}. Gather facts, data, background information, and existing analysis from reliable sources."
+        r2_desc = f"Alternative perspectives and debates on: {task}. Identify conflicting viewpoints, controversies, gaps in knowledge, and complementary information."
+
+    subtasks = [
+        {
+            "id": 1,
+            "description": r1_desc,
+            "agent_type": "researcher",
+            "result": None,
+        },
+        {
+            "id": 2,
+            "description": r2_desc,
+            "agent_type": "researcher",
+            "result": None,
+        },
+        {
+            "id": 3,
+            "description": "Synthesize findings from both researchers into a comprehensive final report with the required 7-section structure.",
+            "agent_type": "aggregator",
+            "result": None,
+        },
+    ]
+    logs = state.get("step_logs", [])
+    logs.append(f"🎯 Deep Research decomposed task into {len(subtasks)} subtasks (2x researcher + aggregator)")
+    return {"subtasks": subtasks, "step_logs": logs}
+
+
+async def parallel_researchers_node(state: OrchestratorState):
+    """Executes all researcher subtasks in parallel and updates their results."""
+    subtasks = state["subtasks"]
+    researcher_indices = [i for i, st in enumerate(subtasks) if st["agent_type"] == "researcher"]
+    logs = list(state.get("step_logs", []))
+    logs.append(f"🚀 Launching {len(researcher_indices)} researcher agents in parallel")
+
+    original_task = state["original_task"]
+
+    async def run_researcher(description: str) -> str:
+        llm = get_llm(temperature=AgentConfig.OrchestratorAgent.RESEARCHER_TEMPERATURE)
+        prompt = f"""Original task: {original_task}
+
+        Your research assignment: {description}
+
+        Conduct thorough research and provide detailed findings. Include facts, data, sources, and any relevant context. Be comprehensive and precise."""
+
+        response = await llm.ainvoke([
+            SystemMessage(content="You are a research agent. Your job is to thoroughly research the given topic and provide comprehensive, unique, and factual information."),
+            HumanMessage(content=prompt),
+        ])
+        return response.content
+
+    tasks = [run_researcher(subtasks[i]["description"]) for i in researcher_indices]
+    results = await asyncio.gather(*tasks)
+
+    new_subtasks = list(subtasks)
+    for idx, result in zip(researcher_indices, results):
+        st = dict(new_subtasks[idx])
+        st["result"] = result
+        new_subtasks[idx] = st
+
+    logs.append(f"✅ All {len(researcher_indices)} researchers completed")
+    return {"subtasks": new_subtasks, "step_logs": logs}
+
+
+async def aggregator_node(state: OrchestratorState):
+    """Takes aggregator subtask and both researcher results, produces the final 7-section report."""
+    subtasks = state["subtasks"]
+    aggregator_subtask = next((st for st in subtasks if st["agent_type"] == "aggregator"), None)
+    logs = list(state.get("step_logs", []))
+
+    if not aggregator_subtask:
+        logs.append("❌ No aggregator subtask found")
+        return {"final_result": "Error: Aggregator agent missing.", "step_logs": logs}
+
+    researcher_results = [st["result"] for st in subtasks if st["agent_type"] == "researcher"]
+    researcher_texts = "\n\n".join(
+        f"--- Researcher {i+1} ---\n{res}" for i, res in enumerate(researcher_results)
+    )
+
+    llm = get_llm(temperature=AgentConfig.OrchestratorAgent.AGGREGATOR_TEMPERATURE, change=True)
+    prompt = f"""You are a professional research writer. Synthesize the following research findings into a comprehensive, structured final report.
+
+            Original Task: {state['original_task']}
+
+            Research Inputs:
+            {researcher_texts}
+
+            Write a Bery High detailed report using EXACTLY these sections (use proper markdown headings):
+
+            1. Executive Summary
+            Provide a Detailed overview of the topic and main conclusions.
+
+            2. Key Findings
+            List the most important discoveries in bullet points. Also write the relatted things for the discoveries too.
+
+            3. Evidence From Sources
+            Present detailed evidence, data, and source citations.
+
+            4. Trends / Analysis
+            Analyze trends, patterns, implications, and provide insights. This Insight should be simple and Very Detailed.
+
+            5. Contradictions or Debates
+            Highlight any conflicting information, controversies, or areas of disagreement.
+
+            6. Conclusion
+            Summarize the key points and provide a forward-looking perspective.
+
+            7. Sources / Citations
+            List Major sources referenced in the research. If none were provided, note that.
+
+            Use clear markdown formatting with ## for major sections and ### for subsections where appropriate. Be comprehensive but avoid redundancy."""
+
+    response = await llm.ainvoke([HumanMessage(content=prompt)])
+    logs.append("✍️ Aggregator agent synthesized final report with 7-section structure")
+
+    new_subtasks = list(subtasks)
+    for i, st in enumerate(new_subtasks):
+        if st["agent_type"] == "aggregator":
+            new_subtasks[i] = dict(st)
+            new_subtasks[i]["result"] = response.content
+            break
+
+    return {"final_result": response.content, "subtasks": new_subtasks, "step_logs": logs}
+
+
+async def critic_node(state: OrchestratorState):
+    """Evaluates the aggregator's final output, assigns confidence and logical consistency scores."""
+    logs = list(state.get("step_logs", []))
+    final_result = state["final_result"]
+
+    llm = get_llm(temperature=AgentConfig.OrchestratorAgent.CRITIC_TEMPERATURE, change=True)
+    prompt = f"""You are a strict research quality critic.
+
+            Evaluate the report against the task and produce one JSON object only.
+
+            SCORING RUBRIC (integer 0-100):
+            - confidence: How trustworthy and well-supported the report is.
+              0-39 = major factual/support gaps; 40-69 = partial support with notable gaps;
+              70-89 = mostly supported and reliable; 90-100 = strongly supported, precise, and robust.
+            - consistency: Internal logic and alignment with the requested task/structure.
+              0-39 = contradictory or off-task; 40-69 = mixed coherence; 70-89 = coherent with minor issues;
+              90-100 = fully coherent, complete, and on-task.
+
+            SERIOUS MISTAKE CRITERIA:
+            Include only high-impact problems (fabricated claims, major missing sections, direct contradictions,
+            unsafe or misleading guidance, or conclusions unsupported by evidence).
+            Every serious mistake must describe the issue and a concrete corrective action.
+
+            Report:
+            {final_result}
+
+            Task:
+            {state['original_task']}
+
+            Output contract (STRICT JSON ONLY; no markdown/backticks/preamble):
+            {{
+            "confidence": 0,
+            "consistency": 0,
+            "friendly_feedback": "2-4 sentence actionable summary with at least one concrete next step.",
+            "serious_mistakes": [
+                {{
+                "severity": "high|critical",
+                "description": "What is wrong and where it appears.",
+                "action": "Specific fix the writer should apply."
+                }}
+            ]
+            }}
+            If none, return "serious_mistakes": [] exactly."""
+
+    response = await llm.ainvoke([
+        SystemMessage(content="You are a Self-Reflective Critic agent. Output raw JSON only."),
+        HumanMessage(content=prompt)
+    ])
+    logs.append("🔬 Critic agent evaluated output quality")
+
+    parse_error = ""
+    parsed: dict[str, Any] = {}
+    try:
+        parsed = load_json_object(response.content if isinstance(response.content, str) else str(response.content))
+    except ValueError as exc:
+        parse_error = str(exc)
+        logs.append(f"⚠️ Critic parsing error: {parse_error}")
+
+    confidence_default = 30 if parse_error else 70
+    consistency_default = 30 if parse_error else 70
+    confidence = clamp_score(parsed.get("confidence"), default=confidence_default)
+    consistency = clamp_score(
+        parsed.get("consistency", parsed.get("logical_consistency", parsed.get("consistency_score"))),
+        default=consistency_default,
+    )
+    feedback = normalize_text(parsed.get("friendly_feedback", parsed.get("critic_feedback")))
+    if not feedback:
+        feedback = (
+            "Critic output failed strict JSON validation. Re-run evaluation with strict format compliance."
+            if parse_error
+            else "Review complete. Address highlighted weaknesses to improve confidence and consistency."
+        )
+    serious_mistakes = normalize_serious_mistakes(parsed.get("serious_mistakes", []))
+    if parse_error and not serious_mistakes:
+        serious_mistakes = [
+            {
+                "severity": "high",
+                "description": "Critic output was not valid JSON, so quality scoring may be unreliable.",
+                "action": "Re-run critic with strict JSON-only output and reassess the report.",
+            }
+        ]
+
+    return {
+        "critic_confidence": confidence,
+        "critic_logical_consistency": consistency,
+        "critic_feedback": feedback,
+        "serious_mistakes": serious_mistakes,
+        "step_logs": logs,
+    }
+
+
+# ─── Build Graph ──────────────────────────────────────────────────────────────
+
+def _build_deep_research_graph():
+    graph = StateGraph(OrchestratorState)
+    graph.add_node("deep_research", deep_research_node)
+    graph.add_node("parallel_researchers", parallel_researchers_node)
+    graph.add_node("aggregator", aggregator_node)
+    graph.add_node("critic", critic_node)
+
+    graph.set_entry_point("deep_research")
+    graph.add_edge("deep_research", "parallel_researchers")
+    graph.add_edge("parallel_researchers", "aggregator")
+    graph.add_edge("aggregator", "critic")
+    graph.add_edge("critic", END)
+
+    return graph.compile()
+
+
+_deep_research_graph = _build_deep_research_graph()
+
+
+def get_deep_research_graph():
+    """Return the compiled deep_research graph."""
+    return _deep_research_graph

agents/smart_orchestrator.py

@@ -0,0 +1,64 @@
+from core.llm_engine import get_llm
+from core.config import AgentConfig
+from langchain_core.messages import HumanMessage, SystemMessage
+from utils.graph_nodes import get_standard_node_coords, get_deep_research_node_coords
+
+
+# ─── Node Coordinates for Standard & Deep Research Paths ──────────────────────
+
+STANDARD_NODE_COORDS = get_standard_node_coords()
+DEEP_RESEARCH_NODE_COORDS = get_deep_research_node_coords()
+
+
+def get_standard_node_coords() -> dict:
+    """Return node coordinates for the standard path."""
+    return STANDARD_NODE_COORDS
+
+
+def get_deep_research_node_coords() -> dict:
+    """Return node coordinates for the deep research path."""
+    return DEEP_RESEARCH_NODE_COORDS
+
+
+# ─── Query Classifier ─────────────────────────────────────────────────────────
+
+async def classify_query(task: str) -> tuple[str, str, str]:
+    """Classify the task into one of three paths and return problem understanding for code tasks."""
+    llm = get_llm(temperature=AgentConfig.SmartOrchestrator.ROUTER_TEMPERATURE, instant=True)
+
+    prompt = f"""You are a query router. Classify the following user query into exactly one category.
+
+        Query: {task}
+
+        Categories:
+        - standard: Simple factual as well as the Detailed questions, greetings, quick calculations, single-step as well as multi step tasks. Use this In most of normal QA.
+        - deep_research: Questions requiring very hard multi-perspective research, analysis, comparisons, explanations of complex topics, if the topic needs very good research then select this mode.
+        - code: Requests to write, implement, debug, or generate code, algorithms, data structures
+
+        Respond in EXACTLY this format:
+        PATH: [standard|deep_research|code]
+        UNDERSTANDING: [If PATH is code, provide a brief 2-3 sentence problem understanding explaining what the problem asks for and what the expected solution should look like. If PATH is not code, write "N/A"]
+        REASON: [brief explanation of why this path was chosen]"""
+
+    response = await llm.ainvoke([
+        SystemMessage(content="You are a query classifier. Output only the specified format."),
+        HumanMessage(content=prompt),
+    ])
+
+    content = response.content.strip()
+    path = "standard"
+    reason = "Default classification"
+    problem_understanding = "N/A"
+
+    for line in content.split("\n"):
+        line = line.strip()
+        if line.startswith("PATH:"):
+            extracted = line.split(":")[1].strip().lower()
+            if extracted in ("standard", "deep_research", "code"):
+                path = extracted
+        elif line.startswith("UNDERSTANDING:"):
+            problem_understanding = line.split(":", 1)[1].strip()
+        elif line.startswith("REASON:"):
+            reason = line.split(":", 1)[1].strip()
+
+    return path, reason, problem_understanding

core/__init__.py

@@ -0,0 +1,12 @@
+# Core module — re-exports commonly used items
+# NOTE: app is NOT imported here to avoid circular imports.
+# Import app directly: from core.app import app
+from core.llm_engine import get_llm, get_client
+from core.autogen_client import get_autogen_groq_client
+from core.auth import hash_password, verify_password, create_token, decode_token, get_current_user
+from core.exceptions import (
+    DatabaseError,
+    LLMError,
+    QdrantError,
+    register_exception_handlers,
+)

core/app.py

@@ -0,0 +1,82 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from core.exceptions import register_exception_handlers
+from repositories import init_db, close_pool, init_qdrant_collections
+from routers import (
+    auth_router,
+    chat_router,
+    history_router,
+    pdf_router,
+    debate_router,
+    admin_router,
+    reflection_router
+)
+
+app = FastAPI(title="AI Agents Platform")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Register global exception handlers
+register_exception_handlers(app)
+
+# Include all routers
+app.include_router(auth_router)
+app.include_router(chat_router)
+app.include_router(history_router)
+app.include_router(pdf_router)
+app.include_router(debate_router)
+app.include_router(admin_router)
+app.include_router(reflection_router)
+
+
+# ─── Startup / Shutdown Events ────────────────────────────────────────────────
+
+@app.on_event("startup")
+async def startup():
+    """Initialize database and Qdrant collections on server start."""
+    await init_db()
+    await close_pool()
+    try:
+        init_qdrant_collections()
+        print("[app] Qdrant collections initialized.")
+    except Exception as e:
+        print(f"[app] Qdrant initialization skipped (unavailable): {e}")
+    print("[app] Server started successfully.")
+
+
+@app.on_event("shutdown")
+async def shutdown():
+    """Close database pool on shutdown."""
+    await close_pool()
+    print("[app] Server shut down.")
+
+
+# ─── Root ──────────────────────────────────────────────────────────────────────
+
+@app.get("/")
+async def root():
+    """Root endpoint - API landing page"""
+    return {
+        "service": "Agentrix.io API",
+        "status": "operational",
+        "version": "2.6.0",
+        "endpoints": {
+            "auth_register": "/auth/register (POST)",
+            "auth_login": "/auth/login (POST)",
+            "chat": "/chat (POST)",
+            "orchestrator": "/orchestrator/task (POST)",
+            "smart_orchestrator": "/smart-orchestrator/stream (POST)",
+            "debate": "/debate/stream (GET)",
+            "upload": "/upload-pdf (POST)",
+            "memory_pdfs": "/memory/pdfs (GET)",
+            "history": "/history (GET)",
+            "reflection": "/reflection/summary (GET)",
+            "docs": "/docs",
+            "redoc": "/redoc",
+        },
+    }

core/auth.py

@@ -0,0 +1,58 @@
+import os
+from datetime import datetime, timedelta, timezone
+
+from dotenv import load_dotenv
+from fastapi import HTTPException, Header
+from jose import JWTError, jwt
+import bcrypt
+
+load_dotenv()
+
+# ─── Password Hashing ─────────────────────────────────────────────────────────
+
+
+def hash_password(plain: str) -> str:
+    """Hash a plaintext password using bcrypt."""
+    return bcrypt.hashpw(plain.encode("utf-8"), bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    """Verify a plaintext password against a bcrypt hash."""
+    return bcrypt.checkpw(plain.encode("utf-8"), hashed.encode("utf-8"))
+
+
+# ─── JWT Token ────────────────────────────────────────────────────────────────
+
+JWT_SECRET = os.getenv("JWT_SECRET", "agentrix-default-secret-change-me")
+JWT_ALGORITHM = "HS256"
+JWT_EXPIRY_DAYS = 7
+
+
+def create_token(user_id: str) -> str:
+    """Create a JWT token with 7-day expiry."""
+    payload = {
+        "sub": user_id,
+        "exp": datetime.now(timezone.utc) + timedelta(days=JWT_EXPIRY_DAYS),
+        "iat": datetime.now(timezone.utc),
+    }
+    return jwt.encode(payload, JWT_SECRET, algorithm=JWT_ALGORITHM)
+
+
+def decode_token(token: str) -> str:
+    """Decode a JWT token and return the user_id. Raises HTTPException on failure."""
+    try:
+        payload = jwt.decode(token, JWT_SECRET, algorithms=[JWT_ALGORITHM])
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise HTTPException(status_code=401, detail="Invalid token: missing subject")
+        return user_id
+    except JWTError:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
+
+
+async def get_current_user(authorization: str = Header(...)) -> str:
+    """FastAPI dependency: extracts and validates Bearer token from Authorization header."""
+    if not authorization.startswith("Bearer "):
+        raise HTTPException(status_code=401, detail="Invalid authorization header format")
+    token = authorization.split(" ", 1)[1]
+    return decode_token(token)

core/autogen_client.py

@@ -0,0 +1,30 @@
+import os
+
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+
+
+GROQ_OPENAI_BASE_URL = "https://api.groq.com/openai/v1"
+
+
+def get_autogen_groq_client(model: str, temperature: float = 0.7) -> OpenAIChatCompletionClient:
+    """Create an AutoGen-compatible OpenAI client targeting Groq."""
+    api_key = os.getenv("GROQ_API_KEY")
+    if not api_key:
+        raise ValueError("GROQ_API_KEY is required for AutoGen debate execution.")
+
+    # AutoGen 0.4 requires model_info for non-standard OpenAI model names.
+    # We provide standard capabilities for Groq-hosted models.
+    model_info = {
+        "vision": False,
+        "function_calling": True,
+        "json_output": True,
+        "family": "gpt-4",  # Using gpt-4 family as a safe baseline for capabilities
+    }
+
+    return OpenAIChatCompletionClient(
+        model=model,
+        api_key=api_key,
+        base_url=GROQ_OPENAI_BASE_URL,
+        temperature=temperature,
+        model_info=model_info,
+    )

core/config.py

@@ -0,0 +1,126 @@
+"""
+Centralized configuration module for LLM parameters, scoring, and constants.
+
+Provides single source of truth for:
+- LLM temperature profiles for different use cases
+- Scoring and confidence thresholds
+- Valid severity levels for mistakes/issues
+- Graph node coordinates (eventually)
+- Agent-specific parameters
+
+Usage:
+    from core.config import LLMConfig, ScoringConfig
+    
+    llm = get_llm(temperature=LLMConfig.PRECISE)
+    score = clamp_score(value, default=ScoringConfig.DEFAULT)
+"""
+
+
+class LLMConfig:
+    """
+    LLM temperature profiles for different use cases.
+    
+    Temperature controls randomness: 0 = deterministic, 1 = highly random.
+    - Structured: Planning, routing, critics (need precision)
+    - Precise: Code generation, technical writing (mostly deterministic)
+    - Balanced: Research, analysis, general reasoning (mix of precision & exploration)
+    - Creative: Brainstorming, alternatives (high exploration)
+    """
+    # Planning & Decision Making (deterministic)
+    STRUCTURED = 0.0
+    
+    # Code & Technical Output (precise but not rigid)
+    PRECISE = 0.1
+    
+    # Research & Analysis (balanced exploration + precision)
+    BALANCED = 0.3
+    
+    # Brainstorming & Alternatives (exploratory)
+    CREATIVE = 0.7
+
+
+class ScoringConfig:
+    """
+    Configuration for confidence and consistency scoring.
+    
+    Used for evaluating LLM output quality:
+    - Range: [MIN, MAX]
+    - Default: Used as fallback when parsing fails
+    """
+    MIN = 0
+    MAX = 100
+    DEFAULT = 50
+    
+    # Quality thresholds for evaluation feedback
+    POOR_THRESHOLD = 39        # 0-39: poor quality, requires rework
+    PARTIAL_THRESHOLD = 69     # 40-69: partial quality, has gaps
+    GOOD_THRESHOLD = 89        # 70-89: good quality, manageable issues
+    # 90-100: excellent quality, production-ready
+
+
+class SeverityConfig:
+    """
+    Valid severity levels for mistakes/issues found in LLM output.
+    
+    Used for categorizing problems:
+    - low: Minor issues, cosmetic
+    - medium: Moderate issues, affects usability
+    - high: Significant issues, affects correctness
+    - critical: Breaking issues, prevents function
+    """
+    VALID_LEVELS = {"low", "medium", "high", "critical"}
+    DEFAULT = "high"
+
+
+class CriticConfig:
+    """
+    Configuration for critic/reviewer agents.
+    
+    Used when evaluating LLM-generated code, research, or other output.
+    """
+    # Default confidence score when parsing fails
+    PARSE_ERROR_CONFIDENCE = 25
+    PARSE_ERROR_CONSISTENCY = 25
+    
+    # Default confidence score when parsing succeeds
+    SUCCESS_BASELINE_CONFIDENCE = 70
+    SUCCESS_BASELINE_CONSISTENCY = 70
+
+
+class AgentConfig:
+    """
+    Agent-specific configuration and parameters.
+    """
+    
+    class CodingAgent:
+        """Code generation and review agent configuration."""
+        # Temperature for planning/routing decisions
+        PLANNER_TEMPERATURE = LLMConfig.PRECISE
+        
+        # Temperature for parallel code generation
+        CODER_TEMPERATURE = LLMConfig.PRECISE
+        
+        # Temperature for code merging/aggregation
+        AGGREGATOR_TEMPERATURE = LLMConfig.PRECISE
+        
+        # Temperature for code review/criticism
+        REVIEWER_TEMPERATURE = LLMConfig.STRUCTURED
+    
+    class OrchestratorAgent:
+        """Deep research orchestrator agent configuration."""
+        # Temperature for research decomposition
+        DECOMPOSER_TEMPERATURE = LLMConfig.BALANCED
+        
+        # Temperature for researcher agents
+        RESEARCHER_TEMPERATURE = LLMConfig.CREATIVE
+        
+        # Temperature for research aggregation
+        AGGREGATOR_TEMPERATURE = LLMConfig.BALANCED
+        
+        # Temperature for research quality criticism
+        CRITIC_TEMPERATURE = LLMConfig.STRUCTURED
+    
+    class SmartOrchestrator:
+        """Smart routing orchestrator configuration."""
+        # Temperature for query classification and routing
+        ROUTER_TEMPERATURE = LLMConfig.STRUCTURED

core/exceptions.py

@@ -0,0 +1,54 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+
+class DatabaseError(Exception):
+    """Raised when a database operation fails."""
+
+    def __init__(self, detail: str = "Database operation failed"):
+        self.detail = detail
+        super().__init__(self.detail)
+
+
+class LLMError(Exception):
+    """Raised when an LLM call fails."""
+
+    def __init__(self, detail: str = "LLM call failed"):
+        self.detail = detail
+        super().__init__(self.detail)
+
+
+class QdrantError(Exception):
+    """Raised when a Qdrant operation fails."""
+
+    def __init__(self, detail: str = "Qdrant operation failed"):
+        self.detail = detail
+        super().__init__(self.detail)
+
+
+async def database_error_handler(request: Request, exc: DatabaseError):
+    """Handle DatabaseError globally."""
+    return JSONResponse(status_code=500, content={"detail": f"Database error: {exc.detail}"})
+
+
+async def llm_error_handler(request: Request, exc: LLMError):
+    """Handle LLMError globally."""
+    return JSONResponse(status_code=502, content={"detail": f"LLM error: {exc.detail}"})
+
+
+async def qdrant_error_handler(request: Request, exc: QdrantError):
+    """Handle QdrantError globally."""
+    return JSONResponse(status_code=502, content={"detail": f"Qdrant error: {exc.detail}"})
+
+
+async def generic_exception_handler(request: Request, exc: Exception):
+    """Catch-all handler for unhandled exceptions."""
+    return JSONResponse(status_code=500, content={"detail": f"Internal server error: {str(exc)}"})
+
+
+def register_exception_handlers(app):
+    """Register all custom exception handlers on a FastAPI app."""
+    app.add_exception_handler(DatabaseError, database_error_handler)
+    app.add_exception_handler(LLMError, llm_error_handler)
+    app.add_exception_handler(QdrantError, qdrant_error_handler)
+    app.add_exception_handler(Exception, generic_exception_handler)

core/llm_engine.py

@@ -0,0 +1,35 @@
+import os
+from groq import Groq
+from dotenv import load_dotenv
+from langchain_groq import ChatGroq
+from langchain_openai import ChatOpenAI
+
+load_dotenv()
+
+
+def get_llm(temperature: float = 0.1, change: bool = True, instant = False):
+    """Return a ChatGroq LLM instance. change=True uses Llama-4, change=False uses GPT-oss."""
+    model = "openai/gpt-oss-20b"
+    if change:
+        model = "meta-llama/llama-4-scout-17b-16e-instruct"
+    if instant:
+        model = "llama-3.1-8b-instant"
+
+    return ChatGroq(
+        model=model,
+        api_key=os.getenv("GROQ_API_KEY"),
+        temperature=temperature,
+    )
+
+
+def get_client() -> Groq:
+    """Return a raw Groq client (for streaming completions)."""
+    return Groq(api_key=os.getenv("GROQ_API_KEY"))
+
+def coding_llm(temperature: float = 0.2):
+    return ChatOpenAI(
+        model="stepfun/step-3.5-flash:free",
+        base_url="https://openrouter.ai/api/v1",
+        api_key=os.getenv("OPENROUTER_API_KEY"),
+        temperature=temperature
+    )

create_pdf_id_index.py

@@ -0,0 +1,26 @@
+"""
+One-off script to create the missing pdf_id payload index on the pdf_chunks collection.
+Run this once from the backend directory: python create_pdf_id_index.py
+"""
+import os
+from dotenv import load_dotenv
+from qdrant_client import QdrantClient
+from qdrant_client.models import PayloadSchemaType
+
+load_dotenv()
+
+client = QdrantClient(
+    url=os.getenv("QDRANT_CLIENT"),
+    api_key=os.getenv("QDRANT_API_KEY"),
+)
+
+try:
+    client.create_payload_index(
+        collection_name="pdf_chunks",
+        field_name="pdf_id",
+        field_schema=PayloadSchemaType.KEYWORD,
+    )
+    print("[OK] Created 'pdf_id' keyword index on 'pdf_chunks' collection.")
+except Exception as e:
+    print(f"[INFO] Index creation result: {e}")
+    print("(If this says 'already exists', the index was already created — you're good!)")

delete.py

@@ -0,0 +1,66 @@
+"""
+delete.py — Drop all PostgreSQL tables and Qdrant collections.
+Run this to reset the database before applying new schema changes.
+Usage: python delete.py
+"""
+
+import os
+import asyncio
+import asyncpg
+from dotenv import load_dotenv
+from qdrant_client import QdrantClient
+
+load_dotenv()
+
+
+async def drop_all_tables():
+    """Drop all tables, enums, and indexes from PostgreSQL."""
+    conn = await asyncpg.connect(os.getenv("DATABASE_URL"))
+    try:
+        # Drop tables (CASCADE handles FK dependencies)
+        await conn.execute("DROP TABLE IF EXISTS chunk_retrieval_log CASCADE;")
+        await conn.execute("DROP TABLE IF EXISTS detected_mistakes CASCADE;")
+        await conn.execute("DROP TABLE IF EXISTS debate_sessions CASCADE;")
+        await conn.execute("DROP TABLE IF EXISTS messages CASCADE;")
+        await conn.execute("DROP TABLE IF EXISTS conversations CASCADE;")
+        await conn.execute("DROP TABLE IF EXISTS users CASCADE;")
+
+        # Drop enum types
+        await conn.execute("DROP TYPE IF EXISTS conv_type CASCADE;")
+        await conn.execute("DROP TYPE IF EXISTS debate_winner CASCADE;")
+        await conn.execute("DROP TYPE IF EXISTS mistake_severity CASCADE;")
+        await conn.execute("DROP TYPE IF EXISTS reasoning_type CASCADE;")
+
+        print("[delete] All PostgreSQL tables and enums dropped.")
+    finally:
+        await conn.close()
+
+
+def drop_qdrant_collections():
+    """Delete Qdrant collections."""
+    client = QdrantClient(
+        url=os.getenv("QDRANT_CLIENT"),
+        api_key=os.getenv("QDRANT_API_KEY"),
+    )
+    collections = [c.name for c in client.get_collections().collections]
+    for name in collections:
+        client.delete_collection(name)
+        print(f"[delete] Deleted Qdrant collection: {name}")
+
+    if not collections:
+        print("[delete] No Qdrant collections found.")
+
+
+async def main():
+    print("=" * 50)
+    print("  Agentrix.io — Database Cleanup Script")
+    print("=" * 50)
+
+    await drop_all_tables()
+    drop_qdrant_collections()
+
+    print("\n[delete] Cleanup complete. Run `python main.py` to reinitialize.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

repositories/__init__.py

@@ -0,0 +1,35 @@
+# Repositories module — re-exports all database CRUD functions
+from repositories.postgres_repo import (
+    init_db,
+    close_pool,
+    get_pool,
+    create_user,
+    get_user_by_email,
+    get_user_by_id,
+    create_conversation,
+    append_message,
+    create_debate_session,
+    get_debate_session_by_conversation_id,
+    get_user_history,
+    update_conversation_timestamp,
+    rename_conversation,
+    delete_conversation,
+    clear_all_history,
+    get_conversation_with_messages,
+    log_chunk_retrieval,
+    log_detected_mistakes,
+    get_pdf_quality_scores,
+)
+from repositories.qdrant_repo import (
+    get_embedding,
+    get_qdrant_client,
+    init_qdrant_collections,
+    upsert_pdf_summary,
+    get_user_pdf_summaries,
+    upsert_pdf_chunks,
+    search_chunks,
+    search_pdf_summary,
+    search_chunks_by_pdf_id,
+    get_pdf_ids_by_names,
+    get_most_recent_pdf_id,
+)

repositories/postgres_repo.py

@@ -0,0 +1,521 @@
+import os
+import uuid
+from datetime import datetime
+import json as _json
+
+import asyncpg
+from dotenv import load_dotenv
+from core.exceptions import DatabaseError
+
+load_dotenv()
+
+_pool: asyncpg.Pool | None = None
+
+
+async def get_pool() -> asyncpg.Pool:
+    """Returns the global asyncpg connection pool singleton."""
+    global _pool
+    if _pool is None:
+        _pool = await asyncpg.create_pool(
+            os.getenv("DATABASE_URL"),
+            min_size=2,
+            max_size=10,
+        )
+    return _pool
+
+
+async def close_pool():
+    """Close the global pool on shutdown."""
+    global _pool
+    if _pool:
+        await _pool.close()
+        _pool = None
+
+
+# ─── Table Definitions ────────────────────────────────────────────────────────
+
+CREATE_TABLES_SQL = """
+-- Enum types
+DO $$ BEGIN
+    CREATE TYPE conv_type AS ENUM ('standard', 'debate');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+DO $$ BEGIN
+    CREATE TYPE reasoning_type AS ENUM ('standard', 'deep_research', 'multi_agent');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+DO $$ BEGIN
+    CREATE TYPE mistake_severity AS ENUM ('low', 'medium', 'high');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+-- 1. Users table
+CREATE TABLE IF NOT EXISTS users (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    password_hash VARCHAR(255) NOT NULL,
+    display_name VARCHAR(255),
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- 2. Conversations table
+CREATE TABLE IF NOT EXISTS conversations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    type conv_type NOT NULL DEFAULT 'standard',
+    title VARCHAR(500),
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- 3. Messages table
+-- Each row is one full query+response turn.
+-- message JSONB stores an array: [{"user": "...", "assistant": "..."}, ...]
+-- New messages are appended as new dicts in the array.
+CREATE TABLE IF NOT EXISTS messages (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+    reasoning_mode reasoning_type NOT NULL,
+    message JSONB NOT NULL DEFAULT '[]',
+    confidence NUMERIC(4,3) CHECK (confidence BETWEEN 0 AND 1),
+    consistency NUMERIC(4,3) CHECK (consistency BETWEEN 0 AND 1),
+    pre_thinking JSONB DEFAULT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- 4. Debate sessions table
+CREATE TABLE IF NOT EXISTS debate_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    conversation_id UUID NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+    topic TEXT NOT NULL,
+    debate_messages JSONB NOT NULL DEFAULT '[]',
+    verdict_text TEXT,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- 5. Detected mistakes table
+CREATE TABLE IF NOT EXISTS detected_mistakes (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message_id UUID REFERENCES messages(id) ON DELETE CASCADE,
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    description TEXT NOT NULL,
+    severity mistake_severity NOT NULL DEFAULT 'medium',
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- 6. Chunk retrieval log table
+CREATE TABLE IF NOT EXISTS chunk_retrieval_log (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    message_id UUID REFERENCES messages(id) ON DELETE CASCADE,
+    qdrant_chunk_id VARCHAR(255),
+    pdf_id VARCHAR(255),
+    similarity_score FLOAT,
+    quality_score FLOAT,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_conversations_user_id ON conversations(user_id);
+CREATE INDEX IF NOT EXISTS idx_messages_conversation_id_created ON messages(conversation_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_debate_sessions_user_id ON debate_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_debate_sessions_conversation_id ON debate_sessions(conversation_id);
+CREATE INDEX IF NOT EXISTS idx_detected_mistakes_user_id ON detected_mistakes(user_id);
+CREATE INDEX IF NOT EXISTS idx_chunk_retrieval_message_id ON chunk_retrieval_log(message_id);
+"""
+
+
+async def init_db():
+    """Initialize the database: create all tables and indexes."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        await conn.execute(CREATE_TABLES_SQL)
+        await _migrate_messages_pre_thinking(conn)
+    print("[postgres] Database initialized successfully.")
+
+
+async def _column_exists(conn: asyncpg.Connection, table: str, column: str) -> bool:
+    return bool(
+        await conn.fetchval(
+            """
+            SELECT EXISTS (
+                SELECT 1
+                FROM information_schema.columns
+                WHERE table_schema = current_schema()
+                  AND table_name = $1
+                  AND column_name = $2
+            )
+            """,
+            table,
+            column,
+        )
+    )
+
+
+async def _migrate_messages_pre_thinking(conn: asyncpg.Connection) -> None:
+    table_exists = bool(
+        await conn.fetchval(
+            """
+            SELECT EXISTS (
+                SELECT 1
+                FROM information_schema.tables
+                WHERE table_schema = current_schema()
+                  AND table_name = 'messages'
+            )
+            """
+        )
+    )
+    if not table_exists:
+        return
+
+    has_pre_thinking = await _column_exists(conn, "messages", "pre_thinking")
+    has_what_happened = await _column_exists(conn, "messages", "what_happened")
+
+    if has_what_happened and not has_pre_thinking:
+        await conn.execute(
+            "ALTER TABLE messages RENAME COLUMN what_happened TO pre_thinking"
+        )
+    elif has_what_happened and has_pre_thinking:
+        await conn.execute(
+            """
+            UPDATE messages
+            SET pre_thinking = COALESCE(pre_thinking, what_happened)
+            WHERE what_happened IS NOT NULL
+            """
+        )
+        await conn.execute("ALTER TABLE messages DROP COLUMN what_happened")
+    elif not has_pre_thinking:
+        await conn.execute("ALTER TABLE messages ADD COLUMN pre_thinking JSONB DEFAULT NULL")
+
+
+# ─── Helper Functions ─────────────────────────────────────────────────────────
+
+
+async def create_user(
+    email: str, password_hash: str, display_name: str | None = None
+) -> str:
+    """Create a new user and return their UUID."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "INSERT INTO users (email, password_hash, display_name) VALUES ($1, $2, $3) RETURNING id",
+            email,
+            password_hash,
+            display_name,
+        )
+        return str(row["id"])
+
+
+async def get_user_by_email(email: str) -> dict | None:
+    """Fetch a user by email. Returns dict or None."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "SELECT id, email, password_hash, display_name FROM users WHERE email = $1",
+            email,
+        )
+        if row:
+            return dict(row)
+        return None
+
+
+async def get_user_by_id(user_id: str) -> dict | None:
+    """Fetch a user by UUID. Returns dict or None."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "SELECT id, email, display_name FROM users WHERE id = $1",
+            uuid.UUID(user_id),
+        )
+        if row:
+            return dict(row)
+        return None
+
+
+async def create_conversation(
+    user_id: str, conv_type: str = "standard", title: str | None = None
+) -> str:
+    """Create a new conversation and return its UUID."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "INSERT INTO conversations (user_id, type, title) VALUES ($1, $2, $3) RETURNING id",
+            uuid.UUID(user_id),
+            conv_type,
+            title,
+        )
+        return str(row["id"])
+
+
+async def append_message(
+    conversation_id: str,
+    reasoning_mode: str,
+    user_content: str,
+    assistant_content: str,
+    confidence: float | None = None,
+    consistency: float | None = None,
+    pdfs: list[str] | None = None,
+    pre_thinking: dict | None = None,
+    tools: list[str] | None = None,
+) -> str:
+    """
+    Append a user+assistant pair as a new row in the messages table.
+    Each row represents one full query+response turn.
+    Returns the new message row UUID.
+    """
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        new_entry = {"user": user_content, "assistant": assistant_content}
+        if pdfs:
+            new_entry["pdfs"] = pdfs
+        if tools:
+            new_entry["tools"] = tools
+        row = await conn.fetchrow(
+            "INSERT INTO messages (conversation_id, reasoning_mode, message, confidence, consistency, pre_thinking) VALUES ($1, $2, $3, $4, $5, $6) RETURNING id",
+            uuid.UUID(conversation_id),
+            reasoning_mode,
+            _json.dumps([new_entry]),
+            confidence,
+            consistency,
+            _json.dumps(pre_thinking) if pre_thinking else None,
+        )
+        return str(row["id"])
+
+
+async def create_debate_session(
+    user_id: str,
+    conversation_id: str,
+    topic: str,
+    debate_messages: list[dict],
+    verdict_text: str | None = None,
+) -> str:
+    """Persist a debate session and return its UUID."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "INSERT INTO debate_sessions (user_id, conversation_id, topic, debate_messages, verdict_text) VALUES ($1, $2, $3, $4, $5) RETURNING id",
+            uuid.UUID(user_id),
+            uuid.UUID(conversation_id),
+            topic,
+            _json.dumps(debate_messages),
+            verdict_text,
+        )
+        return str(row["id"])
+
+
+async def get_debate_session_by_conversation_id(conversation_id: str, user_id: str) -> dict | None:
+    """Fetch a debate session by its conversation UUID for the authenticated user."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            SELECT id, user_id, conversation_id, topic, debate_messages, verdict_text, created_at
+            FROM debate_sessions
+            WHERE conversation_id = $1 AND user_id = $2
+            """,
+            uuid.UUID(conversation_id),
+            uuid.UUID(user_id),
+        )
+        if not row:
+            return None
+
+        data = dict(row)
+        if isinstance(data.get("debate_messages"), str):
+            data["debate_messages"] = _json.loads(data["debate_messages"])
+        return data
+
+
+async def get_user_history(user_id: str) -> list[dict]:
+    """Get conversation metadata for a user, ordered by most recent."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT
+                c.id AS conv_id,
+                c.type AS conv_type,
+                c.title,
+                c.created_at AS conv_created,
+                c.updated_at AS conv_updated
+            FROM conversations c
+            WHERE c.user_id = $1
+            ORDER BY c.updated_at DESC
+            """,
+            uuid.UUID(user_id),
+        )
+
+        return [
+            {
+                "id": str(row["conv_id"]),
+                "type": row["conv_type"],
+                "title": row["title"],
+                "created_at": row["conv_created"].isoformat()
+                if row["conv_created"]
+                else None,
+                "updated_at": row["conv_updated"].isoformat()
+                if row["conv_updated"]
+                else None,
+                "messages": [],
+            }
+            for row in rows
+        ]
+
+
+async def update_conversation_timestamp(conversation_id: str):
+    """Update the updated_at timestamp for a conversation."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        await conn.execute(
+            "UPDATE conversations SET updated_at = NOW() WHERE id = $1",
+            uuid.UUID(conversation_id),
+        )
+
+
+async def rename_conversation(
+    conversation_id: str, user_id: str, new_title: str
+) -> bool:
+    """Rename a conversation title. Returns True if updated."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "UPDATE conversations SET title = $1, updated_at = NOW() WHERE id = $2 AND user_id = $3",
+            new_title,
+            uuid.UUID(conversation_id),
+            uuid.UUID(user_id),
+        )
+        return result == "UPDATE 1"
+
+
+async def delete_conversation(conversation_id: str, user_id: str) -> bool:
+    """Delete a conversation and all its messages. Returns True if deleted."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "DELETE FROM conversations WHERE id = $1 AND user_id = $2",
+            uuid.UUID(conversation_id),
+            uuid.UUID(user_id),
+        )
+        return result == "DELETE 1"
+
+
+async def clear_all_history(user_id: str) -> int:
+    """Delete all conversations for a user. Returns count deleted."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        result = await conn.execute(
+            "DELETE FROM conversations WHERE user_id = $1",
+            uuid.UUID(user_id),
+        )
+        return int(result.split()[-1]) if result.startswith("DELETE") else 0
+
+
+async def log_chunk_retrieval(
+    message_id: str | None,
+    qdrant_chunk_id: str,
+    pdf_id: str,
+    similarity_score: float,
+    quality_score: float | None = None,
+) -> str:
+    """Log a chunk retrieval for analytics."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "INSERT INTO chunk_retrieval_log (message_id, qdrant_chunk_id, pdf_id, similarity_score, quality_score) VALUES ($1, $2, $3, $4, $5) RETURNING id",
+            uuid.UUID(message_id) if message_id else None,
+            qdrant_chunk_id,
+            pdf_id,
+            similarity_score,
+            quality_score,
+        )
+        return str(row["id"])
+
+
+async def get_pdf_quality_scores(pdf_ids: list[str]) -> dict[str, float]:
+    """Get the average similarity score for a list of pdf_ids from chunk_retrieval_log."""
+    if not pdf_ids:
+        return {}
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            "SELECT pdf_id, AVG(similarity_score) as avg_score FROM chunk_retrieval_log WHERE pdf_id = ANY($1::text[]) GROUP BY pdf_id",
+            pdf_ids,
+        )
+        return {row["pdf_id"]: float(row["avg_score"]) for row in rows}
+
+
+async def get_conversation_with_messages(conversation_id: str, user_id: str) -> dict:
+    """Get a specific conversation and all its messages. Raises ValueError if not found."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        conv = await conn.fetchrow(
+            "SELECT id, type, title FROM conversations WHERE id = $1 AND user_id = $2",
+            uuid.UUID(conversation_id),
+            uuid.UUID(user_id),
+        )
+        if not conv:
+            raise ValueError("Conversation not found")
+
+        msgs = await conn.fetch(
+            "SELECT id, reasoning_mode, message, confidence, consistency, pre_thinking, created_at FROM messages WHERE conversation_id = $1 ORDER BY created_at ASC",
+            uuid.UUID(conversation_id),
+        )
+
+        messages = []
+        for m in msgs:
+            content = m["message"]
+            if isinstance(content, str):
+                content = _json.loads(content)
+            pre_thinking = m.get("pre_thinking")
+            if pre_thinking and not isinstance(pre_thinking, dict):
+                pre_thinking = _json.loads(pre_thinking) if pre_thinking else None
+            messages.append(
+                {
+                    "id": str(m["id"]),
+                    "reasoning_mode": m["reasoning_mode"],
+                    "content": content,
+                    "confidence": float(m["confidence"]) if m["confidence"] else None,
+                    "consistency": float(m["consistency"])
+                    if m["consistency"]
+                    else None,
+                    "pre_thinking": pre_thinking,
+                    "created_at": m["created_at"].isoformat()
+                    if m["created_at"]
+                    else None,
+                }
+            )
+
+        return {
+            "conversation": {
+                "id": str(conv["id"]),
+                "type": conv["type"],
+                "title": conv["title"],
+            },
+            "messages": messages,
+        }
+
+
+async def log_detected_mistakes(
+    message_id: str, user_id: str, mistakes: list[dict]
+) -> None:
+    """Log serious mistakes to the detected_mistakes table."""
+    if not mistakes:
+        return
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        values = []
+        for m in mistakes:
+            sev = str(m.get("severity", "medium")).lower()
+            if sev not in ("low", "medium", "high"):
+                sev = "medium"
+            desc = str(m.get("description", ""))
+            if desc:
+                values.append((uuid.UUID(message_id), uuid.UUID(user_id), desc, sev))
+
+        if values:
+            await conn.executemany(
+                "INSERT INTO detected_mistakes (message_id, user_id, description, severity) VALUES ($1, $2, $3, $4)",
+                values,
+            )

repositories/qdrant_repo.py

@@ -0,0 +1,333 @@
+import os
+import time
+import uuid
+from typing import List
+
+from dotenv import load_dotenv
+from qdrant_client import QdrantClient
+from qdrant_client.models import (
+    Distance,
+    FieldCondition,
+    Filter,
+    MatchValue,
+    PayloadSchemaType,
+    PointStruct,
+    VectorParams,
+)
+from sentence_transformers import SentenceTransformer
+
+load_dotenv()
+
+# ─── Embedding Model (cached) ─────────────────────────────────────────────────
+
+_embedding_model: SentenceTransformer | None = None
+
+
+def get_embedding_model() -> SentenceTransformer:
+    """Get cached SentenceTransformer model."""
+    global _embedding_model
+    if _embedding_model is None:
+        _embedding_model = SentenceTransformer("BAAI/bge-small-en-v1.5")
+    return _embedding_model
+
+
+def get_embedding(text: str) -> list[float]:
+    """Generate a 384-dim embedding for the given text."""
+    model = get_embedding_model()
+    embedding = model.encode(text, normalize_embeddings=True)
+    return embedding.tolist()
+
+
+# ─── Qdrant Client ────────────────────────────────────────────────────────────
+
+_qdrant_client: QdrantClient | None = None
+
+
+def get_qdrant_client() -> QdrantClient:
+    """Get the global Qdrant client singleton."""
+    global _qdrant_client
+    if _qdrant_client is None:
+        _qdrant_client = QdrantClient(
+            url=os.getenv("QDRANT_CLIENT"),
+            api_key=os.getenv("QDRANT_API_KEY"),
+        )
+    return _qdrant_client
+
+
+def init_qdrant_collections():
+    """Create pdf_summary and pdf_chunks collections if they don't exist."""
+    client = get_qdrant_client()
+    collections = [c.name for c in client.get_collections().collections]
+
+    if "pdf_summary" not in collections:
+        client.create_collection(
+            collection_name="pdf_summary",
+            vectors_config=VectorParams(size=384, distance=Distance.COSINE),
+        )
+        print("[qdrant] Created 'pdf_summary' collection.")
+
+    try:
+        client.create_payload_index(
+            collection_name="pdf_summary",
+            field_name="user_id",
+            field_schema=PayloadSchemaType.KEYWORD,
+        )
+        print("[qdrant] Created 'user_id' index on 'pdf_summary'.")
+    except Exception:
+        pass
+
+    if "pdf_chunks" not in collections:
+        client.create_collection(
+            collection_name="pdf_chunks",
+            vectors_config=VectorParams(size=384, distance=Distance.COSINE),
+        )
+        print("[qdrant] Created 'pdf_chunks' collection.")
+
+    try:
+        client.create_payload_index(
+            collection_name="pdf_chunks",
+            field_name="user_id",
+            field_schema=PayloadSchemaType.KEYWORD,
+        )
+        print("[qdrant] Created 'user_id' index on 'pdf_chunks'.")
+    except Exception:
+        pass
+
+    # pdf_id index is required for filtering chunks by a specific PDF
+    try:
+        client.create_payload_index(
+            collection_name="pdf_chunks",
+            field_name="pdf_id",
+            field_schema=PayloadSchemaType.KEYWORD,
+        )
+        print("[qdrant] Created 'pdf_id' index on 'pdf_chunks'.")
+    except Exception:
+        pass
+
+
+# ─── PDF Summary CRUD ─────────────────────────────────────────────────────────
+
+def upsert_pdf_summary(
+    pdf_id: str,
+    user_id: str,
+    conversation_id: str | None,
+    doc_name: str,
+    doc_summary: str,
+    topic_tags: list[str],
+) -> str:
+    """Store a PDF summary in the pdf_summary collection. Returns the point ID."""
+    client = get_qdrant_client()
+    embedding = get_embedding(doc_summary)
+
+    point_id = str(uuid.uuid4())
+    payload = {
+        "pdf_id": pdf_id,
+        "user_id": user_id,
+        "conversation_id": conversation_id,
+        "doc_name": doc_name,
+        "doc_summary": doc_summary,
+        "topic_tags": topic_tags,
+        "created_at": time.time(),  # Unix timestamp — used to find the most recently uploaded PDF
+    }
+
+    client.upsert(
+        collection_name="pdf_summary",
+        points=[PointStruct(id=point_id, vector=embedding, payload=payload)],
+    )
+    return point_id
+
+
+def get_user_pdf_summaries(user_id: str) -> list[dict]:
+    """Get all PDF summaries for a given user."""
+    client = get_qdrant_client()
+
+    results = client.scroll(
+        collection_name="pdf_summary",
+        scroll_filter=Filter(
+            must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+        ),
+        limit=100,
+    )
+
+    summaries = []
+    for point in results[0]:
+        summaries.append({
+            "id": str(point.id),
+            "pdf_id": point.payload.get("pdf_id"),
+            "doc_name": point.payload.get("doc_name"),
+            "doc_summary": point.payload.get("doc_summary"),
+            "topic_tags": point.payload.get("topic_tags", []),
+            "user_id": point.payload.get("user_id"),
+            "conversation_id": point.payload.get("conversation_id"),
+        })
+    return summaries
+
+
+# ─── PDF Chunks CRUD ──────────────────────────────────────────────────────────
+
+def upsert_pdf_chunks(
+    pdf_id: str,
+    user_id: str,
+    doc_name: str,
+    chunks: list[dict],
+) -> int:
+    """
+    Store PDF chunks in the pdf_chunks collection.
+    Each chunk dict should have: page_number, chunk_index, text_content.
+    Returns the number of chunks stored.
+    """
+    client = get_qdrant_client()
+
+    points = []
+    for chunk in chunks:
+        embedding = get_embedding(chunk["text_content"])
+        point_id = str(uuid.uuid4())
+        payload = {
+            "pdf_id": pdf_id,
+            "user_id": user_id,
+            "doc_name": doc_name,
+            "page_number": chunk.get("page_number", 0),
+            "chunk_index": chunk.get("chunk_index", 0),
+            "text_content": chunk["text_content"],
+        }
+        points.append(PointStruct(id=point_id, vector=embedding, payload=payload))
+
+    batch_size = 100
+    for i in range(0, len(points), batch_size):
+        batch = points[i : i + batch_size]
+        client.upsert(collection_name="pdf_chunks", points=batch)
+
+    return len(points)
+
+
+def search_chunks(query: str, user_id: str, top_k: int = 3) -> list[dict]:
+    """Search for relevant chunks filtered by user_id."""
+    client = get_qdrant_client()
+    embedding = get_embedding(query)
+
+    results = client.query_points(
+        collection_name="pdf_chunks",
+        query=embedding,
+        query_filter=Filter(
+            must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+        ),
+        limit=top_k,
+        with_payload=True,
+    )
+
+    chunks = []
+    for hit in results.points:
+        chunks.append({
+            "id": str(hit.id),
+            "text_content": hit.payload.get("text_content", ""),
+            "pdf_id": hit.payload.get("pdf_id"),
+            "doc_name": hit.payload.get("doc_name"),
+            "page_number": hit.payload.get("page_number"),
+            "similarity_score": hit.score,
+        })
+    return chunks
+
+
+def search_pdf_summary(query: str, user_id: str, top_k: int = 3) -> list[dict]:
+    """Search pdf_summary collection by query similarity for a given user.
+    Returns list of {pdf_id, doc_name, doc_summary, similarity_score}.
+    """
+    client = get_qdrant_client()
+    embedding = get_embedding(query)
+
+    results = client.query_points(
+        collection_name="pdf_summary",
+        query=embedding,
+        query_filter=Filter(
+            must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+        ),
+        limit=top_k,
+        with_payload=True,
+    )
+
+    summaries = []
+    for hit in results.points:
+        summaries.append({
+            "id": str(hit.id),
+            "pdf_id": hit.payload.get("pdf_id"),
+            "doc_name": hit.payload.get("doc_name"),
+            "doc_summary": hit.payload.get("doc_summary"),
+            "topic_tags": hit.payload.get("topic_tags", []),
+            "similarity_score": hit.score,
+        })
+    return summaries
+
+
+def search_chunks_by_pdf_id(query: str, user_id: str, pdf_id: str, top_k: int = 5) -> list[dict]:
+    """Search pdf_chunks filtered by a specific pdf_id. Returns the most relevant chunks."""
+    client = get_qdrant_client()
+    embedding = get_embedding(query)
+
+    results = client.query_points(
+        collection_name="pdf_chunks",
+        query=embedding,
+        query_filter=Filter(
+            must=[
+                FieldCondition(key="user_id", match=MatchValue(value=user_id)),
+                FieldCondition(key="pdf_id", match=MatchValue(value=pdf_id)),
+            ]
+        ),
+        limit=top_k,
+        with_payload=True,
+    )
+
+    chunks = []
+    for hit in results.points:
+        chunks.append({
+            "id": str(hit.id),
+            "text_content": hit.payload.get("text_content", ""),
+            "pdf_id": hit.payload.get("pdf_id"),
+            "doc_name": hit.payload.get("doc_name"),
+            "page_number": hit.payload.get("page_number"),
+            "similarity_score": hit.score,
+        })
+    return chunks
+
+
+def get_pdf_ids_by_names(doc_names: list[str], user_id: str) -> dict[str, str]:
+    """Look up pdf_ids by doc_name for a given user. Returns {doc_name: pdf_id}."""
+    client = get_qdrant_client()
+    result: dict[str, str] = {}
+
+    hits, _ = client.scroll(
+        collection_name="pdf_summary",
+        scroll_filter=Filter(
+            must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+        ),
+        limit=200,
+        with_payload=True,
+    )
+    for point in hits:
+        name = point.payload.get("doc_name", "")
+        if name in doc_names:
+            result[name] = point.payload.get("pdf_id", "")
+
+    return result
+
+
+def get_most_recent_pdf_id(user_id: str) -> str | None:
+    """Return the pdf_id of the most recently uploaded PDF for a given user.
+    Uses the created_at timestamp stored in the pdf_summary payload.
+    Falls back gracefully for older entries that lack the timestamp.
+    """
+    client = get_qdrant_client()
+
+    hits, _ = client.scroll(
+        collection_name="pdf_summary",
+        scroll_filter=Filter(
+            must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+        ),
+        limit=200,
+        with_payload=True,
+    )
+    if not hits:
+        return None
+
+    # Sort descending by created_at; entries without the field get 0 (treated as oldest)
+    sorted_hits = sorted(hits, key=lambda p: p.payload.get("created_at", 0), reverse=True)
+    return sorted_hits[0].payload.get("pdf_id")

requirements.txt

@@ -0,0 +1,21 @@
+fastapi
+uvicorn
+asyncpg
+python-jose[cryptography]
+bcrypt
+python-multipart
+qdrant-client
+pymupdf
+langchain-textsplitters
+langchain-core
+langchain-groq
+langchain-openai
+groq
+python-dotenv
+autogen-agentchat~=0.4.0.dev10
+autogen-ext[openai]~=0.4.0.dev10
+httpx
+sentence-transformers
+langgraph
+# Install CPU-only torch to keep the image size manageable
+torch --index-url https://download.pytorch.org/whl/cpu

routers/__init__.py

@@ -0,0 +1,8 @@
+# Routers module — re-exports all API routers
+from routers.auth_router import router as auth_router
+from routers.chat_router import router as chat_router
+from routers.history_router import router as history_router
+from routers.pdf_router import router as pdf_router
+from routers.debate_router import router as debate_router
+from routers.admin_router import router as admin_router
+from routers.reflection_router import router as reflection_router

routers/admin_router.py

@@ -0,0 +1,181 @@
+from fastapi import APIRouter, HTTPException, Query
+from repositories import get_pool
+
+router = APIRouter(prefix="/admin", tags=["admin"])
+
+
+@router.get("/tables")
+async def list_tables():
+    """List all tables and their row counts."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        tables = [
+            "users",
+            "conversations",
+            "messages",
+            "debate_sessions",
+            "detected_mistakes",
+            "chunk_retrieval_log",
+        ]
+        result = {}
+        for table in tables:
+            count = await conn.fetchval(f"SELECT COUNT(*) FROM {table}")
+            result[table] = count
+        return {"tables": result}
+
+
+@router.get("/users")
+async def view_users(limit: int = Query(50, le=200), offset: int = Query(0, ge=0)):
+    """View all users (passwords masked)."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            "SELECT id, email, '***' as password_hash, display_name, created_at, updated_at FROM users ORDER BY created_at DESC LIMIT $1 OFFSET $2",
+            limit, offset,
+        )
+        total = await conn.fetchval("SELECT COUNT(*) FROM users")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/conversations")
+async def view_conversations(limit: int = Query(50, le=200), offset: int = Query(0, ge=0)):
+    """View all conversations."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """SELECT c.id, c.user_id, u.email as user_email, c.type, c.title, c.created_at, c.updated_at
+               FROM conversations c LEFT JOIN users u ON c.user_id = u.id
+               ORDER BY c.updated_at DESC LIMIT $1 OFFSET $2""",
+            limit, offset,
+        )
+        total = await conn.fetchval("SELECT COUNT(*) FROM conversations")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/messages")
+async def view_messages(
+    conversation_id: str | None = Query(None),
+    limit: int = Query(50, le=200),
+    offset: int = Query(0, ge=0),
+):
+    """View messages, optionally filtered by conversation_id."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        if conversation_id:
+            rows = await conn.fetch(
+                """SELECT m.id, m.conversation_id, m.reasoning_mode, m.message, m.confidence, m.consistency, m.pre_thinking, m.created_at
+                   FROM messages m WHERE m.conversation_id = $1
+                   ORDER BY m.created_at ASC LIMIT $2 OFFSET $3""",
+                conversation_id, limit, offset,
+            )
+            total = await conn.fetchval("SELECT COUNT(*) FROM messages WHERE conversation_id = $1", conversation_id)
+        else:
+            rows = await conn.fetch(
+                """SELECT m.id, m.conversation_id, m.reasoning_mode, m.message, m.confidence, m.consistency, m.pre_thinking, m.created_at
+                   FROM messages m ORDER BY m.created_at DESC LIMIT $1 OFFSET $2""",
+                limit, offset,
+            )
+            total = await conn.fetchval("SELECT COUNT(*) FROM messages")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/messages/{message_id}")
+async def view_message_detail(message_id: str):
+    """View full details of a single message including JSONB content."""
+    import json as _json
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "SELECT * FROM messages WHERE id = $1", message_id,
+        )
+        if not row:
+            raise HTTPException(status_code=404, detail="Message not found")
+        data = dict(row)
+        # Parse JSONB message content
+        if isinstance(data.get("message"), str):
+            data["message"] = _json.loads(data["message"])
+        return data
+
+
+@router.get("/debate-sessions")
+async def view_debate_sessions(limit: int = Query(50, le=200), offset: int = Query(0, ge=0)):
+    """View all debate sessions."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """SELECT d.id, d.user_id, u.email as user_email, d.conversation_id, d.topic,
+                      LENGTH(d.debate_messages::text) as messages_size,
+                      LENGTH(d.verdict_text) as verdict_size, d.created_at
+               FROM debate_sessions d LEFT JOIN users u ON d.user_id = u.id
+               ORDER BY d.created_at DESC LIMIT $1 OFFSET $2""",
+            limit, offset,
+        )
+        total = await conn.fetchval("SELECT COUNT(*) FROM debate_sessions")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/debate-sessions/{session_id}")
+async def view_debate_session_detail(session_id: str):
+    """View full details of a single debate session."""
+    import json as _json
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow("SELECT * FROM debate_sessions WHERE id = $1", session_id)
+        if not row:
+            raise HTTPException(status_code=404, detail="Debate session not found")
+        data = dict(row)
+        if isinstance(data.get("debate_messages"), str):
+            data["debate_messages"] = _json.loads(data["debate_messages"])
+        return data
+
+
+@router.get("/mistakes")
+async def view_mistakes(limit: int = Query(50, le=200), offset: int = Query(0, ge=0)):
+    """View all detected mistakes."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """SELECT dm.id, dm.message_id, dm.user_id, u.email as user_email,
+                      dm.description, dm.severity, dm.created_at
+               FROM detected_mistakes dm LEFT JOIN users u ON dm.user_id = u.id
+               ORDER BY dm.created_at DESC LIMIT $1 OFFSET $2""",
+            limit, offset,
+        )
+        total = await conn.fetchval("SELECT COUNT(*) FROM detected_mistakes")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/chunk-logs")
+async def view_chunk_logs(limit: int = Query(50, le=200), offset: int = Query(0, ge=0)):
+    """View chunk retrieval logs."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """SELECT id, message_id, qdrant_chunk_id, pdf_id, similarity_score, quality_score, created_at
+               FROM chunk_retrieval_log ORDER BY created_at DESC LIMIT $1 OFFSET $2""",
+            limit, offset,
+        )
+        total = await conn.fetchval("SELECT COUNT(*) FROM chunk_retrieval_log")
+        return {"total": total, "offset": offset, "limit": limit, "data": [dict(r) for r in rows]}
+
+
+@router.get("/stats")
+async def view_stats():
+    """Get database statistics."""
+    pool = await get_pool()
+    async with pool.acquire() as conn:
+        stats = {}
+        stats["users"] = await conn.fetchval("SELECT COUNT(*) FROM users")
+        stats["conversations"] = await conn.fetchval("SELECT COUNT(*) FROM conversations")
+        stats["conversations_standard"] = await conn.fetchval("SELECT COUNT(*) FROM conversations WHERE type = 'standard'")
+        stats["conversations_debate"] = await conn.fetchval("SELECT COUNT(*) FROM conversations WHERE type = 'debate'")
+        stats["messages"] = await conn.fetchval("SELECT COUNT(*) FROM messages")
+        stats["debate_sessions"] = await conn.fetchval("SELECT COUNT(*) FROM debate_sessions")
+        stats["detected_mistakes"] = await conn.fetchval("SELECT COUNT(*) FROM detected_mistakes")
+        stats["chunk_retrieval_logs"] = await conn.fetchval("SELECT COUNT(*) FROM chunk_retrieval_log")
+
+        # Recent activity
+        recent_conv = await conn.fetchrow("SELECT created_at FROM conversations ORDER BY created_at DESC LIMIT 1")
+        stats["last_conversation_at"] = str(recent_conv["created_at"]) if recent_conv else None
+
+        return stats

routers/auth_router.py

@@ -0,0 +1,53 @@
+from fastapi import APIRouter, HTTPException
+from core import hash_password, verify_password, create_token
+from repositories import create_user, get_user_by_email
+from schemas import RegisterRequest, LoginRequest
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/register")
+async def register(req: RegisterRequest):
+    """Register a new user and return a JWT token."""
+    try:
+        existing = await get_user_by_email(req.email)
+        if existing:
+            raise HTTPException(status_code=400, detail="Email already registered")
+
+        password_hash = hash_password(req.password)
+        user_id = await create_user(req.email, password_hash, req.display_name)
+        token = create_token(user_id)
+
+        return {
+            "token": token,
+            "user_id": user_id,
+            "display_name": req.display_name,
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/login")
+async def login(req: LoginRequest):
+    """Login with email and password, return a JWT token."""
+    try:
+        user = await get_user_by_email(req.email)
+        if not user:
+            raise HTTPException(status_code=401, detail="Invalid email or password")
+
+        if not verify_password(req.password, user["password_hash"]):
+            raise HTTPException(status_code=401, detail="Invalid email or password")
+
+        token = create_token(str(user["id"]))
+
+        return {
+            "token": token,
+            "user_id": str(user["id"]),
+            "display_name": user.get("display_name"),
+        }
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

routers/chat_router.py

@@ -0,0 +1,550 @@
+import json
+import logging
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
+from core import get_current_user
+
+from schemas import (
+    QueryRequest,
+    TaskRequest,
+    SmartOrchestratorRequest
+)
+
+from services import (
+    run_tool_agent_stream_sse,
+    smart_orchestrator_stream,
+    get_conversation_memory_context_async,
+    run_deep_research_stream_with_state,
+    _to_non_empty_text,
+    add_to_memory
+)
+
+from repositories import (
+    create_conversation,
+    append_message,
+    update_conversation_timestamp,
+    log_chunk_retrieval,
+    log_detected_mistakes,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["chat"])
+
+
+@router.post("/chat/stream")
+async def agent_query_stream(
+    req: QueryRequest, user_id: str = Depends(get_current_user)
+):
+    """
+    Standard chat endpoint with SSE streaming (3-phase: initial → tools → final).
+
+    Flow:
+      1. Load memory context (if conversation_id provided)
+      2. Stream tool agent execution via SSE
+      3. Persist message + chunk logs after streaming completes
+    """
+    logger.info(
+        f"[chat_router:stream] Request from user={user_id}, conv_id={req.conversation_id}"
+    )
+
+    # ── Fetch prior conversation memory ─
+    memory_context: str | None = None
+    if req.conversation_id:
+        logger.info(
+            f"[chat_router:stream] Fetching memory for conv_id={req.conversation_id}"
+        )
+        memory_context = await get_conversation_memory_context_async(
+            req.conversation_id, user_id
+        )
+        if memory_context:
+            logger.info(
+                f"[chat_router:stream] Memory context ready: {len(memory_context)} chars"
+            )
+        else:
+            logger.info(
+                f"[chat_router:stream] No prior memory found for conv_id={req.conversation_id}"
+            )
+
+    async def event_generator():
+        final_answer = ""
+        retrieved_chunks = []
+
+        try:
+            # Stream the tool agent execution
+            async for sse_line in run_tool_agent_stream_sse(
+                query=req.query,
+                user_id=user_id,
+                pdfs=req.pdfs,
+                memory_context=memory_context,
+            ):
+                # Parse to capture final data for DB persistence
+                try:
+                    if sse_line.startswith("data: "):
+                        evt = json.loads(sse_line[6:].strip())
+                        if evt.get("type") == "done":
+                            final_answer = evt.get("answer", "")
+                            tools_used = evt.get("tools_used", [])
+                            retrieved_chunks = evt.get("retrieved_chunks", [])
+                        elif evt.get("type") == "error":
+                            logger.error(
+                                f"[chat_router:stream] Stream error: {evt.get('message')}"
+                            )
+                except (json.JSONDecodeError, IndexError):
+                    pass
+                yield sse_line
+
+        except Exception as e:
+            logger.error(f"[chat_router:stream] Streaming error: {e}", exc_info=True)
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+
+        # ── Persist to DB after streaming ─
+        try:
+            conv_id = req.conversation_id
+            if not conv_id:
+                conv_id = await create_conversation(
+                    user_id, "standard", req.query[:200]
+                )
+                logger.info(f"[chat_router:stream] Created new conversation: {conv_id}")
+
+            message_id = await append_message(
+                conversation_id=conv_id,
+                reasoning_mode="standard",
+                user_content=req.query,
+                assistant_content=final_answer,
+                pdfs=req.pdfs,
+            )
+            await update_conversation_timestamp(conv_id)
+            logger.info(
+                f"[chat_router:stream] Persisted message {message_id} to conv {conv_id}"
+            )
+
+            # Log retrieved chunks
+            for chunk in retrieved_chunks:
+                try:
+                    await log_chunk_retrieval(
+                        message_id=message_id,
+                        qdrant_chunk_id=chunk.get("id", ""),
+                        pdf_id=chunk.get("pdf_id", ""),
+                        similarity_score=chunk.get("similarity_score", 0.0),
+                        quality_score=None,
+                    )
+                except Exception as log_err:
+                    logger.warning(
+                        f"[chat_router:stream] Chunk log failed for {chunk.get('id')}: {log_err}"
+                    )
+
+            # Emit conversation_id to frontend
+            yield f"data: {json.dumps({'type': 'conversation_id', 'conversation_id': conv_id})}\n\n"
+
+            # ── Update window memory ─────────────────────────────
+            if conv_id:
+                add_to_memory(conv_id, req.query, final_answer)
+
+        except Exception as db_err:
+            logger.error(
+                f"[chat_router:stream] DB persist error: {db_err}", exc_info=True
+            )
+
+        yield 'data: {"type": "done"}\n\n'
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+@router.post("/deep_research/task")
+async def deep_research_task(req: TaskRequest, user_id: str = Depends(get_current_user)):
+    """Run the multi-agent orchestrator (deep research) with SSE streaming."""
+
+    async def event_generator():
+        final_result = ""
+        final_meta = {}
+        conv_id = req.conversation_id
+        pre_thinking = {"decomposition": "", "researcher1": "", "researcher2": ""}
+        aggregation_content = ""
+
+        try:
+            # Load memory context
+            memory_context: str | None = None
+            if req.conversation_id:
+                memory_context = await get_conversation_memory_context_async(req.conversation_id, user_id)
+
+            # Stream orchestrator events
+            async for event in run_deep_research_stream_with_state(req.task, memory_context=memory_context):
+                event_type = event.get("type", "")
+
+                # Forward all events to frontend
+                yield f"data: {json.dumps(event)}\n\n"
+
+                # Capture final result for DB persistence
+                if event_type == "final":
+                    final_result = event.get("result", "")
+                    final_meta = event.get("meta", {})
+                elif event_type == "content_chunk":
+                    section = event.get("section", "")
+                    content = event.get("content", "")
+                    if section == "decomposition":
+                        pre_thinking["decomposition"] = content
+                    elif section == "researcher_1":
+                        pre_thinking["researcher1"] = content
+                    elif section == "researcher_2":
+                        pre_thinking["researcher2"] = content
+                    elif section == "aggregation":
+                        aggregation_content = content
+
+        except Exception as e:
+            logger.error(f"[deep_research_router] Streaming error: {e}", exc_info=True)
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+
+        # Persist to DB after streaming completes
+        try:
+            if not conv_id:
+                conv_id = await create_conversation(user_id, "standard", req.task[:200])
+
+            raw_conf = final_meta.get("confidence_score")
+            raw_cons = final_meta.get("logical_consistency")
+            deep_research_raw = final_meta.get("deep_research_raw", {})
+
+            assistant_content_to_store = (
+                _to_non_empty_text(final_result)
+                or (
+                    _to_non_empty_text(deep_research_raw.get("final_result", ""))
+                    if isinstance(deep_research_raw, dict)
+                    else ""
+                )
+                or _to_non_empty_text(aggregation_content)
+                or "Deep research completed."
+            )
+
+            # Only save pre_thinking if we have decomposition content
+            pre_thinking_data = (
+                pre_thinking if pre_thinking.get("decomposition") else None
+            )
+
+            await append_message(
+                conversation_id=conv_id,
+                reasoning_mode="deep_research",
+                user_content=req.task,
+                assistant_content=assistant_content_to_store,
+                confidence=raw_conf / 100 if raw_conf is not None else None,
+                consistency=raw_cons / 100 if raw_cons is not None else None,
+                pre_thinking=pre_thinking_data,
+                tools=["Researcher_Agent1", "Researcher_Agent2", "Aggregator_Agent"],
+            )
+            await update_conversation_timestamp(conv_id)
+
+            # Emit conversation_id to frontend
+            yield f"data: {json.dumps({'type': 'conversation_id', 'conversation_id': conv_id})}\n\n"
+
+            # Update window memory
+            if conv_id:
+                add_to_memory(conv_id, req.task, assistant_content_to_store)
+
+        except Exception as db_err:
+            logger.error(f"[deep_research_router] DB persist error: {db_err}", exc_info=True)
+
+        yield 'data: {"type": "done"}\n\n'
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )
+
+
+@router.post("/smart-orchestrator/stream")
+async def smart_orchestrator_endpoint(
+    req: SmartOrchestratorRequest, user_id: str = Depends(get_current_user)
+):
+    """Smart orchestrator SSE stream (routes to standard/deep_research/code)."""
+    final_result = ""
+    meta_info = {}
+    detected_path = "standard"
+    pre_thinking = {"decomposition": "", "researcher1": "", "researcher2": ""}
+    deep_research_aggregation = ""
+    code_pre_thinking = {
+        "problem_understanding": "",
+        "approach": "",
+        "agent_outputs": [],
+        "file_outputs": [],
+    }
+    code_final_marker = None
+
+    def _to_non_empty_text(value) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, str):
+            return value.strip()
+        if isinstance(value, (dict, list)):
+            try:
+                return json.dumps(value, ensure_ascii=False).strip()
+            except Exception:
+                return str(value).strip()
+        return str(value).strip()
+
+    def _extract_code_complete_marker(value):
+        parsed_result = None
+        if isinstance(value, str) and value.strip():
+            try:
+                parsed_result = json.loads(value)
+            except json.JSONDecodeError:
+                parsed_result = None
+        elif isinstance(value, dict):
+            parsed_result = value
+
+        if isinstance(parsed_result, dict) and parsed_result.get("type") == "code_complete":
+            return parsed_result
+        return None
+
+    def _build_code_approach_from_subtasks(subtasks) -> str:
+        if not isinstance(subtasks, list):
+            return ""
+        lines = []
+        for subtask in subtasks:
+            if not isinstance(subtask, dict):
+                continue
+            desc = str(subtask.get("description", "")).strip()
+            if not desc:
+                continue
+            subtask_id = subtask.get("id")
+            if subtask_id is not None:
+                lines.append(f"- Agent {subtask_id}: {desc}")
+            else:
+                lines.append(f"- {desc}")
+        if not lines:
+            return ""
+        return "Parallel implementation plan:\n" + "\n".join(lines)
+
+    def _build_code_assistant_content(
+        problem_understanding: str,
+        approach: str,
+        final_marker: dict | None,
+    ) -> str:
+        sections = []
+        if problem_understanding:
+            sections.append(f"Problem Understanding:\n{problem_understanding}")
+        if approach:
+            sections.append(f"Approach:\n{approach}")
+        summary = "\n\n".join(sections).strip()
+        if summary:
+            return summary
+
+        if isinstance(final_marker, dict):
+            file_count = final_marker.get("file_count")
+            filenames = final_marker.get("filenames", [])
+            if isinstance(file_count, int):
+                if isinstance(filenames, list) and filenames:
+                    return (
+                        f"Code generation completed with {file_count} file(s): "
+                        + ", ".join(str(name) for name in filenames)
+                    )
+                return f"Code generation completed with {file_count} file(s)."
+        return ""
+
+    async def event_generator():
+        nonlocal final_result, meta_info, detected_path, pre_thinking, deep_research_aggregation, code_pre_thinking, code_final_marker
+        try:
+            async for chunk in smart_orchestrator_stream(
+                req.task,
+                conversation_id=req.conversation_id,
+                user_id=user_id,
+            ):
+                try:
+                    if chunk.startswith("data: "):
+                        evt = json.loads(chunk[6:].strip())
+                        evt_type = evt.get("type")
+                        if evt_type == "final":
+                            final_result = evt.get("result", "")
+                            meta_info = evt.get("meta", {})
+                            if detected_path == "code":
+                                parsed_result = _extract_code_complete_marker(final_result)
+                                if isinstance(parsed_result, dict):
+                                    code_final_marker = parsed_result
+                        elif evt_type == "route":
+                            detected_path = evt.get("path", "standard")
+                        elif evt_type == "content_chunk":
+                            section = evt.get("section", "")
+                            content = evt.get("content", "")
+                            if section == "decomposition":
+                                pre_thinking["decomposition"] = content
+                            elif section == "researcher_1":
+                                pre_thinking["researcher1"] = content
+                            elif section == "researcher_2":
+                                pre_thinking["researcher2"] = content
+                            elif section == "aggregation":
+                                deep_research_aggregation = content
+                        elif evt_type == "code_section":
+                            section = evt.get("section", "")
+                            content = evt.get("content", "")
+                            if section == "problem_understanding":
+                                code_pre_thinking["problem_understanding"] = content
+                            elif section == "approach":
+                                code_pre_thinking["approach"] = content
+                        elif evt_type == "plan" and detected_path == "code":
+                            if not code_pre_thinking.get("approach"):
+                                generated_approach = _build_code_approach_from_subtasks(
+                                    evt.get("subtasks", [])
+                                )
+                                if generated_approach:
+                                    code_pre_thinking["approach"] = generated_approach
+                        elif evt_type == "agent_output" and detected_path == "code":
+                            code_pre_thinking["agent_outputs"].append(
+                                {
+                                    "agent_id": evt.get("agent_id"),
+                                    "agent_name": evt.get("agent_name"),
+                                    "content": evt.get("content", ""),
+                                }
+                            )
+                        elif evt_type == "file_output" and detected_path == "code":
+                            code_pre_thinking["file_outputs"].append(
+                                {
+                                    "filename": evt.get("filename", ""),
+                                    "language": evt.get("language", "text"),
+                                    "index": evt.get("index"),
+                                    "total": evt.get("total"),
+                                    "content": evt.get("content", ""),
+                                }
+                            )
+                except (json.JSONDecodeError, IndexError):
+                    pass
+                yield chunk
+        except Exception as e:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+        finally:
+            try:
+                reasoning = (
+                    "multi_agent"
+                    if detected_path in ("deep_research", "code")
+                    else "multi_agent"
+                )
+
+                conv_id = req.conversation_id
+                if not conv_id:
+                    conv_id = await create_conversation(
+                        user_id, "standard", req.task[:200]
+                    )
+
+                raw_conf = meta_info.get("confidence_score")
+                raw_cons = meta_info.get("logical_consistency")
+                serious_mistakes = meta_info.get("serious_mistakes", [])
+                orchestrator_raw = meta_info.get("orchestrator_raw", {})
+                orchestrator_raw_result = (
+                    _to_non_empty_text(orchestrator_raw.get("final_result", ""))
+                    if isinstance(orchestrator_raw, dict)
+                    else ""
+                )
+                path_specific_final_result = _to_non_empty_text(final_result)
+                deep_research_chunk_content = _to_non_empty_text(deep_research_aggregation)
+                code_summary_content = ""
+                pre_thinking_data = None
+
+                if detected_path == "deep_research":
+                    pre_thinking_data = (
+                        pre_thinking if pre_thinking.get("decomposition") else None
+                    )
+                elif detected_path == "code":
+                    parsed_result = _extract_code_complete_marker(final_result)
+                    if code_final_marker is None and isinstance(parsed_result, dict):
+                        code_final_marker = parsed_result
+                    if isinstance(parsed_result, dict):
+                        path_specific_final_result = ""
+
+                    problem_understanding = str(
+                        code_pre_thinking.get("problem_understanding", "")
+                    ).strip()
+                    approach = str(code_pre_thinking.get("approach", "")).strip()
+                    agent_outputs = code_pre_thinking.get("agent_outputs", [])
+                    file_outputs = code_pre_thinking.get("file_outputs", [])
+
+                    code_summary_content = _build_code_assistant_content(
+                        problem_understanding,
+                        approach,
+                        code_final_marker
+                        if isinstance(code_final_marker, dict)
+                        else None,
+                    )
+
+                    pre_thinking_data = {
+                        "route_path": detected_path,
+                        "agent_outputs": agent_outputs,
+                        "file_outputs": file_outputs,
+                    }
+                    if isinstance(code_final_marker, dict):
+                        pre_thinking_data["final_marker"] = code_final_marker
+
+                    if not (
+                        pre_thinking_data["agent_outputs"]
+                        or pre_thinking_data["file_outputs"]
+                        or pre_thinking_data.get("final_marker")
+                    ):
+                        pre_thinking_data = None
+
+                # Build tools list based on detected path
+                tools = None
+                if detected_path == "deep_research":
+                    tools = ["Researcher_Agent1", "Researcher_Agent2", "Aggregator_Agent"]
+                elif detected_path == "code":
+                    tools = ["Code_Planner", "Coder_1", "Coder_2", "Coder_3", "Aggregator", "Reviewer"]
+                else:
+                    # Standard mode - use tools from meta
+                    tools = meta_info.get("tools_used", [])
+                    if tools:
+                        tools = [t if isinstance(t, str) else t.get("tool", str(t)) for t in tools]
+
+                explicit_fallback_text = (
+                    "Deep research completed."
+                    if detected_path == "deep_research"
+                    else "Code generation completed."
+                    if detected_path == "code"
+                    else "Request completed."
+                )
+
+                assistant_content_to_store = (
+                    path_specific_final_result
+                    or orchestrator_raw_result
+                    or deep_research_chunk_content
+                    or code_summary_content
+                    or explicit_fallback_text
+                )
+
+                message_id = await append_message(
+                    conversation_id=conv_id,
+                    reasoning_mode=reasoning,
+                    user_content=req.task,
+                    assistant_content=assistant_content_to_store,
+                    confidence=raw_conf / 100 if raw_conf is not None else None,
+                    consistency=raw_cons / 100 if raw_cons is not None else None,
+                    pdfs=req.pdfs,
+                    pre_thinking=pre_thinking_data,
+                    tools=tools,
+                )
+                await update_conversation_timestamp(conv_id)
+
+                if serious_mistakes:
+                    try:
+                        await log_detected_mistakes(
+                            message_id, user_id, serious_mistakes
+                        )
+                    except Exception as log_err:
+                        print(f"[chat_router] Mistake log error: {log_err}")
+
+                # Emit the final conversation_id to the frontend
+                yield f"data: {json.dumps({'type': 'conversation_id', 'conversation_id': conv_id})}\n\n"
+                
+                # ── Update window memory ─────────────────────────────
+                if conv_id:
+                    add_to_memory(conv_id, req.task, assistant_content_to_store)
+                    
+            except Exception as db_err:
+                print(f"[chat_router] DB persist error: {db_err}")
+
+            yield 'data: {"type": "done"}\n\n'
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+    )

routers/debate_router.py

@@ -0,0 +1,74 @@
+import json
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
+from core import get_current_user
+
+from services import (
+    run_debate_stream,
+    structure_debate_rounds
+)
+from repositories import (
+    create_conversation,
+    create_debate_session,
+    get_debate_session_by_conversation_id,
+    update_conversation_timestamp
+)
+
+router = APIRouter(tags=["debate"])
+
+
+@router.get("/debate/stream")
+async def debate_stream(
+    topic: str,
+    rounds: int = 3,
+    mode: str = "autogen",
+    user_id: str = Depends(get_current_user)
+):
+    """Stream a debate between two agents via SSE."""
+    debate_events = []
+
+    async def event_generator():
+        nonlocal debate_events
+        try:
+            async for msg in run_debate_stream(topic, rounds, mode):
+                debate_events.append(msg)
+                yield f"data: {json.dumps(msg)}\n\n"
+
+            # Persist debate session after all rounds complete
+            conv_id = await create_conversation(user_id, "debate", topic[:200])
+            
+            structured_rounds = structure_debate_rounds(debate_events)
+
+            verdict_text = None
+            for msg in debate_events:
+                if msg.get("type") == "verdict":
+                    verdict_text = msg.get("content", "")
+
+            await create_debate_session(
+                user_id=user_id,
+                conversation_id=conv_id,
+                topic=topic,
+                debate_messages=structured_rounds,
+                verdict_text=verdict_text,
+            )
+            await update_conversation_timestamp(conv_id)
+            
+            # Emit conversation_id for this debate session
+            yield f"data: {json.dumps({'type': 'conversation_id', 'conversation_id': conv_id})}\n\n"
+        except ValueError as ve:
+            yield f"data: {json.dumps({'type': 'error', 'message': str(ve)})}\n\n"
+        except Exception as db_err:
+            print(f"[debate_router] DB persist error: {db_err}")
+
+        yield "data: {\"type\": \"done\"}\n\n"
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@router.get("/debate/session/{conversation_id}")
+async def get_debate_session(conversation_id: str, user_id: str = Depends(get_current_user)):
+    """Return a saved debate session for history replay."""
+    session = await get_debate_session_by_conversation_id(conversation_id, user_id)
+    if not session:
+        return {"session": None}
+    return {"session": session}

routers/history_router.py

@@ -0,0 +1,90 @@
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel
+from core import get_current_user
+from repositories import (
+    get_user_history,
+    rename_conversation,
+    delete_conversation,
+    clear_all_history,
+    get_conversation_with_messages,
+)
+from services import (
+    clear_conversation_memory,
+    get_all_conversations
+)
+
+from schemas import (
+    RenameRequest
+)
+
+router = APIRouter(tags=["history"])
+
+
+@router.get("/history")
+async def get_history(user_id: str = Depends(get_current_user)):
+    """Get all conversations with messages for the authenticated user."""
+    try:
+        history = await get_user_history(user_id)
+        return {"conversations": history}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.put("/history/{conversation_id}")
+async def rename_conv(
+    conversation_id: str, req: RenameRequest, user_id: str = Depends(get_current_user)
+):
+    """Rename a conversation title."""
+    try:
+        ok = await rename_conversation(conversation_id, user_id, req.title)
+        if not ok:
+            raise HTTPException(status_code=404, detail="Conversation not found")
+        return {"status": "ok"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/history/{conversation_id}")
+async def delete_conv(conversation_id: str, user_id: str = Depends(get_current_user)):
+    """Delete a conversation and all its messages."""
+    try:
+        ok = await delete_conversation(conversation_id, user_id)
+        if not ok:
+            raise HTTPException(status_code=404, detail="Conversation not found")
+        # Clear from window memory
+        clear_conversation_memory(conversation_id)
+        return {"status": "ok"}
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/history")
+async def clear_history(user_id: str = Depends(get_current_user)):
+    """Clear all conversation history for the user."""
+    try:
+        count = await clear_all_history(user_id)
+        # Clear all window memories for this user (clear all since all convs deleted)
+        all_convs = get_all_conversations()
+        for conv_id in all_convs:
+            clear_conversation_memory(conv_id)
+        return {"status": "ok", "deleted": count}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/history/{conversation_id}")
+async def get_conversation_messages(
+    conversation_id: str, user_id: str = Depends(get_current_user)
+):
+    """Get all messages for a specific conversation."""
+    try:
+        result = await get_conversation_with_messages(conversation_id, user_id)
+        return result
+    except ValueError:
+        raise HTTPException(status_code=404, detail="Conversation not found")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

routers/pdf_router.py

@@ -0,0 +1,86 @@
+import os
+import shutil
+import tempfile
+from fastapi import APIRouter, UploadFile, File, Depends
+from core import get_current_user
+from utils.pdf_processor import process_pdfs
+from repositories import (
+    create_conversation,
+    update_conversation_timestamp,
+    get_user_pdf_summaries,
+    get_pdf_quality_scores
+)
+
+router = APIRouter(tags=["pdf"])
+
+
+@router.post("/upload-pdf")
+async def upload_pdfs(
+    files: list[UploadFile] = File(...),
+    conversation_id: str | None = None,
+    user_id: str = Depends(get_current_user),
+):
+    """
+    Accepts multiple PDF files, saves them temporarily,
+    processes them through pdf_processor, and stores in Qdrant.
+    """
+    temp_dir = tempfile.mkdtemp()
+    file_paths = []
+
+    try:
+        for file in files:
+            if not file.filename:
+                continue
+            temp_path = os.path.join(temp_dir, file.filename)
+            with open(temp_path, "wb") as buffer:
+                content = await file.read()
+                buffer.write(content)
+            file_paths.append(temp_path)
+
+        conv_id = conversation_id
+        if not conv_id:
+            conv_id = await create_conversation(user_id, "standard", f"PDF Upload: {len(files)} file(s)")
+        
+        results = await process_pdfs(file_paths, user_id, conversation_id=conv_id)
+        await update_conversation_timestamp(conv_id)
+
+        return {
+            "status": "success",
+            "processed": results.get("total_chunks", 0),
+            "details": results,
+            "conversation_id": conv_id,
+        }
+    except Exception as e:
+        print(f"[pdf_router] PDF processing error: {e}")
+        return {
+            "status": "partial",
+            "processed": 0,
+            "details": {"error": str(e), "note": "Qdrant may be unavailable. PDFs processed but not stored."},
+        }
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+@router.get("/memory/pdfs")
+async def get_memory_pdfs(user_id: str = Depends(get_current_user)):
+    """Get all PDF summaries for the authenticated user."""
+    try:
+        summaries = get_user_pdf_summaries(user_id)
+        
+        if summaries:
+            pdf_ids = [s.get("pdf_id") for s in summaries if s.get("pdf_id")]
+            if pdf_ids:
+                scores = await get_pdf_quality_scores(pdf_ids)
+                for s in summaries:
+                    pid = s.get("pdf_id")
+                    if pid and pid in scores:
+                        # Normalize to a percentage if it's cosine similarity (-1 to 1 or 0 to 1)
+                        # We'll just pass it as is or multiply by 100 on the frontend, let's keep it 0-100 format if it was 0-1
+                        # If average similarity is 0.85, maybe we want it as 85.
+                        avg = scores[pid]
+                        s["quality_score"] = int(avg * 100) if 0 <= avg <= 1 else int(avg)
+
+        return {"pdfs": summaries}
+    except Exception as e:
+        print(f"[pdf_router] Qdrant unavailable, returning empty list: {e}")
+        return {"pdfs": []}

routers/reflection_router.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from core import get_current_user
+from repositories import get_pool
+
+router = APIRouter(prefix="/reflection", tags=["reflection"])
+
+
+def _clamp_score(value: float, minimum: int = 0, maximum: int = 100) -> int:
+    return max(minimum, min(maximum, round(value)))
+
+
+def _normalize_to_percent(value: float | None) -> float | None:
+    if value is None:
+        return None
+    return value * 100 if value <= 1 else value
+
+
+def _default_improvement(severity: str) -> str:
+    if severity == "high":
+        return "Escalated to stricter validation and cross-checking gates."
+    if severity == "medium":
+        return "Added additional reasoning checks before final response."
+    return "Applied lightweight post-response self-review for similar prompts."
+
+
+def _default_strategy(severity: str) -> str:
+    if severity == "high":
+        return "Require tool-backed evidence and second-pass verification for claims."
+    if severity == "medium":
+        return "Increase consistency checks on multi-step reasoning chains."
+    return "Track pattern frequency and auto-flag repeated low-severity slips."
+
+
+def _build_radar(
+    confidence_score: int,
+    logical_consistency: int,
+    factual_reliability: int,
+    self_correction_triggered: bool,
+    issue_count: int,
+    high_severity_count: int,
+) -> list[dict]:
+    adaptation = _clamp_score(
+        72
+        + (14 if self_correction_triggered else 4)
+        - (high_severity_count * 4)
+        - min(issue_count, 6)
+    )
+    return [
+        {"metric": "Planning", "value": logical_consistency},
+        {"metric": "Reasoning", "value": confidence_score},
+        {"metric": "Verification", "value": factual_reliability},
+        {"metric": "Adaptation", "value": adaptation},
+        {"metric": "Confidence", "value": confidence_score},
+    ]
+
+
+@router.get("")
+@router.get("/summary")
+async def get_reflection_summary(user_id: str = Depends(get_current_user)):
+    """
+    User-scoped reflection summary:
+    - confidence / logical consistency from messages table (all user conversations)
+    - reflection report issues from detected_mistakes
+    """
+    try:
+        pool = await get_pool()
+        async with pool.acquire() as conn:
+            quality_row = await conn.fetchrow(
+                """
+                SELECT
+                    AVG(m.confidence) AS avg_confidence,
+                    AVG(m.consistency) AS avg_consistency,
+                    COUNT(m.id) AS message_count
+                FROM messages m
+                JOIN conversations c ON c.id = m.conversation_id
+                WHERE c.user_id = $1
+                """,
+                uuid.UUID(user_id),
+            )
+
+            mistakes = await conn.fetch(
+                """
+                SELECT id, description, severity
+                FROM detected_mistakes
+                WHERE user_id = $1
+                ORDER BY created_at DESC
+                LIMIT 200
+                """,
+                uuid.UUID(user_id),
+            )
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc))
+
+    avg_confidence = _normalize_to_percent(
+        float(quality_row["avg_confidence"])
+        if quality_row and quality_row["avg_confidence"] is not None
+        else None
+    )
+    avg_consistency = _normalize_to_percent(
+        float(quality_row["avg_consistency"])
+        if quality_row and quality_row["avg_consistency"] is not None
+        else None
+    )
+
+    confidence_score = _clamp_score(avg_confidence if avg_confidence is not None else 82)
+    logical_consistency = _clamp_score(avg_consistency if avg_consistency is not None else 84)
+
+    severity_count = {"high": 0, "medium": 0, "low": 0}
+    issues = []
+    for idx, row in enumerate(mistakes):
+        severity = str(row["severity"] or "medium").lower()
+        if severity not in severity_count:
+            severity = "medium"
+        severity_count[severity] += 1
+        issues.append(
+            {
+                "id": str(row["id"]),
+                "issue": row["description"] or "Detected reasoning issue.",
+                "improvement": _default_improvement(severity),
+                "strategy": _default_strategy(severity),
+                "severity": severity,
+            }
+        )
+
+    message_count = int(quality_row["message_count"]) if quality_row and quality_row["message_count"] else 0
+    issue_penalty = (
+        severity_count["high"] * 12
+        + severity_count["medium"] * 7
+        + severity_count["low"] * 4
+    )
+    density_penalty = (
+        min(15, round((len(issues) / message_count) * 30)) if message_count > 0 else 0
+    )
+    factual_reliability = _clamp_score(92 - issue_penalty - density_penalty, 35, 98)
+    self_correction_triggered = len(issues) > 0
+
+    return {
+        "scores": {
+            "confidenceScore": confidence_score,
+            "logicalConsistency": logical_consistency,
+            "factualReliability": factual_reliability,
+            "selfCorrectionTriggered": self_correction_triggered,
+        },
+        "radarData": _build_radar(
+            confidence_score=confidence_score,
+            logical_consistency=logical_consistency,
+            factual_reliability=factual_reliability,
+            self_correction_triggered=self_correction_triggered,
+            issue_count=len(issues),
+            high_severity_count=severity_count["high"],
+        ),
+        "issues": issues,
+    }

schemas/__init__.py

@@ -0,0 +1,13 @@
+from schemas.schema import (
+    RegisterRequest,
+    LoginRequest,
+    QueryRequest,
+    TaskRequest,
+    SmartOrchestratorRequest,
+    AgentState,
+    OrchestratorState,
+    CodeModeState,
+    CodingSubtask,
+    CodingAgentState,
+    RenameRequest
+)

schemas/schema.py

@@ -0,0 +1,86 @@
+import operator
+from pydantic import BaseModel
+from langchain_core.messages import BaseMessage
+from typing import TypedDict, Annotated, Sequence, List, Optional
+
+class RegisterRequest(BaseModel):
+    email: str
+    password: str
+    display_name: str | None = None
+
+
+class LoginRequest(BaseModel):
+    email: str
+    password: str
+
+class QueryRequest(BaseModel):
+    query: str
+    conversation_id: str | None = None
+    pdfs: list[str] | None = None
+
+class DebateRequest(BaseModel):
+    topic: str
+    rounds: int = 3
+
+class TaskRequest(BaseModel):
+    task: str
+    conversation_id: str | None = None
+
+class SmartOrchestratorRequest(BaseModel):
+    task: str
+    conversation_id: str | None = None
+    pdfs: list[str] | None = None
+
+class AgentState(TypedDict):
+    messages: Annotated[Sequence[BaseMessage], operator.add]
+
+class RenameRequest(BaseModel):
+    title: str
+
+class OrchestratorState(TypedDict):
+    original_task: str
+    subtasks: List[dict]          # [{id, description, agent_type, result}]
+    current_subtask_index: int
+    final_result: str
+    step_logs: List[str]
+    critic_confidence: int
+    critic_logical_consistency: int
+    critic_feedback: str
+    serious_mistakes: List[dict]
+
+class CodeModeState(TypedDict):
+    original_task: str
+    plan: str
+    code_results: List[dict]  # [{agent_id, code}]
+    final_code: str
+    review_feedback: str
+    confidence_score: int
+    consistency_score: int
+    step_logs: List[str]
+    serious_mistakes: List[dict]
+    graph_nodes: List[dict]
+    graph_edges: List[dict]
+
+
+class CodingSubtask(TypedDict):
+    id: int
+    description: str
+    signatures: List[str]
+    result: Optional[str]
+
+
+class CodingAgentState(TypedDict):
+    original_task: str
+    subtasks: List[CodingSubtask]
+    shared_contract: str
+    coder_results: List[str]
+    merged_code: str
+    review_errors: List[str]
+    retry_count: int
+    confidence_score: int
+    logical_consistency: int
+    critic_feedback: str
+    final_output: str
+    parsed_files: List[dict]   # [{"filename": str, "content": str, "language": str}]
+    step_logs: List[str]
+

services/__init__.py

@@ -0,0 +1,41 @@
+# Services module — re-exports service-level orchestration functions
+from services.agent_service import (
+    run_tool_agent,
+    run_tool_agent_stream_sse
+)
+from services.deep_research_service import (
+    run_deep_research,
+    run_deep_research_stream_with_state,
+    _to_non_empty_text
+)
+from services.debate_service import (
+    run_debate_stream,
+    run_debate_stream_raw,
+    run_debate_stream_autogen,
+    structure_debate_rounds
+)
+from services.smart_orchestrator_service import (
+    smart_orchestrator_stream
+)
+from services.rag_service import (
+    run_smart_chat
+)
+from services.memory_service import (
+    get_conversation_memory_context,
+    get_conversation_memory_context_async,
+    add_to_memory,
+    clear_conversation_memory,
+    get_all_conversations
+)
+from services.context_injector import (
+    inject_memory_context,
+    has_memory_context,
+    log_context_injection
+)
+from services.base_stream_service import (
+    format_sse_event,
+    yield_sse_events,
+    yield_sse_with_error_handling,
+    create_sse_event
+)
+

services/agent_service.py

@@ -0,0 +1,234 @@
+import json
+import logging
+from typing import AsyncGenerator
+import utils.tools as _tools_module
+from agents import get_tool_agent_graph, run_tool_agent_stream
+from schemas.schema import AgentState
+from langchain_core.messages import HumanMessage, AIMessage
+from services.memory_service import format_memory_block
+
+logger = logging.getLogger(__name__)
+
+# ─── System instructions for tool agent ──────────
+_SYSTEM_PROMPT = """
+You have access to the following tools:
+- knowledge_retriever: Use this tool to answer questions about uploaded PDF documents. Call it when user asks about document content.
+- calculator: Use for mathematical calculations.
+- get_current_datetime: Use when user asks about current time or date.
+
+Instructions:
+- Only call tools when necessary
+- If you know the answer, respond directly without calling tools
+- Do not guess or make up information
+- When calling knowledge_retriever, include relevant search query
+"""
+
+
+async def run_tool_agent(
+    query: str,
+    user_id: str = "default_user",
+    pdfs: list[str] | None = None,
+    memory_context: str | None = None,
+) -> dict:
+    """
+    Run the tool-calling agent and return answer + tool usage info.
+
+    Returns a dict with:
+        answer          : str
+        tools_used      : list[dict]
+        message_count   : int
+        retrieved_chunks: list[dict]  ← all chunks buffered during this call,
+                                        to be logged by the caller after append_message
+                                        returns the real message_id.
+    """
+    # ── Set per-request context; clear chunk buffer from any previous request ─
+    _tools_module.CURRENT_USER_ID = user_id
+    _tools_module.RETRIEVED_CHUNKS_BUFFER.clear()
+
+    # ── Build the message content (inject prior history if available) ─────────
+    if memory_context:
+        logger.info(
+            f"[agent_service] Injecting memory context ({len(memory_context)} chars) into tool agent prompt."
+        )
+        message_content = format_memory_block(memory_context) + query + _SYSTEM_PROMPT
+    else:
+        logger.info(
+            "[agent_service] No memory context — running tool agent without history."
+        )
+        message_content = query + _SYSTEM_PROMPT
+
+    try:
+        graph = get_tool_agent_graph()
+        initial_state: AgentState = {
+            "messages": [HumanMessage(content=message_content)]
+        }
+        result = graph.invoke(initial_state)
+        messages = result["messages"]
+
+        tools_used = []
+        final_answer = ""
+
+        for msg in messages:
+            if hasattr(msg, "tool_calls") and msg.tool_calls:
+                for tc in msg.tool_calls:
+                    tools_used.append({"tool": tc["name"], "args": tc["args"]})
+            if (
+                isinstance(msg, AIMessage)
+                and msg.content
+                and not (hasattr(msg, "tool_calls") and msg.tool_calls)
+            ):
+                final_answer = msg.content
+
+        # Snapshot the buffer — caller uses this after append_message to log with correct message_id
+        retrieved_chunks = list(_tools_module.RETRIEVED_CHUNKS_BUFFER)
+
+        return {
+            "answer": final_answer,
+            "tools_used": tools_used,
+            "message_count": len(messages),
+            "retrieved_chunks": retrieved_chunks,
+        }
+    except Exception as e:
+        logger.error(f"[agent_service] Error: {e}", exc_info=True)
+        raise
+    finally:
+        # Always clean up — prevents chunks from leaking into the next request
+        _tools_module.CURRENT_USER_ID = "default_user"
+        _tools_module.RETRIEVED_CHUNKS_BUFFER.clear()
+
+
+async def run_tool_agent_stream_sse(
+    query: str,
+    user_id: str = "default_user",
+    pdfs: list[str] | None = None,
+    memory_context: str | None = None,
+) -> AsyncGenerator[str, None]:
+    """
+    Run the tool-calling agent with SSE streaming (3-phase: initial → tools → final).
+
+    Tokens are batched (~50ms windows) to reduce SSE event overhead
+    and produce smooth, low-latency streaming on the frontend.
+
+    Yields SSE-formatted event strings:
+        data: {"type": "token", "content": "...", "phase": "initial"|"final"}
+        data: {"type": "tool_start", "tool_name": "...", "tool_args": {...}}
+        data: {"type": "tool_end", "tool_name": "...", "tool_output": "..."}
+        data: {"type": "done", "answer": "...", "tools_used": [...], "retrieved_chunks": [...]}
+    """
+    # ── Set per-request context; clear chunk buffer ─
+    _tools_module.CURRENT_USER_ID = user_id
+    _tools_module.RETRIEVED_CHUNKS_BUFFER.clear()
+
+    # ── Build message content ─
+    if memory_context:
+        logger.info(
+            f"[agent_service:stream] Injecting memory context ({len(memory_context)} chars)"
+        )
+        message_content = format_memory_block(memory_context) + query + _SYSTEM_PROMPT
+    else:
+        logger.info("[agent_service:stream] No memory context — fresh run")
+        message_content = query + _SYSTEM_PROMPT
+
+    messages = [HumanMessage(content=message_content)]
+    final_answer = ""
+    tools_used = []
+    retrieved_chunks = []
+
+    def _sse(event: dict) -> str:
+        return f"data: {json.dumps(event)}\n\n"
+
+    # Token batching: accumulate tokens and flush periodically
+    token_buffer: dict[str, str] = {"initial": "", "final": ""}
+    last_flush = 0.0
+    FLUSH_INTERVAL = 0.025  # 25ms — smooth without overwhelming the network
+
+    import time
+
+    async def _flush_tokens(force: bool = False):
+        nonlocal last_flush
+        now = time.monotonic()
+        if not force and (now - last_flush) < FLUSH_INTERVAL:
+            return
+        for phase in ("initial", "final"):
+            if token_buffer[phase]:
+                yield _sse(
+                    {
+                        "type": "token",
+                        "content": token_buffer[phase],
+                        "phase": phase,
+                    }
+                )
+                token_buffer[phase] = ""
+        last_flush = now
+
+    try:
+        logger.info("[agent_service:stream] Starting 3-phase streaming execution...")
+
+        async for event in run_tool_agent_stream(messages):
+            evt_type = event.get("type")
+
+            if evt_type == "token":
+                # Accumulate into phase buffer instead of yielding immediately
+                phase = event.get("phase", "initial")
+                token_buffer[phase] += event["content"]
+                # Flush if buffer is getting large (>300 chars)
+                if len(token_buffer[phase]) > 300:
+                    async for sse_line in _flush_tokens(force=True):
+                        yield sse_line
+
+            elif evt_type == "tool_start":
+                # Flush any pending tokens before tool execution
+                async for sse_line in _flush_tokens(force=True):
+                    yield sse_line
+                logger.info(
+                    f"[agent_service:stream] Tool starting: {event['tool_name']}"
+                )
+                yield _sse(
+                    {
+                        "type": "tool_start",
+                        "tool_name": event["tool_name"],
+                        "tool_args": event["tool_args"],
+                    }
+                )
+
+            elif evt_type == "tool_end":
+                logger.info(
+                    f"[agent_service:stream] Tool completed: {event['tool_name']}"
+                )
+                yield _sse(
+                    {
+                        "type": "tool_end",
+                        "tool_name": event["tool_name"],
+                        "tool_output": event["tool_output"],
+                    }
+                )
+
+            elif evt_type == "complete":
+                # Flush remaining tokens
+                async for sse_line in _flush_tokens(force=True):
+                    yield sse_line
+                final_answer = event["answer"]
+                tools_used = event["tools_used"]
+                retrieved_chunks = list(_tools_module.RETRIEVED_CHUNKS_BUFFER)
+
+                logger.info(
+                    f"[agent_service:stream] Complete. Answer: {len(final_answer)} chars, "
+                    f"Tools: {len(tools_used)}, Chunks: {len(retrieved_chunks)}"
+                )
+
+                yield _sse(
+                    {
+                        "type": "done",
+                        "answer": final_answer,
+                        "tools_used": tools_used,
+                        "retrieved_chunks": retrieved_chunks,
+                    }
+                )
+
+    except Exception as e:
+        logger.error(f"[agent_service:stream] Error: {e}", exc_info=True)
+        yield _sse({"type": "error", "message": str(e)})
+        raise
+    finally:
+        _tools_module.CURRENT_USER_ID = "default_user"
+        _tools_module.RETRIEVED_CHUNKS_BUFFER.clear()

services/base_stream_service.py

@@ -0,0 +1,111 @@
+"""
+Base streaming service with shared SSE (Server-Sent Events) utilities.
+
+Provides consistent patterns for:
+- SSE event formatting
+- Event yielding and streaming
+- Error handling in streams
+- Event queue management
+
+Single source of truth for server-sent event generation across all services.
+"""
+
+import json
+from typing import Any, AsyncGenerator, Callable
+
+
+def format_sse_event(data: dict[str, Any]) -> str:
+    """
+    Format a dict as SSE (Server-Sent Events) message.
+    
+    Args:
+        data: Dict to serialize as JSON event
+        
+    Returns:
+        SSE-formatted string: "data: {json}\n\n"
+        
+    Example:
+        event = {"type": "token", "content": "hello"}
+        sse_message = format_sse_event(event)
+        # Returns: 'data: {"type": "token", "content": "hello"}\n\n'
+    """
+    return f"data: {json.dumps(data)}\n\n"
+
+
+async def yield_sse_events(
+    event_source: AsyncGenerator[dict[str, Any], None],
+) -> AsyncGenerator[str, None]:
+    """
+    Convert dict events to SSE format.
+    
+    Args:
+        event_source: Async generator yielding event dicts
+        
+    Yields:
+        SSE-formatted event strings
+        
+    Example:
+        async def my_events():
+            yield {"type": "start"}
+            yield {"type": "token", "content": "hello"}
+            yield {"type": "done"}
+        
+        async for sse_msg in yield_sse_events(my_events()):
+            await send(sse_msg)
+    """
+    try:
+        async for event in event_source:
+            yield format_sse_event(event)
+    except Exception as exc:
+        yield format_sse_event({
+            "type": "error",
+            "message": str(exc),
+        })
+
+
+async def yield_sse_with_error_handling(
+    event_source: AsyncGenerator[dict[str, Any], None],
+    error_logger: Callable[[str], None] | None = None,
+) -> AsyncGenerator[str, None]:
+    """
+    Convert dict events to SSE format with error handling and logging.
+    
+    Args:
+        event_source: Async generator yielding event dicts
+        error_logger: Optional callback to log errors
+        
+    Yields:
+        SSE-formatted event strings
+    """
+    try:
+        async for event in event_source:
+            yield format_sse_event(event)
+    except Exception as exc:
+        error_msg = str(exc)
+        if error_logger:
+            error_logger(f"SSE stream error: {error_msg}")
+        yield format_sse_event({
+            "type": "error",
+            "message": error_msg,
+        })
+
+
+def create_sse_event(
+    event_type: str,
+    **kwargs: Any,
+) -> dict[str, Any]:
+    """
+    Create a properly-structured SSE event dict.
+    
+    Args:
+        event_type: Type of event (e.g., "token", "done", "error")
+        **kwargs: Additional fields to include
+        
+    Returns:
+        Dict ready to be formatted as SSE
+        
+    Example:
+        event = create_sse_event("token", content="hello", phase="initial")
+        sse_msg = format_sse_event(event)
+    """
+    return {"type": event_type, **kwargs}

services/context_injector.py

@@ -0,0 +1,94 @@
+"""
+Context injection utilities for memory and history management.
+
+Provides consistent patterns for:
+- Checking if memory/context is available
+- Logging context injection
+- Formatting and prepending context to tasks/prompts
+- Context size tracking for monitoring
+
+Single source of truth for memory injection patterns used across all services.
+"""
+
+import logging
+from services.memory_service import format_memory_block
+
+logger = logging.getLogger(__name__)
+
+
+def inject_memory_context(
+    primary_content: str,
+    memory_context: str | None = None,
+    service_name: str = "agent",
+    context_type: str = "memory",
+) -> str:
+    """
+    Inject memory/context into primary content with consistent logging.
+    
+    Args:
+        primary_content: Main content (task, query, prompt)
+        memory_context: Optional prior history/context to prepend
+        service_name: Name of calling service for logging (e.g., "agent_service", "orchestrator")
+        context_type: Type of context for logging clarity (e.g., "memory", "history", "prior_conversation")
+        
+    Returns:
+        Combined content with memory prepended if available, otherwise primary_content as-is
+        
+    Example:
+        effective_task = inject_memory_context(
+            primary_content=task,
+            memory_context=user_history,
+            service_name="coding_service",
+            context_type="conversation"
+        )
+    """
+    if memory_context:
+        logger.info(
+            f"[{service_name}] Injecting {context_type} context ({len(memory_context)} chars) into task."
+        )
+        return format_memory_block(memory_context) + primary_content
+    else:
+        logger.info(
+            f"[{service_name}] No {context_type} context available — proceeding without prior history."
+        )
+        return primary_content
+
+
+def has_memory_context(memory_context: str | None) -> bool:
+    """
+    Check if memory context is available (non-None and non-empty).
+    
+    Args:
+        memory_context: Potential context string
+        
+    Returns:
+        True if context exists and is non-empty, False otherwise
+    """
+    return bool(memory_context and memory_context.strip())
+
+
+def log_context_injection(
+    service_name: str,
+    context_size: int | None = None,
+    context_type: str = "memory",
+    action: str = "injecting",
+) -> None:
+    """
+    Log context injection with standardized format.
+    
+    Args:
+        service_name: Name of calling service
+        context_size: Optional size in bytes/chars for monitoring
+        context_type: Type of context (memory, history, etc.)
+        action: Action being taken (injecting, skipping, loading, etc.)
+        
+    Example:
+        log_context_injection("orchestrator_service", 245, "conversation", "injecting")
+        # Output: [orchestrator_service] Injecting 245 chars of conversation context
+    """
+    if context_size:
+        logger.info(
+            f"[{service_name}] {action.capitalize()} {context_size} chars of {context_type} context"
+        )
+    else:
+        logger.info(f"[{service_name}] {action.capitalize()} {context_type} context")

services/debate_service.py

@@ -0,0 +1,324 @@
+import asyncio
+import inspect
+from typing import Any, AsyncGenerator
+
+from autogen_core import CancellationToken
+from autogen_agentchat.messages import TextMessage
+
+from core import get_client
+from agents import (
+    create_critic_agent,
+    create_proposer_agent,
+    create_verifier_agent,
+    get_agent_a_persona,
+    get_agent_b_persona,
+    get_debate_model,
+)
+
+
+def _phase_for_round(round_num: int, total_rounds: int) -> str:
+    if round_num == 1:
+        return "opening statement"
+    if round_num == total_rounds:
+        return "closing rebuttal"
+    return "rebuttal round"
+
+
+def _format_transcript(rounds_data: dict[int, dict[str, str]]) -> str:
+    transcript_lines: list[str] = []
+    for rnd in sorted(rounds_data.keys()):
+        proposer = rounds_data[rnd].get("proposer", "").strip()
+        critic = rounds_data[rnd].get("critic", "").strip()
+        transcript_lines.append(f"Round {rnd} - FOR: {proposer}")
+        transcript_lines.append(f"Round {rnd} - AGAINST: {critic}")
+    return "\n".join(transcript_lines)
+
+
+def _content_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        chunks: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                chunks.append(item)
+            elif isinstance(item, dict):
+                text = item.get("text")
+                if isinstance(text, str):
+                    chunks.append(text)
+        return "\n".join(part for part in chunks if part.strip())
+    raise ValueError(f"Unsupported AutoGen message content type: {type(content)}")
+
+
+async def _agent_reply(agent: Any, prompt: str) -> str:
+    response = await agent.on_messages(
+        [TextMessage(content=prompt, source="user")],
+        cancellation_token=CancellationToken(),
+    )
+    chat_message = getattr(response, "chat_message", None)
+    if chat_message is None:
+        raise ValueError("AutoGen response did not include chat_message.")
+
+    text = _content_to_text(getattr(chat_message, "content", ""))
+    cleaned = text.strip()
+    if not cleaned:
+        raise ValueError("AutoGen response content is empty.")
+    return cleaned
+
+
+async def _close_agent_model_client(agent: Any) -> None:
+    model_client = getattr(agent, "model_client", None)
+    if model_client is None:
+        return
+
+    close_fn = getattr(model_client, "close", None)
+    if close_fn is None:
+        return
+
+    result = close_fn()
+    if inspect.isawaitable(result):
+        await result
+
+
+async def run_debate_stream_raw(topic: str, rounds: int = 3) -> AsyncGenerator[dict, None]:
+    """Stream a debate using raw Groq API (original implementation)."""
+    groq_client = get_client()
+    model = get_debate_model()
+    persona_a = get_agent_a_persona()
+    persona_b = get_agent_b_persona()
+
+    history_a = []
+    history_b = []
+
+    yield {"type": "info", "message": f"🎭 Debate started: '{topic}' | {rounds} rounds"}
+    await asyncio.sleep(0.2)
+
+    last_a_message = ""
+    last_b_message = ""
+
+    for round_num in range(1, rounds + 1):
+        yield {"type": "round", "round": round_num, "total_rounds": rounds}
+        await asyncio.sleep(0.1)
+
+        # Agent A (Proposer)
+        if round_num == 1:
+            user_msg_a = f'The debate topic is: "{topic}". You are arguing FOR this position. Give your opening statement.'
+        else:
+            user_msg_a = f'Agent Critic said: "{last_b_message}"\nContinue the debate. Counter their argument and strengthen your position. Round {round_num} of {rounds}.'
+
+        history_a.append({"role": "user", "content": user_msg_a})
+        response_a = groq_client.chat.completions.create(
+            model=model,
+            messages=[{"role": "system", "content": persona_a}] + history_a,
+            temperature=0.7,
+        )
+        msg_a = response_a.choices[0].message.content
+        history_a.append({"role": "assistant", "content": msg_a})
+        last_a_message = msg_a
+
+        yield {
+            "type": "message",
+            "agent": "Agent Proposer",
+            "agent_id": "A",
+            "position": "FOR",
+            "round": round_num,
+            "content": msg_a,
+        }
+        await asyncio.sleep(0.1)
+
+        # Agent B (Critic)
+        if round_num == 1:
+            user_msg_b = f'The debate topic is: "{topic}". You are arguing AGAINST this position. Give your opening statement.'
+        else:
+            user_msg_b = f'Agent Proposer said: "{last_a_message}"\nRespond to their argument and reinforce your position. Round {round_num} of {rounds}.'
+
+        history_b.append({"role": "user", "content": user_msg_b})
+        response_b = groq_client.chat.completions.create(
+            model=model,
+            messages=[{"role": "system", "content": persona_b}] + history_b,
+            temperature=0.7,
+        )
+        msg_b = response_b.choices[0].message.content
+        history_b.append({"role": "assistant", "content": msg_b})
+        last_b_message = msg_b
+
+        yield {
+            "type": "message",
+            "agent": "Agent Critic",
+            "agent_id": "B",
+            "position": "AGAINST",
+            "round": round_num,
+            "content": msg_b,
+        }
+        await asyncio.sleep(0.2)
+
+    # Verdict
+    yield {"type": "info", "message": "⚖️ Generating debate summary..."}
+    await asyncio.sleep(0.01)
+
+    all_debate = ""
+    for i, (ha, hb) in enumerate(zip(
+        [m for m in history_a if m["role"] == "assistant"],
+        [m for m in history_b if m["role"] == "assistant"],
+    )):
+        all_debate += f"\nRound {i+1} - FOR: {ha['content']}\nRound {i+1} - AGAINST: {hb['content']}\n"
+
+    verdict_response = groq_client.chat.completions.create(
+        model=model,
+        messages=[{
+            "role": "user",
+            "content": f"""Topic: "{topic}"
+
+Debate transcript:
+{all_debate}
+
+As an impartial judge, summarize the key arguments made by both sides and provide a balanced verdict on who made stronger arguments and why. Be concise (6-7 sentences)."""
+        }],
+        temperature=0.3,
+    )
+
+    verdict = verdict_response.choices[0].message.content
+
+    yield {
+        "type": "verdict",
+        "content": verdict,
+    }
+
+
+async def run_debate_stream_autogen(topic: str, rounds: int = 3) -> AsyncGenerator[dict, None]:
+    """Stream a debate between Agent Proposer and Agent Critic using AutoGen."""
+    proposer_agent = create_proposer_agent()
+    critic_agent = create_critic_agent()
+    verifier_agent = create_verifier_agent()
+
+    rounds_data: dict[int, dict[str, str]] = {}
+
+    yield {"type": "info", "message": f"🎭 Debate started: '{topic}' | {rounds} rounds"}
+    await asyncio.sleep(0.2)
+
+    try:
+        for round_num in range(1, rounds + 1):
+            phase = _phase_for_round(round_num, rounds)
+            yield {"type": "round", "round": round_num, "total_rounds": rounds}
+            await asyncio.sleep(0.1)
+
+            transcript = _format_transcript(rounds_data)
+            proposer_prompt = (
+                f"Debate topic: \"{topic}\"\n"
+                f"Current phase: {phase}\n"
+                "Role: You must argue FOR the topic.\n"
+                "Rules: Provide one clear claim, one support, and one direct rebuttal "
+                "to the strongest opposing point seen so far.\n"
+                f"Transcript so far:\n{transcript if transcript else 'No prior rounds.'}\n"
+                "Respond in 3-4 sentences."
+            )
+
+            proposer_msg = await _agent_reply(proposer_agent, proposer_prompt)
+            if round_num not in rounds_data:
+                rounds_data[round_num] = {"proposer": "", "critic": ""}
+            rounds_data[round_num]["proposer"] = proposer_msg
+
+            yield {
+                "type": "message",
+                "agent": "Agent Proposer",
+                "agent_id": "A",
+                "position": "FOR",
+                "round": round_num,
+                "content": proposer_msg,
+            }
+            await asyncio.sleep(0.4)
+
+            transcript = _format_transcript(rounds_data)
+            critic_prompt = (
+                f"Debate topic: \"{topic}\"\n"
+                f"Current phase: {phase}\n"
+                "Role: You must argue AGAINST the topic.\n"
+                "Rules: Address Proposer's latest claim directly, expose one weakness, "
+                "and present one counter-claim with support.\n"
+                f"Transcript so far:\n{transcript}\n"
+                "Respond in 3-4 sentences."
+            )
+
+            critic_msg = await _agent_reply(critic_agent, critic_prompt)
+            rounds_data[round_num]["critic"] = critic_msg
+
+            yield {
+                "type": "message",
+                "agent": "Agent Critic",
+                "agent_id": "B",
+                "position": "AGAINST",
+                "round": round_num,
+                "content": critic_msg,
+            }
+            await asyncio.sleep(0.2)
+
+        yield {"type": "info", "message": "⚖️ Generating debate summary..."}
+        await asyncio.sleep(0.01)
+
+        final_transcript = _format_transcript(rounds_data)
+        verdict_prompt = (
+            f"Topic: \"{topic}\"\n"
+            "You are the impartial verifier. Evaluate the debate below.\n"
+            "Scoring criteria: argument strength, evidence quality, and logical consistency.\n"
+            "Output requirements: 6-7 sentences, balanced summary, and explicit winner with reason.\n"
+            f"Debate transcript:\n{final_transcript}"
+        )
+        verdict = await _agent_reply(verifier_agent, verdict_prompt)
+
+        yield {
+            "type": "verdict",
+            "content": verdict,
+        }
+    finally:
+        await _close_agent_model_client(proposer_agent)
+        await _close_agent_model_client(critic_agent)
+        await _close_agent_model_client(verifier_agent)
+
+
+async def run_debate_stream(
+    topic: str,
+    rounds: int = 3,
+    mode: str = "autogen"
+) -> AsyncGenerator[dict, None]:
+    """
+    Route to appropriate debate implementation based on mode.
+
+    Args:
+        topic: Debate topic
+        rounds: Number of debate rounds
+        mode: "raw" for original Groq API, "autogen" for AutoGen orchestration
+
+    Yields:
+        SSE events (same format for both modes)
+
+    Raises:
+        ValueError: If mode is not "raw" or "autogen"
+    """
+    if mode.lower() not in ("raw", "autogen"):
+        raise ValueError(f"Invalid debate mode: {mode}. Must be 'raw' or 'autogen'.")
+
+    if mode.lower() == "raw":
+        async for event in run_debate_stream_raw(topic, rounds):
+            yield event
+    else:  # autogen
+        async for event in run_debate_stream_autogen(topic, rounds):
+            yield event
+
+
+
+def structure_debate_rounds(debate_events: list[dict]) -> list[dict]:
+    """
+    Convert raw debate events into structured rounds format:
+    [{"proposer": "...", "critic": "..."}, ...]
+    """
+    rounds_data: dict[int, dict] = {}
+    for evt in debate_events:
+        if evt.get("type") == "message":
+            rnd = evt.get("round", 0)
+            if rnd not in rounds_data:
+                rounds_data[rnd] = {"proposer": "", "critic": ""}
+            if evt.get("agent_id") == "A":
+                rounds_data[rnd]["proposer"] = evt.get("content", "")
+            elif evt.get("agent_id") == "B":
+                rounds_data[rnd]["critic"] = evt.get("content", "")
+    return [rounds_data[k] for k in sorted(rounds_data.keys())]

services/deep_research_service.py

@@ -0,0 +1,314 @@
+import json
+from typing import AsyncGenerator
+from agents import get_deep_research_graph
+from schemas.schema import OrchestratorState
+from services.memory_service import format_memory_block
+
+def _to_non_empty_text(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value.strip()
+    if isinstance(value, (dict, list)):
+        try:
+            return json.dumps(value, ensure_ascii=False).strip()
+        except Exception:
+            return str(value).strip()
+    return str(value).strip()
+
+async def run_deep_research(task: str, memory_context: str | None = None) -> dict:
+    """Run the deep_research pipeline: planner → parallel researchers → aggregator → critic.
+    
+    If memory_context is provided (prior conversation history), it is prepended to the
+    task so the deep_research planner has awareness of the ongoing thread.
+    """
+    try:
+        graph = get_deep_research_graph()
+
+        # Inject prior conversation context into the task
+        effective_task = task
+        if memory_context:
+            print(f"[deep_research_service] Injecting memory context ({len(memory_context)} chars) into deep_research task.")
+            effective_task = format_memory_block(memory_context) + task
+        else:
+            print("[deep_research_service] No memory context — running deep_research without history.")
+
+        initial_state: OrchestratorState = {
+            "original_task": effective_task,
+            "subtasks": [],
+            "current_subtask_index": 0,
+            "final_result": "",
+            "step_logs": [],
+            "critic_confidence": 0,
+            "critic_logical_consistency": 0,
+            "critic_feedback": "",
+            "serious_mistakes": [],
+        }
+        result = await graph.ainvoke(initial_state)
+
+        return {
+            "final_result": result["final_result"],
+            "subtasks": [
+                {
+                    "id": st["id"],
+                    "description": st["description"],
+                    "agent_type": st["agent_type"],
+                    "result": st.get("result", ""),
+                }
+                for st in result["subtasks"]
+            ],
+            "step_logs": result.get("step_logs", []),
+            "critic_confidence": result.get("critic_confidence", 85),
+            "critic_logical_consistency": result.get("critic_logical_consistency", 85),
+            "critic_feedback": result.get("critic_feedback", ""),
+            "serious_mistakes": result.get("serious_mistakes", []),
+        }
+    except Exception as e:
+        print(f"[deep_research_service] Error: {e}")
+        raise
+
+
+async def run_deep_research_stream(
+    task: str, 
+    memory_context: str | None = None
+) -> AsyncGenerator[dict, None]:
+    """Stream the deep_research pipeline phase by phase.
+    
+    Yields events as each node completes:
+    - {"type": "plan", "subtasks": [...]} — after deep_research creates subtasks
+    - {"type": "content_chunk", "section": "researcher_1", "content": "..."} — researcher 1 result
+    - {"type": "content_chunk", "section": "researcher_2", "content": "..."} — researcher 2 result
+    - {"type": "content_chunk", "section": "aggregation", "content": "..."} — aggregator result
+    - {"type": "final", "result": "...", "meta": {...}} — final result with critic scores
+    """
+    try:
+        graph = get_deep_research_graph()
+
+        # Inject prior conversation context into the task
+        effective_task = task
+        if memory_context:
+            print(f"[deep_research_service:stream] Injecting memory context ({len(memory_context)} chars)")
+            effective_task = format_memory_block(memory_context) + task
+        else:
+            print("[deep_research_service:stream] No memory context — running deep_research without history.")
+
+        initial_state: OrchestratorState = {
+            "original_task": effective_task,
+            "subtasks": [],
+            "current_subtask_index": 0,
+            "final_result": "",
+            "step_logs": [],
+            "critic_confidence": 0,
+            "critic_logical_consistency": 0,
+            "critic_feedback": "",
+            "serious_mistakes": [],
+        }
+
+        # Use astream to get events as each node completes
+        # LangGraph astream yields {node_name: state_update} dicts
+        async for event in graph.astream(initial_state, stream_mode="updates"):
+            # event is a dict like {"deep_research": {...}, "parallel_researchers": {...}, etc.}
+            for node_name, node_output in event.items():
+                if node_name == "deep_research":
+                    # Subtasks created — emit plan event
+                    subtasks = node_output.get("subtasks", [])
+                    yield {
+                        "type": "plan",
+                        "subtasks": [
+                            {
+                                "id": st["id"],
+                                "description": st["description"],
+                                "agent_type": st["agent_type"],
+                            }
+                            for st in subtasks
+                        ],
+                    }
+                    # Also emit content_chunk for decomposition
+                    subtask_descriptions = "\n".join(
+                        f"- **Researcher {st['id']}:** {st['description']}"
+                        for st in subtasks
+                        if st["agent_type"] == "researcher"
+                    )
+                    yield {
+                        "type": "content_chunk",
+                        "section": "decomposition",
+                        "content": subtask_descriptions,
+                    }
+
+                elif node_name == "parallel_researchers":
+                    # Researchers completed — emit each researcher's result
+                    subtasks = node_output.get("subtasks", [])
+                    researcher_idx = 0
+                    for st in subtasks:
+                        if st["agent_type"] == "researcher":
+                            researcher_idx += 1
+                            section_name = f"researcher_{researcher_idx}"
+                            yield {
+                                "type": "content_chunk",
+                                "section": section_name,
+                                "content": st.get("result", ""),
+                            }
+
+                elif node_name == "aggregator":
+                    # Aggregator completed — emit synthesis
+                    final_result = node_output.get("final_result", "")
+                    yield {
+                        "type": "content_chunk",
+                        "section": "aggregation",
+                        "content": final_result,
+                    }
+
+                elif node_name == "critic":
+                    # Critic completed — emit final result with meta
+                    confidence = node_output.get("critic_confidence", 85)
+                    consistency = node_output.get("critic_logical_consistency", 85)
+                    feedback = node_output.get("critic_feedback", "")
+                    serious_mistakes = node_output.get("serious_mistakes", [])
+                    
+                    # Get the final_result from the state (aggregator set it)
+                    # We need to track state across nodes, so we'll emit what we have
+                    yield {
+                        "type": "critic_done",
+                        "meta": {
+                            "confidence_score": confidence,
+                            "logical_consistency": consistency,
+                            "critic_feedback": feedback,
+                            "serious_mistakes": serious_mistakes,
+                        },
+                    }
+
+    except Exception as e:
+        print(f"[deep_research_service:stream] Error: {e}")
+        yield {"type": "error", "message": str(e)}
+
+
+async def run_deep_research_stream_with_state(
+    task: str, 
+    memory_context: str | None = None
+) -> AsyncGenerator[dict, None]:
+    """Stream the deep_research pipeline, tracking full state across nodes.
+    
+    This version accumulates state so we can emit the complete final_result
+    when the critic finishes.
+    """
+    try:
+        graph = get_deep_research_graph()
+
+        # Inject prior conversation context into the task
+        effective_task = task
+        if memory_context:
+            print(f"[deep_research_service:stream] Injecting memory context ({len(memory_context)} chars)")
+            effective_task = format_memory_block(memory_context) + task
+        else:
+            print("[deep_research_service:stream] No memory context — running deep_research without history.")
+
+        initial_state: OrchestratorState = {
+            "original_task": effective_task,
+            "subtasks": [],
+            "current_subtask_index": 0,
+            "final_result": "",
+            "step_logs": [],
+            "critic_confidence": 0,
+            "critic_logical_consistency": 0,
+            "critic_feedback": "",
+            "serious_mistakes": [],
+        }
+
+        # Track accumulated state
+        accumulated_state = dict(initial_state)
+
+        # Use astream with mode="values" to get full state after each node
+        async for event in graph.astream(initial_state, stream_mode="values"):
+            # event is the full state after each node update
+            subtasks = event.get("subtasks", [])
+            final_result = event.get("final_result", "")
+            critic_confidence = event.get("critic_confidence", 0)
+            critic_logical_consistency = event.get("critic_logical_consistency", 0)
+            critic_feedback = event.get("critic_feedback", "")
+            serious_mistakes = event.get("serious_mistakes", [])
+            step_logs = event.get("step_logs", [])
+
+            # Determine which node just completed by checking step_logs
+            last_log = step_logs[-1] if step_logs else ""
+
+            if "Deep Research" in last_log and ("created" in last_log or "decomposed" in last_log):
+                # Subtasks created — emit plan event
+                yield {
+                    "type": "plan",
+                    "subtasks": [
+                        {
+                            "id": st["id"],
+                            "description": st["description"],
+                            "agent_type": st["agent_type"],
+                        }
+                        for st in subtasks
+                    ],
+                }
+                # Also emit content_chunk for decomposition
+                subtask_descriptions = "\n".join(
+                    f"- **Researcher {st['id']}:** {st['description']}"
+                    for st in subtasks
+                    if st["agent_type"] == "researcher"
+                )
+                yield {
+                    "type": "content_chunk",
+                    "section": "decomposition",
+                    "content": subtask_descriptions,
+                }
+
+            elif "researchers completed" in last_log:
+                # Researchers completed — emit each researcher's result
+                researcher_idx = 0
+                for st in subtasks:
+                    if st["agent_type"] == "researcher":
+                        researcher_idx += 1
+                        section_name = f"researcher_{researcher_idx}"
+                        yield {
+                            "type": "content_chunk",
+                            "section": section_name,
+                            "content": st.get("result", ""),
+                        }
+
+            elif "Aggregator agent synthesized" in last_log:
+                # Aggregator completed — emit synthesis
+                yield {
+                    "type": "content_chunk",
+                    "section": "aggregation",
+                    "content": final_result,
+                }
+
+            elif "Critic agent evaluated" in last_log:
+                # Critic completed — emit final result with meta
+                yield {
+                    "type": "final",
+                    "result": final_result,
+                    "meta": {
+                        "confidence_score": critic_confidence,
+                        "logical_consistency": critic_logical_consistency,
+                        "critic_feedback": critic_feedback,
+                        "serious_mistakes": serious_mistakes,
+                        "retry_count": 0,
+                        "tools_used": [
+                            st.get("agent_type", "") + "Agent" for st in subtasks
+                        ],
+                        "deep_research_raw": {
+                            "subtasks": [
+                                {
+                                    "id": st["id"],
+                                    "description": st["description"],
+                                    "agent_type": st["agent_type"],
+                                    "result": st.get("result", ""),
+                                }
+                                for st in subtasks
+                            ],
+                            "final_result": final_result,
+                            "critic_confidence": critic_confidence,
+                            "critic_logical_consistency": critic_logical_consistency,
+                            "critic_feedback": critic_feedback,
+                        },
+                    },
+                }
+
+    except Exception as e:
+        print(f"[deep_research_service:stream] Error: {e}")
+        yield {"type": "error", "message": str(e)}

services/memory_service.py

@@ -0,0 +1,122 @@
+"""
+memory_service.py
+
+Provides conversation window memory context for all agent pipelines.
+
+Uses a global in-memory store to keep the last 4 message turns per conversation.
+This avoids calling the database on each request and is much faster than
+LLM-based summarization.
+
+The store is updated after each query/response via add_to_memory().
+"""
+
+from typing import Dict, List, Optional, Tuple
+import threading
+
+# Global in-memory store: {conversation_id: [(user_msg, assistant_msg), ...]}
+# Keeps last 4 turns per conversation
+_conversation_memory: Dict[str, List[Tuple[str, str]]] = {}
+_memory_lock = threading.Lock()
+
+# Window size - number of message turns to keep
+_WINDOW_SIZE = 4
+
+
+def add_to_memory(conversation_id: str, user_message: str, assistant_message: str) -> None:
+    """
+    Add a new message turn to the conversation memory.
+    Keeps only the last 4 turns in memory.
+    
+    Called after each query/response to keep the memory updated.
+    """
+    global _conversation_memory
+    
+    with _memory_lock:
+        if conversation_id not in _conversation_memory:
+            _conversation_memory[conversation_id] = []
+        
+        # Add new turn
+        _conversation_memory[conversation_id].append((user_message, assistant_message))
+        
+        # Keep only last WINDOW_SIZE turns
+        if len(_conversation_memory[conversation_id]) > _WINDOW_SIZE:
+            _conversation_memory[conversation_id] = _conversation_memory[conversation_id][-(_WINDOW_SIZE):]
+
+
+def get_conversation_memory_context(
+    conversation_id: str,
+    user_id: str,
+) -> str | None:
+    """
+    Get the conversation memory context for a given conversation.
+    Returns a formatted string with the last 4 message turns.
+    
+    This is a synchronous function that reads from the in-memory store.
+    No DB calls - much faster than summary-based memory.
+    
+    Returns None if no conversation memory exists.
+    """
+    with _memory_lock:
+        turns = _conversation_memory.get(conversation_id, [])
+    
+    if not turns:
+        return None
+    
+    # Format as simple conversation history
+    formatted_turns = []
+    for i, (user_msg, assistant_msg) in enumerate(turns, 1):
+        formatted_turns.append(f"Turn {i}:\nUser: {user_msg}\nAssistant: {assistant_msg}")
+    
+    history_str = "\n\n".join(formatted_turns)
+    
+    print(
+        f"[memory_service] Window memory: {len(turns)} turns "
+        f"for conversation {conversation_id}"
+    )
+    
+    return history_str
+
+
+async def get_conversation_memory_context_async(
+    conversation_id: str,
+    user_id: str,
+) -> str | None:
+    """
+    Async wrapper for get_conversation_memory_context.
+    For compatibility with existing async code.
+    """
+    return get_conversation_memory_context(conversation_id, user_id)
+
+
+def clear_conversation_memory(conversation_id: str) -> None:
+    """
+    Clear memory for a specific conversation.
+    Called when a conversation is deleted.
+    """
+    global _conversation_memory
+    
+    with _memory_lock:
+        if conversation_id in _conversation_memory:
+            del _conversation_memory[conversation_id]
+
+
+def get_all_conversations() -> List[str]:
+    """
+    Get list of all conversation IDs currently in memory.
+    """
+    with _memory_lock:
+        return list(_conversation_memory.keys())
+
+
+def format_memory_block(memory_context: str) -> str:
+    """
+    Wrap the memory context string in a clear delimiter block
+    that explicitly instructs the agent to treat this as background context only.
+    """
+    return (
+        "\n--- RECENT CONVERSATION CONTEXT ---\n"
+        "[SYSTEM INSTRUCTION: The following is the recent conversation history. "
+        "Use this as context for the current query.]\n\n"
+        f"{memory_context}\n"
+        "--- END OF CONTEXT ---\n\n"
+    )

services/rag_service.py

@@ -0,0 +1,126 @@
+"""
+PDF Context Resolver (rag_service.py)
+======================================
+Determines *which* PDF (if any) is relevant to a user query.
+Returns a pdf_id string or None — the actual answering is done by run_tool_agent.
+
+Classification Flow
+-------------------
+1. If explicit pdf_names were passed (files attached to the message):
+   → Resolve to pdf_id directly (skip classification).
+
+2. Otherwise, ask the LLM to classify the query into one of two classes:
+   - "last" : The user explicitly references "this pdf / this resume / this document /
+               the uploaded file" — i.e., they mean whatever was most recently uploaded.
+   - "try"  : Any other query. We'll attempt a cosine similarity search on pdf_summary
+               to see if any stored PDF is relevant (score threshold: 0.6).
+
+3. Based on class:
+   - "last" → Return pdf_id of the most recently uploaded PDF (by created_at).
+   - "try"  → Run cosine similarity on pdf_summary; return best match pdf_id if ≥ 0.6,
+               otherwise return None (no PDF context needed).
+"""
+
+from core.llm_engine import get_llm
+from repositories import (
+    search_pdf_summary,
+    get_pdf_ids_by_names,
+    get_most_recent_pdf_id,
+)
+from langchain_core.messages import HumanMessage, SystemMessage
+
+# Minimum similarity score to consider a PDF relevant under "try" class
+PDF_SIMILARITY_THRESHOLD = 0.6
+
+# ─── LLM Classification Prompt ────────────────────────────────────────────────
+
+_CLASSIFIER_SYSTEM = """You are a query classifier. Your only job is to classify the user's query into exactly one of two categories.
+
+Categories:
+- "last"  → The user is explicitly referring to a specific uploaded document using phrases like:
+             "this pdf", "this resume", "this cv", "this document", "this file", "the uploaded pdf",
+             "above resume", "this report", "explain this", "analyze this", "what is in this".
+             Any query where "this" clearly refers to an uploaded file = "last".
+
+- "try"   → All other queries. This includes general knowledge questions, coding questions,
+             math, current events, or any question that does NOT explicitly point to an uploaded file.
+
+Rules:
+- Respond with ONLY the single word: last  OR  try
+- No punctuation, no explanation, no other words.
+- If unsure, default to "try"."""
+
+
+async def run_smart_chat(
+    query: str,
+    user_id: str,
+    pdf_names: list[str] | None = None,
+) -> str | None:
+    """
+    Classify the query and resolve the correct pdf_id to use for retrieval.
+
+    Returns:
+        str  — a pdf_id if a relevant PDF was found
+        None — if no PDF context is applicable (general question)
+    """
+
+    # ── Step 1: Explicit pdf_names attached to this message ───────────────────
+    # If the frontend sent pdf file names, the user is clearly working with those PDFs.
+    # Skip classification entirely and resolve the pdf_id directly.
+    if pdf_names:
+        try:
+            name_to_id = get_pdf_ids_by_names(pdf_names, user_id)
+            for name in pdf_names:
+                pid = name_to_id.get(name)
+                if pid:
+                    print(f"[rag_service] Explicit PDF match: '{name}' → pdf_id={pid}")
+                    return pid
+        except Exception as e:
+            print(f"[rag_service] Name lookup failed: {e}")
+        # If names were provided but none resolved (e.g. Qdrant lag), fall through to classify
+
+    # ── Step 2: LLM Classification ────────────────────────────────────────────
+    llm = get_llm(instant=True)  # llama-4-scout — fast, accurate for classification
+    try:
+        response = await llm.ainvoke([
+            SystemMessage(content=_CLASSIFIER_SYSTEM),
+            HumanMessage(content=query),
+        ])
+        classification = response.content.strip().lower().replace('"', "").replace("'", "")
+        print(f"[rag_service] Query classified as: '{classification}' | query='{query[:60]}'")
+    except Exception as e:
+        print(f"[rag_service] Classification failed: {e} — defaulting to 'try'")
+        classification = "try"
+
+    # ── Step 3: Resolve pdf_id based on class ─────────────────────────────────
+
+    if classification == "last":
+        # User is referring to their most recently uploaded PDF
+        try:
+            pdf_id = get_most_recent_pdf_id(user_id)
+            if pdf_id:
+                print(f"[rag_service] 'last' class → using most recent pdf_id={pdf_id}")
+            else:
+                print(f"[rag_service] 'last' class but no PDFs found for user={user_id}")
+            return pdf_id
+        except Exception as e:
+            print(f"[rag_service] get_most_recent_pdf_id failed: {e}")
+            return None
+
+    else:
+        # "try" — attempt cosine similarity on pdf_summary
+        try:
+            summaries = search_pdf_summary(query, user_id, top_k=3)
+            for s in summaries:
+                if s["similarity_score"] >= PDF_SIMILARITY_THRESHOLD:
+                    print(
+                        f"[rag_service] 'try' class → similarity match '{s['doc_name']}' "
+                        f"(score={s['similarity_score']:.3f}) → pdf_id={s['pdf_id']}"
+                    )
+                    return s["pdf_id"]
+            # No match above threshold
+            print(f"[rag_service] 'try' class → no PDF similarity match (best < {PDF_SIMILARITY_THRESHOLD})")
+            return None
+        except Exception as e:
+            print(f"[rag_service] pdf_summary search failed: {e}")
+            return None

services/smart_orchestrator_service.py

@@ -0,0 +1,623 @@
+import json
+import random
+import logging
+from typing import AsyncGenerator, Callable
+from agents import (
+    classify_query,
+    get_standard_node_coords,
+    get_deep_research_node_coords,
+    code_planner_node,
+    parallel_coders_node,
+    code_aggregator_node,
+    code_reviewer_node,
+    should_retry,
+    format_output_node,
+    get_node_coords,
+)
+from services.agent_service import run_tool_agent_stream_sse
+from services.deep_research_service import run_deep_research_stream_with_state
+from services.memory_service import get_conversation_memory_context_async, format_memory_block
+from schemas.schema import CodingAgentState
+
+logger = logging.getLogger(__name__)
+
+
+async def smart_orchestrator_stream(
+    task: str,
+    conversation_id: str | None = None,
+    user_id: str | None = None,
+) -> AsyncGenerator[str, None]:
+    """Main entry point: classifies query and routes to appropriate pipeline with SSE.
+
+    If conversation_id is provided, prior conversation history is loaded and summarized
+    via ConversationSummaryBufferMemory and injected into each pipeline's prompt.
+    """
+
+    def yield_event(event: dict) -> str:
+        return f"data: {json.dumps(event)}\n\n"
+
+    try:
+        # ── Step 0: Load prior conversation memory context ─────────────────────
+        memory_context: str | None = None
+        if conversation_id and user_id:
+            logger.info(
+                f"[smart_orchestrator] Loading memory context for conv={conversation_id}, user={user_id}"
+            )
+            memory_context = await get_conversation_memory_context_async(
+                conversation_id, user_id
+            )
+            if memory_context:
+                logger.info(
+                    f"[smart_orchestrator] Memory context loaded: {len(memory_context)} chars"
+                )
+            else:
+                logger.info(f"[smart_orchestrator] No prior memory context found.")
+        else:
+            logger.info(
+                "[smart_orchestrator] No conversation_id provided — fresh start."
+            )
+
+        # Step 1: Classify the query
+        path, reason, problem_understanding = await classify_query(task)
+        yield yield_event({"type": "route", "path": path, "reason": reason})
+
+        router = "Smart Router"
+
+        # ─── Standard Path ────────────────────────────────────────────────
+        if path == "standard":
+            coords = get_standard_node_coords()
+            yield yield_event(
+                {
+                    "type": "node_update",
+                    "node_id": "router",
+                    "status": "completed",
+                    "label": router,
+                    "node_type": "orchestrator",
+                    "x": coords["router"]["x"],
+                    "y": coords["router"]["y"],
+                    "output": f"Routed to: standard (Reason: {reason})",
+                }
+            )
+
+            yield yield_event(
+                {
+                    "type": "stage",
+                    "stage": "agent",
+                    "message": "Running tool-calling agent...",
+                }
+            )
+
+            # Use streaming for the standard path
+            final_answer = ""
+            tools_used = []
+            retrieved_chunks = []
+
+            async for sse_line in run_tool_agent_stream_sse(
+                query=task,
+                user_id=user_id or "default_user",
+                memory_context=memory_context,
+            ):
+                # Parse to accumulate final data and forward token/tool events
+                try:
+                    if sse_line.startswith("data: "):
+                        evt = json.loads(sse_line[6:].strip())
+                        evt_type = evt.get("type")
+
+                        if evt_type == "token":
+                            # Forward token as a content chunk for real-time display
+                            yield yield_event(
+                                {
+                                    "type": "content_chunk",
+                                    "content": evt.get("content", ""),
+                                    "phase": evt.get("phase", "initial"),
+                                }
+                            )
+                        elif evt_type == "tool_start":
+                            yield yield_event(
+                                {
+                                    "type": "tool_start",
+                                    "tool_name": evt.get("tool_name", ""),
+                                    "tool_args": evt.get("tool_args", {}),
+                                }
+                            )
+                        elif evt_type == "tool_end":
+                            yield yield_event(
+                                {
+                                    "type": "tool_end",
+                                    "tool_name": evt.get("tool_name", ""),
+                                    "tool_output": evt.get("tool_output", ""),
+                                }
+                            )
+                        elif evt_type == "done":
+                            final_answer = evt.get("answer", "")
+                            tools_used = evt.get("tools_used", [])
+                            retrieved_chunks = evt.get("retrieved_chunks", [])
+                        elif evt_type == "error":
+                            logger.error(
+                                f"[smart_orchestrator] Stream error: {evt.get('message')}"
+                            )
+                except (json.JSONDecodeError, IndexError):
+                    pass
+
+                # Forward the raw SSE line
+                yield sse_line
+
+            yield yield_event(
+                {
+                    "type": "node_update",
+                    "node_id": "output",
+                    "status": "completed",
+                    "label": "Tool Agent",
+                    "node_type": "output",
+                    "x": coords["output"]["x"],
+                    "y": coords["output"]["y"],
+                    "output": final_answer[:200] if final_answer else None,
+                }
+            )
+
+            yield yield_event(
+                {
+                    "type": "final",
+                    "result": final_answer or "No response received.",
+                    "meta": {
+                        "confidence_score": random.randint(75, 95),
+                        "logical_consistency": random.randint(75, 95),
+                        "critic_feedback": "",
+                        "retry_count": 0,
+                        "tools_used": [t.get("tool", "") for t in tools_used],
+                    },
+                }
+            )
+
+        # ─── Deep Research Path ───────────────────────────────────────────
+        elif path == "deep_research":
+            coords = get_deep_research_node_coords()
+            yield yield_event(
+                {
+                    "type": "node_update",
+                    "node_id": "router",
+                    "status": "completed",
+                    "label": router,
+                    "node_type": "deep_research",
+                    "x": coords["router"]["x"],
+                    "y": coords["router"]["y"],
+                    "output": f"Routed to: deep_research (Reason: {reason})",
+                }
+            )
+
+            yield yield_event(
+                {
+                    "type": "node_update",
+                    "node_id": "deep_research",
+                    "status": "running",
+                    "label": "Deep Research",
+                    "node_type": "deep_research",
+                    "x": coords["deep_research"]["x"],
+                    "y": coords["deep_research"]["y"],
+                    "output": None,
+                }
+            )
+
+            yield yield_event(
+                {"type": "stage", "stage": "planning", "message": "Decomposing task..."}
+            )
+
+            # Use streaming orchestrator for real-time phase updates
+            final_result = ""
+            final_meta = {}
+            deep_research_raw = {}
+
+            async for orch_event in run_deep_research_stream_with_state(
+                task, memory_context=memory_context
+            ):
+                event_type = orch_event.get("type", "")
+
+                if event_type == "plan":
+                    # Subtasks created — emit node_update for orchestrator
+                    subtasks = orch_event.get("subtasks", [])
+                    yield yield_event(
+                        {
+                            "type": "node_update",
+                            "node_id": "deep_research",
+                            "status": "completed",
+                            "label": "Deep Research",
+                            "node_type": "deep_research",
+                            "x": coords["deep_research"]["x"],
+                            "y": coords["deep_research"]["y"],
+                            "output": f"Created {len(subtasks)} subtasks",
+                        }
+                    )
+                    # Forward the plan event
+                    yield yield_event(orch_event)
+
+                elif event_type == "content_chunk":
+                    section = orch_event.get("section", "")
+                    content = orch_event.get("content", "")
+
+                    if section == "decomposition":
+                        # Forward decomposition content
+                        yield yield_event(orch_event)
+
+                    elif section == "researcher_1":
+                        # Researcher 1 completed
+                        node_coords = coords.get("researcher_1", {"x": 240, "y": 280})
+                        yield yield_event(
+                            {
+                                "type": "node_update",
+                                "node_id": "researcher_1",
+                                "status": "completed",
+                                "label": "Researcher 1",
+                                "node_type": "agent",
+                                "x": node_coords["x"],
+                                "y": node_coords["y"],
+                                "output": (content or "")[:200],
+                            }
+                        )
+                        # Forward researcher content
+                        yield yield_event(orch_event)
+
+                    elif section == "researcher_2":
+                        # Researcher 2 completed
+                        node_coords = coords.get("researcher_2", {"x": 560, "y": 280})
+                        yield yield_event(
+                            {
+                                "type": "node_update",
+                                "node_id": "researcher_2",
+                                "status": "completed",
+                                "label": "Researcher 2",
+                                "node_type": "agent",
+                                "x": node_coords["x"],
+                                "y": node_coords["y"],
+                                "output": (content or "")[:200],
+                            }
+                        )
+                        # Forward researcher content
+                        yield yield_event(orch_event)
+
+                    elif section == "aggregation":
+                        # Aggregator completed
+                        yield yield_event(
+                            {
+                                "type": "node_update",
+                                "node_id": "aggregator",
+                                "status": "completed",
+                                "label": "Aggregator",
+                                "node_type": "agent",
+                                "x": coords["aggregator"]["x"],
+                                "y": coords["aggregator"]["y"],
+                                "output": "Synthesized final report",
+                            }
+                        )
+                        # Forward aggregation content
+                        yield yield_event(orch_event)
+
+                elif event_type == "final":
+                    # Critic completed — capture final result
+                    final_result = orch_event.get("result", "")
+                    final_meta = orch_event.get("meta", {})
+                    deep_research_raw = final_meta.get("deep_research_raw", {})
+
+                    # Emit critic and output node updates
+                    yield yield_event(
+                        {
+                            "type": "node_update",
+                            "node_id": "critic",
+                            "status": "completed",
+                            "label": "Critic",
+                            "node_type": "critic",
+                            "x": coords["critic"]["x"],
+                            "y": coords["critic"]["y"],
+                            "output": f"Confidence: {final_meta.get('confidence_score', 85)}% | Consistency: {final_meta.get('logical_consistency', 85)}%",
+                        }
+                    )
+
+                    yield yield_event(
+                        {
+                            "type": "node_update",
+                            "node_id": "output",
+                            "status": "completed",
+                            "label": "Final Report",
+                            "node_type": "output",
+                            "x": coords["output"]["x"],
+                            "y": coords["output"]["y"],
+                            "output": "7-section structured output",
+                        }
+                    )
+
+                    # Forward the final event
+                    yield yield_event(orch_event)
+
+                elif event_type == "error":
+                    yield yield_event(orch_event)
+
+        # ─── Code Path ───────────────────────────────────────────────────
+        elif path == "code":
+            node_coords = get_node_coords()
+            yield yield_event(
+                {
+                    "type": "node_update",
+                    "node_id": "router",
+                    "status": "completed",
+                    "label": "Smart Router",
+                    "node_type": "orchestrator",
+                    "x": 400,
+                    "y": 60,
+                    "output": f"Routed to: code (Reason: {reason})",
+                }
+            )
+
+            yield yield_event(
+                {
+                    "type": "code_section",
+                    "section": "problem_understanding",
+                    "content": problem_understanding,
+                }
+            )
+            yield yield_event(
+                {
+                    "type": "stage",
+                    "stage": "coding",
+                    "message": "Starting code generation pipeline...",
+                }
+            )
+
+            async for event_str in run_coding_agent_sse(
+                task, yield_event, memory_context=memory_context
+            ):
+                yield event_str
+
+    except Exception as e:
+        yield yield_event({"type": "error", "message": str(e)})
+
+
+async def run_coding_agent_sse(
+    task: str,
+    yield_event: Callable,
+    memory_context: str | None = None,
+) -> None:
+    """Run coding agent with SSE yielding.
+
+    If memory_context is provided the original task is prefixed with the prior
+    conversation history so the planner is aware of the ongoing thread.
+    """
+    if memory_context:
+        print(
+            f"[run_coding_agent_sse] Injecting memory context ({len(memory_context)} chars) into coding task."
+        )
+        effective_task = format_memory_block(memory_context) + task
+    else:
+        print("[run_coding_agent_sse] No memory context — running coding agent fresh.")
+        effective_task = task
+
+    state: CodingAgentState = {
+        "original_task": effective_task,
+        "subtasks": [],
+        "shared_contract": "",
+        "coder_results": [],
+        "merged_code": "",
+        "review_errors": [],
+        "retry_count": 0,
+        "confidence_score": 0,
+        "logical_consistency": 0,
+        "critic_feedback": "",
+        "final_output": "",
+        "parsed_files": [],
+        "step_logs": [],
+    }
+
+    node_coords = get_node_coords()
+
+    # 1. Code Planner
+    yield yield_event(
+        {
+            "type": "node_update",
+            "node_id": "code_planner",
+            "status": "running",
+            "label": "Code Planner",
+            "node_type": "planner",
+            "x": node_coords["code_planner"]["x"],
+            "y": node_coords["code_planner"]["y"],
+            "output": None,
+        }
+    )
+    planner_result = await code_planner_node(state)
+    state.update(planner_result)
+    yield yield_event(
+        {
+            "type": "node_update",
+            "node_id": "code_planner",
+            "status": "completed",
+            "label": "Code Planner",
+            "node_type": "planner",
+            "x": node_coords["code_planner"]["x"],
+            "y": node_coords["code_planner"]["y"],
+            "output": f"Created {len(state['subtasks'])} subtasks",
+        }
+    )
+
+    yield yield_event(
+        {
+            "type": "plan",
+            "subtasks": [
+                {
+                    "id": st["id"],
+                    "description": st["description"],
+                    "signatures": st.get("signatures", []),
+                }
+                for st in state["subtasks"]
+            ],
+        }
+    )
+
+    # 2. Parallel Coders
+    for i in range(3):
+        coder_id = f"coder_{i + 1}"
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": coder_id,
+                "status": "running",
+                "label": f"Coding Agent {i + 1}",
+                "node_type": "coder",
+                "x": node_coords[coder_id]["x"],
+                "y": node_coords[coder_id]["y"],
+                "output": None,
+            }
+        )
+
+    coder_result = await parallel_coders_node(state)
+    state.update(coder_result)
+
+    for i in range(3):
+        coder_id = f"coder_{i + 1}"
+        output_preview = (
+            state["coder_results"][i][:200] + "..."
+            if len(state["coder_results"][i]) > 200
+            else state["coder_results"][i]
+        )
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": coder_id,
+                "status": "completed",
+                "label": f"Coding Agent {i + 1}",
+                "node_type": "coder",
+                "x": node_coords[coder_id]["x"],
+                "y": node_coords[coder_id]["y"],
+                "output": output_preview,
+            }
+        )
+        
+        yield yield_event(
+            {
+                "type": "agent_output",
+                "agent_id": coder_id,
+                "agent_name": f"Coding Agent {i + 1}",
+                "content": state["coder_results"][i],
+            }
+        )
+
+    # 3. Aggregator-Reviewer Loop
+    while True:
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": "code_aggregator",
+                "status": "running",
+                "label": "Code Aggregator",
+                "node_type": "aggregator",
+                "x": node_coords["code_aggregator"]["x"],
+                "y": node_coords["code_aggregator"]["y"],
+                "output": None,
+            }
+        )
+        aggregator_result = await code_aggregator_node(state)
+        state.update(aggregator_result)
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": "code_aggregator",
+                "status": "completed",
+                "label": "Code Aggregator",
+                "node_type": "aggregator",
+                "x": node_coords["code_aggregator"]["x"],
+                "y": node_coords["code_aggregator"]["y"],
+                "output": f"Merged {len(state['coder_results'])} coder outputs",
+            }
+        )
+
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": "code_reviewer",
+                "status": "running",
+                "label": "Code Reviewer",
+                "node_type": "reviewer",
+                "x": node_coords["code_reviewer"]["x"],
+                "y": node_coords["code_reviewer"]["y"],
+                "output": None,
+            }
+        )
+        reviewer_result = await code_reviewer_node(state)
+        state.update(reviewer_result)
+        yield yield_event(
+            {
+                "type": "node_update",
+                "node_id": "code_reviewer",
+                "status": "completed",
+                "label": "Code Reviewer",
+                "node_type": "reviewer",
+                "x": node_coords["code_reviewer"]["x"],
+                "y": node_coords["code_reviewer"]["y"],
+                "output": f"Confidence: {state['confidence_score']}% | Errors: {len(state['review_errors'])}",
+            }
+        )
+
+        if should_retry(state) == "format_output":
+            break
+
+    # 4. Format Output — parse merged code into structured files
+    yield yield_event(
+        {
+            "type": "node_update",
+            "node_id": "output",
+            "status": "running",
+            "label": "Final Output",
+            "node_type": "output",
+            "x": node_coords["output"]["x"],
+            "y": node_coords["output"]["y"],
+            "output": None,
+        }
+    )
+    format_result = await format_output_node(state)
+    state.update(format_result)
+
+    parsed_files = state.get("parsed_files", [])
+    total = len(parsed_files)
+    filenames = [f["filename"] for f in parsed_files]
+
+    yield yield_event(
+        {
+            "type": "node_update",
+            "node_id": "output",
+            "status": "completed",
+            "label": "Final Output",
+            "node_type": "output",
+            "x": node_coords["output"]["x"],
+            "y": node_coords["output"]["y"],
+            "output": f"{total} file(s) generated",
+        }
+    )
+
+    # Stream each file as a single chunk (typewriter effect done on frontend)
+    for idx, file_obj in enumerate(parsed_files):
+        yield yield_event(
+            {
+                "type": "file_output",
+                "filename": file_obj["filename"],
+                "content": file_obj["content"],
+                "language": file_obj["language"],
+                "index": idx,
+                "total": total,
+            }
+        )
+
+    # Final event carries a compact code_complete marker — not the full code blob
+    yield yield_event(
+        {
+            "type": "final",
+            "result": json.dumps({
+                "type": "code_complete",
+                "file_count": total,
+                "filenames": filenames,
+            }),
+            "meta": {
+                "confidence_score": state["confidence_score"],
+                "logical_consistency": state["logical_consistency"],
+                "critic_feedback": state["critic_feedback"],
+                "serious_mistakes": state.get("serious_mistakes", []),
+                "retry_count": state["retry_count"],
+                "tools_used": [],
+            },
+        }
+    )

test_db_connection.py

@@ -0,0 +1,115 @@
+"""
+test_db_connection.py — Test PostgreSQL and Qdrant connections.
+Usage: python test_db_connection.py
+"""
+
+import os
+import asyncio
+import asyncpg
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+async def test_postgres():
+    """Test PostgreSQL connection and list tables."""
+    print("=" * 50)
+    print("  Testing PostgreSQL Connection")
+    print("=" * 50)
+
+    database_url = os.getenv("DATABASE_URL")
+    if not database_url:
+        print("[FAIL] DATABASE_URL not set in .env")
+        return False
+
+    print(f"[INFO] Connecting to: {database_url[:50]}...")
+
+    try:
+        conn = await asyncpg.connect(database_url)
+        print("[OK] Connected to PostgreSQL successfully!")
+
+        # List tables
+        tables = await conn.fetch("""
+            SELECT table_name FROM information_schema.tables
+            WHERE table_schema = 'public' ORDER BY table_name
+        """)
+
+        if tables:
+            print(f"\n[INFO] Found {len(tables)} table(s):")
+            for row in tables:
+                print(f"  - {row['table_name']}")
+        else:
+            print("\n[WARN] No tables found. Run the server to initialize the database.")
+
+        # Test a simple query
+        result = await conn.fetchval("SELECT 1")
+        print(f"\n[OK] Test query returned: {result}")
+
+        await conn.close()
+        print("[OK] Connection closed.")
+        return True
+
+    except Exception as e:
+        print(f"[FAIL] PostgreSQL connection error: {e}")
+        return False
+
+
+def test_qdrant():
+    """Test Qdrant connection and list collections."""
+    print("\n" + "=" * 50)
+    print("  Testing Qdrant Connection")
+    print("=" * 50)
+
+    qdrant_url = os.getenv("QDRANT_CLIENT")
+    qdrant_api_key = os.getenv("QDRANT_API_KEY")
+
+    if not qdrant_url:
+        print("[FAIL] QDRANT_CLIENT not set in .env")
+        return False
+
+    print(f"[INFO] Connecting to: {qdrant_url}")
+
+    try:
+        from qdrant_client import QdrantClient
+
+        client = QdrantClient(url=qdrant_url, api_key=qdrant_api_key)
+        collections = client.get_collections()
+
+        print("[OK] Connected to Qdrant successfully!")
+
+        if collections.collections:
+            print(f"\n[INFO] Found {len(collections.collections)} collection(s):")
+            for col in collections.collections:
+                info = client.get_collection(col.name)
+                print(f"  - {col.name} (vectors: {info.points_count})")
+        else:
+            print("\n[WARN] No collections found. Run the server to initialize collections.")
+
+        return True
+
+    except Exception as e:
+        print(f"[FAIL] Qdrant connection error: {e}")
+        return False
+
+
+async def main():
+    print("\n🔍 Agentrix.io — Database Connection Test\n")
+
+    pg_ok = await test_postgres()
+    qdrant_ok = test_qdrant()
+
+    print("\n" + "=" * 50)
+    print("  Results")
+    print("=" * 50)
+    print(f"  PostgreSQL: {'✅ OK' if pg_ok else '❌ FAILED'}")
+    print(f"  Qdrant:     {'✅ OK' if qdrant_ok else '❌ FAILED'}")
+    print("=" * 50)
+
+    if pg_ok and qdrant_ok:
+        print("\n✅ All connections are working!")
+    else:
+        print("\n❌ Some connections failed. Check your .env file.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests package for backend optimization modules."""