TensorCode for TypeScript#

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

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, and it runs in Node.js with no runtime dependencies.

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 (Python 0.4.0a4). 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.

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. Pure computation is synchronous.

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#

• 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; needs neither Python nor network
node examples/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.