Axiom V4.6: Production-Locked. Multilingual Neural Core Operational.

.env.example

@@ -0,0 +1,4 @@
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key
+GROQ_API_KEY=gsk_...
+EMBEDDING_MODE=local

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.env
+.next/
+__pycache__/
+*.pyc

Dockerfile

@@ -0,0 +1,49 @@
+# 1. SOTA Base Image (Lean & Stable)
+FROM python:3.11-slim
+
+# 2. Environment Hardening
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HUB_OFFLINE=0 
+
+# 3. System Intelligence (Hardened for Docling V2 & Python-Magic)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libmagic1 \
+    libmagic-dev \
+    libgomp1 \
+    poppler-utils \
+    tesseract-ocr \
+    libgl1 \
+    libglib2.0-0 \
+    libxml2-dev \
+    libxslt-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# 4. Secure User Architecture (Hugging Face Standard)
+RUN useradd -m -u 1000 user
+USER user
+WORKDIR $HOME/app
+
+# 5. Ingestion Buffer Setup
+# Ensure the temp directory for Docling exists and is writable
+RUN mkdir -p /tmp/axiom_ingest && chmod 777 /tmp/axiom_ingest
+
+# 6. Dependency Hydration
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# 7. Application Ingestion
+COPY --chown=user . .
+
+# 8. Port Specification
+EXPOSE 7860
+
+# 9. Start Engine (SOTA Event Loop Optimization)
+# --loop asyncio is mandatory for RAGAS 0.2/nest_asyncio compatibility
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--loop", "asyncio", "--proxy-headers", "--forwarded-allow-ips", "*"]

README.md

@@ -0,0 +1,20 @@
+---
+title: Axiom Engine API
+emoji: 🛡️
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Axiom Engine — Reasoning Core
+Enterprise Evidence-Gated RAG API. 
+
+## Technical Specifications
+- **Runtime:** Python 3.11 FastAPI
+- **Intelligence:** LangGraph + Llama 3.3
+- **Vector Engine:** Supabase 1024-dim (Local)
+- **Deployment:** Docker (Hugging Face Spaces)
+
+*Strictly for internal Lexpertz AI organizational use.*

app/__init__.py

@@ -0,0 +1 @@
+

app/agents/graph.py

@@ -0,0 +1,85 @@
+from langgraph.graph import StateGraph, END, START
+from app.agents.state import AgentState
+from app.agents.nodes import (
+    retrieve_node, 
+    distill_node, 
+    generate_node, 
+    grade_generation_node,
+    strategist_node
+)
+
+# --- 1. ROUTING LOGIC ---
+
+def route_post_retrieval(state: AgentState):
+    """
+    Determines path based on evidence status, document count, and AXM-CLI commands.
+    """
+    if state.get("status") == "no_evidence":
+        return "end"
+    
+    command = state.get("command") or ""
+    filenames = state.get("filenames",[])
+    
+    # SOTA: Multi-Flag Check. If "-c" is anywhere in the command string.
+    if "-c" in command or len(filenames) > 1:
+        return "strategist"
+        
+    return "distill"
+
+def route_post_grading(state: AgentState):
+    """
+    The Adversarial Gatekeeper. Routes to Architect for retry.
+    """
+    if state.get("status") == "verified":
+        return "end"
+
+    # Safety: Limit retry recursion to prevent token burn
+    current_retries = state.get("retry_count", 0)
+    if current_retries < 2:
+        return "retry"
+    
+    return "end"
+
+# --- 2. THE CIRCUIT DESIGN ---
+workflow = StateGraph(AgentState)
+
+# Register Professional Agent Nodes
+workflow.add_node("Librarian", retrieve_node)
+workflow.add_node("Editor", distill_node)
+workflow.add_node("Strategist", strategist_node)
+workflow.add_node("Architect", generate_node)
+workflow.add_node("Prosecutor", grade_generation_node)
+
+# --- 3. THE WIRING ---
+
+# Start Node
+workflow.add_edge(START, "Librarian")
+
+# A. Gate 1: Post-Retrieval Routing
+workflow.add_conditional_edges(
+    "Librarian",
+    route_post_retrieval,
+    {
+        "end": END,
+        "strategist": "Strategist",
+        "distill": "Editor"
+    }
+)
+
+# B. Reasoning & Comparison Processing
+workflow.add_edge("Editor", "Architect")
+workflow.add_edge("Strategist", "Architect")
+workflow.add_edge("Architect", "Prosecutor")
+
+# C. Gate 2: The Adversarial/Retry Loop
+workflow.add_conditional_edges(
+    "Prosecutor",
+    route_post_grading,
+    {
+        "end": END,
+        "retry": "Architect" 
+    }
+)
+
+# Compile the Sovereign Brain
+app_graph = workflow.compile()

app/agents/nodes.py

@@ -0,0 +1,172 @@
+import os
+import time
+import re
+from typing import cast, List, Dict, Any, Union, Optional
+
+from langchain_core.caches import BaseCache
+from langchain_core.callbacks import Callbacks
+from langchain_core.outputs import ChatResult
+from pydantic import SecretStr
+
+from langchain_groq import ChatGroq
+from langchain_nvidia_ai_endpoints import ChatNVIDIA
+
+from app.agents.state import AgentState
+from app.core.retriever import hybrid_search
+from app.core.reranker import get_reranked_scores 
+from app.core.monitor import monitor
+from app.core.evaluator import axiom_evaluator
+
+# IMPORTING THE ENTERPRISE REGISTRY
+from app.prompts.templates import (
+    VERIFICATION_PROMPT, 
+    DISTILLATION_PROMPT, 
+    STRATEGIST_COMPARATIVE_PROMPT,
+    GRADING_PROMPT,
+    distill_parser,    
+    grade_parser
+)
+
+try:
+    ChatGroq.model_rebuild()
+    ChatNVIDIA.model_rebuild()
+    print("AXIOM-CORE: Neural Registry Stabilized.")
+except Exception as e:
+    print(f"AXIOM-CORE: Model rebuild notice: {e}")
+
+_nv_key = os.getenv("NVIDIA_API_KEY")
+_groq_key = os.getenv("GROQ_API_KEY")
+
+base_llm: Any 
+editor_llm_core: Any
+prosecutor_llm_core: Any
+
+if _nv_key:
+    try:
+        base_llm = ChatNVIDIA(model="meta/llama-3.3-70b-instruct", nvidia_api_key=_nv_key, temperature=0, max_tokens=2048)
+        editor_llm_core = ChatNVIDIA(model="nvidia/nvidia-nemotron-nano-9b-v2", nvidia_api_key=_nv_key, temperature=0.1, max_tokens=1024)
+        prosecutor_llm_core = ChatNVIDIA(model="meta/llama-3.1-405b-instruct", nvidia_api_key=_nv_key, temperature=0, max_tokens=512)
+    except: _nv_key = None
+
+if not _nv_key:
+    base_llm = ChatGroq(temperature=0, model="llama-3.3-70b-versatile", api_key=SecretStr(_groq_key) if _groq_key else None) # type: ignore
+    editor_llm_core = ChatGroq(temperature=0, model="llama-3.1-8b-instant", api_key=SecretStr(_groq_key) if _groq_key else None) # type: ignore
+    prosecutor_llm_core = base_llm
+
+simple_llm = base_llm 
+
+
+async def retrieve_node(state: AgentState):
+    raw_question = state["question"].strip()
+    command = None
+    clean_question = raw_question
+    
+    # SOTA: Multi-Flag Parser (Captures '-a -t -v' as a single block)
+    cmd_match = re.match(r'^/axm\s+((?:-[a-z]+\s*|\.\.\s*)+)(.*)', raw_question, re.IGNORECASE | re.DOTALL)
+    if cmd_match:
+        command = cmd_match.group(1).strip().lower()
+        clean_question = cmd_match.group(2).strip()
+        print(f"AXM-CLI: Detected Commands [{command}]")
+
+    filenames = state.get("filenames",[])
+    is_vault_mode = "vault" in filenames or len(filenames) == 0
+    search_input = None if is_vault_mode else filenames
+    
+    # SOTA: Use 'in' to check for specific flags inside the chained command
+    is_deep_audit = command and "-a" in command
+    search_limit = 60 if is_deep_audit else 30
+    top_k = 20 if is_deep_audit else 12
+
+    initial_chunks = await hybrid_search(query=clean_question, user_id=state["user_id"], filename=search_input, limit=search_limit)
+    if not initial_chunks:
+        return {"documents":[], "generation": "Insufficient Evidence.", "status": "no_evidence", "command": command, "question": clean_question}
+
+    gold_chunks = await get_reranked_scores(query=clean_question, documents=initial_chunks, top_k=top_k)
+    return {"documents": gold_chunks, "status": "thinking", "active_node": "Librarian", "command": command, "question": clean_question }
+
+async def distill_node(state: AgentState):
+    context_text = monitor.guard_context(state["documents"])
+    if not context_text.strip(): 
+        return {"generation": "NO RELEVANT EVIDENCE", "status": "thinking"}
+
+    chain = DISTILLATION_PROMPT | base_llm | distill_parser
+    
+    try:
+        raw_response = await chain.ainvoke({"context": context_text, "question": state["question"]})
+        
+        brief_content = raw_response.brief
+        preambles_to_strip =["Here is the synthesized evidence brief:", "Based on the provided snippets:", "Synthesized Evidence Brief:", "Here is the brief:"]
+        for preamble in preambles_to_strip:
+            brief_content = brief_content.replace(preamble, "")
+            
+        return {"generation": brief_content.strip() if raw_response.has_relevant_evidence else "NO RELEVANT EVIDENCE", "status": "thinking", "active_node": "Editor"}
+    except Exception as e:
+        print(f"⚠️ EDITOR JSON FAILSAFE TRIGGERED: {e}")
+        cleaned_context = re.sub(r'--- EXHIBIT_(START|END)_ID_\w+ ---', '', context_text)
+        return {"generation": cleaned_context[:6000], "status": "thinking", "active_node": "Editor"}
+        
+async def strategist_node(state: AgentState):
+    context_text = monitor.guard_context(state["documents"])
+    chain = STRATEGIST_COMPARATIVE_PROMPT | simple_llm 
+    response = await chain.ainvoke({"context": context_text, "question": state["question"]})
+    return {"generation": str(response.content), "status": "thinking", "active_node": "Strategist"}
+
+async def generate_node(state: AgentState):
+    distilled_brief = state["generation"]
+    command = state.get("command")
+    history = state.get("history",[])
+
+    if "NO RELEVANT EVIDENCE" in distilled_brief:
+        return {"generation": "No direct evidence found in the vault.", "status": "verifying"}
+
+    history_context = ""
+    # SOTA Check: Is the reset flag present?
+    if history and (not command or ".." not in command):
+        history_context = "\n\n### PREVIOUS AUDIT CONTEXT:\n"
+        for turn in history[-3:]: 
+            history_context += f"{turn['role'].upper()}: {turn['content']}\n"
+
+    # SOTA Check: Is the table flag present?
+    formatting_directive = "\n\nCRITICAL: You are in TABLE MODE. Output strictly as a Markdown Data Grid." if command and "-t" in command else ""
+
+    chain = VERIFICATION_PROMPT | simple_llm 
+    response = await chain.ainvoke({"context": f"{history_context}\n\nEVIDENCE:\n{distilled_brief}{formatting_directive}", "question": state["question"]})
+    return {"generation": str(response.content), "status": "verifying", "active_node": "Architect"}
+
+async def grade_generation_node(state: AgentState):
+    generation = state.get("generation", "")
+    if "No direct evidence found" in generation or not generation.strip():
+        return {"hallucination_score": 1.0, "metrics": {"faithfulness": 1.0, "precision": 1.0, "relevance": 1.0}, "status": "verified", "active_node": "Prosecutor"}
+
+    command = state.get("command")
+    # SOTA Check: Is the intense verification flag present?
+    intensify = command is not None and "-v" in command
+    
+    context_list = state["documents"]
+    context_str = "\n\n".join(context_list)
+    
+    try:
+        chain = GRADING_PROMPT | prosecutor_llm_core | grade_parser
+        grade = await chain.ainvoke({"context": context_str, "generation": generation})
+        
+        if str(grade.is_hallucinating).strip().lower() == "true":
+            print(f"LOGIC BREACH (NIM): {grade.explanation}")
+            return {"hallucination_score": 0.0, "status": "thinking", "retry_count": state.get("retry_count", 0) + 1, "active_node": "Prosecutor"}
+    except Exception as e:
+        print(f"⚠️ PROSECUTOR JSON FAILSAFE: {e}")
+        pass 
+
+    try:
+        print("--- AXIOM: EXECUTING RAGAS MATHEMATICAL AUDIT ---")
+        scores = await axiom_evaluator.score_response(state["question"], generation, context_list)
+        faith = scores.get('faithfulness', 0.0)
+        threshold = 0.9 if intensify else 0.7
+        
+        if faith < threshold:
+            print(f"FAITHFULNESS BREACH: {faith} (Threshold: {threshold})")
+            return {"hallucination_score": faith, "metrics": scores, "status": "thinking", "retry_count": state.get("retry_count", 0) + 1, "active_node": "Prosecutor"}
+
+        return {"hallucination_score": faith, "metrics": scores, "status": "verified", "active_node": "Prosecutor"}
+    except Exception as e:
+        print(f"⚠️ PROSECUTOR SYSTEM FAILSAFE: {e}")
+        return {"hallucination_score": 0.5, "status": "verified", "active_node": "Prosecutor", "metrics": {"faithfulness": 0.5, "precision": 1.0, "relevance": 1.0}}

