mcp-agentic-pipelines 1.0.1

package/vendors/precis/backend/orchestrator/planner.py

@@ -0,0 +1,81 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+import json
+from typing import Dict, List, Optional
+
+from backend.orchestrator.types import ExecutionPlan, SubTask, TaskType
+from backend.llm.base import LLMProvider
+from backend.core.tracing import TraceCollector, TraceEventType
+
+
+class PlannerAgent:
+    """Decomposes natural language queries into structured execution plans via LLM."""
+
+    def __init__(self, llm: LLMProvider) -> None:
+        self.llm = llm
+
+    async def plan(self, query: str, available_tools: Optional[List[Dict[str, str]]] = None,
+                   conversation_history: Optional[List[Dict[str, str]]] = None,
+                   trace: Optional[TraceCollector] = None) -> ExecutionPlan:
+        if trace:
+            trace.span_start("Planner", "plan")
+
+        tool_desc = ""
+        if available_tools:
+            tool_desc = "\n".join(f"- {t['name']}: {t['description']}" for t in available_tools)
+
+        system_prompt = (
+            "You are a query planning agent. Decompose the user's question into specific subtasks. "
+            "Available specialized agents:\n"
+            f"{tool_desc}\n\n"
+            "Return ONLY valid JSON:\n"
+            '{"subtasks": [{"id": "1", "type": "factual_retrieval|data_synthesis", '
+            '"query": "specific sub-query", "priority": 1, "depends_on": []}], "reasoning": "why this plan"}\n'
+            'Use "factual_retrieval" to search documents for facts. '
+            'Use "data_synthesis" to combine multiple results into an answer.'
+        )
+
+        user_prompt = f"Query: {query}\n\nPlan this query into subtasks."
+        if conversation_history:
+            history_text = "\n".join(f"Q: {t['query']}\nA: {t.get('response_summary', '')}"
+                                     for t in conversation_history[-5:])
+            user_prompt = f"Conversation history:\n{history_text}\n\n{user_prompt}"
+
+        try:
+            response = await self.llm.generate(user_prompt, system_prompt=system_prompt, temperature=0.0, max_tokens=300)
+            plan = self._parse_response(response, query)
+        except Exception:
+            plan = self._fallback_plan(query)
+
+        if trace:
+            trace.event(TraceEventType.PLAN_CREATED, agent_name="Planner",
+                        message=f"Created plan with {len(plan.subtasks)} subtasks",
+                        data={"subtask_count": len(plan.subtasks), "reasoning": plan.reasoning})
+            trace.span_end()
+        return plan
+
+    def _parse_response(self, response: str, query: str) -> ExecutionPlan:
+        try:
+            data = json.loads(response)
+        except json.JSONDecodeError:
+            start = response.find("{")
+            end = response.rfind("}") + 1
+            data = json.loads(response[start:end]) if start >= 0 and end > start else {}
+
+        subtasks = []
+        for s in data.get("subtasks", []):
+            try:
+                ttype = TaskType(s["type"])
+            except ValueError:
+                ttype = TaskType.FACTUAL_RETRIEVAL
+            subtasks.append(SubTask(id=s.get("id", str(len(subtasks))), type=ttype,
+                                    query=s.get("query", query), priority=s.get("priority", 1),
+                                    depends_on=s.get("depends_on", [])))
+        return ExecutionPlan(original_query=query, subtasks=subtasks,
+                             reasoning=data.get("reasoning", "LLM-generated plan"))
+
+    def _fallback_plan(self, query: str) -> ExecutionPlan:
+        return ExecutionPlan(original_query=query, subtasks=[
+            SubTask(id="1", type=TaskType.FACTUAL_RETRIEVAL, query=query),
+            SubTask(id="2", type=TaskType.CREATIVE_REASONING, query=query, depends_on=["1"]),
+        ], reasoning="Fallback plan: retrieve then reason")

package/vendors/precis/backend/orchestrator/router.py

