intutic-clawde

Python SDK for Intutic Agentic AI Governance proxy wrappers.

The proxy's address is INTUTIC_BASE_URL, else http://localhost:4000. What talks to an Intutic control plane (ControlPlaneClient, check_budget(), session registration, the gate's control-plane tiers) needs its address: pass it to the client or set INTUTIC_CONTROL_PLANE_URL. There is no default; without one, ControlPlaneClient raises ValueError and ClawdeClient.chat() still works through the proxy.

ClawdeClient.chat() sends a request through the Intutic proxy and returns the completion with verdict set to "allow". A governance refusal (policy block, reask, loop run held for review, spend cap, DLP block) raises ClawdeBlockedError with the proxy's verdict, code, rule_id (when the proxy names the rule) and reason, fires the matching kill / reask / hold event, and is never retried; transport failures and 5xx answers are retried, except a 5xx the proxy already retried upstream. See Verdicts and Errors for every refusal code.

When the proxy withholds a tool call from the model's answer (a tool an SOP denies, the SSO group policy, destructive SQL, sensitive output), the answer arrives as a 200 that names the refusal in the x-intutic-refusal and x-intutic-refusal-rule headers; chat() raises ClawdeBlockedError for it too. For a stream you read yourself, pass each line to stream_refusal().

With an Intutic virtual key, in a git repository, the first chat() registers a session with the control plane carrying the repository (the origin remote as host/path, credentials removed), the branch and the HEAD commit, so the calls count in cost per branch, commit and pull request. This is on by default; pass auto_context=False to send none of it. See Git context and cost attribution.

ControlPlaneClient covers the operator APIs the CLI exposes: org and workspace setup, gateways, settings and provider credentials, the MCP registry, notification rules, SIEM destinations, usage, the AI inventory, compliance evidence, policy guardrails, held decisions and loop runs, incidents, findings, traces, trace integrity, WASM rules, SOPs, API keys (list_api_keys and the rest), the SOP Optimizer's settings (get_optimizer_settings, update_optimizer_settings) and task-management connections (list_task_connections), with the TypeScript SDK's methods in snake_case. verify_evidence_archive() checks a compliance evidence archive offline and verify_integrity_root() a sealed trace root's signature; both signature checks need pip install 'intutic-clawde[compliance]'. See the SDK reference.

The intutic_clawde.gate subpackage is the pre-execution tool gate for Python agent frameworks; see the Gate SDK reference. Its GateClient fails closed by default (fail_closed=True): when the control plane's hook gate cannot be reached, or answers GOVERNANCE_UNAVAILABLE because a check it runs could not complete, the call is refused. Pass fail_closed=False to let calls through during such an outage. A request the hook gate cannot read (HTTP 400, INVALID_REQUEST), and a key that lacks the scope the hook gate needs (HTTP 403, INSUFFICIENT_SCOPE), are refused whatever fail_closed says. A GateClient given an API key but no control plane address (no base_url, no INTUTIC_CONTROL_PLANE_URL) raises ValueError rather than skip the hook gate. A GateClient with no API key (what GateClient.from_env() builds when neither INTUTIC_API_KEY nor ~/.intutic/credentials.json has one) is local-only (client.local_only): it sends nothing, the hook gate's answer is an allow with code LOCAL_ONLY, and the local tiers still decide. See Fail-closed defaults.

A call a decide rule could not decide raises IntuticGateEscalation (from intutic_clawde.gate, code DECIDE_ESCALATED, with the rule in rule_id): a subclass of IntuticGateRefusal, so code that stops on every refusal stops on it too, and code that can ask its user asks with its reason and runs the call only on a yes. A SOP's requires_before: action:run_tests[ok] -> … is met only by a recorded passing test run: @guard and guard_tools record each call's outcome after it runs, and a caller that evaluates calls with Gate directly must call Gate.record_outcome(tool_name, tool_input, exit_code=..., output=...) after each call it runs, or the prerequisite is never met.

intutic_clawde.decide(state, questions, when=...) asks a self-hosted model a few narrow yes/no or pick-one questions about a piece of text, written as a decide rule's questions, and returns each answer's probability and reading (with when, the outcome the rule would reach). The engine comes from ~/.intutic/decide/engine.json and the INTUTIC_DECIDE_* variables; a hosted decision API is refused before anything is sent. An engine that is not configured, refused or cannot answer in time raises DecideEngineError. See Decide rules.

Every public module's API, with signatures and defaults: Python SDK reference.