BondCheck: an agentic AI platform for job-bond transparency

AI agents that read offer letters, extract and verify job-bond terms, and warn freshers before they sign.

Seven specialised agents turn anonymously uploaded offer letters into a verified, evidence-backed, searchable database of bond terms, answer students' questions with citations, and proactively alert them before placement drives.

Agents	Orchestrator · Privacy · Extraction · Verification · Q&A · Monitor · Alert
Stack	LangGraph · Claude API (Haiku + Sonnet) · FastAPI · PostgreSQL / SQLite · Next.js 16 + Tailwind 4 + Framer Motion
Runs on	Kubernetes (load-balanced API replicas, autoscaling, Gateway API), or Vercel + Render. See k8s/README.md.
Runs without an API key	Yes. A deterministic offline engine drives the same agent graph, so everything works locally out of the box.

All demo companies and people are fictional. BondCheck shows information reported in uploaded documents and public sources. It is not legal advice.

---

Quick start

Backend (Python 3.12):

cd bondcheck
python -m venv .venv
.venv\Scripts\activate            # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env              # optional: add ANTHROPIC_API_KEY, DATABASE_URL, …
python -m db.seed                 # runs ~70 synthetic letters through the real agent pipeline
uvicorn api.main:app --port 8000  # API docs at http://localhost:8000/docs

Frontend (Node 20+):

cd bondcheck/frontend
npm install
cp .env.example .env.local        # NEXT_PUBLIC_API_URL=http://localhost:8000
npm run dev                       # http://localhost:3000

Moderator console: http://localhost:3000/admin (local token: dev-admin-token).

Tests and evaluation:

pytest -q                         # 42 tests: tools, agents, guardrails, API, multi-replica forwarding
python -m eval.run_eval           # writes eval/results.json + eval/report.md (shown on /how-it-works)

Modes

Setting	Effect
No ANTHROPIC_API_KEY	Offline rule engine for classification, PII detection and extraction; a deterministic planner for Q&A; web search disabled; scanned letters need Tesseract.
ANTHROPIC_API_KEY set	claude-haiku-4-5 classifies documents, double-checks PII and transcribes scans; claude-sonnet-5-5 extracts fields (structured JSON output), answers questions in a tool-use loop and researches public sources with web search. Sonnet calls opt in to server-side refusal fallbacks.
No DATABASE_URL	Local SQLite at data/bondcheck.db (auto-created and seeded on first API start).
DATABASE_URL set	PostgreSQL (Neon/Supabase). Run db/schema.sql, then optionally db/seed.sql. Create the read-only Q&A role from the bottom of schema.sql and put it in DATABASE_URL_READONLY.

---

Architecture

                        ┌──────────────────────────────┐
   Events ─────────────▶│      ORCHESTRATOR AGENT      │  LangGraph state graph:
   • New upload         │  plans, routes, retries (≤2), │  routing, retries, token budget,
   • Student question   │  budgets, escalates to humans │  interrupt() for human input
   • Scheduled job      └──────────────┬───────────────┘
   ┌─────────────────┬─────────────────┼──────────────────┬─────────────────┐
   ▼                 ▼                 ▼                  ▼                 ▼
 PRIVACY ──▶    EXTRACTION ──▶   VERIFICATION         Q&A AGENT        MONITOR ──▶ ALERT
 redact +       quote-verified    corroborate /        read-only SQL,   (daily)      (7 days before
 re-scan ×3     self-check loop   variant / conflict / exit-cost calc,               a drive)
                    │             outlier / new_company citations
                    ▼                   ▼
            uploader confirms     moderation queue        PostgreSQL + agent_runs log

Workflow A, upload. intake → [ocr] → classify → privacy → extraction ⟲ → [confirm: interrupt()] → verification → finalize (document deleted). Any step can route to reject (not an offer letter, PII left after 3 scans, unreadable) or escalate (failed after 2 retries, over the token budget). Every event streams to the UI as NDJSON.

Workflow B, question. The Q&A agent calls find_company, run_readonly_sql, calc_exit_cost and get_evidence, and must cite record IDs, upload counts and dates.

Workflow C, monitoring. The Monitor agent checks drives in the next 30 days for missing, stale or conflicting data, saves public findings as unverified records, and creates "data needed" requests. The Alert agent emails subscribers 7 days before a drive, and skips "no bond, high confidence" alerts unless the student opted in.

The self-verification loop (Extraction Agent)

1. Extract all 12 fields, each with a verbatim evidence quote.
2. verify_quote() confirms every quote exists in the (redacted) document, which catches made-up values.
3. Re-derive the value from the quote with deterministic normalisers (₹1.5 lakh → 150000, two (2) years → 24).
4. Check relevance and consistency: a probation clause isn't a bond, a salary isn't a penalty, "no bond" isn't a bond, a bond needs a period or a penalty.
5. Re-read just the failing section with the failure as feedback (max 2 rounds).
6. Drop anything whose quote can't be found; ask the uploader about the rest.

---

Evaluation (offline engine, 50 synthetic letters)

	Single-pass extraction	Agentic (self-check + re-read)	+ uploader confirmation
Field accuracy	88.5%	99.6%	100%
Hallucinated fields	22	0	—

This is the beginning of the README. Read the rest at the original. Read the full README ↗