Metadata-Version: 2.4
Name: arti-fit
Version: 3.0.12
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: 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: 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: 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: 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: 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: 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'
Provides-Extra: web
Requires-Dist: onnx>=1.16; extra == 'web'
Requires-Dist: onnxscript>=0.3; extra == 'web'
Description-Content-Type: text/markdown

# ARTI

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

ARTI is a domain-independent neural-network library for transforming hidden
tensors at runtime. It provides versioned components for activation, compact
workspaces, Recall, Formula execution, reversible topology, persistent tensor
operations, and model attachment.

```text
tensor input -> ARTI layer or mechanism -> tensor output
```

ARTI does not prescribe a tokenizer, task head, dataset, model family, or
training loop. Applications decide what a tensor means; ARTI supplies reusable
ways to observe, route, transform, remember, and compose it.

## Install

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

```bash
uv add "arti-fit==3.0.12"
```

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.

Optional integrations are installed only when needed:

```bash
uv add "arti-fit[jax]==3.0.12"
uv add "arti-fit[qwen]==3.0.12"
uv add "arti-fit[sd]==3.0.12"
uv add "arti-fit[web]==3.0.12"
```

The browser runtime remains a separate alpha package:

```bash
pnpm add @arti-fit/web@alpha
```

## Stable 3.0.12

This release restores real K-wide Recall traversal and extends Formula Fabric
with stable typed atoms for nonlinear maps, broadcast, selection, lookup,
slicing, concatenation, and masked softmax. It also ships optional alpha
components for bounded Formula program selection and shape-polymorphic Federal
Bank execution. Alpha component identities remain explicitly marked in the
registry even though they are distributed in the stable package.

`arti.ARTILayer` is now `arti/layer@2`: a tensor-in/tensor-out host for one
composable `AdaptivePulse` graph. An empty graph is an exact identity, so a
layer can be inserted before an application chooses its mechanisms.

```python
import torch
import arti

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

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

Build a layer from ordinary ARTI modules:

```python
pulse = arti.mechanisms.AdaptivePulse(
    half=arti.Half(stochastic=False, learnable=True),
)
layer = arti.ARTILayer(pulse)
y, info = layer(x, return_info=True)
```

The public namespaces have explicit roles:

- `arti` and `arti.torch`: stable high-level PyTorch APIs.
- `arti.nn`: practical standalone tensor layers and explicit layer profiles.
- `arti.mechanisms`: stable, versioned composition/runtime mechanisms.
- `arti.legacy`: the retired monolithic `ARTILayer@1`, `LayerRecall`, and
  `StatefulRecall`, retained for historical artifact inspection.
- `arti.experimental`: integrations that are still experimental; currently the
  Python-first Web exporter.

`arti.alpha` remains a compatibility name for `arti.mechanisms`; new code should
use the stable namespace.

## Attach To A Model

Attach an AdaptivePulse-backed layer to selected tensor boundaries without
changing the host model class:

```python
import arti

pulse = arti.mechanisms.AdaptivePulse(
    half=arti.Half(stochastic=False, learnable=True),
)
layer = arti.ARTILayer(pulse)

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

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

Reload into a fresh host or remove the attached layers:

```python
restored = arti.ARTI.load(fresh_model, "assistant.arti.st", layer=layer)
restored = restored.arti.detach()
```

Attachment preserves the host model type and arbitrary tensor trees. Boundary
values are packed for ARTI execution and restored to their original rank,
layout, dtype, and position. See [Unified Attachment](docs/unified-attachment.md).

## Mechanism Map

| Need | API |
| --- | --- |
| Same-shape survival pressure | `arti.Half` |
| Soft learned workspace compaction | `arti.nn.Fold` |
| Trainable learned expansion | `arti.nn.UnFold` |
| Reversible active/folded topology | `arti.mechanisms.Fold`, `arti.mechanisms.UnFold` |
| Compact learned pulse workspace | `arti.Pulse` |
| Composable bounded execution graph | `arti.mechanisms.AdaptivePulse` |
| K-wide Recall with hard winner | `arti.nn.Recall` |
| Iterative hidden-state refinement | `arti.RecallRefiner` |
| Typed Formula programs | `arti.mechanisms.FormulaFabricV2` |
| Bounded typed program selection (alpha) | `arti.mechanisms.FormulaProgramQuery` |
| Addressable forward Bank updates | `arti.mechanisms.TargetBankUpdater` |
| Shape-autonomous Bank hierarchy | `arti.mechanisms.FederalRecall` |
| Persistent auxiliary tensor editing | `arti.mechanisms.TensorOperationLoop` |

