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.13a5"

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.13a5"
uv add "arti-fit[qwen]==3.0.13a5"
uv add "arti-fit[sd]==3.0.13a5"
uv add "arti-fit[web]==3.0.13a5"

The browser runtime remains a separate alpha package:

pnpm add @arti-fit/web@alpha

Alpha 3.0.13a5

This prerelease adds two controlled alpha compilation surfaces. Federal path compilation lowers an already selected, bounded Federal route into an ordinary layerwise PyTorch graph. Tensorized Query, Federation, stateful transition, and ragged-shape compilers are available from arti.alpha; they reject runtime callbacks, mutable unrepresented state, and data-dependent shapes instead of silently approximating them.

RCC adds a host adapter that captures context from arbitrary host layers and consumes the compiled context at a separately selected input head. The host owns position and attention-mask conventions, so context remains late-bound and is not assigned an absolute position by ARTI. These compiler and host integration APIs are alpha and do not change the stable ARTILayer surface.

The preceding 3.0.13a4 prerelease added automatic CUDA grouped Formula forward/backward execution and prepared typed device dispatch. Compatible numerical groups can be compiled individually or as one ordinary dispatch graph before CUDA Graph capture. On supported CUDA environments, the first uncaptured call prepares compiled execution and later calls reuse it. The caller owns the capture boundary; fixed forward, loss and first-order gradient computation can share one graph. CPU and older PyTorch retain native execution. Explicit native mode is available for debugging. Neither grouping nor compilation changes Formula mathematics or Bank ownership.

This prerelease adds automatic CUDA grouped Formula forward/backward execution and prepared typed device dispatch. Compatible numerical groups can be compiled individually or as one ordinary dispatch graph before CUDA Graph capture. On supported CUDA environments, the first uncaptured call prepares compiled execution and later calls reuse it. The caller owns the capture boundary; fixed forward, loss and first-order gradient computation can share one graph. CPU and older PyTorch retain native execution. Explicit native mode is available for debugging. Neither grouping nor compilation changes Formula mathematics or Bank ownership.

The execution foundation includes named-output and nested program candidates, typed pools, device-side routing, and the versioned Formula operands they use. Low-level acceleration interfaces remain experimental. Automatic compilation requires PyTorch 2.11 or newer. Compiled and captured paths require an appropriate PyTorch/compiler/device environment; they are not an automatic speed guarantee for arbitrary dynamic models or optimizer steps. See prepared execution and the grouped training example.

The preceding release added FormulaProgramQueryV4.execute_many(...): compatible inference candidates share a checked Formula execution plan, with optional chunking before input stacking. Training keeps each candidate's autograd graph independent while aggregating finite-value checks. Immutable program fingerprints are cached; live tensor and Bank validation is not. Neither path changes search width, Bank capacity, predecessor ownership, or commit semantics.

See the candidate execution guide and batching example. This low-level entry point does not implement a new searcher or automatically commit state.

The 3.0.13a2 correction makes NeuralPlasticity modify the actual Bank Value used by its ordinary Formula predecessor. The effect's data output remains the same tensor. It has no separate effect-owned memory or caller-selected write target.

FormulaProgramQueryV3 commits a selected stopped path for later invocations. FormulaProgramQueryV4 additionally lets the same Bank owner re-execute with its branch-local successor during one forward. Other branches stay isolated; only the selected execution can be committed to persistent Bank buffers.

Ordinary Formula candidates and six plasticity families can share the search space. A bounded, optionally trainable execution-count operand controls repeated transitions. The old alpha FormulaProgramQueryV2 state-arena API is removed; rebuild those programs with predecessor-owned Bank slots. These alpha changes do not expand or replace the stable compatibility surface.

See the Formula Fabric guide and runnable example. The example demonstrates writeback and reload, not downstream task-quality superiority.

The stable 3.0.12 base retains K-wide Recall traversal, the typed Formula atom basis, shape-polymorphic Federal Bank execution, and the default AdaptivePulse-backed ARTILayer described below.

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.

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.

FormulaProgramQuery@3 extends that search to predecessor-owned Bank effects with commit-visible successors. FormulaProgramQuery@4 additionally permits the same producer to re-execute using its branch-local successor. Query sees ordinary SSA tensors, not a direct state input. Persistent commit_() installs only the selected stopped execution and detaches its state from the training graph.

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
• Federal Compilation
• Recursive Context Compilation
• 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.13a5 新增受限的 Federal 路径、Query、状态图和 RCC 主机编译 alpha 接口；3.0.13a4 在受支持的 CUDA 环境默认启用 Formula 分组前向与反向及 typed device dispatch 融合， 并提供固定计算片段的 CUDA Graph 执行支持。张量、梯度和 Bank 归属语义保持不变，并保留 在 3.0.12 稳定表面之上完成的 alpha 级 NeuralPlasticity 前序 Bank 写回纠正与 可搜索的自修改程序拓扑：网络从局部候选中学习自修改节点的数量、顺序、位置 和连接，而不是由调用者预先拼好完整链。应用负责张量的业务语义，ARTI 负责 张量的观察、路由、变换、记忆与组合。