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

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

pip install -r requirements.txt
python api.py