mcp-agentic-pipelines 1.0.1

package/vendors/precis/backend/db/models.py

@@ -0,0 +1,173 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================
+# All persistent entities in the Precis system.
+# Single SQLite database file: data/app.db
+#
+# Tables:
+#   execution_traces  — Complete audit trail per query (JSON events)
+#   conversation_turns— Conversation history per session
+#   document_index    — Metadata about indexed documents
+#   agent_metrics     — Aggregated per-agent performance over time
+#
+# Related:
+#   backend/db/repository.py  — Data access layer
+#   backend/core/tracing.py   — TraceCollector (produces trace data)
+#   backend/orchestrator/memory.py — Conversation turn storage
+# =============================================================================
+
+from datetime import datetime, timezone
+from typing import Optional
+import uuid
+
+from sqlalchemy import Column, String, Integer, Float, Text, DateTime, ForeignKey, Index
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    """Base class for all SQLAlchemy ORM models."""
+    pass
+
+
+# =============================================================================
+# ExecutionTrace — The User-Facing Audit Trail
+# =============================================================================
+
+class ExecutionTrace(Base):
+    """
+    Stores the complete audit trail for a single query execution.
+
+    Each row = one user query, with ALL agent decision events stored
+    as a JSON array in the events_json column.
+
+    Why one JSON column instead of normalized event rows?
+      - Write pattern: All events for a query are generated together.
+        One INSERT is faster and simpler than N INSERTs.
+      - Read pattern: User always requests the FULL trace for a query.
+        No need to join — just SELECT the JSON column.
+      - Query pattern: When you DO need to analyze across traces,
+        SQLite's json_extract() function can query into the JSON.
+    """
+
+    __tablename__ = "execution_traces"
+
+    # Primary key
+    trace_id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+
+    # Links
+    query_id = Column(String(36), nullable=False, index=True)
+    session_id = Column(String(36), nullable=True, index=True)
+
+    # Content
+    query_text = Column(Text, nullable=False)          # The original user query
+    events_json = Column(Text, nullable=False)          # Full trace as JSON string
+    status = Column(String(20), nullable=False, default="success")  # success | error
+
+    # Metrics
+    duration_ms = Column(Integer, nullable=False, default=0)
+    agent_count = Column(Integer, nullable=False, default=0)  # How many agents executed
+    event_count = Column(Integer, nullable=False, default=0)  # How many trace events
+
+    # Timestamps
+    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
+
+    # Index for fast lookup: find all traces for a session
+    __table_args__ = (
+        Index("idx_traces_session", "session_id", "created_at"),
+    )
+
+
+# =============================================================================
+# ConversationTurn — Persistent Conversation History
+# =============================================================================
+
+class ConversationTurn(Base):
+    """
+    Stores a single turn (query + response pair) in a conversation.
+
+    Used by MemoryAgent (backend/orchestrator/memory.py) for Tier 2 persistence.
+    Tier 1 is in-memory OrderedDict. Tier 2 is this SQLite table.
+    """
+
+    __tablename__ = "conversation_turns"
+
+    turn_id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    session_id = Column(String(36), nullable=False, index=True)
+    query_text = Column(Text, nullable=False)
+    response_summary = Column(Text, nullable=True)       # LLM-generated compact summary
+    trace_id = Column(String(36), nullable=True)          # Link to full execution trace
+    plan_used = Column(Text, nullable=True)               # JSON of the ExecutionPlan
+    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
+
+
+# =============================================================================
+# DocumentIndex — Metadata About Indexed Documents
+# =============================================================================
+
+class DocumentIndex(Base):
+    """
+    Tracks documents that have been ingested into the ExactHash index.
+
+    Used to avoid re-indexing documents and to show the user what's available.
+    """
+
+    __tablename__ = "document_index"
+
+    doc_id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    filename = Column(String(500), nullable=False, unique=True)
+    file_hash = Column(String(64), nullable=False)        # SHA-256 of file contents
+    page_count = Column(Integer, nullable=False, default=0)
+    multitoken_count = Column(Integer, nullable=False, default=0)
+    document_text = Column(Text, nullable=True)            # Original text for re-indexing on restart
+    corpus_name = Column(String(100), nullable=False, default="default")
+    indexed_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
+
+
+# =============================================================================
+# AgentMetrics — Aggregated Performance Over Time
+# =============================================================================
+
+class AgentMetrics(Base):
+    """
+    Aggregated performance metrics per agent, updated periodically.
+
+    Feeds the Evaluation Dashboard (frontend/src/app/evaluate/page.tsx)
+    and AgentStatusCard components.
+    """
+
+    __tablename__ = "agent_metrics"
+
+    metric_id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    agent_name = Column(String(50), nullable=False, index=True)
+    metric_name = Column(String(50), nullable=False)       # "avg_latency_ms", "accuracy", etc.
+    metric_value = Column(Float, nullable=False)
+    sample_count = Column(Integer, nullable=False, default=0)
+    computed_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))
+
+
+# =============================================================================
+# WorkOrder — Extracted Aviation MRO Work Orders
+# =============================================================================
+
+class WorkOrderRecord(Base):
+    """Structured work order extracted from aviation maintenance documents."""
+
+    __tablename__ = "work_orders"
+
+    wo_id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))
+    source_file = Column(String(500), nullable=False)
+    tail_number = Column(String(20), nullable=True, index=True)
+    work_order_number = Column(String(50), nullable=True, index=True)
+    date = Column(String(30), nullable=True)
+    aircraft_model = Column(String(30), nullable=True)
+    part_numbers = Column(Text, nullable=True)     # JSON array
+    part_descriptions = Column(Text, nullable=True) # JSON array
+    serial_numbers = Column(Text, nullable=True)    # JSON array
+    mechanic_id = Column(String(30), nullable=True, index=True)
+    station = Column(String(10), nullable=True, index=True)
+    work_performed = Column(Text, nullable=True)
+    hours_worked = Column(String(20), nullable=True)
+    ad_sb_references = Column(Text, nullable=True)  # JSON array
+    inspector_stamp = Column(String(50), nullable=True)
+    extracted_fields_json = Column(Text, nullable=True)  # Full extraction trace
+    created_at = Column(DateTime, nullable=False, default=lambda: datetime.now(timezone.utc))

