TensorCode#

Website: tensorcode.dev · Docs: tensorcode.dev/docs · Source: GitHub · Changelog

TensorCode is a Python SDK for programs that carry both the logic you can write down and the parameters you have to learn. Write a bounded numerical function. TensorCode compiles it to a circuit that runs exactly, checks out against every declared input, trains only the numbers you mark as trainable, executes as a NumPy program, a PyTorch graph or an attention machine, and saves as a few kilobytes of JSON that load in Python, TypeScript and the browser without evaluating code.

The newest piece turns that into a cost story. A large model costs the same on every request, forever. tensorcode.distill has an authoring model write a small program for a workload you already run through that large model, compiles the reply without executing it, scores it on cases the author never saw, serves it on a CPU in microseconds, escalates the inputs it does not claim, and repairs it from those escalations. The large model runs at authoring time and leaves the request path.

Status: 0.4.0 alpha. APIs may change between alphas. The core package has no dependencies and importing it does not import PyTorch or touch the network. Measured behavior and its limits are in validation. The distillation loop and weight patches are in this source checkout, not yet in a published release, and their measured example uses recorded author replies rather than a live model. Consistent benefits of the learned cognitive workspace are not yet established.

What TensorCode unlocks#

• Rules you verify instead of prompt for. Compile a bounded function over declared integer ranges and check it on every input: 256 cases for one int32(min=-128, max=127), no sampling, no model call. The artifact alone reproduces the rule; nothing is fitted.
• Learned numbers inside readable structure. Mark the thresholds and weights you want learned. Gradient descent moves those and only those. The branches and arithmetic around them stay as written, and a trained algorithm exports to standalone NumPy source you can read.
• One algorithm, three executors. The same artifact runs as a NumPy reference program, a native PyTorch autograd graph and a scheduled attention machine. compare checks any two case by case, and a hard attention machine converts back to the symbolic program. The algorithm's structure can also be projected into a pretrained transformer's attention as a structural prior.
• Distilled programs that serve in microseconds from kilobytes. The recorded ticket-routing example yields a 1,770-byte artifact that runs in about 45 microseconds per call on the reference executor, gives zero wrong answers on the hidden cases it claims, and sends 30% of fresh traffic to the fallback. Agreement is measured against the teacher you supply, never assumed.
• Weight edits as patches you can review. Render tensors as text a model can read, parse the edit statements it writes back with a fixed grammar, and store the change as a hash-pinned JSON patch in sparse, dense, low-rank or projection form. A patch applies to any state dictionary and refuses a base that has drifted.
• Tools that own their models and remember where feedback came from. Investigator, Planner, Chatbot, Decision and Scene train on reviewed feedback with explicit provenance and save as data-only artifacts that reload from disk or the Hugging Face Hub.
• Artifacts are data, never code. JSON configuration and safetensors weights, no pickles. Loading never evaluates source. The same files load in TypeScript, and compiled programs also run in the browser on WebAssembly or WebGPU.

Install#

Python 3.11+:

python -m pip install 'tensorcode[tools]'

From a checkout, use python -m pip install -e '.[tools]'. Choose the extras for the interfaces you use:

Compile a rule without training#

The compiler described here is available in this source checkout. Install the checkout when trying these APIs; this guide does not establish which published package release contains them.

from tensorcode.program import compile, int32

choose = compile("def choose(a): return 10 if a > 4 else 12",
                 inputs={"a": int32(min=-128, max=127)})
assert choose.run({"a": 5}) == {"result": 10}
checked = choose.verify(lambda a: 10 if a > 4 else 12)
assert checked["passed"] and checked["cases"] == 256

This example needs only the core package. From this repository, install it with python -m pip install -e .; add [vec] to train compiled parameters with PyTorch.

The declared integer range makes checking all 256 possible inputs practical. Floating inputs require explicit verification cases. Compilation rejects syntax outside its bounded subset; it is not a compiler for arbitrary application code. The program guide continues with learned corrections, state, gradient policies and cross-language artifacts.

Distill a workload into a program#

Take inputs you already send to a large model, with that model's answers, and have an authoring model write a small program that handles them. The author sees half the workload and gets feedback on it; the other half scores the result once, at the end. Needs tensorcode[algorithm].

from tensorcode.distill import Distillation, distill
from tensorcode.integrations import OpenAICompatibleModel

author = OpenAICompatibleModel(base_url="http://localhost:8000/v1", model="your-served-model")
result = distill(
    "Route a support ticket from twelve 0/1 keyword indicators: features 0-3 are "
    "billing words, 4-7 technical, 8-11 account. Return 0 billing, 1 technical, 2 account.",
    inputs={"features": (12,)},
    workload=[{"features": row} for row in rows],           # inputs you already serve
    targets=[{"route": float(r)} for r in teacher_routes],  # the large model's answers
    author=author,
    attempts=4,
    holdout=0.5,       # this half of the workload is never shown to the author
    min_coverage=0.6,
)
print(result.report["acceptance"])  # agreement on cases the author never saw
result.save("./ticket-router")