All mechanisms remain independently usable. Coordinates, masks, visibility,
Observation, Recall, Formula, Fold, and tensor operations are not mandatory
parts of one monolithic architecture.

## Recall

New `arti.nn.Recall` modules use `arti/recall@4`. One query can preserve K
candidate routes, refine them independently, and forward exactly one hard
winner. Weighted merging is opt-in.

```python
recall = arti.nn.Recall(dim=768, slots=64)  # portable default K=8
next_state = recall(x)

wide = arti.nn.Recall(dim=768, slots=64, breadth=16, group_topk=16)
next_state, branches = wide(x, return_branches=True)
next_state = wide(x, active_k=4)
```

Eight is the portable default; 8-32 is a useful starting range when Bank
capacity and runtime budget allow. `breadth=1` executes one candidate.

Runtime refine depth is explicit and may be adjusted without rewriting an
artifact:

```python
arti.set_recall_refine_steps(model, 10, min_steps=2, tolerance=0.003)
arti.set_recall_refine_schedule(
    model,
    {
        "model.layers.0": 2,
        "model.layers.1": 6,
        "model.layers.2": 12,
    },
)
```

## Formula And Federal Banks

Formula Fabric executes bounded, typed tensor programs with declared operands,
shapes, route sources, and output contracts. Built-in atoms include ordinary
tensor transforms as well as Fabric-native Fold and UnFold operations.

The stable atom basis can compose Transformer-like subgraphs without hiding an
opaque Attention, MLP, or Transformer primitive. `FormulaProgramQuery@1` is an
alpha controller for selecting a bounded, shape-valid SSA path from final task
loss; it chooses one hard candidate per step rather than averaging outputs.

Federal Banks can carry their own sealed Query, Formula program, local Refine
policy, and terminal ABI. A Bank may change its tensor shape internally and
re-query after every local step; it leaves the Bank only after producing a
value accepted by the shared terminal contract. This separates federation
depth from Bank-local computation depth.

See [Formula Fabric](docs/formula-fabric.md) and
[Federal Contracts](docs/federal-contracts.md).

## Operable Tensors

The tensor-operation API supplies a default-backed, hot-swappable auxiliary
tensor port. Reader Refine and tensor operations consume the same call-boundary
snapshot in parallel. Operations can address ranges or sparse index maps of an
arbitrary-rank logical tensor; proposals become visible after the caller
advances the port for a later invocation.

See [Operable Tensor Port](docs/operable-tensor-port.md).

## Artifacts

`arti.save()` and `arti.load()` store model state in SafeTensors with separate
architecture metadata and SHA-256 locks. Component identities and artifact
schemas are versioned independently from the package version.

Recall Bank artifacts record the host, reader, Formula, optional Updater, Bank
layout, dtype, shapes, provenance, and tensor hashes. Named compatible Banks
can be composed without silently changing their source identity.

See [Recall Artifacts](docs/recall-artifacts.md) and
[Component Provenance](docs/component-provenance.md).

## Documentation

- [Stable Release Surface](docs/stable-release-surface.md)
- [Unified Attachment](docs/unified-attachment.md)
- [Adaptive Observation](docs/adaptive-observation.md)
- [Reversible Topology](docs/reversible-topology.md)
- [Formula Fabric](docs/formula-fabric.md)
- [Federal Contracts](docs/federal-contracts.md)
- [Batched Refine](docs/batched-refine.md)
- [Flattened Refine Training](docs/flattened-refine-training.md)
- [Refine Exit](docs/refine-exit.md)
- [Operable Tensor Port](docs/operable-tensor-port.md)
- [WebGPU Alpha](docs/webgpu-alpha.md)

## Development

```bash
uv sync --locked --extra dev
uv run --extra dev pytest
uv build
uv run --extra dev python scripts/check_package.py
```

Public CI runs Python 3.10, 3.11, and 3.12, the optional JAX contract suite,
the Python-owned Web artifact generator, and the TypeScript browser runtime.

## Scope

Stable means the documented component identities, tensor contracts, artifact
formats, and composition semantics are reviewed and release-gated. It does not
claim universal downstream superiority, a production service SLA, full JAX
parity, or WebGPU training.

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

## 中文简介

ARTI 是一个领域无关、PyTorch-first 的可组合张量动力学基础库。3.0.12
将 `AdaptivePulse` 设为默认 `ARTILayer` 的执行图，并把经过版本化和验证的
Recall、Formula、Fold/UnFold、Bank、Observation、TensorOperation 与
Federal Bank 机制提升为稳定 API。应用负责张量的业务语义，ARTI 负责张量
的观察、路由、变换、记忆与组合。