package/vendors/precis/backend/db/repository.py

@@ -0,0 +1,269 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+import json
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+import uuid
+
+from sqlalchemy import create_engine, desc
+from sqlalchemy.orm import Session
+
+from backend.db.models import Base, ExecutionTrace, ConversationTurn, DocumentIndex, AgentMetrics
+from backend.config import settings
+
+_engine = create_engine(
+    settings.DATABASE_URL,
+    connect_args={"check_same_thread": False} if "sqlite" in settings.DATABASE_URL else {},
+    echo=False,
+)
+
+
+def init_db() -> None:
+    """Create all tables. Safe to call multiple times."""
+    Base.metadata.create_all(bind=_engine)
+
+
+def get_session() -> Session:
+    return Session(_engine)
+
+
+# ── ExecutionTrace ─────────────────────────────────────────────
+
+def save_trace(query_id: str, query_text: str, events_json: str,
+               session_id: Optional[str] = None, status: str = "success",
+               duration_ms: int = 0, agent_count: int = 0, event_count: int = 0) -> str:
+    """Persist a completed execution trace. Returns trace_id."""
+    trace_id = str(uuid.uuid4())
+    with get_session() as session:
+        trace = ExecutionTrace(
+            trace_id=trace_id, query_id=query_id, session_id=session_id,
+            query_text=query_text, events_json=events_json, status=status,
+            duration_ms=duration_ms, agent_count=agent_count, event_count=event_count,
+        )
+        session.add(trace)
+        session.commit()
+    return trace_id
+
+
+def get_trace(trace_id: str) -> Optional[Dict]:
+    """Retrieve a trace by ID. Returns dict or None."""
+    with get_session() as session:
+        row = session.get(ExecutionTrace, trace_id)
+        if row is None:
+            return None
+        return {
+            "trace_id": row.trace_id, "query_id": row.query_id,
+            "query_text": row.query_text, "status": row.status,
+            "duration_ms": row.duration_ms, "agent_count": row.agent_count,
+            "event_count": row.event_count,
+            "events_json": json.loads(row.events_json) if row.events_json else {},
+            "created_at": row.created_at.isoformat() if row.created_at else "",
+        }
+
+
+def get_traces_for_session(session_id: str, limit: int = 50) -> List[Dict]:
+    """Get all traces for a session, most recent first."""
+    with get_session() as session:
+        rows = (session.query(ExecutionTrace)
+                .filter(ExecutionTrace.session_id == session_id)
+                .order_by(desc(ExecutionTrace.created_at))
+                .limit(limit).all())
+        return [_trace_summary(r) for r in rows]
+
+
+def get_recent_traces(limit: int = 20) -> List[Dict]:
+    with get_session() as session:
+        rows = (session.query(ExecutionTrace)
+                .order_by(desc(ExecutionTrace.created_at)).limit(limit).all())
+        return [_trace_summary(r) for r in rows]
+
+
+def _trace_summary(row: ExecutionTrace) -> Dict:
+    return {"trace_id": row.trace_id, "query_id": row.query_id,
+            "query_text": row.query_text[:200], "status": row.status,
+            "duration_ms": row.duration_ms, "agent_count": row.agent_count,
+            "created_at": row.created_at.isoformat() if row.created_at else ""}
+
+
+# ── Conversation ───────────────────────────────────────────────
+
+def save_conversation_turn(session_id: str, query_text: str, response_summary: str,
+                           trace_id: Optional[str] = None, plan_used: Optional[str] = None) -> str:
+    turn_id = str(uuid.uuid4())
+    with get_session() as session:
+        turn = ConversationTurn(turn_id=turn_id, session_id=session_id,
+                                query_text=query_text, response_summary=response_summary,
+                                trace_id=trace_id, plan_used=plan_used)
+        session.add(turn)
+        session.commit()
+    return turn_id
+
+
+def get_conversation_history(session_id: str, limit: int = 50) -> List[Dict]:
+    with get_session() as session:
+        rows = (session.query(ConversationTurn)
+                .filter(ConversationTurn.session_id == session_id)
+                .order_by(desc(ConversationTurn.created_at)).limit(limit).all())
+        return [{"turn_id": r.turn_id, "query_text": r.query_text,
+                 "response_summary": r.response_summary,
+                 "trace_id": r.trace_id, "created_at": r.created_at.isoformat() if r.created_at else ""}
+                for r in rows]
+
+
+# ── Document Index ─────────────────────────────────────────────
+
+def register_document(filename: str, file_hash: str, page_count: int,
+                      multitoken_count: int, corpus_name: str = "default") -> str:
+    with get_session() as session:
+        existing = session.query(DocumentIndex).filter(DocumentIndex.file_hash == file_hash).first()
+        if existing:
+            return existing.doc_id
+        doc_id = str(uuid.uuid4())
+        doc = DocumentIndex(doc_id=doc_id, filename=filename, file_hash=file_hash,
+                            page_count=page_count, multitoken_count=multitoken_count,
+                            corpus_name=corpus_name)
+        session.add(doc)
+        session.commit()
+    return doc_id
+
+
+def register_document_simple(filename: str, content_hash: str = "", multi_token_count: int = 0,
+                             corpus_name: str = "default", document_text: str = "") -> str:
+    """Lightweight registration for uploaded docs (no page count needed)."""
+    with get_session() as session:
+        existing = session.query(DocumentIndex).filter(
+            DocumentIndex.filename == filename,
+            DocumentIndex.corpus_name == corpus_name
+        ).first()
+        if existing:
+            existing.multitoken_count = multi_token_count
+            if document_text:
+                existing.document_text = document_text
+            session.commit()
+            return existing.doc_id
+        doc_id = str(uuid.uuid4())
+        doc = DocumentIndex(doc_id=doc_id, filename=filename,
+                            file_hash=content_hash or filename,
+                            page_count=1, multitoken_count=multi_token_count,
+                            corpus_name=corpus_name, document_text=document_text)
+        session.add(doc)
+        session.commit()
+    return doc_id
+
+
+def get_all_documents(corpus_name: str = "default") -> list:
+    with get_session() as session:
+        rows = (session.query(DocumentIndex)
+                .filter(DocumentIndex.corpus_name == corpus_name)
+                .order_by(DocumentIndex.indexed_at.desc()).all())
+        return [{"doc_id": r.doc_id, "filename": r.filename,
+                 "multitoken_count": r.multitoken_count,
+                 "page_count": r.page_count,
+                 "indexed_at": r.indexed_at.isoformat() if r.indexed_at else ""}
+                for r in rows]
+
+
+def get_all_document_texts(corpus_name: str = "default") -> list:
+    """Retrieve all stored document texts for re-indexing on startup."""
+    with get_session() as session:
+        rows = (session.query(DocumentIndex)
+                .filter(DocumentIndex.corpus_name == corpus_name,
+                        DocumentIndex.document_text.isnot(None),
+                        DocumentIndex.document_text != "")
+                .all())
+        return [{"filename": r.filename, "text": r.document_text, "multitoken_count": r.multitoken_count}
+                for r in rows]
+
+
+def get_indexed_documents(corpus_name: str = "default") -> List[Dict]:
+    with get_session() as session:
+        rows = (session.query(DocumentIndex)
+                .filter(DocumentIndex.corpus_name == corpus_name)
+                .order_by(desc(DocumentIndex.indexed_at)).all())
+        return [{"doc_id": r.doc_id, "filename": r.filename, "page_count": r.page_count,
+                 "multitoken_count": r.multitoken_count,
+                 "indexed_at": r.indexed_at.isoformat() if r.indexed_at else ""} for r in rows]
+
+
+# ── Agent Metrics ──────────────────────────────────────────────
+
+def record_agent_metric(agent_name: str, metric_name: str, metric_value: float) -> None:
+    with get_session() as session:
+        m = AgentMetrics(metric_id=str(uuid.uuid4()), agent_name=agent_name,
+                         metric_name=metric_name, metric_value=metric_value, sample_count=1)
+        session.add(m)
+        session.commit()
+
+
+def get_agent_metrics(agent_name: str, metric_name: str, limit: int = 100) -> List[Dict]:
+    with get_session() as session:
+        rows = (session.query(AgentMetrics)
+                .filter(AgentMetrics.agent_name == agent_name,
+                        AgentMetrics.metric_name == metric_name)
+                .order_by(desc(AgentMetrics.computed_at)).limit(limit).all())
+        return [{"metric_value": r.metric_value, "computed_at": r.computed_at.isoformat() if r.computed_at else ""}
+                for r in rows]
+
+
+# ── Work Orders ─────────────────────────────────────────────────
+
+def save_work_order(wo) -> str:
+    """Save an extracted WorkOrder to the database. Returns work_order_id."""
+    import json
+    from backend.db.models import WorkOrderRecord
+    wo_id = str(uuid.uuid4())
+    with get_session() as session:
+        record = WorkOrderRecord(
+            wo_id=wo_id,
+            source_file=wo.source_file,
+            tail_number=wo.tail_number,
+            work_order_number=wo.work_order_number,
+            date=wo.date,
+            aircraft_model=wo.aircraft_model,
+            part_numbers=json.dumps(wo.part_numbers),
+            part_descriptions=json.dumps(wo.part_descriptions),
+            serial_numbers=json.dumps(wo.serial_numbers),
+            mechanic_id=wo.mechanic_id,
+            station=wo.station,
+            work_performed=wo.work_performed[:2000] if wo.work_performed else None,
+            hours_worked=wo.hours_worked,
+            ad_sb_references=json.dumps(wo.ad_sb_references),
+            inspector_stamp=wo.inspector_stamp,
+            extracted_fields_json=json.dumps([{
+                "field_name": f.field_name, "raw_label": f.raw_label,
+                "value": f.value, "confidence": f.confidence,
+                "page": f.page, "line": f.line_number,
+            } for f in wo.extracted_fields]),
+        )
+        session.add(record)
+        session.commit()
+    return wo_id
+
+
+def query_work_orders(tail_number: str = "", mechanic_id: str = "", limit: int = 50) -> list:
+    """Query work orders by tail number, mechanic ID, or return recent."""
+    from backend.db.models import WorkOrderRecord
+    import json
+    with get_session() as session:
+        q = session.query(WorkOrderRecord)
+        if tail_number:
+            q = q.filter(WorkOrderRecord.tail_number == tail_number)
+        if mechanic_id:
+            q = q.filter(WorkOrderRecord.mechanic_id == mechanic_id)
+        rows = q.order_by(desc(WorkOrderRecord.created_at)).limit(limit).all()
+        return [{
+            "wo_id": r.wo_id,
+            "source_file": r.source_file,
+            "tail_number": r.tail_number,
+            "work_order_number": r.work_order_number,
+            "date": r.date,
+            "aircraft_model": r.aircraft_model,
+            "part_numbers": json.loads(r.part_numbers) if r.part_numbers else [],
+            "mechanic_id": r.mechanic_id,
+            "station": r.station,
+            "hours_worked": r.hours_worked,
+            "ad_sb_references": json.loads(r.ad_sb_references) if r.ad_sb_references else [],
+            "inspector_stamp": r.inspector_stamp,
+            "work_performed": (r.work_performed or "")[:300],
+            "created_at": r.created_at.isoformat() if r.created_at else "",
+        } for r in rows]

