Pydantic AI API

Install threvo-actions[pydantic-ai] before importing this module.

pydantic_ai

Pydantic AI Capability for confirm-first financial actions.

SafeReference module-attribute

SafeReference = Annotated[str, StringConstraints(min_length=1, max_length=255), AfterValidator(_validate_safe_reference)]

DepsT module-attribute

DepsT = TypeVar('DepsT')

DepsContraT module-attribute

DepsContraT = TypeVar('DepsContraT', contravariant=True)

CommandT module-attribute

CommandT = TypeVar('CommandT', bound=BaseModel)

PrivateSnapshotT module-attribute

PrivateSnapshotT = TypeVar('PrivateSnapshotT', bound=BaseModel)

PreviewT module-attribute

PreviewT = TypeVar('PreviewT', bound=BaseModel)

ResultT module-attribute

ResultT = TypeVar('ResultT', bound=BaseModel)

JsonObject module-attribute

JsonObject = dict[str, JsonValue]

_TOOL_NAME_PATTERN module-attribute

_TOOL_NAME_PATTERN = re.compile('^[a-z][a-z0-9_]{0,63}$', flags=re.ASCII)

__all__ module-attribute

__all__ = ['ActionAgentContext', 'ActionCapability', 'ActionContextResolver', 'ActionToolBinding', 'ActionToolResult', 'DeferredActionRequest', 'InlineAuthorityHandler', 'IntegrationOutcome']

ActionType

Bases: ExperimentalModel

A host-defined action name with an explicit contract version.

namespace instance-attribute

namespace: ActionNamespace

name instance-attribute

name: ActionName

version instance-attribute

version: Annotated[int, Field(ge=1)]

EvidenceConsumer

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['evidence_consumer'] = 'evidence_consumer'

reference instance-attribute

reference: SafeReference

ExperimentalModel

Bases: BaseModel

Strict, immutable base for the experimental public contract.

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', strict=True, frozen=True)

LifecycleStatus

Bases: StrEnum

Closed lifecycle vocabulary for proposal execution and verification.

AWAITING_AUTHORITY class-attribute instance-attribute

AWAITING_AUTHORITY = 'awaiting_authority'

DENIED class-attribute instance-attribute

DENIED = 'denied'

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

AUTHORIZED class-attribute instance-attribute

AUTHORIZED = 'authorized'

BLOCKED class-attribute instance-attribute

BLOCKED = 'blocked'

STALE class-attribute instance-attribute

STALE = 'stale'

SUPERSEDED class-attribute instance-attribute

SUPERSEDED = 'superseded'

EXECUTING class-attribute instance-attribute

EXECUTING = 'executing'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

VERIFICATION_PENDING class-attribute instance-attribute

VERIFICATION_PENDING = 'verification_pending'

VERIFICATION_UNRESOLVED class-attribute instance-attribute

VERIFICATION_UNRESOLVED = 'verification_unresolved'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

VERIFIED class-attribute instance-attribute

VERIFIED = 'verified'

ProposingAgent

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['proposing_agent'] = 'proposing_agent'

reference instance-attribute

reference: SafeReference

RequestingPrincipal

Bases: ExperimentalModel

kind class-attribute instance-attribute

kind: Literal['requesting_principal'] = 'requesting_principal'

reference instance-attribute

reference: SafeReference

ReadContext

Bases: ExperimentalModel

tenant_reference instance-attribute

tenant_reference: SafeReference

consumer instance-attribute

consumer: EvidenceConsumer

ActionOperationResult

Bases: ExperimentalModel

proposal_reference instance-attribute

proposal_reference: SafeReference

lifecycle_status instance-attribute

lifecycle_status: LifecycleStatus

outcome instance-attribute

outcome: OperationOutcome

revision instance-attribute

revision: int

display_preview class-attribute instance-attribute

display_preview: JsonObject = Field(default_factory=dict)

safe_result class-attribute instance-attribute

safe_result: JsonObject | None = None

fresh_proposal_reference class-attribute instance-attribute

fresh_proposal_reference: SafeReference | None = None

reason_code class-attribute instance-attribute

reason_code: SafeReference | None = None

is_terminal property

is_terminal: bool

Whether the proposal lifecycle has no valid transition left.

needs_reconciliation property

needs_reconciliation: bool

Whether authoritative reconciliation may advance this proposal.

ActionRuntime

ActionRuntime(*, store: ActionStore, retention_store: RetentionStore | None = None, clock: Clock | None = None, identifiers: IdentifierProvider | None = None, event_sink: EventSink | None = None, runtime_revision: str | None = None)

Coordinates host-owned controls without owning host business truth.

prepare async

prepare(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, command: CommandT, requesting_principal: RequestingPrincipal, proposing_agent: ProposingAgent | None = None) -> ActionOperationResult

record_authority async

record_authority(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, evidence: AuthorityEvidence, authenticated_authority: ConfirmingAuthority, proposal_reference: str | None = None) -> ActionOperationResult

expire_due async

