Metadata-Version: 2.4
Name: arti-fit
Version: 1.0.2
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 :: 4 - Beta
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: equinox>=0.11.0; extra == 'all'
Requires-Dist: hatchling>=1.25; extra == 'all'
Requires-Dist: jax>=0.4.30; 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: optax>=0.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: safetensors>=0.4; extra == 'all'
Requires-Dist: torch>=2.2; extra == 'all'
Requires-Dist: transformers>=4.51; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.25; extra == 'dev'
Requires-Dist: numpy>=2.0; extra == 'dev'
Requires-Dist: pytest>=8.0; 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: equinox>=0.11.0; extra == 'jax'
Requires-Dist: jax>=0.4.30; extra == 'jax'
Requires-Dist: optax>=0.2.0; 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: peft>=0.12; extra == 'sd'
Requires-Dist: pillow>=10.0; extra == 'sd'
Requires-Dist: safetensors>=0.4; extra == 'sd'
Requires-Dist: transformers>=4.51; extra == 'sd'
Provides-Extra: torch
Requires-Dist: torch>=2.2; extra == 'torch'
Description-Content-Type: text/markdown

# ARTI

**AI x RT: composable latent tensor layers for PyTorch.**

ARTI is a domain-independent neural-network library for transforming hidden
tensors at runtime. Its layers work with ordinary tensors and can optionally
use coordinates, masks, visibility, latent recall, and compact workspaces.

```text
hidden tensor -> ARTI layer or block -> transformed latent tensor
```

ARTI does not define a tokenizer, task head, data schema, or business model.
Applications remain responsible for encoding their context into tensors.

Version 1.0.2 is a **Stable Candidate**. The supported 1.x surface is frozen
for final compatibility verification, but this release does not yet carry an
LTS commitment. See [Stability](STABILITY.md) and [Security](SECURITY.md).

## Install

Add ARTI to a project with [uv](https://docs.astral.sh/uv/):

```bash
uv add arti-fit
```

ARTI requires Python 3.10 or newer and PyTorch 2.2 or newer. The consuming
project chooses the appropriate CPU or CUDA build of PyTorch.

The PyPI distribution is named `arti-fit`; the Python import remains `arti`.

Optional integrations can be installed as needed:

```bash
uv sync --extra jax
uv sync --extra qwen
uv sync --extra peft
uv sync --extra sd
```

## Use ARTI As A Layer

The smallest API behaves like a normal PyTorch layer:

```python
import arti
import torch

layer = arti.nn.Layer(dim=32)
x = torch.randn(4, 16, 32)
mask = torch.ones(4, 16, dtype=torch.bool)

out = layer(x, mask=mask)

assert out.y.shape == (4, 16, 32)
assert out.pooled.shape == (4, 32)
print(out.diagnostics.keys())
```

For `[B, D]` inputs, ARTI treats each row as a single token and restores the
original rank on output.

Capabilities are opt-in. Enable only the structure carried by the data:

```python
recall_layer = arti.nn.Layer(dim=32, profile="recall")
multisource = arti.nn.Layer(dim=32, profile="multisource", coord_dim=4)
```

## Compose Recall, Half, And Fold

ARTI mechanisms are also available as standalone modules:

```python
import arti

recall = arti.ARTILatentRecallField(hidden_dim=64, slots=8)
half = arti.nn.Half()
fold = arti.nn.Fold(k=16, dim=64)
```

The common Recall branch pattern is deliberately small:

```python
delta = recall(h, mask, recall=None)[0]
h = h + half(delta)
workspace = fold(h, mask=mask)
```

`Recall` proposes latent traces, `Half` applies feature-strength survival, and
`Fold` compacts surviving information into a fixed-size workspace. Each module
can be used independently.

## Attach To An Existing Model

ARTI can discover and attach Recall branches without changing the model class:

```python
import arti

model = arti.ARTI.attach(
    model,
    recall={
        "layers": "model.layers.*",
        "rank": 16,
        "slots": 8,
    },
)

print(model.arti.summary())
model.arti.save("assistant.recall.arti.st")
```

Attachment configuration supports explicit layer paths, per-layer dimensions,
independent Recall lines, Half switches, resource previews, and reversible
removal. Transformers, PEFT, and Diffusers are optional integration boundaries;
the core package remains PyTorch-first.

## Save And Load Weights

ARTI uses SafeTensors with JSON integrity sidecars:

```python
saved = arti.save(layer, "layer.arti.st")
loaded = arti.load("layer.arti.st", model=fresh_layer)

print(saved.weights_sha256)
print(loaded.missing_keys, loaded.unexpected_keys)
```

ARTI 1.x reads compatible format-version 1 artifacts produced by the pre-public
0.x line. Legacy `.pt` migration uses PyTorch's restricted tensor-only loader:

```python
arti.migrate_pt("legacy-state.pt", "layer.arti.st")
```

Artifact hashes detect modification relative to their lock files; they are not
publisher signatures. Obtain models and weights from trusted sources.

## Public Modules

- `arti.nn`: `Layer`, `Half`, `Fold`, `Pulse`, `RecallRefiner`, and visual workspace modules.
- `arti`: complete ARTI layers, residual blocks, reference models, attachment, serialization, and diagnostics.
- `arti.torch`: backend-explicit aliases for PyTorch applications.
- `arti.jax`: optional functional JAX backend with JIT and gradient support.
- `arti.functional`: mask, visibility, pooling, coordinate-frame, and activation helpers.

Experimental and legacy APIs are identified in their docstrings and are not
frozen at the same level as the supported core surface.

## Develop

```bash
git clone https://github.com/ragnarok-io/ARTI.git
cd ARTI
uv sync --extra dev
uv run --extra dev pytest
uv build
```

The test suite covers tensor shapes, masks, gradients, serialization, malformed
artifacts, public API imports, and optional backend boundaries. Contribution
guidance is in [CONTRIBUTING.md](CONTRIBUTING.md).

## Citation And Authorship

ARTI was initiated and designed by [Thiocy](https://github.com/Thiocy).
Citation metadata is provided in [CITATION.cff](CITATION.cff). The project also
documents [authorship](AUTHORS.md) and [AI assistance](AI_ASSISTANCE.md).

## License

[MIT](LICENSE)
