swadhin / aegisvision public
/ aegisvision / AGENTS.md
swadhinbiswas feat: AegisVision v2 — AI enterprise surveillance & monitoring platform · 8/8/2026
7ad9221
102 lines · 5.9 KB
Raw Download

AGENTS.md

Guidelines for AI agents (and contributors) working in this repository.

Project purpose

AegisVision — AI Enterprise Surveillance Platform (a.k.a. AegisVision).

A production-grade, plug-and-play face-recognition monitoring system for offices,
schools, colleges and workplaces. It streams CCTV/webcam feeds, identifies people
in real time against an enrolled roster, tags UNKNOWN faces (never saving new files),
and derives behavioral analytics:

  • Attendance (in/out at gates), live occupancy counts
  • Productivity: active / idle-lazy / bunking / phone-distraction times
  • Health: drowsiness, fatigue, posture
  • Spatial anti-theft and asset-displacement memory
  • Real-time incident alerts + a Generative-AI decision copilot

Tech stack & architecture

  • Backend: Python 3.12, FastAPI, Uvicorn, SQLAlchemy + SQLite, ChromaDB (cosine vector index), OpenCV, insightface/ONNX (SCRFD+ArcFace, default) with face_recognition/dlib fallback, watchdog, Google GenAI (gemini-2.5-flash). Managed with uv.
  • Frontend: vanilla-JS + Tailwind CSS, static SPA served by FastAPI itself (no bundler/build step); fetch wrapper + WebSocket alert feed in frontend/js/.
  • Data dirs (runtime, git-ignored): data/known_persons/ (plug-and-play roster), data/vector_db/ (ChromaDB), data/surveillance.db (SQLite), data/logs/.

Directory map (the v2 architecture — see PLAN Phase 0 re: legacy cleanup):

backend/
  main.py                       FastAPI entry (lifespan: init DB, sync roster, start watcher)
  app/
    config.py                   Central config/constants/thresholds & camera map
    db/
      sqlite_db.py              Engine/session/init
      models.py                 Personnel, AttendanceLog, ProductivityLog, HealthLog, AssetLog, IncidentAlert
      vector_db.py              ChromaDB face-embedding upsert/query/delete (+ dim self-heal)
    services/
      face_backend.py           Recognition backend (insightface/ONNX 512-d or dlib 128-d, auto-fallback)
      face_engine.py            Detect → liveness → embed → VectorDB match → UNKNOWN tagging + HUD draw
      ingestion_service.py      Plug-and-play folder/photo/JSON rostering + directory watcher
      productivity_engine.py    active/lazy/bunk/phone-status state machine
      health_sentinel.py        drowsiness/posture/fatigue telemetry
      spatial_memory.py         Asset-region displacement / anti-theft rules
      genai_engine.py           Gemini Copilot Q&A (+ rule-based fallback)
      alert_dispatcher.py       WebSocket fan-out for live alerts
      alert_service.py          Persist + WS broadcast + external push on new IncidentAlert
      notify.py                 Config-gated push: Telegram bot + JSON webhook (best-effort)
      rule_engine.py            Background rule-escalation sweep (UNKNOWN×3, phone-overuse, drowsiness)
      logging_service.py        Rotating file + console logging under data/logs
    routes/
      stream.py                 MJPEG video_feed + WS endpoint
      personnel.py              enroll/delete personnel
      analytics.py              dashboard + attendance/productivity/health/assets
      alerts.py                 list/resolve alerts
      copilot.py                POST /api/copilot/query
      assets.py                 register/list/delete tracked assets (spatial anti-theft)
      auth.py · system.py · metrics.py
frontend/
  index.html                    Tailwind dashboard shell (served by FastAPI at site root)
  js/{api,main}.js              fetch wrapper + WS helper, tab router
  js/views/*.js                 live · personnel · analytics · productivity · health · incidents · assets · copilot · system
  css/app.css · login.html
docs/diagrams/*.svg              architecture, recognition pipeline, data model, deployment
legacy: backend/functions/ admin/ models/ settings/ tools/  ← Phase 0 cleanup (pickle + Firebase). Do not extend.

Non-negotiables (do not break)

  1. UNKNOWN faces must never be written to disk and must be visibly labeled on-frame (UNKNOWN FACE).
  2. Plug-and-play roster: dropping <person_id>_<Name>/ with info.json + photos into
    data/known_persons/ must auto-register (startup sync + live watchdog).
  3. VectorDB + SQLite must stay in sync on enroll/delete.
  4. Entrance/attendance logs are cooldown-throttled (30 s per person) per camera.
  5. Frontend never hardcodes a production host — same-origin requests through
    frontend/js/api.js (relative /api paths + WebSocket to location.host).

Conventions

  • Python: typed signatures, one service per file, route files stay thin (logic → services), SQLAlchemy sessions opened/closed in try/finally, Pydantic schemas for API responses.
  • Frontend: views are plain JS modules (frontend/js/views/*.js) with Tailwind utility classes; native fetch/WebSocket; DOM rendering, no framework bundler.
  • Do NOT add code comments. Self-documenting names and minimal docstrings only.
  • Add tests for any new service logic under tests/ (pytest + httpx TestClient).
  • Match existing naming (snake_case Python, PascalCase components).

How to run

# Backend (uv-managed venv already at .venv)
cp backend/.env.example backend/.env   # fill GEMINI_API_KEY / camera sources
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000   # run from backend/

# Frontend is served by FastAPI itself (SERVE_FRONTEND=true) — open the site root.
# API docs
open http://localhost:8000/docs

Verify before finishing any change

  • uv run pytest — add tests alongside new logic (suite lives under tests/).
  • Backend: uv run python -m compileall backend/app or run uvicorn and hit /, /docs, /api/analytics/dashboard.
  • Frontend: a UI change is verified by loading the served app at / (and /login.html) in a browser — no build step. make build-frontend checks frontend/index.html exists.
  • TODO: lint/typecheck commands are not yet configured (frontend eslint script exists but is not enforced).