app/agents/state.py

@@ -0,0 +1,36 @@
+from typing import TypedDict, List, Dict, Any, Optional
+
+class AgentState(TypedDict):
+    """
+    The Axiom Sovereign State Machine V4.6.
+    Synchronized for LangGraph 0.2.x and Command-Aware Auditing.
+    """
+    # --- Input Context ---
+    question: str
+    user_id: str
+    filenames: List[str]
+    
+    # --- V4.6 Persistent Memory ---
+    # history: Stores last 5 turns: [{"role": "user", "content": "..."}, ...]
+    history: List[Dict[str, str]]
+    
+    # --- V4.6 Command Register ---
+    # command: Stores the specific /axm shorthand (e.g., "-a", "-t", "..")
+    command: Optional[str]
+    
+    # --- Working Memory ---
+    # comparison_map: Intermediate JSON extraction for multi-doc audits
+    comparison_map: Dict[str, Any]
+    documents: List[str]
+    
+    # --- Output State ---
+    generation: str
+    status: str
+    
+    # --- Telemetry & Logic Control ---
+    hallucination_score: float
+    metrics: Dict[str, float]
+    retry_count: int
+    
+    # SSE Observability (Step 0, Step 1, etc.)
+    active_node: Optional[str]

app/api/__init__.py

@@ -0,0 +1,3 @@
+# Expose routers for cleaner imports in main.py,
+from . import ingest
+from . import run

app/api/history.py

@@ -0,0 +1,101 @@
+import asyncio
+from fastapi import APIRouter, Depends, HTTPException, Query, Path
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, cast, Optional
+from app.core.database import db
+from app.core.auth import get_current_user
+
+router = APIRouter()
+
+# --- 1. RESPONSE MODELS (Strict Serialization) ---
+class DocumentItem(BaseModel):
+    filename: str
+    status: str
+    created_at: str
+
+class ChatMessageItem(BaseModel):
+    id: int
+    role: str
+    content: str
+    metrics: Optional[Dict[str, float]] = None
+    created_at: str
+
+# --- 2. ENDPOINTS ---
+
+@router.get("/documents", response_model=List[DocumentItem])
+async def get_user_documents(
+    # Bounded Limit: Max 100 documents at a time to prevent RAM exhaustion
+    limit: int = Query(100, ge=1, le=500, description="Pagination limit"),
+    user_id: str = Depends(get_current_user)
+):
+    """
+    SOTA Document Fetcher:
+    Retrieves the latest documents asynchronously.
+    """
+    if not db:
+        raise HTTPException(status_code=503, detail="Vault DB Offline")
+
+    try:
+        # Non-blocking Database Call
+        res = await asyncio.to_thread(
+            lambda: db.table("documents")
+            .select("filename, status, created_at")
+            .eq("user_id", user_id)
+            .order("created_at", desc=True)
+            .limit(limit)
+            .execute()
+        )
+        
+        return cast(List[Dict[str, Any]], res.data)
+    except Exception as e:
+        print(f"❌ DOCUMENT FETCH ERROR: {e}")
+        raise HTTPException(status_code=500, detail="Failed to retrieve vault ledger")
+
+
+@router.get("/chat/{filename}", response_model=List[ChatMessageItem])
+async def get_document_chat_history(
+    # Path Validation: Protects against directory traversal and malformed URLs
+    filename: str = Path(..., min_length=1, max_length=255), 
+    # Chat Limit: Fetch only the most recent 50 messages to keep UI snappy
+    limit: int = Query(50, ge=1, le=200),
+    user_id: str = Depends(get_current_user)
+):
+    """
+    V4.6 SOTA History Hydrator:
+    Fetches the latest conversation efficiently, offloaded to a background thread.
+    """
+    if not db:
+        raise HTTPException(status_code=503, detail="Vault DB Offline")
+
+    try:
+        # 1. Non-blocking Document ID Fetch
+        doc_res = await asyncio.to_thread(
+            lambda: db.table("documents").select("id").eq("filename", filename).eq("user_id", user_id).execute()
+        )
+        doc_data = cast(List[Dict[str, Any]], doc_res.data)
+        
+        if not doc_data:
+            return [] # Cleanly return empty history if document doesn't exist
+
+        doc_id = doc_data[0]['id']
+
+        # 2. Non-blocking Messages Fetch (Smart Chronology)
+        # We fetch the LATEST 'limit' messages first (desc=True)
+        msg_res = await asyncio.to_thread(
+            lambda: db.table("chat_messages")
+            .select("id, role, content, metrics, created_at")
+            .eq("document_id", doc_id)
+            .order("created_at", desc=True) # Get newest first
+            .limit(limit)
+            .execute()
+        )
+        
+        messages = cast(List[Dict[str, Any]], msg_res.data)
+        
+        # 3. Reverse the array in Python so the UI displays Oldest -> Newest
+        return messages[::-1]
+
+    except Exception as e:
+        print(f"❌ HISTORY FETCH ERROR: {str(e)}")
+        # Don't return an empty array on DB crash; tell the UI something went wrong
+        raise HTTPException(status_code=500, detail="Failed to retrieve audit history")

app/api/ingest.py

@@ -0,0 +1,240 @@
+import os
+import uuid
+import math
+import asyncio
+from typing import Optional, List, Any, Dict, cast
+from fastapi import APIRouter, UploadFile, File, HTTPException, BackgroundTasks, Depends, Path
+from pydantic import BaseModel
+
+from app.core.database import db
+from app.core.chunking import chunker
+from app.core.embeddings import get_embedding
+from app.core.auth import get_current_user
+
+# Lazy Initialization for Docling
+_converter = None
+
+def get_converter():
+    global _converter
+    if _converter is None:
+        print("AXIOM-CORE: Waking up Docling V2 Intelligence...")
+        from docling.document_converter import DocumentConverter # type: ignore
+        _converter = DocumentConverter()
+    return _converter
+
+router = APIRouter()
+TEMP_DIR = "/tmp/axiom_ingest"
+
+# --- HELPER: CONCURRENT VECTORIZATION ---
+async def fetch_embedding_concurrently(chunk_text: str, semaphore: asyncio.Semaphore) -> List[float]:
+    """Bounds concurrent requests to NVIDIA to prevent 429 Rate Limits."""
+    async with semaphore:
+        return await asyncio.to_thread(get_embedding, chunk_text, input_type="document")
+
+# --- THE SOTA BACKGROUND ENGINE ---
+async def process_document(file_path: str, filename: str, user_id: str) -> None:
+    try:
+        print(f"AXIOM-CORE: Parsing {filename} (Async Mode)")
+        
+        # 1. CPU-Bound Task Offloading (Prevents GIL Freeze)
+        converter = get_converter()
+        conv_result = await asyncio.to_thread(converter.convert, file_path)
+        markdown_content = conv_result.document.export_to_markdown()
+
+        # 2. Register Document (Non-blocking DB)
+        document_id: Optional[int] = None
+        if db:
+            doc_res = await asyncio.to_thread(
+                lambda: db.table("documents").insert({
+                    "filename": filename, "user_id": user_id, "status": "processing", "is_permanent": False 
+                }).execute()
+            )
+            data = cast(List[Dict[str, Any]], doc_res.data)
+            if data: document_id = data[0].get('id')
+
+        if not document_id: raise RuntimeError("DB Insert Failed")
+
+        # 3. Chunking
+        chunks = chunker.split_text(markdown_content)
+        print(f"AXIOM-CORE: Vectorizing {len(chunks)} chunks concurrently...")
+
+        # 4. SOTA: Concurrent Batch Vectorization (Massive Speedup)
+        # Limit to 5 parallel connections to respect NVIDIA NIM rate limits
+        semaphore = asyncio.Semaphore(5) 
+        tasks =[fetch_embedding_concurrently(chunk, semaphore) for chunk in chunks]
+        vectors = await asyncio.gather(*tasks)
+
+        # 5. Assemble Payload
+        data_payload: List[Dict[str, Any]] =[]
+        for i, (chunk_text, vector) in enumerate(zip(chunks, vectors)):
+            data_payload.append({
+                "document_id": document_id, "user_id": user_id, "content": chunk_text,
+                "embedding": vector, "metadata": {"index": i, "source": filename, "engine": "docling-v2-nim"}
+            })
+
+        # 6. Non-Blocking Batch DB Insertion
+        if db:
+            # Strictly typed helper function to satisfy Mypy
+            def insert_batch(batch_data: List[Dict[str, Any]]) -> None:
+                db.table("document_chunks").insert(cast(Any, batch_data)).execute()
+
+            BATCH_SIZE = 50
+            for j in range(0, len(data_payload), BATCH_SIZE):
+                batch = data_payload[j : j + BATCH_SIZE]
+                # Pass the function and its arguments natively to to_thread
+                await asyncio.to_thread(insert_batch, batch)
+            
+            # Helper for the status update to avoid another lambda
+            def update_status() -> None:
+                db.table("documents").update({"status": "indexed"}).eq("id", document_id).execute()
+                
+            await asyncio.to_thread(update_status)
+
+        print(f"COMPLETE: {filename} indexed successfully.")
+        
+    except Exception as e:
+        print(f"❌ INGESTION FAILED: {str(e)}")
+        if db: 
+            await asyncio.to_thread(
+                lambda: db.table("documents").update({"status": "error"}).eq("filename", filename).execute()
+            )
+    finally:
+        if os.path.exists(file_path): os.remove(file_path)
+
+# --- ROUTES ---
+
+@router.post("/upload")
+async def ingest_document(
+    background_tasks: BackgroundTasks, 
+    file: UploadFile = File(...),
+    user_id: str = Depends(get_current_user)
+):
+    """File Upload Handler with Path Traversal Protection"""
+    if not file.filename or not file.filename.lower().endswith(".pdf"):
+        raise HTTPException(status_code=400, detail="Protocol Violation: PDF Document Required.")
+
+    try:
+        os.makedirs(TEMP_DIR, exist_ok=True)
+        # Prevent Directory Traversal by stripping paths
+        safe_filename = os.path.basename(file.filename)
+        file_path = f"{TEMP_DIR}/{uuid.uuid4()}_{safe_filename}"
+        
+        # Async file read/write
+        content = await file.read()
+        await asyncio.to_thread(lambda: open(file_path, "wb").write(content))
+        
+        # FastAPI Native Async Background Task
+        background_tasks.add_task(process_document, file_path, safe_filename, user_id)
+        
+        return {"status": "queued", "filename": safe_filename}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@router.get("/status/{filename}")
+async def get_ingestion_status(filename: str = Path(...), user_id: str = Depends(get_current_user)):
+    if not db: return {"status": "error", "message": "DB Offline"}
+    res = await asyncio.to_thread(
+        lambda: db.table("documents").select("status").eq("filename", filename).eq("user_id", user_id).order("created_at", desc=True).limit(1).execute()
+    )
+    data = cast(List[Dict[str, Any]], res.data)
+    return {"status": data[0].get('status', 'unknown')} if data else {"status": "not_found"}
+
+@router.get("/latest")
+async def get_latest_document(user_id: str = Depends(get_current_user)):
+    if not db: return {"status": "error"}
+    res = await asyncio.to_thread(
+        lambda: db.table("documents").select("filename, status").eq("user_id", user_id).order("created_at", desc=True).limit(1).execute()
+    )
+    data = cast(List[Dict[str, Any]], res.data)
+    return {"status": "success", "filename": data[0].get("filename"), "doc_status": data[0].get("status")} if data else {"status": "none"}
+
+@router.get("/metadata/{filename}")
+async def get_document_metadata(filename: str = Path(...), user_id: str = Depends(get_current_user)):
+    if not db: return {"status": "error"}
+    res = await asyncio.to_thread(
+        lambda: db.table("documents").select("*").eq("filename", filename).eq("user_id", user_id).order("created_at", desc=True).limit(1).execute()
+    )
+    data_list = cast(List[Dict[str, Any]], res.data)
+    if not data_list: return {"status": "not_found"}
+    doc_data = data_list[0]
+    
+    chunks = await asyncio.to_thread(
+        lambda: db.table("document_chunks").select("id", count=cast(Any, "exact")).eq("document_id", doc_data['id']).execute()
+    )
+    return {
+        "filename": filename,
+        "status": doc_data.get('status'),
+        "created_at": doc_data.get('created_at'),
+        "chunk_count": chunks.count if chunks.count else 0,
+        "is_permanent": doc_data.get('is_permanent', False)
+    }
+
+class SaveRequest(BaseModel):
+    filename: str
+
+@router.post("/save")
+async def save_document_to_vault(req: SaveRequest, user_id: str = Depends(get_current_user)):
+    if db:
+        await asyncio.to_thread(
+            lambda: db.table("documents").update({"is_permanent": True}).eq("filename", req.filename).eq("user_id", user_id).execute()
+        )
+        return {"status": "persisted"}
+    return {"status": "error"}
+
+@router.delete("/documents/{filename}")
+async def delete_document(filename: str = Path(...), user_id: str = Depends(get_current_user)):
+    if not db: raise HTTPException(status_code=500, detail="Vault DB Offline")
+    await asyncio.to_thread(
+        lambda: db.table("documents").delete().eq("filename", filename).eq("user_id", user_id).execute()
+    )
+    return {"status": "purged", "filename": filename}
+
+def sanitize_float(val: Any) -> float:
+    try:
+        f_val = float(val)
+        return f_val if math.isfinite(f_val) else 0.0
+    except (TypeError, ValueError):
+        return 0.0
+
+@router.get("/telemetry")
+async def get_system_telemetry(user_id: str = Depends(get_current_user)):
+    """Async offloaded telemetry aggregation."""
+    if not db: return {"chunks": "--", "persistence": "--", "blocked": "--", "latency": "--"}
+    
+    try:
+        docs_res = await asyncio.to_thread(lambda: db.table("documents").select("id, is_permanent").eq("user_id", user_id).execute())
+        docs = cast(List[Dict[str, Any]], docs_res.data)
+        
+        total_docs = len(docs)
+        persisted_docs = sum(1 for d in docs if d.get("is_permanent", False))
+        persistence_rate = f"{int((persisted_docs / total_docs) * 100)}%" if total_docs > 0 else "0%"
+        
+        chunks_res = await asyncio.to_thread(lambda: db.table("document_chunks").select("id", count=cast(Any, "exact")).eq("user_id", user_id).execute())
+        total_chunks = chunks_res.count if chunks_res.count else 0
+        
+        logs_res = await asyncio.to_thread(lambda: db.table("audit_logs").select("faithfulness, precision, relevance, latency").eq("user_id", user_id).order("created_at", desc=True).limit(50).execute())
+        logs = cast(List[Dict[str, Any]], logs_res.data)
+        
+        avg_faith, avg_prec, avg_rel, avg_latency, blocked = 0.0, 0.0, 0.0, 0.0, 0
+        
+        if logs:
+            total_logs = len(logs)
+            avg_faith = sum(sanitize_float(l.get("faithfulness", 0.0)) for l in logs) / total_logs
+            avg_prec = sum(sanitize_float(l.get("precision", 0.0)) for l in logs) / total_logs
+            avg_rel = sum(sanitize_float(l.get("relevance", 0.0)) for l in logs) / total_logs
+            blocked = sum(1 for l in logs if sanitize_float(l.get("faithfulness", 0.0)) < 0.8)
+            
+            valid_latencies =[sanitize_float(l.get("latency", 0.0)) for l in logs if sanitize_float(l.get("latency", 0.0)) > 0]
+            if valid_latencies:
+                avg_latency = sum(valid_latencies) / len(valid_latencies)
+            
+        return {
+            "chunks": str(total_chunks),
+            "persistence": persistence_rate,
+            "blocked": str(blocked),
+            "latency": f"{sanitize_float(avg_latency):.1f}s",
+            "ragas": {"faithfulness": sanitize_float(avg_faith), "precision": sanitize_float(avg_prec), "relevance": sanitize_float(avg_rel)}
+        }
+    except Exception as e:
+        print(f"❌ TELEMETRY ERROR: {e}")
+        return {"chunks": "--", "persistence": "--", "blocked": "--", "latency": "--"}

