biodex 1.0.1__tar.gz

biodex-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-ci.txt
+
+      - name: Run unit tests
+        run: pytest tests/ -v -m "not slow"
+
+      - name: Verify Gradio app builds
+        run: python -c "from app import build_app; build_app(); print('app ok')"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-ci.txt
+
+      - name: Ruff
+        run: ruff check core app.py ui desktop tests
+
+      - name: Mypy
+        run: mypy core app.py ui
+
+      - name: Pre-commit (all files)
+        run: |
+          pip install pre-commit
+          pre-commit run --all-files
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build package artifacts
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build

biodex-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build hatchling
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify package metadata
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Attach build artifacts to GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: false
+          fail_on_unmatched_files: true
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Trusted Publishing must be configured on PyPI before enabling this job:
+    #   https://pypi.org/manage/project/biodex/settings/publishing/  (see docs/publishing.md)
+    # This job stays SKIPPED (not failed) until you set the repository variable
+    #   PYPI_PUBLISH = true   (Settings -> Secrets and variables -> Actions -> Variables)
+    # so release runs are green out of the box.
+    if: startsWith(github.ref, 'refs/tags/v') && vars.PYPI_PUBLISH == 'true'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

biodex-1.0.1/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Gradio
+.gradio/
+flagged/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Model weights and caches (downloaded on first run)
+*.pt
+*.pth
+*.onnx
+megadetector/
+md_v5a*
+.cache/
+torch_cache/
+
+# Temp exports
+biodex_annotated_*
+biodex_detections_*
+
+# Logs
+*.log
+
+# Test outputs
+outputs/
+results/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Sync / build tarballs and transient working dirs
+*.tar
+demo/
+deploy/
+utils/

biodex-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+# See https://pre-commit.com for more information
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^(core|ui|desktop|tests|app\.py)/
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-Pillow
+          - pandas-stubs
+        args: [core, app.py, ui]
+        pass_filenames: false

biodex-1.0.1/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to BioDex are documented here.
+
+## [1.0.1] — 2026-06-09
+
+### Added
+
+- **Optional AI review (BYOK)** — footer **Use via API** menu with provider/model/key storage; **AI review (LLM)** on batch frame review (scene summary, species second opinion, data-quality flags)
+- LLM modules: `ui/llm_settings.py`, `ui/llm_review.py`, `ui/api_menu.py`
+- Brand assets under `docs/` and savanna background for the field-review UI
+
+### Changed
+
+- UI polish: compact footer/API menu, analytics contrast, hidden broken dataframe toolbar buttons
+- README and SECURITY updated for current feature set (removed outdated dark-mode references; documented BYOK key storage)
+- Model catalog labels note custom model IDs are supported
+
+### Fixed
+
+- OpenAI GPT-5 / o-series test and generation requests use `max_completion_tokens` where required
+- Ruff lint (`page_column` unused binding in `app.py`)
+
+### Known limitations
+
+- LLM review is optional BYOK and limited to batch frame review in this release
+- Model dropdown slugs are provider-specific; not all entries are validated against live APIs
+- API keys stored as plain text in `~/.cache/biodex/settings.json` (documented in SECURITY.md)
+
+## [1.0.0] — 2026-06-08
+
+### Added
+
+- General-availability release line for BioDex with local-first camera-trap analysis workflows
+- Stable tabbed UI workflow (Dashboard, Batch, Video, Analytics, Settings) and export pipeline coverage
+- Production packaging path (CPU/GPU Dockerfiles, release workflow, pre-commit hooks)
+
+### Changed
+
+- Version bumped from `0.5.0` to `1.0.0` in runtime metadata and release documentation
+- Roadmap and README updated to reflect a v1 baseline and post-1.0 planning
+
+### Reliability
+
+- Full quality gates pass: pytest (`not slow`), ruff, mypy (`core`, `app.py`, `ui`), and `build_app()` smoke check
+- Default behavior remains backwards-compatible (`MDV5A` detector + optional SpeciesNet classification)
+- CI/release hardening: package build job, pre-commit checks in CI, and Docker health checks
+- Added release documentation artifacts: `CITATION.cff`, `CONTRIBUTING.md`, `SECURITY.md`
+
+## [0.5.0] — 2025-06-08
+
+### Added
+
+- **Pluggable model architecture** — `core/models/` registry with MegaDetector and SpeciesNet adapters; edge ONNX/TensorRT stubs
+- **ModelSettings** — env-driven config (`BIODEX_DETECTOR_MODEL`, `BIODEX_TORCH_COMPILE`, `BIODEX_GEOFENCE_REGION`, etc.)
+- **Batch performance** — chunking, cancel event, I/O workers, ETA progress (`core/progress.py`)
+- **Video foundations** — `core/video.py` frame extraction, `VideoResult`, `biodex video` CLI (requires `[video]` extra)
+- **Advanced exports** — Wildlife Insights CSV, iNaturalist drafts, timelapse JSON, SQLite, EcoSentinel hook
+- **Analytics** — diversity index, activity heatmap (`[analytics]` extra)
+- **Audit log stub** — opt-in hash-chained JSONL (`BIODEX_AUDIT_LOG=1`)
+- **EXIF/GPS** — `core/exif_utils.py` for export metadata and geofencing fallback
+- **Tabbed UI** — Dashboard, Batch, Video, Analytics, Settings tabs with dark mode and cancel button
+- **Packaging** — Dockerfile (CPU/GPU), release workflow, pre-commit hooks
+- **Optional extras** — `video`, `analytics`, `edge`, `all`
+
+### Changed
+
+- `detector.py` and `classifier.py` refactored as thin facades over the model registry
+- CLI adds `--chunk-size`, `--workers`, `--torch-compile`
+- JSON exports include `human_review` and `review_notes` fields
+- `BatchResult.interrupted` flag for cancelled runs
+
+### Backwards compatibility
+
+- All symbols in `core/__init__.py` remain importable with identical default behavior (MDV5A + SpeciesNet)
+- `build_app()` and `launch_app()` signatures unchanged
+
+## [0.4.x] — prior releases
+
+See git history for v0.4 batch CLI, species tiers, and field-review UI.

