Metadata-Version: 2.4
Name: singularic
Version: 1.0.2
Summary: Full-stack modern AI/ML library in pure JAX
Project-URL: Repository, https://github.com/singularic/singularic
Project-URL: Homepage, https://singularic.ai
Project-URL: Documentation, https://singularic.ai/docs
Project-URL: Bug Tracker, https://github.com/singularic/singularic/issues
Project-URL: Changelog, https://github.com/singularic/singularic/releases
Author: Singularic contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: checkpoint,deep-learning,distributed,jax,jax-framework,machine-learning,neural-networks,optimization,training
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: jax<0.12,>=0.11.0
Requires-Dist: numpy<3,>=2.0
Requires-Dist: safetensors<0.9,>=0.8.0
Description-Content-Type: text/markdown

# Singularic

[![PyPI version](https://img.shields.io/pypi/v/singularic)](https://pypi.org/project/singularic/)
[![Python version](https://img.shields.io/pypi/pyversions/singularic)](https://pypi.org/project/singularic/)
[![CI](https://github.com/singularic/singularic/actions/workflows/ci.yml/badge.svg)](https://github.com/singularic/singularic/actions/workflows/ci.yml)
[![License](https://img.shields.io/pypi/l/singularic)](https://github.com/singularic/singularic/blob/main/LICENSE)

Singularic is a standalone, unified, JAX-native modern machine-learning framework. It
combines Pythonic modules, semantic optimization, deterministic data pipelines,
automatically compiled training, portable checkpoints, and distributed
placement behind one state and selector system.

```python
import jax
import jax.numpy as jnp
import singularic


class MLP(singularic.Module):
    def __init__(self) -> None:
        self.hidden = singularic.Linear(8, 32)
        self.output = singularic.Linear(32, 2)

    def __call__(self, inputs: jax.Array) -> jax.Array:
        return self.output(jax.nn.gelu(self.hidden(inputs)))


def loss(model, batch, _context):
    inputs, targets = batch
    return singularic.mean_squared_error(model(inputs), targets)


records = [(jnp.ones((8,)), jnp.zeros((2,))) for _ in range(1_024)]
dataset = singularic.Dataset(records).shuffle(42).batch(32)
trainer = singularic.Trainer(
    MLP(), loss_fn=loss
)
trainer.fit(dataset, steps=20)
```

`Trainer` uses AdamW and hardware-aware precision by default. Supply
`optimizer=` or `precision=` only when your run needs an explicit policy.

`Trainer` owns stable JIT boundaries for training, evaluation, prediction,
automatic differentiation, accumulation, mixed precision, donation, and
placement. Advanced users can still use `jax.jit`, `jax.grad`, and all other JAX
APIs directly through `singularic.core.apply.apply`, graph definitions, and `State`.

## Install

Singularic requires Python 3.14 or newer.

```console
uv add singularic
```

JAX is the only numerical backend. Runtime dependencies are JAX, NumPy, and
safetensors.

## Core guarantees

- One metadata-rich `State` pytree for parameters, buffers, caches, RNGs,
  metrics, and optimizer slots.
- One composable `Selector` and ordered rule system for optimization, freezing,
  sharding, precision, and checkpoint policy.
- Semantic Muon/AdamW routing through `singularic.optim.specs.muon()`; `output` fields
  automatically map to the `output_weight` role.
- Immutable deterministic data pipelines with JSON-safe global cursors;
  non-indexed sources must declare a `ResumableStream` replay contract.
- Exact process-count elasticity for fixed-cardinality indexed pipelines.
  Filtering and bucketing require deterministic source plans.
- Versioned JSON plus safetensors checkpoint bundles; never pickle. Immutable
  objects and conditional commit records work through the dependency-free
  `ByteStore` protocol, with a durable POSIX/shared-filesystem adapter in core.

Singularic is a standalone library. Its package version is inferred from the
checked-out Git tag. Start with the concise `import singularic` facade; every
owning module remains public for advanced use. Read the [quickstart](https://github.com/singularic/singularic/blob/main/docs/quickstart.md),
[architecture contract](https://github.com/singularic/singularic/blob/main/docs/architecture.md),
and [API guide](https://github.com/singularic/singularic/blob/main/docs/api.md). CPU, GPU, and TPU use the same portable-JAX
correctness contract; GPU accelerators are optional and lazily imported.
Serving, quantization, executable export, and external dataset connectors are
out of scope.

## Development and benchmarks

All operations use `uv`:

```console
./scripts/bootstrap.sh
./scripts/check.sh
```

The common focused development commands are:

```console
./scripts/dev.sh test
./scripts/dev.sh fast
./scripts/dev.sh type
./scripts/dev.sh docs
./scripts/dev.sh format
```

Run the reproducible decoder benchmark with
`uv run python -m benchmarks.train_decoder`; see
[benchmark policy](https://github.com/singularic/singularic/blob/main/docs/benchmarks.md) for environment-scoped baselines and the
10% release-regression gate.

Licensed under Apache-2.0.
