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.

Continue training from a previous model

When people have corrected the auto-labels, retrain from the model you already have instead of from scratch — it keeps what it learned and needs far fewer epochs:

Auspex().train(dataset="corrected.xml", images="imgs/", output="runs/v2",
               base_bundle="runs/v1/auspex_model.pt", epochs=15)

auspex train --dataset corrected.xml --images imgs/ --output runs/v2 \
             --base-bundle runs/v1/auspex_model.pt --base-allow-unsigned --epochs 15

• Every head starts from its best checkpoint in the base bundle — box, polygon, keypoint, polyline and tag.
• Classes are matched by name. Classes in both keep what they learned (even if their position moved), new classes can be added — they start fresh while everything else carries over — and removed ones are dropped.
• Never silent: a head the base bundle doesn't have, or whose architecture you changed, trains from scratch, and training_summary.json → head_init records per head whether it started from the bundle or from scratch (and why), plus the classes kept / added / removed. Use --set BASE_BUNDLE_STRICT=true to fail such a head instead.
• Verified before loading: pass base_verify_key="their.pub" for a model you didn't produce — a bundle is executable content. On the CLI you choose a verification mode, just as with auspex predict.
• The train/val split is stable per image, so images the base model trained on never land in the new run's validation set — warm-start metrics stay honest as your dataset grows. One exception, and it is flagged: the first warm start from a bundle made before 0.3.2 (which used a shuffled split) validates partly on images the base trained on, so its val metrics read optimistic (training_summary.json → base_bundle.split.clean_val: false). Retrains after it are clean.
• Write the new model to a new name or folder: a run refuses to overwrite its own base bundle, so a failed run can never cost you the model you started from.

On our reference retrain, an 8-epoch warm start reached 94–96% of a full 30-epoch retrain's quality on the keypoint and polyline heads in under a third of the time, and added classes learned as well as from scratch. Box (YOLO) heads gain the most from a somewhat longer budget — about a third of your usual epochs is a good starting point.

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.

Ultralytics is held at 8.4.52–8.4.90. Newer releases make box training diverge on small datasets, and pip enforces the range automatically.

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