app/api/keys.py

@@ -0,0 +1,84 @@
+import secrets
+import hashlib
+import asyncio
+from fastapi import APIRouter, Depends, HTTPException, Path
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, cast
+from app.core.auth import get_current_user
+from app.core.database import db
+
+router = APIRouter()
+
+# --- 1. STRICT SCHEMAS ---
+class CreateKeyRequest(BaseModel):
+    # Firewall: Prevent DB Overflow by capping the name length
+    name: str = Field(..., min_length=1, max_length=64, description="Name identifier for the API key")
+
+def generate_secure_key():
+    """
+    Generates a production-grade API key.
+    Returns: (raw_key_for_user, hashed_key_for_db, key_hint_for_ui)
+    """
+    raw_secret = secrets.token_hex(24) 
+    full_key = f"axm_live_{raw_secret}"
+    key_hash = hashlib.sha256(full_key.encode()).hexdigest()
+    key_hint = f"{full_key[:12]}...{full_key[-4:]}"
+    return full_key, key_hash, key_hint
+
+# --- 2. ASYNC ENDPOINTS ---
+
+@router.post("/")
+async def create_api_key(req: CreateKeyRequest, user_id: str = Depends(get_current_user)):
+    """Generates a new API key. The raw key is returned ONLY ONCE."""
+    if not db: raise HTTPException(503, "DB Offline")
+    
+    full_key, key_hash, key_hint = generate_secure_key()
+    
+    # Non-blocking DB Insert
+    await asyncio.to_thread(
+        lambda: db.table("api_keys").insert({
+            "user_id": user_id,
+            "name": req.name,
+            "key_value": key_hash, 
+            "key_hint": key_hint   
+        }).execute()
+    )
+    
+    return {
+        "status": "success", 
+        "name": req.name, 
+        "key_value": full_key, 
+        "message": "Please copy this key now. You will not be able to see it again."
+    }
+
+@router.get("/")
+async def list_api_keys(user_id: str = Depends(get_current_user)):
+    """Lists all active API keys using their secure hints asynchronously."""
+    if not db: raise HTTPException(503, "DB Offline")
+    
+    res = await asyncio.to_thread(
+        lambda: db.table("api_keys")
+        .select("id, name, created_at, last_used_at, is_active, key_hint")
+        .eq("user_id", user_id)
+        .order("created_at", desc=True)
+        .execute()
+    )
+    
+    return {"keys": cast(List[Dict[str, Any]], res.data)}
+
+@router.delete("/{key_id}")
+async def revoke_api_key(
+    key_id: str = Path(..., description="ID of the key to revoke"), 
+    user_id: str = Depends(get_current_user)
+):
+    """Instantly revokes an API key (Sets is_active to False) without freezing the UI."""
+    if not db: raise HTTPException(503, "DB Offline")
+    
+    await asyncio.to_thread(
+        lambda: db.table("api_keys")
+        .update({"is_active": False})
+        .eq("id", key_id)
+        .eq("user_id", user_id)
+        .execute()
+    )
+    return {"status": "revoked", "id": key_id}

app/api/run.py

@@ -0,0 +1,156 @@
+import time
+import math
+import json
+import asyncio
+from fastapi import APIRouter, HTTPException, Depends, Request
+from sse_starlette.sse import EventSourceResponse
+from pydantic import BaseModel
+from app.agents.graph import app_graph
+from app.agents.state import AgentState
+from app.core.auth import get_current_user
+from app.core.database import db
+from typing import Dict, Any, cast, List, AsyncGenerator
+
+router = APIRouter()
+
+# --- 1. SCHEMAS ---
+class VerificationRequest(BaseModel):
+    question: str
+    filenames: List[str]
+
+class VerificationResponse(BaseModel):
+    answer: str
+    status: str
+    evidence_count: int
+    metrics: Dict[str, float]
+
+def sanitize_float(val: Any) -> float:
+    try:
+        f_val = float(val)
+        return f_val if math.isfinite(f_val) else 0.0
+    except (TypeError, ValueError):
+        return 0.0
+
+# --- 2. STREAMING ENDPOINT ---
+@router.post("/verify")
+async def run_verification(
+    payload: VerificationRequest,
+    user_id: str = Depends(get_current_user)
+):
+    async def event_generator() -> AsyncGenerator[Dict[str, Any], None]:
+        try:
+            start_time = time.time()
+            print(f"--- STREAM STARTED FOR: {payload.question[:30]}... ---")
+
+            history_buffer: List[Dict[str, str]] = []
+            is_root_reset = payload.question.strip().startswith("/axm ..")
+
+            if db and not is_root_reset:
+                try:
+                    primary_file = payload.filenames[0] if payload.filenames else "vault"
+                    doc_res = db.table("documents").select("id").eq("filename", primary_file).eq("user_id", user_id).execute()
+                    
+                    # FIX: Explicit cast to allow indexing
+                    doc_rows = cast(List[Dict[str, Any]], doc_res.data)
+                    if doc_rows:
+                        doc_id = doc_rows[0]['id']
+                        hist_res = db.table("chat_messages").select("role, content").eq("document_id", doc_id).eq("user_id", user_id).order("created_at", desc=True).limit(5).execute()
+                        
+                        # FIX: Cast to match AgentState history requirements
+                        raw_hist = cast(List[Dict[str, str]], hist_res.data)
+                        history_buffer = raw_hist[::-1]
+                except Exception as e:
+                    print(f"AXM-MEM: History hydration failed: {e}")
+
+            initial_state: AgentState = {
+                "question": payload.question, 
+                "user_id": user_id, 
+                "filenames": payload.filenames,
+                "history": history_buffer,   
+                "command": None,             
+                "comparison_map": {}, 
+                "documents":[], 
+                "generation": "", 
+                "hallucination_score": 0.0,
+                "metrics": {}, 
+                "status": "thinking", 
+                "retry_count": 0,
+                "active_node": None
+            }
+
+            full_generation = ""
+            final_metrics: Dict[str, float] = {}
+            current_active_node = "System"
+            
+            ui_node_map = {
+                "retrieve_node": "Librarian", "Librarian": "Librarian",
+                "distill_node": "Editor", "Editor": "Editor",
+                "strategist_node": "Strategist", "Strategist": "Strategist",
+                "generate_node": "Architect", "Architect": "Architect",
+                "grade_generation_node": "Prosecutor", "Prosecutor": "Prosecutor"
+            }
+
+            async for event in app_graph.astream_events(initial_state, version="v1"):
+                kind = event["event"]
+                name = event["name"]
+                
+                if kind == "on_chain_start" and name in ui_node_map:
+                    current_active_node = ui_node_map[name]
+                    yield {"event": "node_update", "data": json.dumps({"node": current_active_node, "status": "active"})}
+
+                elif kind == "on_chat_model_stream":
+                    if current_active_node in ["Architect", "Strategist"]:
+                        chunk = event["data"].get("chunk")
+                        content = ""
+                        if chunk:
+                            if hasattr(chunk, "content"): content = str(chunk.content)
+                            elif isinstance(chunk, dict) and "content" in chunk: content = str(chunk["content"])
+                                
+                        if content:
+                            full_generation += content
+                            yield {"event": "token", "data": json.dumps({"text": content})}
+
+                elif kind == "on_chain_end" and name in ["generate_node", "Architect"]:
+                    # FIX: Explicit type annotation for Mypy
+                    node_output: Dict[str, Any] = event["data"].get("output", {})
+                    if not full_generation and "generation" in node_output:
+                        full_generation = str(node_output["generation"])
+                        yield {"event": "token", "data": json.dumps({"text": full_generation})}
+
+                elif kind == "on_chain_end" and name in ["grade_generation_node", "Prosecutor"]:
+                    # FIX: Explicit type annotation for Mypy
+                    eval_output: Dict[str, Any] = event["data"].get("output", {})
+                    final_metrics = eval_output.get("metrics", {})
+
+            if not full_generation.strip():
+                full_generation = "Verification Failed: Audit logic rejected the draft."
+                yield {"event": "token", "data": json.dumps({"text": full_generation})}
+
+            actual_latency = round(time.time() - start_time, 2)
+            safe_metrics = {k: sanitize_float(v) for k, v in final_metrics.items()}
+
+            if db:
+                try:
+                    primary_file = payload.filenames[0] if payload.filenames else "vault"
+                    doc_res = db.table("documents").select("id").eq("filename", primary_file).eq("user_id", user_id).execute()
+                    doc_data = cast(List[Dict[str, Any]], doc_res.data)
+                    
+                    if doc_data:
+                        doc_id = doc_data[0]['id']
+                        db.table("chat_messages").insert({"document_id": doc_id, "user_id": user_id, "role": "user", "content": payload.question}).execute()
+                        db.table("chat_messages").insert({"document_id": doc_id, "user_id": user_id, "role": "assistant", "content": full_generation, "metrics": safe_metrics}).execute()
+                        db.table("audit_logs").insert({"user_id": user_id, "question": payload.question, "faithfulness": safe_metrics.get("faithfulness", 0.0), "latency": actual_latency}).execute()
+                except Exception as log_err:
+                    print(f"SSE DB ERROR: {log_err}")
+
+            yield {
+                "event": "audit_complete",
+                "data": json.dumps({"answer": full_generation, "metrics": safe_metrics})
+            }
+
+        except Exception as e:
+            error_msg = str(e)
+            print(f"❌ MASTER STREAM CRASH: {error_msg}")
+            yield {"event": "error", "data": json.dumps({"detail": f"Backend Engine Disconnected: {error_msg}"})}
+
+    return EventSourceResponse(event_generator())

