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:
- 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.
- 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
- The instant agents run inside every
/chunkresponse, with a 5-second per-call cache so interim updates don't re-read the reports file. - The web agents start when the call starts (reputation) and again when an identity claim is first heard (that organisation's site). They run in a thread pool under
CALLER_CHECK_DEADLINE_SECONDS(default 6). - While they run,
caller_check.statusis"running"and the web client pollsGET /v1/call/{id}/statusevery 1.2 s, so the result arrives even while nobody is talking — a reported number alarms before the caller says a word. - The number can be typed or corrected mid-call:
POST /v1/call/{id}/caller.
Verdicts
| Verdict | Meaning | Effect on the call |
|---|---|---|
reported | ≥ 2 independent reports (community, web, or earlier checks) | floor 0.78, critical alert before anything is said |
not_official | the claimed organisation has verified numbers and this isn't one | claim contradicted: floor 0.50, completes the combo alarm (0.92) with any request |
wrong_kind | a bank or government office "calling" from a personal mobile or from abroad | as not_official |
official | on the verified registry, or found on the organisation's own website | none — information only (see below) |
unverified | claimed, nothing confirms or contradicts it | +0.10, as for any unprovable claim |
no_record | no claim yet; nothing known against the number | none |
no_number | withheld, or not typed | none — 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.
- An official number never lowers the risk. Caller ID is trivially spoofed: the bank's real number on screen, saying "read me your OTP", is still a scam.
officialadds a line of evidence and nothing else; the card is never green. (Same rule as the AI: evidence may sharpen a verdict, never cancel a floor.) - Nothing leaves the machine without two switches: the operator's
WEB_INTEL_ENABLED=trueand the user's tick on "Also check this number on the web" for this call. Every lookup is listed inexternal_lookupsand shown on the card ("Sent off this device: …"). Invariant 4. - A failed search is unknown, not clean. Timeouts and bot challenges become
unavailableevidence. - Official means the organisation's own domain. A page counts only if its host is one of the registry's
official_domains(or a subdomain); a lookalike host (bankfab.com.scam.example) does not, and a redirect off the domain proves nothing — the fetcher refuses it. - A bank's fraud-awareness page is not a report about the bank. Pages on any registered organisation's own domain are excluded from scam-report counting — they print their own number next to the word "fraud".
- No private number is stored in the clear. Invariant 9: findings are keyed by an HMAC fingerprint of the number. Details and URLs of
reportedfindings are stored without the number (complaint sites put it in the URL). The one exception is a number found on an organisation's own website — public business information, kept so a person can promote it into the registry. - No number is ever suggested to call. Invariant 10. The card shows the number the user typed and links to pages on the organisation's own domain.
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_fp | HMAC fingerprint of the canonical number (AE:501234567) |
entity_id | the organisation the finding is about ("" = the number alone) |
finding | official · reported · nothing_found |
detail, url, source | what was found, where, by which agent |
public_number | only for official — a public business number |
method_version | caller-1; bump it when what a finding means changes |
expires_at | official 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_PROVIDER | Key | Notes |
|---|---|---|
auto (default) | — | a keyed API if configured, else DuckDuckGo |
duckduckgo | none | HTML endpoint; rate-limits automated traffic (HTTP 202 → unavailable). Fine for a demo. |
brave | BRAVE_SEARCH_API_KEY | Brave Search API |
tavily | TAVILY_API_KEY | Tavily, 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
- Web research agent — an LLM plans searches and reads pages (official contact pages, regulator notices, complaint threads) and returns cited evidence. Like the live-call AI it is bounded: it can add evidence, never overrule the registry or lower a floor.
- Curator agent — proposes registry changes (a new official number, a number to block) with the evidence attached; nothing reaches the signed pack without a person approving it. A wrong "official" number is worse than none.
- Distribution — verified numbers ship to phones in the signed intelligence pack, so iOS call directory / Android call screening can answer offline.
Limits
- The registry has verified numbers for one organisation so far (Emirates NBD); everything else relies on the number-type rule and the web agents until numbers are verified and added.
wrong_kindis a rule of thumb. Some relationship managers do call from mobiles; the card says "normally", and the advice is the same either way: hang up and call the number on your card.- Web results depend on what the search engine indexes; "not found on the site" is weak evidence, and the card says so.