Caller check

Type the number that is calling you. While the call goes on, ScamGuard checks it against who the caller says they are — on this machine at once, on the web in the background — and remembers what it learned for the next call.

Code: backend/app/verify/caller.py (agents and coordinator), backend/app/verify/phone.py (UAE numbering), backend/app/verify/search.py (search back ends). Tests: backend/tests/test_caller_check.py, plus the browser tests in test_live_call_browser.py.

Why

The most common UAE phone scam opens the same way: "Hello, this is Emirates NBD fraud department." Two facts decide it quickly, and neither depends on what the recogniser heard:

  1. Is the number one the organisation uses? A bank's call centre is a 600 or 800 number, published on its own website. A personal mobile or a foreign number claiming to be a bank does not fit.
  2. Has anyone reported this number? Scam numbers are reused until they are blocked, and complaint sites list them.

Rules on the transcript catch the request ("read me the code"). The caller check catches the identity — usually earlier in the call, often before anything has been asked.

How it runs


 number typed ──▶ parse (UAE plan: mobile · landline · 600 · 800 · international · withheld)
                     │
   every update ─────┼──▶ INSTANT AGENTS (this machine, microseconds, always on)
   (~7 per second)   │      number_format   a bank on a personal mobile / from abroad?
                     │      registry        the claimed organisation's verified numbers
                     │      community       ScamGuard users' reports of this number
                     │      evidence_store  what earlier web checks established
                     │
   call start ───────┼──▶ WEB AGENTS (background thread, opt-in, one deadline)
   claim heard ──────┘      web_reports     scam reports about the number (at call start)
                            web_official    is the number on the claimed organisation's
                                            OWN site? search with site:, then fetch the
                                            page and find the number on it (on claim)
                     ▼
               COORDINATOR — weighs evidence into one verdict, never one source alone
                     ▼
     LiveCallStatus.caller_check  ──▶  card on the live-call pane, alert lines,
                                        score floors, the combo alarm

Verdicts

VerdictMeaningEffect on the call
reported≥ 2 independent reports (community, web, or earlier checks)floor 0.78, critical alert before anything is said
not_officialthe claimed organisation has verified numbers and this isn't oneclaim contradicted: floor 0.50, completes the combo alarm (0.92) with any request
wrong_kinda bank or government office "calling" from a personal mobile or from abroadas not_official
officialon the verified registry, or found on the organisation's own websitenone — information only (see below)
unverifiedclaimed, nothing confirms or contradicts it+0.10, as for any unprovable claim
no_recordno claim yet; nothing known against the numbernone
no_numberwithheld, or not typednone — and never "not their number"

A verified list beats a rule of thumb: not_official is decided before wrong_kind. Couriers are exempt from wrong_kind — drivers really do ring from mobiles.

Safety

Each of these has a test in test_caller_check.py.

The source of truth

caller_evidence (SQLAlchemy model CallerEvidenceRecord) is the start of a verified-number database that grows with use instead of searching again:

column
number_fpHMAC fingerprint of the canonical number (AE:501234567)
entity_idthe organisation the finding is about ("" = the number alone)
findingofficial · reported · nothing_found
detail, url, sourcewhat was found, where, by which agent
public_numberonly for official — a public business number
method_versioncaller-1; bump it when what a finding means changes
expires_atofficial 30 days · reported 7 days · nothing found 1 day

The registry itself (rules/known_entities.yaml) stays human-curated: an agent may discover that a number is on an organisation's site, but a person promotes it into official_phones:


python -m app.ops numbers                       # numbers found on official sites, with the page
python -m app.ops caller-check 600540000 --claim emirates_nbd           # live, from a terminal
python -m app.ops caller-check "+971 52 999 0000" --claim fab --offline # local agents only

Search back ends

SEARCH_PROVIDERKeyNotes
auto (default)—a keyed API if configured, else DuckDuckGo
duckduckgononeHTML endpoint; rate-limits automated traffic (HTTP 202 → unavailable). Fine for a demo.
braveBRAVE_SEARCH_API_KEYBrave Search API
tavilyTAVILY_API_KEYTavily, built for AI agents

The DuckDuckGo parser is tested against saved markup and the Brave and Tavily parsers against their documented response shapes; none of them is exercised against the live services in the test suite (it is offline by design). Use python -m app.ops caller-check to try them on a real network.

Production: from agents to a multi-agent service

What runs today is a deterministic coordinator over independent evidence agents. The production shape keeps that contract — agents produce evidence, the coordinator decides, people curate the source of truth — and scales each part:


                    ┌────────────────── Number Intelligence Service ──────────────────┐
  clients ──API──▶  │  Coordinator (deterministic, deadline-bound, explains itself)   │
                    │     │                                                            │
                    │     ├─ Registry agent        verified numbers, signed, versioned │
                    │     ├─ Reputation agent      community + carrier/regulator feeds │
                    │     ├─ Web research agent    LLM-planned searches, page reading  │
                    │     │                        with citations; bounded influence   │
                    │     ├─ Consistency agent     claim vs number vs transcript       │
                    │     └─ Curator agent ──▶ review queue ──▶ human ──▶ registry     │
                    │                                                                  │
                    │  Evidence store (Postgres) — fingerprints, findings, provenance  │
                    └──────────────────────────────────────────────────────────────────┘
                                       │ signed packs (intelligence-sync.md)
                                       ▼
                         phones answer offline from the verified set

Limits