@@ -0,0 +1,319 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Type
+
+from backend.orchestrator.types import AgentResult, SubTask, TaskType
+from backend.llm.base import LLMProvider
+from backend.core.tracing import TraceCollector, TraceEventType
+
+
+@dataclass
+class AgentRegistryEntry:
+    name: str
+    task_type: TaskType
+    agent_class: Type
+    description: str
+    is_external_llm: bool = False
+    singleton_instance: object = None  # Pre-built instance to reuse (e.g., seeded index)
+
+
+class AgentRegistry:
+    """Registry mapping TaskType → specialized agent class."""
+
+    def __init__(self) -> None:
+        self._registry: Dict[TaskType, AgentRegistryEntry] = {}
+
+    def register(self, entry: AgentRegistryEntry) -> None:
+        self._registry[entry.task_type] = entry
+
+    def get(self, task_type: TaskType) -> Optional[AgentRegistryEntry]:
+        return self._registry.get(task_type)
+
+    def list_tools(self) -> List[Dict[str, str]]:
+        return [{"name": e.name, "description": e.description} for e in self._registry.values()]
+
+
+class RouterAgent:
+    """Routes SubTasks to agents. Handles parallel execution with dependency ordering."""
+    
+    # ── Section-number helpers ─────────────────────────────────────
+    
+    @staticmethod
+    def _next_section_candidates(tokens: tuple) -> list:
+        """Given a section-number token like '3.4', yield likely next
+        section numbers: '3.5', then '4'.  Used to find section
+        boundaries via the hash index."""
+        import re
+        for t in tokens:
+            m = re.match(r'^(\d+)\.(\d+)$', t)
+            if m:
+                major, minor = int(m.group(1)), int(m.group(2))
+                yield f"{major}.{minor + 1}"   # 3.4 → 3.5
+                yield str(major + 1)            # 3.4 → 4
+                break
+
+    def __init__(self, registry: AgentRegistry, llm: Optional[LLMProvider] = None) -> None:
+        self.registry = registry
+        self.llm = llm
+
+    async def execute_subtask(self, subtask: SubTask,
+                               source_filter: Optional[List[str]] = None,
+                               search_mode: str = "standard",
+                               trace: Optional[TraceCollector] = None) -> AgentResult:
+        entry = self.registry.get(subtask.type)
+        if entry is None:
+            return AgentResult(subtask_id=subtask.id, agent_name="router",
+                               success=False, error_message=f"No agent for {subtask.type.value}")
+
+        # Data synthesis is handled by main.py with LLM — return a placeholder
+        if entry.is_external_llm:
+            return AgentResult(subtask_id=subtask.id, agent_name=entry.name,
+                               success=True, data={"synthesis": "(pending LLM synthesis)"})
+
+        start = time.time()
+        if trace:
+            trace.span_start(entry.name, "execute")
+            trace.event(TraceEventType.AGENT_STARTED, agent_name=entry.name,
+                        message=f"Starting: {subtask.query[:80]}...")
+
+        try:
+            # Use singleton instance if provided, otherwise create new
+            if entry.singleton_instance is not None:
+                agent = entry.singleton_instance
+            elif not entry.is_external_llm:
+                agent = entry.agent_class()
+            else:
+                agent = None
+            if agent and hasattr(agent, "hybrid_search"):
+                # Stem query tokens to match the stemmed index
+                from backend.core.stemming import PrecisStemmer
+                stemmer = PrecisStemmer()
+                query_words = [w for w in subtask.query.lower().split() if len(w) > 1]
+                stemmed_tokens = tuple(stemmer.stem_tokens(query_words))
+                results = agent.hybrid_search(stemmed_tokens, source_filter=source_filter, trace=trace)
+                print(f"[Precis] Router hash search: source_filter={source_filter!r} results={len(results)}")
+                
+                # Auto-retry with query expansion when 0 results (Thorough mode only)
+                if len(results) == 0 and self.llm and search_mode == "thorough":
+                    try:
+                        from backend.agents.query_expander import QueryExpander
+                        expander = QueryExpander(self.llm)
+                        expanded_queries = await expander.expand(
+                            subtask.query, list(stemmed_tokens)
+                        )
+                        for eq in expanded_queries:
+                            eq_words = [w for w in eq.lower().split() if len(w) > 1]
+                            eq_stemmed = tuple(stemmer.stem_tokens(eq_words))
+                            retry_results = agent.hybrid_search(eq_stemmed, source_filter=source_filter, trace=trace)
+                            if retry_results:
+                                if trace:
+                                    trace.event(
+                                        type("TE", (), {"value": "decision.search_type"})(),
+                                        agent_name="QueryExpander",
+                                        message=f"Expanded '{subtask.query[:40]}...' → '{eq[:60]}...' → {len(retry_results)} results",
+                                        data={"original_query": subtask.query, "expanded_query": eq, "results": len(retry_results)}
+                                    )
+                                results = retry_results
+                                break
+                    except Exception as ex:
+                        if trace:
+                            trace.event(
+                                type("TE", (), {"value": "agent.failed"})(),
+                                agent_name="QueryExpander",
+                                message=f"Expansion failed: {ex}"
+                            )
+                # Build hash items (CPU work in thread)
+                def build_hash_items():
+                    items = []
+                    for r in results[:40]:
+                        text = " ".join(r.multitoken.metadata.get("original_words", r.multitoken.tokens))
+                        ctx = agent.get_context(r.multitoken.source_doc, r.multitoken.source_page,
+                                                r.multitoken.source_position)
+                        items.append({
+                            "text": text, "surrounding": ctx["surrounding"],
+                            "sentence": ctx["sentence"], "page": ctx["page"],
+                            "source": ctx["file"], "score": round(r.relevance_score, 3),
+                            "match_type": r.match_type,
+                        })
+                    return items
+
+                # Run hash build + vector search concurrently (skip vector in Fast mode)
+                hash_task = asyncio.to_thread(build_hash_items)
+                vec_task = None
+                if search_mode != "fast":
+                    try:
+                        import backend.main as _main
+                        if _main._vector_index:
+                            vec_task = asyncio.to_thread(_main._vector_index.search, subtask.query, 10, source_filter)
+                    except Exception:
+                        pass
+
+                if vec_task:
+                    raw_items, vec_results = await asyncio.gather(hash_task, vec_task)
+                else:
+                    raw_items = await hash_task
+                    vec_results = []
+                print(f"[Precis] After gather: raw_items={len(raw_items)} vec_results={len(vec_results)}")
+
+                # Fuse hash + vector results
+                if vec_results:
+                    try:
+                        from backend.agents.fusion_ranker import FusionRanker
+                        fuser = FusionRanker()
+                        fused = fuser.fuse({"hash": raw_items, "vector": vec_results}, top_k=15)
+                        raw_items = [{
+                            "text": f["text"],
+                            "surrounding": f.get("surrounding", f["text"]),
+                            "sentence": f.get("sentence", f["text"][:200]),
+                            "page": f.get("page", 1),
+                            "source": f.get("source", ""),
+                            "score": f.get("score", 0),
+                            "match_type": f.get("match_type", "fusion"),
+                        } for f in fused]
+                        if trace:
+                            trace.event(type("TE",(),{"value":"decision.fusion"})(), agent_name="FusionRanker",
+                                message=f"Fused hash+vector: {len(fused)} results",
+                                data={"vector_items": len(vec_results), "fused": len(fused)})
+                    except Exception:
+                        pass
+                
+                # Dedup by surrounding text (same paragraph = same result)
+                seen_texts = {}
+                for item in raw_items:
+                    key = item["surrounding"][:120]  # First 120 chars of surrounding context
+                    if key not in seen_texts or item["score"] > seen_texts[key]["score"]:
+                        seen_texts[key] = item
+                deduped = sorted(seen_texts.values(), key=lambda x: -x["score"])[:15]
+                print(f"[Precis] After dedup: deduped={len(deduped)} first_source={deduped[0].get('source','') if deduped else 'EMPTY'}")
+
+                # Semantic re-ranking: DISABLED — DeepSeek scores every n-gram
+                # fragment as 0, adding ~3s latency with zero ranking benefit.
+                # Re-enable when using a stronger LLM (GPT-4, Claude) that can
+                # actually judge fragment relevance.
+                _ENABLE_SEMANTIC_RERANKER = False
+                if _ENABLE_SEMANTIC_RERANKER and self.llm and len(deduped) > 3:
+                    try:
+                        from backend.agents.semantic_reranker import SemanticReRanker
+                        reranker = SemanticReRanker(self.llm)
+                        reranked = await reranker.rerank(subtask.query, deduped, top_k=5)
+                        if reranked:
+                            if trace:
+                                trace.event(
+                                    type("TE", (), {"value": "decision.rerank"})(),
+                                    agent_name="SemanticReRanker",
+                                    message=f"Re-ranked {len(deduped)} → {len(reranked)} results",
+                                    data={"before": len(deduped), "after": len(reranked),
+                                          "top_score": reranked[0].get("semantic_score", 0)}
+                                )
+                            deduped = reranked
+                    except Exception:
+                        pass  # Re-ranking is best-effort; fall back to hash scores
+
+                # Quality filter: keep results above minimum hash-score threshold.
+                # (SemanticReRanker is disabled, so we use the original hash scores.)
+                MIN_SCORE = 0.10
+                deduped = [d for d in deduped if d.get("score", 0) >= MIN_SCORE]
+                print(f"[Precis] After MIN_SCORE: deduped={len(deduped)}")
+
+                # Thorough mode: HASH found the section heading.
+                # Both matches are TOC entries — "next heading" is always
+                # the adjacent TOC line, so boundary detection fails.
+                # Instead: extract a generous window from the BEST match
+                # (the one with the most surrounding content).  No char cap —
+                # the LLM is smart enough to identify the section body.
+                if search_mode == "thorough":
+                    print(f"[Precis] Thorough: generous window from hash position")
+                    try:
+                        import os
+                        filter_set = None
+                        if source_filter:
+                            filter_set = {os.path.basename(str(f).lower().strip()) for f in source_filter}
+                        
+                        if hasattr(agent, '_doc_texts'):
+                            for filename, text in agent._doc_texts.items():
+                                if filter_set and os.path.basename(filename.lower().strip()) not in filter_set:
+                                    continue
+                                lines = text.split("\n")
+                                best_excerpt = ""
+                                best_pos = 0
+                                
+                                for r in results[:5]:
+                                    pos = r.multitoken.source_position
+                                    end = min(len(lines), pos + 300)
+                                    excerpt = "\n".join(lines[pos:end])
+                                    # Keep the one with the MOST content
+                                    if len(excerpt) > len(best_excerpt):
+                                        best_excerpt = excerpt
+                                        best_pos = pos
+                                
+                                if len(best_excerpt) > 200:
+                                    deduped.append({
+                                        "text": best_excerpt,
+                                        "source": filename,
+                                        "score": 0.7,
+                                        "match_type": "section_body",
+                                        "page": best_pos // 40 + 1,
+                                        "surrounding": best_excerpt,
+                                        "sentence": best_excerpt[:500],
+                                    })
+                                    if trace:
+                                        trace.event(
+                                            type("TE", (), {"value": "decision.direct_read"})(),
+                                            agent_name="SectionExtractor",
+                                            message=f"Section window: {len(best_excerpt)} chars from line {best_pos}",
+                                            data={"from": best_pos, "chars": len(best_excerpt)},
+                                        )
+                    except Exception:
+                        pass
+
+                result = AgentResult(subtask_id=subtask.id, agent_name=entry.name, success=True,
+                                     data={"results": deduped},
+                                     citations=[{"source_doc": r.multitoken.source_doc,
+                                                 "source_page": r.multitoken.source_page}
+                                                for r in results[:20]])
+            elif agent and hasattr(agent, "predict"):
+                import numpy as np
+                pred, contribs = agent.predict(np.array([0.5]), trace=trace)
+                result = AgentResult(subtask_id=subtask.id, agent_name=entry.name, success=True,
+                                     data={"prediction": float(pred), "contributing_nodes": contribs[:5]})
+            elif agent and hasattr(agent, "detect_all"):
+                flags = agent.detect_all(trace=trace)
+                result = AgentResult(subtask_id=subtask.id, agent_name=entry.name, success=True,
+                                     data={"flags": [{"entity": f.entity_id, "type": f.flag_type,
+                                                      "severity": f.severity} for f in flags]})
+            else:
+                result = AgentResult(subtask_id=subtask.id, agent_name=entry.name, success=True,
+                                     data={"response": "Agent executed successfully"})
+        except Exception as e:
+            result = AgentResult(subtask_id=subtask.id, agent_name=entry.name,
+                                 success=False, error_message=str(e))
+
+        result.execution_time_ms = (time.time() - start) * 1000
+        if trace:
+            trace.event(TraceEventType.AGENT_COMPLETED, agent_name=entry.name,
+                        message="Completed" if result.success else f"Failed: {result.error_message}",
+                        data={"success": result.success, "duration_ms": result.execution_time_ms})
+            trace.span_end()
+        return result
+
+    async def execute_plan(self, subtasks: List[SubTask], max_parallel: int = 4,
+                            source_filter: Optional[List[str]] = None,
+                            search_mode: str = "standard",
+                            trace: Optional[TraceCollector] = None) -> List[AgentResult]:
+        print(f"[Precis] execute_plan: source_filter={source_filter!r} mode={search_mode}")
+        results: Dict[str, AgentResult] = {}
+        pending = list(subtasks)
+        while pending:
+            ready = [s for s in pending if all(d in results for d in s.depends_on)]
+            if not ready:
+                break
+            batch = ready[:max_parallel]
+            pending = [s for s in pending if s not in batch]
+            batch_results = await asyncio.gather(*(self.execute_subtask(s, source_filter, search_mode, trace) for s in batch))
+            for s, r in zip(batch, batch_results):
+                results[s.id] = r
+        return [results.get(s.id, AgentResult(subtask_id=s.id, agent_name="router", success=False,
+                                               error_message="Dependency not met")) for s in subtasks]

