Coco
Look something up

Python API

Look up the Python SDK, from loading a project to the guard, the engine, the gate client, and each decision.

Look up the Python SDK, from loading a project to the guard, the engine, and the gate client.

trustcoco-sdk decides tool calls in your process or through the hosted gate, with one surface for both. For a how-to, see Python agents.


load

From coco_sdk.project.

CallWhat it does
load(start=".")Returns the Project whose coco.yaml sits at or above start. Raises ProjectError when there's none, or when mode isn't monitor or enforce.
load_env(start=".")Reads KEY=value lines from the project's .env into the environment. A variable already set wins.
project.engine(local=False, **overrides)Returns the gate's client once the project is connected, otherwise an in-process Engine. Keyword arguments win over coco.yaml. local=True always decides in process.
project.guard(engine=None, **kwargs)Returns a CocoGuard on the project's engine, with actions, tell_agent, and the agent id from coco.yaml. Keyword arguments win.
project.gate()Returns the gate's URL and the key once connected, otherwise None. Reads the key from the environment, then the project's .env.
project.gate_url()Returns the gate's URL, or empty when the project decides locally.
project.contracts()Returns the project's parsed contracts.

load() doesn't read .env into the environment, but the project key is found there regardless. For anything else in the file, call load_env first.

A connected project gets a RemoteEngine whose timeout is verdict_timeout plus 3 seconds. Of the keyword overrides, only mode reaches it.

Keep in mind: A connected project without its key raises ProjectError from engine(). It never falls back to deciding in process.

CocoGuard

CocoGuard(engine, *, actions=None, state=None, agent_id="agent", tell_agent=False)

A middleware for create_agent. It wraps every tool call, sync and async, and calls the tool only when the effect allows it.

ArgumentDescription
engineAn Engine or a RemoteEngine.
actionsTool name to contract action. A tool not listed uses metadata["coco_action"], then its own name.
stateOne callable (action, args) -> dict for every action, or a mapping from action to callable.
agent_idWritten into every receipt as agent.id.
tell_agentIn Monitor, adds one line to the tool result: Coco would deny this in Enforce: <reason>, or would escalate.

from coco_sdk import CocoGuard attaches to coco-framework when it's installed, and to upstream LangChain otherwise. from coco_sdk.langchain import CocoGuard always attaches to upstream.

Engine

Engine(contracts, *, mode="monitor", ledger=None, limits=None, unknown_action="AUTO_EXECUTE",
       fail_open=False, judge=None, verdict_timeout=2.0, impact_threshold=0.5)
Engine.from_path("contracts/", **kwargs)
ArgumentDescription
modemonitor or enforce.
ledgerA path for the SQLite ledger. Left out, receipts stay in memory and go with the process.
limitsNumbers rules read as limits.*.
unknown_actionA tool no live contract governs: AUTO_EXECUTE, DENY, or impact. coco.yaml sets impact. A bare Engine defaults to AUTO_EXECUTE.
fail_openLets the call run in Enforce when the engine raises. The verdict stays DENY, and a rule's own error isn't covered.
judgeClassifierJudge(url, api_key=...) from coco_sdk.engine.judge, for judge checks. Without one, each judge check takes its on_error verdict.
verdict_timeoutSeconds to wait for the classifier.
impact_thresholdThe probability at which the classifier calls a tool impactful.
MethodReturns
check(action, args=None, *, state=None, session_id="default", agent=None, call_id=None, conversation=None, tool=None)A Decision, with its receipt written. It never raises for a failed decision.
escalation(id)One escalation, or None.
pending_escalations()Escalations still waiting.
resolve_escalation(id, *, approve, by, reason="")A person's decision, written to the chain. by is required, and a rejection needs a reason.

Example:

from coco_sdk import Engine

engine = Engine.from_path("contracts/", mode="enforce", ledger=".coco/ledger.db")
d = engine.check("payments.send", {"amount": 900, "payee": "Sunrise Capital Ltd"},
                 state={"account": {"status": "active"}, "approved_payees": ["Sunrise Capital Ltd"]},
                 session_id="run-42", call_id="call-1")
print(d.verdict, d.effect, d.reason)

call_id ties a retry to its escalation. A call with the same session id and call id as an open or decided escalation gets the escalation's answer first, before any rule runs.

Decision

FieldDescription
verdictAUTO_EXECUTE, OBSERVE, ESCALATE, or DENY.
effectrun, escalate, or deny, after the mode.
modemonitor or enforce.
reason, actionWhy, and the action decided.
rule, deciding_checkThe contract (id, version) and check that decided.
checksEvery check on this call, passing ones too.
audit_id, receipt_hashThe receipt. audit_id is None when the gate never saw the call.
escalation, obligationsThe open escalation, and what the contract asks of the approver.
impactFor a tool no contract governs, how its impact was established.
runs, denied, waitingThe effect as booleans.
as_dict()All of it as a dictionary.

RemoteEngine

from coco_sdk.remote import RemoteEngine

RemoteEngine(url, key, *, mode=None, timeout=5.0, fail_open=False, project=None)

The Engine surface, with the gate deciding. check, escalation, and resolve_escalation take the same arguments, so code written against Engine runs unchanged. The client sends the last 12 messages of the conversation, for judge checks to read.

DifferenceOn the gate
modeWhat the client assumes before the gate has answered. After that, the gate's own mode. Defaults to enforce.
projectSent as X-Coco-Project on every request.
resolve_escalation(approve=False)Withdraws an escalation this agent opened.
resolve_escalation(approve=True)Raises PermissionError. A person approves.
pending_escalations()Always empty. Listing is a reviewer's job.
rules()The project's mode, limits, contracts, and free checks left. Raises PermissionError when the gate refuses the key, and OSError when it can't be reached.
ledgerNone. The record lives in the gate.

When the gate doesn't answer

A gate the client can't reach, a late answer, or an error answer gives DENY. In Enforce the call stops, and in Monitor it runs. fail_open=True lets the call run in Enforce as well. The verdict stays DENY and the reason still says what failed. It has no coco.yaml key, so construct the engine yourself to set it:

import os
from coco_sdk.remote import RemoteEngine

engine = RemoteEngine(os.environ["COCO_GATE_URL"], os.environ["COCO_API_KEY"], fail_open=True)

A decision made without the gate has no audit_id, and no receipt exists for it. Its reason starts The call was not authorised: and names what failed. An in-process engine error writes an error receipt.

Sessions

CallerSession id
CocoGuardThe graph's thread_id, or default when the config has none.
Engine.check, RemoteEngine.checkThe session_id you pass. Defaults to default.
Claude Code hookClaude Code's own session id.

Errors

ExceptionFromRaised when
ProjectErrorcoco_sdk.projectA coco.yaml can't be used, or a connected project has no key.
ContractErrorcoco_sdkA contract doesn't meet the format, when it loads.

On this page