biodex-1.0.1/CITATION.cff

@@ -0,0 +1,14 @@
+cff-version: 1.2.0
+title: BioDex
+message: "If you use BioDex in research, please cite this software."
+type: software
+authors:
+  - family-names: FratresMedAI
+    given-names: Team
+repository-code: "https://github.com/FratresMedAI/BioDex"
+license: MIT
+version: "1.0.1"
+date-released: 2026-06-08
+abstract: >
+  BioDex is a local-first wildlife camera-trap analysis tool using MegaDetector
+  and optional SpeciesNet classification, with export formats for conservation workflows.

biodex-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing to BioDex
+
+Thanks for helping improve BioDex.
+
+## Development setup
+
+```bash
+pip install -e ".[ui,models,dev]"
+pre-commit install
+```
+
+## Quality gates (must pass)
+
+```bash
+ruff check core app.py ui desktop tests
+mypy core app.py ui
+pytest tests/ -v -m "not slow"
+python -c "from app import build_app; build_app(); print('app ok')"
+```
+
+## Scope and standards
+
+- Keep BioDex local-first and privacy-preserving by default.
+- Preserve public API compatibility (`core/__init__.py`, CLI behavior, `build_app()` / `launch_app()`).
+- Add/maintain docstrings and explicit error handling.
+- Include tests for behavior changes.
+
+## Pull request checklist
+
+- [ ] Added or updated tests
+- [ ] Updated docs/CHANGELOG when user-facing behavior changed
+- [ ] Ran all quality gates locally
+- [ ] Avoided unrelated refactors

biodex-1.0.1/Dockerfile

@@ -0,0 +1,39 @@
+# BioDex CPU Docker image
+FROM python:3.11-slim AS runtime
+
+LABEL org.opencontainers.image.title="BioDex" \
+      org.opencontainers.image.description="Local-first wildlife camera trap AI analysis (CPU)" \
+      org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml README.md constraints.txt ./
+COPY core ./core
+COPY ui ./ui
+COPY biodex ./biodex
+COPY app.py ./
+
+# Models install order mirrors scripts/install_biodex.sh to avoid the
+# megadetector/speciesnet protobuf + onnx ResolutionImpossible. CPU torch is
+# installed before megadetector so its torch dependency is already satisfied
+# (keeps the multi-GB CUDA wheels out of the CPU image).
+RUN pip install --no-cache-dir --upgrade pip wheel \
+    && pip install --no-cache-dir "protobuf==3.20.1" \
+    && pip install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cpu \
+    && pip install --no-cache-dir "megadetector>=10.0,<11.0" \
+    && pip install --no-cache-dir "Pillow>=9.5" "numpy>=1.26.4,<2.0" "pandas>=2.1" "tqdm>=4.64" "setuptools>=65.0,<81.0" \
+    && (pip install --no-cache-dir "speciesnet>=5.0,<6.0" || pip install --no-cache-dir "speciesnet>=5.0,<6.0" --no-deps) \
+    && pip install --no-cache-dir ".[ui,video]" \
+    && pip install --no-cache-dir "protobuf==3.20.1" --force-reinstall
+
+EXPOSE 7860
+ENV BIODEX_HOST=0.0.0.0 BIODEX_DEPLOY=1
+HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
+  CMD python -c "import socket; s=socket.socket(); s.settimeout(3); s.connect(('127.0.0.1',7860)); s.close()"
+
+CMD ["biodex-ui"]

