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

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.