app/api/vault.py

@@ -0,0 +1,68 @@
+import asyncio
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, cast
+from app.core.database import db
+from app.core.embeddings import get_embedding
+from app.core.auth import get_current_user
+
+router = APIRouter()
+
+# --- 1. HARDENED SCHEMAS (Security) ---
+class VaultSearchRequest(BaseModel):
+    # Bound the query to ~400 words to prevent NVIDIA NIM Token Limit Crashes (HTTP 413)
+    query: str = Field(..., min_length=2, max_length=2000, description="The audit query")
+    # Cap the limit to prevent DB Compute DoS attacks
+    limit: int = Field(default=5, ge=1, le=50, description="Max results to return")
+
+class VaultSearchResult(BaseModel):
+    id: int
+    filename: str
+    content: str
+    similarity: float
+    fts_rank: float
+
+# --- 2. ASYNC OPTIMIZED ENDPOINT (Speed) ---
+@router.post("/search", response_model=List[VaultSearchResult])
+async def search_vault(
+    req: VaultSearchRequest,
+    user_id: str = Depends(get_current_user)
+):
+    """
+    SOTA Hybrid Interrogator:
+    Executes a parallel Vector + Keyword search across the user's entire vault.
+    Now utilizes asyncio thread-pooling for non-blocking execution.
+    """
+    if not db:
+        raise HTTPException(status_code=503, detail="Vault Engine Offline")
+
+    try:
+        # 1. Non-Blocking Embedding Generation
+        # Offload the synchronous NVIDIA network call to a background thread
+        query_vector = await asyncio.to_thread(
+            get_embedding, 
+            text=req.query, 
+            input_type="query"
+        )
+
+        # 2. Prepare RPC Parameters
+        rpc_params = {
+            "query_text": req.query,
+            "query_embedding": query_vector,
+            "match_count": req.limit,
+            "target_user_id": user_id
+        }
+        
+        # 3. Non-Blocking Database Execution
+        # Offload the synchronous Supabase HTTP request to prevent event loop freezing
+        res = await asyncio.to_thread(
+            lambda: db.rpc("hybrid_vault_search", rpc_params).execute()
+        )
+        
+        # 4. Strict Type Casting & Return
+        return cast(List[Dict[str, Any]], res.data)
+
+    except Exception as e:
+        print(f"❌ VAULT SEARCH ERROR: {str(e)}")
+        # Generic 500 prevents leaking exact database schemas/errors to the client
+        raise HTTPException(status_code=500, detail="Retrieval Protocol Failure")

app/core/auth.py

@@ -0,0 +1,139 @@
+import os
+import requests
+import hashlib
+import asyncio
+from datetime import datetime
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from jose import jwt, jwk
+from typing import Optional, Dict, Any, List, cast
+from app.core.database import db
+
+# --- Security Configuration ---
+security = HTTPBearer()
+
+# SOTA: Resilient Clerk Public Key Manager
+class ClerkKeyManager:
+    _instance = None
+    _jwks: Optional[Dict[str, Any]] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(ClerkKeyManager, cls).__new__(cls)
+        return cls._instance
+
+    def get_jwks(self, force_refresh: bool = False) -> Dict[str, Any]:
+        """
+        Fetches Clerk's public keys. 
+        Supports forced cache invalidation to survive automatic Key Rotations.
+        """
+        if self._jwks is None or force_refresh:
+            jwks_url = os.getenv("CLERK_JWKS_URL")
+            if not jwks_url:
+                print("⚠️ SECURITY ALERT: CLERK_JWKS_URL missing.")
+                return {}
+            
+            try:
+                # Synchronous request, but we will wrap this in to_thread when calling
+                response = requests.get(jwks_url, timeout=10)
+                response.raise_for_status()
+                self._jwks = response.json()
+                if force_refresh:
+                    print("AXIOM-AUTH: Clerk JWKS Cache Successfully Rotated.")
+            except Exception as e:
+                print(f"❌ AUTH ERROR: Failed to fetch JWKS: {e}")
+                return self._jwks or {} # Fallback to stale cache if network is down
+        return self._jwks
+
+key_manager = ClerkKeyManager()
+
+async def get_current_user(auth: HTTPAuthorizationCredentials = Depends(security)) -> str:
+    """
+    V4.6 Enterprise Dual-Auth Guard: 
+    Fully async, non-blocking, and resilient to cryptographic key rotation.
+    """
+    token = auth.credentials
+
+    # ==========================================
+    # PATH A: AXIOM API KEY (MCP / IDE / CLI)
+    # ==========================================
+    if token.startswith("axm_live_") or token.startswith("axm_test_"):
+        if not db:
+            raise HTTPException(status_code=503, detail="Auth Database Offline")
+            
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+            
+        # 1. Non-Blocking High-speed lookup
+        res = await asyncio.to_thread(
+            lambda: db.table("api_keys").select("user_id, is_active").eq("key_value", token_hash).execute()
+        )
+        key_data = cast(List[Dict[str, Any]], res.data)
+        
+        # 2. Reject if invalid or revoked
+        if not key_data or not key_data[0].get("is_active"):
+            raise HTTPException(status_code=401, detail="Invalid or Revoked Axiom API Key.")
+            
+        # 3. SOTA: Fire-and-Forget Timestamp Update (Zero added latency for the user)
+        def update_timestamp():
+            try:
+                db.table("api_keys").update({"last_used_at": datetime.utcnow().isoformat()}).eq("key_value", token_hash).execute()
+            except Exception as e:
+                print(f"⚠️ Timestamp Update Failed (Non-fatal): {e}")
+                
+        asyncio.create_task(asyncio.to_thread(update_timestamp))
+        
+        return str(key_data[0]["user_id"])
+
+    # ==========================================
+    # PATH B: CLERK JWT (Web Browser Dashboard)
+    # ==========================================
+    
+    # 1. Async fetch of the JWKS cache
+    jwks = await asyncio.to_thread(key_manager.get_jwks)
+    
+    if not jwks:
+        if os.getenv("ENV") == "development":
+            payload = jwt.get_unverified_claims(token)
+            return str(payload.get("sub"))
+        raise HTTPException(status_code=503, detail="Auth Engine Misconfigured")
+
+    try:
+        header = jwt.get_unverified_header(token)
+        kid = header.get("kid")
+        
+        # 2. Smart Cache Invalidation (The Key Rotation Fix)
+        # If the 'kid' in the JWT isn't in our cache, Clerk likely rotated their keys.
+        # We force a refresh of the JWKS cache and try one more time.
+        if kid not in[k.get("kid") for k in jwks.get("keys", [])]:
+            print(f"AXIOM-AUTH: Unknown Key ID '{kid}' detected. Forcing JWKS rotation...")
+            jwks = await asyncio.to_thread(key_manager.get_jwks, force_refresh=True)
+
+        public_key = None
+        for key in jwks.get("keys", []):
+            if key["kid"] == kid:
+                public_key = jwk.construct(key)
+                break
+        
+        if not public_key:
+            raise HTTPException(status_code=401, detail="Invalid Security Key ID. Issuer may have revoked the key.")
+
+        # 3. VERIFY SIGNATURE, ISSUER, AND EXPIRATION
+        # (This is CPU bound, but extremely fast; safe to run synchronously here)
+        payload = jwt.decode(
+            token, 
+            public_key, 
+            algorithms=["RS256"],
+            options={"verify_aud": False}
+        )
+        
+        user_id = payload.get("sub")
+        if not user_id:
+            raise HTTPException(status_code=401, detail="Identity Subject Missing")
+            
+        return str(user_id)
+        
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=401, detail="Identity Session Expired")
+    except Exception as e:
+        print(f"❌ AUTH BREACH ATTEMPT: {str(e)}")
+        raise HTTPException(status_code=401, detail="Identity Handshake Denied")

app/core/chunking.py

