Examples#

Start with the pretrained checkpoint catalog for complete Hub-loaded tools and their measured limits.

These are complete programs for supplied input files and sourced datasets. Owned-model training and explicit provider-backed applications are separate paths. They use public TensorCode operations and tools, expose their model/policy choices, and can be adapted without adopting an application framework.

Install from the checkout with python -m pip install -e '.[tools]' (owned tools and transformers) or '.[vec]' for vector-only examples. Run commands from the repository root. The HTTP examples require your own running OpenAI-compatible model; replace your-served-model with its actual model ID. Hosted credentials come from OPENAI_API_KEY, or the variable named by --api-key-env. Selected file contents are sent to the endpoint you configure.

Compare a cognitive component#

compare_cognitive_verifiers.py replaces only an explicitly selected verifier in an existing complete cognitive Chatbot. Its bootstrap command fits temperature on 256 pinned SNLI validation pairs, checks all other components are unchanged, and verifies full artifact reload. evaluate runs supplied case JSONL through the public tool, retains complete receipts and runs omission/replacement controls plus an authored conflicting-source fixture. These commands require the designated CUDA host and pyarrow in addition to the tools dependencies.

Use recover-development only to reproduce historical cases as development data. Freeze model/configuration choices before evaluating new cases; manually review non-abstained answers against sources and gold answers. NLI approval and lexical containment do not establish correctness. No classifier weights are trained by this example, and a better verifier does not establish a workspace advantage.

Train an appended encoder readout#

OUTPUT_ENCODING learning accepts supplied JSONL {"text": "input text", "target": "reviewed output"} rows. It initializes the encoder and decoder, captures their connected computation, saves and reloads experience, trains the readout token and decoder bridge, then saves and reloads both complete operations. Native foundations stay frozen.

python examples/output_encoding_learning.py --foundation /local/flan-t5-small \
  --revision <pinned-revision> --data reviewed.jsonl --output /tmp/readout-run

Run real models on a training host. This example measures supplied training pairs and restores weights; it does not claim generalization or optimizer continuation.

Pretrained vector operations#

Install python -m pip install -e '.[pretrained]', then run the bounded latent lifecycle on a suitable GPU host:

python examples/pretrained_latent_lifecycle.py --output /tmp/latent-run --device cuda

It initializes the operations before collection, compares native text behavior, trains a linear adapter on four explicitly authored pairs, and restores both model weights and optimizer progress. This demonstrates the training lifecycle; four examples do not establish generalization. The optional --image-input /path/to/photo.jpg adds ViT encoding and diffusion generation; install .[diffusion] for that path. Foundation downloads are pinned and artifacts stay in the selected output directory. See the vector model guide for conditioning contracts and supported architectures.

Owned cognitive models#

Install python -m pip install -e '.[tools]'. Start with the offline quickstart to construct an Investigator, collect sourced feedback, persist experience, train and save a complete model that loads in a fresh process. The same Trainer.from_tool(...) lifecycle applies to Planner and Chatbot with their declared target formats.

Train cognitive tools trains owned Investigator and Planner models on pinned HotpotQA document-support annotations. It records held-out results before/after training, a workspace ablation and restored-model parity. Install pyarrow in addition to the tools extra and inspect --help for sample counts and output paths. It downloads the selected dataset shards. Planner feedback in this experiment is document relevance, not observed outcomes of executed plans. Supplied candidate passages do not demonstrate hypothesis generation or general planning. See validation for actual measurements.

Train a chatbot accepts disjoint UTF-8 training/test JSONL files. Each row requires nonempty id, input, and target; inputs must contain only evidence available at inference time. For conversational training, use the same user: ... / assistant: ... transcript convention used by the chatbot. This illustrative record shows the schema, not a training dataset:

{"id":"review:17","input":"user: Which service failed? Evidence: database refused the connection.","target":"The database connection failed."}

python examples/train_chatbot.py --train reviewed-train.jsonl \
  --test reviewed-test.jsonl --output /tmp/chatbot-run --device cpu
