Initial commit

.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+kb/index/
+

README.md

@@ -0,0 +1,145 @@
+# ClaimCheck.AI — Agentic Fact Verification for Calls (IBM watsonx)
+
+**ClaimCheck.AI** is an agentic AI pipeline that turns meeting audio (Zoom/phone) into an evidence-backed report:
+1) **ASR Agent (IBM STT)** → transcript + timestamps  
+2) **Claim Extraction (watsonx.ai LLM)** → JSON claims  
+3) **Evidence Retrieval (watsonx.ai Embeddings + FAISS + optional Rerank)** → KB hits  
+4) **Verification (watsonx.ai LLM)** → supported/refuted/insufficient + citations  
+5) **Summarizer (watsonx.ai LLM)** → executive summary + action items
+
+## ✨ Why it matters
+High-stakes calls contain promises and metrics (SLA, compliance, finance). ClaimCheck.AI verifies statements against your **trusted KB** so decisions are grounded in facts—not memory.
+
+---
+
+## 🔧 Project structure
+
+```
+claim-check/
+├─ app/
+│  ├─ agents/
+│  │  ├─ claims.py            # Claim extractor (watsonx.ai Prompt Lab / LLM)
+│  │  ├─ retriever.py         # IBM embeddings + FAISS + optional rerank
+│  │  ├─ verifier.py          # LLM verdicts (supported/refuted/insufficient)
+│  │  └─ summarizer.py        # LLM executive summary + action items
+│  ├─ core/
+│  │  ├─ config.py            # env wiring (IBM base url, project, keys)
+│  │  └─ json_utils.py        # robust JSON extraction from LLM outputs
+│  ├─ schemas/                # pydantic models (Claim, Evidence, Verdict, CallReport)
+│  ├─ services/
+│  │  └─ asr.py               # IBM Speech to Text or Whisper (fallback)
+│  └─ main.py                 # FastAPI: /health, /process-audio, /process-transcript
+├─ kb/
+│  ├─ snippets.jsonl          # your knowledge base (facts; one JSON per line)
+│  └─ index/                  # FAISS index (auto-built)
+├─ data/audio/                # demo audio files
+├─ .env                       # local secrets (NOT committed)
+├─ .env.sample                # template for env vars (safe to commit)
+├─ requirements.txt
+└─ README.md
+```
+
+---
+
+## 🧪 Quick start
+
+### 1) Python env
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 2) Configure IBM (edit `.env`)
+Copy the sample and fill in values from your IBM Cloud / watsonx project.
+
+```bash
+cp .env.sample .env
+```
+
+**Required env keys:**
+```
+# IBM Core
+WATSONX_BASE_URL=https://us-south.ml.cloud.ibm.com
+WATSONX_PROJECT_ID=<your-watsonx-project-id>
+WATSONX_API_KEY=<your-ibm-cloud-api-key>
+IBM_API_VERSION=2023-05-29
+
+# Models
+IBM_EMBEDDINGS_MODEL_ID=ibm/granite-embedding-107m-multilingual   # 384-dim
+IBM_RERANK_MODEL_ID=ibm/slate-30m-english-rtrvr-v2                 # optional
+IBM_VERIFIER_MODEL_ID=ibm/granite-3-8b-instruct
+IBM_SUMMARY_MODEL_ID=ibm/granite-3-8b-instruct
+
+# Speech to Text (IBM)
+IBM_STT_URL=<your-ibm-stt-instance-url>   # e.g. https://api.us-south.speech-to-text.watson.cloud.ibm.com/instances/XXXX
+IBM_STT_APIKEY=<your-ibm-stt-api-key>
+
+# Whisper fallback (optional)
+WHISPER_MODEL_SIZE=base
+WHISPER_DEVICE=cpu
+WHISPER_COMPUTE_TYPE=int8
+```
+
+### 3) Seed the KB
+Put your facts in `kb/snippets.jsonl` (one JSON per line). Example:
+
+```jsonl
+{"doc_id":"uptime_q2_report","source":"Global Uptime Dashboard","snippet":"Q2 2025 uptime was 99.982% globally; LATAM outage lowered regional uptime to 99.965%.","metadata":{"quarter":"Q2","year":2025}}
+```
+
+If you change the KB, rebuild the index by deleting the `kb/index/` folder.
+
+### 4) Run the API
+```bash
+# macOS OpenMP fix (optional) + run
+KMP_DUPLICATE_LIB_OK=TRUE OMP_NUM_THREADS=1 uvicorn app.main:app --reload
+```
+
+### 5) Try it
+
+**Transcript path (no audio):**
+```bash
+curl -X POST http://127.0.0.1:8000/process-transcript   -H "Content-Type: application/json"   -d '{"text":"We achieved 99.99% uptime in Q2. P95 latency under 200 ms globally. Default retention is 30 days."}'
+```
+
+**Audio path (IBM STT):**
+```bash
+curl -X POST http://127.0.0.1:8000/process-audio   -F "file=@data/audio/demo_call.wav"
+```
+
+**Health:**
+```bash
+curl http://127.0.0.1:8000/health/ibm
+```
+
+---
+
+## 🧠 How it works (agentic)
+
+- **ASR Agent (IBM STT):** audio → timestamped segments (+ diarization)
+- **Claim Extractor (watsonx.ai):** segments → `{id, text, speaker, start, end}`
+- **Retriever (Embeddings + FAISS + Rerank):** claim → top KB snippets
+- **Verifier (watsonx.ai):** claim + evidence → verdict + rationale + citation_ids
+- **Summarizer (watsonx.ai):** executive summary + action items
+- **Output:** `CallReport` JSON; easy to render as PDF/HTML
+
+---
+
+## 🛡️ Notes on data & security
+- Do **not** commit `.env` or audio with sensitive content.  
+- Use IBM Cloud secrets manager / vault in production.  
+- All third-party calls are behind explicit env flags; the pipeline fails safe (insufficient) if evidence is missing.
+
+---
+
+## 🧰 Troubleshooting
+- **Embeddings 400** → ensure `version` query param, body includes `"inputs"` and `"model_id"`.  
+- **FAISS dim mismatch** → delete `kb/index/` after changing embedding model.  
+- **OpenMP error (macOS)** → set `KMP_DUPLICATE_LIB_OK=TRUE` and `OMP_NUM_THREADS=1`.  
+- **JSON parse errors** → we use a robust extractor; check server logs `[RAW OUTPUT]`.
+
+---
+
+## 📄 License
+MIT (or your choice). See `LICENSE`.