expire_due(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

Expire an unexecuted proposal once its prepared lifetime has elapsed.

execute async

execute(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

reconcile async

reconcile(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, tenant_reference: str, proposal_reference: str) -> ActionOperationResult

read async

read(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, proposal_reference: str, context: ReadContext) -> ProposalView

erase async

erase(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], *, proposal_reference: str, context: ReadContext) -> ActionOperationResult

AuthorizationDeniedError

Bases: PermissionError

OperationOutcome

Bases: StrEnum

PREPARED class-attribute instance-attribute

PREPARED = 'prepared'

AUTHORITY_PENDING class-attribute instance-attribute

AUTHORITY_PENDING = 'authority_pending'

AUTHORIZED class-attribute instance-attribute

AUTHORIZED = 'authorized'

DENIED class-attribute instance-attribute

DENIED = 'denied'

BLOCKED class-attribute instance-attribute

BLOCKED = 'blocked'

STALE class-attribute instance-attribute

STALE = 'stale'

IN_PROGRESS class-attribute instance-attribute

IN_PROGRESS = 'in_progress'

EXPIRED class-attribute instance-attribute

EXPIRED = 'expired'

REPLAYED class-attribute instance-attribute

REPLAYED = 'replayed'

CONFLICT class-attribute instance-attribute

CONFLICT = 'conflict'

VERIFICATION_PENDING class-attribute instance-attribute

VERIFICATION_PENDING = 'verification_pending'

VERIFIED class-attribute instance-attribute

VERIFIED = 'verified'

PARTIALLY_SUCCEEDED class-attribute instance-attribute

PARTIALLY_SUCCEEDED = 'partially_succeeded'

FAILED_KNOWN class-attribute instance-attribute

FAILED_KNOWN = 'failed_known'

FAILED_UNKNOWN class-attribute instance-attribute

FAILED_UNKNOWN = 'failed_unknown'

VERIFICATION_UNRESOLVED class-attribute instance-attribute

VERIFICATION_UNRESOLVED = 'verification_unresolved'

RESEND_ALLOWED class-attribute instance-attribute

RESEND_ALLOWED = 'resend_allowed'

ERASED class-attribute instance-attribute

ERASED = 'erased'

ProposalNotFoundError

ProposalNotFoundError()

Bases: LookupError

ActionDefinition dataclass

ActionDefinition(action_type: ActionType, command_model: type[CommandT], private_snapshot_model: type[PrivateSnapshotT], display_preview_model: type[PreviewT], result_model: type[ResultT], preparation: PreparationPort[CommandT, PrivateSnapshotT, PreviewT], authorization: AuthorizationPort[CommandT, PrivateSnapshotT], authority_evaluator: AuthorityEvaluatorPort, state_resolver: StateResolverPort[PrivateSnapshotT, PreviewT], executor: GovernedExecutorPort[PrivateSnapshotT, ResultT], verifier: VerifierPort[ResultT], commitment_provider: CommitmentProvider, protection_codec: ProtectionCodec, retention: RetentionPort, proposal_ttl: timedelta, executor_identity: GovernedExecutor, target_identity: AuthoritativeTarget, authority_audience: str, authority_channel_assurance: str, verification_delay: timedelta = timedelta(0), max_verification_attempts: int = 3, effect_kind: EffectKind = 'single', allow_resend_after_final_absence: bool = False, verification_lease_duration: timedelta = timedelta(minutes=1), semantic_idempotency_strategy: Literal['host_defined'] = 'host_defined')

Bases: Generic[CommandT, PrivateSnapshotT, PreviewT, ResultT]

action_type instance-attribute

action_type: ActionType

command_model instance-attribute

command_model: type[CommandT]

private_snapshot_model instance-attribute

private_snapshot_model: type[PrivateSnapshotT]

display_preview_model instance-attribute

display_preview_model: type[PreviewT]

result_model instance-attribute

result_model: type[ResultT]

preparation instance-attribute

preparation: PreparationPort[CommandT, PrivateSnapshotT, PreviewT]

authorization instance-attribute

authorization: AuthorizationPort[CommandT, PrivateSnapshotT]

authority_evaluator instance-attribute

authority_evaluator: AuthorityEvaluatorPort

state_resolver instance-attribute

state_resolver: StateResolverPort[PrivateSnapshotT, PreviewT]

executor instance-attribute

executor: GovernedExecutorPort[PrivateSnapshotT, ResultT]

verifier instance-attribute

verifier: VerifierPort[ResultT]

commitment_provider instance-attribute

commitment_provider: CommitmentProvider

protection_codec instance-attribute

protection_codec: ProtectionCodec

retention instance-attribute

retention: RetentionPort

proposal_ttl instance-attribute

proposal_ttl: timedelta

executor_identity instance-attribute

executor_identity: GovernedExecutor

target_identity instance-attribute

target_identity: AuthoritativeTarget

authority_audience instance-attribute

authority_audience: str

authority_channel_assurance instance-attribute

authority_channel_assurance: str

verification_delay class-attribute instance-attribute

verification_delay: timedelta = timedelta(0)

max_verification_attempts class-attribute instance-attribute

max_verification_attempts: int = 3

effect_kind class-attribute instance-attribute

effect_kind: EffectKind = 'single'

allow_resend_after_final_absence class-attribute instance-attribute

allow_resend_after_final_absence: bool = False

verification_lease_duration class-attribute instance-attribute

verification_lease_duration: timedelta = timedelta(minutes=1)

semantic_idempotency_strategy class-attribute instance-attribute

semantic_idempotency_strategy: Literal['host_defined'] = 'host_defined'

__post_init__

__post_init__() -> None

ActionAgentContext

Bases: ExperimentalModel

Trusted host context resolved from authenticated agent dependencies.

tenant_reference instance-attribute

tenant_reference: SafeReference

requesting_principal instance-attribute

requesting_principal: RequestingPrincipal

evidence_consumer instance-attribute

evidence_consumer: EvidenceConsumer

proposing_agent class-attribute instance-attribute

proposing_agent: ProposingAgent | None = None

IntegrationOutcome

Bases: StrEnum

INVALID_CONTINUATION class-attribute instance-attribute

INVALID_CONTINUATION = 'invalid_continuation'

PREPARATION_DENIED class-attribute instance-attribute

PREPARATION_DENIED = 'preparation_denied'

ActionToolResult

Bases: ExperimentalModel

Display-safe result returned to the model after a continuation attempt.

proposal_reference class-attribute instance-attribute

proposal_reference: SafeReference | None = None

lifecycle_status class-attribute instance-attribute

lifecycle_status: LifecycleStatus | None = None

outcome instance-attribute

outcome: OperationOutcome | IntegrationOutcome

revision class-attribute instance-attribute

revision: int | None = None

display_preview class-attribute instance-attribute

display_preview: JsonObject = Field(default_factory=dict)

safe_result class-attribute instance-attribute

safe_result: JsonObject | None = None

fresh_proposal_reference class-attribute instance-attribute

fresh_proposal_reference: SafeReference | None = None

DeferredActionRequest

Bases: ExperimentalModel

Safe request passed to an optional server-side inline authority handler.

tool_call_id instance-attribute

tool_call_id: SafeReference

tool_name instance-attribute

tool_name: SafeReference

proposal_reference instance-attribute

proposal_reference: SafeReference

action_type instance-attribute

action_type: ActionType

ActionContextResolver

Bases: Protocol[DepsContraT]

__call__

__call__(deps: DepsContraT) -> ActionAgentContext

InlineAuthorityHandler

Bases: Protocol[DepsContraT]

__call__

__call__(request: DeferredActionRequest, *, deps: DepsContraT) -> bool | Awaitable[bool]

_ContinuationMetadata

Bases: ExperimentalModel

proposal_reference instance-attribute

proposal_reference: SafeReference

tool_name instance-attribute

tool_name: SafeReference

action_type instance-attribute

action_type: ActionType

display_preview instance-attribute

display_preview: JsonObject

_BuildableBinding

Bases: Protocol[DepsContraT]

name property

name: str

build_tool

build_tool(runtime: ActionRuntime) -> Tool[DepsContraT]

ActionToolBinding dataclass

ActionToolBinding(definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT], context_resolver: ActionContextResolver[DepsT], name: str, description: str)

