FastAPI + BackgroundTasks
Submission returns immediately while the worker advances the claim through pending, in-progress, completed, or failed states.
The engineering thesis
Make model output reviewable by designing the workflow around state, evidence, and failure.
Aegis is not presented as an autonomous truth oracle. It is an investigation workflow for claims, market anomalies, and fast-moving public narratives. The useful engineering problem is orchestration: accepting work, preventing duplicates, gathering context, constraining the verdict shape, recording status, and exposing failure to the UI.
The deployed product combines a static multi-page frontend, a Netlify Gemini gateway, a FastAPI service, background claim processing, RSS ingestion, and Supabase persistence.
Core pipelineClaim ingestion, research, investigation
Specialist logicScout and Trending agents
Review surfaceSearchable verdict dashboard
PersistenceClaims, evidence, threat records
System architecture
Five boundaries, one traceable claim
The architecture separates deterministic application work from probabilistic model work. That separation makes retries, fallbacks, and review states visible.
Ingest
Manual submit or RSS headline
→
Identify
Normalize and SHA-256 deduplicate
→
Research
Supporting and refuting context
→
Investigate
Verdict, confidence, severity
→
Review
Supabase record and dashboard
Gemini 2.5 Flash
Research and investigation are distinct prompts. JSON normalization, schema checks, provider fallback, and controlled errors sit around the model call.
Supabase PostgreSQL
Claims and evidence survive page refreshes. The dashboard prefers persisted completed claims and explicitly tops up from the WELFake dataset.
Scout + Trending
Scout computes market-volatility evidence; Trending collects Google News RSS and optional external social data for specialist scans.
Runtime workflow
What happens after Submit
01
Normalize before spending model tokens
The ingestion agent trims and normalizes the claim, then derives a stable SHA-256 identifier. Existing claims return their current record instead of triggering duplicate inference.
normalized_claim → sha256 → existing record or new job02
Move slow work behind a status contract
FastAPI schedules claim processing in the background. The record becomes the shared contract between the API, worker, database, and frontend.
pending → in_progress → completed | failed03
Separate evidence collection from judgment
The Research Agent produces supporting and refuting material. The Investigator Agent receives that structured context and generates verdict, confidence, severity, and reasoning as a second step.
04
Persist the result and its failure mode
Successful jobs write evidence and final fields. Failed jobs keep a failed status and an internal error reason, avoiding a silent blank result.
05
Expose source state in the interface
The dashboard can show persisted claims, cached data, or dataset fallback. The interface tells the user when the hosted backend is waking rather than pretending every row is live.
Product surfaces
The system is visible, not buried in a notebook
Implementation map
Where the important work lives
| Subsystem | Source | Responsibility | Engineering detail |
|---|---|---|---|
| API orchestration | backend/main.py | Routes, state, dashboard data, startup loops | FastAPI, GZip, CORS, background jobs, explicit fallbacks |
| Claim worker | backend/workers/claim_worker.py | Research-to-verdict lifecycle | State transitions and persisted failure handling |
| Research / verdict | backend/agents/* | Two-stage model workflow | JSON extraction, schema normalization, model and key retry |
| Market intelligence | scout_agent.py | Price history and volatility evidence | Rolling statistics, impact simulation, specialist output |
| News ingestion | rss_ingestion.py | Recurring claim discovery | Google News RSS loop with claim-level deduplication |
| Edge gateway | netlify/functions/gemini.js | Browser-safe model access | Environment-only keys, model fallback, controlled response |
Engineering judgment
What is real, and what still needs validation
A coherent end-to-end investigation system
- Deterministic claim identity and deduplication
- Asynchronous evidence and verdict stages
- Persistent status, evidence, and dashboard records
- Market and news specialist workflows
- Hosted frontend, API, and database integration
Not an externally validated truth engine
- Model-generated evidence needs stronger source retrieval and citation checks
- Dashboard fallback rows are demonstration data, not live detections
- BrandShield and Personal Watch remain interface-level concepts
- No benchmark currently establishes operational accuracy or response-time claims
Next engineering milestone
Ground every verdict in retrieved source documents, retain multiple evidence records per claim, and run a frozen benchmark with calibration, latency, and abstention metrics.