TensorCode for TypeScript#

Website: tensorcode.dev · Docs: tensorcode.dev/docs · Source: GitHub · Python package: tensacode-py

TensorCode represents deterministic rules and learned behavior in one SDK. Compile a bounded numerical function to run without training, or compose its circuit with explicitly trainable parameters. The source compiler and existing operation tracing serve different purposes: compilation captures supported arithmetic and control flow; tracing records calls between operations.

TensorCode builds trainable programs from callable operations and small tools that own their models. This is the TypeScript port of the Python tensorcode package. It has the same operations, tools, tracing, training and artifact formats. Its numerical engine has no native dependencies; source compilation uses the bundled npm dependency typescript.

You can compose encoders, scorers and decoders (tensorcode/ops/*) or use a complete tool such as Investigator, Planner or Chatbot (tensorcode/tools). Collect reviewed feedback with explicit provenance, train it with the built-in autograd core, and save everything as a data-only artifact. The artifact reloads in a fresh process, from the Hugging Face Hub, or in the Python package. Tracing records which operation produced which value, so supervised local tensor paths can be replayed and trained. Tracing does not make arbitrary JavaScript or remote model calls differentiable.

Status: 0.4.0 alpha (both SDKs). APIs may change between alphas. Importing any entry point performs no I/O and loads no model weights. The measured behavior and its limits are documented at tensorcode.dev/docs. Consistent benefits of the learned cognitive workspace are not yet established.

Install#

This needs Node.js 20.16 or newer:

npm install tensorcode

The package is ESM-only (import, not require) and ships its own type declarations. The optional peer @huggingface/transformers is only needed for integrations.LocalModel.

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.

import { compile, int32 } from 'tensorcode/program';

const choose = compile((a: number) => a > 4 ? 10 : 12, {
  inputs: { a: int32({ min: -128, max: 127 }) },
  semantics: 'exact',
});
console.log(choose.run({ a: 5 })); // { result: 10 }
console.log(choose.verify()); // passed: true, cases: 256, exhaustive: true

Run npm install in this repository to build the checkout before running it.

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.

30-second example#

This trains an Investigator to rank two supplied hypotheses from log evidence, saves the model and reloads it. It runs offline on CPU in well under a second. Save it as quickstart.mts and run node quickstart.mts (Node 22.18 or newer runs TypeScript directly; otherwise use npx tsx quickstart.mts).

import { AdamW, manualSeed } from 'tensorcode/nn';
import { Investigator } from 'tensorcode/tools';
import { Trainer } from 'tensorcode/training';

manualSeed(0);
const model = new Investigator({
  vocabulary: ['database', 'network', 'connection', 'refused', 'packet', 'loss'],
  dimensions: 16, slots: 2, steps: 1,
});
const trainer = Trainer.fromTool(model, { optimizer: (params) => new AdamW(params, { lr: 0.01 }) });

const hypotheses = [
  { id: 'database', text: 'database connection refused' },
  { id: 'network', text: 'network packet loss' },
];
const incident = (logLine: string) => ({
  question: 'which component failed',
  evidence: [{ source_id: 'log:1', text: logLine }],
  hypotheses,
});

// Reviewed feedback, with explicit provenance, becomes training experience.
const experiences = [
  trainer.capture(incident('connection refused'), 'database', { source: 'review:1' }),
  trainer.capture(incident('packet loss'), 'network', { source: 'review:2' }),
];
const losses = trainer.fit(experiences, { epochs: 30 });

await model.savePretrained('./investigator');
const restored = await Investigator.fromPretrained('./investigator');
console.log(restored.call(incident('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 with persisted experience files, resumable training checkpoints and loading in a fresh process.

What is inside#

Generated hypotheses are not evidence, and generated plans are not executable code. Evidence, policies and actions stay explicit in your code.

The TypeScript API uses camelCase (savePretrained, fromPretrained, Trainer.fromTool, loadExperience). Persisted data keeps Python's snake_case (selected_id, tensorcode_config.json fields, experience files), so the two implementations can share artifacts. Anything that touches the filesystem or network returns a Promise. CPU computation is synchronous; program WebGPU batch execution is asynchronous.

Parity with Python#

Parity with Python explains how parity is checked, which files move between the two languages and the few remaining differences. DESIGN.md maps each Python module to its TypeScript file.

Guides#

• Compiled programs: compile known rules, check their outputs, add trainable parameters, and persist state and portable circuits.

• Quickstart: the offline training lifecycle, end to end.

• Operations: vector, text and graph operations, providers and custom operations.

• Tools: Chatbot, Investigator, Decision, Planner and Scene, pretrained artifacts and the Hub.

• Training: tracing, experience, replay, checkpoints and calibration.

• Examples: runnable programs.

• Parity with Python: what matches, what is interchangeable and what still differs.

• Changelog.

• Full documentation, validation results and the Python guides: tensorcode.dev/docs.

Development#

npm install          # also builds dist/ through the prepare script
npm run typecheck    # tsc --noEmit over src and tests
npm run build        # tsc -> dist/
npm test             # vitest; program interoperability tests need python3 and ../python/src
node examples/cognition/investigatorQuickstart.ts

Library code lives in src/. Tests in test/ port the Python suite and check parity against fixtures generated by the Python package (npm run fixtures -- <generator>, which needs ../python/.venv). Tests that need a cached Hugging Face checkpoint skip when it is absent. MIT license.

Algorithm substrates#

The current checkout supports typed tensor algorithms across symbolic (ALG.0), differentiable circuit (ALG.1), and scheduled attention (ALG.2) execution. See algorithm substrates for conversion contracts and the 20-joint MuJoCo robotics policy example. Structural priors and exact execution have separate guarantees.