Skip to Content
Modules

The tools

The tools of Tommos for a module, in TypeScript and in Python: fetch, the cursor, the builders of a bid and a prospect, the domain, the date and the key, the log, and ask.

The tools come as a package of a version: @tommos/module-sdk for TypeScript and tommos-module-sdk for Python. Take them as a package; never copy their files into your module (check c).

{ "dependencies": { "@tommos/module-sdk": "github:TommosCRM/tommos-module-sdk#v0.2.0" } }
tommos-module-sdk @ git+https://github.com/TommosCRM/tommos-module-sdk@v0.2.0#subdirectory=python

The version in package.json or requirements.txt must be the version of sdk.version in the manifest. In the sandbox, Tommos gives your module the tools of that version.

TypeScriptPythonWhat it does
fetch(url, o)fetch(url, ...)Reads a URL of a host the manifest names
theCursor(context, start)the_cursor(context, start)The cursor of the last good run, or start
aBid(fields)a_bid(**fields)A bid of the contract, or ContractError
aProspect(fields)a_prospect(**fields)A prospect of the contract, or ContractError
aDomain(v)a_domain(v)A company's domain from a link or a host
aDate(v)a_date(v)A day, YYYY-MM-DD, from an ISO time, an email date or a date
aKey(...parts)a_key(*parts)A record's key from its parts
log.read, log.skipped, log.warningthe sameThe module's lines of the log
ask(o)ask(cls, prompt, ...)A model's answer, through Tommos

fetch

fetch reaches only a host of the manifest; any other is refused before a call, with words that name the host. It waits half a second after the last call to the same host, and tries a 429, a 5xx or no answer again, three times in all, a little longer each time. It answers { status, ok, text(), json() }.

const answer = await fetch("https://api.example.gov/tenders?page=2", { headers: { authorization: `Bearer ${process.env.THE_TOKEN}` } });
if (!answer.ok) throw new Error(`The register answered ${answer.status}`);

While Tommos runs your examples, fetch answers from the example's responses.json, and a URL it does not hold is refused. Nothing leaves the sandbox then.

The cursor

theCursor(context, start) is the cursor of the last run that worked, or start on the first run. Give back the new cursor from find; Tommos keeps it only when the run worked.

The builders

aBid and aProspect drop empty fields, make dates days and a domain plain, and check the record against its contract. A record that fails throws ContractError, with reasons (each in words) and record (what it made). Give e.record back: Tommos refuses it with its reasons, and the trial report shows them.

The domain, the date and the key

aDomain("https://WWW.Acme.co.uk/about"); // "acme.co.uk"
aDate("Tue, 10 Nov 2026 08:00:00 +0000"); // "2026-11-10"
aKey("FN", "0001");                     // "FN:0001"; a key past 200 characters is its SHA-256

ask

A module asks a model only through ask. Tommos calls the model on its own key; no key and no model name stand in your module. You name the class of the task:

ClassForThe model
fastA short judgement of a short text: is this a software company, which of three kinds is thisThe fast model of Tommos's tested list
smartA careful reading of a long textThe smart model of Tommos's tested list
import { ask, AskRefused, log } from "@tommos/module-sdk";

// try {
//   const { json } = await ask({ class: "fast", system: "Answer in JSON: { \"software\": true | false }", prompt: page, json: true, maxTokens: 50 });
// } catch (e) {
//   if (e instanceof AskRefused) log.warning(`the model was not asked: ${e.message}`);
//   else throw e;
// }
from tommos_module import AskRefused, ask, log

# try:
#     answer = ask("fast", page, system='Answer in JSON: { "software": true | false }', json_answer=True, max_tokens=50)
# except AskRefused as e:
#     log.warning(f"the model was not asked: {e}")

The pass of the run is put on the call by the sandbox's firewall: no pass and no key stand in your module. The sandbox reaches this one door of Tommos and no other path of it.

The limits:

  • The manifest names max_model_calls_per_run. A call past it is refused with AskRefused, and the run goes on.
  • The owner sets the most the scout may spend on the model in a day, London time, in Settings, Scouts. Each call holds its worst cost before the model is asked, so calls at once cannot pass it; a call past it is refused the same way.
  • Each call is a line of the run's log: the model, the tokens in and out, and the cost. The trial report shows the cost of one run and of a month.

While Tommos runs your examples, ask answers from responses.json, "ask": [{ "text": "..." }, ...], one answer for each call, in order.

On this page