Bases: Generic[DepsT, CommandT, PrivateSnapshotT, PreviewT, ResultT]

Explicitly binds one action definition to one model-visible tool.

definition instance-attribute

definition: ActionDefinition[CommandT, PrivateSnapshotT, PreviewT, ResultT]

context_resolver instance-attribute

context_resolver: ActionContextResolver[DepsT]

name instance-attribute

name: str

description instance-attribute

description: str

__post_init__

__post_init__() -> None

build_tool

build_tool(runtime: ActionRuntime) -> Tool[DepsT]

ActionCapability dataclass

ActionCapability(*, runtime: ActionRuntime, bindings: Sequence[_BuildableBinding[DepsT]], inline_authority_handler: InlineAuthorityHandler[DepsT] | None = None, id: str = 'threvo_actions')

Bases: AbstractCapability[DepsT]

Expose confirm-first actions without trusting framework approval as authority.

id instance-attribute

id = id

description instance-attribute

description = 'Prepare and safely resume confirm-first financial actions.'

defer_loading instance-attribute

defer_loading = False

get_serialization_name classmethod

get_serialization_name() -> str | None

get_instructions

get_instructions() -> str

get_toolset

get_toolset() -> FunctionToolset[DepsT]

build_continuation_results

build_continuation_results(requests: DeferredToolRequests, *, decisions: Mapping[str, bool]) -> DeferredToolResults

Build framework continuations while preserving safe proposal metadata.

handle_deferred_tool_calls async

handle_deferred_tool_calls(ctx: RunContext[DepsT], *, requests: DeferredToolRequests) -> DeferredToolResults | None

_tool_result

_tool_result(result: ActionOperationResult) -> ActionToolResult

_continuation_metadata

_continuation_metadata(value: object) -> _ContinuationMetadata | None