mcp-agentic-pipelines 1.0.1

package/vendors/piste/pipeline/stage4/verdict_aggregator.py

@@ -0,0 +1,157 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+"""
+Stage 4b: Verdict Aggregator [J5]
+====================================
+DSPy-powered synthesis of per-source classifications into a
+7-way PolitiFact-aligned verdict.
+
+Jewel [J5] — DSPy typed Signatures with auto-optimization:
+  - Weighted by source credibility scores
+  - Generates natural language explanation with citations
+  - Returns probability distribution over all 7 verdict labels
+  - Model-agnostic (swap LLMs without changing code)
+
+Verdict labels:
+  TRUE, MOSTLY_TRUE, HALF_TRUE, MOSTLY_FALSE, FALSE, PANTS_ON_FIRE, UNVERIFIABLE
+"""
+
+import json
+import dspy
+from typing import Tuple, Dict
+from pipeline.signatures.signatures import VerdictAggregationSignature
+from pipeline.stage3.orchestrator import ClassificationResult
+
+# 7-way PolitiFact-aligned verdict labels
+VERDICT_LABELS = [
+    "TRUE",
+    "MOSTLY_TRUE",
+    "HALF_TRUE",
+    "MOSTLY_FALSE",
+    "FALSE",
+    "PANTS_ON_FIRE",
+    "UNVERIFIABLE",
+]
+
+
+class VerdictAggregator(dspy.Module):
+    """
+    DSPy module that synthesizes per-source classifications into a
+    final 7-way verdict with explanation and probability distribution.
+
+    Jewel [J5] — DSPy Compiler + Framework:
+    Typed Signatures, model-agnostic, compiler-optimizable.
+    Loop 3: re-optimized with user feedback labels.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.aggregate = dspy.ChainOfThought(VerdictAggregationSignature)
+
+    def forward(
+        self,
+        claim: str,
+        classifications: list[ClassificationResult],
+        locale: str = "en",
+    ) -> Tuple[str, float, str, Dict[str, float]]:
+        """
+        Aggregate per-source classifications into final verdict.
+
+        Args:
+            claim: The atomic claim being verified.
+            classifications: Per-source classification results from Stage 3.
+            locale: Language locale for the response (en, fr).
+
+        Returns:
+            verdict: One of the 7 verdict labels
+            confidence: 0.0–1.0 overall confidence
+            explanation: Natural language explanation with citations
+            distribution: Probability weight for each verdict label
+        """
+        # Build weighted classification summary
+        classifications_json = self._build_classifications_payload(
+            claim, classifications
+        )
+
+        result = self.aggregate(
+            claim=claim,
+            classifications_json=classifications_json,
+            locale=locale,
+        )
+
+        # Normalize verdict
+        verdict = result.verdict.strip().upper()
+        verdict = self._normalize_verdict(verdict)
+
+        # Parse distribution
+        try:
+            distribution = json.loads(result.distribution_json)
+        except (json.JSONDecodeError, TypeError):
+            distribution = self._default_distribution(verdict)
+
+        # Ensure all labels are present
+        for label in VERDICT_LABELS:
+            if label not in distribution:
+                distribution[label] = 0.0
+
+        return (
+            verdict,
+            float(result.confidence),
+            result.explanation,
+            distribution,
+        )
+
+    def _build_classifications_payload(
+        self,
+        claim: str,
+        classifications: list[ClassificationResult],
+    ) -> str:
+        """Build JSON payload summarizing per-source classifications."""
+        summary = []
+        for i, c in enumerate(classifications):
+            summary.append({
+                "source_index": i,
+                "source_domain": c.source_domain,
+                "credibility_score": c.credibility_score,
+                "label": c.label,
+                "confidence": c.confidence,
+                "rationale": c.rationale,
+            })
+        return json.dumps(summary, indent=2)
+
+    def _normalize_verdict(self, raw: str) -> str:
+        """Normalize LLM output to a valid verdict label."""
+        raw_upper = raw.upper().strip()
+
+        # Direct match
+        if raw_upper in VERDICT_LABELS:
+            return raw_upper
+
+        # Fuzzy match
+        mapping = {
+            "TRUE": "TRUE",
+            "MOSTLY TRUE": "MOSTLY_TRUE",
+            "MOSTLYTRUE": "MOSTLY_TRUE",
+            "HALF TRUE": "HALF_TRUE",
+            "HALFTRUE": "HALF_TRUE",
+            "MOSTLY FALSE": "MOSTLY_FALSE",
+            "MOSTLYFALSE": "MOSTLY_FALSE",
+            "FALSE": "FALSE",
+            "PANTS ON FIRE": "PANTS_ON_FIRE",
+            "PANTSONFIRE": "PANTS_ON_FIRE",
+            "UNVERIFIABLE": "UNVERIFIABLE",
+            "NOT ENOUGH INFORMATION": "UNVERIFIABLE",
+            "NEI": "UNVERIFIABLE",
+        }
+        return mapping.get(raw_upper, "UNVERIFIABLE")
+
+    def _default_distribution(self, verdict: str) -> Dict[str, float]:
+        """Create a default distribution centered on the given verdict."""
+        dist = {label: 0.0 for label in VERDICT_LABELS}
+        dist[verdict] = 1.0
+        return dist
+
+
+# Singleton
+verdict_aggregator = VerdictAggregator()

package/vendors/piste/requirements.txt

@@ -0,0 +1,53 @@
+# ============================================================
+# Piste — Backend Dependencies
+# FastAPI 0.115 + DSPy 2.6 + LiteLLM + PostgreSQL + Redis
+# ============================================================
+
+# --- Web Framework ---
+fastapi==0.115.6
+uvicorn[standard]==0.34.0
+sse-starlette==2.2.1
+
+# --- Validation ---
+pydantic==2.10.5
+pydantic-settings==2.7.1
+
+# --- Database ---
+sqlalchemy[asyncio]==2.0.36
+asyncpg==0.30.0
+alembic==1.14.1
+psycopg2-binary==2.9.10
+
+# --- Cache ---
+redis==5.2.1
+hiredis==3.0.0
+
+# --- AI / ML Pipeline ---
+dspy-ai
+litellm
+faiss-cpu
+numpy
+
+# --- HTTP / SSE / Web ---
+httpx
+aiohttp
+
+# --- Observability ---
+prometheus-client==0.21.1
+opentelemetry-api==1.29.0
+opentelemetry-sdk==1.29.0
+opentelemetry-instrumentation-fastapi==0.50b0
+
+# --- Utilities ---
+python-dotenv==1.0.1
+python-multipart==0.0.19
+tenacity==9.0.0
+orjson==3.10.13
+
+# --- Auth ---
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+
+# --- Testing ---
+pytest==8.3.4
+pytest-asyncio==0.25.0

package/vendors/precis/backend/__init__.py

@@ -0,0 +1,6 @@
+# =============================================================================
+# © JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT
+# =============================================================================
+# Package initialization. Import key classes here for convenient access:
+#   from backend import PrecisOrchestrator, ExactHashRetriever, ...
+# =============================================================================

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

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

package/vendors/precis/backend/agents/data_synthesis.py

@@ -0,0 +1,105 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+from typing import Any, Dict, List, Optional
+
+from backend.orchestrator.types import AgentResult
+from backend.llm.base import LLMProvider
+
+
+class DataSynthesisAgent:
+    """Combines results from upstream agents into a coherent synthesis using LLM reasoning.
+
+    The *llm* parameter on __init__ serves as a default; individual calls to
+    synthesize() may override it.  If no provider is available at call time
+    the agent falls back to returning raw fragments — this is intentional so
+    the pipeline never breaks, but a warning is logged.
+    """
+
+    def __init__(self, llm: Optional[LLMProvider] = None) -> None:
+        self.llm = llm
+
+    async def synthesize(
+        self,
+        query: str,
+        upstream_results: List[AgentResult],
+        llm: Optional[LLMProvider] = None,
+    ) -> AgentResult:
+        """Synthesize results from multiple upstream agents into a single answer.
+
+        Parameters
+        ----------
+        query : str
+            The original user query.
+        upstream_results : List[AgentResult]
+            Results from upstream retrieval / analysis agents.
+        llm : Optional[LLMProvider]
+            Per-call override for the LLM provider.  Falls back to self.llm.
+        """
+        provider = llm or self.llm
+
+        # ── Collect text fragments from upstream results ─────────
+        fragments: List[str] = []
+        for r in upstream_results:
+            if not r.success or not r.data:
+                continue
+            if isinstance(r.data, dict):
+                for item in r.data.get("results", []):
+                    if isinstance(item, dict):
+                        text = item.get("text", "")
+                        if isinstance(text, (list, tuple)):
+                            fragments.append(" ".join(str(t) for t in text))
+                        elif text:
+                            fragments.append(str(text))
+                # Also capture any pre-existing synthesis
+                synth = r.data.get("synthesis", "")
+                if synth:
+                    fragments.append(str(synth))
+            elif isinstance(r.data, str):
+                fragments.append(r.data)
+
+        combined_context = "\n".join(fragments[:50]) if fragments else "(no data retrieved)"
+
+        # ── LLM synthesis (or graceful fallback) ─────────────────
+        if provider and fragments:
+            prompt = (
+                "You are a precise data synthesis agent. Synthesize the following retrieved\n"
+                "information into a concise answer to the user's query.\n\n"
+                f"USER QUERY: {query}\n\n"
+                f"RETRIEVED DATA:\n{combined_context}\n\n"
+                "SYNTHESIS: Answer the query using ONLY the retrieved data above. "
+                "If the data is insufficient, state what's missing. "
+                "Be specific with numbers, percentages, and entity names found in the data."
+            )
+            try:
+                import asyncio
+                response = await asyncio.wait_for(
+                    provider.generate(prompt, max_tokens=250),
+                    timeout=30,
+                )
+                synthesis_text = response
+            except asyncio.TimeoutError:
+                synthesis_text = (
+                    f"(LLM synthesis timed out. Retrieved {len(fragments)} fragments.)\n"
+                    f"{combined_context[:500]}"
+                )
+            except Exception as e:
+                synthesis_text = (
+                    f"(LLM synthesis error: {e})\n{combined_context[:500]}"
+                )
+        elif fragments:
+            synthesis_text = (
+                f"Retrieved {len(fragments)} fragments:\n{combined_context[:1000]}"
+            )
+        else:
+            synthesis_text = "(No data retrieved — unable to synthesize a response.)"
+
+        return AgentResult(
+            subtask_id="synthesis",
+            agent_name="DataSynthesis",
+            success=True,
+            data={
+                "synthesis": synthesis_text,
+                "source_fragments": len(fragments),
+            },
+            citations=[],
+        )

package/vendors/precis/backend/agents/dist_free_synth.py

@@ -0,0 +1,97 @@
+"""© JINAN KORDAB — 2026 AI HYBRID AGENTIC RETRIEVAL-AUGMENTED GENERATION RAG PIPELINE - PERSONAL PROJECT"""
+
+import numpy as np
+import pandas as pd
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class SyntheticDataset:
+    dataframe: pd.DataFrame
+    n_rows: int
+    n_features: int
+    generation_mode: str
+    correlation_preserved: bool
+    hellinger_distance: float
+    metadata: Dict = field(default_factory=dict)
+
+
+class DistFreeSynth:
+    """Bin-based distribution-free synthesizer. Outperforms GANs on tabular data."""
+
+    def __init__(self, bins_per_feature: Optional[List[int]] = None) -> None:
+        self.bins_per_feature = bins_per_feature
+        self.pc_table: List[np.ndarray] = []
+        self.bin_counts: Dict[str, int] = {}
+        self.bin_obs: Dict[str, List[np.ndarray]] = {}
+        self.features: List[str] = []
+        self.n_features: int = 0
+        self.n_original: int = 0
+
+    def fit(self, df: pd.DataFrame, bins_per_feature: Optional[List[int]] = None) -> None:
+        self.features = list(df.columns)
+        self.n_features = len(self.features)
+        self.n_original = len(df)
+        if bins_per_feature is None:
+            n = max(len(df), 1)
+            bins_per_feature = [max(5, int(np.sqrt(n))) for _ in range(self.n_features)]
+        self.bins_per_feature = bins_per_feature
+        npdata = df.to_numpy()
+        self.pc_table = []
+        for k in range(self.n_features):
+            incr = 1.0 / bins_per_feature[k]
+            pc = np.arange(0, 1 + incr / 2, incr)
+            arr = np.quantile(npdata[:, k], np.clip(pc, 0, 1))
+            self.pc_table.append(arr)
+        self.bin_counts, self.bin_obs = {}, {}
+        for obs in npdata:
+            key = []
+            for k in range(self.n_features):
+                idx = int(np.searchsorted(self.pc_table[k], obs[k], side="right")) - 1
+                idx = max(0, min(idx, bins_per_feature[k] - 1))
+                key.append(idx)
+            skey = str(key)
+            self.bin_counts[skey] = self.bin_counts.get(skey, 0) + 1
+            self.bin_obs.setdefault(skey, []).append(obs)
+
+    def generate(self, n_synth: int, mode: str = "random_counts",
+                 correlation_preserve: bool = True, seed: Optional[int] = None) -> SyntheticDataset:
+        if seed is not None:
+            np.random.seed(seed)
+        bin_keys = list(self.bin_counts.keys())
+        if mode == "random_counts":
+            probs = np.array([self.bin_counts[k] for k in bin_keys], dtype=float)
+            probs /= probs.sum()
+            sampled = np.random.choice(len(bin_keys), size=n_synth, p=probs)
+            key_counts: Dict[str, int] = {k: 0 for k in bin_keys}
+            for idx in sampled:
+                key_counts[bin_keys[idx]] += 1
+        else:
+            key_counts = dict(self.bin_counts)
+        synth_data = []
+        for skey, count in key_counts.items():
+            if count <= 0:
+                continue
+            key = eval(skey)
+            L = [self.pc_table[k][key[k]] for k in range(self.n_features)]
+            U = [self.pc_table[k][key[k] + 1] for k in range(self.n_features)]
+            for _ in range(count):
+                obs = np.array([np.random.uniform(L[k], U[k]) for k in range(self.n_features)])
+                synth_data.append(obs)
+        result = pd.DataFrame(synth_data, columns=self.features)
+        hd = self._compute_hellinger(self.bin_counts, key_counts)
+        return SyntheticDataset(dataframe=result, n_rows=len(result), n_features=self.n_features,
+                                generation_mode=mode, correlation_preserved=correlation_preserve,
+                                hellinger_distance=hd)
+
+    def _compute_hellinger(self, real: Dict[str, int], synth: Dict[str, int]) -> float:
+        all_keys = set(real) | set(synth)
+        r_total = max(1, sum(real.values()))
+        s_total = max(1, sum(synth.values()))
+        sum_sq = 0.0
+        for k in all_keys:
+            p = real.get(k, 0) / r_total
+            q = synth.get(k, 0) / s_total
+            sum_sq += (np.sqrt(p) - np.sqrt(q)) ** 2
+        return float(np.sqrt(0.5 * sum_sq))