# matrice_models

Shared model training, evaluation, deployment, and prediction utilities for [Matrice.ai](https://matrice.ai) BYOM (Bring Your Own Model) pipelines.

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## Installation

Install from PyPI:

```bash
pip install matrice_models
```

Install from Test PyPI (for pre-release versions):

```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ matrice_models
```

Install from source:

```bash
git clone https://github.com/matrice-ai/py_models.git
cd py_models
pip install -e .
```

## Quick Start

```python
from matrice_models.config import ModelInfo, TrainConfig
from matrice_models.training import LoopTrainer, DelegatedTrainer
```

## Package Structure

| Module | Description |
|---|---|
| `matrice_models.config` | Pydantic-based configuration schemas (`ModelInfo`, `TrainConfig`, `EvalConfig`, `ExportConfig`, `DeployConfig`) |
| `matrice_models.training` | Trainer hierarchy (`LoopTrainer`, `DelegatedTrainer`), callbacks, checkpoints, early stopping, optimizers, schedulers, device utilities |
| `matrice_models.eval` | Evaluation orchestration, inference runners, metric formatting, model loader registry |
| `matrice_models.deploy` | Deployment server, framework routing, runtime resolution |
| `matrice_models.predict` | Prediction pipeline — model loading strategies, pre/post-processing, TensorRT adapters |
| `matrice_models.metrics` | Classification and detection metrics (precision, recall, F1, mAP, IoU) |

## Training

The training module provides two trainer base classes:

- **`LoopTrainer`** — for custom epoch-based training loops where you control iteration logic.
- **`DelegatedTrainer`** — for framework-owned loops (e.g., HuggingFace Trainer, Ultralytics).

Task-specific models override these hooks: `_get_dataloader`, `_init_model`, `_compute_loss`, `_format_metrics`, `_get_augmentation`.

## Development

### Prerequisites

- Python 3.10, 3.11, or 3.12
- [Ruff](https://docs.astral.sh/ruff/) for linting and formatting

### Setup

```bash
git clone https://github.com/matrice-ai/py_models.git
cd py_models
pip install -e ".[dev]"
```

### Linting & Formatting

```bash
ruff check src/
ruff format src/
```

Configuration lives in `ruff.toml` (line length 120, Google-style docstrings, Python 3.10+ target).

### Running Tests

```bash
pytest tests/
```

## Build Modes

The package supports two build modes controlled via the `ENABLE_MYPYC` environment variable or `build-config.json`:

| Mode | Command | Output |
|---|---|---|
| **Pure Python** (default) | `python -m build` | Universal `py3-none-any` wheel |
| **Mypyc Compiled** | `ENABLE_MYPYC=true python -m build` | Platform-specific compiled wheels |

Mypyc compilation produces native extensions for faster execution but requires building per-platform wheels.

## CI / CD

The GitHub Actions workflow (`.github/workflows/publish-to-pypi.yml`) automates building and publishing:

1. **Config** — reads versions and platform matrix from `build-config.json`
2. **Build** — creates pure Python or mypyc-compiled wheels depending on config
3. **Publish** — uploads to Test PyPI (dev), Test PyPI, and PyPI

Versioning is managed in `build-config.json`:


## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
