Getting started

Getting started#

Two ways in: a ready-made package that carries its own Python, or the orchestrant library in an environment of your own. What the package, yolo-monitor and the extras are is overview.md; how to contribute to any of the family’s repositories is ANTfrastructure’s repository-family.md.

Install a package#

Ready-made packages: no Python needed. Every lane run builds them as CI artifacts, and every push to main publishes them as the v<version> GitHub release once every lane is green (release.yml, since 2026-10-16). Each one carries its own CPython, the locked dependencies, ONNX Runtime and the detection model with its LICENSE and NOTICE, and CI starts each one once (yolo-monitor --self-test) before it ships:

Platform	Package	After installing
Windows x64 / arm64	`orchestrant-<version>-windows-<x64\|arm64>.msi`	Start menu → OrchestrANT; `yolo-monitor`, `orchestrant-bench` and `orchestrant-smoke` on `PATH`
Windows x64 / arm64	`orchestrant-<version>-windows-<x64\|arm64>.msix`	trust the `…-test-signing.cer` first (below); then Start menu → OrchestrANT, and the three commands as execution aliases
Windows x64 / arm64	`orchestrant-<version>-windows-<x64\|arm64>.zip`	unzip anywhere, run `yolo-monitor.exe`
Linux x86_64 / arm64	`orchestrant_<version>_<amd64\|arm64>.deb`	`sudo apt install ./orchestrant_<version>_<arch>.deb`, then `yolo-monitor`
Linux x86_64 / arm64	`orchestrant-<version>-<x86_64\|aarch64>.AppImage`	`chmod +x`, then run it
Linux x86_64 / arm64	`orchestrant-<version>-linux-<x86_64\|aarch64>.tar.gz`	unpack anywhere, run `bin/yolo-monitor`

The Linux packages carry the image’s glibc and the family’s own GStreamer (since 2026-10-18), so they start on Debian 13 and Ubuntu 24.04 too, and CI installs and starts them on a bare ubuntu-26.04 runner. Releases up to v0.0.32 still need glibc 2.43 (Ubuntu 26.04 or newer), which their bundled ONNX Runtime asks for. On Windows, OpenCV is the build without Media Foundation, so it also runs on Windows N and Server Core.

The MSIX is signed with a test certificate, not a trusted publisher, so Windows installs it only after you trust that certificate. From an elevated PowerShell:

Import-Certificate -FilePath .\orchestrant-<version>-windows-x64-test-signing.cer -CertStoreLocation Cert:\LocalMachine\TrustedPeople
Add-AppxPackage .\orchestrant-<version>-windows-x64.msix

The MSI needs no such step. How the packages are built, and what each CI check proves, is ANTfrastructure’s python-app-bundles.md.

Install the Python library#

Three ways to use OrchestrANT as a library:

pip, from GitHub:

pip install OrchestrANT@git+https://github.com/Kataglyphis/OrchestrANT

or a tagged version:

pip install OrchestrANT@git+https://github.com/Kataglyphis/OrchestrANT@v0.0.1

From a clone:

git clone --recurse-submodules https://github.com/Kataglyphis/OrchestrANT
pip install .

or pip install -e . for an editable install, which reflects changes in the clone.

As a submodule of your repository (not generally recommended: your repo’s installation then has to install all of OrchestrANT’s dependencies itself):
```
git submodule add https://github.com/Kataglyphis/OrchestrANT
```

The heavy dependencies are extras, chosen at install time: overview.md § Extras.

Picamera web browser live stream#

picamera2, the Raspberry Pi camera library behind orchestrant/streaming/capture.py, is installed via apt, not PyPI (source), so the venv has to see the system packages:

sudo apt install python3-picamera2
uv venv --system-site-packages
uv run --extra frontend orchestrant-stream   # http://127.0.0.1:5000

KATAGLYPHIS_STREAM_HOST=0.0.0.0 lets other machines on the network open it. Each browser tab draws the camera’s frames as JPEG through Flet; it replaced the Flask MJPEG page.

Demos#

python third_party/ANTfrastructure/linux/scripts/lib/fetch-data-lock.py --lock resources/models/models.lock   # once: the model
uv run --extra app python -m orchestrant.yolo.monitor
uv run --extra app --extra frontend python -m orchestrant.yolo.monitor --web   # in a browser
uv run python examples/monitoring.py

yolo-monitor imports OpenCV and ONNX Runtime, which only the app extra (or an ml-ai* extra) installs. uv run --extra app yolo-monitor --self-test is the check without a camera.

Development setup#

A virtual environment on the pinned CPython, PYTHON_VERSION in third_party/ANTfrastructure/linux/scripts/01-core/versions.env; requires-python allows >=3.11, but the lanes test the pin alone:

uv venv --python 3.15    # 3.15t for the free-threaded build

The pre-commit hook, the static-analysis gate, binary-only wheels and the tools are shared with WebDavClient: ANTfrastructure python-ci.md § Working on a Python consumer locally.

Dependency upgrades go through Renovate as a local CLI, never by hand: the commands are in AGENTS.md § 5.

Tests#

uv sync --extra pytorch-cpu --extra test
uv run pytest tests/unit
bash scripts/linux/ci_tests.sh   # what the Linux lane runs: pytest + coverage

The LLM lab’s own suite, benchmarks/tests, is in testpaths beside tests, so every lane runs it. Its ten harness modules skip on Windows: the candidate sandbox needs POSIX rlimits, process groups and shell fixtures.

Static analysis#

./scripts/linux/ci_static_analysis.sh > "ci_analysis_$(date +%Y%m%d_%H%M%S).log" 2>&1

The CI gate on both lanes: ruff check --no-fix, ruff format --check, ty, bandit, vulture and codespell. It exits 1 on any finding, which the redirect hides (why).

Binary-only wheels#

The shipped wheels compile every module with Cython; inspecting one: ANTfrastructure python-ci.md.

Before an editable install over a Cython build, delete the files the build generated. They all sit under orchestrant/ (.gitignore’s orchestrant/**/*.c):

find orchestrant -type f \( -name '*.c' -o -name '*.so' -o -name '*.pyd' \) -delete

On Windows:

Get-ChildItem -Path orchestrant -Recurse -File | Where-Object { $_.Extension -in '.c', '.so', '.pyd' } | Remove-Item