Coco
Integrate and operate

Write contracts

Write rules and judge checks by hand, and test a contract before it goes live.

Write rules and judge checks by hand, and test them before they go live.

Most contracts come from your policy documents. Write one by hand for what a policy doesn't state, such as a blocklist.


Create a contract

Save this as a YAML file in contracts/:

contracts:
  - id: payments.send_limit          # family.snake_case
    version: 1
    status: draft                    # draft | testing | live | retired
    action: payments.send
    governs: A payment above the limit waits for a person.
    source: {document: Payments Policy, section: "2.1", text: "Payments above AUD 10,000 ..."}
    checks:
      - id: under_limit
        check: 'args.amount <= limits.auto_release_limit'
        on_fail: ESCALATE            # OBSERVE | ESCALATE | DENY
        reason: Above the auto-release limit

A check is a condition that must hold, and on_fail is the verdict when it doesn't.

Rules read limits from coco.yaml:

limits:
  auto_release_limit: 10000

To see the contract, run coco contracts list. A malformed contract stops loading with an error naming the contract and the check.

Write the rule

A rule can read the call, your facts, the session, and the project's limits:

args.amount <= limits.auto_release_limit                 # the call, against the project's numbers
"payee_manager" in state.initiator.roles                 # facts from your systems
session.total.amount + args.amount <= limits.daily_cap   # what already ran in this conversation
matches(args.memo, "\\bAPC-[0-9]{4}-[0-9]{4}\\b")        # a pattern
lower(args.payee) not in ["apex corp", "shadow ltd"]     # a blocklist

state comes from your state provider, never from the model. For the full language, see Contracts and rules.

Keep in mind: A field the call lacks reads as null, and comparing a number against null denies. A missing number never passes a limit.

Choose a verdict

VerdictUse it when
OBSERVEThe call may run, and the receipt should flag it.
ESCALATEA person decides. obligations tell the approver what's required.
DENYThe call must never run as proposed. The reason goes to the model.

The most severe verdict among live contracts wins.

Guard the rest with a pre check

A pre check runs first. When one fails at DENY, Coco skips the constraints behind it:

checks:
  - id: account_active
    stage: pre
    check: 'state.account.status == "active"'
    on_fail: DENY
    reason: The source account is not active

Narrow when a contract applies

applies_when is a rule, and the contract applies only when it holds:

action: payments.send
applies_when: 'args.currency == "AUD"'

action: "*" governs every action, usually narrowed with applies_when.

Add a judge check

A judge check asks the classifier about what no rule can see. Phrase the question so yes means the check fails:

checks:
  - id: requested_by_user
    judge:
      question: Is this transfer something the user did not clearly ask for?
      reads: [args, conversation, clause]      # clause: the contract's source text
    escalate_at: 0.5
    deny_at: 0.9
    reason: The transfer does not match what the user asked for

Set classifier.url in coco.yaml or COCO_CLASSIFIER_URL. Without a classifier, every judge check takes its on_error verdict, ESCALATE by default.

Keep in mind: The hosted gate has no classifier today, so this applies on every connected project. Use judge checks for intent and prose, never for a hard limit. Results shows why.

Test it and make it live

Move the contract to testing, read what it would have done, then make it live:

coco contracts activate payments.send_limit --testing     # recorded, never enforced
coco ledger                                               # read what it would have done
coco contracts activate payments.send_limit --live        # enforced

Good to know: coco contracts activate changes files that hold a contracts: list, as above. A file with one contract at its top level also loads, but activate skips it, so edit its status: by hand.

To try a call without a model, run:

python - <<'EOF'
from coco_sdk.project import load
engine = load().engine(mode="enforce")
d = engine.check("payments.send", {"amount": 25000, "payee": "Sunrise Capital"})
print(d.verdict, d.reason)
EOF

On a connected project, a contract you write by hand reaches the gate through an administrator. See Contracts on a connected project.


On this page