app/agents/claims.py

@@ -0,0 +1,24 @@
+# app/agents/claims.py
+from typing import List, Dict
+from app.schemas.claim import Claim
+from app.agents.ibm_client import run_claim_extractor
+
+def extract_claims(segments: List[Dict]) -> List[Claim]:
+    transcript = " ".join(s.get("text","") for s in segments).strip()
+    if not transcript:
+        return []
+    data = run_claim_extractor(transcript)
+    items = data.get("claims", [])
+    claims: List[Claim] = []
+    for i, c in enumerate(items):
+        text = (c.get("text") or "").strip()
+        if not text:
+            continue
+        claims.append(Claim(
+            id=f"c{i}",
+            text=text,
+            speaker=c.get("speaker"),
+            segment_idx=0,  # map to real segment later using start/end
+            confidence=float(c.get("confidence", 0.6))
+        ))
+    return claims

app/agents/ibm_client.py

@@ -0,0 +1,108 @@
+# app/agents/ibm_client.py
+import os, json, re, requests
+from typing import Dict, Any
+from app.core.config import WATSONX_BASE_URL, WATSONX_PROJECT
+from app.core.ibm_auth import ibm_iam_token  # we wrote this earlier
+
+GEN_URL = f"{WATSONX_BASE_URL}/ml/v1/text/generation?version=2023-05-29"
+MODEL_ID = os.getenv("IBM_CLAIM_EXTRACTOR_MODEL", "ibm/granite-3-8b-instruct")
+
+# Few-shot, strict-JSON prompt. We’ll append the runtime transcript at the end.
+PROMPT_TEMPLATE = r"""
+You extract factual claims from messy spoken transcripts.
+Return strict JSON with this shape:
+{
+  "claims": [
+    {"text": str, "speaker": str|null, "start": float, "end": float, "confidence": float}
+  ]
+}
+
+Guidelines:
+- A "claim" is a checkable factual assertion (metrics, quantities, time-bound facts).
+- Prefer sentences with numbers, percentages, dates, quantities, KPIs.
+- Split multiple claims in one sentence into separate objects.
+- If unsure about speaker or timestamps, set speaker=null and start/end=0.
+- Do NOT include opinions, greetings, or questions unless they state a checkable fact.
+- Output ONLY JSON. No prose.
+
+Input: We grew forty percent quarter over quarter in Q2. Customer churn fell to two percent. According to the CRM, Q2 growth was twelve percent. Churn stabilized at four percent in Q2.
+Output: {
+  "claims": [
+    {"text":"We grew 40% quarter over quarter in Q2","speaker":null,"start":0.0,"end":0.0,"confidence":0.55},
+    {"text":"Customer churn fell to 2%","speaker":null,"start":0.0,"end":0.0,"confidence":0.55},
+    {"text":"Q2 growth was 12%","speaker":null,"start":0.0,"end":0.0,"confidence":0.7},
+    {"text":"Churn stabilized at 4% in Q2","speaker":null,"start":0.0,"end":0.0,"confidence":0.7}
+  ]
+}
+
+Input: We expanded into three new regions this year. Our operating margin improved by five points since Q1.
+Output: {
+  "claims": [
+    {"text":"We expanded into 3 new regions this year","speaker":null,"start":0.0,"end":0.0,"confidence":0.6},
+    {"text":"Operating margin improved by 5 percentage points since Q1","speaker":null,"start":0.0,"end":0.0,"confidence":0.7}
+  ]
+}
+
+Input: {TRANSCRIPT}
+Output:
+""".strip()
+
+def _build_payload(transcript: str) -> Dict[str, Any]:
+    prompt = PROMPT_TEMPLATE.replace("{TRANSCRIPT}", transcript.strip())
+    return {
+        "input": prompt,
+        "parameters": {
+            "decoding_method": "greedy",
+            "max_new_tokens": 200,
+            "min_new_tokens": 0,
+            "repetition_penalty": 1.0,
+            # Stop when it tries to start another example
+            "stop_sequences": ["\n\nInput:", "\nInput:"]
+        },
+        "model_id": MODEL_ID,
+        "project_id": WATSONX_PROJECT,
+        # Keep moderations minimal; you can re-enable if your org requires it
+        "moderations": {
+            "hap": {"input": {"enabled": False}, "output": {"enabled": False}},
+            "pii": {"input": {"enabled": False}, "output": {"enabled": False}}
+        }
+    }
+
+def _post_generation(payload: Dict[str, Any]) -> str:
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {ibm_iam_token()}",
+    }
+    r = requests.post(GEN_URL, headers=headers, json=payload, timeout=90)
+    if r.status_code != 200:
+        raise RuntimeError(f"watsonx generation error: {r.status_code} {r.text}")
+    data = r.json()
+    # watsonx usually returns {"results":[{"generated_text":"..."}], ...}
+    txt = ""
+    if isinstance(data, dict) and "results" in data and data["results"]:
+        txt = data["results"][0].get("generated_text", "")
+    elif isinstance(data, dict) and "generated_text" in data:
+        txt = data["generated_text"]
+    return txt.strip()
+
+def _extract_json_block(text: str) -> Dict[str, Any]:
+    """
+    Try direct JSON parse; if that fails, find the first {...} block and parse it.
+    """
+    try:
+        return json.loads(text)
+    except Exception:
+        pass
+    m = re.search(r"\{.*\}", text, flags=re.DOTALL)
+    if not m:
+        return {"claims": []}
+    try:
+        return json.loads(m.group(0))
+    except Exception:
+        return {"claims": []}
+
+def run_claim_extractor(transcript: str) -> Dict[str, Any]:
+    payload = _build_payload(transcript)
+    out_text = _post_generation(payload)
+    return _extract_json_block(out_text)  # -> {"claims":[...]}

