Coco
Integrate and operate

Turn policies into contracts

Take your policy documents to reviewed, live contracts, on the hosted document service or on your machine.

Take your policy documents to reviewed, live contracts.

A model reads your documents, and a person decides what goes live. For a walkthrough on a sample policy, see Your first governed agent.


Read the documents

Put your documents in policies/, then choose where they're read:

Hosted document serviceYour machine
Commandcoco policy uploadcoco policy extract
AcceptsPDF and DOCX, up to 50 MiB.PDF.
NeedsA connected project.A checkout of the policy pipeline and its model key.
Result.coco/policy/<stem>-<sha8>/The same folder.

Use the hosted document service

See the available models, then upload:

coco policy models                       # the presets the service offers, and which are available
coco policy upload                       # every PDF and DOCX in policies/, or the files named
coco policy upload --model gpt-6-luna    # another preset for this upload

For each file, Coco registers the document, uploads it, waits for the job, pulls the results into .coco/policy/<stem>-<sha8>/, and deletes the document on the service. You'll see:

sample_policy-e3851671: 17 rules, issues AMBIGUITY 6, FLAGGED
  contracts in the dashboard: transaction.review, approval_decision.record, payment.approve, payment.release, record.retain
  the service deleted the document, its context and its policy version; 5 draft contracts stay on the dashboard

Next: coco contracts compile

The two-page sample policy took 51 seconds on production on 7 November 2026. A model reads the document, so the rule count varies between runs. FLAGGED means the pipeline kept every rule it traced to the text and marked the rest for review.

Good to know: With no arguments, coco policy upload sends every PDF and DOCX in policies/, including the sample. To upload one document, name it: coco policy upload policies/your-policy.pdf.

Choose a model. --model names a preset. Without it, Coco uses policy.model from coco.yaml, then the service's default.

PresetProviderRulesVision
qwen3.8-max (default)Alibaba Cloud Model Studioqwen3.8-maxqwen3.7-plus
qwen3.7-plusAlibaba Cloud Model Studioqwen3.7-plusqwen3.7-plus
gpt-6-lunaOpenAIgpt-6-lunagpt-6-luna
gpt-6-astraOpenAIgpt-6-astragpt-6-luna

For a document that must stay with a US provider, choose a gpt preset.

Only the contracts stay. Once the files are in .coco/policy/, Coco deletes the source, context, index, policy, and numbered policy version on the service. The draft contracts on the dashboard stay. To keep everything, pass --keep on upload. On pull and retry, --keep keeps what the service still holds: the context and the policy version, and the source only when the upload said --keep.

If a job fails. Coco prints the service's reason and exits 2. The service keeps the source for a day, so a retry needs no second upload:

coco policy retry JOB_ID                 # --model NAME picks another preset, --no-wait returns once queued

After a day, retry returns 409 and you upload the file again.

For long jobs. --no-wait prints each document and job id and returns. The document stays until you pull it:

coco policy jobs                         # the project's documents, newest first
coco policy pull JOB_ID                  # pulls a finished job, then deletes its document unless --keep

To skip writing drafts to the dashboard, pass --no-publish.

Use your machine

coco policy extract runs the policy pipeline on every PDF in policies/. Point pipeline.path in coco.yaml, or COCO_PIPELINE, at the pipeline's checkout, and set its model key, DASHSCOPE_API_KEY. Then run:

coco policy extract
coco policy extract --from-output DIR    # import a folder the pipeline already wrote

The pipeline uses offline embeddings, so you need no embedding server. To use one, set EMBEDDING_MODE=api and EMBEDDING_BASE_URL in the project's .env.

Good to know: A local run can end REVIEW_REQUIRED, which means the pipeline found something a person needs to read, such as an ambiguous clause. The output is complete, and the next steps carry the open issues forward.

Compile draft contracts

Compile what you extracted:

coco contracts compile

The compiler groups rules by resource and action and writes every contract as a draft:

  • Each condition becomes a rule.
  • REQUIRE_APPROVAL, REVIEW, and MFA become ESCALATE, with the obligations the approver needs to see.
  • A rule given only in prose, one the pipeline left to a judge, or one with a missing threshold or vague term becomes a judge check citing the rule's text.
  • Boundary cases go to .coco/cases/.

Review each draft

Print the drafts:

coco contracts review                    # every draft
coco contracts review payment.transfer   # one contract

Read each draft against the document. source and says give the page, section, and words behind the rule. review lists the compiler's own doubts.

Confirm the bindings

contracts/bindings.yaml maps the policy's words to what the tool receives. The compiler lists every entry it guessed under guessed:. Check each one, then empty the list:

fields:
  transaction.amount: args.amount       # the policy's amount is the tool's amount
actions:
  payment.transfer: payments.send       # a payment transfer is what send_payment does
guessed: []                             # a person has checked these

Run coco contracts compile again afterwards.

Replay the boundary cases

Replay the compiled cases, each with the verdict the policy text implies:

coco eval cases

A miss names the case and the reason. Settle each miss before a contract goes live.

Activate

On a local project, move the contract to testing, then live:

coco contracts activate payment.transfer --testing     # recorded, never enforced
coco contracts activate payment.transfer --live        # enforced

A contract with open review issues doesn't go live. Open the compiled file in contracts/, find the issue under review:, add resolved: true with a note, and activate again. --force skips the check. A later coco contracts compile asks again.

On a connected project, coco policy upload has already written each draft to the Contracts page:

  1. Open your project at app.trustcoco.ai and select Contracts.
  2. Open a draft.
  3. Select Activate and confirm.

An unactivated draft enforces nothing. Processing a policy again refreshes its drafts and leaves active contracts as they are. coco contracts activate edits local files, so it doesn't change the gate.

Keep in mind: Activate a contract only if your tool sends every argument its rules read. A rule Coco can't evaluate fails closed.

Map your tool to the contract

A contract governs an action. If your tool performs a different action from the contract you activated, map it in coco.yaml, using the tool's name as the key:

actions: {send_payment: payment.approve}

Without the mapping, the verdict is ESCALATE with the reason No live contract governs payments.send, and whether it changes anything is unknown.


On this page