@@ -0,0 +1,92 @@
+import re
+import asyncio
+from typing import List, Optional
+import tiktoken
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+class AxiomChunker:
+    """
+    SOTA Token-Aware Chunker (V4.6 Enterprise).
+    Preserves structural Markdown (Tables/Headers) for Financial/Legal accuracy.
+    Includes async offloading to prevent GIL freezes on massive PDFs.
+    """
+    def __init__(self, chunk_size: int = 400, chunk_overlap: int = 50):
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.tokenizer: Optional[tiktoken.Encoding] = None
+        self.splitter: Optional[RecursiveCharacterTextSplitter] = None
+
+    def _lazy_init(self) -> None:
+        """Fires only when the first document needs to be chunked."""
+        if self.tokenizer is None or self.splitter is None:
+            print("AXIOM-CORE: Initializing Tiktoken & Semantic Splitters...")
+            self.tokenizer = tiktoken.get_encoding("cl100k_base")
+            
+            # SOTA Splitter: Respects structural boundaries
+            self.splitter = RecursiveCharacterTextSplitter(
+                chunk_size=self.chunk_size,
+                chunk_overlap=self.chunk_overlap,
+                length_function=self._count_tokens,
+                # Prioritize splitting on double newlines to keep table rows intact
+                separators=["\n\n", "\n", ". ", " ", ""]
+            )
+
+    def _count_tokens(self, text: str) -> int:
+        if self.tokenizer is None:
+            self.tokenizer = tiktoken.get_encoding("cl100k_base")
+        return len(self.tokenizer.encode(text))
+
+    def _sanitize_markdown(self, text: str) -> str:
+        """
+        SOTA Preservative Sanitization:
+        Strips invisible/junk characters but STRICTLY PRESERVES tables, 
+        lists, and headers which are vital for vector semantics.
+        """
+        # Remove massive blocks of empty newlines (e.g., page breaks)
+        text = re.sub(r'\n{3,}', '\n\n', text)
+        # Remove zero-width spaces and weird unicode artifacts
+        text = text.replace('\u200b', '').replace('\ufeff', '')
+        # Clean trailing whitespace on lines without destroying the line itself
+        text = re.sub(r'[ \t]+$', '', text, flags=re.MULTILINE)
+        return text.strip()
+
+    def split_text(self, text: str) -> List[str]:
+        """Synchronous split (Internal use)"""
+        self._lazy_init()
+        
+        # PHASE 1: PRESERVATIVE SANITIZATION
+        clean_text = self._sanitize_markdown(text)
+        
+        # PHASE 2: SMART SPLITTING
+        if not self.splitter:
+            raise RuntimeError("Splitter failed to initialize")
+            
+        raw_chunks = self.splitter.split_text(clean_text)
+        
+        # PHASE 3: GUARDRAILS (NVIDIA NIM 512-Token Limit Compliance)
+        valid_chunks =[]
+        for c in raw_chunks:
+            # 510 allows 2 tokens overhead for embedding engine system prompts
+            if self._count_tokens(c) <= 510: 
+                valid_chunks.append(c)
+        
+        return valid_chunks
+
+    async def asplit_text(self, text: str) -> List[str]:
+        """
+        Async wrapper: Offloads heavy CPU tokenization to a background thread.
+        Prevents FastAPI event loop starvation when parsing 100+ page PDFs.
+        """
+        return await asyncio.to_thread(self.split_text, text)
+
+
+# Singleton Instance
+chunker = AxiomChunker()
+
+def get_chunks(text: str) -> List[str]:
+    """Universal synchronous interface."""
+    return chunker.split_text(text)
+
+async def aget_chunks(text: str) -> List[str]:
+    """Universal async interface for the Ingestion Port."""
+    return await chunker.asplit_text(text)

app/core/database.py

@@ -0,0 +1,41 @@
+import os
+import threading
+from typing import Optional
+from supabase import create_client, Client
+
+class Database:
+    """
+    SOTA Thread-Safe Singleton for Supabase.
+    Optimized for high-concurrency async background tasks.
+    """
+    _instance: Optional['Database'] = None
+    _lock = threading.Lock()
+    client: Optional[Client] = None
+
+    def __new__(cls) -> 'Database':
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super(Database, cls).__new__(cls)
+                    cls._instance._init_client()
+        return cls._instance
+
+    def _init_client(self) -> None:
+        url = os.environ.get("SUPABASE_URL")
+        key = os.environ.get("SUPABASE_SERVICE_KEY")
+        
+        if not url or not key:
+            print("⚠️  CRITICAL: Supabase credentials missing. Vault features will be disabled.")
+            return
+
+        try:
+            # SOTA: Initializing the Master Service Client
+            self.client = create_client(url, key)
+            print("AXIOM-CORE: Vault Database Connection Established.")
+        except Exception as e:
+            print(f"❌ DATABASE INIT ERROR: {e}")
+
+# Global Accessor
+# Initialized once at module load, but shielded by the Singleton logic.
+_db_manager = Database()
+db: Optional[Client] = _db_manager.client

app/core/embeddings.py

@@ -0,0 +1,90 @@
+import os
+import threading
+import numpy as np # type: ignore
+from typing import List, Any, Optional
+from openai import OpenAI
+
+class EmbeddingAdapter:
+    """
+    SOTA Multilingual Inference Adapter (V4.6 Thread-Safe).
+    Upgraded to Llama-Nemotron-Embed-1B-v2 for global sovereign audits.
+    Native Integration via 0.3.7 Update.
+    """
+    _instance: Optional['EmbeddingAdapter'] = None
+    _client: Optional[OpenAI] = None
+    _model_name: str = "nvidia/llama-nemotron-embed-1b-v2"
+    
+    # THE SHIELD: Thread lock for concurrent batching in ingest.py
+    _lock: threading.Lock = threading.Lock()
+
+    def __new__(cls) -> 'EmbeddingAdapter':
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super(EmbeddingAdapter, cls).__new__(cls)
+        return cls._instance
+
+    def _lazy_init(self) -> None:
+        """Thread-safe initialization of the NVIDIA client."""
+        if self._client is not None:
+            return 
+
+        with self._lock:
+            if self._client is not None:
+                return
+
+            # SOTA: Fetch key at runtime, not import time
+            api_key = os.getenv("NVIDIA_API_KEY")
+            if not api_key:
+                raise RuntimeError("CRITICAL: NVIDIA_API_KEY missing.")
+
+            print(f"AXIOM-CORE: Multilingual Link Established via {self._model_name} (Native)")
+            
+            self._client = OpenAI(
+                base_url="https://integrate.api.nvidia.com/v1",
+                api_key=api_key.strip(), # Strip removes hidden newlines!
+                max_retries=5, 
+                timeout=60.0
+            )
+
+    def _normalize(self, vector: List[float]) -> List[float]:
+        """Mathematically enforces Unit Length (L2 Norm) for pgvector speed."""
+        arr = np.array(vector)
+        norm = np.linalg.norm(arr)
+        if norm == 0:
+            return vector
+        return (arr / norm).tolist()
+
+    def embed_text(self, text: str, is_query: bool = False) -> List[float]:
+        """Transmits text to NVIDIA grid and returns a normalized 1024-D vector."""
+        self._lazy_init()
+        
+        if self._client is None:
+            return[0.0] * 1024
+
+        try:
+            target_type = "query" if is_query else "passage"
+            
+            response = self._client.embeddings.create(
+                input=[text],
+                model=self._model_name,
+                extra_body={
+                    "input_type": target_type, 
+                    "truncate": "END",
+                    "dimensions": 1024 # Forces compatibility with Supabase schema
+                }
+            )
+            raw_vector = response.data[0].embedding
+            return self._normalize(raw_vector[:1024])
+
+        except Exception as e:
+            print(f"⚠️ NEURAL LINK FAILURE: {str(e)}")
+            return[0.0] * 1024 
+
+# Singleton Instance
+_engine = EmbeddingAdapter()
+
+def get_embedding(text: str, input_type: str = "query") -> List[float]:
+    """Universal thread-safe interface for the Axiom Engine."""
+    is_query = True if input_type == "query" else False
+    return _engine.embed_text(text, is_query=is_query)

app/core/evaluator.py

@@ -0,0 +1,90 @@
+import os
+import math
+import asyncio
+from typing import Dict, List, Optional, Any
+
+# SOTA: Migration to RAGAS 0.4.x API
+from ragas import evaluate, SingleTurnSample, EvaluationDataset
+from ragas.metrics import Faithfulness
+from ragas.llms import LangchainLLMWrapper
+from langchain_openai import ChatOpenAI
+from pydantic import SecretStr
+
+# CRITICAL: Fix for Pydantic V2 "BaseCache" error
+from langchain_core.caches import BaseCache
+from langchain_core.callbacks import Callbacks
+from langchain_core.language_models.chat_models import BaseChatModel
+
+class AxiomEvaluator:
+    """
+    The Lite Auditor (V4.6 Production Refactor)
+    Stabilized for LangChain 1.x Parent-Child Type Resolution & Concurrency.
+    """
+    def __init__(self) -> None:
+        # 1. MYPY FIX: Use 'Any' because RAGAS 0.4.x wrappers are dynamically typed
+        self.evaluator_llm: Any = None
+        self.faithfulness_metric: Optional[Faithfulness] = None
+
+    def _lazy_init(self) -> None:
+        """Initializes RAGAS V2 and stabilizes the Pydantic Registry."""
+        if self.evaluator_llm is None:
+            try:
+                BaseChatModel.model_rebuild()
+                ChatOpenAI.model_rebuild()
+                print("AXIOM-CORE: Evaluator Registry Synchronized.")
+            except Exception as e:
+                print(f"AXIOM-CORE: Registry notice (Non-fatal): {e}")
+
+            print("AXIOM-CORE: Materializing RAGAS V2 Auditor (NVIDIA NIM)...")
+            raw_key = os.environ.get("NVIDIA_API_KEY")
+            
+            llm = ChatOpenAI(
+                model="meta/llama-3.3-70b-instruct",
+                temperature=0,
+                api_key=SecretStr(raw_key) if raw_key else None,
+                base_url="https://integrate.api.nvidia.com/v1",
+                max_completion_tokens=2048
+            )
+            
+            self.evaluator_llm = LangchainLLMWrapper(llm)
+            self.faithfulness_metric = Faithfulness(llm=self.evaluator_llm)
+
+    async def score_response(self, question: str, answer: str, contexts: List[str]) -> Dict[str, float]:
+        self._lazy_init()
+        try:
+            # Prepare RAGAS V2 Sample
+            sample = SingleTurnSample(
+                user_input=question, 
+                response=answer, 
+                retrieved_contexts=contexts
+            )
+            dataset = EvaluationDataset(samples=[sample])
+
+            # 2. SOTA THREAD POOLING
+            def run_ragas() -> Any:
+                return evaluate(dataset=dataset, metrics=[self.faithfulness_metric]) # type: ignore
+            
+            result = await asyncio.to_thread(run_ragas)
+            
+            # 3. Offload Pandas DataFrame operations
+            def extract_score() -> float:
+                scores_df = result.to_pandas()
+                return float(scores_df["faithfulness"].iloc[0])
+                
+            raw_val = await asyncio.to_thread(extract_score)
+            
+            # 4. Sanitize for JSON compliance
+            faithfulness_score = raw_val if math.isfinite(raw_val) else 0.0
+            print(f"AXIOM-AUDIT: Faithfulness Score Verified at {faithfulness_score * 100}%")
+
+            return {
+                "faithfulness": faithfulness_score,
+                "relevance": 1.0, 
+                "precision": 1.0
+            }
+            
+        except Exception as e:
+            print(f"RAGAS V2 EVAL ERROR: {e}")
+            return {"faithfulness": 0.0, "relevance": 1.0, "precision": 1.0}
+
+axiom_evaluator = AxiomEvaluator()

app/core/monitor.py

@@ -0,0 +1,41 @@
+import tiktoken
+from typing import List, Optional
+
+class ContextMonitor:
+    """SOTA Token Sentry V4.6. Enterprise-grade context truncation."""
+    _instance: Optional["ContextMonitor"] = None
+    encoder: Optional[tiktoken.Encoding] = None
+    LIMIT: int = 100000 
+
+    def __new__(cls) -> "ContextMonitor":
+        if cls._instance is None:
+            cls._instance = super(ContextMonitor, cls).__new__(cls)
+        return cls._instance
+
+    def _lazy_init(self) -> None:
+        if self.encoder is None:
+            print("AXIOM-CORE: Materializing Token Sentry...")
+            self.encoder = tiktoken.get_encoding("cl100k_base")
+
+    def count_tokens(self, text: str) -> int:
+        if not text: return 0
+        self._lazy_init()
+        return len(self.encoder.encode(text)) # type: ignore
+
+    def guard_context(self, context_list: List[str]) -> str:
+        self._lazy_init()
+        current_parts: List[str] = []
+        total_tokens = 0
+        
+        for chunk in context_list:
+            tokens = self.count_tokens(chunk) + 4 
+            if total_tokens + tokens > self.LIMIT:
+                break
+            current_parts.append(chunk)
+            total_tokens += tokens
+        
+        pressure = (total_tokens / self.LIMIT) * 100
+        print(f"CONTEXT_PRESSURE: {pressure:.1f}% ({total_tokens} tokens)")
+        return "\n\n".join(current_parts)
+
+monitor = ContextMonitor()

app/core/reranker.py