python examples/pretrained_chatbot.py /tmp/chatbot-run/model \
  --prompt 'Which evidence should we examine next?' --save-session /tmp/session.json

Training explicitly bootstraps the pinned foundation selected by --foundation and --revision, so the first command may download weights. Set --local-files-only to require cached assets. A freshly initialized workspace is not a pretrained cognitive tool; assess the resulting held-out report before using its saved model. The inference CLI also accepts a TensorCode Hub repository and --revision, and supports interactive sessions when --prompt is omitted.

The hypothesis and plan scripts below deliberately remain smaller direct-operation examples. They explain mechanisms without presenting an authored fixture or a random model as a pretrained cognitive agent.

Train proposal generation and response realization separately#

Hypothesis training joins human QA2D declarations to the original SQuAD question and source paragraph. Only that original question and paragraph enter the proposal prompt. Short answers, human target declarations and rule-generated QA2D outputs do not enter its inputs. The human declaration is a training target. Splits separate documents and context within this run; they do not establish that the foundation never saw the benchmark during pretraining.

Prepare data, then run substantial training on the designated CUDA training host:

python examples/train_hypotheses.py --data /tmp/hypothesis-data --prepare-only
python examples/train_hypotheses.py --data /tmp/hypothesis-data \
  --output /tmp/hypothesis-model --device cuda

The script supports pinned --foundation/--revision, --local-files-only, --resume, and an optional --verifier-path. Inspect --help for dataset sizes and training controls. NLI evaluation is a model judgment, not verified truth.

Realization training reads the prepared training/development partitions and teaches the decoder to preserve an already selected statement:

python examples/train_realization.py --data /tmp/hypothesis-data \
  --output /tmp/realization-model --foundation google/flan-t5-base --device cuda

Here the human declaration intentionally appears both in the selected-hypothesis input field and as the target. This measures copying/realization of a known statement, not question answering or inference from evidence. Original question and context remain in the prompt, token limits are checked, and the script does not open the prepared test partition. The two training tasks must not be conflated when interpreting metrics. Their saved models are language components, not proof that an entire cognitive chatbot is ready for arbitrary tasks.

Collect feedback from executed actions#

Action-outcome learning runs an explicitly authored service-recovery simulation. All model parameters exist before collection. Labels come from actual simulator transitions, not from assigning assumed outcomes to unexecuted alternatives. Action names, reward, exploration and environment rules are application fixtures; they are not general core policies.

python examples/learn_action_outcomes.py --output /tmp/action-outcome-run --epochs 18

The output includes sourced traces, observed trajectories, a model directory, a separate training checkpoint, session state and a report. The script reloads weights and saved experience, checks restored session/trajectory state and resumes an optimizer update. To load the resulting predictor:

from tensorcode.tools.planner import Planner

planner = Planner.from_pretrained("/tmp/action-outcome-run/model")
result = planner({
    "goal": "restore service",
    "evidence": [{"source_id": "simulation:new", "text": "status hot"}],
    "plans": [{"id": "cool", "text": "cool"},
              {"id": "reindex", "text": "reindex"},
              {"id": "serve", "text": "serve"}],
})
print(result["selected_id"])

The model returns a prediction; it does not execute the chosen action. The example explicitly converts candidate IDs into registered structured actions and replans from observed state. Disjoint scenario IDs still share the same authored status classes, so the evaluation is a simulation mechanism check, not a demonstration of novel-task or production competence.

For owned hypothesis generation, source-wise verification and chatbot evidence revisions, see the cognitive API guide. Those examples need a compatible complete artifact; a ranking-only checkpoint cannot supply missing generation or verification weights.

Learn from images and relational descriptions#

Scene learning initializes an owned image/text model before training, captures a sourced experience, trains on supplied image/candidate rows, saves model and training artifacts separately, reloads weights, and reports full-image, blank-image, zero-workspace and bypass-workspace evaluations. Install python -m pip install -e '.[tools]' and python -m pip install pillow.

