mcp-agentic-pipelines 1.0.1

package/vendors/piste/pipeline/stage1/atomic_decomposer.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+"""
+Stage 1b: Atomic Claim Decomposer [J7]
+========================================
+FACT5's jewel: decompose compound claims into independent atomic claims.
+Each atomic claim focuses on ONE verifiable fact.
+
+Example:
+  "We created 800,000 jobs and cut taxes by 20%"
+  → ["We created 800,000 jobs.", "We cut taxes by 20%."]
+"""
+
+import dspy
+from typing import List
+from pipeline.signatures.signatures import AtomicClaimDecompositionSignature
+
+
+class AtomicClaimDecomposer(dspy.Module):
+    """
+    DSPy module that splits compound claims into atomic, independently
+    verifiable claims.
+
+    Jewel [J7] — FACT5's atomization:
+    A holistic verdict on a compound claim is meaningless — some parts
+    may be true, others false. Atomize first, then verify each sub-claim
+    independently.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.decompose = dspy.ChainOfThought(AtomicClaimDecompositionSignature)
+
+    def forward(self, claim_text: str) -> List[str]:
+        """
+        Decompose a claim into atomic sub-claims.
+
+        Returns:
+            List of independent atomic claims, each a single verifiable fact.
+            If the claim is already atomic, returns a single-element list.
+        """
+        result = self.decompose(claim_text=claim_text)
+
+        # Post-process: ensure each atomic claim is a complete sentence
+        atomic_claims = []
+        for claim in result.atomic_claims:
+            claim = claim.strip()
+            if claim and not claim.endswith((".", "!", "?")):
+                claim += "."
+            atomic_claims.append(claim)
+
+        # If decomposition returned nothing useful, treat original as atomic
+        if not atomic_claims:
+            atomic_claims = [claim_text.strip()]
+
+        return atomic_claims
+
+
+# Singleton instance
+atomic_claim_decomposer = AtomicClaimDecomposer()

package/vendors/piste/pipeline/stage1/check_worthiness.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+"""
+Stage 1a: Check-Worthiness Detector [J4]
+==========================================
+ClaimBuster's jewel: classify whether a claim is worth fact-checking.
+Uses DSPy ChainOfThought with voting (3 completions, majority wins).
+If agreement < threshold → safe default (UFC).
+
+Verdict: CFC (Check-worthy Factual Claim), UFC (Unimportant Factual Claim),
+         or NFC (Non-Factual Claim).
+"""
+
+import dspy
+from typing import Literal, Tuple
+from pipeline.signatures.signatures import CheckWorthinessSignature
+from app.core.config import settings
+
+
+class CheckWorthinessDetector(dspy.Module):
+    """
+    DSPy module that classifies whether a claim is worth fact-checking.
+
+    Jewel [J4] — ClaimBuster's pre-filter:
+    In the real world, claims are embedded in a firehose of text.
+    You must find the needles (check-worthy claims) before examining them.
+
+    Voting mechanism: 3 independent LLM completions, majority wins.
+    If no majority meets the threshold → default to UFC (safe).
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.classify = dspy.ChainOfThought(CheckWorthinessSignature)
+        self.voting_completions: int = settings.VOTING_COMPLETIONS
+        self.voting_threshold: float = settings.VOTING_THRESHOLD
+
+    def forward(
+        self, claim_text: str, locale: str = "en"
+    ) -> Tuple[str, float, str, list[str]]:
+        """
+        Classify claim check-worthiness with majority voting.
+
+        Returns:
+            label: "CFC", "UFC", or "NFC"
+            confidence: 0.0–1.0
+            rationale: Explanation of the classification
+            votes: Raw individual votes for audit trail [C5]
+        """
+        votes: list[str] = []
+        confidences: list[float] = []
+
+        # Run N independent completions
+        for _ in range(self.voting_completions):
+            result = self.classify(claim_text=claim_text, locale=locale)
+            votes.append(result.label.strip().upper())
+            confidences.append(float(result.confidence))
+
+        # Majority vote
+        final_label = self._resolve_vote(votes, confidences)
+        avg_confidence = sum(confidences) / len(confidences)
+
+        # Get rationale from the majority-vote completion
+        rationale = self._get_rationale(claim_text, final_label)
+
+        return final_label, avg_confidence, rationale, votes
+
+    def _resolve_vote(
+        self, votes: list[str], confidences: list[float]
+    ) -> str:
+        """Determine final label via majority vote with configurable threshold."""
+        from collections import Counter
+
+        counts = Counter(votes)
+        most_common_label, most_common_count = counts.most_common(1)[0]
+        agreement_ratio = most_common_count / len(votes)
+
+        if agreement_ratio >= self.voting_threshold:
+            return most_common_label
+        else:
+            # No majority met → safe default
+            # If any vote was CFC, be conservative and still check it
+            if "CFC" in votes:
+                return "CFC"
+            return "UFC"
+
+    def _get_rationale(self, claim_text: str, label: str) -> str:
+        """Generate a concise rationale for the final classification."""
+        rationale_map = {
+            "CFC": "This claim contains a verifiable factual assertion that warrants evidence-based checking.",
+            "UFC": "This claim is factual but trivial or not of public interest — fact-checking resources are better allocated elsewhere.",
+            "NFC": "This is an opinion, question, or non-factual statement — there is no verifiable claim to check.",
+        }
+        # Optionally, re-query LLM for a more specific rationale
+        return rationale_map.get(label, "Classification complete.")
+
+
+# Singleton instance
+check_worthiness_detector = CheckWorthinessDetector()

