Metadata-Version: 2.4
Name: arti-fit
Version: 3.1.0a3
Summary: AI x RT: dynamic latent tensor representation layers for PyTorch.
Author: Thiocy
License: MIT
License-File: AUTHORS.md
License-File: LICENSE
Keywords: latent-tensor,neural-networks,pytorch,representation-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: safetensors>=0.4
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: torch>=2.2
Provides-Extra: all
Requires-Dist: accelerate>=0.33; extra == 'all'
Requires-Dist: build>=1.2; extra == 'all'
Requires-Dist: diffusers>=0.30; extra == 'all'
Requires-Dist: hatchling>=1.25; extra == 'all'
Requires-Dist: jax>=0.4.30; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: mkdocs>=1.6; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'all'
Requires-Dist: numpy>=2.0; extra == 'all'
Requires-Dist: onnx>=1.16; extra == 'all'
Requires-Dist: onnxruntime<1.24,>=1.22; (python_version < '3.11') and extra == 'all'
Requires-Dist: onnxruntime>=1.22; (python_version >= '3.11') and extra == 'all'
Requires-Dist: onnxscript>=0.3; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: peft>=0.12; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.15.21; extra == 'all'
Requires-Dist: safetensors>=0.4; extra == 'all'
Requires-Dist: torch>=2.2; extra == 'all'
Requires-Dist: torchvision>=0.26; extra == 'all'
Requires-Dist: transformers>=4.51; extra == 'all'
Provides-Extra: bench
Requires-Dist: matplotlib>=3.8; extra == 'bench'
Requires-Dist: numpy>=2.0; extra == 'bench'
Requires-Dist: pandas>=2.0; extra == 'bench'
Requires-Dist: pillow>=10.0; extra == 'bench'
Requires-Dist: tensorboard>=2.18; extra == 'bench'
Requires-Dist: torch>=2.2; extra == 'bench'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
Requires-Dist: numpy>=2.0; extra == 'dev'
Requires-Dist: onnx>=1.16; extra == 'dev'
Requires-Dist: onnxruntime<1.24,>=1.22; (python_version < '3.11') and extra == 'dev'
Requires-Dist: onnxruntime>=1.22; (python_version >= '3.11') and extra == 'dev'
Requires-Dist: onnxscript>=0.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.15.21; extra == 'dev'
Requires-Dist: tensorboard>=2.18; extra == 'dev'
Requires-Dist: torch>=2.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: font
Requires-Dist: pillow>=10.0; extra == 'font'
Provides-Extra: jax
Requires-Dist: jax>=0.4.30; extra == 'jax'
Provides-Extra: peft
Requires-Dist: accelerate>=0.33; extra == 'peft'
Requires-Dist: peft>=0.12; extra == 'peft'
Requires-Dist: transformers>=4.51; extra == 'peft'
Provides-Extra: qwen
Requires-Dist: accelerate>=0.33; extra == 'qwen'
Requires-Dist: safetensors>=0.4; extra == 'qwen'
Requires-Dist: transformers>=4.51; extra == 'qwen'
Provides-Extra: sd
Requires-Dist: accelerate>=0.33; extra == 'sd'
Requires-Dist: diffusers>=0.30; extra == 'sd'
Requires-Dist: numpy>=2.0; extra == 'sd'
Requires-Dist: peft>=0.12; extra == 'sd'
Requires-Dist: pillow>=10.0; extra == 'sd'
Requires-Dist: safetensors>=0.4; extra == 'sd'
Requires-Dist: torchvision>=0.26; extra == 'sd'
Requires-Dist: transformers>=4.51; extra == 'sd'
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == 'torch'
Provides-Extra: web
Requires-Dist: onnx>=1.16; extra == 'web'
Requires-Dist: onnxscript>=0.3; extra == 'web'
Description-Content-Type: text/markdown

# ARTI

**A PyTorch runtime for composable tensor programs.**

ARTI lets a model work with tensors through explicit, versioned components:
programs, retrieval, Formula Fabric operations, resources, and bounded
execution. It is useful when a model needs more than a fixed sequence of
layers, while still keeping tensor contracts, component identity, and artifacts
inspectable.

ARTI does not prescribe a tokenizer, model family, task head, or training loop.
Applications define the meaning of their tensors; ARTI provides the program
runtime around them.

## Install

The PyPI distribution is `arti-fit`; the Python package is `arti`.

```bash
uv add "arti-fit==3.1.0a3"
```

