Metadata-Version: 2.5
Name: nexuml
Version: 0.2.1
Summary: Modular deep learning pipeline framework
Project-URL: Homepage, https://www.nexufed.ai/
Project-URL: Documentation, https://nexufed.github.io/NexuML/
Project-URL: Repository, https://github.com/NexuFed/NexuML
Project-URL: Issues, https://github.com/NexuFed/NexuML/issues
Project-URL: Releases, https://github.com/NexuFed/NexuML/releases
Maintainer: NexuFed AI
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: lightning-utilities>=0.10
Requires-Dist: lightning>=2.0
Requires-Dist: loguru>=0.7
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: safetensors>=0.4
Requires-Dist: tensorboard>=2.0
Requires-Dist: tensordict>=0.6
Requires-Dist: torch>=2.0
Requires-Dist: typer>=0.9
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: mlflow>=2.0; extra == 'all'
Requires-Dist: nexuml-library<0.3,>=0.2; extra == 'all'
Requires-Dist: onnxscript>=0.1; extra == 'all'
Requires-Dist: optuna>=3.0; extra == 'all'
Requires-Dist: pillow>=10; extra == 'all'
Requires-Dist: ray[default,train]<2.59,>=2.57; extra == 'all'
Requires-Dist: soundfile>=0.12; extra == 'all'
Requires-Dist: tqdm>=4.66; extra == 'all'
Provides-Extra: audio
Requires-Dist: soundfile>=0.12; extra == 'audio'
Provides-Extra: dali
Requires-Dist: nvidia-dali-cuda120; (sys_platform == 'linux') and extra == 'dali'
Provides-Extra: data
Requires-Dist: tqdm>=4.66; extra == 'data'
Provides-Extra: dev
Requires-Dist: mike>=2.1; extra == 'dev'
Requires-Dist: mkdocs-click>=0.8; extra == 'dev'
Requires-Dist: mkdocs-gen-files>=0.5; extra == 'dev'
Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.29; extra == 'dev'
Requires-Dist: pymdown-extensions>=10.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Provides-Extra: export
Requires-Dist: onnxscript>=0.1; extra == 'export'
Requires-Dist: pillow>=10; extra == 'export'
Requires-Dist: soundfile>=0.12; extra == 'export'
Provides-Extra: library
Requires-Dist: nexuml-library<0.3,>=0.2; extra == 'library'
Provides-Extra: ray
Requires-Dist: ray[default,train]<2.59,>=2.57; extra == 'ray'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Provides-Extra: tracking
Requires-Dist: mlflow>=2.0; extra == 'tracking'
Provides-Extra: tuning
Requires-Dist: optuna>=3.0; extra == 'tuning'
Description-Content-Type: text/markdown

<div align="center">

<img alt="NexuML" src="https://www.nexufed.ai/assets/logo-long-Ceach6Dp.png" width="800px" style="max-width: 100%;">

<br/>

<img alt="Python" src="https://img.shields.io/badge/python-3.12%2B-blue?style=flat-square&logo=python">
<img alt="PyTorch" src="https://img.shields.io/badge/PyTorch-compatible-ee4c2c?style=flat-square&logo=pytorch&logoColor=white">
<img alt="Status" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square">
<a href="https://test.pypi.org/project/nexuml/"><img alt="TestPyPI" src="https://img.shields.io/badge/TestPyPI-nexuml-blue?style=flat-square&logo=pypi"></a>
<a href="https://github.com/NexuFed/NexuML/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/NexuFed/NexuML/ci.yml?branch=main&style=flat-square&label=CI"></a>
<a href="https://github.com/NexuFed/NexuML/actions/workflows/release.yml"><img alt="Release" src="https://img.shields.io/github/actions/workflow/status/NexuFed/NexuML/release.yml?style=flat-square&label=release"></a>

<br/>
<br/>

**Composable ML pipelines for reproducible experiments.**

NexuML is a modular PyTorch framework for building machine-learning systems from reusable, typed components connected through explicit TensorDict keys. A `ScenarioSpec` describes data, model pipelines, training, evaluation, logging, export, and execution in one place and can be persisted as validated YAML.

