Collections AI

An intelligent, self-improving debt collections system powered by three specialized agents that learn from every interaction.

How it works

Riverline orchestrates three agents through a Temporal workflow:

1. Assessment Agent — Initial borrower contact. Gathers identity, debt details, and financial situation via chat.
2. Resolution Agent — Voice handoff to Vapi for real-time negotiation when needed.
3. Final Notice Agent — Final communication stage via chat if resolution wasn't reached.

Each agent writes observations to an events table. Before passing context to the next agent, a compressor squeezes everything into a 500-token handoff packet—critical info stays, droppable insights drop first.

The system then runs a learning loop: simulate new prompt iterations, measure compliance and recovery rate lift, adopt winners, and roll back regressions.

Architecture

What's here

• Three-agent orchestration with Temporal
• Event-sourced context (append-only events table + JSONL transcripts)
• Token-budget-aware handoff compressor
• Compliance checker (identity, recording disclosure, no harassment, fair terms, hardship offers, data privacy)
• Meta-evaluator that watches for prompt decoupling, persona blindspot, zero-firing rules, and low judge agreement
• Learning loop with statistical significance testing (Welch's t-test) and bootstrap confidence intervals
• React dashboard for live borrower monitoring and transcript review
• FastAPI backend with SQLite

Tech

• Backend: Python, FastAPI, Temporal SDK, SQLite
• Models: Cloudflare Workers AI (primary), OpenRouter (simulator only)
• Voice: Vapi webhooks for call triggers and outcomes
• Frontend: Vite, React, Tailwind (via CDN)

Setup

Copy the env template and fill in your keys:

cp .env.example .env

Required:

• CF_ACCOUNT_ID, CF_API_TOKEN (Cloudflare Workers AI)
• TEMPORAL_HOST (defaults to localhost:7233 for local dev)

Optional:

• VAPI_API_KEY, VAPI_PHONE_NUMBER_ID, VAPI_WEBHOOK_SECRET, PUBLIC_BASE_URL (for voice)
• OPENROUTER_API_KEY (for simulator fallback)

Run

Start all four processes with:

./dev.sh

Or start them separately in different terminals:

temporal server start-dev
uv run python -m backend.temporal_app.worker
uv run uvicorn backend.main:app --reload
cd frontend && bun dev

API

• POST /api/v1/borrowers?borrower_id=<id> — Start a collections workflow
• POST /api/v1/chat/{borrower_id}/message — Send borrower message (agent sees and responds)
• GET /api/v1/conversations/{borrower_id} — Get full transcript and current state

Scripts

uv run python scripts/seed_borrower.py
uv run python scripts/run_learning_loop.py --seed 42 --cycles 1 --dry-run
uv run python scripts/build_evolution_report.py
uv run python scripts/dgm_validation.py