package/vendors/precis/backend/orchestrator/types.py

@@ -0,0 +1,58 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+import uuid
+
+
+class TaskType(str, Enum):
+    FACTUAL_RETRIEVAL = "factual_retrieval"
+    ANOMALY_DETECTION = "anomaly_detection"
+    PREDICTION = "prediction"
+    DATA_SYNTHESIS = "data_synthesis"
+    CREATIVE_REASONING = "creative_reasoning"
+    EVALUATION = "evaluation"
+
+
+@dataclass
+class SubTask:
+    id: str
+    type: TaskType
+    query: str
+    context: Dict[str, Any] = field(default_factory=dict)
+    priority: int = 1
+    depends_on: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ExecutionPlan:
+    plan_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    original_query: str = ""
+    subtasks: List[SubTask] = field(default_factory=list)
+    reasoning: str = ""
+    created_at: datetime = field(default_factory=datetime.now)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentResult:
+    subtask_id: str = ""
+    agent_name: str = ""
+    success: bool = True
+    data: Any = None
+    citations: List[Dict[str, Any]] = field(default_factory=list)
+    error_message: str = ""
+    execution_time_ms: float = 0.0
+
+
+@dataclass
+class FinalReport:
+    query: str = ""
+    narrative: str = ""
+    agent_results: List[AgentResult] = field(default_factory=list)
+    evaluation: Optional[Any] = None
+    citations: List[Dict[str, Any]] = field(default_factory=list)
+    generated_at: datetime = field(default_factory=datetime.now)
+    execution_plan: Optional[ExecutionPlan] = None

