README.md

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

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.

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:

{"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

# 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):

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):

curl -X POST http://127.0.0.1:8000/process-audio   -F "file=@data/audio/demo_call.wav"

Health:

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.