package/vendors/piste/pipeline/stage1/orchestrator.py

@@ -0,0 +1,175 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+"""
+Stage 1 Orchestrator
+=====================
+Coordinates Stage 1a (Check-Worthiness) and Stage 1b (Atomic Decomposition).
+Writes APPEND-ONLY stage records to PostgreSQL audit ledger [C5].
+Emits SSE events for real-time frontend updates.
+"""
+
+import time
+import uuid
+from typing import Optional
+from dataclasses import dataclass, field
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from app.db.models import StageRecord
+from pipeline.stage1.check_worthiness import check_worthiness_detector
+from pipeline.stage1.atomic_decomposer import atomic_claim_decomposer
+
+
+@dataclass
+class Stage1Result:
+    """Output of Stage 1 — Claim Processing."""
+    claim_text: str
+    locale: str
+
+    # Stage 1a: Check-Worthiness
+    worthiness_label: str  # CFC, UFC, NFC
+    worthiness_confidence: float
+    worthiness_rationale: str
+    worthiness_votes: list[str]
+
+    # Stage 1b: Atomic Decomposition
+    atomic_claims: list[str]
+
+    # If not check-worthy, pipeline stops here
+    is_check_worthy: bool
+    stop_reason: str = ""
+
+
+class Stage1Orchestrator:
+    """
+    Orchestrates Stage 1 of the fact-checking pipeline.
+
+    Flow:
+      1. Run CheckWorthinessDetector (1a) with voting
+      2. If CFC → run AtomicClaimDecomposer (1b)
+      3. If UFC or NFC → stop pipeline, return early verdict
+      4. Write stage records to PostgreSQL (append-only)
+      5. Emit SSE events via callback
+    """
+
+    def __init__(self, sse_callback: Optional[callable] = None):
+        """
+        Args:
+            sse_callback: async function(event_type, data) to emit SSE events.
+        """
+        self.sse_callback = sse_callback
+
+    async def process(
+        self,
+        claim_text: str,
+        locale: str = "en",
+        db: Optional[AsyncSession] = None,
+        run_id: Optional[uuid.UUID] = None,
+        context: str = "",
+    ) -> Stage1Result:
+        """
+        Run Stage 1 processing.
+
+        Args:
+            claim_text: The raw claim text submitted by the user.
+            locale: Language locale (en, fr, es, ...).
+            db: Async database session for audit ledger writes.
+            context: Optional additional context to aid the LLM.
+
+        Returns:
+            Stage1Result with worthiness classification and atomic claims.
+        """
+        # Merge context into claim text if provided
+        effective_claim = f"Context: {context}\n\nClaim: {claim_text}" if context and context.strip() else claim_text
+
+        # --- Stage 1a: Check-Worthiness Detection ---
+        await self._emit("stage_1a_start", {"claim_text": claim_text, "locale": locale, "context": context})
+        t0 = time.monotonic()
+
+        label, confidence, rationale, votes = check_worthiness_detector(
+            effective_claim, locale
+        )
+
+        latency_1a = (time.monotonic() - t0) * 1000
+
+        await self._emit("stage_1a_complete", {
+            "label": label,
+            "confidence": confidence,
+            "votes": votes,
+        })
+
+        # Write stage record (append-only)
+        if db:
+            db.add(StageRecord(
+                run_id=run_id or uuid.UUID("00000000-0000-0000-0000-000000000000"),
+                stage_name="stage_1a",
+                input_snapshot={"claim_text": claim_text, "locale": locale, "context": context or None},
+                output_snapshot={
+                    "label": label,
+                    "confidence": confidence,
+                    "rationale": rationale,
+                    "votes": votes,
+                },
+                model_used="dspy/check_worthiness",
+                latency_ms=latency_1a,
+                retry_attempt=0,
+            ))
+
+        # Stop if not check-worthy
+        if label != "CFC":
+            return Stage1Result(
+                claim_text=claim_text,
+                locale=locale,
+                worthiness_label=label,
+                worthiness_confidence=confidence,
+                worthiness_rationale=rationale,
+                worthiness_votes=votes,
+                atomic_claims=[],
+                is_check_worthy=False,
+                stop_reason=f"Claim classified as {label}: {rationale}",
+            )
+
+        # --- Stage 1b: Atomic Claim Decomposition ---
+        await self._emit("stage_1b_start", {"claim_text": claim_text})
+        t0 = time.monotonic()
+
+        atomic_claims = atomic_claim_decomposer(claim_text)
+
+        latency_1b = (time.monotonic() - t0) * 1000
+
+        await self._emit("stage_1b_complete", {
+            "atomic_claims": atomic_claims,
+            "count": len(atomic_claims),
+        })
+
+        # Write stage record (append-only)
+        if db:
+            db.add(StageRecord(
+                run_id=run_id or uuid.UUID("00000000-0000-0000-0000-000000000000"),
+                stage_name="stage_1b",
+                input_snapshot={"claim_text": claim_text},
+                output_snapshot={"atomic_claims": atomic_claims},
+                model_used="dspy/atomic_decomposer",
+                latency_ms=latency_1b,
+                retry_attempt=0,
+            ))
+
+        return Stage1Result(
+            claim_text=claim_text,
+            locale=locale,
+            worthiness_label=label,
+            worthiness_confidence=confidence,
+            worthiness_rationale=rationale,
+            worthiness_votes=votes,
+            atomic_claims=atomic_claims,
+            is_check_worthy=True,
+        )
+
+    async def _emit(self, event_type: str, data: dict):
+        """Emit SSE event via callback if configured."""
+        if self.sse_callback:
+            await self.sse_callback(event_type, data)
+
+
+# Singleton
+stage1_orchestrator = Stage1Orchestrator()