biodex-1.0.1/Dockerfile.gpu

@@ -0,0 +1,38 @@
+# BioDex GPU Docker image (CUDA runtime + PyTorch GPU wheels)
+FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04
+
+LABEL org.opencontainers.image.title="BioDex" \
+      org.opencontainers.image.description="Local-first wildlife camera trap AI analysis (GPU)" \
+      org.opencontainers.image.licenses="MIT"
+
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 python3-pip python3-venv \
+    libgl1 libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md constraints.txt ./
+COPY core ./core
+COPY ui ./ui
+COPY biodex ./biodex
+COPY app.py ./
+
+# Models install order mirrors scripts/install_biodex.sh to avoid the
+# megadetector/speciesnet protobuf + onnx ResolutionImpossible. CUDA torch is
+# installed before megadetector so its torch dependency is already satisfied.
+RUN pip3 install --no-cache-dir --upgrade pip wheel \
+    && pip3 install --no-cache-dir "protobuf==3.20.1" \
+    && pip3 install --no-cache-dir torch torchvision --index-url https://download.pytorch.org/whl/cu121 \
+    && pip3 install --no-cache-dir "megadetector>=10.0,<11.0" \
+    && pip3 install --no-cache-dir "Pillow>=9.5" "numpy>=1.26.4,<2.0" "pandas>=2.1" "tqdm>=4.64" "setuptools>=65.0,<81.0" \
+    && (pip3 install --no-cache-dir "speciesnet>=5.0,<6.0" || pip3 install --no-cache-dir "speciesnet>=5.0,<6.0" --no-deps) \
+    && pip3 install --no-cache-dir ".[ui,video]" \
+    && pip3 install --no-cache-dir "protobuf==3.20.1" --force-reinstall
+
+EXPOSE 7860
+ENV BIODEX_HOST=0.0.0.0 BIODEX_DEPLOY=1
+HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
+  CMD python3 -c "import socket; s=socket.socket(); s.settimeout(3); s.connect(('127.0.0.1',7860)); s.close()"
+
+CMD ["biodex-ui"]

biodex-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BioDex Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

