Architecture
AIGuard is a set of independent components connected by well-defined queues and storage. Each layer can be replaced or scaled independently.
Data flow
text
┌──────────────────────────────────────────────────────────────────┐
│ Your Application │
│ import aiguard │
│ response = aiguard.chat(model="gpt-4o", messages=[...]) │
└──────────────────────┬───────────────────────────────────────────┘
│ TraceEvent (non-blocking)
▼
┌──────────────────────────────────────────────────────────────────┐
│ SDK (sdk/) │
│ client.py ──► queue.py ──► dispatcher.py ──► handlers[] │
└──────────────────────┬───────────────────────────────────────────┘
│ trace_dict
▼
┌──────────────────────────────────────────────────────────────────┐
│ Pipeline (pipeline/) │
│ TraceQueue ──► EvaluationQueue ──► BatchScheduler │
│ │ │
│ ├── HallucinationTest │
│ ├── Adversarial scorer │
│ └── StorageManager.save_* │
└──────────────────────┬───────────────────────────────────────────┘
│ SQLite / Postgres
▼
┌──────────────────────────────────────────────────────────────────┐
│ Storage (storage/) │
│ Tables: traces, evaluation_results, review_labels, │
│ test_cases, dataset_registry │
└──────────────────────┬───────────────────────────────────────────┘
│ read-only queries
▼
┌──────────────────────────────────────────────────────────────────┐
│ Monitoring API (FastAPI, :8080) │
│ /traces /metrics/* /review/queue /health │
└──────────────────────┬───────────────────────────────────────────┘
│ /api proxy
▼
┌──────────────────────────────────────────────────────────────────┐
│ Monitoring UI (Vite + React, :3000) │
│ Dashboard · TraceExplorer · TraceDetail · ReviewQueue │
└──────────────────────────────────────────────────────────────────┘Components
- SDK — wraps LiteLLM and emits TraceEvents to a bounded in-memory queue handled by a daemon worker.
- Pipeline — accumulates traces and evaluates them in time-windowed batches.
- Storage — backend-agnostic. SQLite for local/CI, Postgres for shared deployments.
- Monitoring API — FastAPI server exposing read-only metrics, traces, and the review queue.
- Monitoring UI — React SPA proxied behind the API.
- Review — separate process for human reviewers with calibration feedback.
Offline / CI path
aiguard evaluate bypasses the live pipeline. It reads aiguard.yaml, instantiates the requested evaluation modules, executes them against the configured target model, and writes results directly to storage.