package/vendors/piste/pipeline/stage1/test_stage1.py

@@ -0,0 +1,162 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+"""
+Unit Tests — Stage 1: Claim Processing
+=======================================
+Tests CheckWorthinessDetector [J4] and AtomicClaimDecomposer [J7]
+with mock DSPy LLM responses.
+
+Run: pytest pipeline/stage1/test_stage1.py -v
+"""
+
+import pytest
+from unittest.mock import patch, MagicMock
+
+
+# ============================================================
+# Check-Worthiness Detector Tests
+# ============================================================
+
+class TestCheckWorthinessDetector:
+    """Test CheckWorthinessDetector [J4] with voting mechanism."""
+
+    @pytest.fixture
+    def detector(self):
+        from pipeline.stage1.check_worthiness import CheckWorthinessDetector
+        return CheckWorthinessDetector()
+
+    def test_majority_vote_cfc(self, detector):
+        """When all 3 votes are CFC, return CFC."""
+        votes = ["CFC", "CFC", "CFC"]
+        confidences = [0.9, 0.85, 0.88]
+        result = detector._resolve_vote(votes, confidences)
+        assert result == "CFC"
+
+    def test_majority_vote_ufc(self, detector):
+        """When 2/3 votes are UFC, return UFC (meets 0.67 threshold)."""
+        votes = ["UFC", "UFC", "NFC"]
+        confidences = [0.7, 0.8, 0.6]
+        result = detector._resolve_vote(votes, confidences)
+        assert result == "UFC"
+
+    def test_no_majority_falls_back_to_cfc(self, detector):
+        """When no majority met but CFC present, be conservative and check it."""
+        votes = ["CFC", "UFC", "NFC"]
+        confidences = [0.6, 0.5, 0.4]
+        # Agreement is 1/3 = 0.33 < 0.67 threshold
+        result = detector._resolve_vote(votes, confidences)
+        assert result == "CFC"  # Conservative: better to check than miss
+
+    def test_no_majority_no_cfc_falls_back_to_ufc(self, detector):
+        """When no majority and no CFC, default to UFC."""
+        votes = ["UFC", "NFC", "NFC"]
+        confidences = [0.5, 0.6, 0.5]
+        result = detector._resolve_vote(votes, confidences)
+        assert result == "UFC"
+
+    def test_rationale_for_known_label(self, detector):
+        """Rationale should be a non-empty string for all labels."""
+        for label in ["CFC", "UFC", "NFC"]:
+            rationale = detector._get_rationale("test claim", label)
+            assert isinstance(rationale, str)
+            assert len(rationale) > 0
+
+
+# ============================================================
+# Atomic Claim Decomposer Tests
+# ============================================================
+
+class TestAtomicClaimDecomposer:
+    """Test AtomicClaimDecomposer [J7]."""
+
+    @pytest.fixture
+    def decomposer(self):
+        from pipeline.stage1.atomic_decomposer import AtomicClaimDecomposer
+        return AtomicClaimDecomposer()
+
+    def test_post_process_adds_period(self, decomposer):
+        """Claims without ending punctuation get a period appended."""
+        # We test the post-processing logic directly via the forward method
+        # with a mock that returns claims without periods
+        pass  # Requires mock DSPy — see integration tests
+
+    def test_empty_result_falls_back_to_original(self, decomposer):
+        """If DSPy returns no atomic claims, use the original text."""
+        # Test the post-processing guard
+        pass  # Requires mock DSPy
+
+
+# ============================================================
+# Stage1Result Tests
+# ============================================================
+
+class TestStage1Result:
+    """Test the Stage1Result dataclass."""
+
+    def test_check_worthy_claim(self):
+        from pipeline.stage1.orchestrator import Stage1Result
+        result = Stage1Result(
+            claim_text="Water boils at 100°C.",
+            locale="en",
+            worthiness_label="CFC",
+            worthiness_confidence=0.95,
+            worthiness_rationale="Verifiable scientific claim.",
+            worthiness_votes=["CFC", "CFC", "CFC"],
+            atomic_claims=["Water boils at 100°C."],
+            is_check_worthy=True,
+        )
+        assert result.is_check_worthy is True
+        assert len(result.atomic_claims) == 1
+
+    def test_non_check_worthy_claim_stops_pipeline(self):
+        from pipeline.stage1.orchestrator import Stage1Result
+        result = Stage1Result(
+            claim_text="Nice weather today!",
+            locale="en",
+            worthiness_label="NFC",
+            worthiness_confidence=0.92,
+            worthiness_rationale="This is an opinion, not a factual claim.",
+            worthiness_votes=["NFC", "NFC", "NFC"],
+            atomic_claims=[],
+            is_check_worthy=False,
+            stop_reason="Claim classified as NFC: This is an opinion.",
+        )
+        assert result.is_check_worthy is False
+        assert result.atomic_claims == []
+        assert "NFC" in result.stop_reason
+
+
+# ============================================================
+# Integration-style Test (no LLM calls)
+# ============================================================
+
+def test_stage1_result_roundtrip():
+    """Stage1Result can be serialized/deserialized for JSONB storage."""
+    import json
+    from pipeline.stage1.orchestrator import Stage1Result
+
+    result = Stage1Result(
+        claim_text="Test claim.",
+        locale="en",
+        worthiness_label="CFC",
+        worthiness_confidence=0.88,
+        worthiness_rationale="Check-worthy.",
+        worthiness_votes=["CFC", "CFC", "UFC"],
+        atomic_claims=["Test claim."],
+        is_check_worthy=True,
+    )
+
+    # Should be JSON-serializable for stage_records JSONB columns
+    data = {
+        "label": result.worthiness_label,
+        "confidence": result.worthiness_confidence,
+        "rationale": result.worthiness_rationale,
+        "votes": result.worthiness_votes,
+        "atomic_claims": result.atomic_claims,
+    }
+    json_str = json.dumps(data)
+    parsed = json.loads(json_str)
+    assert parsed["label"] == "CFC"
+    assert parsed["votes"] == ["CFC", "CFC", "UFC"]
+    assert parsed["atomic_claims"] == ["Test claim."]

