Upload 17 files

cleaned and removed wikidata

agents/claim_extractor.py

@@ -1,28 +1,3 @@
-"""
-Agent 1 — Claim Extractor (LLM Version)
-Arabic News Analyzer · Graduation Project
-
-Extracts atomic, verifiable factual claims from Arabic news text.
-Uses Groq (llama-3.3-70b-versatile) — same stack as Agents 3 & 4.
-
-Why LLM over NER/POS:
-  - Arabic morphology defeats rule-based POS pipelines on news text
-  - LLMs understand discourse boundaries → true atomic claim splitting
-  - Numerical/relational claims ("300 injuries", "first flight") are
-    invisible to NER but trivial for an LLM
-  - Produces fully self-contained claims — no [سياق:] workarounds needed
-  - No external Gradio Space dependency
-
-Output per claim:
-  A complete, standalone Arabic sentence with the subject always explicit.
-  e.g. "أعلنت إدارة نادي ريال مدريد أن التقديم الرسمي لمبابي سيكون في برنابيو"
-  NOT: "وأضافت أن التقديم الرسمي سيكون في برنابيو"
-
-Required setup:
-    pip install groq python-dotenv
-    Add to .env: GROQ_API_KEY=gsk_...
-"""
-
 import asyncio
 import json
 import logging
@@ -34,21 +9,17 @@ from dotenv import load_dotenv
 
 load_dotenv()
 
-# ── Logging ───────────────────────────────────────────────────────────────────
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
 )
 logger = logging.getLogger(__name__)
 
-# ── Config ────────────────────────────────────────────────────────────────────
 GROQ_MODEL = "llama-3.3-70b-versatile"
 MAX_TOKENS = 1024
-# Zero temperature = fully deterministic extraction, no creativity wanted here
 TEMPERATURE = 0.0
 MAX_RETRIES = 2
 
-# ── System prompt ─────────────────────────────────────────────────────────────
 SYSTEM_PROMPT = """أنت نظام متخصص في استخراج الادعاءات الإخبارية القابلة للتحقق من النصوص العربية.
 
 ━━━ تعريف الادعاء القابل للتحقق ━━━
@@ -94,24 +65,6 @@ SYSTEM_PROMPT = """أنت نظام متخصص في استخراج الادعاء
 
 
 class ClaimExtractor:
-    """
-    Agent 1 — Extracts atomic verifiable claims from Arabic news text.
-
-    Every claim is a fully self-contained Arabic sentence with an explicit
-    subject — no pronouns, no implicit references. Safe to pass directly
-    to Agent 2 as a search query without any preprocessing.
-
-    Usage (async):
-        extractor = ClaimExtractor()
-        claims = await extractor.run(text)
-
-    Usage (sync, for standalone testing):
-        claims = asyncio.run(extractor.run(text))
-
-    Output:
-        List of self-contained claim strings, each independently verifiable.
-    """
-
     def __init__(self):
         api_key = os.environ.get("GROQ_API_KEY2")
         if not api_key:
@@ -119,20 +72,10 @@ class ClaimExtractor:
                 "GROQ_API_KEY2 not set — ClaimExtractor will fail at runtime.")
         self.client = AsyncGroq(api_key=api_key)
 
-    # ── Public entry point ────────────────────────────────────────────────────
-
     async def run(self, text: str) -> list[str]:
-        """
-        Main entry point. Takes raw Arabic article text,
-        returns a list of atomic claim strings.
-
-        Retries once on JSON parse failure (same pattern as Verifier).
-        Returns empty list on complete failure — never raises.
-        """
         if not text or not text.strip():
             return []
 
-        # First attempt
         result = await self._call_groq(text)
         if result is not None:
             return result
@@ -148,13 +91,7 @@ class ClaimExtractor:
             "[ClaimExtractor] Both attempts failed — returning empty list.")
         return []
 
-    # ── Groq API call ─────────────────────────────────────────────────────────
-
     async def _call_groq(self, text: str) -> list[str] | None:
-        """
-        Single Groq API call.
-        Returns parsed claims list on success, None on any failure.
-        """
         try:
             response = await self.client.chat.completions.create(
                 model=GROQ_MODEL,
@@ -172,32 +109,17 @@ class ClaimExtractor:
         raw = response.choices[0].message.content or ""
         return self._parse_response(raw)
 
-    # ── Response parsing ─────────────────���────────────────────────────────────
-
     def _parse_response(self, raw: str) -> list[str] | None:
-        """
-        Parse Groq's JSON response into a list of claim strings.
-
-        Handles:
-        - Clean JSON
-        - JSON wrapped in ```json ... ``` markdown fences
-        - JSON embedded in prose
-
-        Returns None if parsing fails completely (triggers retry).
-        """
-        # Strip markdown fences
         clean = re.sub(r"```json\s*", "", raw)
         clean = re.sub(r"```\s*", "", clean)
         clean = clean.strip()
 
-        # Direct parse
         try:
             parsed = json.loads(clean)
             return self._validate_claims(parsed)
         except json.JSONDecodeError:
             pass
 
-        # Extract JSON object from prose
         match = re.search(r"\{.*\}", clean, re.DOTALL)
         if match:
             try:
@@ -210,10 +132,6 @@ class ClaimExtractor:
         return None
 
     def _validate_claims(self, parsed: dict) -> list[str]:
-        """
-        Validate the parsed dict and return a clean claims list.
-        Filters out empty strings or non-string entries.
-        """
         claims = parsed.get("claims", [])
         if not isinstance(claims, list):
             return []

agents/evidence_retriever.py

@@ -1,33 +1,3 @@
-"""
-Agent 2 - Evidence Retriever
-Arabic News Analyzer - Graduation Project
-
-Retrieves evidence for each claim from 3 parallel sources:
-  1. Wikidata     - structured entity facts (free, no key)
-  2. Google FC    - already fact-checked claims (free, needs API key)
-  3. Tavily       - real-time web evidence (free tier, needs API key)
-
-All three run in parallel via asyncio.gather.
-SPARQLWrapper is synchronous - wrapped in run_in_executor to avoid
-blocking the event loop.
-
-Google FC and Tavily can optionally be restricted to a whitelist
-of trusted domains (see config/trusted_sources.py). Wikidata is not
-domain-restricted since it's structured entity data, not open web search.
-
-Input:  self-contained claim string from Agent 1
-        (fully explicit subject — no pronouns, no [سياق:] tags)
-Output: list of evidence dicts, each with {snippet, source_url, source, rating}
-
-Required setup:
-    pip install SPARQLWrapper tavily-python httpx python-dotenv
-    Create .env file in project root with:
-        GOOGLE_FACTCHECK_API_KEY=AIza...
-        TAVILY_API_KEY=tvly-...
-    Get free Google FC key at: https://developers.google.com/fact-check/tools/api
-    Get free Tavily key at: https://tavily.com
-"""
-
 import asyncio
 import sys
 from pathlib import Path
@@ -36,30 +6,11 @@ if __package__ in {None, ""}:
     sys.path.append(str(Path(__file__).resolve().parent.parent))
 
 from config.trusted_sources import TRUSTED_DOMAINS
-from tools.tavily_search import search_tavily
 from tools.google_factcheck import search_google_factcheck
-from tools.wikidata import search_wikidata
+from tools.tavily_search import search_tavily
 
 
 class EvidenceRetriever:
-    """
-    Agent 2 - retrieves evidence for a single claim from 3 sources in parallel.
-
-    Each source returns a list of evidence dicts:
-    {
-        "snippet":    str   - the evidence text
-        "source_url": str   - where it came from
-        "source":     str   - "wikidata" | "google_factcheck" | "tavily"
-        "rating":     str | None  - verdict rating (google_factcheck only)
-    }
-
-    Usage:
-        retriever = EvidenceRetriever()                      # uses default trusted whitelist
-        retriever = EvidenceRetriever(domains=["bbc.com"])    # custom whitelist
-        retriever = EvidenceRetriever(domains=None)           # no restriction, open web
-        evidence = await retriever.run(claim)
-    """
-
     def __init__(self, domains: list[str] | None = TRUSTED_DOMAINS):
         self.domains = domains
 
@@ -71,59 +22,31 @@ class EvidenceRetriever:
         print(f"[DEBUG] Domain whitelist: {self.domains}")
 
         results = await asyncio.gather(
-            self._search_wikidata(claim),
             self._search_google_factcheck(search_query),
             self._search_tavily(search_query),
             return_exceptions=True,
         )
 
         evidence = []
-        source_names = ["wikidata", "google_factcheck", "tavily"]
+        source_names = ["google_factcheck", "tavily"]
         for i, result_set in enumerate(results):
             if isinstance(result_set, Exception):
                 print(
-                    f"[EvidenceRetriever] {source_names[i]} error: {type(result_set).__name__}: {result_set!r}")
+                    f"[EvidenceRetriever] {source_names[i]} error: {type(result_set).__name__}: {result_set!r}"
+                )
                 continue
