matrice-models 0.0.3

Shared model training, evaluation, deployment, and prediction utilities for Matrice.ai BYOM pipelines

matrice_models

Shared model training, evaluation, deployment, and prediction utilities for Matrice.ai BYOM (Bring Your Own Model) pipelines.

Installation

Install from PyPI:

pip install matrice_models

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

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

Install from source:

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

Quick Start

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 for linting and formatting

Setup

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

Linting & Formatting

ruff check src/
ruff format src/

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

Running Tests

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 for details.