package/vendors/piste/pipeline/stage2/__init__.py

@@ -0,0 +1,34 @@
+# Copyright (c) 2026 Jinan Kordab
+# SPDX-License-Identifier: MIT
+
+# Stage 2 — Blind Retrieval [J2]
+#   2a: Search-Decision Generator [J1]   — pipeline/stage2/search_decision.py
+#   2b: Blind Retriever                  — pipeline/stage2/blind_retriever.py
+#   2c: Per-Domain Credibility Scorer [J1b] — pipeline/stage2/credibility_scorer.py
+#   2d: Intelligent Query Refiner [J8c]  — pipeline/stage2/query_refiner.py (Loop 1)
+#   2e: Canonical Evidence Mapper [C6]   — pipeline/stage2/canonical_mapper.py
+#   Orchestrator: pipeline/stage2/orchestrator.py
+
+from pipeline.stage2.search_decision import SearchDecisionGenerator, search_decision_generator
+from pipeline.stage2.blind_retriever import BlindRetriever, blind_retriever, RawSearchResult
+from pipeline.stage2.credibility_scorer import CredibilityScorer
+from pipeline.stage2.query_refiner import QueryRefiner
+from pipeline.stage2.canonical_mapper import (
+    CanonicalEvidenceMapper, CanonicalEvidence,
+)
+from pipeline.stage2.orchestrator import Stage2Orchestrator, Stage2Result, stage2_orchestrator
+
+__all__ = [
+    "SearchDecisionGenerator",
+    "search_decision_generator",
+    "BlindRetriever",
+    "blind_retriever",
+    "RawSearchResult",
+    "CredibilityScorer",
+    "QueryRefiner",
+    "CanonicalEvidenceMapper",
+    "CanonicalEvidence",
+    "Stage2Orchestrator",
+    "Stage2Result",
+    "stage2_orchestrator",
+]