Training and test JSONL rows use the following schema. This is an illustrative record; supply your own images and reviewed labels:

{"image_path":"photos/table.jpg","source_id":"photo:17","question":"Which description matches?","candidates":[{"id":"left","text":"The cup is left of the plate."},{"id":"right","text":"The cup is right of the plate."}],"target":"left"}

Relative image paths resolve beside the JSONL file. Images are converted to RGB and resized to the requested square size; patch coordinates refer to that resized image. Keep training/evaluation image sources disjoint. The script rejects repeated source IDs across the splits, so use stable IDs for the same photograph.

python examples/train_scene.py --train scene-train.jsonl --test scene-test.jsonl \
  --model /tmp/scene-model --epochs 10 --image-size 64 --report /tmp/scene-report.json
python examples/train_scene.py --test scene-test.jsonl --model /tmp/scene-model \
  --image-size 64 --report /tmp/scene-reloaded.json

The second command evaluates saved weights without training and can also accept a compatible TensorCode Hub model ID. Use the same preprocessing as training. Candidate descriptions and labels are supplied data; the program does not create an autonomous scene graph. Accuracy and ablations measure candidate ranking, while attention remains a routing diagnostic. See validation for real-data results and their limitations.

Direct operation learning: initialize, collect, train, save and load#

Install python -m pip install -e '.[vec]' for the learning examples. These run locally with randomly initialized PyTorch models; no API key or pretrained weights are required. from tensorcode.ops import vec is the public vector namespace.

Owned vector lifecycle is a small offline example using only JSON-configured owned operations. It collects sourced experience, trains, saves model artifacts and a separate optimizer checkpoint, reloads both, asserts exact prediction parity, then resumes one update:

python examples/owned_vector_lifecycle.py --output /tmp/owned-vector-run

The two authored cases test lifecycle mechanics, not predictive quality.

Both learning-agent programs construct their operations in bindings(manifest) before processing input. Their lifecycle is explicit:

1. Collect: build the vocabulary from training evidence, initialize all operations, save initial-checkpoint/, and capture traces with sourced feedback.
2. Train: construct compatible operations again, load the initial weights and saved experiences, replay the DAG with gradients, and save trained-checkpoint/ with optimizer state.
3. Predict: construct fresh operations, load learned weights, and process new input. Each command can run in a separate process.

Keep artifacts outside the checkout and use a new directory for each collection. The scripts' train commands fit the collected dataset from the initial checkpoint; they do not resume an interrupted optimizer or automatically collect new feedback. The training API also supports restoring optimizer state. The quickstart shows this lifecycle in one short program.

Revise hypotheses as evidence arrives#

Hypothesis learning models a small interpretation workspace: source evidence accumulates, a learned classifier revises its distribution over supplied hypotheses, and an authored display renders the selected interpretation. For example, use reviewed incident investigations, support conversations, or research annotations where each evidence prefix has its own reviewed interpretation.

Collection JSONL has case_id and ordered evidence entries. This illustrative record shows the schema; replace it with actual reviewed cases:

{"case_id":"incident-17","evidence":[{"source_id":"ticket:17","text":"Requests are timing out.","target":"unresolved","reviewer":"review:17:1"},{"source_id":"log:17","text":"Service workers cannot connect to the database.","target":"service_fault","reviewer":"review:17:2"}]}

A target applies to the evidence available at that step. Do not copy the final incident diagnosis onto earlier prefixes that could not support it. Hypothesis names and reviewer identities are caller supplied, and never appended to the text that the encoder learns from.

python examples/hypothesis_learning.py collect --input reviewed-cases.jsonl \
  --hypothesis unresolved --hypothesis service_fault --artifacts /tmp/hypothesis-model
python examples/hypothesis_learning.py train --artifacts /tmp/hypothesis-model --epochs 30
python examples/hypothesis_learning.py predict --input new-cases.jsonl \
  --artifacts /tmp/hypothesis-model

