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.

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:

uv add "arti-fit==3.0.11"

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:

uv add "arti-fit[jax]==3.0.11"
uv add "arti-fit[qwen]==3.0.11"
uv add "arti-fit[sd]==3.0.11"
uv add "arti-fit[web]==3.0.11"

The browser runtime remains a separate alpha package:

pnpm add @arti-fit/web@alpha

Stable 3.0.11

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.

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:

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:

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:

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.

Mechanism Map

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.

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:

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.

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 and Federal Contracts.

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.

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 and Component Provenance.

Documentation

• Stable Release Surface
• Unified Attachment
• Adaptive Observation
• Reversible Topology
• Formula Fabric
• Federal Contracts
• Batched Refine
• Flattened Refine Training
• Refine Exit
• Operable Tensor Port
• WebGPU Alpha

Development

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. Citation metadata is in CITATION.cff.

中文简介

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