@@ -0,0 +1,59 @@
+import os
+import asyncio
+from typing import List, Optional
+from langchain_nvidia_ai_endpoints import NVIDIARerank
+from langchain_core.documents import Document
+
+class AxiomReranker:
+    """
+    SOTA Cloud-Lean Reranker Delegate (V4.6.1).
+    Engineered for Nemotron-Multilingual Synergy.
+    """
+    _instance = None
+    _client: Optional[NVIDIARerank] = None
+    # THE VERIFIED SLUG:
+    _model_name: str = "nvidia/llama-nemotron-rerank-1b-v2"
+
+    def __new__(cls) -> 'AxiomReranker':
+        if cls._instance is None:
+            cls._instance = super(AxiomReranker, cls).__new__(cls)
+        return cls._instance
+
+    def _lazy_init(self, top_k: int) -> None:
+        if self._client is None:
+            api_key = os.getenv("NVIDIA_API_KEY")
+            if not api_key:
+                raise RuntimeError("CRITICAL: NVIDIA_API_KEY missing.")
+            
+            print(f"AXIOM-CORE: Materializing {self._model_name}...")
+            
+            self._client = NVIDIARerank(
+                model=self._model_name,
+                api_key=api_key, # type: ignore
+                top_n=top_k
+            )
+        else:
+            self._client.top_n = top_k
+
+    async def rerank(self, query: str, documents: List[str], top_k: int = 10) -> List[str]:
+        if not documents: return []
+        if len(documents) <= top_k: return documents
+            
+        self._lazy_init(top_k=top_k)
+        
+        def perform_rerank() -> List[str]:
+            if not self._client: return documents[:top_k]
+            lc_docs = [Document(page_content=txt) for txt in documents]
+            compressed_docs = self._client.compress_documents(query=query, documents=lc_docs)
+            return [doc.page_content for doc in compressed_docs]
+
+        try:
+            return await asyncio.to_thread(perform_rerank)
+        except Exception as e:
+            print(f"⚠️ RERANKER FAILSAFE: {e}")
+            return documents[:top_k]
+
+_reranker_instance = AxiomReranker()
+
+async def get_reranked_scores(query: str, documents: List[str], top_k: int = 10) -> List[str]:
+    return await _reranker_instance.rerank(query, documents, top_k=top_k)

app/core/retriever.py