Prediction JSONL uses the same case/evidence structure with only source_id and text in each evidence entry. Output retains the evidence prefix, full hypothesis distribution, selected interpretation and whether it changed since the previous step. The artifact directory retains original evidence and review provenance.

The learned mechanism is a mean-pooled text encoder and classifier. It learns associations from reviewed text; it does not discover new hypotheses, reason about causality, or reliably represent negation, evidence order or source reliability. Distributions are uncalibrated. Revision is observable behavior, not a guarantee that later evidence will produce a better interpretation.

Learn which supplied plans tend to work#

Plan learning encodes a task, its evidence and each candidate plan, predicts a numeric outcome, then selects the highest-scoring candidate. Possible applications include ranking troubleshooting procedures, experiment plans, or job-recovery strategies from historical results.

Collection JSONL contains id, task, evidence (id, text) and observed plans (id, text, outcome, source). This illustrative record describes one observed action; it does not assign invented outcomes to untried alternatives:

{"id":"incident-17","task":"restore checkout","evidence":[{"id":"log:17","text":"Errors began after deployment."}],"plans":[{"id":"rollback","text":"Restore the previous deployment.","outcome":1.0,"source":"incident:17:recovery-observation"}]}

Use a consistent numeric outcome scale where higher is better. Each training row may contain just the plan actually tried. Include multiple outcomes only when those observations exist; an unchosen plan does not receive an automatic zero.

python examples/plan_learning.py collect --input observed-plans.jsonl \
  --artifacts /tmp/plan-model
python examples/plan_learning.py train --artifacts /tmp/plan-model --epochs 100
python examples/plan_learning.py predict --input candidate-plans.jsonl \
  --artifacts /tmp/plan-model

Prediction uses the same task/evidence structure with all candidate plans, omitting outcome and source. Every candidate is scored before selection. Output retains the task, source evidence, candidate descriptions and scores; it never executes the selected plan. Historical observations remain in the artifact directory.

To compare against initial weights, add --checkpoint initial-checkpoint. If prediction input includes sourced outcomes for every candidate, output also includes held-out MSE and rejects overlapping training IDs/inputs. Ordinary unlabeled prediction can revisit a known task. Hold out whole tasks, not just different plan rows from the same task, when measuring generalization.

The neural encoder and outcome predictor learn from feedback. Candidate generation, the text representation and highest-score selection are authored policies. Scores are uncalibrated estimates, not confidence or causal effects. Historical action selection can bias them; this example does not estimate counterfactual outcomes or learn a world model. Mechanism tests use explicitly authored outcomes, not evidence of real-world planning quality.

Route support tickets#

Export tickets as UTF-8 JSONL, one object per line with id and text fields:

{"id":"case-1042","text":"Our team cannot sign in after enabling SSO."}

Supply your own policy file defining the routes and when to abstain:

python examples/support_triage.py --input tickets.jsonl --policy routing-policy.txt \
  --label billing --label incident --label question \
  --base-url http://localhost:8000/v1 --model your-served-model \
  --output routes.jsonl

Output preserves ticket IDs and order. The script does not invent missing confidence or replace invalid model answers with a default route. Limits on ticket count, ticket length and policy length are available in --help.

Search a handbook#

python examples/document_search.py --directory ./handbook \
  --query 'How do I recover access after losing my MFA device?' --top-k 3 \
  --base-url http://localhost:8000/v1 --model your-served-model

The program chunks visible UTF-8 .txt/.md files, asks the model to retrieve existing chunks, and generates an answer from selected excerpts. Output includes relative file paths, character offsets and excerpt text. Unknown or missing citation IDs are rejected. A valid citation identifies an excerpt; it does not prove the claim follows from it.

This is intentionally for small collections, with explicit file, chunk and request-size limits. It sends candidate excerpts to the model rather than building a scalable embedding index. Hidden paths and symlinks are skipped.

Inspect an image#

Use an explicitly configured remote multimodal model:

python examples/image_inspection.py ./photos/equipment.jpg \
  'Describe the visible controls and any readable labels.' \
  --base-url http://localhost:8000/v1 --model your-served-model

