devdocs/documentation.md

AVIS Documentation

Welcome to the general documentation for AVIS (Automated Violation Intelligence System), codename Gridlock.

1. Project Overview

AVIS is a hybrid traffic violation detection system designed to be rigorous about evidence. Instead of claiming perfect accuracy for every type of violation from a single photo, AVIS intelligently distinguishes between:

• Appearance Facts: Provable from a single frame (e.g., helmet non-compliance, triple-riding).
• Spatial Facts: Provable using per-camera geometric calibration (e.g., stop-line violation).
• Temporal Facts: Usually requires motion or video, meaning a still frame only generates a "candidate" (e.g., wrong-side driving, running a red light).

By classifying violations into evidence-sufficiency tiers, AVIS provides court-ready, explainable verdicts that degrade gracefully rather than outputting false positives.

2. Setup and Installation

Local Development (Zero Infrastructure)

This mode runs the entire pipeline locally using SQLite for storage and in-process execution (no Redis needed). Ideal for rapid development and testing.

# 1. Create a virtual environment
python -m venv .venv
# Activate it (Windows PowerShell)
.venv\Scripts\Activate.ps1
# (Linux/macOS) source .venv/bin/activate

# 2. Install core dependencies
pip install -r requirements.txt

# 3. Setup configuration
cp .env.example .env

# 4. Run the API server
uvicorn api.main:app --reload

Navigate to http://127.0.0.1:8000 to access the API.

Full Stack Deployment (Docker)

For production-credible environments or advanced testing with queue workers, Postgres, and MinIO:

docker compose up --build

This single command spins up:

• The FastAPI Backend API (:8000)
• PostgreSQL Database (:5432)
• Redis Queue (:6379)
• MinIO Object Storage (:9000, console :9001)

Hugging Face Spaces Deployment (Docker)

The project includes a Dockerfile pre-configured to meet Hugging Face Spaces requirements (runs on port 7860, executes as a non-root user with UID 1000).

1. Create a new Docker Space on Hugging Face.
2. Push this repository to the Space.
3. Configure your Space secrets in the settings:
   • GEMINI_API_KEY: Your Gemini Flash API key.
4. The space will automatically build and deploy. Data will be stored safely in the /home/user/app/data directory using SQLite.

3. Configuration

The system is configured primarily via the .env file (parsed by Pydantic Settings in core/config.py). Key variables include:

• DATABASE_URL: Connection string (defaults to sqlite:///avis.db for local dev).
• LLM_PROVIDER: gemini (default) or null to bypass VLM verification.
• GEMINI_API_KEY: API key for Gemini Flash.
• PLATE_PROVIDER: Choose fastalpr for license plate detection.

4. Testing and Evaluation

Unit Testing

The project uses pytest for rigorous unit testing of rules, parsing, and pipeline flow without requiring heavy machine learning models to be loaded.

pytest -q

Static Analysis

Maintain code quality with ruff and mypy.

ruff check .
mypy core/ api/

ML Evaluation

To evaluate the pipeline's performance metrics (Precision, Recall, F1 score, OCR accuracy, and latency), use the dedicated evaluation script:

python -m eval.run eval/sample_dataset.json

This script performs a rule-only vs. rule+VLM ablation study, proving the efficacy of the hybrid approach in reducing false positives.

5. Development Guidelines

• Add New Violations: Add the violation logic as a deterministic rule function in core/rules/ and map it to a Tier in the Rule Engine. Do not use ML models directly within the rule functions.
• Dependency Management: Update requirements.txt carefully, keeping heavy ML libraries (ultralytics, fast-alpr) separated in documentation if possible from core API dependencies.
• Type Safety: Pydantic schemas in core/schemas/ are the single source of truth. Rely on the EvidenceGraph to pass detection data between stages.