staging deployment completed

.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# secrets
+.env
+
+# directories
+design/
+.idea/
+
+# files
+*.toml
+.python-version

Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,2 @@
+# UCode - Understand Monolith Codebases with Ease
+

call_graph.json

@@ -0,0 +1,117 @@
+{
+  "AI Practice.api.read_root": {
+    "id": "AI Practice.api.read_root",
+    "name": "read_root",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.get"
+    ],
+    "called_by": []
+  },
+  "AI Practice.api.get_todos": {
+    "id": "AI Practice.api.get_todos",
+    "name": "get_todos",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.get"
+    ],
+    "called_by": []
+  },
+  "AI Practice.api.get_todo": {
+    "id": "AI Practice.api.get_todo",
+    "name": "get_todo",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.get",
+      "HTTPException"
+    ],
+    "called_by": []
+  },
+  "AI Practice.api.create_todo": {
+    "id": "AI Practice.api.create_todo",
+    "name": "create_todo",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.post",
+      "todos.append",
+      "todo.dict"
+    ],
+    "called_by": []
+  },
+  "AI Practice.api.update_todo": {
+    "id": "AI Practice.api.update_todo",
+    "name": "update_todo",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.put",
+      "enumerate",
+      "HTTPException",
+      "updated_todo.dict"
+    ],
+    "called_by": []
+  },
+  "AI Practice.api.delete_todo": {
+    "id": "AI Practice.api.delete_todo",
+    "name": "delete_todo",
+    "class_name": "",
+    "module": "AI Practice",
+    "file": "AI Practice/api.py",
+    "calls": [
+      "app.delete",
+      "enumerate",
+      "HTTPException",
+      "todos.pop"
+    ],
+    "called_by": []
+  },
+  "Chat Bot.app.home": {
+    "id": "Chat Bot.app.home",
+    "name": "home",
+    "class_name": "",
+    "module": "Chat Bot",
+    "file": "Chat Bot/app.py",
+    "calls": [
+      "app.route",
+      "render_template"
+    ],
+    "called_by": []
+  },
+  "Chat Bot.app.chat": {
+    "id": "Chat Bot.app.chat",
+    "name": "chat",
+    "class_name": "",
+    "module": "Chat Bot",
+    "file": "Chat Bot/app.py",
+    "calls": [
+      "app.route",
+      "request.json.get",
+      "memory.append",
+      "client.chat.completions.create",
+      "jsonify",
+      "str"
+    ],
+    "called_by": []
+  },
+  "IMCSBOT.app.generate": {
+    "id": "IMCSBOT.app.generate",
+    "name": "generate",
+    "class_name": "",
+    "module": "IMCSBOT",
+    "file": "IMCSBOT/app.py",
+    "calls": [
+      "app.post",
+      "generator"
+    ],
+    "called_by": []
+  }
+}

config/config.py

@@ -0,0 +1,7 @@
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+PINECONE_API_KEY = os.getenv("PINECONE_API_KEY")
+PINECONE_INDEX     = "codebase-oracle"
+EMBEDDING_DIM      = 384

inference/inference.py

@@ -0,0 +1,468 @@
+"""
+inference.py
+------------
+Pure LLM inference layer for the Codebase Oracle system.
+No HTTP server, no FastAPI — just context + query → response.
+
+Responsibilities:
+    1. Accept query type + subtype + function/module name
+    2. Retrieve relevant context from vector store + call graph
+    3. Build correct prompt via prompts/ modules
+    4. Call OpenRouter API
+    5. Return clean markdown response string
+
+This module is the single entry point that main.py (FastAPI) calls.
+
+Depends on:
+    - retriever.py
+    - call_graph.py
+    - macro_prompts.py
+    - micro_prompts.py
+    - cross_module_prompts.py
+    - openai (OpenRouter is OpenAI-compatible)
+    - rich (logging only)
+
+Install:
+    pip install openai rich
+"""
+
+import os
+from dataclasses import dataclass, field
+from dotenv import load_dotenv
+from openai import OpenAI
+from rich.console import Console
+
+load_dotenv()  # loads OPENROUTER_API_KEY from .env file
+
+from retrieve.retrieve import Retriever, QueryType
+from store.call_graph import get_call_graph
+from prompt.macro_prompt import (
+    get_macro_system_prompt,
+    build_macro_user_prompt,
+)
+from prompt.micro_prompt import (
+    get_micro_system_prompt,
+    build_micro_user_prompt,
+    build_micro_followup_prompt,
+)
+from prompt.cross_module import (
+    get_cross_module_system_prompt,
+    build_cross_module_user_prompt,
+    build_cross_module_followup_prompt,
+    build_call_graph_payload,
+)
+
+console = Console()
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+DEFAULT_MODEL       = "nvidia/nemotron-3-super-120b-a12b:free"
+MAX_TOKENS          = 4096
+CONTEXT_MAX_CHARS   = 6000    # max chars fed to LLM as retrieved context
+N_RESULTS_DEFAULT   = 5       # default number of chunks to retrieve
+
+
+# ── Request / Response Models ─────────────────────────────────────────────────
+
+@dataclass
+class InferenceRequest:
+    """
+    Unified request model for all query types.
+
+    Fields:
+        query_type    : "macro" | "micro" | "cross_module"
+        query         : Developer's natural language question
+        subtype       : macro subtype or "" for micro/cross_module
+        function_name : Target function/method name (micro + cross_module)
+        class_name    : Target class name if method (optional)
+        module_name   : Target module name (macro module_responsibility)
+        followup      : True if this is a follow-up to a previous response
+        previous_response: Previous LLM response for follow-up context
+    """
+    query_type:        str
+    query:             str
+    subtype:           str        = ""
+    function_name:     str        = ""
+    class_name:        str        = ""
+    module_name:       str        = ""
+    followup:          bool       = False
+    previous_response: str        = ""
+
+
+@dataclass
+class InferenceResponse:
+    """
+    Unified response model returned to FastAPI / caller.
+
+    Fields:
+        success  : True if inference succeeded
+        content  : Markdown response string
+        error    : Error message if success is False
+        metadata : Optional dict with retrieval stats
+    """
+    success:  bool
+    content:  str        = ""
+    error:    str        = ""
+    metadata: dict       = field(default_factory=dict)
+
+
+# ── OpenRouter Client ─────────────────────────────────────────────────────────
+
+def _get_client() -> OpenAI:
+    """
+    Build and return an OpenAI-compatible client pointed at OpenRouter.
+    Reads OPENROUTER_API_KEY from .env file via load_dotenv.
+
+    Raises:
+        EnvironmentError: If OPENROUTER_API_KEY is not set.
+    """
+    api_key = os.getenv("OPENROUTER_API_KEY")
+    if not api_key:
+        raise EnvironmentError(
+            "OPENROUTER_API_KEY environment variable is not set. "
+            "Add OPENROUTER_API_KEY=your_key to your .env file."
+        )
+    return OpenAI(
+        base_url=OPENROUTER_BASE_URL,
+        api_key=api_key,
+    )
+
+
+def _call_llm(system_prompt: str,
+              user_prompt:   str,
+              model:         str = DEFAULT_MODEL) -> str:
+    """
+    Make a single LLM call via OpenRouter and return the response text.
+
+    Args:
+        system_prompt : System prompt string.
+        user_prompt   : User prompt string.
+        model         : OpenRouter model identifier.
+
+    Returns:
+        Raw response text from LLM.
+
+    Raises:
+        Exception: On API errors, propagated to caller.
+    """
+    client = _get_client()
+
+    response = client.chat.completions.create(
+        model=model,
+        max_tokens=MAX_TOKENS,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user",   "content": user_prompt},
+        ],
+    )
+
+    return response.choices[0].message.content or ""
+
+
+# ── Inference Engine ──────────────────────────────────────────────────────────
+
+class InferenceEngine:
+    """
+    Core inference engine for the Codebase Oracle.
+    Retrieves context, builds prompts, calls LLM, returns response.
+
+    Single instance shared across all FastAPI requests.
+    """
+
+    def __init__(self, model: str = DEFAULT_MODEL):
+        self.model     = model
+        self.retriever = Retriever()
+        console.print(
+            f"[green]✔[/green] InferenceEngine ready "
+            f"(model: [cyan]{model}[/cyan])\n"
+        )
+
+    # ── Public Entry Point ────────────────────────────────────────────────────
+
+    def infer(self, request: InferenceRequest) -> InferenceResponse:
+        """
+        Main entry point. Routes to the correct handler based on query_type.
+
+        Args:
+            request: InferenceRequest with all query parameters.
+
+        Returns:
+            InferenceResponse with markdown content or error.
+        """
+        try:
+            if request.query_type == QueryType.MACRO:
+                return self._handle_macro(request)
+
+            elif request.query_type == QueryType.MICRO:
+                return self._handle_micro(request)
+
+            elif request.query_type == QueryType.CROSS_MODULE:
+                return self._handle_cross_module(request)
+
+            else:
+                return InferenceResponse(
+                    success=False,
+                    error=f"Unknown query_type: '{request.query_type}'. "
+                          f"Use 'macro', 'micro', or 'cross_module'."
+                )
+
+        except EnvironmentError as e:
+            return InferenceResponse(success=False, error=str(e))
+
+        except Exception as e:
+            console.print(f"[red]❌ Inference error: {e}[/red]")
+            return InferenceResponse(
+                success=False,
+                error=f"Inference failed: {str(e)}"
+            )
+
+    # ── Macro Handler ─────────────────────────────────────────────────────────
+
+    def _handle_macro(self, req: InferenceRequest) -> InferenceResponse:
+        """Handle macro-level queries (architecture, module, data flow)."""
+
+        if not req.subtype:
+            return InferenceResponse(
+                success=False,
+                error="Macro queries require a subtype: "
+                      "'overall_architecture', 'module_responsibility', "
+                      "or 'data_flow'."
+            )
+
+        # Retrieve class-level chunks — macro uses class collection
+        chunks = self.retriever.retrieve(
+            query=req.query,
+            query_type=QueryType.MACRO,
+            n_results=N_RESULTS_DEFAULT,
+            filters={"module": {"$eq": req.module_name}}
+            if req.module_name and req.subtype == "module_responsibility"
+            else None,
+        )
+
+        context  = self.retriever.build_context(chunks, CONTEXT_MAX_CHARS)
+        system   = get_macro_system_prompt(req.subtype)
+        user     = build_macro_user_prompt(
+            subtype=req.subtype,
+            context=context,
+            query=req.query,
+            module_name=req.module_name,
+        )
+
+        console.print(
+            f"[cyan]→ Macro [{req.subtype}][/cyan] "
+            f"| {len(chunks)} chunks | {len(context)} chars"
+        )
+
+        content = _call_llm(system, user, self.model)
+
+        return InferenceResponse(
+            success=True,
+            content=content,
+            metadata={
+                "query_type":    "macro",
+                "subtype":       req.subtype,
+                "chunks_used":   len(chunks),
+                "context_chars": len(context),
+            }
+        )
+
+    # ── Micro Handler ─────────────────────────────────────────────────────────
+
+    def _handle_micro(self, req: InferenceRequest) -> InferenceResponse:
+        """Handle micro-level queries (function definition, body, consideration)."""
+
+        if not req.function_name:
+            return InferenceResponse(
+                success=False,
+                error="Micro queries require a function_name."
+            )
+
+        # Follow-up path
+        if req.followup and req.previous_response:
+            complete_chunks = self.retriever.retrieve_complete_function(
+                req.function_name, req.class_name, n_results=1
+            )
+            context = self.retriever.build_context(complete_chunks, CONTEXT_MAX_CHARS)
+            system = get_micro_system_prompt(followup=True)
+            user = build_micro_followup_prompt(
+                previous_response=req.previous_response,
+                followup_query=req.query,
+                context=context,
+            )
+        else:
+            # Primary path — retrieve complete function + complete class context
+            complete_func_chunks = self.retriever.retrieve_complete_function(
+                req.function_name, req.class_name, n_results=1
+            )
+            complete_class_chunks = (
+                self.retriever.retrieve_complete_class(req.class_name, n_results=1)
+                if req.class_name else []
+            )
+            all_chunks = complete_func_chunks + complete_class_chunks
+            context = self.retriever.build_context(all_chunks, CONTEXT_MAX_CHARS)
+            system = get_micro_system_prompt(followup=False)
+            user = build_micro_user_prompt(
+                context=context,
+                query=req.query,
+                function_name=req.function_name,
+                class_name=req.class_name,
+            )
+
+        console.print(
+            f"[cyan]→ Micro[/cyan] "
+            f"| fn: {req.function_name} "
+            f"| {len(context)} chars"
+        )
+
+        content = _call_llm(system, user, self.model)
+
+        return InferenceResponse(
+            success=True,
+            content=content,
+            metadata={
+                "query_type": "micro",
+                "function_name": req.function_name,
+                "class_name": req.class_name,
+                "context_chars": len(context),
+                "followup": req.followup,
+            }
+        )
+
+    # ── Cross-Module Handler ──────────────────────────────────────────────────
+
+    def _handle_cross_module(self, req: InferenceRequest) -> InferenceResponse:
+        """Handle cross-module queries (dependency + impact analysis)."""
+
+        if not req.function_name:
+            return InferenceResponse(
+                success=False,
+                error="Cross-module queries require a function_name."
+            )
+
+        # Primary context — the target function
+        primary_chunks = self.retriever.retrieve_by_function(
+            req.function_name, req.class_name, n_results=2
+        )
+        primary_context = self.retriever.build_context(
+            primary_chunks, CONTEXT_MAX_CHARS // 2
+        )
+
+        # Dependency context — callers and callees
+        dep_chunks = self.retriever.retrieve_dependencies(req.function_name)
+        dep_context = self.retriever.build_context(
+            dep_chunks, CONTEXT_MAX_CHARS // 2
+        )
+
+        # Call graph data
+        try:
+            graph    = get_call_graph()
+            calls    = graph.get_calls(req.function_name, req.class_name)
+            called_by = graph.get_called_by(req.function_name, req.class_name)
+            impact   = graph.get_impact(req.function_name, req.class_name, depth=2)
+        except FileNotFoundError:
+            calls, called_by, impact = [], [], {}
+            console.print(
+                "[yellow]⚠ call_graph.json not found — "
+                "proceeding without graph data.[/yellow]"
+            )
+
+        call_graph_payload = build_call_graph_payload(
+            function_name=req.function_name,
+            calls=calls,
+            called_by=called_by,
+            impact=impact,
+        )
+
+        # Follow-up path
+        if req.followup and req.previous_response:
+            system = get_cross_module_system_prompt(followup=True)
+            user   = build_cross_module_followup_prompt(
+                previous_response=req.previous_response,
+                followup_query=req.query,
+                primary_context=primary_context,
+                dependency_context=dep_context,
+                call_graph_data=call_graph_payload,
+            )
+        else:
+            system = get_cross_module_system_prompt(followup=False)
+            user   = build_cross_module_user_prompt(
+                primary_context=primary_context,
+                dependency_context=dep_context,
+                call_graph_data=call_graph_payload,
+                query=req.query,
+                function_name=req.function_name,
+                class_name=req.class_name,
+            )
+
+        console.print(
+            f"[cyan]→ Cross-Module[/cyan] "
+            f"| fn: {req.function_name} "
+            f"| deps: {len(dep_chunks)} "
+            f"| graph nodes: {len(calls) + len(called_by)}"
+        )
+
+        content = _call_llm(system, user, self.model)
+
+        return InferenceResponse(
+            success=True,
+            content=content,
+            metadata={
+                "query_type":    "cross_module",
+                "function_name": req.function_name,
+                "calls":         len(calls),
+                "called_by":     len(called_by),
+                "dep_chunks":    len(dep_chunks),
+                "followup":      req.followup,
+            }
+        )
+
+
+# ── Singleton Access ──────────────────────────────────────────────────────────
+
+_engine_instance: InferenceEngine | None = None
+
+
+def get_engine(model: str = DEFAULT_MODEL) -> InferenceEngine:
+    """
+    Return a singleton InferenceEngine instance.
+    Creates it on first call, reuses on subsequent calls.
+
+    Args:
+        model: OpenRouter model identifier.
+
+    Returns:
+        Shared InferenceEngine instance.
+    """
+    global _engine_instance
+    if _engine_instance is None:
+        _engine_instance = InferenceEngine(model)
+    return _engine_instance
+
+
+# ── Entry Point (manual test) ─────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+    from rich.markdown import Markdown
+
+    console.rule("[bold cyan]Inference Engine — Manual Test[/bold cyan]")
+
+    engine = get_engine()
+
+    # Test micro query
+    console.rule("[cyan]Test — Micro Query[/cyan]")
+    req = InferenceRequest(
+        query_type="micro",
+        query="What does this function do and how do I use it?",
+        function_name=sys.argv[1] if len(sys.argv) > 1 else "parse_file",
+        class_name="",
+    )
+
+    resp = engine.infer(req)
+
+    if resp.success:
+        console.print(Markdown(resp.content))
+        console.print(f"\n[dim]Metadata: {resp.metadata}[/dim]")
+    else:
+        console.print(f"[red]❌ Error: {resp.error}[/red]")

ingest/embed.py