package/vendors/precis/backend/llm/__init__.py

@@ -0,0 +1,3 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================

package/vendors/precis/backend/llm/anthropic_provider.py

@@ -0,0 +1,39 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+from typing import AsyncGenerator, List, Optional
+from anthropic import AsyncAnthropic
+from backend.llm.base import LLMProvider
+
+
+class AnthropicProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = "claude-3-5-sonnet-20241022") -> None:
+        self._client = AsyncAnthropic(api_key=api_key)
+        self._model = model
+
+    async def generate(self, prompt: str, system_prompt: Optional[str] = None,
+                       temperature: float = 0.7, max_tokens: int = 4096, **kwargs) -> str:
+        resp = await self._client.messages.create(
+            model=self._model, max_tokens=max_tokens, temperature=temperature,
+            system=system_prompt or "",
+            messages=[{"role": "user", "content": prompt}], **kwargs)
+        return resp.content[0].text if resp.content else ""
+
+    async def generate_stream(self, prompt: str, system_prompt: Optional[str] = None,
+                              temperature: float = 0.7, max_tokens: int = 4096, **kwargs) -> AsyncGenerator[str, None]:
+        async with self._client.messages.stream(
+            model=self._model, max_tokens=max_tokens, temperature=temperature,
+            system=system_prompt or "",
+            messages=[{"role": "user", "content": prompt}], **kwargs) as stream:
+            async for text in stream.text_stream:
+                yield text
+
+    async def embed(self, texts: List[str], model: Optional[str] = None) -> List[List[float]]:
+        raise NotImplementedError("Anthropic does not provide a public embeddings API")
+
+    def get_model_name(self) -> str: return self._model
+
+    def get_token_count(self, text: str) -> int:
+        try:
+            return self._client.count_tokens(text)
+        except Exception:
+            return len(text) // 4

