> ## Documentation Index > Fetch the complete documentation index at: https://docs.ctrlrun.dev/llms.txt > Use this file to discover all available pages before exploring further. # Python API > Every frozen public name of the ctrlrun package and its extras, one page each, rendered from the docstrings. The names below are the ones the specifications freeze: `ctrlrun.__all__`, the entry points of the extras, and `ctrlrun.verify.run`. Each page is rendered from the docstring; a name with no docstring fails a test, so every page has one. | Name | Kind | Summary | | --------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ | | [`ctrlrun.Action`](/reference/api/Action) | class | A proposed agent action: what, with which arguments, by whom, on what. | | [`ctrlrun.ActionDenied`](/reference/api/ActionDenied) | class | The action may not run. `reason` says why, e.g. `unknown_action` (SPEC-v0.1 §3.4). | | [`ctrlrun.AmbiguousEffect`](/reference/api/AmbiguousEffect) | class | The outcome of this effect is unknown; only a human may resolve it (SPEC-v0.1 §5.4). | | [`ctrlrun.Approval`](/reference/api/Approval) | class | A human's grant, bound to one `action_hash` (SPEC-v0.1 §4.1). | | [`ctrlrun.ApprovalAnswer`](/reference/api/ApprovalAnswer) | class | A human's answer, and who gave it (SPEC-v0.5 §2.2, §3.4). | | [`ctrlrun.ApprovalMismatch`](/reference/api/ApprovalMismatch) | class | The presented approval does not authorize this action (SPEC-v0.1 §4.2). | | [`ctrlrun.ApprovalProvider`](/reference/api/ApprovalProvider) | class | How a human is asked, and how the answer comes back (SPEC-v0.1 §4.3). | | [`ctrlrun.ApprovalRequest`](/reference/api/ApprovalRequest) | class | A pending question for a human: may this exact action run? (SPEC-v0.1 §4.1) | | [`ctrlrun.ApprovalRequired`](/reference/api/ApprovalRequired) | class | The action needs a human. `request_id` is what `ctrlrun approve` takes (SPEC §4.3). | | [`ctrlrun.ApprovalTimeout`](/reference/api/ApprovalTimeout) | class | Nobody answered the approval request in time (SPEC-v0.1 §4.3). | | [`ctrlrun.Authority`](/reference/api/Authority) | class | The `authority:` section, loaded and evaluable (SPEC-v0.3 §4). | | [`ctrlrun.AuthorityDenied`](/reference/api/AuthorityDenied) | class | The principal holds no grant that covers this action (SPEC-v0.3 §4.3). | | [`ctrlrun.AuthorityEscalation`](/reference/api/AuthorityEscalation) | class | A delegation that may not exist: it is not contained in its parent (SPEC-v0.3 §5.3). | | [`ctrlrun.AuthorityResult`](/reference/api/AuthorityResult) | class | What the authority axis decided, and which grant it decided on (§4.8). | | [`ctrlrun.CTRLRunError`](/reference/api/CTRLRunError) | class | Base class for every error raised by CTRLRun. | | [`ctrlrun.Condition`](/reference/api/Condition) | class | One `_: operand` test against an action's arguments (SPEC-v0.1 §3.2). | | [`ctrlrun.Control`](/reference/api/Control) | class | Policy, state and evidence composed around a single action (SPEC-v0.1 §8). | | [`ctrlrun.Decision`](/reference/api/Decision) | class | What may happen to an action: exactly three outcomes in v0.1 (SPEC-v0.1 §3.3). | | [`ctrlrun.Delegation`](/reference/api/Delegation) | class | A grant created at runtime by a principal who already holds one (SPEC-v0.3 §5.1). | | [`ctrlrun.DelegationRecord`](/reference/api/DelegationRecord) | class | One row of the `delegations` table (SPEC-v0.3 §5.2). | | [`ctrlrun.DuplicateEffect`](/reference/api/DuplicateEffect) | class | This logical effect already happened, or is happening now (SPEC-v0.1 §5.4). | | [`ctrlrun.EffectKeyError`](/reference/api/EffectKeyError) | class | An effect template cannot be resolved to a key (SPEC-v0.1 §5.1). | | [`ctrlrun.EffectRecord`](/reference/api/EffectRecord) | class | What a StateStore holds for one effect key (ARCHITECTURE §5). | | [`ctrlrun.EffectState`](/reference/api/EffectState) | class | Where a logical effect stands (SPEC-v0.1 §5.2). | | [`ctrlrun.Event`](/reference/api/Event) | class | One ordered step in the life of an action (SPEC-v0.1 §6.2). | | [`ctrlrun.EventSink`](/reference/api/EventSink) | class | Somewhere a copy of every `Event` and `Receipt` goes (SPEC-v0.2 §4.1). | | [`ctrlrun.FrameworkInterrupt`](/reference/api/FrameworkInterrupt) | class | One framework's human-in-the-loop primitive, and nothing else (SPEC-v0.5 §2.1). | | [`ctrlrun.Grant`](/reference/api/Grant) | class | One permission: this subject may propose these actions, under these limits (§4.2). | | [`ctrlrun.HeaderIdentityProvider`](/reference/api/HeaderIdentityProvider) | class | The principal named by a trusted HTTP header (§3.3). | | [`ctrlrun.IdentityContext`](/reference/api/IdentityContext) | class | What a provider is told about the call it is resolving a principal for (§3.1). | | [`ctrlrun.IdentityError`](/reference/api/IdentityError) | class | A credential was offered and rejected (SPEC-v0.3 §3.2). | | [`ctrlrun.IdentityProvider`](/reference/api/IdentityProvider) | class | Resolves the principal for one action (SPEC-v0.3 §3.1). | | [`ctrlrun.InMemoryStateStore`](/reference/api/InMemoryStateStore) | class | Everything held in process memory: for tests and `ctrlrun demo`. | | [`ctrlrun.InterruptApprovalProvider`](/reference/api/InterruptApprovalProvider) | class | An `ApprovalProvider` whose `wait()` routes through a framework's own primitive. | | [`ctrlrun.InvalidArgument`](/reference/api/InvalidArgument) | class | An argument cannot be accepted as given. | | [`ctrlrun.JSONLEventSink`](/reference/api/JSONLEventSink) | class | The JSONL half of the evidence: two append-only files in one directory (SPEC §6). | | [`ctrlrun.LocalApprovalProvider`](/reference/api/LocalApprovalProvider) | class | Requests go to the StateStore; `wait()` polls it (SPEC-v0.1 §4.3). | | [`ctrlrun.MissingDependency`](/reference/api/MissingDependency) | class | An optional extra is not installed (SPEC-v0.2 §1.1, §11). | | [`ctrlrun.NotExecuted`](/reference/api/NotExecuted) | class | Raised by an executor to assert the remote side did nothing (SPEC-v0.1 §5.5). | | [`ctrlrun.PendingApproval`](/reference/api/PendingApproval) | class | What the framework's interrupt is handed, and the only thing it is (SPEC-v0.5 §2.3). | | [`ctrlrun.Policy`](/reference/api/Policy) | class | Action-level autonomy policy: which actions may run, and under which conditions. | | [`ctrlrun.PolicyError`](/reference/api/PolicyError) | class | The policy is missing, unreadable, or malformed. Raised at load time (SPEC-v0.1 §3.4). | | [`ctrlrun.Principal`](/reference/api/Principal) | class | Who is acting: an agent, optionally on behalf of a human. | | [`ctrlrun.Receipt`](/reference/api/Receipt) | class | Portable evidence of one action that reached a terminal state (SPEC-v0.1 §6.1). | | [`ctrlrun.ReconcileOutcome`](/reference/api/ReconcileOutcome) | attribute | What a `reconcile` hook may answer about an effect key (SPEC-v0.2 §2). | | [`ctrlrun.SQLiteStateStore`](/reference/api/SQLiteStateStore) | class | Approvals, effects and evidence in one SQLite file (ARCHITECTURE §5). | | [`ctrlrun.SchemaMismatch`](/reference/api/SchemaMismatch) | class | A store met a database it does not recognise, in either direction (SPEC-v0.6 §3.3). | | [`ctrlrun.ScriptedApprovalProvider`](/reference/api/ScriptedApprovalProvider) | class | A human replaced by a fixed script: for tests and `ctrlrun demo` (SPEC-v0.1 §4.3). | | [`ctrlrun.StateStore`](/reference/api/StateStore) | class | Durable state behind a `Control` (SPEC-v0.1 §5.3): approvals, effects, evidence. | | [`ctrlrun.StaticIdentityProvider`](/reference/api/StaticIdentityProvider) | class | A fixed principal, for development, tests and single-tenant demonstrations (§3.3). | | [`ctrlrun.Subject`](/reference/api/Subject) | class | Who a grant is addressed to: an agent pattern, a user pattern, or both (§4.2). | | [`ctrlrun.Suspended`](/reference/api/Suspended) | class | Raised by an executor: the remote asked for something before it will finish. | | [`ctrlrun.WebhookApprovalProvider`](/reference/api/WebhookApprovalProvider) | class | Notify a human system on `APPROVAL_REQUESTED`, and let it answer (SPEC-v0.2 §7). | | [`ctrlrun.action_hash`](/reference/api/action_hash) | function | Return the action hash used to bind approvals to an exact action (SPEC-v0.1 §2.3). | | [`ctrlrun.banner`](/reference/api/banner) | function | Log SPEC-v0.3 §6.5's observe banner, once per `Control`. An adapter MUST call it (§3.6). | | [`ctrlrun.canonical_bytes`](/reference/api/canonical_bytes) | function | The canonical form of an arbitrary mapping: UTF-8 JSON, sorted keys, no whitespace. | | [`ctrlrun.canonicalize`](/reference/api/canonicalize) | function | Return the canonical form of an Action: UTF-8 JSON, sorted keys, no whitespace. | | [`ctrlrun.context`](/reference/api/context) | function | Bind the principal for calls made inside the block. | | [`ctrlrun.needs_approval`](/reference/api/needs_approval) | function | Does this call need a human? For a framework that asks before it invokes (SPEC-v0.5 §3.5). | | [`ctrlrun.parse_conditions`](/reference/api/parse_conditions) | function | Parse a `when:`-shaped mapping into conditions, keyed by the raw condition key. | | [`ctrlrun.protect`](/reference/api/protect) | function | Bind a function to an action name: every call becomes a decided, recorded Action. | | [`ctrlrun.with_approval`](/reference/api/with_approval) | function | Present a granted approval to the calls made inside the block (SPEC-v0.1 §4.3). | | [`ctrlrun.postgres.PostgresStateStore`](/reference/api/postgres-PostgresStateStore) | class | Approvals, effects and evidence in a Postgres schema (SPEC-v0.6 §4). | | [`ctrlrun.otel.OTelEventSink`](/reference/api/otel-OTelEventSink) | class | Export every `Event` and `Receipt` as OpenTelemetry spans (SPEC-v0.2 §8). | | [`ctrlrun.jwt_identity.JWTIdentityProvider`](/reference/api/jwt_identity-JWTIdentityProvider) | class | Verify a bearer JWT and map its verified claims onto a `Principal` (SPEC-v0.3 §3.4). | | [`ctrlrun.acs.AcsControlHook`](/reference/api/acs-AcsControlHook) | class | Answer ACS `steps/*` hooks with CTRLRun's decisions and outcomes. | | [`ctrlrun.gateway.serve`](/reference/api/gateway-serve) | function | Run a gateway in front of one upstream MCP server (SPEC-v0.2 §6.1). | | [`ctrlrun.verify.run`](/reference/api/verify-run) | function | Run the applicable guarantees against this configuration and report (§9.1). | | [`ctrlrun.conformance.run`](/reference/api/conformance-run) | function | Drive every suite through `adapter` and report what each came to (SPEC-v0.5 §5). | | [`ctrlrun.conformance.store.run`](/reference/api/conformance-store-run) | function | Drive every case against `backend` and report what each came to (SPEC-v0.6 §2). | ## Next * [CLI reference](/reference/cli). * [Get started](/get-started/quickstart) · [Why](/why). ## Related topics - [Python API](/reference/api/index.md) - [Action](/reference/api/Action.md) - [Approval](/reference/api/Approval.md) - [Event](/reference/api/Event.md) - [Grant](/reference/api/Grant.md)