[Documentation](https://nexufed.github.io/NexuML/) · [Hands-on tutorials](https://github.com/NexuFed/NexuMLTutorial) · [TestPyPI](https://test.pypi.org/project/nexuml/)

</div>

## Why NexuML?

ML projects often start as a clean notebook and gradually collect project-specific dataset code, model wiring, training loops, evaluation scripts, and export logic. Copying a project template improves the folder structure, but it still duplicates implementations and makes experiments harder to reproduce or extend.

NexuML separates **reusable implementations** from **experiment composition**. Datasets, model blocks, evaluation algorithms, and loader backends can live in libraries; scenarios assemble those pieces into explicit pipelines without reimplementing the training lifecycle for every project.

## Core ideas

- **Typed component definitions** — Python scenarios construct concrete Pydantic definitions directly; stable registry identities are used for discovery and persisted YAML.
- **TensorDict pipelines** — named tensors flow through ordered stages using explicit `keys_in` and `keys_out` contracts.
- **Declarative scenarios** — `ScenarioSpec` composes data, pipeline, training, evaluation, logging, checkpoint, export, and execution configuration.
- **One Lightning lifecycle** — PyTorch Lightning owns the training loop; local and Ray execution reuse the same NexuML session semantics.
- **Pluggable data paths** — PyTorch, NVIDIA DALI, and tensor-shard loaders plus dataset export to NumPy, mmap, Torch, TensorDict memmap, WebDataset, and tensor shards.
- **Post-training evaluation** — typed evaluation definitions materialize stateful algorithms while fitted pipeline layers can perform post-train processing before test.
- **Portable model artifacts** — export a compiled pipeline with weights, resolved configuration, metadata, and dependency information.
- **CLI workflow** — inspect registries and backends, resolve scenarios, build pipelines, train, tune, export datasets, and package models.

## Install

NexuML is currently published on TestPyPI. PyPI remains the fallback for dependencies.

For most users, install the framework together with the reusable base library:

```bash
uv pip install --index https://test.pypi.org/simple --default-index https://pypi.org/simple "nexuml[library]"
```

Install only the framework and CLI when you want to provide all components yourself:

```bash
uv pip install --index https://test.pypi.org/simple --default-index https://pypi.org/simple nexuml
```

NVIDIA DALI, Ray, tracking, tuning, S3, and export integrations are optional. See the [installation guide](https://nexufed.github.io/NexuML/start/install/) before adding platform-specific extras.

## Container image

The complete Linux AMD64 development and training environment is also published with an explicit NexuML and CUDA version:

```bash
docker pull ghcr.io/nexufed/nexuml:0.2.0-cuda12.8.1
docker run --rm -it --gpus all ghcr.io/nexufed/nexuml:0.2.0-cuda12.8.1
```

The image contains both NexuML packages and all optional extras. See the [installation guide](https://nexufed.github.io/NexuML/start/install/#container-image) for host requirements and other tags.

## First look

With the base library installed, inspect a real scenario without starting a training job:

```bash
nexuml registry list scenarios
nexuml resolve cifar-resnet
nexuml build configs/cifar-resnet.yaml
```

This shows the central NexuML flow: a Python scenario is resolved to a reproducible configuration and then materialized into a validated TensorDict pipeline. Continue with [Get started](https://nexufed.github.io/NexuML/start/) for training requirements.

## Learn by building

The [NexuML Tutorial repository](https://github.com/NexuFed/NexuMLTutorial) is the home for complete hands-on projects. It builds an external NexuML library from scratch rather than hiding the framework behind finished built-in components.

The learning path starts with MNIST library basics, then adds file-backed Speech Commands audio with native DALI loading and demonstrates pipeline composition by swapping a CNN encoder for a Transformer while reusing the rest of the system.

> **Version note:** the tutorial repository evolves independently from NexuML. NexuML 0.2 uses typed component definitions and rejects the legacy selector/parameter-bag syntax, so use a tutorial revision compatible with the NexuML version you install.

## Documentation

- **[Get started](https://nexufed.github.io/NexuML/start/)** — install NexuML and inspect your first scenario.
- **[Tutorials](https://nexufed.github.io/NexuML/tutorials/)** — complete hands-on projects and the tutorial compatibility note.
- **[Guides](https://nexufed.github.io/NexuML/how-to/)** — accomplish a specific task such as training, tuning, exporting, or adding a component.
- **[Concepts](https://nexufed.github.io/NexuML/explanation/)** — understand the architecture, TensorDict data flow, definitions, discovery, and scenarios.
- **[Reference](https://nexufed.github.io/NexuML/reference/)** — exact CLI, configuration, backend, decorator, and Python API information.

## Extending NexuML

External libraries can provide their own typed layers, data sources, evaluation algorithms, loader backends, and scenarios through the `nexuml.libraries` entry-point group or a local library root. See [Build a custom library](https://nexufed.github.io/NexuML/how-to/custom-library/) for the package structure and component contracts.
