Metadata-Version: 2.4
Name: auspex-engine
Version: 0.3.1
Summary: Train your own auto-annotator: learns a specialist model per annotation type from one labelled dataset (CVAT/COCO/YOLO/VOC/LabelMe) and labels the rest
Author: Sohanur Islam Shuvo
License: Copyright (c) 2026 Sohanur Islam Shuvo. All rights reserved.
        
        PROPRIETARY SOFTWARE LICENCE
        
        This software and its associated documentation and files (collectively, the
        "Software") are the proprietary property of the copyright holder named above.
        The Software is licensed, not sold. By downloading, installing or using the
        Software you agree to these terms; if you do not agree, do not install or use
        the Software.
        
        1. GRANT OF LICENCE
        
        Subject to your compliance with these terms, the copyright holder grants you a
        non-exclusive, non-transferable, worldwide, royalty-free licence to download,
        install and use the Software, in the unmodified binary form in which it is
        distributed, for your own internal or commercial purposes, including training
        models with it and using the models you train.
        
        Models, weights and annotation outputs that you produce using the Software are
        yours; the copyright holder claims no rights in them.
        
        2. RESTRICTIONS
        
        Except as permitted above, or as expressly authorised in writing by the
        copyright holder, you may not:
        
          (a) redistribute, publish, sublicense, sell, rent, lease or lend the
              Software, or make it available to third parties as a hosted or managed
              service;
          (b) modify, adapt, translate or create derivative works of the Software;
          (c) reverse-engineer, decompile or disassemble the Software, or otherwise
              attempt to derive its source code, except to the extent that this
              restriction cannot lawfully be excluded under applicable law;
          (d) remove, obscure or alter any copyright, licence or attribution notice
              contained in the Software.
        
        3. THIRD-PARTY COMPONENTS
        
        The Software depends on third-party components that are licensed separately
        under their own terms, which are set out in the accompanying
        THIRD_PARTY_LICENSES file. Those terms govern your use of those components and
        prevail over this licence with respect to them. Notably, the Software depends
        on Ultralytics, which is licensed under the GNU Affero General Public License
        v3.0 (AGPL-3.0); nothing in this licence restricts any right you have under
        AGPL-3.0 in respect of that component.
        
        4. RESERVATION OF RIGHTS
        
        All rights not expressly granted in Section 1 are reserved by the copyright
        holder. No licence or right is granted, by implication, estoppel or otherwise,
        under any patent, trademark or other intellectual property right, except for
        the licence expressly granted above.
        
        5. TERMINATION
        
        This licence terminates automatically if you breach any of these terms. On
        termination you must cease all use of the Software and destroy all copies in
        your possession. Sections 2 through 7 survive termination.
        
        6. NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
        7. LIMITATION OF LIABILITY
        
        IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR
        OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
        FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
        IN THE SOFTWARE.
        
Keywords: annotation,auto-labeling,computer-vision,object-detection,segmentation,keypoints,cvat,coco,yolo
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES
Requires-Dist: torch>=2.6.0
Requires-Dist: torchvision
Requires-Dist: timm>=1.0.0
Requires-Dist: ultralytics<9,>=8.4.0
Requires-Dist: opencv-contrib-python>=4.8.1.78
Requires-Dist: scikit-image>=0.22
Requires-Dist: Pillow>=10.0
Requires-Dist: numpy>=1.24.3
Requires-Dist: scipy>=1.11
Requires-Dist: PyYAML>=6.0
Requires-Dist: matplotlib>=3.7
Requires-Dist: tqdm>=4.65
Requires-Dist: shapely>=2.0
Requires-Dist: cryptography>=43.0
Dynamic: license-file

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

```bash
pip install auspex-engine
```

---

## Quick start

```python
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:

```bash
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

```text
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.

```python
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:

```bash
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):

```text
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:

```bash
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](https://github.com/ultralytics/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`).