package/vendors/precis/bridge_precis.py

@@ -0,0 +1,185 @@
+"""
+Precis Bridge — stdin/stdout JSON worker for MCP server.
+
+Usage: python bridge_precis.py
+
+Reads JSON requests from stdin, processes them using the real Precis backend,
+writes JSON responses to stdout.
+
+Protocol:
+  Input:  {"id": 1, "action": "query", "params": {"query": "...", "search_mode": "standard"}}
+  Output: {"id": 1, "result": {...}} or {"id": 1, "error": "message"}
+
+Actions:
+  - query:         Full RAG pipeline
+  - list_documents: List indexed documents
+  - debug_stem:     Show stemmer output for a query
+  - debug_search:   Direct hybrid search result
+  - health:         Returns {"status": "ok"}
+"""
+
+import sys, importlib, json, asyncio, os
+
+# ── Verify dependencies (installed by MCP server on startup) ─────
+REQUIRED = {'fastapi': 'fastapi', 'uvicorn': 'uvicorn', 'pydantic': 'pydantic',
+            'numpy': 'numpy', 'nltk': 'nltk', 'sqlalchemy': 'sqlalchemy',
+            'httpx': 'httpx', 'dotenv': 'python-dotenv'}
+_missing = [mod for mod in REQUIRED if not importlib.util.find_spec(mod)]
+if _missing:
+    sys.stderr.write(f'[precis] FATAL: missing packages: {", ".join(_missing)}. '
+                     f'The MCP server should have installed them.\n')
+    sys.stderr.flush()
+    sys.exit(1)
+
+# Ensure the precis-agentic-pipeline directory is on sys.path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Suppress excessive logging
+os.environ.setdefault('PRECIS_LOG_LEVEL', 'WARNING')
+
+# ── Global state (initialized lazily) ──────────────────────────────────
+_app = None
+_loop = None
+
+def get_loop():
+    global _loop
+    if _loop is None or _loop.is_closed():
+        _loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(_loop)
+    return _loop
+
+def init_app():
+    """Initialize the Precis FastAPI app and its lifespan (DB, indexes, LLM)."""
+    global _app
+    if _app is not None:
+        return _app
+
+    from backend.main import app, lifespan
+    _app = app
+
+    loop = get_loop()
+    # Run the lifespan startup
+    async def startup():
+        async with lifespan(app) as gen:
+            await gen.__anext__()
+    loop.run_until_complete(startup())
+
+    return _app
+
+
+def handle_query(params):
+    """Execute a full RAG query through the real Precis pipeline."""
+    from backend.main import process_query
+
+    loop = get_loop()
+    query_dict = {
+        "query": params.get("query", ""),
+        "session_id": params.get("session_id", None),
+        "source_filter": params.get("source_filter", None),
+        "search_mode": params.get("search_mode", "standard"),
+    }
+
+    result = loop.run_until_complete(process_query(query_dict))
+    return result
+
+
+def handle_list_documents(params):
+    """List indexed documents from the database."""
+    from backend.db.repository import get_all_documents
+    docs = get_all_documents()
+    return docs
+
+
+def handle_debug_stem(params):
+    """Show how the PrecisStemmer processes a query."""
+    from backend.core.stemming import PrecisStemmer
+    stemmer = PrecisStemmer()
+    raw = params.get("q", "").lower().split()
+    stemmed = stemmer.stem_tokens(raw)
+    return {"raw_tokens": raw, "stemmed_tokens": list(stemmed)}
+
+
+def handle_debug_search(params):
+    """Run a direct hybrid search bypassing the planner."""
+    from backend.core.stemming import PrecisStemmer
+    import backend.main as _main
+
+    stemmer = PrecisStemmer()
+    raw = params.get("q", "").lower().split()
+    stemmed = tuple(stemmer.stem_tokens(raw))
+    index = _main._demo_index
+    results = index.hybrid_search(stemmed)
+
+    return {
+        "query": params.get("q", ""),
+        "stemmed_tokens": list(stemmed),
+        "result_count": len(results),
+        "results": [
+            {
+                "tokens": list(r.multitoken.tokens) if hasattr(r, 'multitoken') else [],
+                "source": r.multitoken.source_doc if hasattr(r, 'multitoken') else "",
+                "score": r.relevance_score if hasattr(r, 'relevance_score') else 0,
+                "match_type": r.match_type if hasattr(r, 'match_type') else "",
+            }
+            for r in results[:10]
+        ],
+    }
+
+
+# ── Action dispatcher ─────────────────────────────────────────────────
+
+ACTIONS = {
+    "query": handle_query,
+    "list_documents": handle_list_documents,
+    "debug_stem": handle_debug_stem,
+    "debug_search": handle_debug_search,
+    "health": lambda p: {"status": "ok", "backend": "precis"},
+}
+
+
+def main():
+    # Send ready signal
+    sys.stdout.write("__READY__\n")
+    sys.stdout.flush()
+
+    # Initialize app on first request, not at startup (faster initial ready signal)
+    _initialized = False
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            request = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        req_id = request.get("id")
+        action = request.get("action", "")
+        params = request.get("params", {})
+
+        handler = ACTIONS.get(action)
+        if not handler:
+            result = {"id": req_id, "error": f"Unknown action: {action}"}
+            sys.stdout.write(json.dumps(result) + "\n")
+            sys.stdout.flush()
+            continue
+
+        try:
+            # Lazy init
+            if not _initialized and action != "health":
+                init_app()
+                _initialized = True
+
+            result_data = handler(params)
+            response = {"id": req_id, "result": result_data}
+        except Exception as e:
+            response = {"id": req_id, "error": str(e)}
+
+        sys.stdout.write(json.dumps(response, default=str) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/vendors/precis/data/sample_reports/README.md

@@ -0,0 +1,8 @@
+# Sample data for Precis demo
+# Place public 10-K reports, earnings transcripts, or financial documents here.
+# These are used by the seed_data.py script to populate the demo index.
+#
+# Suggested sources (all public domain):
+#   - SEC EDGAR: https://www.sec.gov/edgar.shtml
+#   - Sample 10-K filings from large public companies
+#   - Earnings call transcripts