-            print(
-                f"[DEBUG] {source_names[i]} returned {len(result_set)} results:")
+            print(f"[DEBUG] {source_names[i]} returned {len(result_set)} results:")
             for r in result_set:
-                print(
-                    f"    - {r.get('source_url', '')} | {r.get('snippet', '')[:120]}")
+                print(f"    - {r.get('source_url', '')} | {r.get('snippet', '')[:120]}")
             evidence.extend(result_set)
 
         return evidence
 
     def _build_query(self, claim: str) -> str:
-        """
-        Build search query for Tavily and Google FC.
-        Arabic verification prefix biases results toward fact-check sources.
-        """
         return f"تحقق {claim}"
 
-    async def _search_wikidata(self, claim: str) -> list[dict]:
-        """
-        Searches Wikidata for entities mentioned in the claim.
-        SPARQLWrapper is synchronous -> run in executor.
-        Tries Arabic label first, falls back to English.
-        """
-        return await search_wikidata(claim)
-
     async def _search_google_factcheck(self, query: str) -> list[dict]:
-        """
-        Searches Google Fact Check Tools API for matching fact-checked claims.
-        Returns publisher verdict + review URL as evidence.
-        Requires GOOGLE_FACTCHECK_API_KEY env var.
-        """
         return await search_google_factcheck(query)
 
     async def _search_tavily(self, query: str) -> list[dict]:
-        """
-        Searches Tavily for real-time Arabic web evidence.
-        Runs two queries in parallel:
-          1. fact-check angle  (تحقق + claim + context)
-          2. news angle        (claim + مصدر رسمي)
-        Merges and deduplicates by URL.
-        If self.domains is set, results are restricted to the whitelist
-        (both via Tavily's include_domains and a local post-filter).
-        """
         return await search_tavily(query, domains=self.domains)

agents/explainer.py

@@ -1,34 +1,3 @@
-"""
-Agent 4 — Explainer
-Arabic News Analyzer · Graduation Project
-
-Receives the claim + evidence + verdict from Agent 3.
-Calls Groq API to produce a human-readable Arabic explanation
-with cited sources.
-
-Output schema:
-{
-    "arabic_explanation": "...",   # full Arabic paragraph for the user
-    "verdict":            "...",   # echoed from Agent 3
-    "confidence":         0.0,     # echoed from Agent 3
-    "citations": [
-        {"title": "...", "url": "..."},
-        ...
-    ]
-}
-
-Rules:
-- One Groq call per claim
-- Retry once (with 1s delay) on JSON parse failure
-- Default to a minimal explanation on any error
-- Uses AsyncGroq — non-blocking, compatible with FastAPI + LangGraph async
-- Pydantic models for validated I/O schema
-
-Required setup:
-    pip install groq python-dotenv pydantic
-    Add to .env: GROQ_API_KEY5=gsk_...
-"""
-
 import asyncio
 import json
 import logging
@@ -41,25 +10,22 @@ from pydantic import BaseModel, field_validator
 
 load_dotenv()
 
-# ── Logging ───────────────────────────────────────────────────────────────────
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
 )
 logger = logging.getLogger(__name__)
 
-# ── Config ────────────────────────────────────────────────────────────────────
 GROQ_MODEL = "llama-3.3-70b-versatile"
 MAX_TOKENS = 1024
-TEMPERATURE = 0.1  # slightly higher than Agent 3 — explanation needs fluency
-RETRY_DELAY = 1.0  # seconds to wait before retry (handles rate-limit spikes)
+TEMPERATURE = 0.1
+RETRY_DELAY = 1.0
 
-MAX_EVIDENCE = 6  # cap sources passed to the prompt
-MAX_SNIPPET_LEN = 200  # chars per snippet in prompt
+MAX_EVIDENCE = 6
+MAX_SNIPPET_LEN = 200
 
 VALID_VERDICTS = {"SUPPORTED", "REFUTED", "PARTIALLY_TRUE", "UNVERIFIABLE"}
 
-# ── Verdict Arabic labels ─────────────────────────────────────────────────────
 VERDICT_LABELS = {
     "SUPPORTED": "✓ مدعوم بالأدلة",
     "REFUTED": "✗ مدحوض",
@@ -67,8 +33,6 @@ VERDICT_LABELS = {
     "UNVERIFIABLE": "? لا يمكن التحقق",
 }
 
-# ── Pydantic I/O models ───────────────────────────────────────────────────────
-
 
 class Citation(BaseModel):
     title: str = ""
@@ -77,7 +41,6 @@ class Citation(BaseModel):
     @field_validator("url")
     @classmethod
     def url_must_be_http(cls, v: str) -> str:
-        """Reject anything that does not look like a real URL."""
         if v and not v.startswith("http"):
             return ""
         return v
@@ -103,8 +66,6 @@ class ExplainerOutput(BaseModel):
 
 
 class VerdictInput(BaseModel):
-    """Expected shape of Agent 3's output."""
-
     verdict: str = "UNVERIFIABLE"
     confidence: float = 0.0
     reasoning: str = ""
@@ -116,7 +77,6 @@ class VerdictInput(BaseModel):
         return v if v in VALID_VERDICTS else "UNVERIFIABLE"
 
 
-# ── Default output when everything fails ──────────────────────────────────────
 def _default_explanation(
     claim: str, verdict: str, confidence: float
 ) -> ExplainerOutput:
@@ -133,7 +93,6 @@ def _default_explanation(
     )
 
 
-# ── System prompt ─────────────────────────────────────────────────────────────
 SYSTEM_PROMPT = """أنت محرر صحفي متخصص في تدقيق الأخبار العربية.
 
 مهمتك: كتابة تقرير تحقق موجز وواضح يفهمه القارئ العادي، يشرح نتيجة التحقق من الادعاء وأسبابها.
@@ -174,48 +133,17 @@ SYSTEM_PROMPT = """أنت محرر صحفي متخصص في تدقيق الأخ
 
 
 class Explainer:
-    """
-    Agent 4 — generates a human-readable Arabic explanation of the verdict.
-
-    Usage:
-        explainer = Explainer()
-        result = await explainer.run(claim, evidence, verdict_result)
-
-    Input:
-        claim:          clean claim string (no [سياق:] tag)
-        evidence:       list of evidence dicts from Agent 2
-        verdict_result: dict from Agent 3 {verdict, confidence, reasoning}
-
-    Output:
-        ExplainerOutput Pydantic model (arabic_explanation, verdict, confidence, citations)
-    """
-
     def __init__(self):
         self.client = AsyncGroq(api_key=os.environ.get("GROQ_API_KEY5"))
 
-    # ── Public entry point ──��────────────────────────────────────────────────
-
     async def run(
         self,
         claim: str,
         evidence: list[dict],
         verdict_result: dict,
     ) -> ExplainerOutput:
-        """
-        Main entry point.
-
-        Steps:
-        1. Strip [سياق:] tag if present
-        2. Validate Agent 3 input with Pydantic
-        3. Build prompt from claim + evidence + verdict
-        4. Call Groq API
-        5. Parse + validate JSON response
-        6. Retry once (after 1s delay) on failure
-        7. Return default explanation on second failure
-        """
         claim = self._strip_context_tag(claim)
 
-        # Validate Agent 3's input
         try:
             v_input = VerdictInput(**verdict_result)
         except Exception as e:
@@ -239,12 +167,10 @@ class Explainer:
             claim, evidence, v_input.verdict, v_input.reasoning, v_input.confidence
         )
 
