Status: experimental — not production-ready.

Venator

A modular, local-first framework for building deepfake detection pipelines across image, video, audio, and audiovisual streams.

Status: early prototype / WIP scaffold. The current codebase provides architecture, plugin registry, FastAPI + Gradio + CLI surfaces, and an ONNX export scaffold. It does not yet ship a trained detector. See STATUS.md before forming expectations.

What this is

Venator is a detector-agnostic framework for assembling local-first deepfake analysis pipelines. It gives you:

• A plugin registry for image / video / audio / audiovisual detectors.
• A unified inference pipeline with ensemble fusion and structured evidence output.
• Three ready-to-use frontends: a FastAPI service, a Gradio web UI, and a CLI.
• Scaffolding for ONNX export, C2PA provenance hooks, and stream ingestion (local file / RTSP / RTMP / generic).
• A reproducible project layout with CI, ruff, mypy, pytest, and Docker builds.

What this is not (yet)

To be unambiguous about a domain where overclaiming is common:

• No trained detector ships in this repo. The default plugin set contains heuristic demonstrators that derive scores from file-level metadata. They exist to exercise the pipeline end-to-end, not to detect deepfakes.
• No empirical benchmark results. Earlier revisions of this README included a results table; those numbers were illustrative targets, not measurements, and have been removed. Real evaluation on FF++ / DFDC / Celeb-DF is on the roadmap and will only be published from reproducible runs.
• Explainability outputs are structured demo evidence, not computed Grad-CAM / SHAP / LIME.
• C2PA validation is a sidecar-JSON hook, not a real trust-chain verifier.
• ONNX export is a stub graph for testing the export pipeline.

See STATUS.md for a per-component breakdown of what works today.

Quick Start

git clone https://github.com/FratresMedAI/VenatorAI.git
cd VenatorAI
pip install -e .[dev]

Launch the Gradio UI

python -m venator.web.app

Run the FastAPI service

uvicorn venator.api.main:app --reload

CLI

venator analyze --file path/to/media.mp4

Run checks

ruff check src tests
pytest

Docker

docker compose -f docker-compose.yml up

An air-gapped variant is provided in docker-compose.airgapped.yml.

Choose Your Path

• Operator: docs/QUICKSTART_10_MIN.md -> docs/USAGE_GUIDE.md
• API Integrator: docs/API_REFERENCE.md -> src/venator/api/main.py
• Research/ML Engineer: docs/ARCHITECTURE.md -> ROADMAP.md
• Contributor: CONTRIBUTING.md -> docs/CONTRIBUTION_PLAYBOOK.md

Repository Map

• src/venator/ - package source (pipeline, registry, API, CLI, web, export).
• docs/INDEX.md - documentation navigator.
• docs/ARCHITECTURE.md - target architecture and module contracts.
• benchmarks/ - placeholder report generator; will be replaced once a real evaluator exists. See benchmarks/README_PLACEHOLDER.md.
• tests/ - smoke / contract tests for the framework surface.
• .github/workflows/ - CI (lint, tests, docker build).

Roadmap

The aspirational scope - multi-modal ensemble with trained backbones, real XAI, real C2PA verification, ONNX deployment, live-stream analysis - lives in ROADMAP.md. Items move out of the roadmap and into the README only after they're actually implemented and reproducibly evaluated.

Governance

• Code of Conduct: CODE_OF_CONDUCT.md
• Contributing Guide: CONTRIBUTING.md
• Security Policy: SECURITY.md

License

MIT - see LICENSE.