app/agents/retriever.py

@@ -0,0 +1,198 @@
+# app/agents/retriever.py
+from typing import List, Tuple, Dict
+import os, json, numpy as np, faiss, requests
+
+from app.schemas.claim import Claim
+from app.schemas.evidence import Evidence
+from app.core.config import WATSONX_BASE_URL as _BASE, WATSONX_PROJECT as _PROJECT, WATSONX_API_KEY as _APIKEY
+
+BASE_URL = (_BASE or "").rstrip("/")          # avoid //ml
+PROJECT_ID = _PROJECT
+API_KEY = _APIKEY
+EMB_MODEL_ID = os.getenv("IBM_EMBEDDINGS_MODEL_ID", "").strip()   # <-- REQUIRED
+RERANK_MODEL_ID = os.getenv("IBM_RERANK_MODEL_ID", "").strip()    # optional
+
+IDX_DIR   = "kb/index"
+IDX_PATH  = f"{IDX_DIR}/kb.index"
+META_PATH = f"{IDX_DIR}/kb_meta.json"
+SNIPPETS  = "kb/snippets.jsonl"
+
+# ---------- IBM helpers ----------
+_tok, _exp = None, 0
+def _ibm_token():
+    import time
+    global _tok, _exp
+    now = time.time()
+    if _tok and now < _exp - 60:
+        return _tok
+    r = requests.post(
+        "https://iam.cloud.ibm.com/identity/token",
+        data={
+            "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
+            "apikey": API_KEY
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=30
+    )
+    r.raise_for_status()
+    data = r.json(); _tok = data["access_token"]; _exp = now + 3000
+    return _tok
+
+def _assert_ibm_ready():
+    missing = []
+    if not BASE_URL: missing.append("WATSONX_BASE_URL")
+    if not PROJECT_ID: missing.append("WATSONX_PROJECT_ID")
+    if not API_KEY: missing.append("WATSONX_API_KEY")
+    if not EMB_MODEL_ID: missing.append("IBM_EMBEDDINGS_MODEL_ID")
+    if missing:
+        raise RuntimeError(f"IBM embeddings not configured. Missing: {', '.join(missing)}")
+
+VERSION = os.getenv("IBM_API_VERSION", "2023-05-29")
+BASE_URL = BASE_URL.rstrip("/")
+
+def _ibm_embed(texts: list[str]) -> np.ndarray:
+    url = f"{BASE_URL}/ml/v1/text/embeddings?version={VERSION}"
+    hdr = {"Authorization": f"Bearer {_ibm_token()}",
+           "Accept": "application/json",
+           "Content-Type": "application/json"}
+    payload = {
+        "inputs": texts,                  # NOTE: plural
+        "model_id": EMB_MODEL_ID,
+        "project_id": PROJECT_ID
+    }
+    r = requests.post(url, headers=hdr, json=payload, timeout=60)
+    r.raise_for_status()
+    j = r.json()
+
+    # Accept either "data": [{"embedding": [...]}, ...]  OR
+    # "results": [{"embedding": [...]}, ...]
+    items = None
+    if isinstance(j, dict):
+        if "data" in j:
+            items = j["data"]
+        elif "results" in j:
+            items = j["results"]
+
+    if not items or not isinstance(items, list):
+        # Print full response once to help diagnose, then fall back
+        print(f"[retriever] Unexpected embeddings schema: {j}")
+        raise RuntimeError("Embeddings response missing 'data'/'results'")
+
+    vecs = np.asarray([it.get("embedding") for it in items], dtype=np.float32)
+    if vecs.ndim != 2:
+        print(f"[retriever] Bad embedding shapes: {vecs.shape}")
+        raise RuntimeError("Embeddings returned with wrong dimensionality")
+    # normalize for cosine/IP
+    vecs /= (np.linalg.norm(vecs, axis=1, keepdims=True) + 1e-12)
+    return vecs
+
+
+def _ibm_rerank(query: str, docs: list[dict], top_n: int = 5) -> list[dict]:
+    if not docs or not RERANK_MODEL_ID:
+        return docs
+    url = f"{BASE_URL}/ml/v1/text/rerank?version={VERSION}"
+    hdr = {"Authorization": f"Bearer {_ibm_token()}",
+           "Accept":"application/json","Content-Type":"application/json"}
+    payload = {
+        "input": {
+            "query": query,
+            "passages": [{"id": d["doc_id"], "text": d["snippet"]} for d in docs]
+        },
+        "model_id": RERANK_MODEL_ID,               # <-- required
+        "project_id": PROJECT_ID,
+        "top_n": min(top_n, len(docs))
+    }
+    r = requests.post(url, headers=hdr, json=payload, timeout=60)
+    if r.status_code != 200:
+        return docs
+    order = r.json().get("results", [])
+    id2doc = {d["doc_id"]: d for d in docs}
+    out = []
+    for it in order:
+        d = id2doc.get(it["id"])
+        if d:
+            d = {**d, "score": it.get("relevance", d.get("score", d.get("score", 0.0)))}
+            out.append(d)
+    return out or docs
+
+
+# ---------- Local embeddings fallback ----------
+_embedder = None
+def _local_embed(texts: list[str]) -> np.ndarray:
+    global _embedder
+    if _embedder is None:
+        from sentence_transformers import SentenceTransformer
+        _embedder = SentenceTransformer("all-MiniLM-L6-v2")
+    vecs = _embedder.encode(texts, normalize_embeddings=True)
+    return np.asarray(vecs, dtype=np.float32)
+
+def _use_ibm():
+    # use IBM only if all pieces exist
+    return bool(BASE_URL and PROJECT_ID and API_KEY and EMB_MODEL_ID)
+
+def _load_snippets() -> list[dict]:
+    docs = []
+    with open(SNIPPETS) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                docs.append(json.loads(line))
+    if not docs:
+        raise RuntimeError("No KB snippets found. Please populate kb/snippets.jsonl")
+    return docs
+
+def _build_or_load():
+    os.makedirs(IDX_DIR, exist_ok=True)
+    if os.path.exists(IDX_PATH) and os.path.exists(META_PATH):
+        return faiss.read_index(IDX_PATH), json.load(open(META_PATH))
+
+    docs = _load_snippets()
+    texts = [d["snippet"] for d in docs]
+    try:
+        embs = _ibm_embed(texts) if _use_ibm() else _local_embed(texts)
+    except Exception as e:
+        # Fallback to local embeddings if IBM call fails, but surface why
+        print(f"[retriever] IBM embeddings failed, falling back to local: {e}")
+        embs = _local_embed(texts)
+
+    index = faiss.IndexFlatIP(embs.shape[1])
+    index.add(embs.astype("float32"))
+    faiss.write_index(index, IDX_PATH)
+    json.dump(docs, open(META_PATH, "w"))
+    return index, docs
+
+def _search(query_text: str, k: int = 8) -> list[dict]:
+    index, meta = _build_or_load()
+    try:
+        q = _ibm_embed([query_text]) if _use_ibm() else _local_embed([query_text])
+    except Exception as e:
+        print(f"[retriever] IBM query embed failed, using local: {e}")
+        q = _local_embed([query_text])
+    D, I = index.search(q.astype("float32"), k)
+    hits = []
+    for rank, idx in enumerate(I[0].tolist()):
+        d = meta[idx]
+        hits.append({
+            "doc_id": d["doc_id"], "source": d.get("source","KB"),
+            "snippet": d["snippet"], "score": float(D[0][rank]),
+            "metadata": d.get("metadata", {})
+        })
+    try:
+        hits = _ibm_rerank(query_text, hits, top_n=5) if _use_ibm() else hits
+    except Exception as e:
+        print(f"[retriever] IBM rerank failed, using original hits: {e}")
+    return hits
+
+def retrieve_evidence_for_claims(claims: List[Claim], k: int = 8) -> Tuple[List[Claim], Dict[str, List[Evidence]]]:
+    claim_to_evidence: Dict[str, List[Evidence]] = {}
+    for cl in claims:
+        hits = _search(cl.text, k=k)
+        ev_list = [
+            Evidence(
+                doc_id=h["doc_id"], source=h["source"], snippet=h["snippet"],
+                score=h["score"], metadata=h["metadata"]
+            )
+            for h in hits[:5]
+        ]
+        claim_to_evidence[cl.id] = ev_list
+    return claims, claim_to_evidence

app/agents/summarizer.py

@@ -0,0 +1,143 @@
+# app/agents/summarizer.py
+from __future__ import annotations
+import os, json, requests, re
+from typing import List, Dict, Any
+from app.schemas.report import CallReport
+from app.schemas.claim import Claim
+from app.schemas.evidence import Evidence
+from app.schemas.verdict import Verdict
+from app.core.config import WATSONX_BASE_URL, WATSONX_PROJECT, WATSONX_API_KEY
+from app.core.json_utils import extract_json_obj
+
+VERSION = os.getenv("IBM_API_VERSION", "2023-05-29")
+MODEL_ID = os.getenv("IBM_SUMMARY_MODEL_ID", "ibm/granite-3-8b-instruct")
+
+def _iam_token() -> str:
+    r = requests.post(
+        "https://iam.cloud.ibm.com/identity/token",
+        data={"grant_type":"urn:ibm:params:oauth:grant-type:apikey","apikey":WATSONX_API_KEY},
+        headers={"Content-Type":"application/x-www-form-urlencoded"},
+        timeout=30
+    )
+    r.raise_for_status()
+    return r.json()["access_token"]
+
+_JSON = re.compile(r"\{[\s\S]*\}\s*$")
+
+
+# Replace _safe_json with:
+def _safe_json(s: str) -> dict:
+    return extract_json_obj(s)
+
+# ---- Prompt for structured output ----
+PROMPT = """You are a precise meeting summarizer for sales/stakeholder calls.
+Given transcript segments, normalized claims, and their verification labels, produce a concise executive summary.
+
+Return STRICT JSON only with:
+{
+  "call_summary": "string, <= 6 sentences, neutral, factual",
+  "action_items": ["string", "..."]            // 1-6 bullets, imperative
+}
+
+Guidelines:
+- Emphasize mismatches between stated claims and evidence.
+- Mention concrete metrics (%, $, dates) when present.
+- Avoid fluff and opinions; be concise and factual.
+
+Segments (JSON):
+{SEGMENTS_JSON}
+
+Claims (JSON):
+{CLAIMS_JSON}
+
+Verdicts (JSON):
+{VERDICTS_JSON}
+
+Now return JSON only:
+"""
+
+# ---- Public API ----
+def make_report(
+    segments: List[Dict[str, Any]],
+    claims: List[Claim],
+    evidence_flat: List[Evidence],
+    verdicts: List[Verdict],
+) -> CallReport:
+    """
+    Build a CallReport:
+      - call_summary + action_items from IBM LLM
+      - claim_table from verdicts (+ best evidence id)
+    """
+    # ---- Prepare claim_table from verdicts
+    # Map claim_id -> claim text
+    id2claim = {c.id: c.text for c in claims}
+    claim_table: List[Dict[str, Any]] = []
+    for v in verdicts:
+        claim_text = id2claim.get(v.claim_id, "")
+        row = {
+            "claim": claim_text,
+            "status": v.label.capitalize(),
+            "evidence_source": v.best_evidence_id or ""
+        }
+        claim_table.append(row)
+
+    # ---- Try IBM Granite for summary/action items
+    call_summary = ""
+    action_items: List[str] = []
+    try:
+        tok = _iam_token()
+        url = f"{WATSONX_BASE_URL.rstrip('/')}/ml/v1/text/generation?version={VERSION}"
+        headers = {
+            "Authorization": f"Bearer {tok}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        body = {
+            "input": PROMPT \
+                .replace("{SEGMENTS_JSON}", json.dumps(segments, ensure_ascii=False)) \
+                .replace("{CLAIMS_JSON}", json.dumps([{"id": c.id, "text": c.text} for c in claims], ensure_ascii=False)) \
+                .replace("{VERDICTS_JSON}", json.dumps([{
+                    "claim_id": v.claim_id,
+                    "label": v.label,
+                    "confidence": v.confidence,
+                    "best_evidence_id": v.best_evidence_id,
+                    "rationale": v.rationale
+                } for v in verdicts], ensure_ascii=False)),
+            "model_id": MODEL_ID,
+            "project_id": WATSONX_PROJECT,
+            "parameters": {
+                "decoding_method": "greedy",
+                "temperature": 0.0,
+                "max_new_tokens": 300,
+                "min_new_tokens": 0,
+                "repetition_penalty": 1.0
+            }
+        }
+        r = requests.post(url, headers=headers, json=body, timeout=120)
+        r.raise_for_status()
+        out = r.json()
+        gen = (out.get("results") or [{}])[0].get("generated_text", "")
+        parsed = _safe_json(gen)
+        call_summary = (parsed.get("call_summary") or "").strip()
+        action_items = parsed.get("action_items") or []
+        if not isinstance(action_items, list):
+            action_items = [str(action_items)]
+    except Exception as e:
+        # Fallback: extract a terse summary from first few segments
+        print(f"[summarizer] watsonx generation failed: {e}")
+        texts = [s.get("text","") for s in segments if s.get("text")]
+        joined = " ".join(texts)[:450].strip()
+        call_summary = (joined + "…") if joined else ""
+        if not action_items:
+            action_items = ["Review claims vs. evidence and confirm metrics in source-of-truth."]
+
+    # ---- Build CallReport dataclass (schema)
+    report = CallReport(
+        call_summary=call_summary,
+        claim_table=claim_table,
+        action_items=action_items,
+        claims=claims,
+        verdicts=verdicts,
+        evidence=evidence_flat
+    )
+    return report

app/agents/verifier.py

@@ -0,0 +1,180 @@
+# app/agents/verifier.py
+from __future__ import annotations
+import os, json, re, requests
+from typing import List, Dict
+from app.schemas.claim import Claim
+from app.schemas.evidence import Evidence
+from app.schemas.verdict import Verdict
+from app.core.config import WATSONX_BASE_URL, WATSONX_PROJECT, WATSONX_API_KEY
+from app.core.json_utils import extract_json_obj
+
+
+VERSION = os.getenv("IBM_API_VERSION", "2023-05-29")
+MODEL_ID = os.getenv("IBM_VERIFIER_MODEL_ID", "ibm/granite-3-8b-instruct")
+# ---- IAM helper ----
+def _iam_token() -> str:
+    r = requests.post(
+        "https://iam.cloud.ibm.com/identity/token",
+        data={
+            "grant_type": "urn:ibm:params:oauth:grant-type:apikey",
+            "apikey": WATSONX_API_KEY,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=30,
+    )
+    r.raise_for_status()
+    return r.json()["access_token"]
+
+
+# Strengthen the prompt header:
+PROMPT = """You are a precise fact verifier.
+Return STRICT JSON ONLY. Your first character MUST be '{' and your last character MUST be '}'.
+Schema:
+{
+  "verdicts": [
+    {"claim_id": "string", "label": "supported|refuted|insufficient", "confidence": 0.0, "citation_ids": ["doc_id", "..."], "rationale": "string"}
+  ]
+}
+# No extra text, no markdown, no backticks.
+
+Rules:
+- "supported" if at least one evidence snippet directly supports the claim.
+- "refuted" if any evidence directly contradicts the claim.
+- "insufficient" if evidence is not enough to decide.
+- Cite relevant evidence doc_ids in "citation_ids".
+- Keep "rationale" ≤ 2 sentences.
+
+Claims (JSON):
+{CLAIMS_JSON}
+
+Evidence catalog (doc_id -> snippet) as JSON:
+{EVIDENCE_JSON}
+
+Output JSON:
+"""
+
+# Replace _safe_json with:
+def _safe_json(s: str) -> dict:
+    return extract_json_obj(s)
+
+# In _post_generation() keep as-is, but add debug preview if parse fails:
+def _post_generation(prompt: str) -> dict:
+    url = f"{WATSONX_BASE_URL.rstrip('/')}/ml/v1/text/generation?version={VERSION}"
+    tok = _iam_token()
+    headers = {
+        "Authorization": f"Bearer {tok}",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    body = {
+        "input": prompt,
+        "model_id": MODEL_ID,
+        "project_id": WATSONX_PROJECT,
+        "parameters": {
+            "decoding_method": "greedy",
+            "max_new_tokens": 400,
+            "min_new_tokens": 0,
+            "repetition_penalty": 1.0,
+            "temperature": 0.0,
+        },
+    }
+    r = requests.post(url, headers=headers, json=body, timeout=120)
+    r.raise_for_status()
+    out = r.json()
+    results = out.get("results") or []
+    text = (results[0] or {}).get("generated_text", "") if results else ""
+    if not text:
+        raise RuntimeError(f"Empty generation response: {out}")
+    try:
+        return _safe_json(text)
+    except Exception as e:
+        print("[verifier] RAW OUTPUT >>>", text[:1000])
+        raise
+
+
+def verify(claims: List[Claim], evidence_map: Dict[str, List[Evidence]]) -> List[Verdict]:
+    """
+    claims: list of Claim (must have .id and .text)
+    evidence_map: claim_id -> List[Evidence] (must have .doc_id, .snippet)
+    returns: List[Verdict]
+    """
+    # 1) Flatten evidence to a doc_id -> snippet map (only those we surfaced)
+    doc_catalog: Dict[str, str] = {}
+    for lst in evidence_map.values():
+        for e in lst:
+            # Don't overwrite if duplicate doc_ids appear across claims
+            doc_catalog.setdefault(e.doc_id, e.snippet)
+
+    # 2) Minimal claims JSON for the LLM
+    claims_json = [{"id": c.id, "text": c.text} for c in claims]
+
+    # 3) Render prompt
+    prompt = PROMPT.replace("{CLAIMS_JSON}", json.dumps(claims_json, ensure_ascii=False)) \
+                   .replace("{EVIDENCE_JSON}", json.dumps(doc_catalog, ensure_ascii=False))
+
+    # 4) Call watsonx
+    try:
+        parsed = _post_generation(prompt)
+    except Exception as e:
+        # Fallback: everything "insufficient"
+        print(f"[verifier] generation failed: {e}")
+        return [
+            Verdict(
+                claim_id=c.id,
+                label="insufficient",
+                confidence=0.4,
+                best_evidence_id="",
+                rationale="Verifier offline; defaulting to insufficient."
+            ) for c in claims
+        ]
+
+    # 5) Validate + convert to Verdict[]
+    out: List[Verdict] = []
+    allowed = {"supported", "refuted", "insufficient"}
+    items = parsed.get("verdicts", [])
+    # Build a quick lookup of top evidence per claim (by retriever score) as tiebreaker
+    top_ev: Dict[str, str] = {}
+    for c in claims:
+        evs = evidence_map.get(c.id, [])
+        best = max(evs, key=lambda e: e.score, default=None)
+        top_ev[c.id] = best.doc_id if best else ""
+
+    for it in items:
+        cid = it.get("claim_id", "")
+        label = (it.get("label") or "").lower()
+        conf = float(it.get("confidence", 0.5))
+        cites = it.get("citation_ids") or []
+        rationale = it.get("rationale") or ""
+
+        if label not in allowed:
+            label = "insufficient"
+
+        # Choose best_evidence_id:
+        best_id = ""
+        for d in cites:
+            if d in doc_catalog:
+                best_id = d
+                break
+        if not best_id:
+            best_id = top_ev.get(cid, "")
+
+        out.append(Verdict(
+            claim_id=cid,
+            label=label,
+            confidence=conf,
+            best_evidence_id=best_id,
+            rationale=rationale[:300]
+        ))
+
+    # Ensure every claim has a verdict
+    have = {v.claim_id for v in out}
+    for c in claims:
+        if c.id not in have:
+            out.append(Verdict(
+                claim_id=c.id,
+                label="insufficient",
+                confidence=0.4,
+                best_evidence_id=top_ev.get(c.id, ""),
+                rationale="No explicit verdict returned; marking as insufficient."
+            ))
+    return out

app/core/config.py

@@ -0,0 +1,11 @@
+# app/core/config.py
+import os
+from dotenv import load_dotenv
+load_dotenv()
+
+WHISPER_COMPUTE_TYPE = os.getenv("WHISPER_COMPUTE_TYPE", "")
+WHISPER_DEVICE = os.getenv("WHISPER_DEVICE", "")
+WHISPER_MODEL_SIZE = os.getenv("WHISPER_MODEL_SIZE", "")
+WATSONX_BASE_URL = os.getenv("WATSONX_BASE_URL", "")
+WATSONX_PROJECT  = os.getenv("WATSONX_PROJECT_ID", "")
+WATSONX_API_KEY  = os.getenv("WATSONX_API_KEY", "")

app/core/ibm_auth.py

@@ -0,0 +1,20 @@
+# app/core/ibm_auth.py
+import requests, time, os
+from app.core.config import WATSONX_API_KEY
+
+_iam = {"tok": None, "exp": 0}
+
+def ibm_iam_token():
+    now = time.time()
+    if _iam["tok"] and now < _iam["exp"] - 60:
+        return _iam["tok"]
+    r = requests.post(
+        "https://iam.cloud.ibm.com/identity/token",
+        data={"grant_type":"urn:ibm:params:oauth:grant-type:apikey","apikey":WATSONX_API_KEY},
+        headers={"Content-Type":"application/x-www-form-urlencoded"}
+    )
+    r.raise_for_status()
+    tok = r.json()["access_token"]
+    _iam["tok"] = tok
+    _iam["exp"] = now + 3000  # ~50 min
+    return tok

app/core/ibm_sanity.py

@@ -0,0 +1,49 @@
+# app/core/ibm_sanity.py
+import os, requests, json, numpy as np
+from app.core.config import WATSONX_BASE_URL, WATSONX_PROJECT, WATSONX_API_KEY
+
+VERSION = os.getenv("IBM_API_VERSION", "2023-05-29")
+EMB = os.getenv("IBM_EMBEDDINGS_MODEL_ID", "")
+CLAIM = os.getenv("IBM_CLAIM_MODEL_ID", "")
+VERIFY = os.getenv("IBM_VERIFIER_MODEL_ID", "")
+
+def _iam_token() -> str:
+    r = requests.post(
+        "https://iam.cloud.ibm.com/identity/token",
+        data={"grant_type":"urn:ibm:params:oauth:grant-type:apikey","apikey":WATSONX_API_KEY},
+        headers={"Content-Type":"application/x-www-form-urlencoded"},
+        timeout=30
+    )
+    r.raise_for_status()
+    return r.json()["access_token"]
+
+def sanity_embeddings():
+    tok = _iam_token()
+    r = requests.post(
+        f"{WATSONX_BASE_URL.rstrip('/')}/ml/v1/text/embeddings?version={VERSION}",
+        headers={"Authorization":f"Bearer {tok}","Accept":"application/json","Content-Type":"application/json"},
+        json={"inputs":["probe"],"model_id":EMB,"project_id":WATSONX_PROJECT},
+        timeout=60,
+    )
+    r.raise_for_status()
+    j = r.json()
+    items = j.get("data") or j.get("results") or []
+    dim = len(items[0]["embedding"])
+    return {"ok": True, "dim": dim}
+
+def sanity_generation(model_id: str, prompt: str):
+    tok = _iam_token()
+    r = requests.post(
+        f"{WATSONX_BASE_URL.rstrip('/')}/ml/v1/text/generation?version={VERSION}",
+        headers={"Authorization":f"Bearer {tok}","Accept":"application/json","Content-Type":"application/json"},
+        json={
+            "input": prompt,
+            "model_id": model_id,
+            "project_id": WATSONX_PROJECT,
+            "parameters": {"decoding_method":"greedy","max_new_tokens":64}
+        },
+        timeout=90,
+    )
+    r.raise_for_status()
+    txt = (r.json().get("results") or [{}])[0].get("generated_text","")
+    return {"ok": True, "preview": txt[:120]}

app/core/json_utils.py

@@ -0,0 +1,48 @@
+# app/core/json_utils.py
+from __future__ import annotations
+import json, re
+
+# Fast path: last {...} block
+_LAST_JSON = re.compile(r"\{[\s\S]*\}\s*$")
+
+def extract_json_obj(text: str) -> dict:
+    s = text.strip()
+    # 1) Try last-JSON regex (often enough)
+    m = _LAST_JSON.search(s)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except Exception:
+            pass
+
+    # 2) Balanced-brace scan: find the largest valid JSON object
+    best = None
+    stack = 0
+    start = None
+    for i, ch in enumerate(s):
+        if ch == '{':
+            if stack == 0:
+                start = i
+            stack += 1
+        elif ch == '}':
+            if stack > 0:
+                stack -= 1
+                if stack == 0 and start is not None:
+                    candidate = s[start:i+1]
+                    try:
+                        obj = json.loads(candidate)
+                        best = obj  # keep last valid (usually the largest)
+                    except Exception:
+                        pass
+    if best is not None:
+        return best
+
+    # 3) Try to strip common wrappers like code fences
+    s2 = s.strip("` \n\t")
+    try:
+        return json.loads(s2)
+    except Exception:
+        pass
+
+    # 4) Give up with a readable error
+    raise ValueError("Could not extract JSON object from model text")

app/core/orchestrator.py

@@ -0,0 +1,42 @@
+# app/core/orchestrator.py
+from typing import Optional, List, Dict, Any
+from app.schemas.report import CallReport
+from app.schemas.claim import Claim
+from app.schemas.evidence import Evidence
+from app.schemas.verdict import Verdict
+from app.services.asr import transcribe
+from app.agents.claims import extract_claims
+from app.agents.retriever import retrieve_evidence_for_claims
+from app.agents.verifier import verify
+from app.agents.summarizer import make_report
+import os
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+os.environ.setdefault("OMP_NUM_THREADS", "1")
+
+
+def process_call(audio_path: Optional[str] = None, transcript: Optional[str] = None) -> CallReport:
+    print("[orchestrator] START")
+
+    segments = transcribe(audio_path) if audio_path else [
+        {"start":0.0,"end":0.0,"speaker":"A","text": transcript or ""}]
+
+    # 2) Claim extraction (IBM)
+    claims: List[Claim] = extract_claims(segments)
+    print(f"[orchestrator] Claims extracted: {len(claims)}")
+    if not claims:
+        print("[orchestrator] No claims found; building minimal report.")
+        return make_report(segments, [], [], [])
+
+    # 3) Evidence retrieval (IBM embeddings + optional rerank)
+    claims, evmap = retrieve_evidence_for_claims(claims, k=8)
+    ev_count = sum(len(v) for v in evmap.values())
+    evidence_flat = [e for lst in evmap.values() for e in lst]
+
+    verdicts: List[Verdict] = verify(claims, evmap)
+    print(f"[orchestrator] Verifier produced {len(verdicts)} verdicts")
+
+    # 5) Summarize
+    report = make_report(segments, claims, evidence_flat, verdicts)
+    print(report.call_summary)
+    print("[orchestrator] DONE")
+    return report

app/main.py

@@ -0,0 +1,37 @@
+# app/main.py
+import os
+from fastapi import FastAPI
+from fastapi import Body
+from fastapi import UploadFile, File
+from app.core.orchestrator import process_call
+from app.core.ibm_sanity import sanity_embeddings, sanity_generation
+
+app = FastAPI(title="ClaimCheck")
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "ClaimCheck"}
+
+@app.get("/health/ibm")
+def health_ibm():
+    emb = sanity_embeddings()
+    claim = sanity_generation(os.getenv("IBM_CLAIM_MODEL_ID",""), "Say OK")
+    verify = sanity_generation(os.getenv("IBM_VERIFIER_MODEL_ID",""), "Say OK")
+    return {"embeddings": emb, "claim_gen": claim, "verify_gen": verify}
+
+
+@app.post("/process-transcript")
+def process_transcript(text: str = Body(..., embed=True)):
+    """
+    Accepts raw transcript text and returns a CallReport JSON.
+    For now, the orchestrator returns a dummy report (no AI).
+    """
+    report = process_call(transcript=text)
+    return report
+
+@app.post("/process-audio")
+async def process_audio(file: UploadFile = File(...)):
+    path = f"data/audio/{file.filename}"
+    with open(path, "wb") as f:
+        f.write(await file.read())
+    return process_call(audio_path=path)

app/schemas/claim.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+from typing import List, Optional
+class Claim(BaseModel):
+    id: str
+    text: str
+    speaker: Optional[str] = None
+    segment_idx: Optional[int] = None
+    entities: List[str] = []
+    confidence: float = 0.0

app/schemas/evidence.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+from typing import Dict
+class Evidence(BaseModel):
+    doc_id: str
+    source: str
+    snippet: str
+    score: float
+    metadata: Dict[str, str] = {}

app/schemas/report.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+from typing import List
+from .claim import Claim
+from .evidence import Evidence
+from .verdict import Verdict
+
+class CallReport(BaseModel):
+    call_summary: str
+    claim_table: List[dict]
+    action_items: List[str] = []
+    claims: List[Claim]
+    verdicts: List[Verdict]
+    evidence: List[Evidence]

app/schemas/verdict.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+class Verdict(BaseModel):
+    claim_id: str
+    label: str           # supported | refuted | insufficient
+    confidence: float
+    best_evidence_id: str
+    rationale: str

app/services/asr.py

@@ -0,0 +1,42 @@
+from typing import List, Dict
+from faster_whisper import WhisperModel
+import os
+
+# Load environment variables
+WHISPER_MODEL_SIZE = os.getenv("WHISPER_MODEL_SIZE", "base")
+WHISPER_DEVICE = os.getenv("WHISPER_DEVICE", "cpu")
+WHISPER_COMPUTE_TYPE = os.getenv("WHISPER_COMPUTE_TYPE", "int8")
+
+_whisper = WhisperModel(
+    WHISPER_MODEL_SIZE,
+    device=WHISPER_DEVICE,
+    compute_type=WHISPER_COMPUTE_TYPE
+)
+
+def transcribe(audio_path: str) -> List[Dict]:
+    """
+    Transcribe an audio file using faster-whisper and return our standard
+    list of segments: [{start, end, speaker, text}].
+    """
+    # beam_size=1 is fastest; raise for a bit more accuracy.
+    segments, info = _whisper.transcribe(
+        audio_path,
+        language="en",         
+        vad_filter=True,      
+        beam_size=1
+    )
+
+    out = []
+    for seg in segments:
+        out.append({
+            "start": float(seg.start),
+            "end": float(seg.end),
+            "speaker": "A",    # no diarization here; we can add later
+            "text": seg.text.strip()
+        })
+
+    # If there were no segments (edge case), return a single empty segment
+    if not out:
+        out = [{"start": 0.0, "end": 0.0, "speaker": "A", "text": ""}]
+
+    return out

data/audio/call_script.txt

@@ -0,0 +1,7 @@
+A: Good morning! You’re interested in our Gold Credit Card? It’s got a 17 percent APR and no annual fee. Really popular right now.
+C: That sounds good. Any other fees I should know about?
+A: No, not really. For personal loans we sometimes have a fee, but that’s usually negligible.
+C: Also, how long do you keep call recordings?
+A: Just about 30 days, then they’re gone.
+C: Great. And I’m also thinking about a small investment product you offer. Any risks?
+A: No major risks, it’s a stable product.

kb/snippets.jsonl

@@ -0,0 +1,19 @@
+{"doc_id":"uptime_q2_report","source":"Global Uptime Dashboard","snippet":"Q2 2025 uptime was 99.982% globally, with LATAM experiencing a 3-hour outage on May 14, lowering uptime in that region to 99.965%.","metadata":{"type":"uptime","quarter":"Q2","year":2025}}
+{"doc_id":"latency_q2_report","source":"Performance Metrics","snippet":"P95 latency in Q2 2025 averaged 198ms globally, but APAC had spikes to 250ms during peak hours in June.","metadata":{"type":"latency","quarter":"Q2","year":2025}}
+{"doc_id":"uptime_incident_apac","source":"Incident Report","snippet":"Outage in APAC data center on June 21 lasted 45 minutes and impacted 12% of customer requests.","metadata":{"type":"incident","date":"2025-06-21"}}
+{"doc_id":"uptime_contract","source":"SLA Agreement","snippet":"Service provider guarantees 99.99% uptime per month; failure results in service credits.","metadata":{"type":"sla","effective_date":"2024-05-01"}}
+{"doc_id":"uptime_customer_feedback","source":"Customer Survey","snippet":"Several enterprise customers in LATAM reported downtime exceeding 2 hours in May 2025.","metadata":{"type":"feedback","month":"2025-05"}}
+
+{"doc_id":"relief_payouts","source":"Disaster Relief Payment System","snippet":"As of July 20, 2025, 87% of registered affected citizens had received payments. Delays remain for 13% due to missing bank details or unresolved eligibility verification.","metadata":{"type":"payout_report","date":"2025-07-20"}}
+{"doc_id":"relief_registry","source":"National Citizen Registry","snippet":"Registry lists 142,300 citizens marked as affected; payment records show 124,801 completed transfers.","metadata":{"type":"registry_report","date":"2025-07-20"}}
+{"doc_id":"relief_remote_area_issues","source":"NGO Field Report","snippet":"Field agents in remote areas reported difficulty verifying identities, delaying payouts to hundreds of citizens.","metadata":{"type":"field_report","date":"2025-07-18"}}
+{"doc_id":"relief_policy_doc","source":"Government Policy Document","snippet":"All affected citizens are eligible for relief payments; disbursement is to be completed within 30 days of disaster declaration.","metadata":{"type":"policy","effective_date":"2025-06-01"}}
+{"doc_id":"relief_complaints","source":"Public Complaints Hotline","snippet":"Calls received in late July indicate some citizens in mountain regions still have not received payment.","metadata":{"type":"complaint","month":"2025-07"}}
+
+{"doc_id":"aml_yearly_trend","source":"Annual Compliance Review 2024","snippet":"Overall AML coverage rate improved from 92% in 2023 to 97% in 2024.","metadata":{"type":"trend","year":2024}}
+{"doc_id":"uptime_yearly_trend","source":"Annual Service Report 2024","snippet":"Annual uptime for 2024 was 99.975% with improvements in redundancy and failover systems.","metadata":{"type":"trend","year":2024}}
+{"doc_id":"relief_previous_disaster","source":"Relief Audit 2024","snippet":"In the 2024 floods, 99% of affected citizens were compensated within 45 days.","metadata":{"type":"historical","year":2024}}
+
+{"doc_id":"aml_press_release","source":"Bank Press Release","snippet":"We are proud to announce we achieved 100% AML screening compliance for all transactions in Q2 2025.","metadata":{"type":"press","quarter":"Q2","year":2025}}
+{"doc_id":"uptime_press_release","source":"Cloud Provider Blog","snippet":"Our infrastructure delivered 99.99% uptime globally with record-low latency this quarter.","metadata":{"type":"press","quarter":"Q2","year":2025}}
+{"doc_id":"relief_press_release","source":"Govt News Bulletin","snippet":"The government has successfully disbursed relief payments to all citizens affected by the July disaster.","metadata":{"type":"press","date":"2025-07-21"}}

requirements.txt

@@ -0,0 +1,5 @@
+fastapi
+uvicorn[standard]
+pydantic>=2
+python-dotenv
+requests