Metadata-Version: 2.4
Name: myelion-csf
Version: 1.0.0
Summary: MYELION CSF Core RT — inference and training runtime for .csf model files
Author-email: "MYELION Inc." <contact@myelion.com>
License: Proprietary — MYELION Inc.
Project-URL: Homepage, https://myelion.com
Project-URL: Documentation, https://myelion.com/docs
Project-URL: Support, https://myelion.com/support
Keywords: object detection,inference,edge AI,embedded AI
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.24.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: Pillow>=10.0.0
Provides-Extra: gpu
Requires-Dist: torch>=2.1.0; extra == "gpu"
Requires-Dist: torchvision>=0.16.0; extra == "gpu"
Provides-Extra: train
Requires-Dist: torch>=2.1.0; extra == "train"
Requires-Dist: torchvision>=0.16.0; extra == "train"
Requires-Dist: Pillow>=10.0.0; extra == "train"
Requires-Dist: PyYAML>=6.0; extra == "train"
Requires-Dist: tqdm>=4.65.0; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: torch>=2.1.0; extra == "dev"
Requires-Dist: cryptography>=41.0.0; extra == "dev"
Requires-Dist: PyJWT>=2.8.0; extra == "dev"
Requires-Dist: Pillow>=10.0.0; extra == "dev"
Dynamic: license-file

# CSF Core RT — Python SDK

**v1.0 · Stable**

Inference runtime for `.csf` model files produced by the CSF Core training framework.  
Device-locked · Hardware-optimised · Precision-configurable.

---

## Requirements

| Requirement       | Minimum version |
|-------------------|-----------------|
| Python            | 3.9             |
| Linux             | x86-64 or ARM64 |
| CUDA (GPU)        | 11.8            |
| ROCm (AMD GPU)    | 5.6             |
| numpy             | 1.22            |

GPU inference additionally requires `torch>=2.0`.

---

## Installation

CSF Core RT is distributed via the MYELION private package registry.  
A valid licence key is required to authenticate.

```bash
# Configure the MYELION registry
pip config set global.index-url https://pkg.myelion.com/simple/
pip config set global.extra-index-url https://pypi.org/simple/

# Install the SDK
pip install csfrt csfrt_ops

# Verify
python -c "import csfrt; print(csfrt.__version__)"
```

---

## Licence Activation

Each device must be activated before the SDK will load models.

```bash
# Online activation
python -m csfrt.activate MYELION-XXXX-XXXX-XXXX

# Check status (no network required)
python -m csfrt.status
```

**Air-gap environments:**

```bash
# 1. Extract fingerprint on the isolated device
python -m csfrt.fingerprint
# → Copy the base64 string and send to zulal.tannur@myelion.com

# 2. After receiving license.mkey, deploy it:
sudo cp license.mkey /etc/csfrt/license.mkey
sudo chmod 644 /etc/csfrt/license.mkey
python -m csfrt.status
```

---

## Quick Start

```python
import csfrt
import numpy as np

# Load model — licence verified automatically
model = csfrt.load("model.csf")

# Synchronous inference
input_data = np.random.rand(1, 3, 512, 512).astype(np.float32)
result = model.infer(input_data)
print(result.shape)   # → (1, num_classes)
```

---

## API Reference

### `csfrt.load()`

```python
csfrt.load(
    path: str,
    device: str = "cuda",
    precision: str = "fp16",
    license: str | None = None,
    num_threads: int = 4,
) -> CSFModel
```

| Parameter     | Type          | Description |
|---------------|---------------|-------------|
| `path`        | `str`         | Path to the `.csf` model file. |
| `device`      | `str`         | `"cuda"`, `"cpu"`, `"cuda:N"`, or `"rocm"`. |
| `precision`   | `str`         | `"fp16"` (default) or `"int8"`. |
| `license`     | `str \| None` | Custom path to `.mkey` file. |
| `num_threads` | `int`         | CPU threads for preprocessing. Default `4`. |

---

### `CSFModel.infer()`

```python
model.infer(
    inputs: np.ndarray | torch.Tensor,
    return_numpy: bool = True,
) -> np.ndarray | torch.Tensor
```

Synchronous inference. Blocks until the result is available.

---

### `CSFModel.infer_async()`

```python
future = model.infer_async(input_data)
do_other_work()
result = future.get(timeout=5.0)
```

Non-blocking inference. Returns a `CSFInferenceFuture`.

---

### `CSFStream`

Real-time streaming with automatic micro-batching and callbacks.

```python
from csfrt import CSFStream

def on_result(result, metadata):
    print(f"Frame {metadata['frame_id']}: {result.shape}")

stream = CSFStream(
    model_path="model.csf",
    callback=on_result,
    batch_size=4,
    precision="fp16",
)

stream.start()
for frame in data_source:
    stream.push(frame, metadata={"frame_id": frame.id})
stream.stop()
```

---

## Precision Modes

| Mode   | Flag      | Notes |
|--------|-----------|-------|
| FP16   | `"fp16"`  | Default. Half-precision float. Recommended for GPU. |
| INT8   | `"int8"`  | ~2× throughput. Requires calibration data in `.csf` file. |

> **Note:** INT8 mode requires quantisation calibration data bundled into the
> `.csf` file at training time. Models compiled without it will raise
> `CSFPrecisionError`.

---

## Exceptions

| Exception              | When raised |
|------------------------|-------------|
| `CSFLicenceError`      | No valid token, or fingerprint mismatch. |
| `CSFLicenceExpiredError` | Token validity period elapsed. |
| `CSFModelError`        | Corrupt/incompatible `.csf` file. |
| `CSFPrecisionError`    | INT8 requested but model has no calibration data. |
| `CSFDeviceError`       | Requested device not available. |
| `CSFShapeError`        | Input shape does not match model specification. |

---

## Docker

```bash
# CUDA (NVIDIA)
docker pull pkg.myelion.com/csfrt:1.0-cuda11.8

# ROCm (AMD)
docker pull pkg.myelion.com/csfrt:1.0-rocm5.6

# CPU only
docker pull pkg.myelion.com/csfrt:1.0-cpu

docker run --gpus all \
  -v /etc/csfrt:/etc/csfrt:ro \
  -v /path/to/model.csf:/model.csf:ro \
  pkg.myelion.com/csfrt:1.0-cuda11.8 \
  python inference.py
```

---

## Benchmarking

```bash
python -m csfrt.bench model.csf --iterations 100 --batch 1
python -m csfrt.bench model.csf --precision fp16 int8 --compare
python -m csfrt.bench model.csf --output benchmark.json
```

---

## Support

Documentation: [myelion.com/docs](https://myelion.com/docs)  
Licensing: [zulal.tannur@myelion.com](mailto:zulal.tannur@myelion.com)