biodex-1.0.1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: biodex
+Version: 1.0.1
+Summary: Local, privacy-first AI for wildlife camera trap analysis and conservation monitoring
+Author: FratresMedAI
+License: MIT
+License-File: LICENSE
+Keywords: biodiversity,camera-trap,conservation,defensive-monitoring,megadetector,speciesnet,wildlife,wildlife-insights
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: <3.13,>=3.10
+Requires-Dist: numpy<2.0,>=1.26.4
+Requires-Dist: pandas>=2.1
+Requires-Dist: pillow>=9.5
+Requires-Dist: setuptools<81.0,>=65.0
+Requires-Dist: tqdm>=4.64
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: gradio<7.0,>=5.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7; extra == 'all'
+Requires-Dist: megadetector<11.0,>=10.0; extra == 'all'
+Requires-Dist: mypy>=1.10; extra == 'all'
+Requires-Dist: onnxruntime>=1.16; extra == 'all'
+Requires-Dist: opencv-python-headless>=4.8; extra == 'all'
+Requires-Dist: pyinstaller>=6.0; extra == 'all'
+Requires-Dist: pytest>=8.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Requires-Dist: seaborn>=0.13; extra == 'all'
+Requires-Dist: speciesnet<6.0,>=5.0; extra == 'all'
+Requires-Dist: torch>=2.0; extra == 'all'
+Requires-Dist: types-pillow; extra == 'all'
+Provides-Extra: analytics
+Requires-Dist: matplotlib>=3.7; extra == 'analytics'
+Requires-Dist: seaborn>=0.13; extra == 'analytics'
+Provides-Extra: desktop
+Requires-Dist: pyinstaller>=6.0; extra == 'desktop'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pillow; extra == 'dev'
+Provides-Extra: edge
+Requires-Dist: onnxruntime>=1.16; (platform_system != 'Darwin' or platform_machine != 'arm64') and extra == 'edge'
+Provides-Extra: models
+Requires-Dist: megadetector<11.0,>=10.0; extra == 'models'
+Requires-Dist: speciesnet<6.0,>=5.0; extra == 'models'
+Requires-Dist: torch>=2.0; extra == 'models'
+Provides-Extra: ui
+Requires-Dist: gradio<7.0,>=5.0; extra == 'ui'
+Provides-Extra: video
+Requires-Dist: opencv-python-headless>=4.8; extra == 'video'
+Description-Content-Type: text/markdown
+
+# BioDex
+
+**Local AI for wildlife camera traps.** Detect animals, filter blanks, identify species, export results — on your machine, not in the cloud.
+
+[![Python 3.10–3.12](https://img.shields.io/badge/python-3.10--3.12-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.1-brightgreen.svg)](CHANGELOG.md)
+[![CI](https://github.com/FratresMedAI/BioDex/actions/workflows/ci.yml/badge.svg)](https://github.com/FratresMedAI/BioDex/actions/workflows/ci.yml)
+[![Release](https://github.com/FratresMedAI/BioDex/actions/workflows/release.yml/badge.svg)](https://github.com/FratresMedAI/BioDex/actions/workflows/release.yml)
+
+Built for conservation research, field review, and defensive wildlife monitoring (Fratres / EcoSentinel integration hooks).
+
+---
+
+## Run locally (do this)
+
+**Mac / Linux**
+
+```bash
+git clone https://github.com/FratresMedAI/BioDex.git
+cd BioDex
+./run_biodex.sh
+```
+
+**Windows**
+
+```bat
+git clone https://github.com/FratresMedAI/BioDex.git
+cd BioDex
+run_biodex.bat
+```
+
+Your browser opens **http://127.0.0.1:7860**. Use the **Batch** tab to process a folder, or **Quick demo** for a fast preview.
+
+First analysis downloads models once (~500 MB). After that, everything stays offline on your computer.
+
+---
+
+## v1.0 highlights
+
+- **Pluggable models** — registry architecture (`core/models/`) with MegaDetector + SpeciesNet adapters
+- **Batch performance** — chunking, cancel, ETA progress, optional `torch.compile`
+- **Video foundations** — frame sampling + timeline export (`biodex video`, requires `[video]` extra)
+- **Advanced exports** — Wildlife Insights, iNaturalist drafts, timelapse JSON, SQLite, EcoSentinel hook
+- **Tabbed UI** — Dashboard, Batch, Video, Analytics, Settings
+- **Optional AI review (BYOK)** — per-frame LLM notes after batch runs (see below)
+- **Docker** — CPU and GPU images for deployment
+- **Release maturity** — stable API surface, strict typing/linting, and CI-gated quality
+
+---
+
+## Optional AI review (BYOK)
+
+Core detection runs **fully offline** on your machine. AI review is an **optional** power feature:
+
+1. Open **Use via API** in the footer.
+2. Choose a provider, paste your API key, pick a model (or type a custom model ID), then **Save**.
+3. After a batch run, select a frame and click **AI review (LLM)** for a field note: scene summary, species second opinion, and data-quality flags.
+
+**Privacy:** API keys are stored locally in `~/.cache/biodex/settings.json` and sent only to the provider you choose — never to BioDex servers. See [SECURITY.md](SECURITY.md).
+
+**Scope in v1.0.1:** batch frame review only. Single-image spot check, video key frames, and batch-level summaries are planned for v1.1. Not every model slug in the dropdown is guaranteed to work with every provider — use a custom model ID if needed.
+
+---
+
+## Extras install matrix
+
+```bash
+pip install -e ".[ui,models]"           # Web UI + inference (default)
+pip install -e ".[video]"               # OpenCV video support
+pip install -e ".[analytics]"           # Heatmaps + diversity metrics
+pip install -e ".[edge]"                # ONNX stubs (future edge deploy)
+pip install -e ".[all]"                 # Everything
+```
+
+---
+
+## Batch CLI
+
+For large folders (100+ images), no browser:
+
+```bash
+biodex batch /path/to/images -o ./results --classify-species --recursive
+biodex batch /path/to/images -o ./results --chunk-size 500 --torch-compile
+biodex video /path/to/clip.mp4 -o ./video-results --fps 1 --max-frames 120
+```
+
+Environment variables: `BIODEX_DETECTOR_MODEL`, `BIODEX_TORCH_COMPILE`, `BIODEX_GEOFENCE_REGION`, `BIODEX_AUDIT_LOG=1`
+
+## Docker quick start
+
+```bash
+docker build -t biodex:cpu -f Dockerfile .
+docker run --rm -p 7860:7860 biodex:cpu
+```
+
+GPU:
+
+```bash
+docker build -t biodex:gpu -f Dockerfile.gpu .
+```
+
+---
+
+## Developers
+
+```bash
+pip install -e ".[ui,models,dev]"
+pytest tests/ -v -m "not slow"
+ruff check core app.py ui
+mypy core app.py ui
+pre-commit install   # optional
+```
+
+See [CHANGELOG.md](CHANGELOG.md), [docs/roadmap.md](docs/roadmap.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [SECURITY.md](SECURITY.md).
+
+---
+
+MIT License. Uses [MegaDetector](https://github.com/agentmorris/MegaDetector) and [SpeciesNet](https://github.com/google/cameratrapai).