Metadata-Version: 2.4
Name: auspex-rt
Version: 0.1.0
Summary: Bounding-box object detection, trained from scratch on your own data
Author: Md. Sohanur Islam Shuvo
License: AUSPEX END-USER LICENSE AGREEMENT (EULA)
        
        Copyright (c) 2026 Md. Sohanur Islam Shuvo (github.com/sohanurislamshuvo)
        ("Licensor"). All rights reserved.
        
        This End-User License Agreement governs use of the Auspex software, including
        its binary distributions, source code, model architecture, configuration
        files, documentation, and tools (the "Software"). By installing or using the
        Software you agree to these terms.
        
        1. LICENSE GRANT. Subject to this Agreement, Licensor grants you ("Licensee")
           a limited, non-exclusive, non-transferable, revocable license to:
           a) install and run the Software, in the binary form provided to you, on
              systems under your control;
           b) train, fine-tune, validate, and run models with the Software using
              Licensee's own data; and
           c) use the resulting model weights and predictions for Licensee's own
              internal business purposes.
        
        2. OWNERSHIP. The Software, its architecture, and all intellectual property
           therein remain the exclusive property of Licensor. Model weights that
           Licensee trains with the Software on Licensee's own data belong to
           Licensee; this does not transfer any rights in the Software itself.
        
        3. RESTRICTIONS. Except with Licensor's prior written permission, Licensee
           shall NOT:
           a) copy (other than as required to install and run), redistribute, sell,
              rent, lease, sublicense, or otherwise make the Software available to
              any third party;
           b) modify, adapt, translate, or create derivative works of the Software;
           c) decompile, disassemble, reverse engineer, or otherwise attempt to
              derive the source code, architecture details, or algorithms of the
              Software, except to the extent such restriction is prohibited by
              applicable law;
           d) use the Software or knowledge gained from it to develop a competing
              product or service; or
           e) remove or alter any copyright or proprietary notices.
        
        4. TERMINATION. This license terminates automatically if Licensee breaches
           this Agreement. Upon termination, Licensee must cease use and destroy all
           copies of the Software; Sections 2, 5, and 6 survive termination, and
           Licensee's rights under Section 1(c) to weights already trained on
           Licensee's own data survive any termination not caused by breach.
        
        5. 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.
        
        6. LIMITATION OF LIABILITY. IN NO EVENT SHALL LICENSOR 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.
        
        For licensing inquiries, contact the copyright holder.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.3
Requires-Dist: torchvision>=0.18
Requires-Dist: numpy>=1.26
Requires-Dist: opencv-python>=4.9
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# Auspex RT

**Bounding-box object detection.** Train on your own boxes, detect boxes. One
task, done properly — no segmentation heads, no keypoints, nothing you are not
using taking up parameters and compute.

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

Trained from **random initialisation**. No pretrained weights are downloaded,
and none are required: the model is yours from the first step, with no upstream
licence attached to it.

## Install

```bash
pip install auspex-rt        # import name: auspex_rt
```

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

```python
from auspex_rt 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-rt train --data data.yaml --labelspace
labelspace.yaml`, `auspex-rt predict --weights best.pt --source images/`,
`auspex-rt val --weights best.pt --data data.yaml`.

## Pointing it at a YOLO export

A Roboflow/YOLO export is described by its `data.yaml`, which is the only file
in it that names the classes. Point the parser straight at that:

```yaml
sources:
  - name: batch1
    path: /datasets/pow/data.yaml   # YOLO data.yaml
    split: train
    provides: {rect: true}
```

Both YOLO line formats are read: the 5-field box form (`cls cx cy w h`) and the
polygon form (`cls x1 y1 … xn yn`) that segmentation and oriented-box exports
produce. **A polygon is converted to its axis-aligned bounding box, and the
conversion is counted and warned about** — this model detects axis-aligned
rectangles, so a polygon carries information it cannot represent, and a silent
lossy import is how you conclude the model is broken when the loader threw the
shape away.

## Pre-labeling workflow

Send model predictions straight back to your labeling tool:

```python
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 AP, per-class AP is logged,
`--patience N` stops early); `--class-balance` oversamples images containing
rare classes; `auspex-rt 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`:

```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 — check your own box sizes before reaching for them.

## Data configuration

`labelspace.yaml` — your categories, in order; the index is the class id.

`data.yaml` — one entry per annotation source:

```yaml
sources:
  - name: batch1
    path: annotations/batch1.xml   # YOLO data.yaml | CVAT 1.1 XML | COCO .json | VOC xml dir
    images_root: images/
    split: train
    provides: {rect: true}
```

`provides: {rect: true}` declares that this source actually labels boxes. A
source that does not is still useful — its images teach background — but it
must not push predictions toward background on classes it never labelled, and
this flag is what prevents that.

A dataset annotated with polygons or keypoints still trains a box model: the
box is derived from the annotation's extent, so a segmentation set you already
own is usable without re-annotation.

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 this against your own data does not require buying anything.

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

```bash
export AUSPEX_RT_LICENSE=AUSPEXRT-...   # a licence key, or
export AUSPEX_RT_LICENSE=HLN1....       # an account token
                                        # or write it to ~/.auspex-rt/license.key
```

- A **licence key** (`AUSPEXRT-...`) 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 RT 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.