-        # First attempt
         result = await self._call_groq(user_prompt, v_input.confidence)
         if result is not None:
             return result
 
-        # Wait then retry (handles transient rate-limit spikes)
         logger.warning(
             f"[Explainer] JSON parse failed — retrying after {RETRY_DELAY}s for: {claim[:60]}"
         )
@@ -259,7 +185,6 @@ class Explainer:
         )
         return _default_explanation(claim, v_input.verdict, v_input.confidence)
 
-    # ── Prompt construction ──────────────────────────────────────────────────
     def _build_prompt(
         self,
         claim: str,
@@ -279,11 +204,10 @@ class Explainer:
             url = e.get("source_url", "")
             rating = e.get("rating")
 
-            source_label = {
-                "google_factcheck": "تحقق من الحقائق",
-                "wikidata": "ويكيبيانات",
-                "tavily": "بحث ويب",
-            }.get(source, source)
+            source_label = {
+                "google_factcheck": "تحقق من الحقائق",
+                "tavily": "بحث ويب",
+            }.get(source, source)
 
             line = f"[{i}] {source_label}"
             if url and url.startswith("http"):
@@ -307,15 +231,9 @@ class Explainer:
 
     اكتب تقريراً تحققياً موجزاً للقارئ العادي بصيغة JSON."""
 
-    # ── Groq API call ────────────────────────────────────────────────────────
-
     async def _call_groq(
         self, user_prompt: str, confidence: float
     ) -> ExplainerOutput | None:
-        """
-        Single Groq API call.
-        Returns ExplainerOutput on success, None on any failure.
-        """
         try:
             response = await self.client.chat.completions.create(
                 model=GROQ_MODEL,
@@ -334,27 +252,17 @@ class Explainer:
         raw = response.choices[0].message.content or ""
         return self._parse_response(raw, confidence)
 
-    # ── Response parsing ─────────────────────────────────────────────────────
-
     def _parse_response(self, raw: str, confidence: float) -> ExplainerOutput | None:
-        """
-        Parse Groq response into validated ExplainerOutput.
-        Handles clean JSON, markdown-fenced JSON, JSON in prose.
-        Returns None if all parsing attempts fail.
-        """
-        # Strip markdown fences
         clean = re.sub(r"```json\s*", "", raw)
         clean = re.sub(r"```\s*", "", clean)
         clean = clean.strip()
 
-        # Direct parse
         try:
             parsed = json.loads(clean)
             return self._validate_response(parsed, confidence)
         except json.JSONDecodeError:
             pass
 
-        # Extract JSON object from prose
         match = re.search(r"\{.*\}", clean, re.DOTALL)
         if match:
             try:
@@ -368,11 +276,6 @@ class Explainer:
         return None
 
     def _validate_response(self, parsed: dict, confidence: float) -> ExplainerOutput:
-        """
-        Validate and normalize parsed dict into ExplainerOutput via Pydantic.
-        Injects confidence from Agent 3 (the LLM doesn't return it).
-        """
-        # Normalize citations before passing to Pydantic
         raw_citations = parsed.get("citations", [])
         clean_citations = []
         if isinstance(raw_citations, list):
@@ -393,10 +296,7 @@ class Explainer:
             citations=clean_citations,
         )
 
-    # ── Helpers ─────────────────────────────────────────────────────────────��
-
     def _strip_context_tag(self, claim: str) -> str:
-        """Remove [سياق: ...] prefix if present."""
         if claim.startswith("[سياق:"):
             match = re.match(r"\[سياق:\s*.+?\]\s*(.+)", claim, re.DOTALL)
             if match:

agents/jury/__init__.py

@@ -1,12 +1,3 @@
-"""
-Delphi Jury System — agents/jury/__init__.py
-Arabic News Analyzer · Graduation Project
-
-Exposes shared jury types.
-The orchestration entry point lives in graph/jury_subgraph.py
-(kept in the graph layer to avoid circular imports).
-"""
-
-from agents.jury.aggregator import JurorOutput, JuryResult  # noqa: F401
+from agents.jury.aggregator import JurorOutput, JuryResult
 
 __all__ = ["JurorOutput", "JuryResult"]

agents/jury/_base_juror.py

@@ -1,19 +1,3 @@
-"""
-Delphi Jury — Base Juror  (agents/jury/_base_juror.py)
-Arabic News Analyzer · Graduation Project
-
-Shared async Groq wrapper used by all three jurors.
-Each juror subclass only needs to define:
-  • JUROR_ID     – identifier string
-  • SYSTEM_PROMPT – specialist persona & rules
-
-The base class handles:
-  • Groq API call (AsyncGroq, llama-3.3-70b-versatile)
-  • JSON parsing with markdown-fence stripping
-  • Retry once on parse failure
-  • Fallback JurorOutput on total failure
-"""
-
 from __future__ import annotations
 
 import json
@@ -30,22 +14,14 @@ load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-# ── Shared config ─────────────────────────────────────────────────────────────
 GROQ_MODEL = "llama-3.3-70b-versatile"
 MAX_TOKENS = 900
-TEMPERATURE = 0.15          # low = more deterministic analysis
+TEMPERATURE = 0.15
 MAX_EVIDENCE_SNIPPETS = 8
-MAX_SNIPPET_LENGTH = 300    # chars
-
+MAX_SNIPPET_LENGTH = 300
 
-# ── Base class ────────────────────────────────────────────────────────────────
 
 class BaseJuror:
-    """
-    Abstract base for all Delphi jurors.
-    Subclasses MUST set JUROR_ID and SYSTEM_PROMPT as class attributes.
-    """
-
     JUROR_ID: str = "base_juror"
     SYSTEM_PROMPT: str = ""
 
@@ -58,19 +34,7 @@ class BaseJuror:
         env_var = key_map.get(self.JUROR_ID, "GROQ_API_KEY1")
         self.client = AsyncGroq(api_key=os.environ.get(env_var))
 
-    # ── Public entry point ───────────────────────────────────────────────────
-
     async def analyse(self, claim: str, evidence: list[dict]) -> JurorOutput:
-        """
-        Analyse the claim against evidence and return a JurorOutput.
-
-        Steps:
-        1. Build prompt from claim + evidence snippets
-        2. Call Groq
-        3. Parse JSON response
-        4. Retry once on parse failure
-        5. Return UNVERIFIABLE default on total failure
-        """
         user_prompt = self._build_prompt(claim, evidence)
 
         result = await self._call_groq(user_prompt)
@@ -95,8 +59,6 @@ class BaseJuror:
             reasoning="فشل الوكيل في تحليل الادعاء.",
         )
 
-    # ── Prompt construction ──────────────────────────────────────────────────
-
     def _build_prompt(self, claim: str, evidence: list[dict]) -> str:
         capped = evidence[:MAX_EVIDENCE_SNIPPETS]
         evidence_lines: list[str] = []
@@ -128,8 +90,6 @@ class BaseJuror:
             f"بناءً على الأدلة أعلاه فقط، أصدر تحليلك بصيغة JSON."
         )
 
-    # ── Groq API call ────────────────────────────────────────────────────────
-
     async def _call_groq(self, user_prompt: str) -> JurorOutput | None:
         try:
             response = await self.client.chat.completions.create(
@@ -148,20 +108,16 @@ class BaseJuror:
         raw = response.choices[0].message.content or ""
         return self._parse_response(raw)
 
-    # ── Response parsing ─────────────────────────────────────────────────────
-
     def _parse_response(self, raw: str) -> JurorOutput | None:
         clean = re.sub(r"```json\s*", "", raw)
         clean = re.sub(r"```\s*", "", clean).strip()
 
-        # Direct parse
         try:
             parsed = json.loads(clean)
             return self._validate(parsed)
         except json.JSONDecodeError:
             pass
 
-        # Extract JSON object from prose
         match = re.search(r"\{.*?\}", clean, re.DOTALL)
         if match:
             try:
@@ -176,13 +132,11 @@ class BaseJuror:
         return None
 
     def _validate(self, parsed: dict) -> JurorOutput:
-        """Normalise parsed dict into a JurorOutput."""
         try:
             confidence = float(parsed.get("confidence", 0.0))
         except (TypeError, ValueError):
             confidence = 0.0
 
-        # Extract citations list if present
         raw_citations = parsed.get("citations", [])
         citations: list[dict] = []
         if isinstance(raw_citations, list):

agents/jury/aggregator.py

@@ -1,25 +1,3 @@
-"""
-Delphi Jury — Aggregator  (agents/jury/aggregator.py)
-Arabic News Analyzer · Graduation Project
-
-Pure-Python consensus engine.  NO LLM calls here.
-
-Aggregation rules
-─────────────────
-• Majority vote (≥ 2/3) determines final verdict.
-• If no majority → verdict = UNVERIFIABLE.
-
-Confidence multiplier
-─────────────────────
-• Unanimous (3/3) → ×1.0
-• Majority  (2/3) → ×0.85
-• No consensus    → ×0.0  (UNVERIFIABLE path)
-
-Final confidence = mean(post_debate_confidences) * multiplier
-
-needs_human_review is set to True when final verdict is UNVERIFIABLE.
-"""
-
 from __future__ import annotations
 
 from collections import Counter
@@ -27,28 +5,23 @@ from dataclasses import dataclass, field
 from statistics import mean
 from typing import Literal
 
-# ── Valid verdict labels ──────────────────────────────────────────────────────
 
-VerdictLabel = Literal["SUPPORTED", "REFUTED", "PARTIALLY_TRUE", "UNVERIFIABLE"]
+VerdictLabel = Literal["SUPPORTED", "REFUTED",
+                       "PARTIALLY_TRUE", "UNVERIFIABLE"]
 
 VALID_VERDICTS: frozenset[str] = frozenset(
     {"SUPPORTED", "REFUTED", "PARTIALLY_TRUE", "UNVERIFIABLE"}
 )
 
-CONFIDENCE_SPREAD_THRESHOLD = 0.25  # triggers debate when exceeded
-
-
-# ── Data classes ─────────────────────────────────────────────────────────────
+CONFIDENCE_SPREAD_THRESHOLD = 0.25
 
 
 @dataclass
 class JurorOutput:
-    """Single juror verdict — same shape for both pre- and post-debate."""
-
-    juror_id: str                   # "J1_empiricist" | "J2_contextualist" | "J3_sceptic"
-    verdict: str                    # one of VALID_VERDICTS
-    confidence: float               # 0.0 – 1.0
-    reasoning: str                  # Arabic or English reasoning paragraph
+    juror_id: str
+    verdict: str
+    confidence: float
+    reasoning: str
     citations: list[dict] = field(default_factory=list)
 
     def __post_init__(self) -> None:
@@ -60,17 +33,12 @@ class JurorOutput:
 
 @dataclass
 class JuryResult:
-    """Final output of the Delphi jury for a single claim."""
-
     verdict: str
     confidence: float
-    jury_outputs: list[JurorOutput]            # post-debate (or initial if no debate)
-    debate_log: list[dict]                     # empty list when debate was skipped
+    jury_outputs: list[JurorOutput]
+    debate_log: list[dict]
     needs_human_review: bool
-    reasoning: str                             # combined reasoning for Explainer
-
-
-# ── Helpers ───────────────────────────────────────────────────────────────────
+    reasoning: str
 
 
 def _normalise_verdict(v: str) -> str:
@@ -85,17 +53,7 @@ def _confidence_spread(outputs: list[JurorOutput]) -> float:
     return max(confidences) - min(confidences)
 
 
-# ── Public API ────────────────────────────────────────────────────────────────
-
-
 def detect_disagreement(outputs: list[JurorOutput]) -> bool:
-    """
-    Return True when a debate round is required.
-
-    Disagreement exists when:
-    • jurors disagree on verdict label, OR
-    • confidence spread > CONFIDENCE_SPREAD_THRESHOLD (0.25)
-    """
     unique_verdicts = {o.verdict for o in outputs}
     if len(unique_verdicts) > 1:
         return True
@@ -105,19 +63,6 @@ def detect_disagreement(outputs: list[JurorOutput]) -> bool:
 
 
 def aggregate(outputs: list[JurorOutput], debate_log: list[dict]) -> JuryResult:
-    """
-    Aggregate post-debate juror outputs into a single JuryResult.
-
-    Parameters
-    ----------
-    outputs   : list of JurorOutput (post-debate or initial if no debate)
-    debate_log: list of debate-round dicts (empty when debate was skipped)
-
-    Returns
-    -------
-    JuryResult with final verdict, confidence, needs_human_review flag,
-    and combined reasoning.
-    """
     if not outputs:
         return JuryResult(
             verdict="UNVERIFIABLE",
@@ -128,27 +73,22 @@ def aggregate(outputs: list[JurorOutput], debate_log: list[dict]) -> JuryResult:
             reasoning="لم يتم الحصول على أي مخرجات من هيئة المحلفين.",
         )
 
-    # ── Majority vote ────────────────────────────────────────────────────────
     verdict_counts: Counter[str] = Counter(o.verdict for o in outputs)
     top_verdict, top_count = verdict_counts.most_common(1)[0]
     total = len(outputs)
 
-    if top_count >= 2:  # majority (2/3 or 3/3)
+    if top_count >= 2:
         final_verdict = top_verdict
         multiplier = 1.0 if top_count == total else 0.85
     else:
-        # Each juror voted differently — no consensus
         final_verdict = "UNVERIFIABLE"
         multiplier = 0.0
 
-    # ── Confidence ───────────────────────────────────────────────────────────
     avg_confidence = mean(o.confidence for o in outputs)
     final_confidence = round(avg_confidence * multiplier, 3)
 
-    # ── needs_human_review ───────────────────────────────────────────────────
     needs_human_review = final_verdict == "UNVERIFIABLE"
 
-    # ── Combined reasoning ───────────────────────────────────────────────────
     reasoning_parts = [
         f"[{o.juror_id}] الحكم: {o.verdict} (ثقة: {o.confidence:.0%})\n{o.reasoning}"
         for o in outputs

agents/jury/contextualist.py

@@ -1,29 +1,8 @@
-"""
-Delphi Jury — J2 Contextualist  (agents/jury/contextualist.py)
-Arabic News Analyzer · Graduation Project
-
-Persona:
-  Uses historical and geopolitical context.
-  Uses named entities and KG relationships.
-  Detects misleading framing even when individual facts are technically true.
-
-Targets:
-  • missing context (claims stripped of necessary background)
-  • narrative manipulation
-  • context-stripped claims that mislead through selective truth
-
-Reasoning style:
-  Frame-aware.  Asks not just "is this fact correct?" but
-  "does the framing create a false impression?"
-"""
-
 from agents.jury._base_juror import BaseJuror
 
-# ── Juror identity ────────────────────────────────────────────────────────────
 
 _JUROR_ID = "J2_contextualist"
 
-# ── System prompt ─────────────────────────────────────────────────────────────
 
 _SYSTEM_PROMPT = """أنت المحقق السياقي (J2) في هيئة تحقق متخصصة في الأخبار العربية.
 
@@ -53,13 +32,6 @@ _SYSTEM_PROMPT = """أنت المحقق السياقي (J2) في هيئة تحق
 }"""
 
 
-# ── Juror class ───────────────────────────────────────────────────────────────
-
 class ContextualistJuror(BaseJuror):
-    """
-    J2 — Contextualist juror.
-    Frame-aware analysis; catches narrative manipulation and context stripping.
-    """
-
     JUROR_ID = _JUROR_ID
     SYSTEM_PROMPT = _SYSTEM_PROMPT

agents/jury/debate.py

@@ -1,27 +1,3 @@
-"""
-Delphi Jury — Debate Module  (agents/jury/debate.py)
-Arabic News Analyzer · Graduation Project
-
-Orchestrates a single debate revision round between dissenting jurors.
-
-How it works
-────────────
-1.  Identify dissenters — jurors whose verdict differs from the majority
-    OR whose confidence deviates significantly from the mean.
-2.  Build an anonymised summary of other jurors' reasoning (no juror IDs).
-3.  Each dissenting juror calls the LLM with the anonymised context and
-    is asked to either revise or defend its position.
-4.  Non-dissenters keep their original output unchanged.
-5.  Return updated outputs + a structured debate log.
-
-Design constraints
-──────────────────
-• Only ONE debate round (as specified).
-• Non-dissenters are never called again (saves Groq tokens).
-• Anonymisation prevents anchoring bias between jurors.
-• asyncio.gather() used for parallel dissenter revision calls.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -40,14 +16,11 @@ load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-# ── Config ────────────────────────────────────────────────────────────────────
 GROQ_MODEL = "llama-3.3-70b-versatile"
 DEBATE_MAX_TOKENS = 700
 DEBATE_TEMPERATURE = 0.2
 
 
-# ── Debate system prompt ──────────────────────────────────────────────────────
-
 _DEBATE_SYSTEM_PROMPT = """أنت محقق في هيئة تحقق عربية متخصصة.
 لقد أصدرت حكماً أولياً على ادعاء، لكن زملاءك (مجهولو الهوية) توصلوا إلى آراء مختلفة.
 
@@ -70,29 +43,21 @@ _DEBATE_SYSTEM_PROMPT = """أنت محقق في هيئة تحقق عربية م
 }"""
 
 
-# ── Internal helpers ──────────────────────────────────────────────────────────
-
 def _majority_verdict(outputs: list[JurorOutput]) -> str | None:
-    """Return the majority verdict or None if no majority."""
     counts: Counter[str] = Counter(o.verdict for o in outputs)
     top_v, top_c = counts.most_common(1)[0]
     return top_v if top_c >= 2 else None
 
 
 def _is_dissenter(juror: JurorOutput, majority_verdict: str | None) -> bool:
-    """A juror is a dissenter if their verdict differs from the majority verdict."""
     if majority_verdict is None:
-        return True  # no majority → all dissent
+        return True
     return juror.verdict != majority_verdict
 
 
 def _anonymise_others(
     all_outputs: list[JurorOutput], exclude_id: str
 ) -> str:
-    """
-    Build an anonymised reasoning summary for the debate prompt,
-    excluding the dissenting juror's own output.
-    """
     parts: list[str] = []
     anon_label = ["المحقق أ", "المحقق ب", "المحقق ج"]
     idx = 0
@@ -141,10 +106,6 @@ async def _revise_juror(
     all_initial: list[JurorOutput],
     client: AsyncGroq,
 ) -> tuple[JurorOutput, dict]:
-    """
-    Ask one dissenting juror to revise its verdict in light of peer reasoning.
-    Returns (updated_output, debate_log_entry).
-    """
     evidence_summary = _build_evidence_summary(evidence)
     peer_summary = _anonymise_others(all_initial, exclude_id=juror.juror_id)
     prompt = _build_debate_prompt(juror, claim, evidence_summary, peer_summary)
@@ -163,7 +124,6 @@ async def _revise_juror(
         raw = response.choices[0].message.content or ""
     except Exception as exc:
         logger.error("[Debate] Groq error for %s: %s", juror.juror_id, exc)
-        # Keep original verdict on API error
         return juror, {
             "juror_id": juror.juror_id,
             "original_verdict": juror.verdict,
@@ -173,7 +133,8 @@ async def _revise_juror(
         }
 
     revised = _parse_revision(raw, juror)
-    changed = revised.verdict != juror.verdict or abs(revised.confidence - juror.confidence) > 0.05
+    changed = revised.verdict != juror.verdict or abs(
+        revised.confidence - juror.confidence) > 0.05
 
     log_entry = {
         "juror_id":        juror.juror_id,
@@ -188,7 +149,6 @@ async def _revise_juror(
 
 
 def _parse_revision(raw: str, original: JurorOutput) -> JurorOutput:
-    """Parse the debate revision response; fall back to original on failure."""
     clean = re.sub(r"```json\s*", "", raw)
     clean = re.sub(r"```\s*", "", clean).strip()
 
@@ -204,7 +164,8 @@ def _parse_revision(raw: str, original: JurorOutput) -> JurorOutput:
             juror_id=original.juror_id,
             verdict=verdict,
             confidence=confidence,
-            reasoning=str(d.get("reasoning", original.reasoning)).strip() or original.reasoning,
+            reasoning=str(d.get("reasoning", original.reasoning)
+                          ).strip() or original.reasoning,
             citations=original.citations,
         )
 
@@ -220,36 +181,20 @@ def _parse_revision(raw: str, original: JurorOutput) -> JurorOutput:
         except json.JSONDecodeError:
             pass
 
-    logger.warning("[Debate] Could not parse revision for %s — keeping original", original.juror_id)
+    logger.warning(
+        "[Debate] Could not parse revision for %s — keeping original", original.juror_id)
     return original
 
 
-# ── Public entry point ────────────────────────────────────────────────────────
-
 async def run_debate(
     initial_outputs: list[JurorOutput],
     claim: str,
     evidence: list[dict],
 ) -> tuple[list[JurorOutput], list[dict]]:
-    """
-    Run the debate round.
-
-    Parameters
-    ----------
-    initial_outputs : list of JurorOutput from Stage 1 (independent analysis)
-    claim           : the claim string (no [سياق:] tag)
-    evidence        : evidence list from Agent 2
-
-    Returns
-    -------
-    (updated_outputs, debate_log)
-        updated_outputs : list[JurorOutput] — post-debate verdicts
-                          (dissenters may have revised; non-dissenters unchanged)
-        debate_log      : list[dict] — one entry per dissenting juror
-    """
     majority = _majority_verdict(initial_outputs)
     dissenters = [o for o in initial_outputs if _is_dissenter(o, majority)]
-    non_dissenters = [o for o in initial_outputs if not _is_dissenter(o, majority)]
+    non_dissenters = [
+        o for o in initial_outputs if not _is_dissenter(o, majority)]
 
     if not dissenters:
         logger.info("[Debate] No dissenters found — debate skipped.")
@@ -262,7 +207,6 @@ async def run_debate(
 
     client = AsyncGroq(api_key=os.environ.get("GROQ_API_KEY5"))
 
-    # Revise all dissenters in parallel
     revision_tasks = [
         _revise_juror(d, claim, evidence, initial_outputs, client)
         for d in dissenters
@@ -280,10 +224,8 @@ async def run_debate(
         updated_dissenters.append(revised_output)
         debate_log.append(log_entry)
 
-    # Combine: non-dissenters keep originals; dissenters use revised
     final_outputs = non_dissenters + updated_dissenters
 
-    # Preserve original order by juror_id
     order = {o.juror_id: i for i, o in enumerate(initial_outputs)}
     final_outputs.sort(key=lambda o: order.get(o.juror_id, 999))
 

agents/jury/empiricist.py

@@ -1,30 +1,8 @@
-"""
-Delphi Jury — J1 Empiricist  (agents/jury/empiricist.py)
-Arabic News Analyzer · Graduation Project
-
-Persona:
-  Only trusts explicit retrieved evidence.
-  Avoids inference beyond source text.
-  Focuses on factual grounding.
-
-Targets:
-  • fabricated statistics
-  • unsupported claims
-  • hallucinated facts
-
-Reasoning style:
-  Evidence-first.  Each statement in the reasoning must map back to a
-  numbered evidence item.  If a fact is not in the evidence, it is
-  treated as unverifiable.
-"""
-
 from agents.jury._base_juror import BaseJuror
 
-# ── Juror identity ────────────────────────────────────────────────────────────
 
 _JUROR_ID = "J1_empiricist"
 
-# ── System prompt ─────────────────────────────────────────────────────────────
 
 _SYSTEM_PROMPT = """أنت المحقق التجريبي (J1) في هيئة تحقق متخصصة في الأخبار العربية.
 
@@ -54,13 +32,7 @@ _SYSTEM_PROMPT = """أنت المحقق التجريبي (J1) في هيئة تح
 }"""
 
 
-# ── Juror class ───────────────────────────────────────────────────────────────
-
 class EmpricistJuror(BaseJuror):
-    """
-    J1 — Empiricist juror.
-    Verdict driven entirely by explicit textual evidence.
-    """
 
     JUROR_ID = _JUROR_ID
     SYSTEM_PROMPT = _SYSTEM_PROMPT

agents/jury/sceptic.py

@@ -1,30 +1,8 @@
-"""
-Delphi Jury — J3 Sceptic  (agents/jury/sceptic.py)
-Arabic News Analyzer · Graduation Project
-
-Persona:
-  Assumes the claim is FALSE until proven otherwise with strong evidence.
-  Requires a high evidentiary bar before issuing SUPPORTED.
-  Serves as the jury's defence against over-confident false positives.
-
-Targets:
-  • overconfident SUPPORTED verdicts based on weak evidence
-  • propaganda-style claims designed to sound authoritative
-  • claims supported only by a single low-credibility source
-
-Reasoning style:
-  Devil's advocate.  Starts from doubt and demands that evidence
-  overcome the presumption of falsity.  Penalises missing sources,
-  single-source confirmations, and vague language.
-"""
-
 from agents.jury._base_juror import BaseJuror
 
-# ── Juror identity ────────────────────────────────────────────────────────────
 
 _JUROR_ID = "J3_sceptic"
 
-# ── System prompt ─────────────────────────────────────────────────────────────
 
 _SYSTEM_PROMPT = """أنت المحقق المشكِّك (J3) في هيئة تحقق متخصصة في الأخبار العربية.
 
@@ -54,13 +32,6 @@ _SYSTEM_PROMPT = """أنت المحقق المشكِّك (J3) في هيئة تح
 }"""
 
 
-# ── Juror class ───────────────────────────────────────────────────────────────
-
 class ScepticJuror(BaseJuror):
-    """
-    J3 — Sceptic juror.
-    Guilty-until-proven-innocent stance; guards against weak SUPPORTED verdicts.
-    """
-
     JUROR_ID = _JUROR_ID
     SYSTEM_PROMPT = _SYSTEM_PROMPT

config/trusted_sources.py

@@ -1,5 +1,4 @@
 TRUSTED_DOMAINS: list[str] = [
-    # --- Existing List ---
     "bbc.com",
     "reuters.com",
     "apnews.com",
@@ -9,50 +8,41 @@ TRUSTED_DOMAINS: list[str] = [
     "un.org",
     "who.int",
 
-    # --- Major International News ---
     "cnn.com",
     "nytimes.com",
     "washingtonpost.com",
     "theguardian.com",
     "bloomberg.com",
-    "afp.com",            # Agence France-Presse (Global wire service)
-    "dw.com",             # Deutsche Welle (Germany)
-    "france24.com",       # France 24
+    "afp.com",
+    "dw.com",
+    "france24.com",
 
-    # --- Middle East: Pan-Arab & Regional Heavyweights ---
-    "asharq.com",         # Asharq Al-Awsat / Asharq News
-    "skynewsarabia.com",  # Sky News Arabia
-    "almayadeen.net",     # Al Mayadeen (Lebanon-based regional network)
-    "thenationalnews.com",  # The National (Major UAE-based English daily)
-    "al-monitor.com",     # Al-Monitor (Deep regional analysis)
+    "asharq.com",
+    "skynewsarabia.com",
+    "almayadeen.net",
+    "thenationalnews.com",
+    "al-monitor.com",
 
-    # --- Middle East: North Africa & Levant Focus ---
     "sana.sy",
     "syria.tv",
     "zamanalwsl.net",
-    "lorientlejour.com",  # L'Orient-Le Jour (Major Lebanese daily)
-    "naharnet.com",       # Naharnet (Lebanon)
-    "jordantimes.com",    # Jordan Times
-    "ahram.org.eg",       # Al-Ahram (Egypt's state/flagship paper)
-    "madaamasr.com",      # Mada Masr (Prominent Egyptian independent media)
+    "lorientlejour.com",
+    "naharnet.com",
+    "jordantimes.com",
+    "ahram.org.eg",
+    "madaamasr.com",
 
-    # --- Middle East: Gulf Focus ---
     "aljazeera.net",
-    "arabnews.com",       # Arab News (Saudi Arabia / English daily)
-    "gulfnews.com",       # Gulf News (UAE)
-    "alrai.com",          # Al-Rai (Kuwait)
+    "arabnews.com",
+    "gulfnews.com",
+    "alrai.com",
 
-    # --- Middle East: Additional Syrian/Levant Media ---
-    "enabbaladi.net",     # Enab Baladi (Respected Syrian independent media)
-    "rozana.fm",          # Radio Rozana (Syrian independent media)
-    "sn4hr.org",          # Syrian Network for Human Rights (Documentation)
+    "enabbaladi.net",
+    "rozana.fm",
+    "sn4hr.org",
 
-    # --- Arabic Fact-Checking Organizations ---
-    # تحقق — Palestinian Observatory for Fact-Checking (AFCN member)
     "tahaqaq.ps",
-    # فتبينوا — MENA-wide fact-checking platform (confirmed via live test)
     "fatabyyano.net",
-    # تأكد — Syria-focused fact-checking (confirmed via live test)
     "verify-sy.com",
-    "misbar.com",         # Misbar — Jordan-based Arabic fact-checking platform
+    "misbar.com",
 ]

graph/jury_subgraph.py

@@ -1,25 +1,3 @@
-"""
-Delphi Jury — Jury Subgraph  (graph/jury_subgraph.py)
-Arabic News Analyzer · Graduation Project
-
-Orchestrates the full Delphi pipeline for a SINGLE claim:
-
-  Stage 1 — Independent parallel analysis (J1, J2, J3 via asyncio.gather)
-  Stage 2 — Disagreement detection        (pure Python, no LLM)
-  Stage 3 — Debate round                  (conditional; only when needed)
-  Stage 4 — Aggregation                   (pure Python, no LLM)
-
-Returns a JuryResult that the LangGraph pipeline stores in state as
-the claim's "verdict" field (plus extended jury metadata).
-
-The function signature is:
-    run_jury_subgraph(claim: str, evidence: list[dict]) -> dict
-
-The returned dict is JSON-serialisable and matches the expected
-claim_result["verdict"] shape consumed by run_explainer and
-_serialize_claim_results in langgraph_pipeline.py.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -39,53 +17,28 @@ from agents.jury.aggregator import (
 
 logger = logging.getLogger(__name__)
 
-# ── Singleton juror instances ─────────────────────────────────────────────────
-# Instantiated once at module load time; each holds one AsyncGroq client.
-
 _j1 = EmpricistJuror()
 _j2 = ContextualistJuror()
 _j3 = ScepticJuror()
 
 
-# ── Public entry point ────────────────────────────────────────────────────────
-
 async def run_jury_subgraph(claim: str, evidence: list[dict]) -> dict:
-    """
-    Run the full Delphi jury pipeline for a single claim.
-
-    Parameters
-    ----------
-    claim    : clean claim string (no [سياق:] tag)
-    evidence : list of evidence dicts from Agent 2
-
-    Returns
-    -------
-    dict with keys:
-        verdict            str   — final consensus verdict
-        confidence         float — weighted confidence
-        reasoning          str   — combined post-debate reasoning
-        jury_outputs       list  — per-juror results (post-debate)
-        debate_log         list  — debate round entries (empty if skipped)
-        needs_human_review bool  — True when verdict == UNVERIFIABLE
-    """
-    # ── Stage 1: Independent parallel analysis ────────────────────────────────
-    logger.info("[Jury] Stage 1 — launching 3 jurors in parallel for: %.60s", claim)
+    logger.info(
+        "[Jury] Stage 1 — launching 3 jurors in parallel for: %.60s", claim)
 
     j1_out, j2_out, j3_out = await asyncio.gather(
         _j1.analyse(claim, evidence),
         _j2.analyse(claim, evidence),
         _j3.analyse(claim, evidence),
-        return_exceptions=False,  # let individual failures surface as JurorOutput fallbacks
+        return_exceptions=False,
     )
 
     initial_outputs: list[JurorOutput] = [j1_out, j2_out, j3_out]
 
     _log_jury_stage(initial_outputs, stage="initial")
 
-    # ── Stage 2: Disagreement detection ──────────────────────────────────────
     disagreement = detect_disagreement(initial_outputs)
 
-    # ── Stage 3: Debate (only when needed) ───────────────────────────────────
     if disagreement:
         logger.info("[Jury] Stage 3 — disagreement detected, starting debate.")
         post_debate_outputs, debate_log = await run_debate(
@@ -97,7 +50,6 @@ async def run_jury_subgraph(claim: str, evidence: list[dict]) -> dict:
         post_debate_outputs = initial_outputs
         debate_log = []
 
-    # ── Stage 4: Aggregation ──────────────────────────────────────────────────
     result: JuryResult = aggregate(post_debate_outputs, debate_log)
 
     logger.info(
@@ -108,8 +60,6 @@ async def run_jury_subgraph(claim: str, evidence: list[dict]) -> dict:
     return _serialise_result(result)
 
 
-# ── Serialisation ─────────────────────────────────────────────────────────────
-
 def _serialise_juror_output(o: JurorOutput) -> dict:
     return {
         "juror_id":   o.juror_id,
@@ -121,21 +71,16 @@ def _serialise_juror_output(o: JurorOutput) -> dict:
 
 
 def _serialise_result(result: JuryResult) -> dict:
-    """Convert JuryResult to a plain JSON-serialisable dict."""
     return {
-        # ── Fields that replace the old single-verifier verdict ───────────────
         "verdict":            result.verdict,
         "confidence":         result.confidence,
         "reasoning":          result.reasoning,
-        # ── Jury-specific metadata ────────────────────────────────────────────
         "jury_outputs":       [_serialise_juror_output(o) for o in result.jury_outputs],
         "debate_log":         result.debate_log,
         "needs_human_review": result.needs_human_review,
     }
 
 
-# ── Debug helper ──────────────────────────────────────────────────────────────
-
 def _log_jury_stage(outputs: list[JurorOutput], stage: str) -> None:
     for o in outputs:
         logger.debug(

graph/langgraph_pipeline.py

@@ -11,7 +11,6 @@ from graph.jury_subgraph import run_jury_subgraph
 class ClaimResult(TypedDict):
     claim: str
     evidence: list[dict[str, Any]]
-    # includes jury_outputs, debate_log, needs_human_review
     verdict: dict[str, Any]
     explanation: dict[str, Any]
 
@@ -160,12 +159,6 @@ async def run_evidence_retriever(state: PipelineState) -> PipelineState:
 
 
 async def run_jury(state: PipelineState) -> PipelineState:
-    """
-    Stage 3 — Delphi Jury.
-
-    Processes each claim independently through the jury subgraph
-    (J1 Empiricist, J2 Contextualist, J3 Sceptic → Debate → Aggregator).
-    """
     updated_results: list[ClaimResult] = []
 
     for result in state["claim_results"]:
@@ -176,12 +169,6 @@ async def run_jury(state: PipelineState) -> PipelineState:
 
 
 async def run_explainer(state: PipelineState) -> PipelineState:
-    """
-    Stage 4 — Explainer.
-
-    Passes jury reasoning + debate log to the explainer so it can produce
-    a richer human-readable explanation that reflects the jury's deliberation.
-    """
     updated_results: list[ClaimResult] = []
 
     for result in state["claim_results"]:
@@ -237,18 +224,11 @@ pipeline = build_pipeline()
 
 
 def _serialize_claim_results(claim_results: list[ClaimResult]) -> list[dict[str, Any]]:
-    """
-    Convert internal ClaimResult list into clean per-claim dicts for the API.
-    Claims from Agent 1 are already self-contained — no stripping needed.
-    Includes jury metadata (jury_outputs, debate_log, needs_human_review)
-    for frontend rendering and audit trails.
-    """
     out = []
     for result in claim_results:
         exp = result.get("explanation", {})
         verdict_block = result.get("verdict", {})
         out.append({
-            # ── Standard fields (VerifyResponse compatible) ────────────────────
             "claim":       result["claim"],
             "verdict":     verdict_block.get("verdict", "UNVERIFIABLE"),
             "confidence":  round(float(verdict_block.get("confidence", 0.0)), 3),
@@ -258,7 +238,6 @@ def _serialize_claim_results(claim_results: list[ClaimResult]) -> list[dict[str,
                 for c in exp.get("citations", [])
                 if isinstance(c, dict)
             ],
-            # ── Jury-specific metadata ─────────────────────────────────────────
             "needs_human_review": verdict_block.get("needs_human_review", False),
             "jury_outputs":       verdict_block.get("jury_outputs", []),
             "debate_log":         verdict_block.get("debate_log", []),
@@ -289,12 +268,10 @@ async def run_pipeline(text: str) -> dict[str, Any]:
     )
 
     return {
-        # ── Article-level summary (VerifyResponse compatible) ─────────────────
         "verdict":            article.get("verdict", "UNVERIFIABLE"),
         "confidence":         round(float(article.get("confidence", 0.0)), 3),
         "arabic_explanation": article.get("arabic_explanation", ""),
         "citations":          article.get("citations", []),
         "needs_human_review": needs_human_review,
-        # ── Per-claim breakdown ───────────────────────────────────────────────
         "claims":             _serialize_claim_results(claim_results),
     }

main.py

@@ -6,8 +6,6 @@ from schemas import VerifyRequest, VerifyResponse
 app = FastAPI(title="Arabic Verifier Service")
 
 
-# ── Endpoints ─────────────────────────────────────────────────────────────────
-
 @app.post("/verify", response_model=VerifyResponse)
 async def verify(req: VerifyRequest):
     try:

schemas.py

@@ -1,26 +1,16 @@
-"""
-schemas.py
-Pydantic request/response models for the Arabic Verifier Service.
-"""
-
 from pydantic import BaseModel
 
 
-# ── Request ───────────────────────────────────────────────────────────────────
-
 class VerifyRequest(BaseModel):
     text: str
 
 
-# ── Response models ───────────────────────────────────────────────────────────
-
 class Citation(BaseModel):
     title: str = ""
     url: str = ""
 
 
 class JurorVerdictDetail(BaseModel):
-    """Per-juror result from the Delphi jury."""
     juror_id: str
     verdict: str
     confidence: float = 0.0
@@ -29,7 +19,6 @@ class JurorVerdictDetail(BaseModel):
 
 
 class DebateLogEntry(BaseModel):
-    """Single entry from the debate round log."""
     juror_id: str
     original_verdict: str
     original_confidence: float = 0.0

tools/google_factcheck.py

@@ -16,8 +16,8 @@ async def search_google_factcheck(
     page_size: int = 5,
     api_key: str | None = None,
 ) -> list[dict[str, Any]]:
-    """Search the Google Fact Check Tools API for reviewed claims."""
-    resolved_api_key = api_key or os.getenv("GOOGLE_FACTCHECK_API_KEY", "").strip()
+    resolved_api_key = api_key or os.getenv(
+        "GOOGLE_FACTCHECK_API_KEY", "").strip()
     if not resolved_api_key:
         print("[GoogleFC] No API key found in GOOGLE_FACTCHECK_API_KEY.")
         return []
@@ -45,7 +45,8 @@ async def search_google_factcheck(
     for claim_item in data.get("claims", []):
         claim_text = str(claim_item.get("text", "")).strip()
         for review in claim_item.get("claimReview", []):
-            publisher = str(review.get("publisher", {}).get("name", "")).strip()
+            publisher = str(review.get(
+                "publisher", {}).get("name", "")).strip()
             rating = str(review.get("textualRating", "")).strip()
             url = str(review.get("url", "")).strip()
             title = str(review.get("title", "")).strip() or claim_text

tools/tavily_search.py

@@ -10,14 +10,8 @@ from tavily import TavilyClient
 
 load_dotenv()
 
-# ── Key rotation ──────────────────────────────────────────────────────────────
-
 
 def _load_keys() -> list[str]:
-    """
-    Collects all TAVILY_API_KEY_N env vars in order (1, 2, 3, ...).
-    Falls back to plain TAVILY_API_KEY if no numbered keys exist.
-    """
     keys = []
     for i in count(1):
         key = os.getenv(f"TAVILY_API_KEY_{i}")
@@ -32,7 +26,7 @@ def _load_keys() -> list[str]:
 
 
 _KEYS = _load_keys()
-_key_index = 0  # points at the currently active key
+_key_index = 0
 
 
 def _current_client() -> TavilyClient | None:
@@ -42,7 +36,6 @@ def _current_client() -> TavilyClient | None:
 
 
 def _rotate_key() -> bool:
-    """Advance to the next key. Returns False if no more keys are left."""
     global _key_index
     if _key_index + 1 < len(_KEYS):
         _key_index += 1
@@ -56,13 +49,11 @@ def _is_rate_limit_error(exc: Exception) -> bool:
     return "429" in msg or "rate limit" in msg or "quota" in msg
 
 
-# ── Domain filtering ─────────────────────────────────────────────────────────
 def _domain_matches(url: str, domains: list[str]) -> bool:
     host = urlparse(url).netloc.lower().removeprefix("www.")
     return any(host == d or host.endswith("." + d) for d in domains)
 
 
-# ── Core search call (sync, retried across keys) ─────────────────────────────
 def _tavily_search_sync(
     query: str,
     *,
@@ -73,7 +64,7 @@ def _tavily_search_sync(
         print("[Tavily] No TAVILY_API_KEY_N or TAVILY_API_KEY set in .env")
         return []
 
-    attempts = len(_KEYS) - _key_index  # remaining keys from current position
+    attempts = len(_KEYS) - _key_index
     for _ in range(attempts):
         client = _current_client()
         try:
@@ -90,7 +81,7 @@ def _tavily_search_sync(
                 print(
                     f"[Tavily] {label} rate-limited: {type(exc).__name__}: {exc!r}")
                 if _rotate_key():
-                    continue  # retry immediately with the next key
+                    continue
                 print("[Tavily] All keys exhausted — giving up for this call")
                 return []
             else:
@@ -119,10 +110,6 @@ async def search_tavily(
     *,
     domains: list[str] | None = None,
 ) -> list[dict[str, Any]]:
-    """
-    Retrieve Arabic web evidence via Tavily using two complementary angles:
-    a fact-check phrasing and a broader official-source news phrasing.
-    """
     raw_query = re.sub(r"^تحقق\s*", "", query).strip()
     news_query = f"{raw_query} مصدر رسمي"