backend/README.md

# HaramGuard — Agentic AI Crowd Management System

## 📁 Folder Structure

```
HaramGuard/
│
├── config.py                  ← All thresholds & API keys (edit here only)
├── pipeline.py                ← RealTimePipeline — orchestrates all agents
├── dashboard.py               ← Streamlit dashboard entry point
├── requirements.txt
│
├── core/                      ← Shared infrastructure (no agent logic here)
│   ├── __init__.py
│   ├── models.py              ← FrameResult, RiskResult, Decision dataclasses
│   └── database.py            ← HajjFlowDB — SQLite (4 tables)
│
├── agents/                    ← One file per agent
│   ├── __init__.py
│   ├── perception_agent.py    ← YOLO tracking + Guardrails GR1/GR2
│   ├── risk_agent.py          ← Clip segmentation + sliding K-window density scoring
│   ├── reflection_agent.py    ← Self-critique design pattern (Bias detection)
│   ├── operations_agent.py    ← Event-driven playbook + rate-limit guardrail
│   └── coordinator_agent.py   ← openai/gpt-oss-120b + output validation guardrails GR-C1..5
│
└── outputs/                   ← Auto-created at runtime
    ├── hajjflow_rt.db         ← Main SQLite database
    └── plots/                 ← Saved charts
```

## 🤖 Agent Pipeline

```
Frame
  │
  ▼
PerceptionAgent   →  FrameResult   (YOLO detect + track)
  │
  ▼
RiskAgent         →  RiskResult    (clip segmentation + K-window density score)
  │
  ▼
ReflectionAgent   →  reflection{}  (bias check + correction)
  │
  ▼
OperationsAgent   →  Decision      (event-driven, P0/P1/P2)
  │
  ▼
CoordinatorAgent  →  plan{}        (openai/gpt-oss-120b action plan, all priorities)
  │
  ▼
pipeline.state    →  Dashboard
```

## 🛡️ Guardrails

| ID | Agent | Description |
|----|-------|-------------|
| GR1 | PerceptionAgent | Person count capped at 500 |
| GR2 | PerceptionAgent | Density score capped at 50 |
| GR3 | RiskAgent | Risk score clamped to [0, 1] (density_pct / 100) |
| GR3b | RiskAgent | level_changed suppressed during K-window warmup (first 17 frames per clip) |
| GR4 | OperationsAgent | P0 rate-limited (1 per 5 min per zone); resets on pipeline restart |
| GR-C1..5 | CoordinatorAgent | LLM output validation (fields, threat_level, confidence, score-level consistency, Arabic fallback) |
| RF1..3 | ReflectionAgent | Chronic LOW bias, rising trend ignored, count-risk mismatch |

## 📊 Run Evaluation

```bash
python evaluation.py
```

Outputs:
- `outputs/plots/eval_perception.png` — PerceptionAgent charts
- `outputs/plots/eval_risk.png`       — RiskAgent score trajectories
- `outputs/plots/eval_e2e.png`        — End-to-end accuracy + throughput
- `outputs/eval/summary.json`         — Final metrics summary

Rubric coverage:
- ✅ End-to-end performance metrics   (Section 5)
- ✅ Component-level evaluation       (Sections 1–4)
- ✅ Error analysis methodology       (Section 6)
- ✅ Evidence of iterative improvement (Section 7)

## 🚀 Run Backend API

```bash
pip install -r requirements.txt
python api.py
```