ARTI requires Python 3.10+ and PyTorch 2.2+. Install the PyTorch build
appropriate for your CPU or CUDA environment first.

Optional integrations are opt-in:

```bash
uv add "arti-fit[qwen]==3.1.0a3"
uv add "arti-fit[sd]==3.1.0a3"
uv add "arti-fit[web]==3.1.0a3"
```

## Start With A Program Host

`ARTILayer` is the tensor-in/tensor-out host boundary. With no configured
program it is an exact identity, making it safe to attach before selecting a
program graph.

```python
import torch
import arti

x = torch.randn(2, 16, 64)
layer = arti.ARTILayer()

assert torch.equal(layer(x), x)
assert arti.component_ref(layer) == arti.canonical_contract_reference("arti/layer@3")
```

For configured execution, build a `FederatedProgram` or a `ProgramGraph` from
`arti.mechanisms`, then provide it to `ARTILayer`. The program owns its local
iteration, Formula Fabric operations, resource bindings, and traversal; the
host layer preserves the ordinary tensor boundary.

## Core Concepts

| Concept | Role |
| --- | --- |
| `ARTILayer` | Host boundary for a federated program or resource graph. |
| `FederatedProgram` | A composable program with sealed Query assets, local iteration, and a terminal tensor ABI. |
| `FormulaFabricV2` | Typed, bounded tensor operations and explicit operands. |
| `ProgramGraph` | Program nodes, resource nodes, connections, and executable graph state. |
| `TensorResource` | A logical tensor resource with an explicit lifecycle, binding, and views. |
| `CreditBoundary` | Identity in the forward pass with an explicit rule for gradient flow through a connection. |
| `OptimizerExecutionPlan` | Learning regions with separate AdamW state and optional region-specific losses. |
| `fabric_layer` | Register a PyTorch module as a typed Fabric node or a differentiable node candidate. |
| `Retrieve` / `RecallExecutor` | Retrieval and bounded execution helpers for standalone use. |
| `ExecutionPolicy` | Limits and traces execution without changing an artifact. |
| `Half`, `Fold`, `UnFold`, `Pulse` | Independently usable tensor layers and workspace operations. |

These components are optional. A program can use only the pieces its tensor
contract needs.

## Attach To A Host Model

ARTI can attach a configured layer at selected tensor boundaries without
rewriting the host model class.

```python
import arti

layer = arti.ARTILayer()
model = arti.ARTI.attach(model, layer, layers="model.layers.*")

model.arti.save("adapter.arti.st")
restored = arti.ARTI.load(fresh_model, "adapter.arti.st", layer=layer)
```

Attachment preserves the host model type and restores tensor-tree structure,
dtype, layout, and position at the boundary. See the
[Unified Attachment guide](docs/unified-attachment.md).

## Artifacts And Component Identity

`arti.save()` and `arti.load()` use SafeTensors alongside architecture metadata
and SHA-256 locks. Component identities, component contracts, and package
versions are separate. This lets a saved program state declare exactly which
components and tensor contracts it requires.

Named compatible Banks and program assets can be composed without silently
losing source identity. Persistent resources are explicit program state rather
than hidden Python side effects.

## Status

ARTI 3.1.0a3 is an alpha release. `ARTILayer`, component identity, artifact
contracts, Formula Fabric, program graphs, Federal execution, and resource
operations are available for structured experimentation and integration.

Public API is not yet frozen for the alpha program/runtime surfaces. Alpha does
not claim broad downstream superiority, a production service SLA, full JAX
parity, or universal acceleration. Dynamic execution only becomes faster when
the selected program, tensor shapes, and backend can be compiled efficiently.

The `arti.legacy` namespace contains retired compatibility readers for historical
artifacts. New code should use `arti`, `arti.nn`, and `arti.mechanisms`.

## Documentation

- [Stable Release Surface](docs/stable-release-surface.md)
- [Unified Attachment](docs/unified-attachment.md)
- [Formula Fabric](docs/formula-fabric.md)
- [Federal Contracts](docs/federal-contracts.md)
- [Program Roles And Resources](docs/reference/program-roles.md)
- [Operable Tensor Port](docs/operable-tensor-port.md)
- [Component Provenance](docs/component-provenance.md)
- [Public API Reference](docs/api/public.md)

## Development

```bash
uv sync --locked --extra dev
uv run --extra dev pytest
uv build
```

ARTI is released under the [MIT License](LICENSE). Citation metadata is in
[`CITATION.cff`](CITATION.cff).