@@ -0,0 +1,110 @@
+import asyncio
+from typing import List, Dict, Any, Optional, cast, Union
+from app.core.database import db
+from app.core.embeddings import get_embedding
+
+async def hybrid_search(
+    query: str, 
+    user_id: str, 
+    filename: Optional[Union[str, List[str]]] = None,
+    limit: int = 20
+) -> List[str]:
+    """
+    SOTA Retrieval Engine V4.6.
+    Fully Asynchronous. Concurrent Multi-Doc Fetching.
+    Injects 'Exhibit-ID' metadata envelopes to force granular citations.
+    """
+    if not db: 
+        return[]
+        
+    try:
+        # 1. Non-Blocking NVIDIA Embedding Generation
+        vector = await asyncio.to_thread(get_embedding, query, "query")
+        
+        is_vault_mode = not filename or filename == "vault" or filename ==["vault"]
+        
+        # =========================================================
+        # PATH A: GLOBAL VAULT SEARCH (Multi-file hybrid search)
+        # =========================================================
+        if is_vault_mode:
+            def run_vault_rpc() -> Any:
+                return db.rpc("hybrid_vault_search", {
+                    "query_text": query,
+                    "query_embedding": vector,
+                    "match_count": limit,
+                    "target_user_id": user_id
+                }).execute()
+                
+            # Non-blocking RPC Call
+            res = await asyncio.to_thread(run_vault_rpc)
+            rows = cast(List[Dict[str, Any]], res.data)
+            
+            return[
+                f"--- EXHIBIT_START_ID_{i+1} ---\n"
+                f"FILE_SOURCE: {row['filename']}\n"
+                f"DATA_CONTENT: {row['content']}\n"
+                f"--- EXHIBIT_END_ID_{i+1} ---" 
+                for i, row in enumerate(rows)
+            ]
+
+        # =========================================================
+        # PATH B: TARGETED DOCUMENT SEARCH (Multi-doc Synthesis)
+        # =========================================================
+        target_files: List[str] =[]
+        if isinstance(filename, str):
+            target_files = [filename]
+        elif isinstance(filename, list):
+            target_files = filename
+        
+        def fetch_docs() -> Any:
+            return db.table("documents").select("id, filename").in_("filename", target_files).eq("user_id", user_id).execute()
+            
+        doc_res = await asyncio.to_thread(fetch_docs)
+        doc_data = cast(List[Dict[str, Any]], doc_res.data)
+
+        if not doc_data:
+            print(f"RETRIEVER: Context {target_files} missing from vault.")
+            return []
+
+        doc_ids = [d['id'] for d in doc_data]
+        id_to_name = {d['id']: d['filename'] for d in doc_data}
+        limit_per_doc = max(1, limit // len(doc_ids))
+        
+        # SOTA OPTIMIZATION: Concurrent RPC execution
+        # Instead of querying documents sequentially, we query them simultaneously!
+        async def fetch_chunks(d_id: int) -> List[Dict[str, Any]]:
+            def run_chunk_rpc() -> Any:
+                return db.rpc("match_document_chunks", {
+                    "query_embedding": vector,
+                    "match_limit": limit_per_doc,
+                    "target_document_id": d_id,
+                    "target_user_id": user_id
+                }).execute()
+            
+            chunk_res = await asyncio.to_thread(run_chunk_rpc)
+            chunk_rows = cast(List[Dict[str, Any]], chunk_res.data)
+            
+            # Tag each chunk with its exact filename
+            for r in chunk_rows:
+                r['filename'] = id_to_name[d_id]
+            return chunk_rows
+
+        # 3. Fire all document queries to Supabase AT THE SAME TIME
+        tasks =[fetch_chunks(d_id) for d_id in doc_ids]
+        results_nested = await asyncio.gather(*tasks)
+        
+        # Flatten the nested results array
+        all_rows = [row for sublist in results_nested for row in sublist]
+
+        # SOTA ENVELOPE INJECTION
+        return[
+            f"--- EXHIBIT_START_ID_{i+1} ---\n"
+            f"FILE_SOURCE: {row['filename']}\n"
+            f"DATA_CONTENT: {row['content']}\n"
+            f"--- EXHIBIT_END_ID_{i+1} ---" 
+            for i, row in enumerate(all_rows)
+        ]
+
+    except Exception as e:
+        print(f"❌ RETRIEVER CRITICAL ERROR: {e}")
+        return[]

app/main.py

@@ -0,0 +1,83 @@
+import os
+from dotenv import load_dotenv
+
+# SOTA: Load environment variables BEFORE any AI components initialize.
+# This guarantees LangSmith telemetry hooks attach correctly.
+load_dotenv()
+
+import nest_asyncio
+nest_asyncio.apply()
+
+import time
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+
+# Axiom Core Imports
+from app.api import ingest, run, history, vault, keys 
+from app.core.database import db
+
+# --- SOTA: Lifespan Management ---
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    print("AXIOM_CORE: Logic Core Initialized. Dependencies Warm.")
+    print("AXIOM_CORE: LangSmith Telemetry Active." if os.getenv("LANGCHAIN_TRACING_V2") == "true" else "AXIOM_CORE: Telemetry Offline.")
+    yield
+    print("AXIOM_CORE: System Offboarding Complete.")
+
+app = FastAPI(
+    title="Axiom Engine API",
+    description="V4.6 Sovereign Evidence-Gated Intelligence (Multilingual)",
+    version="4.6.0",
+    lifespan=lifespan
+)
+
+# --- SOTA: Performance Middleware ---
+app.add_middleware(GZipMiddleware, minimum_size=500)
+
+# --- SOTA: Strict CORS Security ---
+origins =[
+    "http://localhost:3000",
+    "https://axiom-engine-six.vercel.app",
+    "https://lexpertz-axiom-engine.vercel.app", 
+    "https://huggingface.co",
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=origins,
+    allow_origin_regex=r"https://.*-lexpertzai-projects\.vercel\.app", 
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["*"],
+)
+
+# --- SOTA: Telemetry Middleware ---
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    start_time = time.time()
+    response = await call_next(request)
+    process_time = time.time() - start_time
+    response.headers["X-Process-Time"] = str(round(process_time, 4))
+    return response
+
+# --- Router Registration ---
+app.include_router(ingest.router, prefix="/api/v1", tags=["Ingestion"])
+app.include_router(run.router, prefix="/api/v1", tags=["Reasoning"])
+app.include_router(history.router, prefix="/api/v1", tags=["History"])
+app.include_router(vault.router, prefix="/api/v1/vault", tags=["Vault"])
+app.include_router(keys.router, prefix="/api/v1/keys", tags=["API Keys"])
+
+# --- System Health Monitoring ---
+@app.get("/health")
+async def health_check():
+    db_status = "online" if db else "offline"
+    return {
+        "status": "operational",
+        "version": "4.6.0",
+        "vault_link": db_status,
+        "engine": "Axiom Sovereign V4.6",
+        "architect": "meta/llama-3.3-70b-instruct",
+        "vector_core": "nvidia/llama-nemotron-embed-1b-v2"
+    }

app/mcp/server.py

@@ -0,0 +1,115 @@
+import os
+import sys
+import asyncio
+from typing import List, Optional
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+# 1. PATH RESOLUTION
+BASE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+ENV_PATH = os.path.join(BASE_DIR, ".env")
+load_dotenv(ENV_PATH)
+
+# Axiom Intelligence Imports
+from app.agents.graph import app_graph
+from app.agents.state import AgentState  # CRITICAL: For MyPy type safety
+from app.core.retriever import hybrid_search
+from app.skills.github import execute_github_audit
+from app.skills.database import upload_local_csv_to_vault, execute_dataset_audit
+
+# Initialize FastMCP
+mcp = FastMCP("Axiom-Sovereign-Gateway")
+SYSTEM_USER = os.getenv("MCP_SYSTEM_USER", "svc-axiom-core")
+
+# --- 2. THE SOVEREIGN TOOLSET ---
+
+@mcp.tool()
+async def run_axiom_audit(
+    question: str = Field(..., description="The high-level audit query"),
+    filenames: List[str] = Field(..., description="The PDF filenames to target")
+) -> str:
+    """Executes a formal evidence-gated audit using the Sovereign Architect."""
+    
+    # SOTA: Strictly typed AgentState initialization
+    initial_state: AgentState = {
+        "question": question, 
+        "user_id": SYSTEM_USER,
+        "filenames": filenames, 
+        "history": [],
+        "command": None,
+        "comparison_map": {}, 
+        "documents": [], 
+        "generation": "", 
+        "hallucination_score": 0.0,
+        "metrics": {}, 
+        "status": "thinking", 
+        "retry_count": 0,
+        "active_node": None
+    }
+    
+    try:
+        # V1.x: Explicitly providing version='v1' ensures compatibility with SSE
+        final_state = await app_graph.ainvoke(initial_state, version="v1")
+        return str(final_state.get("generation", "Audit yielded no results."))
+    except Exception as e:
+        return f"Axiom Core Error: {str(e)}"
+
+@mcp.tool()
+async def search_axiom_vault(
+    query: str = Field(..., description="Search query"),
+    filenames: List[str] = Field(default=[], description="Specific files to search")
+) -> str:
+    """Performs a high-speed hybrid vector search."""
+    try:
+        results = await hybrid_search(query=query, user_id=SYSTEM_USER, filename=filenames)
+        return "\n\n".join(results) if results else "No evidence found."
+    except Exception as e:
+        return f"Retrieval Error: {str(e)}"
+
+@mcp.tool()
+async def audit_code_implementation(
+    file_path: str = Field(..., description="Path to code file"),
+    file_content: str = Field(..., description="Raw source code"),
+    audit_query: str = Field(..., description="Audit rule"),
+    vault_filenames: List[str] = Field(default=[], description="Policy docs")
+) -> str:
+    """Verifies if local code logic matches policy."""
+    return await execute_github_audit(
+        file_path=file_path, file_content=file_content,
+        audit_query=audit_query, vault_filenames=vault_filenames,
+        system_user=SYSTEM_USER
+    )
+
+@mcp.tool()
+async def upload_csv_dataset(
+    file_path: str = Field(..., description="CSV path"),
+    dataset_name: str = Field(..., description="Dataset ID")
+) -> str:
+    """Uploads spreadsheet to Vault."""
+    return await upload_local_csv_to_vault(
+        file_path=file_path, dataset_name=dataset_name, system_user=SYSTEM_USER
+    )
+
+@mcp.tool()
+async def audit_live_dataset(
+    dataset_name: str = Field(..., description="Dataset name"),
+    audit_query: str = Field(..., description="Reconciliation instructions"),
+    vault_filenames: List[str] = Field(default=[], description="PDF evidence")
+) -> str:
+    """Reconciles PDF evidence against a LIVE dataset."""
+    return await execute_dataset_audit(
+        dataset_name=dataset_name, audit_query=audit_query,
+        vault_filenames=vault_filenames, system_user=SYSTEM_USER
+    )
+
+# --- 3. TRANSPORT EXECUTION ---
+
+if __name__ == "__main__":
+    transport_mode = os.getenv("MCP_TRANSPORT", "stdio")
+    
+    if transport_mode == "sse":
+        print("Axiom MCP Gateway Launching in SSE Mode")
+        mcp.run(transport="sse")
+    else:
+        mcp.run(transport="stdio")

app/prompts/__init__.py

@@ -0,0 +1 @@
+

app/prompts/templates.py

@@ -0,0 +1,137 @@
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import PydanticOutputParser
+from pydantic import BaseModel, Field
+
+# -----------------------------------------------------------------------------
+# 1. ENTERPRISE SCHEMA REGISTRY (SOTA: Hidden Chain-of-Thought)
+# -----------------------------------------------------------------------------
+# By placing 'scratchpad' first, we force the LLM to reason step-by-step 
+# before committing to a final boolean or brief. This drastically reduces hallucinations.
+
+class DistilledContext(BaseModel):
+    scratchpad: str = Field(description="Step-by-step reasoning: analyze what the user wants, and identify if the snippets contain it.")
+    has_relevant_evidence: bool = Field(description="True ONLY if the snippets contain facts directly answering the query.")
+    brief: str = Field(description="The synthesized evidence. Preserve exact markers (e.g., --- EXHIBIT_START_ID_1 ---) and code blocks.")
+
+class HallucinationGrade(BaseModel):
+    scratchpad: str = Field(description="Step-by-step logic: compare the DRAFT REPORT against the RAW EVIDENCE. Look for missing citations or fabricated facts.")
+    is_hallucinating: str = Field(description="Must be 'true' or 'false'.")
+    explanation: str = Field(description="Final summary of the grade logic.")
+
+distill_parser = PydanticOutputParser(pydantic_object=DistilledContext)
+grade_parser = PydanticOutputParser(pydantic_object=HallucinationGrade)
+
+
+# -----------------------------------------------------------------------------
+# 2. PROMPT REGISTRY (SOTA: XML Boundaries & Dynamic Priming)
+# -----------------------------------------------------------------------------
+
+# --- AXIOM SOVEREIGN ARCHITECT IDENTITY ---
+AXIOM_SYSTEM_INSTRUCTION = """<role>
+You are the Axiom Sovereign Architect, an elite Enterprise AI Auditor. 
+Your mandate is to perform high-fidelity, evidence-gated audits across Financial, Legal, Code, and Database domains.
+</role>
+
+<core_directives>
+1. NO CHATTER: Never use conversational filler (e.g., "Here is the report").
+2. MARKDOWN ONLY: Use standard Markdown (`###`, `**text**`).
+3. HTML BAN: NEVER use HTML tags (`<font>`, `<b>`, etc.). It will crash the system.
+4. DYNAMIC HEADER: Start your response with a Markdown H3 header dynamically generated based on the User's Query topic. (e.g., `### [Insert Topic] AUDIT REPORT`).
+5. NO INTERNAL RECAP: Do not mention "The Editor Node" or "Synthesized Brief". Speak as the final authority.
+</core_directives>
+
+<domain_protocols>
+- FINANCIAL: Verify column headers before extracting numbers to prevent "Column Drift". State units explicitly.
+- LEGAL: Distinguish between obligations ("shall") vs. rights ("may"). Call out omissions.
+- CODE: Identify the PDF clause and point to the specific line/block of code.
+- DATABASE: Treat "Live Axiom Database" JSON records as the absolute source of truth.
+</domain_protocols>
+
+<citation_protocol>
+1. Granular Footnotes: Map every specific claim to its unique Exhibit ID using academic markers: [1], [2].
+2. Source References Section: Conclude your report with a `### Source References` section.
+3. List Format Requirement: Follow the exact structure shown in the example below. Do not use block quotes or paragraphs for the references.
+
+<example_format>
+### Source References
+* **[1]** SOURCE: `Filename.pdf` | LOCATION: `Section/Header`
+* **[2]** SOURCE: `Vault_Database` | LOCATION: `Row 42`
+</example_format>
+</citation_protocol>
+
+<rejection_protocol>
+If the evidence vault does not contain the answer, output EXACTLY AND ONLY: "No direct evidence found in the vault."
+</rejection_protocol>
+"""
+
+VERIFICATION_PROMPT = ChatPromptTemplate.from_messages([
+    ("system", AXIOM_SYSTEM_INSTRUCTION),
+    ("human", "<audit_query>\n{question}\n</audit_query>\n\n<evidence_vault>\n{context}\n</evidence_vault>\n\nGenerate the Final Verified Audit Report:"),
+])
+
+
+# --- THE DISTILLATION PROMPT (The Editor Node) ---
+DISTILLATION_PROMPT = ChatPromptTemplate.from_messages([
+    ("system", """<role>
+You are the Axiom Context Editor. Your goal is to clean and structure messy RAG snippets for downstream reasoning.
+</role>
+
+<editorial_mandate>
+1. Noise Extraction: Strip away redundant metadata, UI artifacts, and filler.
+2. Syntax Preservation: PRESERVE exact syntax and structure for Code and JSON.
+3. Marker Preservation: You MUST preserve all `--- EXHIBIT_START_ID_N ---` boundary markers exactly.
+4. No Summarization: Provide raw, cleaned facts in a high-density format.
+</editorial_mandate>
+
+<critical_instruction>
+You MUST output ONLY a valid JSON object matching the exact schema below. No markdown wrappers (` ```json `).
+{format_instructions}
+</critical_instruction>"""),
+    ("human", "<user_query>\n{question}\n</user_query>\n\n<raw_database_snippets>\n{context}\n</raw_database_snippets>"),
+]).partial(format_instructions=distill_parser.get_format_instructions())
+
+
+# --- THE STRATEGIST PROMPT (The Reduce Node) ---
+STRATEGIST_COMPARATIVE_PROMPT = ChatPromptTemplate.from_messages([
+    ("system", """<role>
+You are the Axiom Strategist. Your mission is a Comparative Cross-Domain Audit.
+</role>
+
+<mandate>
+Analyze the excerpts and identify the exact delta (differences). Look for Contradictions, Reconciliation Failures, and Implementation Gaps.
+</mandate>
+
+<output_protocol>
+1. Dynamic Header: Start with `### [Topic] COMPARATIVE MATRIX`.
+2. Comparative Matrix: Create a Markdown table mapping specific deviations (Columns: Feature/Clause | Source 1 | Source 2 | Risk Delta).
+3. Synthesis Summary: Write a brief executive summary below the table.
+4. Strict Citations: Use [1],[2] footnotes and conclude with a `### Source References` bulleted list.
+5. NO HTML: Never use `<font>`, `<b>`, or any HTML tags.
+</output_protocol>
+
+<rejection_protocol>
+If no comparative divergence is found, state ONLY: "No significant comparative divergence detected between the exhibits."
+</rejection_protocol>"""),
+    ("human", "<audit_query>\n{question}\n</audit_query>\n\n<exhibits>\n{context}\n</exhibits>\n\nGenerate the Comparative Audit Report:"),
+])
+
+
+# --- THE ADVERSARIAL GRADER (The Prosecutor Node) ---
+GRADING_PROMPT = ChatPromptTemplate.from_messages([
+    ("system", """<role>
+You are the Axiom Prosecutor. Your role is purely adversarial. 
+You are grading the Architect's 'DRAFT REPORT' against the 'RAW EVIDENCE'.
+</role>
+
+<grading_criteria>
+1. The Ghost Check: Does the report mention facts NOT found in the raw evidence? (Hallucination)
+2. The Column-Drift Check: Did the Architect extract a number from the wrong column?
+3. The Citation Check: Did the Architect fail to include footnotes?
+</grading_criteria>
+
+<critical_instruction>
+You MUST output ONLY a valid JSON object matching the exact schema below. No markdown wrappers.
+{format_instructions}
+</critical_instruction>"""),
+    ("human", "<raw_evidence>\n{context}\n</raw_evidence>\n\n<draft_report>\n{generation}\n</draft_report>"),
+]).partial(format_instructions=grade_parser.get_format_instructions())

app/skills/__init__.py

@@ -0,0 +1 @@
+

app/skills/database.py

@@ -0,0 +1,138 @@
+import os
+import json
+import asyncio
+import pandas as pd
+from typing import List, Dict, Any, cast
+
+from app.core.database import db
+from app.agents.graph import app_graph
+from app.agents.state import AgentState
+from app.core.retriever import hybrid_search
+
+# ==========================================
+# 1. SKILL-SPECIFIC PROMPT ADAPTERS
+# ==========================================
+DATASET_QUERY_WRAPPER = """Audit the static document claims against the LIVE structured dataset below.
+
+### LIVE DATASET ({dataset_name}):
+{dataset_content}
+
+### AUDIT QUERY:
+{audit_query}
+"""
+
+DATASET_EXHIBIT_WRAPPER = """--- EXHIBIT_START_ID_DATABASE ---
+FILE_SOURCE: Live Axiom Database | Dataset: {dataset_name}
+DATA_CONTENT: {dataset_content}
+--- EXHIBIT_END_ID_DATABASE ---"""
+
+# ==========================================
+# 2. SKILL EXECUTION LOGIC
+# ==========================================
+
+async def upload_local_csv_to_vault(
+    file_path: str, 
+    dataset_name: str, 
+    system_user: str
+) -> str:
+    """Reads a local CSV and securely uploads it to the user's JSONB vault."""
+    if not db:
+        return "CRITICAL ERROR: Database offline."
+    
+    if not os.path.exists(file_path):
+        return f"Error: File not found at {file_path}."
+    
+    try:
+        # 1. Thread-safe parsing
+        def parse_csv():
+            df = pd.read_csv(file_path)
+            return df.fillna("").columns.tolist(), df.to_dict(orient="records")
+
+        columns, records = await asyncio.to_thread(parse_csv)
+        
+        # 2. Non-blocking Database ops
+        await asyncio.to_thread(
+            lambda: db.table("user_datasets")
+            .delete()
+            .eq("user_id", system_user)
+            .eq("dataset_name", dataset_name)
+            .execute()
+        )
+        
+        await asyncio.to_thread(
+            lambda: db.table("user_datasets").insert({
+                "user_id": system_user,
+                "dataset_name": dataset_name,
+                "columns": columns,
+                "data": records
+            }).execute()
+        )
+        
+        return f"SUCCESS: Ingested {len(records)} rows into dataset '{dataset_name}'."
+        
+    except Exception as e:
+        return f"Failed to parse or upload CSV: {str(e)}"
+
+
+async def execute_dataset_audit(
+    dataset_name: str, 
+    audit_query: str, 
+    vault_filenames: List[str], 
+    system_user: str
+) -> str:
+    """Pulls live JSONB data and cross-references it with PDF context."""
+    if not db:
+        return "CRITICAL ERROR: Database offline."
+    
+    try:
+        # 1. Non-blocking fetch
+        res = await asyncio.to_thread(
+            lambda: db.table("user_datasets")
+            .select("columns, data")
+            .eq("user_id", system_user)
+            .eq("dataset_name", dataset_name)
+            .execute()
+        )
+        rows = cast(List[Dict[str, Any]], res.data)
+        
+        if not rows:
+            return f"Dataset '{dataset_name}' not found. Upload it first."
+            
+        dataset_content = json.dumps(rows[0]["data"][:500], indent=2)
+        
+        # 2. Formatting
+        formatted_query = DATASET_QUERY_WRAPPER.format(
+            dataset_name=dataset_name, dataset_content=dataset_content, audit_query=audit_query
+        )
+        
+        db_exhibit = DATASET_EXHIBIT_WRAPPER.format(
+            dataset_name=dataset_name, dataset_content=dataset_content
+        )
+        
+        # 3. PDF Retrieval
+        pdf_context = await hybrid_search(query=audit_query, user_id=system_user, filename=vault_filenames) if vault_filenames else []
+        all_context = pdf_context + [db_exhibit]
+        
+        # 4. Strictly Typed State
+        initial_state: AgentState = {
+            "question": formatted_query,
+            "user_id": system_user,
+            "filenames": vault_filenames,
+            "history": [],
+            "command": None,
+            "comparison_map": {},
+            "documents": all_context, 
+            "generation": "",
+            "hallucination_score": 0.0,
+            "metrics": {},
+            "status": "thinking",
+            "retry_count": 0,
+            "active_node": None
+        }
+        
+        # 5. Invoke circuit with SSE versioning
+        final_state = await app_graph.ainvoke(initial_state, version="v1")
+        return str(final_state.get("generation", "Audit complete."))
+        
+    except Exception as e:
+        return f"Database Audit Error: {str(e)}"

app/skills/github.py

@@ -0,0 +1,82 @@
+import os
+from typing import List
+from app.agents.graph import app_graph
+from app.core.retriever import hybrid_search
+from app.agents.state import AgentState
+
+# --- PROMPT ADAPTERS ---
+GITHUB_QUERY_WRAPPER = """Audit this codebase implementation against the provided vault evidence.
+
+### GITHUB CODE ({file_path}):
+{file_content}
+
+### AUDIT QUERY:
+{audit_query}
+"""
+
+GITHUB_EXHIBIT_WRAPPER = """--- EXHIBIT_START_ID_CODE ---
+FILE_SOURCE: GitHub Evidence | File: {file_path}
+DATA_CONTENT: {file_content}
+--- EXHIBIT_END_ID_CODE ---"""
+
+
+# --- SKILL EXECUTION LOGIC ---
+async def execute_github_audit(
+    file_path: str, 
+    file_content: str, 
+    audit_query: str, 
+    vault_filenames: List[str], 
+    system_user: str
+) -> str:
+    """
+    V4.6 SOTA: Receives local code content and cross-references it with Cloud PDF Vault.
+    Upgraded for LangGraph 1.x Strict State Typing.
+    """
+    try:
+        # 1. Format the data using the decoupled wrappers
+        formatted_query = GITHUB_QUERY_WRAPPER.format(
+            file_path=file_path, 
+            file_content=file_content, 
+            audit_query=audit_query
+        )
+        
+        code_exhibit = GITHUB_EXHIBIT_WRAPPER.format(
+            file_path=file_path, 
+            file_content=file_content
+        )
+        
+        # 2. Pull secondary context from the Supabase PDF Vault
+        pdf_context = await hybrid_search(
+            query=audit_query, 
+            user_id=system_user, 
+            filename=vault_filenames
+        ) if vault_filenames else []
+
+        # 3. Merge Local Code with Cloud PDFs into the context stream
+        all_context = pdf_context + [code_exhibit]
+        
+        # 4. Initialize State for V4.6 Graph (Strictly Typed)
+        initial_state: AgentState = {
+            "question": formatted_query,
+            "user_id": system_user,
+            "filenames": vault_filenames, 
+            "history": [],
+            "command": None,
+            "comparison_map": {},
+            "documents": all_context, 
+            "generation": "",
+            "hallucination_score": 0.0,
+            "metrics": {},
+            "status": "thinking",
+            "retry_count": 0,
+            "active_node": None
+        }
+        
+        # 5. Invoke the Sovereign reasoning circuit
+        # Using version='v1' to maintain SSE stream compatibility
+        final_state = await app_graph.ainvoke(initial_state, version="v1")
+        return str(final_state.get("generation", "Audit yielded no results."))
+        
+    except Exception as e:
+        print(f"❌ Sovereign Audit Error: {str(e)}")
+        return f"Sovereign Audit Error: {str(e)}"

migrations/001_init_vault.sql

@@ -0,0 +1,171 @@
+-- AXIOM VAULT MASTER SCHEMA V2.7-STABLE
+-- 1. Enable AI Extensions
+create extension if not exists vector;
+
+-- 2. Parent Documents Table (The Context Hub)
+create table documents (
+  id bigserial primary key,
+  filename text not null,
+  user_id text not null, -- Clerk Identity
+  status text default 'processing',
+  is_permanent boolean default false, -- Persistence Logic
+  created_at timestamptz default now()
+);
+
+-- 3. Evidence Chunks Table (The Vector Store)
+create table document_chunks (
+  id bigserial primary key,
+  document_id bigint references documents(id) on delete cascade,
+  user_id text not null, -- Clerk Identity
+  content text not null,
+  embedding vector(1024), -- NVIDIA NIM E5-v5 Standard
+  metadata jsonb,
+  created_at timestamptz default now(),
+  -- V2.7: Full-Text Search Vector (Calculated for Keyword matching)
+  fts_content tsvector generated always as (to_tsvector('english', content)) stored
+);
+
+-- 4. Audit Logs Table (Security Telemetry)
+create table audit_logs (
+  id bigserial primary key,
+  user_id text not null,
+  document_id text, 
+  question text not null,
+  faithfulness float default 0,
+  precision float default 0,
+  relevance float default 0,
+  latency float default 0,
+  created_at timestamptz default now()
+);
+
+-- 5. Security Framework (Row Level Security)
+alter table documents enable row level security;
+alter table document_chunks enable row level security;
+alter table audit_logs enable row level security;
+
+-- Document Policies
+create policy "Users can only view their own documents" on documents for select using (user_id = auth.jwt() ->> 'sub');
+create policy "Users can only insert their own documents" on documents for insert with check (user_id = auth.jwt() ->> 'sub');
+create policy "Users can only delete their own documents" on documents for delete using (user_id = auth.jwt() ->> 'sub');
+
+-- Chunk Policies
+create policy "Users can only view their own chunks" on document_chunks for select using (user_id = auth.jwt() ->> 'sub');
+
+-- Audit Log Policies
+create policy "Users can only view their own logs" on audit_logs for select using (user_id = auth.jwt() ->> 'sub');
+create policy "Users can insert own logs" on audit_logs for insert with check (user_id = auth.jwt() ->> 'sub');
+
+-- 6. High-Performance Multi-Index Strategy
+-- Semantic Search Index (Meaning)
+create index on document_chunks using hnsw (embedding vector_cosine_ops);
+-- Keyword Search Index (Exact matches)
+create index idx_fts_content on document_chunks using gin (fts_content);
+
+-- V2.7-PATCH: Optimized Hybrid Vault Search
+CREATE OR REPLACE FUNCTION hybrid_vault_search(
+  query_text TEXT,
+  query_embedding VECTOR(1024),
+  match_count INT,
+  target_user_id TEXT
+) RETURNS TABLE (
+  id BIGINT,
+  document_id BIGINT,
+  filename TEXT,
+  content TEXT,
+  similarity FLOAT,
+  fts_rank REAL
+) LANGUAGE plpgsql AS $$
+BEGIN
+  RETURN QUERY
+  SELECT 
+    c.id,
+    c.document_id,
+    d.filename,
+    c.content,
+    1 - (c.embedding <=> query_embedding) AS similarity,
+    -- FIX 1: websearch_to_tsquery for natural language resilience
+    ts_rank_cd(c.fts_content, websearch_to_tsquery('english', query_text)) AS fts_rank
+  FROM document_chunks c
+  JOIN documents d ON c.document_id = d.id
+  WHERE c.user_id = target_user_id
+  -- FIX 2: Enterprise Hybrid Weighting (0.7 Vector + 0.3 Keyword)
+  ORDER BY (0.7 * (1 - (c.embedding <=> query_embedding)) + 0.3 * ts_rank_cd(c.fts_content, websearch_to_tsquery('english', query_text))) DESC
+  LIMIT match_count;
+END;
+$$;
+-- 8. THE DOCUMENT SCOPE (Fixes Context Bleed)
+-- Searches ONLY within a specific document ID.
+create or replace function match_document_chunks(
+  query_embedding vector(1024),
+  match_limit int,
+  target_document_id bigint,
+  target_user_id text
+) returns table (
+  content text,
+  similarity float
+) language plpgsql as $$
+begin
+  return query
+  select
+    document_chunks.content,
+    1 - (document_chunks.embedding <=> query_embedding) as similarity
+  from document_chunks
+  where document_id = target_document_id and user_id = target_user_id
+  order by document_chunks.embedding <=> query_embedding
+  limit match_limit;
+end;
+$$;
+-- V2.9: Chat Persistence Layer
+create table chat_messages (
+  id bigserial primary key,
+  document_id bigint references documents(id) on delete cascade,
+  user_id text not null,
+  role text not null check (role in ('user', 'assistant')),
+  content text not null,
+  -- We store the RAGAS metrics JSON here so the history keeps the scores!
+  metrics jsonb, 
+  created_at timestamptz default now()
+);
+
+-- Enable Security
+alter table chat_messages enable row level security;
+
+-- Policies (Strict User Isolation)
+create policy "Users can only view their own chat history"
+  on chat_messages for select using (user_id = auth.jwt() ->> 'sub');
+
+create policy "Users can insert their own chat messages"
+  on chat_messages for insert with check (user_id = auth.jwt() ->> 'sub');
+
+-- Index for fast loading of long histories
+create index idx_chat_history on chat_messages(document_id, created_at);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id TEXT NOT NULL, -- Links to their Clerk ID
+    name TEXT NOT NULL, -- e.g., "MacBook Claude Desktop"
+    key_value TEXT NOT NULL UNIQUE, -- The actual axm_live_... token
+    last_used_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    is_active BOOLEAN DEFAULT TRUE
+);
+
+-- Index for ultra-fast auth lookups during API calls
+CREATE INDEX IF NOT EXISTS idx_api_keys_value ON api_keys(key_value);
+CREATE INDEX IF NOT EXISTS idx_api_keys_user ON api_keys(user_id);
+
+ALTER TABLE api_keys 
+ADD COLUMN key_hint TEXT;
+
+CREATE TABLE IF NOT EXISTS user_datasets (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    user_id TEXT NOT NULL,          -- Links to their Clerk Auth / MCP Token
+    dataset_name TEXT NOT NULL,     -- e.g., "Q1_Financial_Ledger"
+    columns TEXT[] NOT NULL,        -- e.g., ["Date", "Category", "Amount"]
+    data JSONB NOT NULL,            -- The actual rows of the CSV/Excel
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Indexes for ultra-fast JSONB querying and user isolation
+CREATE INDEX IF NOT EXISTS idx_user_datasets_user_id ON user_datasets(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_datasets_name ON user_datasets(user_id, dataset_name);

requirements.txt

@@ -0,0 +1,54 @@
+# --- Infrastructure (Non-AI Stack) ---
+fastapi==0.135.3
+uvicorn[standard]==0.44.0
+python-dotenv==1.2.2
+python-multipart==0.0.26
+python-jose[cryptography]==3.5.0
+pycryptodome==3.23.0
+tiktoken==0.12.0
+numpy==2.4.4
+httpx[http2]==0.28.1
+sse-starlette==3.3.4
+nest_asyncio==1.6.0
+
+# --- LangChain 1.x Core Ecosystem ---
+langchain-core==1.2.28
+langchain==1.2.15
+langchain-community==0.4.1
+langchain-text-splitters==1.1.1
+langchain-groq==1.1.2
+langchain-openai==1.1.12
+langchain-experimental==0.4.1
+langchain-nvidia-ai-endpoints==1.2.1
+
+# --- LangGraph (1.x Series) ---
+langgraph==1.1.6
+
+# --- Evaluation Framework ---
+ragas==0.4.3
+
+# --- AI Provider SDK ---
+openai==2.31.0
+
+# --- Document Digestion & Data ---
+docling==2.88.0
+pdf2image==1.17.0
+pypdf==6.10.0
+pandas==3.0.2
+pydantic==2.13.0
+pydantic-settings==2.13.1
+supabase==2.28.3
+python-magic==0.4.27
+
+# --- Model Context Protocol & Tools ---
+mcp==1.27.0
+PyGithub==2.9.1
+
+# --- Transitive Safety Pins ---
+langsmith==0.7.30
+tenacity==9.1.4
+jsonpatch==1.33
+setuptools==75.8.0
+
+# --- FORCE CPU-ONLY TORCH ---
+torch==2.2.2 --index-url https://download.pytorch.org/whl/cpu