Architecture
Three tiers, each leading where it is strongest
input text
│
▼
┌─────────────┐
│ redaction │ PII removed BEFORE anything else sees the text
└──────┬──────┘
│
├──────────────▶ TIER 1 · DETERMINISTIC (microseconds)
│ YAML regex rules · identity claims vs official
│ domains/senders/phones · URL heuristics
│ → owns FACTS, sets hard score floors
│
├──────────────▶ TIER 2 · AI (seconds)
│ local LLM judges intent, tone, escalation arc;
│ web intel gathers external evidence (opt-in)
│ → bounded ±0.6, can NEVER cancel a Tier-1 floor
│
└──────────────▶ TIER 3 · HUMAN (async)
verdicts scoring 0.40–0.75 enter the review queue;
human labels become ground truth for tuning
Caller check — the number against the claim
Alongside the transcript, a live call carries the number calling. The caller check (app/verify/caller.py) runs instant local agents on every update — number type, the entity registry, community reports, earlier findings — and, with consent, web agents in the background: is the number on the claimed organisation's own site, and is it reported as a scam? Evidence may contradict a claim or mark a reported number; an official match never lowers the risk. Full design: caller-check.md.
Why the tiers are ordered this way
A bank's official domain is a fact. Asking a language model to recall it invites hallucination, so verify/entities.py checks a local YAML registry instead. Conversely, "this caller is building rapport before making a demand" is a judgment no regex captures, so the LLM handles it — but with a bounded influence, because a confidently wrong model must not be able to talk the system out of hard evidence.
The concrete guarantee: a contradicted identity claim floors the score at 0.78, a critical rule (OTP request, remote-access demand) at 0.85, and the combination of an unverified caller plus a credential request at 0.92. The LLM adjusts within ±0.6 but the floors are re-applied afterwards, so it can sharpen a verdict and never soften one below the evidence.
Module map
backend/app/
main.py App factory, CORS, static web client, DI wiring
config.py All knobs via env/.env (pydantic-settings)
schemas.py API contracts — the single source of truth for clients
api/
routes.py /v1 endpoints
security.py API keys + rate limiting (seam for JWT/OAuth later)
core/
analyzer.py Orchestrator: redact → rules → URLs → verify → LLM → persist
language.py Language detection + honest coverage reporting
livecall.py Real-time call sessions, instant alerts, TTLs
redaction.py PII removal (phone, card, OTP, email, IBAN, passport, address)
rules.py YAML rule engine with negation-aware exclude spans
claims.py* (in verify/) mention vs identity claim
scoring.py Score blending + floors + risk levels
stt.py Local voice transcription (faster-whisper), optional
urls.py URL extraction + lookalike/abuse-TLD heuristics
llm/
base.py Adapter interface + DisabledLLMAdapter
ollama.py Ollama adapter, structured JSON, forensic-linguistics prompt
verify/
claims.py Identity-claim detection (shared by message + live call)
entities.py Official domain/sender/phone verification
intel.py RDAP + web scam reports (opt-in, offline-safe)
service.py Combines evidence into a bounded adjustment
db/ AnalysisRecord — privacy-safe metadata only
rules/
scam_rules.yaml 34 rules (English + Arabic), hot-reloadable
known_entities.yaml Impersonation registry
Live-call analysis
The hard requirement is warning the user mid-sentence, not after the call.
Browser/on-device STT emits two kinds of text: interim hypotheses while the person is still speaking, and final utterances after a pause. Waiting for finals means alerting seconds late. So /v1/call/{id}/chunk accepts commit: false for interim text: it is analyzed against the accumulated transcript for instant alerts but never appended, so the final version does not double-count. Alert deduplication is per-session, so an OTP demand caught mid-sentence alarms once.
Only Tier 1 runs per utterance (microseconds). The LLM pass runs on a throttle over a trailing window via /assess, so slow inference never blocks alerts.
Data and privacy
- Raw message text is never persisted.
AnalysisRecordstores hashes, scores, matched rule IDs, and domains. - Redaction runs before the LLM and before any optional storage.
- External lookups (RDAP, web search) are off by default and require explicit per-request consent; every response reports what ran locally vs externally.
- Live-call transcripts live in memory only, with idle (15 min) and absolute (4 h) TTLs, and are purged on cancel, expiry, or eviction.
- Verdicts are never cached. Only context-free engine artifacts are, under a key containing content, locale, source type, and rules/entities/config versions.
Deployment shape (SaaS)
clients ──▶ FastAPI (stateless, horizontally scalable)
├── Postgres analysis records, review labels
├── Redis artifact cache, rate-limit counters (multi-instance)
└── Ollama/vLLM LLM tier (or a hosted model behind consent)
Rate limiting is currently in-process; move it to Redis before running more than one instance. Auth is API-key based today with api/security.py as the seam for JWT/OAuth and per-tenant quotas.