package/vendors/precis/backend/llm/base.py

@@ -0,0 +1,147 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================
+# Model-agnostic interface for all external LLM providers.
+# Every provider implements this interface → orchestrator doesn't care which LLM.
+#
+# Supported providers:
+#   - OpenAIProvider      → GPT-4o, GPT-4, GPT-3.5 (backend/llm/openai_provider.py)
+#   - AnthropicProvider   → Claude 3.5 Sonnet, Claude 3 Opus
+#   - GoogleProvider      → Gemini 1.5 Pro, Gemini 1.5 Flash
+#   - DeepSeekProvider    → DeepSeek V4 Pro, DeepSeek Reasoner
+#   - OllamaProvider      → Llama 3, Mistral, Phi-3 (local, no API key)
+#
+# Usage:
+#   provider = LLMFactory.create("openai")  # or "ollama" for local
+#   response = await provider.generate("Hello, world!")
+#
+# Related:
+#   backend/llm/factory.py     — Factory for creating providers from config
+#   backend/config.py          — Settings (API keys, default provider)
+# =============================================================================
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional, AsyncGenerator
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base for all LLM providers.
+
+    Every provider must implement:
+      - generate(): Single-turn text generation
+      - generate_stream(): Streaming text generation (for real-time UI)
+      - Embed (optional): Generate embeddings (for semantic fallback)
+
+    The orchestrator uses this interface exclusively — it never
+    imports provider-specific classes directly.
+    """
+
+    @abstractmethod
+    async def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+        **kwargs,
+    ) -> str:
+        """
+        Generate a text completion for the given prompt.
+
+        Args:
+            prompt: The user/agent prompt
+            system_prompt: Optional system-level instruction
+            temperature: Creativity level (0.0 = deterministic, 1.0 = creative)
+            max_tokens: Maximum tokens in the response
+            **kwargs: Provider-specific parameters
+
+        Returns:
+            Generated text response
+        """
+        ...
+        # TODO: Each provider implements this differently
+        #   - OpenAI: client.chat.completions.create()
+        #   - Anthropic: client.messages.create()
+        #   - Google: model.generate_content()
+        #   - Ollama: client.chat()
+        pass
+
+    @abstractmethod
+    async def generate_stream(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+        **kwargs,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Stream a text completion token by token.
+
+        Used by the WebSocket endpoint to stream agent outputs
+        to the frontend in real-time (AgentTimeline component).
+
+        Args:
+            prompt: The user/agent prompt
+            system_prompt: Optional system-level instruction
+            temperature: Creativity level
+            max_tokens: Maximum tokens
+
+        Yields:
+            Text tokens as they are generated
+        """
+        ...
+        # TODO: Each provider implements streaming differently
+        pass
+
+    @abstractmethod
+    async def embed(
+        self,
+        texts: List[str],
+        model: Optional[str] = None,
+    ) -> List[List[float]]:
+        """
+        Generate embeddings for a list of texts.
+
+        Used ONLY for semantic fallback search — not the primary retrieval path.
+        Primary retrieval uses ExactHash (96% accurate, no embeddings needed).
+
+        Args:
+            texts: List of texts to embed
+            model: Optional model override
+
+        Returns:
+            List of embedding vectors
+        """
+        ...
+        pass
+
+    @abstractmethod
+    def get_model_name(self) -> str:
+        """
+        Return the currently active model name.
+
+        Used for logging, cost tracking, and UI display.
+        """
+        ...
+        pass
+
+    @abstractmethod
+    def get_token_count(self, text: str) -> int:
+        """
+        Estimate token count for a text string.
+
+        Used for:
+          - Budget tracking (cost estimation before API call)
+          - Context window management (don't exceed model limits)
+          - Prompt optimization (trim if needed)
+
+        Args:
+            text: The text to count tokens for
+
+        Returns:
+            Estimated token count
+        """
+        ...
+        pass