program = Distillation.load("./ticket-router")
router = program.router(lambda inputs: {"route": float(frontier_route(inputs))})
answer = router({"features": rows[0]})  # answer["escalated"] names the path taken

The program is one bounded function plus a covered output that says whether it claims the input. A wrong answer while covered is the failure the loop minimizes; abstaining costs one fallback call. repair folds the router's escalations back into the design set and rescores on the same hidden cases, and fit moves only the parameters the author declared. The offline example runs with recorded replies and no network:

python examples/distill/route_tickets.py            # recorded author replies
python examples/distill/route_tickets.py --base-url http://localhost:8000/v1 --model your-served-model

The distillation guide has the report fields, the author's contract, the measured numbers and the weight-patch format.

Train a tool in 30 seconds#

This trains an Investigator to rank two supplied hypotheses from log evidence. It saves the model and reloads it. It runs offline on CPU in a few seconds.

import torch
from tensorcode import training
from tensorcode.tools.investigator import Investigator

torch.manual_seed(0)
model = Investigator({"vocabulary": ["database", "network", "connection", "refused", "packet", "loss"],
                      "dimensions": 16, "slots": 2, "steps": 1})
trainer = training.Trainer.from_tool(model, optimizer=torch.optim.AdamW(model.parameters(), lr=0.01))

hypotheses = [{"id": "database", "text": "database connection refused"},
              {"id": "network", "text": "network packet loss"}]

def case(log_line):
    return {"question": "which component failed",
            "evidence": [{"source_id": "log:1", "text": log_line}],
            "hypotheses": hypotheses}

# Reviewed feedback, with explicit provenance, becomes training experience.
experiences = [trainer.capture(case("connection refused"), "database", source="review:1"),
               trainer.capture(case("packet loss"), "network", source="review:2")]
losses = trainer.fit(experiences, epochs=30)

model.save_pretrained("./investigator")
restored = Investigator.from_pretrained("./investigator")
print(restored(case("packet loss"))["selected_id"])  # network

Two authored cases show the lifecycle. They do not show that the model can investigate anything. The result also includes every candidate's score and the source-linked evidence. Probabilities are uncalibrated. The quickstart extends this to persisted experience files, resumable training checkpoints and loading in a fresh process.

What is inside#

• tensorcode.program: bounded source compiler, numerical circuit builder, reference execution, exhaustive verification over declared integer ranges, event state and optional PyTorch integration.
• tensorcode.algorithm: typed tensor algorithms compiled to a NumPy reference executor (ALG.0), a native PyTorch graph (ALG.1) or a scheduled attention machine (ALG.2), with case-by-case comparison, conversion between substrates, import of supported PyTorch modules and structural priors for pretrained attention.
• tensorcode.distill: the author, verify, serve, route and repair loop; Router with escalation; fit for declared parameters; data-only records of every attempt and case.
• tensorcode.weights: hash-pinned weight patches, text rendering of tensors and a fixed-grammar edit language that is parsed, never evaluated.
• tensorcode.ops.vec, ops.text, ops.graph: operations with one calling convention, op(value, *, context=None). Operations are built from JSON configuration, and learned vector operations own their weights. Text operations wrap an owned seq2seq model or an explicit external provider. Graph operations are reserved symbolic interfaces that raise NotImplementedError.
• tensorcode.tools: Chatbot, Investigator, Decision, Planner and Scene, complete trainable models with save_pretrained / from_pretrained.
• tensorcode.trace() and tensorcode.training: dependency capture, explicit supervision, Trainer.from_tool / Trainer.from_ops, portable experience and complete checkpoints.
• tensorcode.integrations: explicit adapters for OpenAI-compatible endpoints, local Transformers models and Jev.

Generated hypotheses are not evidence, and generated plans are not executable code. Evidence, policies and actions stay explicit in your code. Tracing does not make arbitrary Python or remote model calls differentiable.

Guides#

• Compiled programs: compile known rules, check their outputs, add trainable parameters, and persist state and portable circuits.
• Algorithm substrates: symbolic, differentiable and scheduled-attention execution of one artifact, conversion contracts and the 20-joint MuJoCo robotics policy example.
• Distilled programs and weight patches: author, verify, route and repair small programs from a teacher's answers; hash-pinned patches.
• Quickstart: a runnable offline training lifecycle.
• Developer documentation: operation and model contracts.
• Pretrained checkpoints: hosted tools and their measured scope. All eight hosted checkpoints load at main with this release. The two Chatbots and the cognitive Investigator were retrained for the bounded workspace update; their earlier revisions stay pinned for source commit 6607a8b.
• Evidence and cognition: hypotheses, revisions, memory and outcome feedback.
• Training: tracing, replay and resumable checkpoints.
• Examples: learning agents and practical applications.
• Validation: measured behavior and limitations.
• Updating development code: import changes since earlier alphas.

Development#

python -m pip install -e '.[tools,diffusion,dev]'
python -m pytest -q
python -m build

Library code lives in src/tensorcode. See the test guide for how the suite is organized. This alpha API replaces the former provider-owned tools, and there is no legacy compatibility layer. MIT license.