Auspex

One model for every annotation type used in computer-vision labeling work: bounding boxes, instance polygons, keypoints, polylines, and image-level tags — trained on your own data with a few lines of code.

Supported annotation formats: COCO JSON, CVAT-for-images 1.1 XML, Pascal VOC XML — mixed freely in one training run.

Install

pip install auspex-vision        # import name: auspex

Wheels for Linux x86_64, Windows, and macOS Apple Silicon, Python 3.10–3.13. An NVIDIA GPU is recommended for training (precision is picked automatically for your hardware); CPU works for inference.

Use

from auspex import Auspex

model = Auspex(labelspace="labelspace.yaml")
model.train(data="data.yaml", epochs=150)          # train on your own data
results = model.predict("images/", save=True)      # detect

model = Auspex(weights="best.pt")                  # checkpoints are self-contained
model.val(data="data.yaml")

Or the console command: auspex train --data data.yaml --labelspace labelspace.yaml, auspex predict --weights best.pt --source images/, auspex val --weights best.pt --data data.yaml.

Pre-labeling workflow

Send model predictions straight back to your labeling tool:

model.predict("images/", export="cvat")     # CVAT-for-images 1.1 XML pre-labels
model.predict("images/", export="coco")     # or COCO JSON
model.predict("huge_scans/", tiles="auto")  # tile very large images so small
                                            # objects stay detectable

Training quality features: a val split in data.yaml enables validation during training (best.pt tracks real validation fitness, per-class AP is logged, --patience N stops early); --class-balance oversamples images containing rare classes; auspex calibrate --weights best.pt --data data.yaml stores per-class confidence thresholds in the checkpoint so classes with different score scales all show up at their own best operating point.

Very small objects

If your objects are only a few pixels across at training resolution, the default detection grid (finest stride 8) cannot resolve them. Two options, in a train.yaml:

model:
  strides: [4, 8, 16, 32]   # adds a finer detection level
train:
  micro_batch: 2            # ~4x the anchors; halve the batch at 768 px
augment:
  native_crop_p: 0.5        # or: train on zoomed windows of large source images

Measured on a set where half the objects were smaller than one grid cell, the finer level roughly doubled F1 on the smallest classes. It is a trade, not a free win: long thin objects (road-like lines spanning much of the frame) tend to fragment into several detections, so leave it off for those. Both settings are off by default.

Data configuration

labelspace.yaml — your categories (order = class id), keypoint names + flip_pairs for skeleton classes, is_polyline: true for polyline classes, and image-level tags.

data.yaml — one entry per annotation source:

sources:
  - name: batch1
    path: annotations/batch1.xml   # CVAT 1.1 XML | COCO .json | VOC xml dir
    images_root: images/
    split: train
    provides: {rect: true, polygon: true, keypoint: false, polyline: false, tag: false}

provides declares which tasks a source actually labels — unlabeled tasks contribute nothing to training, so sources with different annotation coverage mix safely.

Growing a model over time: --transfer <checkpoint> continues from existing weights even when classes were added or reordered; --source-balance rebalances very unequal sources; --cache-records keeps memory flat on large datasets.

Trial and licensing

Training is free for 30 days, in full — no key, no sign-up, no feature limits. The clock starts on your first training run.

Prediction, validation, calibration and export are never gated. They keep working after the trial ends, on any model you have already trained, forever. Evaluating Auspex against your own data does not require buying anything.

After 30 days, training needs a credential. Either kind goes in the same place:

export AUSPEX_LICENSE=AUSPEX-...        # a licence key, or
export AUSPEX_LICENSE=HLN1....          # an account token
                                        # or write it to ~/.auspex/license.key

• A licence key (AUSPEX-...) is issued to an organisation for a fixed term. Request one at the link below.
• An account token (HLN1....) is one you generate yourself, from the console of an account that has been granted access to this package.

Both are verified offline against a public key compiled into the wheel — nothing phones home, so training works on air-gapped machines and this never sits in the critical path of your build. The trade is that neither can be withdrawn before it expires, which is why both are dated.

Get a key: https://heliontechltd.com/license

License

Proprietary software under an End-User License Agreement: licensed users may install and run Auspex and train models on their own data (the resulting weights are theirs); copying, redistribution, modification, and reverse engineering are prohibited. See https://heliontechltd.com/license for terms and licensing inquiries.