auspex-engine

Train your own auto-annotator from one labelled dataset — then let it label the rest.

Point it at a folder of images plus the annotations you already have (CVAT, COCO, YOLO, Pascal VOC or LabelMe). It trains a separate specialist model for each annotation type present, bundles them into a single portable file, and labels unseen images back into re-importable CVAT XML and COCO JSON.

No assumptions about your domain, your label names, or where you run it.

pip install auspex-engine

---

Quick start

from auspex_engine import Auspex

# TRAIN — format is auto-detected; only the annotation types present get trained
Auspex().train(dataset="ann.xml", images="imgs/", output="runs/exp1", epochs=50)
#   -> writes one file: runs/exp1/auspex_model.pt

# LABEL new images with it
results = Auspex("runs/exp1/auspex_model.pt").predict("test/")   # path | folder | ndarray
results.save("out/")        # annotated images + predictions_cvat.xml + predictions_coco.json
results.detections          # [{type, label, score, box|points|x,y}, ...]
results.plot()              # annotated image as a numpy BGR array

Or from the command line:

auspex train   --dataset ann.xml --images imgs/ --output runs/exp1 --epochs 50
auspex predict --model runs/exp1/auspex_model.pt --source test/ --output out/

Useful flags: --tasks bbox,tag (train a subset) · --device cpu · --imgsz 1024 · --batch 8 · --set KEY=VALUE (override any config knob).

---

What it learns

auspex works with five annotation types and trains a dedicated model for each one it finds in your data — anywhere from one to all five in a single run. You never pay for types you don't use.

Type	What it marks
Bounding box	A rectangle around each object
Polygon	A free-form closed outline around a shape or region
Keypoint	A single point / landmark
Polyline	An open multi-point line or path
Tag	A whole-image label, with no location

Datasets it reads

The format is auto-detected. A format that can't express a given type simply contributes none of it, and that model is skipped.

Format	Point it at	bbox	polygon	polyline	keypoint	tag
CVAT for Images 1.1	the exported .xml	✓	✓	✓	✓	✓
COCO	the .json	✓	✓	✓	✓	✓
YOLO	data.yaml or the dataset folder	✓	✓	—	—	—
Pascal VOC	the folder of per-image .xml files	✓	—	—	—	—
LabelMe	the folder of per-image .json files	✓	✓	✓	✓	✓

Anything auspex can't use — COCO RLE masks, degenerate geometry, YOLO pose lines, LabelMe circles — is skipped with a counted warning rather than silently dropped.

Outputs

runs/exp1/
  auspex_model.pt          ← every trained model, in one portable file
  training_summary.json    per-task metrics, which heads trained, partial-run flag
  master_train_log.txt
  <per-task folders with individual checkpoints and CSV training logs>

Prediction writes annotated images plus predictions_cvat.xml and predictions_coco.json — the CVAT file imports straight back into a CVAT task, so a human can correct the machine's work and you can retrain on the result.

One file to move

Every trained sub-model is bundled into a single auspex_model.pt. Copy or version that one file to move the whole model between machines — no per-task folder juggling.

from auspex_infer import AuspexModel      # detection only, no training code needed
AuspexModel("auspex_model.pt").predict("photo.jpg").save("out/")

Signed bundles

A model bundle is executable content, so auspex can sign and verify one with an ed25519 key. Pin the public key of whoever produced a model and anything not signed by them is refused:

auspex keys generate --out mykey            # once — keep mykey, hand out mykey.pub
auspex train ... --sign-key mykey           # producer signs at train time
auspex predict --model m.pt --verify-key mykey.pub   # consumer pins the signer

Verification happens before anything is unpacked or loaded, and requires torch >= 2.6.

Tuning

Every knob is settable via --set KEY=VALUE, an environment variable, or a keyword argument to train(). The common ones:

Knob	Default	Purpose
--epochs / YOLO_EPOCHS …	50	Training budget (fans out to every head)
--imgsz / INPUT_SIZE	640	Image size; raise it to catch small objects
--device / DEVICE	cuda	cuda or cpu
--batch / YOLO_BATCH_SIZE	8	Batch for the box + tag heads
--no-amp	(AMP on)	Force fp32 — fixes NaN validation loss on some newer GPUs
AUSPEX_TASK_SUBPROCESS=1	off	Isolate each head in its own process; frees all GPU memory between heads on small cards

An explicit per-key override always beats a convenience shortcut, so train(imgsz=640, POLYGON_SEG_INPUT_SIZE=1024) keeps the polygon head at 1024.

Machine-readable progress

For a UI or orchestrator, training emits stable progress events you can parse instead of scraping log text (set AUSPEX_PROGRESS=0 to silence):

AUSPEX_PLAN heads=bbox,polygon,keypoint,polyline
AUSPEX_HEAD_START head=polygon index=2 total=4
AUSPEX_EPOCH head=polygon epoch=19 total=100
AUSPEX_HEAD_END head=polygon status=ok

---

Requirements

Python 3.10 / 3.11 / 3.12 on Windows x64, Linux x86_64 / arm64 (manylinux, glibc 2.17+) or macOS Apple Silicon. A CUDA GPU is recommended for training but not required.

These are compiled wheels — native binaries, no readable Python source, and no source distribution. pip needs a wheel matching your platform; Intel Macs are not supported.

torch >= 2.6.0 installs automatically. To pin a specific CUDA build, install torch first and pip will leave it alone:

pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install auspex-engine

Licence

auspex-engine is proprietary software, free to use. You may download, install and use it — including commercially — and the models you train are yours. Redistribution, modification and reverse-engineering are not permitted. The full terms ship inside the wheel (LICENSE).

Third-party components. auspex-engine depends on Ultralytics, which is licensed AGPL-3.0; your use of that component is governed by AGPL-3.0, which prevails over the terms above for that component. Full notices ship in the wheel (THIRD_PARTY_LICENSES).