Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Python Core API Reference (dmint)

This page documents the supported public API exposed by the dmint package. Import from the top-level package where possible:
from dmint import Dmint, Policy, Rule, ApprovalVerifier

1. Dmint

class Dmint: def __init__( self, policy: Policy | None = None, *, agent_id: str, context: TrustedContext, integration_id: str = "local-runtime", approval_store: ApprovalStore | None = None, approval_verifier: ApprovalVerifier | None = None, policy_provenance: PolicyProvenance | None = None, approval_ttl: timedelta | None = None, clock: Callable[[], datetime] | None = None, webhook_notifier: WebhookNotifier | None = None, # deprecated; ignored policy_file: str | Path | None = None, expected_policy_digest: str | None = None, ) -> None: ... @classmethod def local( cls, policy: Policy | str | Path, *, db_path: str | Path | None = None, state_dir: str | Path | None = None, agent_id: str = "local-agent", context: TrustedContext | Mapping[str, Any] | None = None, approval_ttl: timedelta = timedelta(minutes=10), deployment_epoch: str = "default", integration_id: str = "local-runtime", clock: Callable[[], datetime] | None = None, ) -> Dmint: ...
Dmint.local(...) is a zero-config constructor that automatically creates .dmint/signing.key (0600), .dmint/integrity.key (0600), and .dmint/approvals.sqlite3, and accepts a Policy object, a path to policy.json, or a built-in template name (e.g. "shell").
Dmint is the synchronous authorization and decorator engine. It evaluates the policy deterministically and never calls an LLM.

Parameters

ParameterMeaning
policyCompiled Policy. Optional when policy_file is supplied.
agent_idPrincipal bound to every request made through this engine.
contextHost-supplied TrustedContext. Never populate it from model output.
integration_idRuntime/integration label included in the request binding.
approval_storeApprovalStore used for APPROVAL_REQUIRED and retries.
approval_verifierPublic-key-only verifier required for retry().
policy_provenancePolicyProvenance binding approvals to a policy version and digest.
approval_ttlLifetime of a pending approval.
clockInjectable clock for deterministic deployments and tests.
policy_fileLocal path or pinned https:// policy URL. Remote loading requires expected_policy_digest.
expected_policy_digestExpected policy_digest() value for a remote policy.
webhook_notifierDeprecated and inert in Core. Core never dispatches webhooks. The MCP gateway dispatches notifications. Passing this argument emits a DeprecationWarning.

Decorators and methods

engine.protect(capability: str, *, resource: ResourceSpec = NO_RESOURCE) -> Callable engine.protected(capability: str, *, resource: ResourceSpec = NO_RESOURCE) -> Callable engine.authorize(function: Callable, *args, capability: str, resource: ResourceSpec = NO_RESOURCE, **kwargs) -> AuthorizedRequest engine.execute(authorized: AuthorizedRequest) -> Any engine.retry( protected_callable: Callable, *args, approval_credential: ApprovalAssertion | bytes | None = None, **kwargs, ) -> Any
protect and protected are aliases. resource may be NO_RESOURCE or a callable (lambda args: ...) that receives the bound arguments and returns a resource string.
The decorated function raises:
  • ApprovalRequiredError (DMT_APPROVAL_REQUIRED) after persisting a pending request.
  • AuthorizationError with DMT_POLICY_DENIED, DMT_DEFAULT_DENIED, or DMT_CONSTRAINT_VIOLATION for a deny.
  • RequestValidationError or CanonicalizationError when the invocation cannot be safely canonicalized.
retry() requires both approval_store and approval_verifier. It verifies the signature and full request binding, re-evaluates the current policy, atomically consumes the record, and then executes the original callable exactly once.

2. Policy and Rule

class Policy: @classmethod def from_file(cls, path: str | Path, *, expected_policy_digest: str | None = None) -> Policy: ... @classmethod def from_url( cls, url: str, *, expected_policy_digest: str, timeout: float = 15.0, ) -> Policy: ... @classmethod def from_mapping(cls, value: Mapping[str, Any]) -> Policy: ... def evaluate(self, request: ToolRequest) -> Decision: ... def evaluate_detailed(self, request: ToolRequest) -> tuple[Decision, str | None]: ...
Effects in JSON are lowercase: allow, deny, approval_required. Precedence is DENY > APPROVAL_REQUIRED > ALLOW, independent of rule order.
class Rule: @classmethod def allow( cls, tool: str, action: str, *, agent_id: str | None = None, resource: str | NoResource | AnyResource = NO_RESOURCE, resource_kind: str | None = None, case_sensitive: bool = True, conditions: Sequence[Condition] = (), constraints: Mapping[str, Any] | None = None, schema_hash: str | None = None, ) -> Rule: ...
deny() and approval_required() (also aliased as require_approval() and approve()) use the same keyword-only shape. deny() rejects constraints.
resource defaults to NO_RESOURCE, which matches only requests with no resource. Use resource="*" (or ANY_RESOURCE) for a global rule. tool and action accept "*" as a whole-field wildcard; partial wildcards are not supported.

3. Condition

@dataclass(frozen=True) class Condition: field: str operator: ConditionOperator | str value: Any @classmethod def equals(cls, field: str, value: Any) -> Condition: ...
Conditions evaluate only against TrustedContext values. Supported operators are equals, notEquals, in, contains, startsWith, and endsWith.

4. TrustedContext

@dataclass(frozen=True) class TrustedContext: values: dict[str, Any] @classmethod def from_mapping(cls, values: Mapping[str, Any]) -> TrustedContext: ...
values must be a JSON object/dict. Dmint freezes it so later mutation cannot change an in-flight authorization decision.

5. Storage

SQLiteApprovalStore

class SQLiteApprovalStore(ApprovalStore): def __init__( self, database: str | Path, *, deployment_epoch: str, integrity_key: bytes | Path | str | None = None, recovery_epoch_file: str | Path | None = None, redact_keys: Collection[str] | None = None, max_pending_per_principal: int = 100, clock: Callable[[], datetime] | None = None, ) -> None: ...
Local SQLite persistence with WAL, a busy timeout, HMAC row integrity, cross-process recovery locking, and single-use consumption. deployment_epoch is required.

SQLAlchemyApprovalStore

class SQLAlchemyApprovalStore(ApprovalStore): def __init__( self, url_or_engine: str | Engine, *, deployment_epoch: str, integrity_key: bytes | Path | str | None = None, recovery_epoch_file: str | Path | None = None, redact_keys: Collection[str] | None = None, max_pending_per_principal: int = 100, clock: Callable[[], datetime] | None = None, ) -> None: ...
SQLAlchemy Core store for SQLite URLs and PostgreSQL. PostgreSQL uses row-level locking (SELECT ... FOR UPDATE) for atomic consumption.

ThreadSafeApprovalStore

class ThreadSafeApprovalStore(ApprovalStore): def __init__( self, database: str | Path | None = None, *, deployment_epoch: str = "default", integrity_key: bytes | Path | str | None = None, database_url: str | None = None, default_sqlite_path: str | Path = "dmint.db", recovery_epoch_file: str | Path | None = None, redact_keys: Collection[str] | None = None, max_pending_per_principal: int = 100, clock: Callable[[], datetime] | None = None, ) -> None: ...
Thread-local proxy used by server processes. For SQLite it keeps a store per thread; for PostgreSQL it delegates to the native pool.

create_approval_store

def create_approval_store( database_url: str | None = None, *, deployment_epoch: str, integrity_key: bytes | Path | str | None = None, default_sqlite_path: str | Path = "dmint.db", recovery_epoch_file: str | Path | None = None, redact_keys: Collection[str] | None = None, max_pending_per_principal: int = 100, clock: Callable[[], datetime] | None = None, ) -> ApprovalStore: ...
Uses DMINT_DATABASE_URL/database_url to choose SQLite or PostgreSQL. Invalid or unreachable configured databases raise ApprovalStoreConfigurationError; Dmint never silently falls back to SQLite.

6. Authority and Verification

LocalApprovalAuthority

class LocalApprovalAuthority: def __init__( self, *, issuer_id: str, audience: str, private_key: Ed25519PrivateKey | None = None, key_file: Path | str | None = None, clock: Callable[[], datetime] | None = None, ) -> None: ... def issue( self, record: ApprovalRecord, approver: ApprovalAuthority, *, now: datetime | None = None, ) -> ApprovalAssertion: ... def issue_for_human( self, record: ApprovalRecord, *, subject_id: str, now: datetime | None = None, ) -> ApprovalAssertion: ...
The private key is loaded from key_file, DMINT_KEY_FILE, or ~/.config/dmint/signing.key. It is intended only for the approval surface, never for the agent runtime.

ApprovalVerifier

class ApprovalVerifier: def __init__( self, *, trusted_issuers: Mapping[str, Ed25519PublicKey], audience: str, clock: Callable[[], datetime] | None = None, ) -> None: ... def verify( self, assertion: ApprovalAssertion | bytes, record: ApprovalRecord, *, now: datetime | None = None, ) -> VerifiedApproval: ...
ApprovalVerifier contains public keys only. verify() checks the signature, audience, issuer, expiration, approval/request IDs, full request fingerprint, principal, integration, and policy provenance against the supplied record.
Utilities:
from dmint import ApprovalAssertion assertion = ApprovalAssertion.from_bytes(raw_bytes) raw = assertion.to_bytes() from dmint.core import public_key_from_hex, public_key_from_pem key = public_key_from_hex("...")

7. Dashboard Integration

dmint.dashboard.CoreClient is the dashboard’s thin adapter over Core APIs. It is documented here because host integrations may use it for programmatic handoff:
class CoreClient: def __init__( self, store: ApprovalStore | None = None, authority: LocalApprovalAuthority | None = None, *, approver_id: str = "dashboard-human", deployment_epoch: str = "default", database_url: str | None = None, db_path: str | Path | None = None, clock: Callable[[], datetime] | None = None, ) -> None: ... def list_pending(self, *, limit: int = 100) -> list[ApprovalRecord]: ... def get_approval(self, approval_id: str) -> ApprovalRecord | None: ... def approve( self, approval_id: str, *, reason: str | None = None, approved_by: str | None = None, ) -> ApprovalRecord: ... def approve_with_assertion( self, approval_id: str, *, reason: str | None = None, approved_by: str | None = None, ) -> tuple[ApprovalRecord, ApprovalAssertion]: ... def issue_assertion( self, approval_id: str, ) -> ApprovalAssertion: ... def reject( self, approval_id: str, *, reason: str | None = None, rejected_by: str | None = None, ) -> ApprovalRecord: ...
issue_assertion() succeeds only for an APPROVED record. The assertion subject is the approver recorded on the approval, not the caller downloading the artifact. The dashboard uses it for the one-click assertion download; the returned assertion is still single-use and must be treated as a secret.