@@ -0,0 +1,529 @@
+"""
+embedder.py
+-----------
+Converts parsed codebase (FileInfo objects) into hybrid chunks and
+stores them in ChromaDB across two collections:
+
+    - class_chunks    : one chunk per class (for macro / cross-module queries)
+    - function_chunks : one chunk per function/method (for micro queries)
+
+Each chunk carries rich metadata so the retriever can filter precisely.
+
+Depends on:
+    - ast_parser.parse_codebase() → list[FileInfo]
+    - chromadb
+    - sentence-transformers (local embedding, no API needed)
+
+Install:
+    pip install chromadb sentence-transformers rich
+"""
+
+import json
+import hashlib
+from pathlib import Path
+
+from pinecone import Pinecone, ServerlessSpec
+from sentence_transformers import SentenceTransformer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, BarColumn, TextColumn
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+from config.config import PINECONE_API_KEY, PINECONE_INDEX, EMBEDDING_DIM
+from ingest.parse_ast import parse_codebase, FileInfo, ClassInfo, FunctionInfo
+
+console = Console()
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+EMBEDDING_MODEL  = "all-MiniLM-L6-v2"    # fast, lightweight, good quality
+CLASS_COLLECTION    = "class_chunks"
+FUNCTION_COLLECTION = "function_chunks"
+COMPLETE_COLLECTION = "complete_chunks"
+
+
+# ── Embedding Model ───────────────────────────────────────────────────────────
+
+def load_embedding_model() -> SentenceTransformer:
+    """Load the sentence transformer embedding model."""
+    with console.status("[bold cyan]Loading embedding model...[/bold cyan]"):
+        model = SentenceTransformer(EMBEDDING_MODEL)
+    console.print(f"[green]✔[/green] Embedding model loaded: [cyan]{EMBEDDING_MODEL}[/cyan]")
+    return model
+
+
+# ── ChromaDB Client ───────────────────────────────────────────────────────────
+
+def get_pinecone_index():
+    """Return a Pinecone index, creating it if it does not exist."""
+    pc = Pinecone(api_key=PINECONE_API_KEY)
+    existing = [i.name for i in pc.list_indexes()]
+    if PINECONE_INDEX not in existing:
+        pc.create_index(
+            name=PINECONE_INDEX,
+            dimension=EMBEDDING_DIM,
+            metric="cosine",
+            spec=ServerlessSpec(cloud="aws", region="us-east-1"),
+        )
+    return pc.Index(PINECONE_INDEX)
+
+
+# ── Chunk Builders ────────────────────────────────────────────────────────────
+
+def _make_id(text: str) -> str:
+    """Generate a stable unique ID from chunk text."""
+    return hashlib.md5(text.encode()).hexdigest()
+
+
+def build_class_chunk(cls: ClassInfo, file_info: FileInfo) -> dict:
+    """
+    Build a class-level chunk document.
+    Contains: class name, bases, docstring, all method signatures.
+    """
+    method_signatures = []
+    for m in cls.methods:
+        params = ", ".join(
+            f"{p.name}: {p.annotation}" if p.annotation else p.name
+            for p in m.parameters
+        )
+        ret = f" -> {m.return_type}" if m.return_type else ""
+        method_signatures.append(f"  def {m.name}({params}){ret}")
+
+    methods_block = "\n".join(method_signatures) if method_signatures else "  # no methods"
+    bases_str = ", ".join(cls.bases) if cls.bases else "object"
+    docstring = cls.docstring or "No docstring provided."
+
+    text = (
+        f"Class: {cls.name}\n"
+        f"Inherits: {bases_str}\n"
+        f"Module: {file_info.module}\n"
+        f"File: {file_info.relative}\n"
+        f"Docstring: {docstring}\n"
+        f"Methods:\n{methods_block}"
+    )
+
+    metadata = {
+        "type":       "class",
+        "name":       cls.name,
+        "module":     file_info.module,
+        "file":       file_info.relative,
+        "bases":      json.dumps(cls.bases),
+        "methods":    json.dumps([m.name for m in cls.methods]),
+        "lineno":     cls.lineno,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+
+def build_function_chunk(func: FunctionInfo,
+                          file_info: FileInfo,
+                          class_name: str | None = None,
+                          class_docstring: str | None = None) -> dict:
+    """
+    Build a function/method-level chunk document.
+    Carries class context as metadata so micro queries stay grounded.
+    """
+    params = ", ".join(
+        f"{p.name}: {p.annotation}" if p.annotation else p.name
+        for p in func.parameters
+    )
+    ret = f" -> {func.return_type}" if func.return_type else ""
+    signature = f"def {func.name}({params}){ret}"
+
+    docstring  = func.docstring or "No docstring provided."
+    calls_str  = ", ".join(func.calls[:15]) if func.calls else "none"
+    class_ctx  = (
+        f"Class: {class_name}\nClass purpose: {class_docstring or 'N/A'}\n"
+        if class_name else "Scope: top-level function\n"
+    )
+
+    text = (
+        f"{class_ctx}"
+        f"Function: {func.name}\n"
+        f"Module: {file_info.module}\n"
+        f"File: {file_info.relative}\n"
+        f"Signature: {signature}\n"
+        f"Docstring: {docstring}\n"
+        f"Calls: {calls_str}"
+    )
+
+    metadata = {
+        "type":            "function",
+        "name":            func.name,
+        "module":          file_info.module,
+        "file":            file_info.relative,
+        "class_name":      class_name or "",
+        "return_type":     func.return_type or "",
+        "parameters":      json.dumps([p.name for p in func.parameters]),
+        "calls":           json.dumps(func.calls[:15]),
+        "is_method":       str(func.is_method),
+        "lineno":          func.lineno,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+def build_module_chunk(file_info: FileInfo) -> dict:
+    """
+    Build a module-level chunk for files that contain no classes or functions.
+    Captures imports and docstring as the indexable content.
+    """
+    imports_str = ", ".join(file_info.imports) if file_info.imports else "none"
+    docstring = file_info.docstring or "No module docstring."
+
+    text = (
+        f"Module: {file_info.module}\n"
+        f"File: {file_info.relative}\n"
+        f"Docstring: {docstring}\n"
+        f"Imports: {imports_str}\n"
+        f"Note: This file contains only module-level statements."
+    )
+
+    metadata = {
+        "type":       "module",
+        "name":       Path(file_info.relative).stem,
+        "module":     file_info.module,
+        "file":       file_info.relative,
+        "class_name": "",
+        "return_type": "",
+        "parameters": "[]",
+        "calls":      "[]",
+        "is_method":  "False",
+        "lineno":     0,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+def build_complete_function_chunk(func: FunctionInfo,
+                                   file_info: FileInfo,
+                                   class_name: str | None = None,
+                                   class_docstring: str | None = None) -> dict:
+    """
+    Build a complete function chunk including full source code.
+    Used for edge case analysis and usage example generation.
+    """
+    params = ", ".join(
+        f"{p.name}: {p.annotation}" if p.annotation else p.name
+        for p in func.parameters
+    )
+    ret = f" -> {func.return_type}" if func.return_type else ""
+    signature = f"def {func.name}({params}){ret}"
+
+    docstring = func.docstring or "No docstring provided."
+    calls_str = ", ".join(func.calls[:15]) if func.calls else "none"
+    class_ctx = (
+        f"Class: {class_name}\nClass purpose: {class_docstring or 'N/A'}\n"
+        if class_name else "Scope: top-level function\n"
+    )
+    source_block = func.source if func.source else "Source not available."
+
+    text = (
+        f"{class_ctx}"
+        f"Function: {func.name}\n"
+        f"Module: {file_info.module}\n"
+        f"File: {file_info.relative}\n"
+        f"Signature: {signature}\n"
+        f"Docstring: {docstring}\n"
+        f"Calls: {calls_str}\n"
+        f"Source Code:\n{source_block}"
+    )
+
+    metadata = {
+        "type":        "complete_function",
+        "name":        func.name,
+        "module":      file_info.module,
+        "file":        file_info.relative,
+        "class_name":  class_name or "",
+        "return_type": func.return_type or "",
+        "parameters":  json.dumps([p.name for p in func.parameters]),
+        "calls":       json.dumps(func.calls[:15]),
+        "is_method":   str(func.is_method),
+        "lineno":      func.lineno,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+
+def build_complete_class_chunk(cls: ClassInfo, file_info: FileInfo) -> dict:
+    """
+    Build a complete class chunk including full source code.
+    Used for class-level deep queries.
+    """
+    bases_str = ", ".join(cls.bases) if cls.bases else "object"
+    docstring = cls.docstring or "No docstring provided."
+    source_block = cls.source if cls.source else "Source not available."
+
+    text = (
+        f"Class: {cls.name}\n"
+        f"Inherits: {bases_str}\n"
+        f"Module: {file_info.module}\n"
+        f"File: {file_info.relative}\n"
+        f"Docstring: {docstring}\n"
+        f"Source Code:\n{source_block}"
+    )
+
+    metadata = {
+        "type":    "complete_class",
+        "name":    cls.name,
+        "module":  file_info.module,
+        "file":    file_info.relative,
+        "bases":   json.dumps(cls.bases),
+        "methods": json.dumps([m.name for m in cls.methods]),
+        "lineno":  cls.lineno,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+
+def build_file_chunk(file_info: FileInfo) -> dict:
+    """
+    Build a file-level chunk containing the entire source of a file.
+    Used for file-wide queries.
+    """
+    try:
+        source_block = Path(file_info.path).read_text(encoding="utf-8", errors="ignore")
+    except Exception:
+        source_block = "Source not available."
+
+    docstring = file_info.docstring or "No module docstring."
+    imports_str = ", ".join(file_info.imports) if file_info.imports else "none"
+
+    text = (
+        f"File: {file_info.relative}\n"
+        f"Module: {file_info.module}\n"
+        f"Docstring: {docstring}\n"
+        f"Imports: {imports_str}\n"
+        f"Source Code:\n{source_block}"
+    )
+
+    metadata = {
+        "type":        "file",
+        "name":        Path(file_info.relative).stem,
+        "module":      file_info.module,
+        "file":        file_info.relative,
+        "class_name":  "",
+        "return_type": "",
+        "parameters":  "[]",
+        "calls":       "[]",
+        "is_method":   "False",
+        "lineno":      0,
+    }
+
+    return {"id": _make_id(text), "text": text, "metadata": metadata}
+
+
+# ── Embedding & Upserting ─────────────────────────────────────────────────────
+
+def _upsert_batch(index, chunks: list[dict], model: SentenceTransformer, namespace: str) -> None:
+    """Embed and upsert a list of chunks into a Pinecone namespace."""
+    if not chunks:
+        return
+
+    texts     = [c["text"]     for c in chunks]
+    ids       = [c["id"]       for c in chunks]
+    metadatas = [c["metadata"] for c in chunks]
+
+    embeddings = model.encode(texts, show_progress_bar=False).tolist()
+
+    vectors = [
+        {"id": vid, "values": vec, "metadata": {**meta, "text": txt}}
+        for vid, vec, meta, txt in zip(ids, embeddings, metadatas, texts)
+    ]
+
+    index.upsert(vectors=vectors, namespace=namespace)
+
+
+# ── Main Embed Pipeline ───────────────────────────────────────────────────────
+
+def embed_codebase(root_path: str) -> None:
+    """
+    Full pipeline:
+        1. Parse codebase via ast_parser
+        2. Build hybrid chunks (class + function level)
+        3. Embed with sentence-transformers
+        4. Store in ChromaDB (two collections)
+
+    Args:
+        root_path: Absolute path to the monolithic codebase root.
+    """
+    console.rule("[bold cyan]Codebase Oracle — Embedder[/bold cyan]")
+
+    # Step 1 — Parse
+    console.print(f"\n[bold]📂 Root:[/bold] {root_path}\n")
+    parsed_files: list[FileInfo] = parse_codebase(root_path)
+
+    if not parsed_files:
+        console.print("[yellow]⚠ No Python files parsed. Exiting.[/yellow]")
+        return
+
+    # Step 2 — Build chunks
+    class_chunks:    list[dict] = []
+    function_chunks: list[dict] = []
+
+    for file_info in parsed_files:
+        # Class-level chunks
+        for cls in file_info.classes:
+            class_chunks.append(build_class_chunk(cls, file_info))
+
+            # Method-level chunks (carry class context)
+            for method in cls.methods:
+                function_chunks.append(build_function_chunk(
+                    method, file_info,
+                    class_name=cls.name,
+                    class_docstring=cls.docstring,
+                ))
+
+        # Top-level function chunks
+        for func in file_info.functions:
+            function_chunks.append(build_function_chunk(func, file_info))
+
+        # Module-level chunk for files with no classes and no functions
+        if not file_info.classes and not file_info.functions:
+            function_chunks.append(build_module_chunk(file_info))
+
+    complete_chunks: list[dict] = []
+
+    for file_info in parsed_files:
+        complete_chunks.append(build_file_chunk(file_info))
+        for cls in file_info.classes:
+            complete_chunks.append(build_complete_class_chunk(cls, file_info))
+            for method in cls.methods:
+                complete_chunks.append(build_complete_function_chunk(
+                    method, file_info,
+                    class_name=cls.name,
+                    class_docstring=cls.docstring,
+                ))
+        for func in file_info.functions:
+            complete_chunks.append(build_complete_function_chunk(func, file_info))
+
+    console.print(
+        f"[green]✔[/green] Chunks built: "
+        f"[magenta]{len(class_chunks)}[/magenta] class chunks · "
+        f"[cyan]{len(function_chunks)}[/cyan] function chunks · "
+        f"[yellow]{len(complete_chunks)}[/yellow] complete chunks\n"
+    )
+
+    # Step 3 — Load model
+    model = load_embedding_model()
+
+    # Step 4 — Pinecone
+    index = get_pinecone_index()
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("{task.completed}/{task.total}"),
+        console=console,
+    ) as progress:
+
+        # Embed class chunks in batches of 32
+        BATCH = 32
+        task1 = progress.add_task(
+            "[magenta]Embedding class chunks...", total=len(class_chunks)
+        )
+        for i in range(0, len(class_chunks), BATCH):
+            batch = class_chunks[i:i + BATCH]
+            _upsert_batch(index, batch, model, CLASS_COLLECTION)
+            progress.advance(task1, len(batch))
+
+        task2 = progress.add_task(
+            "[cyan]Embedding function chunks...", total=len(function_chunks)
+        )
+        for i in range(0, len(function_chunks), BATCH):
+            batch = function_chunks[i:i + BATCH]
+            _upsert_batch(index, batch, model, FUNCTION_COLLECTION)
+            progress.advance(task2, len(batch))
+
+        task3 = progress.add_task(
+            "[yellow]Embedding complete chunks...", total=len(complete_chunks)
+        )
+        for i in range(0, len(complete_chunks), BATCH):
+            batch = complete_chunks[i:i + BATCH]
+            _upsert_batch(index, batch, model, COMPLETE_COLLECTION)
+            progress.advance(task3, len(batch))
+
+    # Step 5 — Summary
+    _render_embed_summary(root_path, class_chunks, function_chunks, complete_chunks)
+
+def _render_embed_summary(root_path: str,
+                              class_chunks: list[dict],
+                              function_chunks: list[dict],
+                              complete_chunks: list[dict]) -> None:
+    """Render a rich summary panel after embedding."""
+    table = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    table.add_column(style="dim")
+    table.add_column(style="bold white")
+
+    table.add_row("Codebase",          root_path)
+    table.add_row("Embedding model",   EMBEDDING_MODEL)
+    table.add_row("Class chunks", str(len(class_chunks)))
+    table.add_row("Function chunks", str(len(function_chunks)))
+    table.add_row("Complete chunks", str(len(complete_chunks)))
+    table.add_row("Total chunks", str(len(class_chunks) + len(function_chunks) + len(complete_chunks)))
+    table.add_row("Collections", f"{CLASS_COLLECTION}, {FUNCTION_COLLECTION}, {COMPLETE_COLLECTION}")
+    table.add_row("Status",            "[bold green]✔ Indexing complete[/bold green]")
+
+    console.print(Panel(table, title="[bold cyan]Embedding Summary[/bold cyan]",
+                        border_style="cyan"))
+    console.print("\n[bold green]✔ Codebase indexed. Ready for queries.[/bold green]\n")
+
+
+# ── Query Helper (for retriever.py later) ────────────────────────────────────
+
+def query_chunks(query: str,
+                 collection_name: str,
+                 model: SentenceTransformer,
+                 n_results: int = 5,
+                 filters: dict | None = None) -> list[dict]:
+    """
+    Query a Pinecone namespace and return top-n matching chunks.
+
+    Args:
+        query:           Natural language query string.
+        collection_name: Namespace — CLASS_COLLECTION, FUNCTION_COLLECTION, or COMPLETE_COLLECTION.
+        model:           Loaded SentenceTransformer model.
+        n_results:       Number of results to return.
+        filters:         Optional Pinecone metadata filters.
+
+    Returns:
+        List of dicts with keys: text, metadata, distance.
+    """
+    index     = get_pinecone_index()
+    embedding = model.encode([query]).tolist()[0]
+
+    kwargs: dict = {
+        "vector":          embedding,
+        "top_k":           n_results,
+        "namespace":       collection_name,
+        "include_metadata": True,
+    }
+    if filters:
+        kwargs["filter"] = filters
+
+    results = index.query(**kwargs)
+
+    output = []
+    for match in results["matches"]:
+        meta = dict(match["metadata"])
+        text = meta.pop("text", "")
+        output.append({
+            "text":     text,
+            "metadata": meta,
+            "distance": 1 - match["score"],
+        })
+
+    return output
+
+
+# ── Entry Point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+
+    try:
+        embed_codebase(path)
+    except (FileNotFoundError, NotADirectoryError) as e:
+        console.print(f"[red]❌ {e}[/red]")
+        sys.exit(1)

ingest/parse_ast.py

@@ -0,0 +1,413 @@
+"""
+ast_parser.py
+-------------
+Parses Python source files using the built-in `ast` module to extract
+structured metadata: classes, functions, parameters, return types,
+docstrings, and call relationships (for cross-module analysis).
+
+Uses `rich` for all terminal output.
+Depends on file_walker.walk_codebase() for file discovery.
+"""
+
+import ast
+import sys
+from pathlib import Path
+from dataclasses import dataclass, field
+
+from rich.console import Console
+from rich.tree import Tree
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+# Import from file_walker (must be in same directory or on PYTHONPATH)
+from ingest.walk_files import walk_codebase, group_by_module
+
+console = Console()
+
+
+# ── Data Models ───────────────────────────────────────────────────────────────
+
+@dataclass
+class ParameterInfo:
+    name: str
+    annotation: str | None = None
+    default: str | None = None
+
+
+@dataclass
+class FunctionInfo:
+    name: str
+    parameters: list[ParameterInfo] = field(default_factory=list)
+    return_type: str | None = None
+    docstring: str | None = None
+    calls: list[str] = field(default_factory=list)        # functions this calls
+    lineno: int = 0
+    is_method: bool = False
+    source: str | None = None
+
+
+@dataclass
+class ClassInfo:
+    name: str
+    bases: list[str] = field(default_factory=list)
+    docstring: str | None = None
+    methods: list[FunctionInfo] = field(default_factory=list)
+    lineno: int = 0
+    source: str | None = None
+
+
+@dataclass
+class FileInfo:
+    path: str
+    relative: str
+    module: str
+    classes: list[ClassInfo] = field(default_factory=list)
+    functions: list[FunctionInfo] = field(default_factory=list)   # top-level
+    imports: list[str] = field(default_factory=list)
+    docstring: str | None = None
+
+
+# ── AST Helpers ───────────────────────────────────────────────────────────────
+
+def _annotation_to_str(node) -> str | None:
+    """Convert an AST annotation node to a readable string."""
+    if node is None:
+        return None
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return None
+
+
+def _extract_calls(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    """Extract all function/method call names from a function body."""
+    calls = []
+    for node in ast.walk(func_node):
+        if isinstance(node, ast.Call):
+            if isinstance(node.func, ast.Name):
+                calls.append(node.func.id)
+            elif isinstance(node.func, ast.Attribute):
+                calls.append(f"{ast.unparse(node.func.value)}.{node.func.attr}")
+    return list(dict.fromkeys(calls))  # deduplicate, preserve order
+
+def _parse_function(node: ast.FunctionDef | ast.AsyncFunctionDef,
+                        is_method: bool = False,
+                        raw_source: str | None = None) -> FunctionInfo:
+    """Parse a function or method AST node into a FunctionInfo."""
+    params = []
+
+    args = node.args
+    all_args = args.posonlyargs + args.args + args.kwonlyargs
+    defaults_offset = len(all_args) - len(args.defaults)
+
+    for i, arg in enumerate(all_args):
+        if is_method and arg.arg == "self":
+            continue
+        default_val = None
+        default_idx = i - defaults_offset
+        if default_idx >= 0 and default_idx < len(args.defaults):
+            try:
+                default_val = ast.unparse(args.defaults[default_idx])
+            except Exception:
+                default_val = "..."
+
+        params.append(ParameterInfo(
+            name=arg.arg,
+            annotation=_annotation_to_str(arg.annotation),
+            default=default_val,
+        ))
+
+    # *args
+    if args.vararg:
+        params.append(ParameterInfo(
+            name=f"*{args.vararg.arg}",
+            annotation=_annotation_to_str(args.vararg.annotation),
+        ))
+
+    # **kwargs
+    if args.kwarg:
+        params.append(ParameterInfo(
+            name=f"**{args.kwarg.arg}",
+            annotation=_annotation_to_str(args.kwarg.annotation),
+        ))
+
+    source_segment = None
+    if raw_source is not None:
+        source_segment = ast.get_source_segment(raw_source, node)
+
+    return FunctionInfo(
+        name=node.name,
+        parameters=params,
+        return_type=_annotation_to_str(node.returns),
+        docstring=ast.get_docstring(node),
+        calls=_extract_calls(node),
+        lineno=node.lineno,
+        is_method=is_method,
+        source=source_segment,
+    )
+
+def _parse_class(node: ast.ClassDef, raw_source: str | None = None) -> ClassInfo:
+    """Parse a class AST node into a ClassInfo."""
+    bases = []
+    for base in node.bases:
+        try:
+            bases.append(ast.unparse(base))
+        except Exception:
+            pass
+
+    methods = []
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            methods.append(_parse_function(item, is_method=True, raw_source=raw_source))
+
+    class_source = None
+    if raw_source is not None:
+        class_source = ast.get_source_segment(raw_source, node)
+
+    return ClassInfo(
+        name=node.name,
+        bases=bases,
+        docstring=ast.get_docstring(node),
+        methods=methods,
+        lineno=node.lineno,
+        source=class_source,
+    )
+
+
+def parse_file(file_meta: dict) -> FileInfo | None:
+    """
+    Parse a single Python source file and return a FileInfo.
+    Returns None if the file cannot be parsed (syntax errors, encoding issues).
+
+    Args:
+        file_meta: A dict from walk_codebase() with keys: path, relative, module.
+    """
+    if file_meta["extension"] != ".py":
+        return None  # AST parser only supports Python for now
+
+    try:
+        source = Path(file_meta["path"]).read_text(encoding="utf-8", errors="ignore")
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        console.print(f"[yellow]⚠ Syntax error in {file_meta['relative']}: {e}[/yellow]")
+        return None
+    except Exception as e:
+        console.print(f"[yellow]⚠ Could not parse {file_meta['relative']}: {e}[/yellow]")
+        return None
+
+    info = FileInfo(
+        path=file_meta["path"],
+        relative=file_meta["relative"],
+        module=file_meta["module"],
+        docstring=ast.get_docstring(tree),
+    )
+
+    # Extract imports
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                info.imports.append(alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            mod = node.module or ""
+            for alias in node.names:
+                info.imports.append(f"{mod}.{alias.name}")
+
+    # Extract top-level classes and functions
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            info.classes.append(_parse_class(node, raw_source=source))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            info.functions.append(_parse_function(node, is_method=False, raw_source=source))
+
+    return info
+
+
+def parse_codebase(root_path: str) -> list[FileInfo]:
+    """
+    Walk and parse an entire codebase, returning FileInfo for every
+    parseable Python file.
+
+    Args:
+        root_path: Absolute path to the codebase root.
+
+    Returns:
+        List of FileInfo objects (one per parsed file).
+    """
+    files = walk_codebase(root_path)
+    py_files = [f for f in files if f["extension"] == ".py"]
+
+    results = []
+    with console.status(f"[bold cyan]Parsing {len(py_files)} Python files...[/bold cyan]"):
+        for f in py_files:
+            info = parse_file(f)
+            if info:
+                results.append(info)
+
+    return results
+
+
+# ── Rich Renderers ────────────────────────────────────────────────────────────
+
+def render_file_tree(parsed_files: list[FileInfo]) -> None:
+    """Render a rich tree of the parsed codebase structure."""
+    root_tree = Tree(
+        "[bold bright_cyan]📦 Codebase Structure[/bold bright_cyan]",
+        guide_style="dim cyan",
+    )
+
+    # Group by module
+    modules: dict[str, list[FileInfo]] = {}
+    for f in parsed_files:
+        modules.setdefault(f.module, []).append(f)
+
+    for module_name, module_files in sorted(modules.items()):
+        module_branch = root_tree.add(
+            f"[bold yellow]📁 {module_name}[/bold yellow]"
+        )
+        for file_info in module_files:
+            file_label = f"[green]{Path(file_info.relative).name}[/green]"
+            file_branch = module_branch.add(file_label)
+
+            for cls in file_info.classes:
+                cls_branch = file_branch.add(
+                    f"[bold magenta]🔷 {cls.name}[/bold magenta]"
+                )
+                for method in cls.methods:
+                    cls_branch.add(f"[cyan]  ƒ {method.name}()[/cyan]")
+
+            for func in file_info.functions:
+                file_branch.add(f"[blue]  ƒ {func.name}()[/blue]")
+
+    console.print(root_tree)
+
+
+def render_function(func: FunctionInfo, class_name: str | None = None) -> None:
+    """Render a detailed view of a single function/method."""
+    title = f"{'Method' if func.is_method else 'Function'}: "
+    title += f"{class_name}.{func.name}" if class_name else func.name
+
+    # Signature table
+    param_table = Table(
+        "Parameter", "Type", "Default",
+        box=box.SIMPLE_HEAD,
+        style="dim",
+        header_style="bold cyan",
+        show_edge=False,
+    )
+    for p in func.parameters:
+        param_table.add_row(
+            p.name,
+            p.annotation or "[dim]any[/dim]",
+            p.default or "[dim]—[/dim]",
+        )
+
+    return_str = func.return_type or "[dim]None / untyped[/dim]"
+    doc_str = func.docstring or "[dim]No docstring.[/dim]"
+    calls_str = ", ".join(func.calls[:10]) if func.calls else "[dim]none[/dim]"
+
+    content = Text()
+    content.append("📄 Docstring\n", style="bold")
+    content.append(f"{doc_str}\n\n")
+    content.append("↩  Return type\n", style="bold")
+    content.append(f"{return_str}\n\n")
+    content.append("📞 Calls\n", style="bold")
+    content.append(calls_str)
+
+    console.print(Panel(content, title=f"[bold white]{title}[/bold white]",
+                        border_style="cyan"))
+    if func.parameters:
+        console.print(param_table)
+    else:
+        console.print("  [dim]No parameters.[/dim]\n")
+
+
+def render_class(cls: ClassInfo) -> None:
+    """Render a detailed view of a class and all its methods."""
+    bases_str = ", ".join(cls.bases) if cls.bases else "object"
+    doc_str = cls.docstring or "[dim]No docstring.[/dim]"
+
+    header = Text()
+    header.append(f"class {cls.name}", style="bold magenta")
+    header.append(f"({bases_str})", style="dim")
+
+    console.print(Panel(
+        f"[bold]Docstring:[/bold]\n{doc_str}",
+        title=str(header),
+        border_style="magenta",
+    ))
+
+    for method in cls.methods:
+        render_function(method, class_name=cls.name)
+
+
+def render_summary(parsed_files: list[FileInfo]) -> None:
+    """Render a high-level summary table of the parsed codebase."""
+    table = Table(
+        "Module", "File", "Classes", "Functions", "Imports",
+        box=box.ROUNDED,
+        header_style="bold bright_cyan",
+        border_style="cyan",
+        show_lines=True,
+    )
+
+    for f in parsed_files:
+        table.add_row(
+            f.module,
+            Path(f.relative).name,
+            str(len(f.classes)),
+            str(len(f.functions)),
+            str(len(f.imports)),
+        )
+
+    total_classes   = sum(len(f.classes)   for f in parsed_files)
+    total_functions = sum(len(f.functions) for f in parsed_files)
+    total_methods   = sum(len(c.methods)   for f in parsed_files for c in f.classes)
+
+    console.print(table)
+    console.print(
+        f"\n[bold]Totals:[/bold] "
+        f"[cyan]{len(parsed_files)}[/cyan] files · "
+        f"[magenta]{total_classes}[/magenta] classes · "
+        f"[blue]{total_functions}[/blue] top-level functions · "
+        f"[green]{total_methods}[/green] methods\n"
+    )
+
+
+# ── Entry Point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+
+    console.print(f"\n[bold cyan]🔍 Parsing codebase:[/bold cyan] {path}\n")
+
+    try:
+        parsed = parse_codebase(path)
+    except (FileNotFoundError, NotADirectoryError) as e:
+        console.print(f"[red]❌ Error: {e}[/red]")
+        sys.exit(1)
+
+    if not parsed:
+        console.print("[yellow]No Python files found or parsed.[/yellow]")
+        sys.exit(0)
+
+    console.rule("[bold cyan]Summary[/bold cyan]")
+    render_summary(parsed)
+
+    console.rule("[bold cyan]Codebase Tree[/bold cyan]")
+    render_file_tree(parsed)
+
+    # Demo: render first class found
+    for f in parsed:
+        if f.classes:
+            console.rule(f"[bold cyan]Sample Class — {f.classes[0].name}[/bold cyan]")
+            render_class(f.classes[0])
+            break
+
+    # Demo: render first top-level function found
+    for f in parsed:
+        if f.functions:
+            console.rule(f"[bold cyan]Sample Function — {f.functions[0].name}[/bold cyan]")
+            render_function(f.functions[0])
+            break

ingest/walk_files.py

@@ -0,0 +1,185 @@
+"""
+file_walker.py
+--------------
+Recursively walks a monolithic codebase directory and collects
+all relevant source code files, filtered by supported extensions.
+"""
+
+import os
+from pathlib import Path
+
+# Supported source file extensions
+SUPPORTED_EXTENSIONS = {
+    ".py",    # Python
+    ".java",  # Java
+    ".js",    # JavaScript
+    ".ts",    # TypeScript
+    ".cpp",   # C++
+    ".c",     # C
+    ".cs",    # C#
+    ".go",    # Go
+    ".rb",    # Ruby
+    ".php",   # PHP
+    ".rs",    # Rust
+    ".kt",    # Kotlin
+    ".swift", # Swift
+}
+
+# Directories to always skip
+EXCLUDED_DIRS = {
+    ".devcontainer"
+    "chroma_db",
+    ".github",
+    ".git",
+    "__pycache__",
+    ".git",
+    ".svn",
+    "node_modules",
+    "venv",
+    ".venv",
+    "env",
+    ".env",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+    "migrations",
+    ".mypy_cache",
+    ".pytest_cache",
+}
+
+
+def walk_codebase(root_path: str) -> list[dict]:
+    """
+    Recursively walk the codebase from root_path and return
+    a list of file metadata dicts for all supported source files.
+
+    Args:
+        root_path: Absolute path to the root of the codebase.
+
+    Returns:
+        List of dicts, each containing:
+            - path       : absolute file path (str)
+            - relative   : path relative to root (str)
+            - extension  : file extension (str)
+            - size_bytes : file size in bytes (int)
+            - module     : top-level module/package name (str)
+    """
+    root = Path(root_path).resolve()
+
+    if not root.exists():
+        raise FileNotFoundError(f"Path does not exist: {root}")
+
+    if not root.is_dir():
+        raise NotADirectoryError(f"Path is not a directory: {root}")
+
+    collected = []
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune excluded directories in-place so os.walk skips them
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in EXCLUDED_DIRS and not d.startswith(".")
+        ]
+
+        for filename in filenames:
+            ext = Path(filename).suffix.lower()
+
+            if ext not in SUPPORTED_EXTENSIONS:
+                continue
+
+            abs_path = Path(dirpath) / filename
+            relative = abs_path.relative_to(root)
+
+            # Derive top-level module name (first directory under root)
+            parts = relative.parts
+            module = parts[0] if len(parts) > 1 else "<root>"
+
+            collected.append({
+                "path":       str(abs_path),
+                "relative":   str(relative),
+                "extension":  ext,
+                "size_bytes": abs_path.stat().st_size,
+                "module":     module,
+            })
+
+    # Sort by relative path for deterministic ordering
+    collected.sort(key=lambda f: f["relative"])
+
+    return collected
+
+
+def group_by_module(files: list[dict]) -> dict[str, list[dict]]:
+    """
+    Group a flat list of file dicts by their top-level module name.
+
+    Args:
+        files: Output of walk_codebase().
+
+    Returns:
+        Dict mapping module name → list of file dicts.
+    """
+    grouped: dict[str, list[dict]] = {}
+
+    for f in files:
+        module = f["module"]
+        grouped.setdefault(module, []).append(f)
+
+    return grouped
+
+
+def summarize(files: list[dict]) -> dict:
+    """
+    Return a quick summary of the walked codebase.
+
+    Args:
+        files: Output of walk_codebase().
+
+    Returns:
+        Dict with total_files, total_size_kb, modules, extensions breakdown.
+    """
+    from collections import Counter
+
+    ext_counts   = Counter(f["extension"] for f in files)
+    module_counts = Counter(f["module"]    for f in files)
+    total_size   = sum(f["size_bytes"] for f in files)
+
+    return {
+        "total_files":    len(files),
+        "total_size_kb":  round(total_size / 1024, 2),
+        "modules":        dict(module_counts),
+        "extensions":     dict(ext_counts),
+    }
+
+
+# ── Quick test when run directly ─────────────────────────────────────────────
+if __name__ == "__main__":
+    import sys
+    import json
+
+    path = sys.argv[1] if len(sys.argv) > 1 else "."
+
+    print(f"\n📂 Walking codebase: {path}\n")
+
+    try:
+        files = walk_codebase(path)
+    except (FileNotFoundError, NotADirectoryError) as e:
+        print(f"❌ Error: {e}")
+        sys.exit(1)
+
+    summary = summarize(files)
+
+    print(f"✅ Found {summary['total_files']} source files "
+          f"({summary['total_size_kb']} KB total)\n")
+
+    print("📦 By module:")
+    for module, count in summary["modules"].items():
+        print(f"   {module:<30} {count} files")
+
+    print("\n🔤 By extension:")
+    for ext, count in summary["extensions"].items():
+        print(f"   {ext:<10} {count} files")
+
+    print("\n📄 All files:")
+    for f in files:
+        print(f"   {f['relative']}")

main.py

@@ -0,0 +1,473 @@
+"""
+main.py
+-------
+FastAPI backend for the Codebase Oracle system.
+This is the HTTP layer — thin wrapper around inference.py.
+
+Endpoints:
+    POST /index          — ingest + embed a codebase from given path
+    POST /query          — run a query (macro / micro / cross_module)
+    GET  /status         — check if a codebase is indexed and ready
+    GET  /tree           — return parsed codebase tree for UI sidebar
+    GET  /health         — simple health check
+
+Run:
+    uvicorn main:app --reload --port 8000
+
+Depends on:
+    - inference.py
+    - embedder.py
+    - call_graph.py
+    - ast_parser.py
+    - vector_store.py
+    - fastapi, uvicorn, pydantic, python-dotenv
+"""
+
+import os
+from contextlib import asynccontextmanager
+from dotenv import load_dotenv
+
+import tempfile
+import zipfile
+import shutil
+from fastapi import FastAPI, HTTPException, UploadFile, File
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+from rich.console import Console
+
+from inference.inference import get_engine, InferenceRequest
+from ingest.embed import embed_codebase
+from store.call_graph import build_and_save, get_call_graph, CALL_GRAPH_PATH
+from ingest.parse_ast import parse_codebase
+from store.vector_store import get_vector_store
+
+load_dotenv()
+
+console = Console()
+
+# ── App Lifespan ──────────────────────────────────────────────────────────────
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize shared resources on startup."""
+    console.rule("[bold cyan]Codebase Oracle — Starting[/bold cyan]")
+    # Pre-warm the inference engine (loads embedding model once)
+    get_engine()
+    console.print("[green]✔[/green] Server ready.\n")
+    yield
+    console.print("[dim]Server shutting down.[/dim]")
+
+
+# ── App ───────────────────────────────────────────────────────────────────────
+
+app = FastAPI(
+    title="Codebase Oracle",
+    description="AI-powered monolithic codebase comprehension system.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# Allow UI (served from same origin or localhost dev)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Serve UI static files
+UI_DIR = os.path.join(os.path.dirname(__file__), "ui")
+if os.path.exists(UI_DIR):
+    app.mount("/ui", StaticFiles(directory=UI_DIR), name="ui")
+    app.mount("/static", StaticFiles(directory=os.path.join(UI_DIR, "static")), name="static")
+
+
+# ── Pydantic Request / Response Models ────────────────────────────────────────
+
+class IndexRequest(BaseModel):
+    """Request body for POST /index"""
+    root_path: str = Field(
+        ...,
+        description="Absolute path to the monolithic codebase root directory.",
+        example="/home/user/projects/my-django-app"
+    )
+
+
+class QueryRequest(BaseModel):
+    """Request body for POST /query"""
+    query_type: str = Field(
+        ...,
+        description="One of: 'macro', 'micro', 'cross_module'",
+        example="micro"
+    )
+    query: str = Field(
+        ...,
+        description="Natural language developer query.",
+        example="What does process_payment do and how do I use it?"
+    )
+    subtype: str = Field(
+        default="",
+        description="Macro subtype: 'overall_architecture' | 'module_responsibility' | 'data_flow'",
+        example="overall_architecture"
+    )
+    function_name: str = Field(
+        default="",
+        description="Target function/method name for micro and cross_module queries.",
+        example="process_payment"
+    )
+    class_name: str = Field(
+        default="",
+        description="Target class name if function is a method.",
+        example="PaymentProcessor"
+    )
+    module_name: str = Field(
+        default="",
+        description="Target module name for macro module_responsibility queries.",
+        example="payments"
+    )
+    followup: bool = Field(
+        default=False,
+        description="True if this is a follow-up to a previous response."
+    )
+    previous_response: str = Field(
+        default="",
+        description="Previous LLM response for follow-up context."
+    )
+
+
+class IndexResponse(BaseModel):
+    success:       bool
+    message:       str
+    class_chunks:  int = 0
+    function_chunks: int = 0
+    total_chunks:  int = 0
+    graph_nodes:   int = 0
+    graph_edges:   int = 0
+
+
+class QueryResponse(BaseModel):
+    success:  bool
+    content:  str
+    error:    str = ""
+    metadata: dict = {}
+
+
+class StatusResponse(BaseModel):
+    indexed:          bool
+    class_chunks:     int
+    function_chunks:  int
+    total_chunks:     int
+    graph_loaded:     bool
+    graph_nodes:      int
+
+
+class TreeNode(BaseModel):
+    name:     str
+    type:     str           # "module" | "file" | "class" | "function"
+    children: list["TreeNode"] = []
+
+TreeNode.model_rebuild()
+
+
+class TreeResponse(BaseModel):
+    success: bool
+    tree:    list[TreeNode] = []
+    error:   str = ""
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@app.post("/upload-index", response_model=IndexResponse)
+async def upload_index(file: UploadFile = File(...)):
+    """
+    Accept a ZIP file, extract it to a temp directory, and index it.
+    Allows deployment without requiring local filesystem access.
+    """
+    if not file.filename.endswith(".zip"):
+        raise HTTPException(status_code=400, detail="Only .zip files are accepted.")
+
+    tmp_dir = tempfile.mkdtemp()
+
+    try:
+        zip_path = os.path.join(tmp_dir, file.filename)
+        with open(zip_path, "wb") as f:
+            shutil.copyfileobj(file.file, f)
+
+        with zipfile.ZipFile(zip_path, "r") as zf:
+            zf.extractall(tmp_dir)
+
+        os.remove(zip_path)
+
+        # Find the extracted root — skip __MACOSX and similar artifacts
+        candidates = [
+            os.path.join(tmp_dir, d)
+            for d in os.listdir(tmp_dir)
+            if os.path.isdir(os.path.join(tmp_dir, d)) and not d.startswith("__")
+        ]
+        root = candidates[0] if candidates else tmp_dir
+
+        console.rule(f"[bold cyan]Indexing ZIP: {file.filename}[/bold cyan]")
+
+        embed_codebase(root)
+
+        graph = build_and_save(root)
+        graph_stats = graph.stats()
+
+        store = get_vector_store()
+        vstats = store.stats()
+
+        console.print("[bold green]✔ ZIP Indexing complete.[/bold green]\n")
+
+        return IndexResponse(
+            success=True,
+            message=f"ZIP indexed successfully: {file.filename}",
+            class_chunks=vstats["class_chunks"],
+            function_chunks=vstats["function_chunks"],
+            total_chunks=vstats["total"],
+            graph_nodes=graph_stats["total_nodes"],
+            graph_edges=graph_stats["total_edges"],
+        )
+
+    except zipfile.BadZipFile:
+        raise HTTPException(status_code=400, detail="Invalid or corrupted ZIP file.")
+
+    except Exception as e:
+        console.print(f"[red]❌ ZIP indexing failed: {e}[/red]")
+        raise HTTPException(status_code=500, detail=f"ZIP indexing failed: {str(e)}")
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+@app.get("/health")
+async def health():
+    """Simple health check."""
+    return {"status": "ok", "service": "Codebase Oracle"}
+
+
+@app.get("/", response_class=FileResponse)
+async def serve_ui():
+    """Serve the UI index.html at root."""
+    ui_path = os.path.join(UI_DIR, "index.html")
+    if not os.path.exists(ui_path):
+        raise HTTPException(
+            status_code=404,
+            detail="UI not found. Place index.html in the ui/ directory."
+        )
+    return FileResponse(ui_path)
+
+
+@app.post("/index", response_model=IndexResponse)
+async def index_codebase(req: IndexRequest):
+    """
+    Ingest, parse, embed, and index a monolithic codebase.
+    Builds both ChromaDB vector index and call_graph.json.
+
+    This is the first endpoint to call before any queries.
+    """
+    root = req.root_path.strip()
+
+    if not os.path.exists(root):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Path does not exist: {root}"
+        )
+
+    if not os.path.isdir(root):
+        raise HTTPException(
+            status_code=400,
+            detail=f"Path is not a directory: {root}"
+        )
+
+    try:
+        console.rule(f"[bold cyan]Indexing: {root}[/bold cyan]")
+
+        # Step 1 — Embed codebase into ChromaDB
+        embed_codebase(root)
+
+        # Step 2 — Build and save call graph
+        graph = build_and_save(root)
+        graph_stats = graph.stats()
+
+        # Step 3 — Fetch vector store stats
+        store = get_vector_store()
+        vstats = store.stats()
+
+        console.print("[bold green]✔ Indexing complete.[/bold green]\n")
+
+        return IndexResponse(
+            success=True,
+            message=f"Codebase indexed successfully: {root}",
+            class_chunks=vstats["class_chunks"],
+            function_chunks=vstats["function_chunks"],
+            total_chunks=vstats["total"],
+            graph_nodes=graph_stats["total_nodes"],
+            graph_edges=graph_stats["total_edges"],
+        )
+
+    except Exception as e:
+        console.print(f"[red]❌ Indexing failed: {e}[/red]")
+        raise HTTPException(status_code=500, detail=f"Indexing failed: {str(e)}")
+
+
+@app.post("/query", response_model=QueryResponse)
+async def query(req: QueryRequest):
+    """
+    Run a macro, micro, or cross-module query against the indexed codebase.
+    Returns a markdown-formatted response string.
+    """
+    store = get_vector_store()
+    if not store.is_indexed():
+        raise HTTPException(
+            status_code=400,
+            detail="Codebase is not indexed yet. Call POST /index first."
+        )
+
+    engine = get_engine()
+
+    inference_req = InferenceRequest(
+        query_type=req.query_type,
+        query=req.query,
+        subtype=req.subtype,
+        function_name=req.function_name,
+        class_name=req.class_name,
+        module_name=req.module_name,
+        followup=req.followup,
+        previous_response=req.previous_response,
+    )
+
+    resp = engine.infer(inference_req)
+
+    return QueryResponse(
+        success=resp.success,
+        content=resp.content,
+        error=resp.error,
+        metadata=resp.metadata,
+    )
+
+
+@app.get("/status", response_model=StatusResponse)
+async def status():
+    """
+    Check whether the codebase is indexed and the system is ready for queries.
+    """
+    store  = get_vector_store()
+    vstats = store.stats()
+
+    graph_loaded = False
+    graph_nodes  = 0
+
+    if os.path.exists(CALL_GRAPH_PATH):
+        try:
+            graph = get_call_graph()
+            graph_loaded = graph.is_loaded()
+            graph_nodes  = graph.stats()["total_nodes"]
+        except Exception:
+            pass
+
+    return StatusResponse(
+        indexed=store.is_indexed(),
+        class_chunks=vstats["class_chunks"],
+        function_chunks=vstats["function_chunks"],
+        total_chunks=vstats["total"],
+        graph_loaded=graph_loaded,
+        graph_nodes=graph_nodes,
+    )
+
+
+@app.get("/tree", response_model=TreeResponse)
+async def get_tree():
+    """
+    Return the parsed codebase structure as a nested tree.
+    Used by the UI sidebar to render the codebase explorer.
+    """
+    store = get_vector_store()
+    if not store.is_indexed():
+        return TreeResponse(
+            success=False,
+            error="Codebase not indexed yet. Call POST /index first."
+        )
+
+    try:
+        # Fetch both class and function chunks to reconstruct tree
+        class_results = store.get_all("class_chunks", limit=500)
+        func_results = store.get_all("function_chunks", limit=500)
+
+        # Group by module → file → classes/functions
+        modules: dict[str, dict[str, dict[str, set]]] = {}
+
+        # --- classes ---
+        for chunk in class_results:
+            mod = chunk.module
+            file = chunk.file
+            modules.setdefault(mod, {}).setdefault(file, {"classes": set(), "functions": set()})
+            modules[mod][file]["classes"].add(chunk.name)
+
+        # --- functions (top-level only) ---
+        for chunk in func_results:
+            if not chunk.class_name:
+                mod = chunk.module
+                file = chunk.file
+                modules.setdefault(mod, {}).setdefault(file, {"classes": set(), "functions": set()})
+                modules[mod][file]["functions"].add(chunk.name)
+
+        # Also fetch function chunks for top-level functions
+        func_results = store.get_all("function_chunks", limit=500)
+        func_by_file: dict[str, list[str]] = {}
+        for chunk in func_results:
+            if not chunk.class_name:  # top-level only
+                func_by_file.setdefault(chunk.file, []).append(chunk.name)
+
+                # Build tree structure
+
+                all_files = set()
+                for files in modules.values():
+                    for file_path in files:
+                        all_files.add(file_path)
+
+                # Derive root directory name from common first path component
+                first_parts = [f.split("/")[0] for f in all_files if "/" in f]
+                root_name = first_parts[0] if first_parts else "codebase"
+
+                root_node = TreeNode(name=root_name, type="module")
+
+                for module_name, files in sorted(modules.items()):
+                    module_node = TreeNode(name=module_name, type="module")
+
+                    for file_path, content in sorted(files.items()):
+                        file_node = TreeNode(
+                            name=os.path.basename(file_path),
+                            type="file"
+                        )
+
+                        for cls_name in sorted(content["classes"]):
+                            file_node.children.append(
+                                TreeNode(name=cls_name, type="class")
+                            )
+
+                        for fn_name in sorted(content["functions"]):
+                            file_node.children.append(
+                                TreeNode(name=fn_name, type="function")
+                            )
+
+                        module_node.children.append(file_node)
+
+                    root_node.children.append(module_node)
+
+                return TreeResponse(success=True, tree=[root_node])
+
+    except Exception as e:
+        console.print(f"[red]❌ Tree build failed: {e}[/red]")
+        return TreeResponse(success=False, error=str(e))
+
+
+# ── Entry Point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "main:app",
+        port=8000,
+        reload=True,
+    )

prompt/cross_module.py

@@ -0,0 +1,424 @@
+"""
+cross_module_prompts.py
+-----------------------
+System prompts and prompt builders for cross-module codebase queries.
+
+Cross-module queries reason across multiple modules simultaneously.
+Two subtypes handled by ONE system prompt with internal classification:
+
+    1. dependency_analysis  — what does function X depend on, what depends on it
+    2. impact_analysis      — if function X changes, what breaks and where
+
+The LLM receives:
+    - Primary function context (from vector_store / retriever)
+    - Dependency context (from call_graph — callers and callees)
+    - Call graph metadata (structured dependency relationships)
+
+Depends on:
+    - rich (for __main__ preview only)
+"""
+
+# ── Shared Rules ──────────────────────────────────────────────────────────────
+
+_SHARED_RULES = """
+STRICT FORMATTING RULES:
+- Respond ONLY in valid markdown.
+- Use headers (##, ###) to separate sections clearly.
+- Use triple backtick code blocks for flow diagrams and signatures.
+- Use markdown tables for dependency and impact listings.
+- Use bullet points for risk assessments and recommendations.
+- Do NOT include conversational filler, preamble, or apologies.
+- Do NOT say "Based on the context provided" or similar phrases.
+- Be precise and technical. Assume the reader is a senior developer.
+- Explicitly state cross-module boundaries using module names.
+- If a dependency cannot be resolved from context, list it as unresolved.
+- Always include a ## Limitations section for missing context.
+"""
+
+# ── Subtype Classification (embedded in system prompt) ────────────────────────
+
+_SUBTYPE_DEFINITIONS = """
+QUERY CLASSIFICATION — internally classify every query as ONE of:
+
+TYPE D — Dependency Analysis
+    Triggered when developer asks:
+    - "What does X depend on?"
+    - "What calls X?"
+    - "What does X call?"
+    - "What are the dependencies of X?"
+    - "Who uses X?"
+    - "What modules interact with X?"
+    - "Show me the call chain for X"
+
+TYPE E — Impact Analysis
+    Triggered when developer asks:
+    - "What breaks if X changes?"
+    - "How does changing X affect Y?"
+    - "What is the impact of modifying X?"
+    - "If I change X, what else do I need to update?"
+    - "What are the side effects of changing X across modules?"
+    - "How far does X's influence reach?"
+
+If the query mentions both dependency and impact, classify as TYPE E
+since impact analysis subsumes dependency analysis.
+If ambiguous, default to TYPE D.
+"""
+
+# ── Cross-Module System Prompt ────────────────────────────────────────────────
+
+CROSS_MODULE_SYSTEM = f"""
+You are an expert software architect performing cross-module dependency
+and impact analysis on a monolithic Python codebase.
+
+Your task is to reason across multiple modules simultaneously,
+tracing function dependencies and assessing the blast radius of changes.
+
+You are strictly not allowed to do any task outside of this scope no matter the context. 
+If a function or code is not available in codebase, just return "The function/class might
+not be indexed for explanation. Please check if it's available in codebase."
+
+You will receive:
+1. PRIMARY CONTEXT    — the target function/class retrieved from the vector store
+2. DEPENDENCY CONTEXT — functions this target calls and functions that call it
+3. CALL GRAPH DATA    — structured JSON of the dependency relationships
+
+Use ALL three sources together. Prioritize CALL GRAPH DATA for structure,
+PRIMARY and DEPENDENCY CONTEXT for semantic understanding.
+
+{_SHARED_RULES}
+
+{_SUBTYPE_DEFINITIONS}
+
+─────────────────────────────────────────────────────────────
+RESPONSE SCHEMAS — use the schema matching your classified type:
+─────────────────────────────────────────────────────────────
+
+═══ TYPE D — Dependency Analysis ═══
+
+## Dependency Analysis: `<function_name>`
+**Module:** `<module>` | **File:** `<file>` | **Class:** `<class or top-level>`
+
+## Summary
+2-3 sentences describing the function's role in the broader system
+and its connectivity to other modules.
+
+## Outgoing Dependencies (What it calls)
+| Function | Class | Module | File | Relationship |
+|----------|-------|--------|------|-------------|
+| ...      | ...   | ...    | ...  | direct call |
+
+## Incoming Dependencies (What calls it)
+| Function | Class | Module | File | Relationship |
+|----------|-------|--------|------|-------------|
+| ...      | ...   | ...    | ...  | direct call |
+
+## Call Chain
+```
+[caller_2] → [caller_1] → [<function_name>] → [callee_1] → [callee_2]
+```
+
+## Cross-Module Boundaries
+Bullet points identifying which module boundaries this function crosses,
+and what data or control passes across those boundaries.
+
+## Unresolved Dependencies
+List any calls that could not be traced to a known function in the index.
+
+## Limitations
+Any gaps in the analysis due to missing context.
+
+═══ TYPE E — Impact Analysis ═══
+
+## Impact Analysis: `<function_name>`
+**Module:** `<module>` | **File:** `<file>` | **Class:** `<class or top-level>`
+
+## Proposed Change
+Restate what the developer wants to change, clearly and precisely.
+If no specific change is mentioned, analyze general modification impact.
+
+## Direct Impact
+What changes immediately inside this function and its direct callers.
+
+## Ripple Effects
+| Level | Affected Function | Class | Module | Impact Description | Risk |
+|-------|-------------------|-------|--------|--------------------|------|
+| 1     | ...               | ...   | ...    | ...                | Low/Medium/High |
+| 2     | ...               | ...   | ...    | ...                | Low/Medium/High |
+
+## Cross-Module Impact Map
+```
+[<function_name>] (changed)
+        ↓
+[Level 1: direct callers] — <module_a>, <module_b>
+        ↓
+[Level 2: indirect callers] — <module_c>
+```
+
+## Risk Assessment
+- **Overall risk:** Low / Medium / High
+- **Reason:** <why this risk level>
+- **Most vulnerable function:** <which function is most at risk and why>
+
+## Recommendations
+- **Before changing:** <what to check or prepare>
+- **After changing:** <what to test or update>
+- **Safe change strategy:** <how to minimize blast radius>
+
+## Unresolved Dependencies
+List any functions in the impact chain that could not be fully traced.
+
+## Limitations
+Any gaps in the analysis due to missing context.
+""".strip()
+
+
+# ── User Prompt Builder ───────────────────────────────────────────────────────
+
+def build_cross_module_user_prompt(primary_context:    str,
+                                    dependency_context: str,
+                                    call_graph_data:    dict,
+                                    query:              str,
+                                    function_name:      str,
+                                    class_name:         str = "") -> str:
+    """
+    Build the user prompt for a cross-module query.
+
+    Args:
+        primary_context:    Retrieved context for the target function.
+        dependency_context: Retrieved context for its dependencies.
+        call_graph_data:    Dict from CallGraph containing calls/called_by.
+        query:              The developer's natural language query.
+        function_name:      Name of the target function.
+        class_name:         Optional class name if it's a method.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    import json
+
+    scope = (
+        f"Method `{class_name}.{function_name}`"
+        if class_name
+        else f"Function `{function_name}`"
+    )
+
+    # Serialize call graph data cleanly
+    call_graph_str = json.dumps(call_graph_data, indent=2)
+
+    return f"""
+SUBJECT: {scope}
+
+─── PRIMARY CONTEXT ───────────────────────────────────────────
+{primary_context}
+
+─── DEPENDENCY CONTEXT ────────────────────────────────────────
+{dependency_context if dependency_context.strip() else "No dependency context retrieved."}
+
+─── CALL GRAPH DATA ───────────────────────────────────────────
+{call_graph_str}
+
+─── DEVELOPER QUERY ───────────────────────────────────────────
+{query}
+
+Classify this query as Type D or Type E internally.
+Then respond using the exact schema for the classified type.
+Do not mention the type classification in your response.
+Trace ALL cross-module boundaries explicitly using module names.
+""".strip()
+
+
+# ── Follow-up Prompt Builder ──────────────────────────────────────────────────
+
+CROSS_MODULE_FOLLOWUP_SYSTEM = """
+You are an expert software architect continuing a cross-module dependency
+or impact analysis discussion about a monolithic Python codebase.
+
+The developer has a follow-up question after your previous analysis.
+Use the same context, call graph, and your previous response to answer.
+
+STRICT FORMATTING RULES:
+- Respond ONLY in valid markdown.
+- Be concise — the developer already has your full analysis.
+- Focus only on what was asked in the follow-up.
+- Do NOT repeat your previous full analysis.
+- Always name modules explicitly when referencing cross-module relationships.
+""".strip()
+
+
+def build_cross_module_followup_prompt(previous_response:   str,
+                                        followup_query:      str,
+                                        primary_context:     str,
+                                        dependency_context:  str,
+                                        call_graph_data:     dict) -> str:
+    """
+    Build a follow-up user prompt for a cross-module conversation.
+
+    Args:
+        previous_response:  The LLM's previous cross-module response.
+        followup_query:     The developer's follow-up question.
+        primary_context:    Original primary context.
+        dependency_context: Original dependency context.
+        call_graph_data:    Original call graph data.
+
+    Returns:
+        Formatted follow-up user prompt string.
+    """
+    import json
+
+    return f"""
+─── PRIMARY CONTEXT ───────────────────────────────────────────
+{primary_context}
+
+─── DEPENDENCY CONTEXT ────────────────────────────────────────
+{dependency_context if dependency_context.strip() else "No dependency context retrieved."}
+
+─── CALL GRAPH DATA ───────────────────────────────────────────
+{json.dumps(call_graph_data, indent=2)}
+
+─── YOUR PREVIOUS ANALYSIS ────────────────────────────────────
+{previous_response}
+
+─── DEVELOPER FOLLOW-UP ───────────────────────────────────────
+{followup_query}
+
+Answer the follow-up using the context and your previous analysis.
+Name all modules explicitly when referencing cross-module relationships.
+""".strip()
+
+
+# ── Call Graph Data Builder ───────────────────────────────────────────────────
+
+def build_call_graph_payload(function_name: str,
+                              calls:         list,
+                              called_by:     list,
+                              impact:        dict) -> dict:
+    """
+    Build a clean structured dict from CallGraph data to inject
+    into the cross-module prompt.
+
+    Args:
+        function_name: Target function name.
+        calls:         List of CallNode objects (outgoing).
+        called_by:     List of CallNode objects (incoming).
+        impact:        Dict of impact levels from CallGraph.get_impact().
+
+    Returns:
+        Clean dict safe for JSON serialization.
+    """
+    def node_to_dict(node) -> dict:
+        return {
+            "name":       node.name,
+            "class_name": node.class_name,
+            "module":     node.module,
+            "file":       node.file,
+        }
+
+    impact_serialized = {}
+    for level, nodes in impact.items():
+        impact_serialized[level] = [node_to_dict(n) for n in nodes]
+
+    return {
+        "target_function": function_name,
+        "calls":           [node_to_dict(n) for n in calls],
+        "called_by":       [node_to_dict(n) for n in called_by],
+        "impact_chain":    impact_serialized,
+    }
+
+
+# ── Prompt Accessor ───────────────────────────────────────────────────────────
+
+def get_cross_module_system_prompt(followup: bool = False) -> str:
+    """
+    Return the cross-module system prompt.
+
+    Args:
+        followup: If True, returns the follow-up system prompt.
+
+    Returns:
+        System prompt string.
+    """
+    return CROSS_MODULE_FOLLOWUP_SYSTEM if followup else CROSS_MODULE_SYSTEM
+
+
+# ── Entry Point (preview prompts) ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.rule import Rule
+
+    console = Console()
+
+    sample_primary = """
+--- Chunk 1 (function: extract_function_types) ---
+Scope: top-level function
+Function: extract_function_types
+Module: refurb
+File: refurb/loader.py
+Signature: def extract_function_types(func: Any) -> Generator[type[Node], None, None]
+Docstring: No docstring provided.
+Calls: list, callable, TypeError, signature, isinstance
+""".strip()
+
+    sample_dependency = """
+--- Chunk 1 (function: load_checks) ---
+Scope: top-level function
+Function: load_checks
+Module: refurb
+File: refurb/main.py
+Signature: def load_checks(path: str) -> list[Check]
+Calls: extract_function_types, import_module
+
+--- Chunk 2 (function: run) ---
+Class: Router
+Module: refurb
+File: refurb/main.py
+Signature: def run(args: list[str]) -> int
+Calls: load_checks, parse_args
+""".strip()
+
+    sample_call_graph = build_call_graph_payload(
+        function_name="extract_function_types",
+        calls=[],
+        called_by=[],
+        impact={},
+    )
+
+    queries = [
+        ("What does extract_function_types depend on and what depends on it?",
+         "Type D — Dependency Analysis"),
+        ("What breaks if I change the return type of extract_function_types?",
+         "Type E — Impact Analysis"),
+    ]
+
+    console.print(Rule("[bold cyan]Cross-Module — System Prompt[/bold cyan]"))
+    console.print(Panel(
+        CROSS_MODULE_SYSTEM,
+        border_style="cyan",
+        padding=(1, 2),
+    ))
+
+    for query, label in queries:
+        console.print(Rule(f"[bold magenta]User Prompt — {label}[/bold magenta]"))
+        user_prompt = build_cross_module_user_prompt(
+            primary_context=sample_primary,
+            dependency_context=sample_dependency,
+            call_graph_data=sample_call_graph,
+            query=query,
+            function_name="extract_function_types",
+        )
+        console.print(Panel(
+            user_prompt,
+            border_style="magenta",
+            padding=(1, 2),
+        ))
+
+    console.print(Rule("[bold yellow]Follow-up Prompt Preview[/bold yellow]"))
+    followup = build_cross_module_followup_prompt(
+        previous_response="## Dependency Analysis: `extract_function_types`\n...",
+        followup_query="Which of these callers is most critical to the system?",
+        primary_context=sample_primary,
+        dependency_context=sample_dependency,
+        call_graph_data=sample_call_graph,
+    )
+    console.print(Panel(followup, border_style="yellow", padding=(1, 2)))

prompt/macro_prompt.py

@@ -0,0 +1,357 @@
+"""
+macro_prompts.py
+----------------
+System prompts and prompt builders for macro-level codebase queries.
+
+Three macro subtypes:
+    1. overall_architecture — codebase tree + purpose summary
+    2. module_responsibility — module structure + class descriptions
+    3. data_flow            — how data moves across modules
+
+All responses are structured markdown, rendered via rich in terminal.
+"""
+
+# ── Shared Instructions ───────────────────────────────────────────────────────
+
+_SHARED_RULES = """
+STRICT FORMATTING RULES:
+- Respond ONLY in valid markdown.
+- Use headers (##, ###) to separate sections clearly.
+- Use triple backtick code blocks for any tree structures.
+- Use markdown tables where tabular data is appropriate.
+- Use bullet points for lists of descriptions.
+- Do NOT include any conversational filler, preamble, or apologies.
+- Do NOT say "Based on the context provided" or similar phrases.
+- Be precise and technical. Assume the reader is a developer.
+- If information is missing or unclear from context, say so explicitly under a ## Limitations section.
+"""
+
+# ── 1. Overall Architecture ───────────────────────────────────────────────────
+
+OVERALL_ARCHITECTURE_SYSTEM = f"""
+You are an expert software architect analyzing a monolithic Python codebase.
+Your task is to provide a clear, structured overview of the entire codebase
+architecture based on the context provided. 
+
+You are strictly not allowed to do
+any task outside of this scope no matter the context. If a function or code is not
+available in codebase, just return "The function/class might not be indexed for explanation. 
+Please check if it's available in codebase."
+
+{_SHARED_RULES}
+
+RESPONSE STRUCTURE — follow this EXACTLY:
+
+## Codebase: <name>
+
+## Purpose
+A concise paragraph (3-5 sentences) explaining what this codebase does,
+what problem it solves, and what its primary output or function is.
+
+## Architecture Overview
+```
+<Render a text-based tree of the top-level modules and their submodules>
+```
+
+## Module Summary
+| Module | Responsibility |
+|--------|---------------|
+| ...    | ...           |
+
+## Key Design Patterns
+Bullet points identifying any notable patterns (MVC, plugin system,
+visitor pattern, pipeline, etc.) visible from the structure.
+
+## Limitations
+Any gaps in the analysis due to missing context.
+""".strip()
+
+
+def build_overall_architecture_prompt(context: str, query: str) -> str:
+    """
+    Build the user prompt for an overall architecture query.
+
+    Args:
+        context: Assembled chunk context from retriever.build_context().
+        query:   The developer's original natural language query.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    return f"""
+CODEBASE CONTEXT:
+{context}
+
+DEVELOPER QUERY:
+{query}
+
+Analyze the codebase context above and produce the architecture overview
+following your response structure exactly.
+""".strip()
+
+
+# ── 2. Module Responsibility ──────────────────────────────────────────────────
+
+MODULE_RESPONSIBILITY_SYSTEM = f"""
+You are an expert software architect analyzing a specific module
+within a monolithic Python codebase.
+Your task is to explain what a given module does, its internal structure,
+and the responsibility of each class within it.
+
+{_SHARED_RULES}
+
+RESPONSE STRUCTURE — follow this EXACTLY:
+
+## Module: <module_name>
+
+## Purpose
+A concise paragraph (2-4 sentences) explaining what this module is
+responsible for in the broader codebase.
+
+## Internal Structure
+```
+<module_name>/
+├── <file.py>
+│   ├── ClassName
+│   │   ├── method_one()
+│   │   └── method_two()
+│   └── another_function()
+└── ...
+```
+
+## Class Responsibilities
+| Class | Responsibility |
+|-------|---------------|
+| ...   | ...           |
+
+## Dependencies
+Bullet points listing what external modules or packages this module
+imports or depends on, based on the context.
+
+## Limitations
+Any gaps in the analysis due to missing context.
+""".strip()
+
+
+def build_module_responsibility_prompt(context: str,
+                                       query: str,
+                                       module_name: str) -> str:
+    """
+    Build the user prompt for a module responsibility query.
+
+    Args:
+        context:     Assembled chunk context from retriever.build_context().
+        query:       The developer's original natural language query.
+        module_name: Name of the module being queried.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    return f"""
+MODULE: {module_name}
+
+CODEBASE CONTEXT:
+{context}
+
+DEVELOPER QUERY:
+{query}
+
+Analyze the module context above and explain the module's responsibility
+and internal structure following your response structure exactly.
+""".strip()
+
+
+# ── 3. Data Flow ──────────────────────────────────────────────────────────────
+
+DATA_FLOW_SYSTEM = f"""
+You are an expert software architect analyzing data flow across modules
+in a monolithic Python codebase.
+Your task is to trace and explain how data enters, transforms, and moves
+through the system based on the context provided.
+
+{_SHARED_RULES}
+
+RESPONSE STRUCTURE — follow this EXACTLY:
+
+## Data Flow: <topic or entry point>
+
+## Overview
+A concise paragraph (3-5 sentences) summarizing the high-level data
+flow from input to output.
+
+## Flow Diagram
+```
+[Input / Entry Point]
+        ↓
+[Module A] → <what happens here>
+        ↓
+[Module B] → <what transforms here>
+        ↓
+[Output / Result]
+```
+
+## Step-by-Step Breakdown
+### Step 1: <Entry Point>
+Description of what initiates the flow and what data looks like at this stage.
+
+### Step 2: <Module / Function>
+Description of transformation or processing at this stage.
+
+### Step N: <Final Output>
+Description of what the data looks like at the end.
+
+## Data Structures Involved
+| Structure | Module | Role in Flow |
+|-----------|--------|-------------|
+| ...       | ...    | ...         |
+
+## Limitations
+Any gaps in the analysis due to missing context or ambiguous flow.
+""".strip()
+
+
+def build_data_flow_prompt(context: str, query: str) -> str:
+    """
+    Build the user prompt for a data flow query.
+
+    Args:
+        context: Assembled chunk context from retriever.build_context().
+        query:   The developer's original natural language query.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    return f"""
+CODEBASE CONTEXT:
+{context}
+
+DEVELOPER QUERY:
+{query}
+
+Trace and explain the data flow described in the query using the
+codebase context above. Follow your response structure exactly.
+""".strip()
+
+
+# ── Prompt Router ─────────────────────────────────────────────────────────────
+
+MACRO_SUBTYPES = {
+    "overall_architecture": "Overall Architecture",
+    "module_responsibility": "Module Responsibility",
+    "data_flow":            "Data Flow",
+}
+
+
+def get_macro_system_prompt(subtype: str) -> str:
+    """
+    Return the correct system prompt for a given macro subtype.
+
+    Args:
+        subtype: One of 'overall_architecture', 'module_responsibility',
+                 'data_flow'.
+
+    Returns:
+        System prompt string.
+
+    Raises:
+        ValueError: If subtype is not recognized.
+    """
+    mapping = {
+        "overall_architecture": OVERALL_ARCHITECTURE_SYSTEM,
+        "module_responsibility": MODULE_RESPONSIBILITY_SYSTEM,
+        "data_flow":             DATA_FLOW_SYSTEM,
+    }
+
+    if subtype not in mapping:
+        raise ValueError(
+            f"Unknown macro subtype: '{subtype}'. "
+            f"Choose from: {list(mapping.keys())}"
+        )
+
+    return mapping[subtype]
+
+
+def build_macro_user_prompt(subtype:     str,
+                             context:     str,
+                             query:       str,
+                             module_name: str = "") -> str:
+    """
+    Build the correct user prompt for a given macro subtype.
+
+    Args:
+        subtype:     One of the three macro subtypes.
+        context:     Retrieved context string.
+        query:       Developer's natural language query.
+        module_name: Required only for 'module_responsibility' subtype.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    if subtype == "overall_architecture":
+        return build_overall_architecture_prompt(context, query)
+
+    elif subtype == "module_responsibility":
+        if not module_name:
+            raise ValueError(
+                "'module_name' is required for 'module_responsibility' subtype."
+            )
+        return build_module_responsibility_prompt(context, query, module_name)
+
+    elif subtype == "data_flow":
+        return build_data_flow_prompt(context, query)
+
+    raise ValueError(
+        f"Unknown macro subtype: '{subtype}'. "
+        f"Choose from: {list(MACRO_SUBTYPES.keys())}"
+    )
+
+
+# ── Entry Point (preview prompts) ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.rule import Rule
+
+    console = Console()
+
+    sample_context = """
+--- Chunk 1 (class: Router) ---
+Class: Router
+Module: refurb
+File: refurb/main.py
+Docstring: Main entry point router for the refurb linting tool.
+Methods:
+  def run(args: list[str]) -> int
+  def load_checks(path: str) -> list[Check]
+
+--- Chunk 2 (class: Loader) ---
+Class: Loader
+Module: refurb
+File: refurb/loader.py
+Docstring: Loads and validates check functions from plugin modules.
+Methods:
+  def extract_function_types(func: Any) -> Generator
+  def load_module(path: str) -> ModuleType
+""".strip()
+
+    for subtype, label in MACRO_SUBTYPES.items():
+        console.print(Rule(f"[bold cyan]{label} — System Prompt[/bold cyan]"))
+        console.print(Panel(
+            get_macro_system_prompt(subtype),
+            border_style="cyan",
+            padding=(1, 2),
+        ))
+
+        console.print(Rule(f"[bold magenta]{label} — User Prompt Preview[/bold magenta]"))
+        user_prompt = build_macro_user_prompt(
+            subtype=subtype,
+            context=sample_context,
+            query=f"Explain the {label.lower()} of this codebase",
+            module_name="refurb" if subtype == "module_responsibility" else "",
+        )
+        console.print(Panel(
+            user_prompt,
+            border_style="magenta",
+            padding=(1, 2),
+        ))

prompt/micro_prompt.py

@@ -0,0 +1,330 @@
+"""
+micro_prompts.py
+----------------
+System prompts and prompt builders for micro-level codebase queries.
+
+Micro queries operate at function/method level. The LLM classifies
+the query internally into one of three subtypes:
+
+    1. function_definition  — signature, purpose, parameters, usage example
+    2. function_body        — internal logic, data flow, warnings
+    3. function_consideration — impact of proposed changes
+
+Unlike macro prompts, there is ONE system prompt for micro queries.
+The LLM classifies the subtype from the developer's natural language
+query and responds in the appropriate schema automatically.
+
+Depends on:
+    - rich (for __main__ preview only)
+"""
+
+# ── Shared Rules ──────────────────────────────────────────────────────────────
+
+_SHARED_RULES = """
+STRICT FORMATTING RULES:
+- Respond ONLY in valid markdown.
+- Use headers (##, ###) to separate sections clearly.
+- Use triple backtick code blocks for ALL code snippets and signatures.
+- Use markdown tables for parameter listings.
+- Use bullet points for warnings, considerations, and impact lists.
+- Do NOT include conversational filler, preamble, or apologies.
+- Do NOT say "Based on the context provided" or similar phrases.
+- Be precise and technical. Assume the reader is a developer.
+- If information is unclear from context, say so under a ## Limitations section.
+"""
+
+# ── Subtype Descriptions (used inside system prompt) ─────────────────────────
+
+_SUBTYPE_DEFINITIONS = """
+QUERY CLASSIFICATION — internally classify every incoming query as ONE of:
+
+TYPE A — Function Definition
+    Triggered when developer asks:
+    - "What does X do?"
+    - "Explain X function"
+    - "What are the parameters of X?"
+    - "How do I use X?"
+    - "What does X return?"
+
+TYPE B — Function Body
+    Triggered when developer asks:
+    - "How does X work internally?"
+    - "Walk me through X"
+    - "What is the logic inside X?"
+    - "Explain the flow inside X"
+    - "What happens step by step in X?"
+
+TYPE C — Function Consideration
+    Triggered when developer asks:
+    - "What if I change X to Y?"
+    - "What happens if I modify this parameter?"
+    - "Is it safe to change X?"
+    - "What breaks if I alter X?"
+    - "What are the side effects of changing X?"
+
+If the query is ambiguous, default to TYPE A.
+"""
+
+# ── Micro System Prompt ───────────────────────────────────────────────────────
+
+MICRO_SYSTEM = f"""
+You are an expert Python software engineer analyzing individual functions
+and methods within a monolithic codebase.
+
+Your task is to answer developer questions about specific functions or methods
+at the deepest level of detail possible, based on the context provided.
+
+You are strictly not allowed to do any task outside of this scope no matter the context. 
+If a function or code is not available in codebase, just return "The function/class might
+not be indexed for explanation. Please check if it's available in codebase."
+
+{_SHARED_RULES}
+
+{_SUBTYPE_DEFINITIONS}
+
+─────────────────────────────────────────────────────────────
+RESPONSE SCHEMAS — use the schema matching your classified type:
+─────────────────────────────────────────────────────────────
+
+═══ TYPE A — Function Definition ═══
+
+## Function: `<function_name>`
+**Class:** `<ClassName>` | **Module:** `<module>` | **File:** `<file>`
+
+## Signature
+```python
+def <function_name>(<params>) -> <return_type>:
+```
+
+## Purpose
+Concise paragraph (2-4 sentences) explaining what this function does
+and why it exists.
+
+## Parameters
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| ...       | ...  | ...     | ...         |
+
+## Return Value
+What the function returns, its type, and what it represents.
+
+## Usage Example
+```python
+<concrete, realistic code snippet showing how to call this function>
+```
+
+## Limitations
+Any gaps or unclear aspects from the context.
+
+═══ TYPE B — Function Body ═══
+
+## Function: `<function_name>` — Internal Analysis
+**Class:** `<ClassName>` | **Module:** `<module>` | **File:** `<file>`
+
+## Internal Flow
+Step-by-step breakdown of what happens inside the function:
+
+### Step 1: <label>
+Description of this step.
+
+### Step N: <label>
+Description of this step.
+
+## Data Flow
+```
+input → <transformation> → <intermediate> → <transformation> → output
+```
+
+## Warnings & Edge Cases
+- <potential issue or missing validation>
+- <edge case not handled>
+- <what happens with unexpected input>
+
+## Limitations
+Any gaps or unclear aspects from the context.
+
+═══ TYPE C — Function Consideration ═══
+
+## Impact Analysis: `<function_name>`
+
+## Proposed Change
+Restate the developer's proposed change clearly and precisely.
+
+## Direct Effects
+What changes immediately inside this function if the modification is made.
+
+## Ripple Effects
+| Affected Function | Module | Impact | Risk |
+|-------------------|--------|--------|------|
+| ...               | ...    | ...    | Low/Medium/High |
+
+## Recommendation
+- **Safe to change:** <yes/no/conditional — explain>
+- **Suggested approach:** <how to make the change safely>
+- **Tests to update:** <what would need re-testing>
+
+## Limitations
+Any gaps or unclear aspects from the context.
+""".strip()
+
+
+# ── User Prompt Builder ───────────────────────────────────────────────────────
+
+def build_micro_user_prompt(context:       str,
+                             query:         str,
+                             function_name: str,
+                             class_name:    str = "") -> str:
+    """
+    Build the user prompt for a micro-level query.
+
+    The system prompt handles subtype classification internally,
+    so the user prompt just needs to supply context + query clearly.
+
+    Args:
+        context:       Assembled chunk context from retriever.build_context().
+        query:         The developer's natural language query.
+        function_name: Name of the function/method being queried.
+        class_name:    Optional class name if it's a method.
+
+    Returns:
+        Formatted user prompt string.
+    """
+    scope = (
+        f"Method `{class_name}.{function_name}`"
+        if class_name
+        else f"Function `{function_name}`"
+    )
+
+    return f"""
+FUNCTION CONTEXT:
+{context}
+
+SUBJECT: {scope}
+
+DEVELOPER QUERY:
+{query}
+
+Classify this query into Type A, B, or C internally.
+Then respond using the exact schema for the classified type.
+Do not mention the type classification in your response.
+""".strip()
+
+
+# ── Follow-up Prompt Builder ──────────────────────────────────────────────────
+
+MICRO_FOLLOWUP_SYSTEM = """
+You are an expert Python software engineer continuing a technical discussion
+about a specific function or method in a monolithic codebase.
+
+The developer has a follow-up question after your previous analysis.
+Use the same context and your previous response to answer precisely.
+
+STRICT FORMATTING RULES:
+- Respond ONLY in valid markdown.
+- Be concise — the developer already has your full analysis.
+- Focus only on what was asked in the follow-up.
+- Do NOT repeat your previous full analysis.
+""".strip()
+
+
+def build_micro_followup_prompt(previous_response: str,
+                                 followup_query:    str,
+                                 context:           str) -> str:
+    """
+    Build a follow-up user prompt continuing a micro-level conversation.
+
+    Args:
+        previous_response: The LLM's previous micro response.
+        followup_query:    The developer's follow-up question.
+        context:           Original retrieved context (still relevant).
+
+    Returns:
+        Formatted follow-up user prompt string.
+    """
+    return f"""
+ORIGINAL CONTEXT:
+{context}
+
+YOUR PREVIOUS ANALYSIS:
+{previous_response}
+
+DEVELOPER FOLLOW-UP:
+{followup_query}
+
+Answer the follow-up precisely using the context and your previous analysis.
+""".strip()
+
+
+# ── Prompt Accessor ───────────────────────────────────────────────────────────
+
+def get_micro_system_prompt(followup: bool = False) -> str:
+    """
+    Return the micro system prompt.
+
+    Args:
+        followup: If True, returns the follow-up system prompt.
+
+    Returns:
+        System prompt string.
+    """
+    return MICRO_FOLLOWUP_SYSTEM if followup else MICRO_SYSTEM
+
+
+# ── Entry Point (preview prompts) ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.rule import Rule
+
+    console = Console()
+
+    sample_context = """
+--- Chunk 1 (function: extract_function_types) ---
+Scope: top-level function
+Function: extract_function_types
+Module: refurb
+File: refurb/loader.py
+Signature: def extract_function_types(func: Any) -> Generator[type[Node], None, None]
+Docstring: No docstring provided.
+Calls: list, callable, TypeError, signature(func).parameters.values,
+       len, type_error_with_line_info, isinstance, signature
+""".strip()
+
+    queries = [
+        ("What does extract_function_types do and how do I use it?",
+         "Type A — Definition"),
+        ("Walk me through the internal logic of extract_function_types",
+         "Type B — Body"),
+        ("What happens if I change the return type from Generator to list?",
+         "Type C — Consideration"),
+    ]
+
+    console.print(Rule("[bold cyan]Micro — System Prompt[/bold cyan]"))
+    console.print(Panel(
+        MICRO_SYSTEM,
+        border_style="cyan",
+        padding=(1, 2),
+    ))
+
+    for query, label in queries:
+        console.print(Rule(f"[bold magenta]User Prompt Preview — {label}[/bold magenta]"))
+        user_prompt = build_micro_user_prompt(
+            context=sample_context,
+            query=query,
+            function_name="extract_function_types",
+            class_name="",
+        )
+        console.print(Panel(
+            user_prompt,
+            border_style="magenta",
+            padding=(1, 2),
+        ))
+
+    console.print(Rule("[bold yellow]Follow-up Prompt Preview[/bold yellow]"))
+    followup = build_micro_followup_prompt(
+        previous_response="## Function: `extract_function_types`\n...",
+        followup_query="Can this function handle async functions as input?",
+        context=sample_context,
+    )
+    console.print(Panel(followup, border_style="yellow", padding=(1, 2)))

requirements.txt

@@ -0,0 +1,9 @@
+fastapi
+uvicorn
+networkx
+python-dotenv
+openai
+rich
+sentence-transformers
+pinecone
+python-multipart

retrieve/retrieve.py

@@ -0,0 +1,489 @@
+"""
+retriever.py
+------------
+Retrieves relevant chunks from ChromaDB based on query type.
+
+Query type determines which collection to search:
+    - Macro / Cross-Module  → class_chunks
+    - Micro                 → function_chunks
+
+Provides filtered retrieval by module, class, or function name
+for precise context fetching.
+
+Depends on:
+    - embedder.py  (query_chunks, get_chroma_client, load_embedding_model)
+    - rich         (terminal output)
+"""
+
+from dataclasses import dataclass
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+from ingest.embed import (
+    query_chunks,
+    load_embedding_model,
+    CLASS_COLLECTION,
+    FUNCTION_COLLECTION,
+    COMPLETE_COLLECTION
+)
+
+console = Console()
+
+
+# ── Query Types ───────────────────────────────────────────────────────────────
+
+class QueryType:
+    MACRO        = "macro"
+    MICRO        = "micro"
+    CROSS_MODULE = "cross_module"
+
+
+# ── Result Model ──────────────────────────────────────────────────────────────
+
+@dataclass
+class RetrievedChunk:
+    text:       str
+    metadata:   dict
+    distance:   float
+    collection: str
+
+    @property
+    def name(self) -> str:
+        return self.metadata.get("name", "unknown")
+
+    @property
+    def module(self) -> str:
+        return self.metadata.get("module", "unknown")
+
+    @property
+    def file(self) -> str:
+        return self.metadata.get("file", "unknown")
+
+    @property
+    def class_name(self) -> str:
+        return self.metadata.get("class_name", "")
+
+    @property
+    def chunk_type(self) -> str:
+        return self.metadata.get("type", "unknown")
+
+    @property
+    def relevance_score(self) -> float:
+        """Convert distance to 0-1 relevance score (lower distance = higher relevance)."""
+        return round(1 / (1 + self.distance), 4)
+
+
+# ── Core Retriever ────────────────────────────────────────────────────────────
+
+class Retriever:
+    """
+    Unified retriever for the Codebase Oracle system.
+    Maintains a single embedding model and ChromaDB client across queries.
+    """
+
+    def __init__(self):
+        self.model = load_embedding_model()
+        console.print("[green]✔[/green] Retriever ready.\n")
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def retrieve(self,
+                 query:      str,
+                 query_type: str,
+                 n_results:  int = 5,
+                 filters:    dict | None = None) -> list[RetrievedChunk]:
+        """
+        Main retrieval entry point. Routes to the correct collection
+        based on query_type.
+
+        Args:
+            query:      Natural language query string.
+            query_type: One of QueryType.MACRO / MICRO / CROSS_MODULE.
+            n_results:  Number of chunks to retrieve.
+            filters:    Optional metadata filters (e.g. filter by module).
+
+        Returns:
+            List of RetrievedChunk objects sorted by relevance.
+        """
+        collection = self._route_collection(query_type)
+
+        raw = query_chunks(
+            query=query,
+            collection_name=collection,
+            model=self.model,
+            n_results=n_results,
+            filters=filters,
+        )
+
+        chunks = [
+            RetrievedChunk(
+                text=r["text"],
+                metadata=r["metadata"],
+                distance=r["distance"],
+                collection=collection,
+            )
+            for r in raw
+        ]
+
+        return chunks
+
+    def retrieve_by_class(self,
+                          class_name: str,
+                          n_results:  int = 1) -> list[RetrievedChunk]:
+        """
+        Retrieve class-level chunk by exact class name.
+        Used by micro agent to ground function queries with class context.
+
+        Args:
+            class_name: Exact class name string.
+            n_results:  Usually 1 — we want the specific class.
+
+        Returns:
+            List of RetrievedChunk from class_chunks collection.
+        """
+        return self.retrieve(
+            query=f"class {class_name}",
+            query_type=QueryType.MACRO,
+            n_results=n_results,
+            filters={"name": {"$eq": class_name}},
+        )
+
+    def retrieve_by_function(self,
+                             function_name: str,
+                             class_name:    str | None = None,
+                             n_results:     int = 3) -> list[RetrievedChunk]:
+        """
+        Retrieve function-level chunks by function name.
+        Optionally filter by class name for method disambiguation.
+
+        Args:
+            function_name: Exact function/method name.
+            class_name:    Optional class name to narrow results.
+            n_results:     Number of results.
+
+        Returns:
+            List of RetrievedChunk from function_chunks collection.
+        """
+        filters = {"name": {"$eq": function_name}}
+        if class_name:
+            filters = {
+                "$and": [
+                    {"name":       {"$eq": function_name}},
+                    {"class_name": {"$eq": class_name}},
+                ]
+            }
+
+        return self.retrieve(
+            query=f"function {function_name}",
+            query_type=QueryType.MICRO,
+            n_results=n_results,
+            filters=filters,
+        )
+
+    def retrieve_by_module(self,
+                           module_name: str,
+                           query:       str,
+                           query_type:  str = QueryType.MACRO,
+                           n_results:   int = 5) -> list[RetrievedChunk]:
+        """
+        Retrieve chunks scoped to a specific module.
+
+        Args:
+            module_name: Top-level module/package name.
+            query:       Natural language query within that module.
+            query_type:  MACRO or MICRO.
+            n_results:   Number of results.
+
+        Returns:
+            List of RetrievedChunk filtered to the given module.
+        """
+        return self.retrieve(
+            query=query,
+            query_type=query_type,
+            n_results=n_results,
+            filters={"module": {"$eq": module_name}},
+        )
+
+    def retrieve_dependencies(self, function_name: str) -> list[RetrievedChunk]:
+        """
+        Retrieve all functions that the given function calls.
+        Used by cross-module agent for dependency/impact analysis.
+
+        Args:
+            function_name: Name of the function to trace dependencies for.
+
+        Returns:
+            List of RetrievedChunk for each called function found in index.
+        """
+        # First get the function itself to extract its call list
+        source_chunks = self.retrieve_by_function(function_name, n_results=1)
+
+        if not source_chunks:
+            console.print(f"[yellow]⚠ Function '{function_name}' not found in index.[/yellow]")
+            return []
+
+        import json
+        calls = json.loads(source_chunks[0].metadata.get("calls", "[]"))
+
+        if not calls:
+            return []
+
+        # Retrieve each called function from the index
+        dep_chunks = []
+        seen = set()
+        for call in calls:
+            # Strip object prefix if present (e.g. "self.calculate" → "calculate")
+            name = call.split(".")[-1]
+            if name in seen:
+                continue
+            seen.add(name)
+
+            results = self.retrieve_by_function(name, n_results=1)
+            dep_chunks.extend(results)
+
+        return dep_chunks
+
+    def build_context(self, chunks: list[RetrievedChunk],
+                      max_chars: int = 6000) -> str:
+        """
+        Concatenate retrieved chunks into a single context string
+        for the LLM prompt. Truncates at max_chars to stay within
+        context window limits.
+
+        Args:
+            chunks:    Retrieved chunks to concatenate.
+            max_chars: Maximum total character length of context.
+
+        Returns:
+            A single string ready to inject into an LLM prompt.
+        """
+        parts = []
+        total = 0
+
+        for i, chunk in enumerate(chunks, 1):
+            section = (
+                f"--- Chunk {i} ({chunk.chunk_type}: {chunk.name}) ---\n"
+                f"{chunk.text}\n"
+            )
+            if total + len(section) > max_chars:
+                parts.append("\n[Context truncated — token limit reached]")
+                break
+            parts.append(section)
+            total += len(section)
+
+        return "\n".join(parts)
+
+    def retrieve_complete_function(self,
+                                   function_name: str,
+                                   class_name: str | None = None,
+                                   n_results: int = 1) -> list[RetrievedChunk]:
+        """
+        Retrieve complete function chunk including full source code.
+        Used for micro queries requiring edge case or usage analysis.
+        """
+        filters = {
+            "$and": [
+                {"type": {"$eq": "complete_function"}},
+                {"name": {"$eq": function_name}},
+            ]
+        }
+        if class_name:
+            filters = {
+                "$and": [
+                    {"type": {"$eq": "complete_function"}},
+                    {"name": {"$eq": function_name}},
+                    {"class_name": {"$eq": class_name}},
+                ]
+            }
+
+        raw = query_chunks(
+            query=f"function {function_name}",
+            collection_name=COMPLETE_COLLECTION,
+            model=self.model,
+            n_results=n_results,
+            filters=filters,
+        )
+
+        return [
+            RetrievedChunk(
+                text=r["text"],
+                metadata=r["metadata"],
+                distance=r["distance"],
+                collection=COMPLETE_COLLECTION,
+            )
+            for r in raw
+        ]
+
+    def retrieve_complete_class(self,
+                                class_name: str,
+                                n_results: int = 1) -> list[RetrievedChunk]:
+        """
+        Retrieve complete class chunk including full source code.
+        Used for class-level deep queries.
+        """
+        filters = {
+            "$and": [
+                {"type": {"$eq": "complete_class"}},
+                {"name": {"$eq": class_name}},
+            ]
+        }
+
+        raw = query_chunks(
+            query=f"class {class_name}",
+            collection_name=COMPLETE_COLLECTION,
+            model=self.model,
+            n_results=n_results,
+            filters=filters,
+        )
+
+        return [
+            RetrievedChunk(
+                text=r["text"],
+                metadata=r["metadata"],
+                distance=r["distance"],
+                collection=COMPLETE_COLLECTION,
+            )
+            for r in raw
+        ]
+
+    def retrieve_file(self,
+                      file_name: str,
+                      n_results: int = 1) -> list[RetrievedChunk]:
+        """
+        Retrieve complete file chunk.
+        Used for file-wide queries.
+        """
+        filters = {
+            "$and": [
+                {"type": {"$eq": "file"}},
+                {"name": {"$eq": file_name}},
+            ]
+        }
+
+        raw = query_chunks(
+            query=f"file {file_name}",
+            collection_name=COMPLETE_COLLECTION,
+            model=self.model,
+            n_results=n_results,
+            filters=filters,
+        )
+
+        return [
+            RetrievedChunk(
+                text=r["text"],
+                metadata=r["metadata"],
+                distance=r["distance"],
+                collection=COMPLETE_COLLECTION,
+            )
+            for r in raw
+        ]
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _route_collection(self, query_type: str) -> str:
+        """Map query type to the appropriate ChromaDB collection."""
+        if query_type == QueryType.MICRO:
+            return FUNCTION_COLLECTION
+        return CLASS_COLLECTION   # MACRO and CROSS_MODULE both use class chunks
+
+
+# ── Rich Renderers ────────────────────────────────────────────────────────────
+
+def render_chunks(chunks: list[RetrievedChunk], title: str = "Retrieved Chunks") -> None:
+    """Render retrieved chunks as a rich table."""
+    if not chunks:
+        console.print("[yellow]No chunks retrieved.[/yellow]")
+        return
+
+    table = Table(
+        "Rank", "Type", "Name", "Class", "Module", "File", "Relevance",
+        box=box.ROUNDED,
+        header_style="bold bright_cyan",
+        border_style="cyan",
+        show_lines=True,
+        title=title,
+    )
+
+    for i, chunk in enumerate(chunks, 1):
+        score = chunk.relevance_score
+        score_style = (
+            "bold green" if score > 0.7
+            else "yellow" if score > 0.4
+            else "red"
+        )
+        table.add_row(
+            str(i),
+            chunk.chunk_type,
+            f"[bold]{chunk.name}[/bold]",
+            chunk.class_name or "[dim]—[/dim]",
+            chunk.module,
+            chunk.file,
+            f"[{score_style}]{score}[/{score_style}]",
+        )
+
+    console.print(table)
+
+
+def render_chunk_detail(chunk: RetrievedChunk) -> None:
+    """Render the full text of a single chunk in a panel."""
+    header = Text()
+    header.append(chunk.chunk_type.upper(), style="bold cyan")
+    header.append(f"  {chunk.name}", style="bold white")
+    if chunk.class_name:
+        header.append(f"  in {chunk.class_name}", style="dim")
+
+    console.print(Panel(
+        chunk.text,
+        title=str(header),
+        border_style="cyan",
+        padding=(1, 2),
+    ))
+
+
+def render_context(context: str) -> None:
+    """Render the assembled LLM context string."""
+    console.print(Panel(
+        context,
+        title="[bold cyan]Assembled LLM Context[/bold cyan]",
+        border_style="dim cyan",
+        padding=(1, 2),
+    ))
+
+
+# ── Entry Point (manual test) ─────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+
+    console.rule("[bold cyan]Retriever — Manual Test[/bold cyan]")
+
+    retriever = Retriever()
+
+    # Test 1 — Macro query
+    console.rule("[cyan]Test 1 — Macro Query[/cyan]")
+    query = "what classes handle file parsing and walking"
+    chunks = retriever.retrieve(query, QueryType.MACRO, n_results=3)
+    render_chunks(chunks, title=f'Macro: "{query}"')
+
+    # Test 2 — Micro query
+    console.rule("[cyan]Test 2 — Micro Query[/cyan]")
+    query = "function that parses a single file and extracts classes"
+    chunks = retriever.retrieve(query, QueryType.MICRO, n_results=3)
+    render_chunks(chunks, title=f'Micro: "{query}"')
+    if chunks:
+        render_chunk_detail(chunks[0])
+
+    # Test 3 — Cross module dependencies
+    console.rule("[cyan]Test 3 — Dependency Retrieval[/cyan]")
+    func_name = sys.argv[1] if len(sys.argv) > 1 else "parse_file"
+    dep_chunks = retriever.retrieve_dependencies(func_name)
+    render_chunks(dep_chunks, title=f'Dependencies of: {func_name}')
+
+    # Test 4 — Build context string
+    console.rule("[cyan]Test 4 — Context Assembly[/cyan]")
+    all_chunks = retriever.retrieve("class structure and responsibilities",
+                                    QueryType.MACRO, n_results=4)
+    context = retriever.build_context(all_chunks)
+    console.print(f"[green]✔[/green] Context assembled: [cyan]{len(context)}[/cyan] chars")

store/call_graph.py

@@ -0,0 +1,577 @@
+"""
+call_graph.py
+-------------
+Builds a function-level call graph from parsed codebase (FileInfo objects)
+and persists it as call_graph.json for cross-module dependency analysis.
+
+Graph structure (stored in JSON):
+{
+    "module.FileName.ClassName.function_name": {
+        "id":         "module.FileName.ClassName.function_name",
+        "name":       "function_name",
+        "class_name": "ClassName",
+        "module":     "module",
+        "file":       "relative/path/to/file.py",
+        "calls":      ["other_func", "AnotherClass.method"],
+        "called_by":  ["parent_func", "caller_func"]
+    },
+    ...
+}
+
+Depends on:
+    - ast_parser.parse_codebase() → list[FileInfo]
+    - rich
+"""
+
+import json
+from pathlib import Path
+from dataclasses import dataclass, field
+from collections import defaultdict
+
+from rich.console import Console
+from rich.tree import Tree
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+from ingest.parse_ast import parse_codebase, FileInfo
+
+console = Console()
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+CALL_GRAPH_PATH = "./call_graph.json"
+
+
+# ── Node Model ────────────────────────────────────────────────────────────────
+
+@dataclass
+class CallNode:
+    """Represents a single function/method in the call graph."""
+    id:         str                    # unique fully-qualified ID
+    name:       str                    # function name
+    class_name: str                    # class name or "" for top-level
+    module:     str                    # top-level module/package
+    file:       str                    # relative file path
+    calls:      list[str] = field(default_factory=list)      # what it calls
+    called_by:  list[str] = field(default_factory=list)      # what calls it
+
+    def to_dict(self) -> dict:
+        return {
+            "id":         self.id,
+            "name":       self.name,
+            "class_name": self.class_name,
+            "module":     self.module,
+            "file":       self.file,
+            "calls":      self.calls,
+            "called_by":  self.called_by,
+        }
+
+    @staticmethod
+    def from_dict(data: dict) -> "CallNode":
+        return CallNode(
+            id=data["id"],
+            name=data["name"],
+            class_name=data.get("class_name", ""),
+            module=data["module"],
+            file=data["file"],
+            calls=data.get("calls", []),
+            called_by=data.get("called_by", []),
+        )
+
+
+# ── CallGraph ─────────────────────────────────────────────────────────────────
+
+class CallGraph:
+    """
+    Builds, stores, queries, and persists the function call graph
+    for a monolithic codebase.
+    """
+
+    def __init__(self):
+        # node_id → CallNode
+        self._graph: dict[str, CallNode] = {}
+        # name → list of node_ids (for fuzzy lookup by function name alone)
+        self._name_index: dict[str, list[str]] = defaultdict(list)
+
+    # ── Build ─────────────────────────────────────────────────────────────────
+
+    def build(self, parsed_files: list[FileInfo]) -> None:
+        """
+        Build the call graph from a list of parsed FileInfo objects.
+        Two passes:
+            1. Register all functions as nodes
+            2. Resolve call relationships and populate called_by
+
+        Args:
+            parsed_files: Output of ast_parser.parse_codebase().
+        """
+        self._graph.clear()
+        self._name_index.clear()
+
+        # Pass 1 — register all nodes
+        for file_info in parsed_files:
+            # Top-level functions
+            for func in file_info.functions:
+                node = CallNode(
+                    id=self._make_id(file_info, func.name, class_name=""),
+                    name=func.name,
+                    class_name="",
+                    module=file_info.module,
+                    file=file_info.relative,
+                    calls=func.calls,
+                )
+                self._register(node)
+
+            # Class methods
+            for cls in file_info.classes:
+                for method in cls.methods:
+                    node = CallNode(
+                        id=self._make_id(file_info, method.name, class_name=cls.name),
+                        name=method.name,
+                        class_name=cls.name,
+                        module=file_info.module,
+                        file=file_info.relative,
+                        calls=method.calls,
+                    )
+                    self._register(node)
+
+        # Pass 2 — resolve called_by relationships
+        for node in self._graph.values():
+            for raw_call in node.calls:
+                # Strip object prefix: "self.calculate" → "calculate"
+                callee_name = raw_call.split(".")[-1]
+                candidate_ids = self._name_index.get(callee_name, [])
+                for callee_id in candidate_ids:
+                    callee = self._graph.get(callee_id)
+                    if callee and node.id not in callee.called_by:
+                        callee.called_by.append(node.id)
+
+        total_nodes = len(self._graph)
+        total_edges = sum(len(n.calls) for n in self._graph.values())
+        console.print(
+            f"[green]✔[/green] Call graph built: "
+            f"[cyan]{total_nodes}[/cyan] nodes · "
+            f"[magenta]{total_edges}[/magenta] edges\n"
+        )
+
+    def _make_id(self, file_info: FileInfo,
+                 func_name: str,
+                 class_name: str) -> str:
+        """Generate a unique fully-qualified node ID."""
+        stem = Path(file_info.relative).stem   # filename without extension
+        parts = [file_info.module, stem]
+        if class_name:
+            parts.append(class_name)
+        parts.append(func_name)
+        return ".".join(parts)
+
+    def _register(self, node: CallNode) -> None:
+        """Register a node in the graph and name index."""
+        self._graph[node.id] = node
+        self._name_index[node.name].append(node.id)
+
+    # ── Persist ───────────────────────────────────────────────────────────────
+
+    def save(self, path: str = CALL_GRAPH_PATH) -> None:
+        """
+        Persist the call graph to a JSON file.
+
+        Args:
+            path: File path to write call_graph.json.
+        """
+        data = {node_id: node.to_dict() for node_id, node in self._graph.items()}
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        size_kb = round(Path(path).stat().st_size / 1024, 2)
+        console.print(
+            f"[green]✔[/green] Call graph saved to "
+            f"[cyan]{path}[/cyan] ({size_kb} KB)\n"
+        )
+
+    def load(self, path: str = CALL_GRAPH_PATH) -> None:
+        """
+        Load a persisted call graph from JSON.
+
+        Args:
+            path: File path to read call_graph.json from.
+
+        Raises:
+            FileNotFoundError: If the file does not exist.
+        """
+        graph_path = Path(path)
+        if not graph_path.exists():
+            raise FileNotFoundError(
+                f"Call graph not found at '{path}'. "
+                "Run build_and_save() first."
+            )
+
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        self._graph.clear()
+        self._name_index.clear()
+
+        for node_id, node_data in data.items():
+            node = CallNode.from_dict(node_data)
+            self._graph[node_id] = node
+            self._name_index[node.name].append(node_id)
+
+        console.print(
+            f"[green]✔[/green] Call graph loaded: "
+            f"[cyan]{len(self._graph)}[/cyan] nodes from "
+            f"[cyan]{path}[/cyan]\n"
+        )
+
+    # ── Query API ─────────────────────────────────────────────────────────────
+
+    def get_node(self, function_name: str,
+                 class_name: str | None = None) -> list[CallNode]:
+        """
+        Look up nodes by function name, optionally filtered by class.
+
+        Args:
+            function_name: Name of the function/method to look up.
+            class_name:    Optional class name to narrow results.
+
+        Returns:
+            List of matching CallNode objects.
+        """
+        candidate_ids = self._name_index.get(function_name, [])
+        nodes = [self._graph[nid] for nid in candidate_ids if nid in self._graph]
+
+        if class_name:
+            nodes = [n for n in nodes if n.class_name == class_name]
+
+        return nodes
+
+    def get_calls(self, function_name: str,
+                  class_name: str | None = None) -> list[CallNode]:
+        """
+        Get all functions that the given function calls (outgoing edges).
+
+        Args:
+            function_name: Source function name.
+            class_name:    Optional class scope.
+
+        Returns:
+            List of CallNode objects this function calls.
+        """
+        source_nodes = self.get_node(function_name, class_name)
+        if not source_nodes:
+            return []
+
+        results = []
+        seen = set()
+        for source in source_nodes:
+            for raw_call in source.calls:
+                callee_name = raw_call.split(".")[-1]
+                for callee_node in self.get_node(callee_name):
+                    if callee_node.id not in seen:
+                        seen.add(callee_node.id)
+                        results.append(callee_node)
+
+        return results
+
+    def get_called_by(self, function_name: str,
+                      class_name: str | None = None) -> list[CallNode]:
+        """
+        Get all functions that call the given function (incoming edges).
+
+        Args:
+            function_name: Target function name.
+            class_name:    Optional class scope.
+
+        Returns:
+            List of CallNode objects that call this function.
+        """
+        target_nodes = self.get_node(function_name, class_name)
+        if not target_nodes:
+            return []
+
+        results = []
+        seen = set()
+        for target in target_nodes:
+            for caller_id in target.called_by:
+                if caller_id not in seen and caller_id in self._graph:
+                    seen.add(caller_id)
+                    results.append(self._graph[caller_id])
+
+        return results
+
+    def get_impact(self, function_name: str,
+                   class_name: str | None = None,
+                   depth: int = 2) -> dict[str, list[CallNode]]:
+        """
+        Trace the impact of changing a function — who calls it,
+        who calls those callers, up to `depth` levels.
+
+        Args:
+            function_name: Function to analyze.
+            class_name:    Optional class scope.
+            depth:         How many levels up to trace (default 2).
+
+        Returns:
+            Dict mapping depth level string → list of affected CallNodes.
+        """
+        impact: dict[str, list[CallNode]] = {}
+        current_level = self.get_node(function_name, class_name)
+        visited = {n.id for n in current_level}
+
+        for level in range(1, depth + 1):
+            next_level = []
+            for node in current_level:
+                for caller_id in node.called_by:
+                    if caller_id not in visited and caller_id in self._graph:
+                        visited.add(caller_id)
+                        next_level.append(self._graph[caller_id])
+            if not next_level:
+                break
+            impact[f"level_{level}"] = next_level
+            current_level = next_level
+
+        return impact
+
+    def stats(self) -> dict:
+        """Return summary statistics for the call graph."""
+        total_edges = sum(len(n.calls) for n in self._graph.values())
+        modules = list({n.module for n in self._graph.values()})
+        isolated = [n for n in self._graph.values()
+                    if not n.calls and not n.called_by]
+        return {
+            "total_nodes":    len(self._graph),
+            "total_edges":    total_edges,
+            "modules":        modules,
+            "isolated_nodes": len(isolated),
+        }
+
+    def is_loaded(self) -> bool:
+        """Return True if graph has been built or loaded."""
+        return len(self._graph) > 0
+
+    # ── Rich Renderers ────────────────────────────────────────────────────────
+
+    def render_stats(self) -> None:
+        """Render call graph statistics as a rich panel."""
+        s = self.stats()
+
+        table = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+        table.add_column(style="dim")
+        table.add_column(style="bold white")
+
+        table.add_row("Total nodes",    str(s["total_nodes"]))
+        table.add_row("Total edges",    str(s["total_edges"]))
+        table.add_row("Modules",        ", ".join(s["modules"]))
+        table.add_row("Isolated nodes", str(s["isolated_nodes"]))
+        table.add_row(
+            "Status",
+            "[bold green]✔ Loaded[/bold green]"
+            if self.is_loaded()
+            else "[bold red]✘ Empty[/bold red]"
+        )
+
+        console.print(Panel(
+            table,
+            title="[bold cyan]Call Graph Stats[/bold cyan]",
+            border_style="cyan",
+        ))
+
+    def render_node(self, node: CallNode) -> None:
+        """Render a single node with its calls and callers."""
+        scope = f"{node.class_name}.{node.name}" if node.class_name else node.name
+
+        calls_str    = "\n".join(f"  → {c}" for c in node.calls) or "  [dim]none[/dim]"
+        called_by_str = "\n".join(f"  ← {c}" for c in node.called_by) or "  [dim]none[/dim]"
+
+        content = Text()
+        content.append("Module:  ", style="dim")
+        content.append(f"{node.module}\n")
+        content.append("File:    ", style="dim")
+        content.append(f"{node.file}\n\n")
+        content.append("Calls:\n", style="bold cyan")
+        content.append(calls_str + "\n\n")
+        content.append("Called by:\n", style="bold magenta")
+        content.append(called_by_str)
+
+        console.print(Panel(
+            content,
+            title=f"[bold white]{scope}[/bold white]",
+            border_style="cyan",
+        ))
+
+    def render_impact(self, function_name: str,
+                      impact: dict[str, list[CallNode]]) -> None:
+        """Render the impact tree of a function change."""
+        root = Tree(
+            f"[bold yellow]⚡ Impact of changing:[/bold yellow] "
+            f"[bold white]{function_name}[/bold white]",
+            guide_style="dim yellow",
+        )
+
+        if not impact:
+            root.add("[dim]No callers found — isolated function.[/dim]")
+        else:
+            for level, nodes in impact.items():
+                level_num = level.split("_")[1]
+                level_branch = root.add(
+                    f"[bold cyan]Level {level_num} — {len(nodes)} affected[/bold cyan]"
+                )
+                for node in nodes:
+                    scope = (
+                        f"{node.class_name}.{node.name}"
+                        if node.class_name else node.name
+                    )
+                    level_branch.add(
+                        f"[magenta]{scope}[/magenta]  "
+                        f"[dim]{node.file}[/dim]"
+                    )
+
+        console.print(root)
+
+    def render_dependencies(self, function_name: str,
+                            calls: list[CallNode],
+                            called_by: list[CallNode]) -> None:
+        """Render outgoing and incoming dependencies for a function."""
+        table = Table(
+            "Direction", "Function", "Class", "Module", "File",
+            box=box.ROUNDED,
+            header_style="bold bright_cyan",
+            border_style="cyan",
+            show_lines=True,
+            title=f"Dependencies: {function_name}",
+        )
+
+        for node in calls:
+            table.add_row(
+                "[cyan]→ calls[/cyan]",
+                node.name,
+                node.class_name or "[dim]—[/dim]",
+                node.module,
+                node.file,
+            )
+
+        for node in called_by:
+            table.add_row(
+                "[magenta]← called by[/magenta]",
+                node.name,
+                node.class_name or "[dim]—[/dim]",
+                node.module,
+                node.file,
+            )
+
+        if not calls and not called_by:
+            console.print(f"[yellow]No dependencies found for '{function_name}'.[/yellow]")
+        else:
+            console.print(table)
+
+
+# ── Convenience Pipeline ──────────────────────────────────────────────────────
+
+def build_and_save(root_path: str,
+                   graph_path: str = CALL_GRAPH_PATH) -> CallGraph:
+    """
+    Full pipeline: parse codebase → build graph → save to JSON.
+
+    Args:
+        root_path:  Absolute path to the monolithic codebase root.
+        graph_path: Path to write call_graph.json.
+
+    Returns:
+        Built and saved CallGraph instance.
+    """
+    console.rule("[bold cyan]Call Graph Builder[/bold cyan]")
+    console.print(f"[bold]📂 Root:[/bold] {root_path}\n")
+
+    parsed_files = parse_codebase(root_path)
+
+    graph = CallGraph()
+    graph.build(parsed_files)
+    graph.save(graph_path)
+    graph.render_stats()
+
+    return graph
+
+
+def load_graph(graph_path: str = CALL_GRAPH_PATH) -> CallGraph:
+    """
+    Load a persisted call graph from JSON.
+
+    Args:
+        graph_path: Path to call_graph.json.
+
+    Returns:
+        Loaded CallGraph instance.
+    """
+    graph = CallGraph()
+    graph.load(graph_path)
+    return graph
+
+
+# ── Singleton Access ──────────────────────────────────────────────────────────
+
+_graph_instance: CallGraph | None = None
+
+
+def get_call_graph(graph_path: str = CALL_GRAPH_PATH) -> CallGraph:
+    """
+    Return a singleton CallGraph instance.
+    Loads from JSON on first call, reuses on subsequent calls.
+
+    Args:
+        graph_path: Path to call_graph.json.
+
+    Returns:
+        Shared CallGraph instance.
+    """
+    global _graph_instance
+    if _graph_instance is None:
+        _graph_instance = load_graph(graph_path)
+    return _graph_instance
+
+
+# ── Entry Point ───────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        console.print(
+            "[red]Usage:[/red] python call_graph.py <codebase_path> "
+            "[function_name]"
+        )
+        sys.exit(1)
+
+    root  = sys.argv[1]
+    query = sys.argv[2] if len(sys.argv) > 2 else None
+
+    # Build and save
+    graph = build_and_save(root)
+
+    if query:
+        console.rule(f"[bold cyan]Query: {query}[/bold cyan]")
+
+        # Node detail
+        nodes = graph.get_node(query)
+        if not nodes:
+            console.print(f"[yellow]Function '{query}' not found in graph.[/yellow]")
+        else:
+            for node in nodes:
+                graph.render_node(node)
+
+        # Dependencies
+        calls     = graph.get_calls(query)
+        called_by = graph.get_called_by(query)
+        graph.render_dependencies(query, calls, called_by)
+
+        # Impact analysis
+        impact = graph.get_impact(query, depth=2)
+        graph.render_impact(query, impact)
+    else:
+        # Show sample nodes
+        console.rule("[cyan]Sample Nodes[/cyan]")
+        sample = list(graph._graph.values())[:5]
+        for node in sample:
+            graph.render_node(node)

store/vector_store.py

@@ -0,0 +1,153 @@
+"""
+vector_store.py
+---------------
+Pinecone-backed vector store interface for the Codebase Oracle system.
+Reads from the same Pinecone index used by embed.py via namespaces.
+
+Collections (as Pinecone namespaces):
+    - class_chunks    : one chunk per class (macro / cross-module queries)
+    - function_chunks : one chunk per function/method (micro queries)
+
+Depends on:
+    - pinecone
+    - ingest.embed (get_pinecone_index)
+    - rich
+"""
+
+from dataclasses import dataclass
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.text import Text
+from rich import box
+
+from ingest.embed import get_pinecone_index, CLASS_COLLECTION, FUNCTION_COLLECTION
+
+console = Console()
+
+
+# ── Result Model ──────────────────────────────────────────────────────────────
+
+@dataclass
+class ChunkResult:
+    """Represents a single retrieved chunk."""
+    id:       str
+    text:     str
+    metadata: dict
+    distance: float | None = None
+
+    @property
+    def name(self) -> str:
+        return self.metadata.get("name", "unknown")
+
+    @property
+    def module(self) -> str:
+        return self.metadata.get("module", "unknown")
+
+    @property
+    def file(self) -> str:
+        return self.metadata.get("file", "unknown")
+
+    @property
+    def chunk_type(self) -> str:
+        return self.metadata.get("type", "unknown")
+
+    @property
+    def class_name(self) -> str:
+        return self.metadata.get("class_name", "")
+
+    @property
+    def relevance(self) -> float:
+        if self.distance is None:
+            return 0.0
+        return round(1 / (1 + self.distance), 4)
+
+
+# ── VectorStore ───────────────────────────────────────────────────────────────
+
+class VectorStore:
+    """
+    Pinecone-backed interface for stats and tree queries.
+    Reuses the same index as embed.py — no duplicate client.
+    """
+
+    def __init__(self):
+        self._index = get_pinecone_index()
+        console.print("[green]✔[/green] VectorStore ready (Pinecone)\n")
+
+    def _count(self, namespace: str) -> int:
+        """Return approximate vector count in a namespace."""
+        stats = self._index.describe_index_stats()
+        return stats["namespaces"].get(namespace, {}).get("vector_count", 0)
+
+    def stats(self) -> dict:
+        class_count = self._count(CLASS_COLLECTION)
+        func_count  = self._count(FUNCTION_COLLECTION)
+        return {
+            "class_chunks":    class_count,
+            "function_chunks": func_count,
+            "total":           class_count + func_count,
+        }
+
+    def is_indexed(self) -> bool:
+        s = self.stats()
+        return s["total"] > 0
+
+    def get_all(self, namespace: str, limit: int = 10) -> list[ChunkResult]:
+        """
+        Fetch chunks from a namespace without a query vector.
+        Pinecone does not support scan — we use a zero vector as proxy.
+        """
+        from config.config import EMBEDDING_DIM
+        zero_vector = [0.0] * EMBEDDING_DIM
+
+        results = self._index.query(
+            vector=zero_vector,
+            top_k=limit,
+            namespace=namespace,
+            include_metadata=True,
+        )
+
+        output = []
+        for match in results["matches"]:
+            meta = dict(match["metadata"])
+            text = meta.pop("text", "")
+            output.append(ChunkResult(
+                id=match["id"],
+                text=text,
+                metadata=meta,
+                distance=1 - match["score"],
+            ))
+        return output
+
+    def render_stats(self) -> None:
+        s = self.stats()
+        table = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+        table.add_column(style="dim")
+        table.add_column(style="bold white")
+        table.add_row("Class chunks",    str(s["class_chunks"]))
+        table.add_row("Function chunks", str(s["function_chunks"]))
+        table.add_row("Total chunks",    str(s["total"]))
+        table.add_row(
+            "Status",
+            "[bold green]✔ Indexed[/bold green]"
+            if self.is_indexed()
+            else "[bold red]✘ Not indexed[/bold red]"
+        )
+        console.print(Panel(
+            table,
+            title="[bold cyan]VectorStore Stats[/bold cyan]",
+            border_style="cyan",
+        ))
+
+
+# ── Singleton ─────────────────────────────────────────────────────────────────
+
+_store_instance: VectorStore | None = None
+
+
+def get_vector_store() -> VectorStore:
+    global _store_instance
+    if _store_instance is None:
+        _store_instance = VectorStore()
+    return _store_instance

ui/index.html

@@ -0,0 +1,121 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Codebase Oracle</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;700&family=Syne:wght@400;600;700;800&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="static/style.css" />
+</head>
+<body>
+
+  <!-- ── Top Bar ─────────────────────────────────────────────────────────── -->
+  <header class="topbar">
+    <div class="topbar__brand">
+      <span class="topbar__icon">⬡</span>
+      <span class="topbar__title">Codebase Oracle</span>
+    </div>
+
+    <div class="topbar__index">
+      <input
+        id="pathInput"
+        class="path-input"
+        type="text"
+        placeholder="/absolute/path/to/your/codebase"
+        autocomplete="off"
+        spellcheck="false"
+      />
+      <label class="btn btn--secondary" for="zipInput" id="zipLabel">Upload ZIP</label>
+      <input id="zipInput" type="file" accept=".zip" style="display:none" />
+      <button id="indexBtn" class="btn btn--primary">
+        <span id="indexBtnText">Index</span>
+        <span id="indexSpinner" class="spinner hidden"></span>
+      </button>
+    </div>
+
+    <div id="statusBadge" class="status-badge status-badge--idle">
+      <span class="status-badge__dot"></span>
+      <span id="statusText">Not indexed</span>
+    </div>
+  </header>
+
+  <!-- ── Main Layout ─────────────────────────────────────────────────────── -->
+  <div class="workspace">
+
+    <!-- Sidebar -->
+    <aside class="sidebar">
+      <div class="sidebar__header">
+        <span class="sidebar__label">Explorer</span>
+        <span id="chunkCount" class="sidebar__count"></span>
+      </div>
+      <div id="treeContainer" class="tree-container">
+        <div class="tree-placeholder">
+          <span class="tree-placeholder__icon">⬡</span>
+          <p>Index a codebase to explore its structure</p>
+        </div>
+      </div>
+    </aside>
+
+    <!-- Chat Area -->
+    <main class="chat">
+
+      <!-- Query Type Selector -->
+      <div class="query-controls">
+        <div class="query-type-group" id="queryTypeGroup">
+          <button class="query-type-btn active" data-type="micro">Micro</button>
+          <button class="query-type-btn" data-type="macro">Macro</button>
+          <button class="query-type-btn" data-type="cross_module">Cross-Module</button>
+        </div>
+
+        <!-- Macro subtype (shown only when macro selected) -->
+        <div id="macroSubtypes" class="macro-subtypes hidden">
+          <button class="subtype-btn active" data-subtype="overall_architecture">Architecture</button>
+          <button class="subtype-btn" data-subtype="module_responsibility">Module</button>
+          <button class="subtype-btn" data-subtype="data_flow">Data Flow</button>
+        </div>
+
+        <!-- Contextual inputs -->
+        <div id="contextInputs" class="context-inputs">
+          <input id="functionInput" class="context-field" type="text" placeholder="Function name" autocomplete="off" spellcheck="false" />
+          <input id="classInput"    class="context-field" type="text" placeholder="Class name (optional)" autocomplete="off" spellcheck="false" />
+          <input id="moduleInput"   class="context-field hidden" type="text" placeholder="Module name" autocomplete="off" spellcheck="false" />
+        </div>
+      </div>
+
+      <!-- Messages -->
+      <div id="messages" class="messages">
+        <div class="message message--system">
+          <div class="message__content">
+            <p>Welcome to <strong>Codebase Oracle</strong>. Index a codebase using the path bar above, then ask anything about it.</p>
+          </div>
+        </div>
+      </div>
+
+      <!-- Input Bar -->
+      <div class="input-bar">
+        <textarea
+          id="queryInput"
+          class="query-textarea"
+          placeholder="Ask anything about the codebase…"
+          rows="1"
+          spellcheck="false"
+        ></textarea>
+        <button id="sendBtn" class="btn btn--send" disabled>
+          <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="22" y1="2" x2="11" y2="13"></line>
+            <polygon points="22 2 15 22 11 13 2 9 22 2"></polygon>
+          </svg>
+        </button>
+      </div>
+
+    </main>
+  </div>
+
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/9.1.6/marked.min.js"></script>
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css" />
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+  <script src="static/app.js"></script>
+</body>
+</html>

ui/static/app.js

@@ -0,0 +1,392 @@
+/* app.js — Codebase Oracle frontend logic */
+
+const API = 'http://localhost:8000';
+
+// ── State ─────────────────────────────────────────────────────────────────────
+const state = {
+  indexed:      false,
+  querying:     false,
+  queryType:    'micro',
+  macroSubtype: 'overall_architecture',
+  lastResponse: '',
+};
+
+// ── DOM Refs ──────────────────────────────────────────────────────────────────
+const $ = id => document.getElementById(id);
+
+const dom = {
+  pathInput:     $('pathInput'),
+  zipInput:      $('zipInput'),
+  zipLabel:      $('zipLabel'),
+  indexBtn:      $('indexBtn'),
+  indexBtnText:  $('indexBtnText'),
+  indexSpinner:  $('indexSpinner'),
+  statusBadge:   $('statusBadge'),
+  statusText:    $('statusText'),
+  chunkCount:    $('chunkCount'),
+  treeContainer: $('treeContainer'),
+  messages:      $('messages'),
+  queryInput:    $('queryInput'),
+  sendBtn:       $('sendBtn'),
+  functionInput: $('functionInput'),
+  classInput:    $('classInput'),
+  moduleInput:   $('moduleInput'),
+  macroSubtypes: $('macroSubtypes'),
+};
+
+// ── Marked config ─────────────────────────────────────────────────────────────
+marked.setOptions({
+  breaks: true,
+  gfm:    true,
+});
+
+marked.use({
+  renderer: (() => {
+    const r = new marked.Renderer();
+    r.code = (code, lang) => {
+      const highlighted = (lang && hljs.getLanguage(lang))
+        ? hljs.highlight(code, { language: lang }).value
+        : hljs.highlightAuto(code).value;
+      return `<pre><code class="hljs language-${lang || ''}">${highlighted}</code></pre>`;
+    };
+    return r;
+  })(),
+});
+
+// ── Status ────────────────────────────────────────────────────────────────────
+function setStatus(type, text) {
+  dom.statusBadge.className = `status-badge status-badge--${type}`;
+  dom.statusText.textContent = text;
+}
+
+// ── Index ─────────────────────────────────────────────────────────────────────
+dom.zipInput.addEventListener('change', () => {
+  if (dom.zipInput.files.length > 0) {
+    dom.zipLabel.textContent = dom.zipInput.files[0].name;
+    dom.pathInput.value = '';
+  }
+});
+
+dom.indexBtn.addEventListener('click', async () => {
+  const path    = dom.pathInput.value.trim();
+  const zipFile = dom.zipInput.files[0];
+
+  if (!path && !zipFile) {
+    appendMessage('error', null, '❌ Provide an absolute path or upload a ZIP file.');
+    return;
+  }
+
+  dom.indexBtn.disabled = true;
+  dom.indexBtnText.classList.add('hidden');
+  dom.indexSpinner.classList.remove('hidden');
+  setStatus('indexing', 'Indexing…');
+
+  try {
+    let res, data;
+
+    if (zipFile) {
+      const form = new FormData();
+      form.append('file', zipFile);
+      res  = await fetch(`${API}/upload-index`, { method: 'POST', body: form });
+      data = await res.json();
+    } else {
+      res  = await fetch(`${API}/index`, {
+        method:  'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body:    JSON.stringify({ root_path: path }),
+      });
+      data = await res.json();
+    }
+
+    if (!res.ok) throw new Error(data.detail || 'Indexing failed');
+
+    const label = zipFile ? zipFile.name : path;
+    state.indexed = true;
+    setStatus('ready', `Ready · ${data.total_chunks} chunks`);
+    dom.chunkCount.textContent = `${data.total_chunks} chunks`;
+    dom.sendBtn.disabled = false;
+
+    appendMessage('system', null,
+      `✔ Indexed **${label}**\n\n` +
+      `| Metric | Value |\n|--------|-------|\n` +
+      `| Class chunks | ${data.class_chunks} |\n` +
+      `| Function chunks | ${data.function_chunks} |\n` +
+      `| Total chunks | ${data.total_chunks} |\n` +
+      `| Graph nodes | ${data.graph_nodes} |\n` +
+      `| Graph edges | ${data.graph_edges} |`
+    );
+
+    loadTree();
+
+  } catch (err) {
+    setStatus('error', 'Error');
+    appendMessage('error', null, `❌ ${err.message}`);
+  } finally {
+    dom.indexBtn.disabled = false;
+    dom.indexBtnText.classList.remove('hidden');
+    dom.indexSpinner.classList.add('hidden');
+    dom.zipLabel.textContent = 'Upload ZIP';
+    dom.zipInput.value = '';
+  }
+});
+
+// ── Tree ──────────────────────────────────────────────────────────────────────
+async function loadTree() {
+  try {
+    const res  = await fetch(`${API}/tree`);
+    const data = await res.json();
+
+    if (!data.success || !data.tree.length) {
+      dom.treeContainer.innerHTML =
+        '<div class="tree-placeholder"><p>No structure found.</p></div>';
+      return;
+    }
+
+    dom.treeContainer.innerHTML = '';
+    data.tree.forEach(node => {
+      dom.treeContainer.appendChild(buildTreeNode(node, 0));
+    });
+
+  } catch (err) {
+    console.error('Tree load error:', err);
+  }
+}
+
+const ICONS = {
+  module:   { icon: '📦', cls: 'icon-module'   },
+  file:     { icon: '📄', cls: 'icon-file'     },
+  class:    { icon: '🔷', cls: 'icon-class'    },
+  function: { icon: 'ƒ',  cls: 'icon-function' },
+};
+
+function buildTreeNode(node, depth) {
+  const wrap    = document.createElement('div');
+  const hasKids = node.children && node.children.length > 0;
+  const info    = ICONS[node.type] || ICONS.file;
+
+  wrap.className     = 'tree-node';
+  wrap.dataset.depth = depth;
+
+  const row    = document.createElement('div');
+  row.className = 'tree-node__row';
+
+  const toggle = document.createElement('span');
+  toggle.className   = 'tree-node__toggle';
+  toggle.textContent = hasKids ? '▶' : '';
+
+  const icon  = document.createElement('span');
+  icon.className   = `tree-node__icon ${info.cls}`;
+  icon.textContent = info.icon;
+
+  const label = document.createElement('span');
+  label.className   = 'tree-node__name';
+  label.textContent = node.name;
+
+  row.append(toggle, icon, label);
+  wrap.appendChild(row);
+
+  if (hasKids) {
+    const children = document.createElement('div');
+    children.className = 'tree-node__children';
+    node.children.forEach(child => {
+      children.appendChild(buildTreeNode(child, depth + 1));
+    });
+    wrap.appendChild(children);
+
+    row.addEventListener('click', () => {
+      const open = children.classList.toggle('open');
+      toggle.classList.toggle('open', open);
+    });
+  }
+
+  // Click leaf → auto-fill inputs
+  if (node.type === 'function') {
+    row.addEventListener('click', () => {
+      dom.functionInput.value = node.name;
+      highlightRow(row);
+    });
+  }
+  if (node.type === 'class') {
+    row.addEventListener('click', () => {
+      dom.classInput.value = node.name;
+      highlightRow(row);
+    });
+  }
+
+  return wrap;
+}
+
+function highlightRow(row) {
+  document.querySelectorAll('.tree-node__row.selected')
+    .forEach(r => r.classList.remove('selected'));
+  row.classList.add('selected');
+}
+
+// ── Query Type Tabs ───────────────────────────────────────────────────────────
+document.querySelectorAll('.query-type-btn').forEach(btn => {
+  btn.addEventListener('click', () => {
+    document.querySelectorAll('.query-type-btn')
+      .forEach(b => b.classList.remove('active'));
+    btn.classList.add('active');
+    state.queryType = btn.dataset.type;
+    updateControls();
+  });
+});
+
+document.querySelectorAll('.subtype-btn').forEach(btn => {
+  btn.addEventListener('click', () => {
+    document.querySelectorAll('.subtype-btn')
+      .forEach(b => b.classList.remove('active'));
+    btn.classList.add('active');
+    state.macroSubtype = btn.dataset.subtype;
+    updateControls();
+  });
+});
+
+function updateControls() {
+  const isMacro = state.queryType === 'macro';
+  const needsModule =
+    isMacro && state.macroSubtype === 'module_responsibility';
+
+  dom.macroSubtypes.classList.toggle('hidden', !isMacro);
+  dom.functionInput.classList.toggle('hidden', isMacro);
+  dom.classInput.classList.toggle('hidden', isMacro);
+  dom.moduleInput.classList.toggle('hidden', !needsModule);
+}
+
+// ── Textarea auto-resize ──────────────────────────────────────────────────────
+dom.queryInput.addEventListener('input', () => {
+  dom.queryInput.style.height = 'auto';
+  dom.queryInput.style.height =
+    Math.min(dom.queryInput.scrollHeight, 160) + 'px';
+});
+
+dom.queryInput.addEventListener('keydown', e => {
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault();
+    if (!dom.sendBtn.disabled) sendQuery();
+  }
+});
+
+dom.sendBtn.addEventListener('click', sendQuery);
+
+// ── Send Query ────────────────────────────────────────────────────────────────
+async function sendQuery() {
+  const query = dom.queryInput.value.trim();
+  if (!query || state.querying) return;
+
+  const badge = [
+    state.queryType,
+    state.queryType === 'macro'
+      ? state.macroSubtype.replace(/_/g, ' ')
+      : dom.functionInput.value.trim(),
+  ].filter(Boolean).join(' · ');
+
+  appendMessage('user', badge, query);
+  dom.queryInput.value = '';
+  dom.queryInput.style.height = 'auto';
+
+  const thinkId = appendThinking();
+  state.querying       = true;
+  dom.sendBtn.disabled = true;
+
+  try {
+    const res = await fetch(`${API}/query`, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        query_type:        state.queryType,
+        query,
+        subtype:           state.queryType === 'macro' ? state.macroSubtype : '',
+        function_name:     dom.functionInput.value.trim(),
+        class_name:        dom.classInput.value.trim(),
+        module_name:       dom.moduleInput.value.trim(),
+        followup:          !!state.lastResponse,
+        previous_response: state.lastResponse,
+      }),
+    });
+
+    const data = await res.json();
+    removeMessage(thinkId);
+
+    if (!res.ok)       throw new Error(data.detail  || 'Query failed');
+    if (!data.success) throw new Error(data.error   || 'No result');
+
+    state.lastResponse = data.content;
+    appendMessage('assistant', buildMetaBadge(data.metadata), data.content);
+
+  } catch (err) {
+    removeMessage(thinkId);
+    appendMessage('error', null, `❌ ${err.message}`);
+  } finally {
+    state.querying       = false;
+    dom.sendBtn.disabled = false;
+  }
+}
+
+// ── Messages ──────────────────────────────────────────────────────────────────
+let msgCounter = 0;
+
+function appendMessage(role, badge, content) {
+  const id  = `msg-${++msgCounter}`;
+  const div = document.createElement('div');
+  div.id        = id;
+  div.className = `message message--${role}`;
+
+  const roleLabel = {
+    user: 'You', assistant: 'Oracle',
+    system: 'System', error: 'Error', thinking: 'Thinking',
+  }[role] || role;
+
+  let html = `<div class="message__meta">
+    <span class="message__role">${roleLabel}</span>
+    ${badge ? `<span class="message__badge">${badge}</span>` : ''}
+  </div>
+  <div class="message__content">`;
+
+  html += role === 'thinking'
+    ? `<span class="spinner"></span>${content}`
+    : marked.parse(content || '');
+
+  html += `</div>`;
+  div.innerHTML = html;
+
+  dom.messages.appendChild(div);
+  dom.messages.scrollTop = dom.messages.scrollHeight;
+  return id;
+}
+
+function appendThinking() {
+  return appendMessage('thinking', null, 'Analyzing codebase…');
+}
+
+function removeMessage(id) {
+  document.getElementById(id)?.remove();
+}
+
+function buildMetaBadge(meta) {
+  if (!meta) return null;
+  return [
+    meta.query_type,
+    meta.function_name,
+    meta.chunks_used   ? `${meta.chunks_used} chunks`   : null,
+    meta.context_chars ? `${meta.context_chars} chars`  : null,
+  ].filter(Boolean).join(' · ');
+}
+
+// ── Init ──────────────────────────────────────────────────────────────────────
+(async () => {
+  try {
+    const res  = await fetch(`${API}/status`);
+    const data = await res.json();
+    if (data.indexed) {
+      state.indexed = true;
+      setStatus('ready', `Ready · ${data.total_chunks} chunks`);
+      dom.chunkCount.textContent = `${data.total_chunks} chunks`;
+      dom.sendBtn.disabled = false;
+      loadTree();
+    }
+  } catch { /* server not up yet — stay idle */ }
+
+  updateControls();
+})();

ui/static/style.css

@@ -0,0 +1,587 @@
+/* ── Reset & Base ──────────────────────────────────────────────────────────── */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --bg-base:        #0e0e10;
+  --bg-surface:     #141416;
+  --bg-elevated:    #1a1a1e;
+  --bg-hover:       #202026;
+  --bg-active:      #25252d;
+  --border:         #2a2a32;
+  --border-focus:   #4a90e8;
+  --text-primary:   #d4d4d8;
+  --text-secondary: #71717a;
+  --text-muted:     #3f3f46;
+  --text-bright:    #f4f4f5;
+  --accent:         #4a90e8;
+  --accent-dim:     #1e3a5f;
+  --accent-glow:    rgba(74, 144, 232, 0.15);
+  --green:          #4ade80;
+  --yellow:         #facc15;
+  --red:            #f87171;
+  --purple:         #c084fc;
+  --topbar-h:       60px;
+  --sidebar-w:      320px;
+  --radius:         6px;
+  --radius-lg:      10px;
+  --font-ui:        'Syne', sans-serif;
+  --font-mono:      'JetBrains Mono', monospace;
+  --transition:     150ms ease;
+}
+
+html, body {
+  height: 100%;
+  overflow: hidden;
+  background: var(--bg-base);
+  color: var(--text-primary);
+  font-family: var(--font-ui);
+  font-size: 16px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+
+::-webkit-scrollbar { width: 5px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: var(--text-muted); }
+
+/* ── Topbar ────────────────────────────────────────────────────────────────── */
+.topbar {
+  position: fixed;
+  top: 0; left: 0; right: 0;
+  height: var(--topbar-h);
+  background: var(--bg-surface);
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 0 20px;
+  z-index: 100;
+}
+
+.topbar__brand {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-shrink: 0;
+}
+
+.topbar__icon {
+  font-size: 20px;
+  color: var(--accent);
+  animation: pulse 3s ease-in-out infinite;
+}
+
+@keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }
+
+.topbar__title {
+  font-weight: 800;
+  font-size: 15px;
+  letter-spacing: 0.04em;
+  color: var(--text-bright);
+  white-space: nowrap;
+}
+
+.topbar__index {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 680px;
+}
+
+.path-input {
+  flex: 1;
+  height: 34px;
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  padding: 0 12px;
+  outline: none;
+  transition: border-color var(--transition), box-shadow var(--transition);
+}
+
+.path-input:focus {
+  border-color: var(--border-focus);
+  box-shadow: 0 0 0 3px var(--accent-glow);
+}
+
+.path-input::placeholder { color: var(--text-muted); }
+
+/* ── Buttons ───────────────────────────────────────────────────────────────── */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  border: none;
+  border-radius: var(--radius);
+  cursor: pointer;
+  font-family: var(--font-ui);
+  font-weight: 600;
+  font-size: 13px;
+  transition: background var(--transition), transform var(--transition);
+  white-space: nowrap;
+  outline: none;
+}
+
+.btn:active:not(:disabled) { transform: scale(0.97); }
+.btn:disabled { opacity: 0.4; cursor: not-allowed; }
+
+.btn--primary {
+  height: 34px;
+  padding: 0 18px;
+  background: var(--accent);
+  color: #fff;
+}
+.btn--primary:hover:not(:disabled) { background: #3b7dd8; }
+
+.btn--send {
+  width: 40px; height: 40px;
+  background: var(--accent);
+  color: #fff;
+  border-radius: var(--radius);
+  flex-shrink: 0;
+}
+.btn--send:hover:not(:disabled) { background: #3b7dd8; }
+
+/* ── Status Badge ──────────────────────────────────────────────────────────── */
+.status-badge {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 12px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+  flex-shrink: 0;
+  border: 1px solid transparent;
+  font-family: var(--font-mono);
+}
+
+.status-badge__dot {
+  width: 6px; height: 6px;
+  border-radius: 50%;
+}
+
+.status-badge--idle    { background: var(--bg-elevated); border-color: var(--border); color: var(--text-secondary); }
+.status-badge--idle    .status-badge__dot { background: var(--text-muted); }
+
+.status-badge--indexing { background: rgba(250,204,21,.08); border-color: rgba(250,204,21,.3); color: var(--yellow); }
+.status-badge--indexing .status-badge__dot { background: var(--yellow); animation: blink .8s ease-in-out infinite; }
+
+.status-badge--ready   { background: rgba(74,222,128,.08); border-color: rgba(74,222,128,.3); color: var(--green); }
+.status-badge--ready   .status-badge__dot { background: var(--green); }
+
+.status-badge--error   { background: rgba(248,113,113,.08); border-color: rgba(248,113,113,.3); color: var(--red); }
+.status-badge--error   .status-badge__dot { background: var(--red); }
+
+@keyframes blink { 0%,100% { opacity:1; } 50% { opacity:.2; } }
+
+/* ── Workspace ─────────────────────────────────────────────────────────────── */
+.workspace {
+  display: flex;
+  position: fixed;
+  top: var(--topbar-h); left: 0; right: 0; bottom: 0;
+}
+
+/* ── Sidebar ───────────────────────────────────────────────────────────────── */
+.sidebar {
+  width: var(--sidebar-w);
+  flex-shrink: 0;
+  background: var(--bg-surface);
+  border-right: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.sidebar__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.sidebar__label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--text-secondary);
+}
+
+.sidebar__count {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--text-muted);
+}
+
+.tree-container {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 0;
+}
+
+.tree-placeholder {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  gap: 12px;
+  padding: 40px 20px;
+  text-align: center;
+}
+
+.tree-placeholder__icon { font-size: 32px; color: var(--text-muted); opacity: .5; }
+.tree-placeholder p { font-size: 12px; color: var(--text-muted); line-height: 1.6; }
+
+/* ── Tree Nodes ────────────────────────────────────────────────────────────── */
+.tree-node { user-select: none; }
+
+.tree-node__row {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  padding: 3px 8px;
+  cursor: pointer;
+  border-radius: 4px;
+  margin: 0 6px;
+  transition: background var(--transition);
+  min-height: 24px;
+}
+
+.tree-node__row:hover   { background: var(--bg-hover); }
+.tree-node__row.selected { background: var(--accent-dim); }
+
+.tree-node__toggle {
+  width: 14px; text-align: center;
+  font-size: 9px;
+  color: var(--text-muted);
+  flex-shrink: 0;
+  transition: transform var(--transition);
+}
+.tree-node__toggle.open { transform: rotate(90deg); }
+
+.tree-node__icon  { font-size: 12px; flex-shrink: 0; }
+.tree-node__name  {
+  font-family: var(--font-mono);
+  font-size: 13px;
+  color: var(--text-primary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tree-node__children         { display: none; }
+.tree-node__children.open    { display: block; }
+
+.tree-node[data-depth="1"] .tree-node__row { padding-left: 20px; }
+.tree-node[data-depth="2"] .tree-node__row { padding-left: 34px; }
+.tree-node[data-depth="3"] .tree-node__row { padding-left: 48px; }
+
+.icon-module   { color: var(--yellow); }
+.icon-file     { color: #60a5fa; }
+.icon-class    { color: var(--purple); }
+.icon-function { color: var(--green); }
+
+/* ── Chat ──────────────────────────────────────────────────────────────────── */
+.chat {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+/* ── Query Controls ────────────────────────────────────────────────────────── */
+.query-controls {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-surface);
+  flex-shrink: 0;
+}
+
+.query-type-group, .macro-subtypes {
+  display: flex;
+  gap: 4px;
+  flex-wrap: wrap;
+}
+
+.query-type-btn, .subtype-btn {
+  padding: 7px 18px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  background: transparent;
+  color: var(--text-secondary);
+  font-family: var(--font-ui);
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: all var(--transition);
+  letter-spacing: 0.02em;
+}
+
+.query-type-btn:hover, .subtype-btn:hover {
+  border-color: var(--accent);
+  color: var(--text-primary);
+}
+
+.query-type-btn.active, .subtype-btn.active {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.context-inputs {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.context-field {
+  height: 30px;
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  padding: 0 10px;
+  outline: none;
+  min-width: 160px;
+  transition: border-color var(--transition), box-shadow var(--transition);
+}
+
+.context-field:focus {
+  border-color: var(--border-focus);
+  box-shadow: 0 0 0 3px var(--accent-glow);
+}
+
+.context-field::placeholder { color: var(--text-muted); }
+
+/* ── Messages ──────────────────────────────────────────────────────────────── */
+.messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+}
+
+.message {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  animation: fadeSlideIn 200ms ease both;
+}
+
+@keyframes fadeSlideIn {
+  from { opacity: 0; transform: translateY(8px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.message__meta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.message__role {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  font-family: var(--font-mono);
+}
+
+.message--user      .message__role { color: var(--accent); }
+.message--system    .message__role { color: var(--text-muted); }
+.message--assistant .message__role { color: var(--green); }
+.message--error     .message__role { color: var(--red); }
+.message--thinking  .message__role { color: var(--yellow); }
+
+.message__badge {
+  font-size: 10px;
+  font-family: var(--font-mono);
+  padding: 2px 8px;
+  border-radius: 999px;
+  background: var(--bg-elevated);
+  color: var(--text-muted);
+  border: 1px solid var(--border);
+}
+
+.message__content {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-lg);
+  padding: 14px 18px;
+  line-height: 1.7;
+}
+
+.message--user .message__content {
+  background: var(--accent-dim);
+  border-color: rgba(74,144,232,.3);
+  align-self: flex-end;
+  max-width: 80%;
+}
+
+.message--error .message__content {
+  background: rgba(248,113,113,.06);
+  border-color: rgba(248,113,113,.25);
+  color: var(--red);
+}
+
+.message--thinking .message__content {
+  color: var(--text-muted);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+/* ── Markdown ──────────────────────────────────────────────────────────────── */
+.message__content h1,
+.message__content h2,
+.message__content h3 {
+  font-family: var(--font-ui);
+  font-weight: 700;
+  color: var(--text-bright);
+  margin-top: 20px;
+  margin-bottom: 8px;
+  line-height: 1.3;
+}
+.message__content h1 { font-size: 18px; }
+.message__content h2 { font-size: 15px; color: var(--accent); }
+.message__content h3 { font-size: 13px; }
+.message__content h1:first-child,
+.message__content h2:first-child { margin-top: 0; }
+
+.message__content p  { margin-bottom: 10px; font-size: 15px; }
+.message__content p:last-child { margin-bottom: 0; }
+
+.message__content ul,
+.message__content ol { padding-left: 20px; margin-bottom: 10px; }
+.message__content li { margin-bottom: 4px; font-size: 15px; }
+
+.message__content strong { color: var(--text-bright); font-weight: 700; }
+.message__content em     { color: var(--text-secondary); }
+
+.message__content code {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  background: var(--bg-active);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  color: var(--purple);
+}
+
+.message__content pre {
+  background: #0d0d10 !important;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 14px 16px;
+  overflow-x: auto;
+  margin: 12px 0;
+}
+.message__content pre code {
+  background: none; border: none; padding: 0;
+  color: var(--text-primary); font-size: 12px;
+}
+
+.message__content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 12px 0;
+  font-size: 12.5px;
+  font-family: var(--font-mono);
+}
+.message__content th {
+  background: var(--bg-active);
+  color: var(--text-bright);
+  font-weight: 700;
+  padding: 8px 12px;
+  text-align: left;
+  border: 1px solid var(--border);
+}
+.message__content td {
+  padding: 7px 12px;
+  border: 1px solid var(--border);
+}
+.message__content tr:hover td { background: var(--bg-hover); }
+
+.message__content blockquote {
+  border-left: 3px solid var(--accent);
+  padding-left: 14px;
+  margin: 10px 0;
+  color: var(--text-secondary);
+  font-style: italic;
+}
+
+.message__content hr {
+  border: none;
+  border-top: 1px solid var(--border);
+  margin: 16px 0;
+}
+
+/* ── Input Bar ─────────────────────────────────────────────────────────────── */
+.input-bar {
+  display: flex;
+  align-items: flex-end;
+  gap: 10px;
+  padding: 14px 20px;
+  border-top: 1px solid var(--border);
+  background: var(--bg-surface);
+  flex-shrink: 0;
+}
+
+.query-textarea {
+  flex: 1;
+  background: var(--bg-base);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  color: var(--text-primary);
+  font-family: var(--font-mono);
+  font-size: 15px;
+  padding: 10px 14px;
+  resize: none;
+  outline: none;
+  min-height: 40px;
+  max-height: 160px;
+  overflow-y: auto;
+  line-height: 1.5;
+  transition: border-color var(--transition), box-shadow var(--transition);
+}
+
+.query-textarea:focus {
+  border-color: var(--border-focus);
+  box-shadow: 0 0 0 3px var(--accent-glow);
+}
+
+.query-textarea::placeholder { color: var(--text-muted); }
+
+/* ── Spinner ───────────────────────────────────────────────────────────────── */
+.spinner {
+  width: 14px; height: 14px;
+  border: 2px solid rgba(255,255,255,0.3);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: spin .6s linear infinite;
+}
+
+@keyframes spin { to { transform: rotate(360deg); } }
+
+.hidden { display: none !important; }