Step 2: Write your first contract

A contract covers exactly one field. Give it a name, the values it may take, and for each value the words that would actually appear in one of your records.

{
  "outputField": "allergens",
  "sourceColumns": ["name", "description"],
  "cardinality": "many",
  "policy": "ratchet",
  "minConfidence": 0.7,
  "allowedValues": [
    { "value": "peanut",    "synonyms": ["peanut", "groundnut", "satay"] },
    { "value": "dairy",     "synonyms": ["cream", "milk", "butter", "cheese"] },
    { "value": "gluten",    "synonyms": ["wheat", "flour", "pastry", "bread"] },
    { "value": "shellfish", "synonyms": ["prawn", "shrimp", "crab", "lobster"] }
  ]
}

1. 1

   cardinality: one or many

   A dish can contain peanut and dairy at once, so allergens is many. A difficulty rating cannot be both beginner and advanced, so that would be one. Pick wrong and you will fight the contract forever.

2. 2

   policy: normal or ratchet

   ratchet makes it a safety field. Later runs may add a value, but if a run would ever take one away, that goes to a person instead of happening quietly. Allergens should never silently disappear, so: ratchet.

3. 3

   minConfidence

   Below this, the model's answer is not stored; it becomes your decision. The default is 0.7. Raise it and you review more and serve less. Lower it and you serve more and trust the model further.

4. 4

   sourceColumns

   Which of your columns the rules and the model are allowed to read. Up to ten. Keep it tight: pointing a contract at a column full of marketing adjectives is how you get confident nonsense.

One more rule with teeth. No word may be a synonym of two values of the same field. If “cream” meant both dairy and a sauce style, it settles nothing and quietly mis-tags everything. The editor will not let you save it.

Editing a contract bumps its version. Every receipt records the version it was decided under, so a value tagged under version 3 is still stamped 3 after you edit to version 4. That is how you find exactly what a change affected, rather than re-running everything and hoping.