package/vendors/precis/backend/llm/deepseek_provider.py

@@ -0,0 +1,43 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+from typing import AsyncGenerator, List, Optional
+from openai import AsyncOpenAI
+from backend.llm.base import LLMProvider
+
+
+class DeepSeekProvider(LLMProvider):
+    def __init__(self, api_key: str, model: str = "deepseek-chat",
+                 base_url: str = "https://api.deepseek.com") -> None:
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._model = model
+
+    async def generate(self, prompt: str, system_prompt: Optional[str] = None,
+                       temperature: float = 0.7, max_tokens: int = 4096, **kwargs) -> str:
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        resp = await self._client.chat.completions.create(
+            model=self._model, messages=messages, temperature=temperature,
+            max_tokens=max_tokens, timeout=30, **kwargs)
+        return resp.choices[0].message.content or ""
+
+    async def generate_stream(self, prompt: str, system_prompt: Optional[str] = None,
+                              temperature: float = 0.7, max_tokens: int = 4096, **kwargs) -> AsyncGenerator[str, None]:
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+        stream = await self._client.chat.completions.create(
+            model=self._model, messages=messages, temperature=temperature,
+            max_tokens=max_tokens, stream=True, **kwargs)
+        async for chunk in stream:
+            if chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+    async def embed(self, texts: List[str], model: Optional[str] = None) -> List[List[float]]:
+        raise NotImplementedError("DeepSeek embeddings — check platform.deepseek.com for availability")
+
+    def get_model_name(self) -> str: return self._model
+
+    def get_token_count(self, text: str) -> int: return len(text) // 4