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).
