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=pythonThe 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.
| TypeScript | Python | What 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.warning | the same | The 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-256ask
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:
| Class | For | The model |
|---|---|---|
fast | A short judgement of a short text: is this a software company, which of three kinds is this | The fast model of Tommos's tested list |
smart | A careful reading of a long text | The 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 withAskRefused, 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.