Skip to Content
Modules

The contracts

Each record a module gives back holds the contract of its kind, Bid or Prospect, version 1, field by field.

Tommos checks each record against the contract of its kind. A record that fails is refused with its reason, and the others go on (check d). The builders aBid and aProspect of the tools make a record of the contract and say why one fails.

The contracts are JSON Schemas, published at https://app.tommos.ai/modules/contracts/bid.v1.json and https://app.tommos.ai/modules/contracts/prospect.v1.json, and in the tools under contracts/.

Bid, version 1

A bid is one record per source and key.

FieldRequiredWhat it holds
sourceyesWhere the bid comes from: one of the manifest's record_sources, such as fictional-register. Never highergov, nor a source another module of the workspace names
keyyesThe bid's own id at its source, such as the notice's id, at most 200 characters
matchedyesThe rule of your module that took this bid, as a fact: «an open notice of the fictional register», «CPV 72254, software testing»
titleyesThe notice's own title, at most 500 characters
buyeryes{ "name": "...", "key": "...", "type": "..." }; name is required
source_urlyesThe notice on the source's own site, http or https
contact_emailnoThe buyer's contact, an email address
due_datenoThe day bids are due, YYYY-MM-DD
posted_datenoThe day the notice was posted, YYYY-MM-DD
summarynoA short text of the notice
descriptionnoThe notice's whole text, at most 100000 characters
documentsnoEach file of the notice: { "name": "...", "url": "..." }, at most 100
value_estimateno{ "low": 1000, "high": 5000, "currency": "GBP" }; currency is required, ISO 4217
countrynoThe buyer's country, ISO 3166 alpha-2: GB, US. The log of Tommo Bids shows its flag
naics, cpv, opp_typenoThe notice's codes and its kind of procedure
placeno{ "city": "...", "region": "..." }

A bid of the example's fictional register (no buyer, notice or amount in it is real):

{
  "source": "fictional-register",
  "key": "FN-0001",
  "matched": "an open notice of the fictional register",
  "title": "Testing of the citizen portal (fictional)",
  "buyer": { "name": "The Borough of Nowhere (fictional)" },
  "due_date": "2026-12-01",
  "posted_date": "2026-11-09",
  "source_url": "https://github.com/TommosCRM/tommos-module-template/blob/main/data/fictional-notices.json#FN-0001",
  "description": "A fictional notice: the borough asks for the testing of its citizen portal before it opens.",
  "value_estimate": { "low": 40000, "high": 40000, "currency": "GBP" }
}

A record never carries a secret: neither the value of a secret of the source, nor a link with a credential in its query (such as ?token=). Tommos refuses such a record with its reason.

Prospect, version 1

A prospect is one company, one record per module and domain. Two modules that find the same domain make one card on the board Prospecting, with the evidence of both.

FieldRequiredWhat it holds
domainyesThe company's own website: lower case, no www, no path, such as acme.io
nameyesThe company's name, at most 300 characters
matchedyesThe rule of your module that took this company, as a fact
evidenceyes1 to 50 facts: { "what": "...", "url": "...", "date": "YYYY-MM-DD", "quote": "..." }; what and url are required
segmentnoA segment your module gives as a fact, at most 100 characters
scorenoA number your module gives as a fact
factsnoThe value of each fact the manifest names that the record knows, by its key: { "round": "Seed" }. See Facts
countrynoISO 3166 alpha-2
peoplenoEach person you know: { "name": "...", "title": "...", "email": "...", "url": "..." }

Evidence is a fact, never an opinion: what happened, the link where it stands, its day, and a quote of the source's own words.

{
  "domain": "jobworth.io",
  "name": "JobWorth",
  "matched": "a Show HN launch with its own website",
  "evidence": [
    {
      "what": "Launched on Hacker News (Show HN)",
      "url": "https://news.ycombinator.com/item?id=50453700",
      "date": "2026-11-11",
      "quote": "Show HN: JobWorth, paste a job description, see how hard it is to get"
    }
  ],
  "score": 1
}

Facts

A prospect module names its facts in the manifest: at most six, each with a key, a label and a kind. A record carries a value for each fact it knows, under facts, by the fact's key. A record that knows no fact leaves facts out. Give a fact only when the source states it; a fact is never a guess.

KindThe valueAn example
textA text, at most 300 characters"Seed"
moneyAn amount and its currency, ISO 4217{ "amount": 2500000, "currency": "USD" }
countA whole number, 0 or more12
dateA day, YYYY-MM-DD"2026-11-17"

The prospect example names round (text) and amount (money). It takes them only from the words of the launch's own title. A record of its fictional example:

{
  "domain": "quayside.example",
  "name": "Quayside (fictional)",
  "matched": "a Show HN launch with its own website",
  "evidence": [
    {
      "what": "Launched on Hacker News (Show HN)",
      "url": "https://news.ycombinator.com/item?id=fictional-2",
      "date": "2026-11-17",
      "quote": "Show HN: Quayside (fictional) – we raised $2.5M in a Seed round to test ports"
    }
  ],
  "score": 3,
  "facts": { "round": "Seed", "amount": { "amount": 2500000, "currency": "USD" } }
}

Tommos keeps the facts with the evidence of the company, with their labels. A card on the board Prospecting shows the first two facts the manifest names; the company's page shows all of them.

Tommos refuses a record that carries a fact the manifest does not name, or a value of another kind, with its reason (check d): facts.round is not a value of the kind count: facts.round must be a whole number. A bid carries no facts.

On this page