File size: 4,076 Bytes
1c0c94d | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 | # 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.
```bash
# 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:
```bash
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.
```bash
pytest -q
```
### Static Analysis
Maintain code quality with `ruff` and `mypy`.
```bash
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:
```bash
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.
|