Or install .[local] and use a model you have already downloaded:

python examples/image_inspection.py ./photos/equipment.jpg \
  'Describe the visible controls and any readable labels.' \
  --local-model Qwen/Qwen3-VL-2B-Instruct \
  --revision 89644892e4d85e24eaac8bacfd4f463576704203 --device cuda

Local loading is offline unless you explicitly pass --allow-download. MIME type comes from the image filename, and the message retains its source reference. Answers are model output, not independently verified visual facts.

Let a model choose bounded research actions#

python examples/research_assistant.py ./handbook \
  'What steps does our incident process require before closing an incident?' \
  --base-url http://localhost:8000/v1 --model your-served-model --max-steps 6

The model chooses among a lexical search action, fixed document-read actions and finish. It cannot invent a path or execute a shell command. The result includes its stop reason, read sources and receipts; exhausting the action budget does not count as a finished answer. Search ranking is an authored term-count algorithm. This demonstrates a bounded agent composition, not an unrestricted autonomous researcher. Source IDs are checked; factual correctness still needs evaluation.

Durable text learning#

Obtain the official train/test CSVs from PolyAI Banking77. Choose a new artifact directory for each run:

python examples/banking77_restart.py \
  --train /path/to/train.csv --test /path/to/test.csv \
  --artifacts /tmp/banking77-run --output /tmp/banking77-results.json

This is the canonical Banking77 example. It replaces the earlier, redundant in-process training script. Supervision comes from supplied dataset labels.

Multimodal smoke evaluation#

Install tensorcode[local]. Explicitly download the model first, for example with hf download HuggingFaceTB/SmolVLM-256M-Instruct --revision 7e3e67edbbed1bf9888184d9df282b700a323964. Save the published candy photograph locally, then run:

python examples/local_multimodal.py --image /path/to/candy.JPG \
  --source https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG \
  --output /tmp/multimodal-results.json

The prompts are specific to this image. This is a smoke test, not a general image benchmark. Use --device cuda when available. To select another downloaded model, supply both --model and its matching --revision; the defaults pin SmolVLM. Model outputs can be wrong or fail JSON validation. These failures remain in the report and must not be interpreted as successful decisions.

Each script supports --help. The package README contains smaller API examples; documentation explains contracts and limitations.

Experimental response-quality training#

Response-quality training prepares source-disjoint question/evidence/candidate supervision, then trains an owned internal assessor with separate support, completeness and constraint heads. Labels are explicit booleans or null (masked). Gold answers and review text remain outside inference. The first pilot failed promotion; this runner demonstrates supervised training and verification, not a ready-to-use correctness model.

From a repository checkout, prepare the reviewed development corpus:

python examples/train_response_quality.py prepare \
  --candidates .development/datasets/response-quality-candidates.jsonl \
  --labels .development/datasets/response-quality-labels-a.jsonl \
    .development/datasets/response-quality-labels-b.jsonl \
    .development/datasets/response-quality-labels-c.jsonl \
  --output /tmp/response-quality-data

On the authorized CUDA host, train with the existing pinned local cross-encoder/qnli-electra-base download. Preserve its Hugging Face download metadata; the runner checks revision and content hashes without downloading:

python examples/train_response_quality.py train \
  --data /tmp/response-quality-data \
  --foundation /path/to/pinned-qnli-electra-base \
  --output /tmp/response-quality-pilot

Output directories must be new. The run saves experiences, complete artifacts, optimizer state, calibration and per-axis metrics with simple baselines. It does not modify tool policies or publish weights.

Development qualification scripts#

Most examples use only public TensorCode APIs. Three scripts also depend on private model-development helpers: train_hypotheses.py shares the proposal prompt formatter, evaluate_cognition.py assembles a retrieval component, and train_response_quality.py trains an experimental response assessor. These scripts are qualification infrastructure tied to this checkout; their internal imports are not supported application APIs. Use the public tool factories and lifecycle examples above when building an application.