cayu.tools.grants

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

TARGETED_TOOL_GRANT_DEFAULT_LIFETIME_SECONDS

from cayu.tools import TARGETED_TOOL_GRANT_DEFAULT_LIFETIME_SECONDS

TARGETED_TOOL_GRANT_DEFAULT_LIFETIME_SECONDS = 300

Release source · Runtime guarantees · Capability guides

TARGETED_TOOL_GRANT_INSPECTION_MAX_RECORDS

from cayu.tools import TARGETED_TOOL_GRANT_INSPECTION_MAX_RECORDS

TARGETED_TOOL_GRANT_INSPECTION_MAX_RECORDS = 256

Release source · Runtime guarantees · Capability guides

TARGETED_TOOL_GRANT_MAX_CALLS

from cayu.tools import TARGETED_TOOL_GRANT_MAX_CALLS

TARGETED_TOOL_GRANT_MAX_CALLS = 32

Release source · Runtime guarantees · Capability guides

TARGETED_TOOL_GRANT_MAX_LIFETIME_SECONDS

from cayu.tools import TARGETED_TOOL_GRANT_MAX_LIFETIME_SECONDS

TARGETED_TOOL_GRANT_MAX_LIFETIME_SECONDS = 86400

Release source · Runtime guarantees · Capability guides

TARGETED_TOOL_GRANT_MAX_REQUESTS

from cayu.tools import TARGETED_TOOL_GRANT_MAX_REQUESTS

TARGETED_TOOL_GRANT_MAX_REQUESTS = 32

Release source · Runtime guarantees · Capability guides

TARGETED_TOOL_GRANT_SCHEMA_VERSION

from cayu.tools import TARGETED_TOOL_GRANT_SCHEMA_VERSION

TARGETED_TOOL_GRANT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

TargetedToolGrant

from cayu.tools import TargetedToolGrant

Application request for bounded addressability to one registered tool.

A request contains no executable, schema, policy, or authorization material. The runtime resolves all such identity from the registered catalogue.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	TARGETED_TOOL_GRANT_SCHEMA_VERSION
request_id	str	Field(max_length=TARGETED_TOOL_GRANT_REQUEST_ID_MAX_CHARS)
tool_id	str	required
max_calls	StrictInt	Field(default=1, ge=1, le=TARGETED_TOOL_GRANT_MAX_CALLS)
lifetime_seconds	StrictInt	Field(default=TARGETED_TOOL_GRANT_DEFAULT_LIFETIME_SECONDS, ge=1, le=TARGETED_TOOL_GRANT_MAX_LIFETIME_SECONDS)
expires_after_interaction	Literal[True]	True
origin	str | None	None

validate_schema_version (method)

TargetedToolGrant.validate_schema_version(value: object) -> object

validate_request_id (method)

TargetedToolGrant.validate_request_id(value: str) -> str

validate_interaction_expiry (method)

TargetedToolGrant.validate_interaction_expiry(value: object) -> object

validate_tool_id (method)

TargetedToolGrant.validate_tool_id(value: str) -> str

validate_origin (method)

TargetedToolGrant.validate_origin(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

TargetedToolGrantInspection

from cayu.tools import TargetedToolGrantInspection

Public grant state with aliased scope and no principal authority.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	TARGETED_TOOL_GRANT_SCHEMA_VERSION
grant_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
tool_ref	str	required
request_id	str	Field(max_length=TARGETED_TOOL_GRANT_REQUEST_ID_MAX_CHARS)
session_id	str	required
interaction_id	str	required
generation_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
agent_name	str	required
task_id	str | None	None
environment_name	str | None	None
tool_id	str	required
tool_name	str	required
catalogue_revision	str	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
issued_at	datetime	required
expires_at	datetime	required
expires_after_interaction	Literal[True]	True
max_calls	StrictInt	Field(ge=1, le=TARGETED_TOOL_GRANT_MAX_CALLS)
used_calls	StrictInt	Field(ge=0, le=TARGETED_TOOL_GRANT_MAX_CALLS)
origin	str | None	None
revoked_at	datetime | None	None

validate_schema_version (method)

TargetedToolGrantInspection.validate_schema_version(value: object) -> object

validate_interaction_expiry (method)

TargetedToolGrantInspection.validate_interaction_expiry(value: object) -> object

validate_tool_ref (method)

TargetedToolGrantInspection.validate_tool_ref(value: str) -> str

validate_request_identity (method)

TargetedToolGrantInspection.validate_request_identity(value: str) -> str

validate_scope_identity (method)

TargetedToolGrantInspection.validate_scope_identity(value: str, info) -> str

validate_optional_scope_identity (method)

TargetedToolGrantInspection.validate_optional_scope_identity(value: str | None, info) -> str | None

validate_tool_id (method)

TargetedToolGrantInspection.validate_tool_id(value: str) -> str

validate_catalogue_revision (method)

TargetedToolGrantInspection.validate_catalogue_revision(value: str) -> str

validate_descriptor_version (method)

TargetedToolGrantInspection.validate_descriptor_version(value: str) -> str

validate_origin (method)

TargetedToolGrantInspection.validate_origin(value: str | None) -> str | None

normalize_timestamp (method)

TargetedToolGrantInspection.normalize_timestamp(value: datetime | None, info) -> datetime | None

validate_lifecycle (method)

TargetedToolGrantInspection.validate_lifecycle() -> TargetedToolGrantInspection

remaining_calls (property)

TargetedToolGrantInspection.remaining_calls() -> int

Release source · Runtime guarantees · Capability guides

TargetedToolGrantIssueOutcome

from cayu.tools import TargetedToolGrantIssueOutcome

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
ISSUED	class attribute	'issued'
REUSED	class attribute	'reused'

Release source · Runtime guarantees · Capability guides

TargetedToolGrantIssueResult

from cayu.tools import TargetedToolGrantIssueResult

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
records	tuple[TargetedToolGrantRecord, ...]	required
outcomes	tuple[TargetedToolGrantIssueOutcome, ...]	required
events	tuple[Event, ...]	required

copy_records (method)

TargetedToolGrantIssueResult.copy_records(value: object) -> object

copy_events (method)

TargetedToolGrantIssueResult.copy_events(value: object) -> object

bound_outcomes (method)

TargetedToolGrantIssueResult.bound_outcomes(value: object) -> object

validate_lengths (method)

TargetedToolGrantIssueResult.validate_lengths() -> TargetedToolGrantIssueResult

Release source · Runtime guarantees · Capability guides

TargetedToolGrantReconstructionResult

from cayu.tools import TargetedToolGrantReconstructionResult

Validated grants remaining callable within one recovered interaction.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
valid	tuple[TargetedToolGrantRecord, ...]	()
rejected	tuple[tuple[str, TargetedToolUseRejectionReason], ...]	()
events	tuple[Event, ...]	()

copy_valid_records (method)

TargetedToolGrantReconstructionResult.copy_valid_records(value: object) -> object

copy_events (method)

TargetedToolGrantReconstructionResult.copy_events(value: object) -> object

bound_rejections (method)

TargetedToolGrantReconstructionResult.bound_rejections(value: object) -> object

validate_shape (method)

TargetedToolGrantReconstructionResult.validate_shape() -> TargetedToolGrantReconstructionResult

Release source · Runtime guarantees · Capability guides

TargetedToolGrantRecord

from cayu.tools import TargetedToolGrantRecord

Immutable durable state for one issued targeted reference.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	TARGETED_TOOL_GRANT_SCHEMA_VERSION
grant_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
tool_ref	str	required
request_id	str	Field(max_length=TARGETED_TOOL_GRANT_REQUEST_ID_MAX_CHARS)
session_id	str	required
interaction_id	str	required
generation_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
agent_name	str	required
task_id	str | None	None
environment_name	str | None	None
principal	str | None	None
tenant	str | None	None
tool_id	str	required
tool_name	str	required
catalogue_revision	str	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
issued_at	datetime	required
expires_at	datetime	required
expires_after_interaction	StrictBool	True
max_calls	StrictInt	Field(ge=1, le=TARGETED_TOOL_GRANT_MAX_CALLS)
used_calls	StrictInt	Field(default=0, ge=0, le=TARGETED_TOOL_GRANT_MAX_CALLS)
origin	str | None	None
revoked_at	datetime | None	None
revocation_reason	str | None	None

validate_schema_version (method)

TargetedToolGrantRecord.validate_schema_version(value: object) -> object

validate_required_text (method)

TargetedToolGrantRecord.validate_required_text(value: str, info) -> str

validate_request_identity (method)

TargetedToolGrantRecord.validate_request_identity(value: str) -> str

validate_tool_ref (method)

TargetedToolGrantRecord.validate_tool_ref(value: str) -> str

validate_scope_identity (method)

TargetedToolGrantRecord.validate_scope_identity(value: str, info) -> str

validate_tool_id (method)

TargetedToolGrantRecord.validate_tool_id(value: str) -> str

validate_catalogue_revision (method)

TargetedToolGrantRecord.validate_catalogue_revision(value: str) -> str

validate_descriptor_version (method)

TargetedToolGrantRecord.validate_descriptor_version(value: str) -> str

validate_optional_text (method)

TargetedToolGrantRecord.validate_optional_text(value: str | None, info) -> str | None

validate_origin (method)

TargetedToolGrantRecord.validate_origin(value: str | None) -> str | None

validate_revocation_reason (method)

TargetedToolGrantRecord.validate_revocation_reason(value: str | None) -> str | None

normalize_timestamp (method)

TargetedToolGrantRecord.normalize_timestamp(value: datetime | None, info) -> datetime | None

validate_lifecycle (method)

TargetedToolGrantRecord.validate_lifecycle() -> TargetedToolGrantRecord

remaining_calls (property)

TargetedToolGrantRecord.remaining_calls() -> int

Release source · Runtime guarantees · Capability guides

TargetedToolGrantStateSnapshot

from cayu.tools import TargetedToolGrantStateSnapshot

Complete typed grant state for trusted durable export and validation.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	TARGETED_TOOL_GRANT_SCHEMA_VERSION
records	tuple[TargetedToolGrantRecord, ...]	()
uses	tuple[TargetedToolUseBinding, ...]	()

validate_schema_version (method)

TargetedToolGrantStateSnapshot.validate_schema_version(value: object) -> object

require_materialized_sequences (method)

TargetedToolGrantStateSnapshot.require_materialized_sequences(value: object, info) -> object

validate_state (method)

TargetedToolGrantStateSnapshot.validate_state() -> TargetedToolGrantStateSnapshot

Release source · Runtime guarantees · Capability guides

TargetedToolUseBinding

from cayu.tools import TargetedToolUseBinding

Permanent digest-only evidence for one accepted grant use.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
schema_version	Literal[1]	TARGETED_TOOL_GRANT_SCHEMA_VERSION
grant_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
use_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
session_id	str	required
interaction_id	str	required
model_step_id	str	required
outer_tool_call_id	str	required
arguments_sha256	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
invocation_id	str	required
bound_at	datetime	required

validate_schema_version (method)

TargetedToolUseBinding.validate_schema_version(value: object) -> object

validate_required_text (method)

TargetedToolUseBinding.validate_required_text(value: str, info) -> str

validate_scope_identity (method)

TargetedToolUseBinding.validate_scope_identity(value: str, info) -> str

validate_execution_identity (method)

TargetedToolUseBinding.validate_execution_identity(value: str, info) -> str

normalize_timestamp (method)

TargetedToolUseBinding.normalize_timestamp(value: datetime) -> datetime

validate_use_id (method)

TargetedToolUseBinding.validate_use_id() -> TargetedToolUseBinding

Release source · Runtime guarantees · Capability guides

TargetedToolUseDisposition

from cayu.tools import TargetedToolUseDisposition

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
BOUND	class attribute	'bound'
REJOINED	class attribute	'rejoined'
REJECTED	class attribute	'rejected'

Release source · Runtime guarantees · Capability guides

TargetedToolUseRejectionReason

from cayu.tools import TargetedToolUseRejectionReason

Bases: StrEnum.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
MALFORMED	class attribute	'malformed'
UNKNOWN	class attribute	'unknown'
NOT_YET_VALID	class attribute	'not_yet_valid'
EXPIRED	class attribute	'expired'
REVOKED	class attribute	'revoked'
EXHAUSTED	class attribute	'exhausted'
CROSS_SESSION	class attribute	'cross_session'
CROSS_INTERACTION	class attribute	'cross_interaction'
CROSS_GENERATION	class attribute	'cross_generation'
PRINCIPAL_MISMATCH	class attribute	'principal_mismatch'
TENANT_MISMATCH	class attribute	'tenant_mismatch'
AGENT_MISMATCH	class attribute	'agent_mismatch'
TASK_MISMATCH	class attribute	'task_mismatch'
ENVIRONMENT_MISMATCH	class attribute	'environment_mismatch'
OUT_OF_CEILING	class attribute	'out_of_ceiling'
CATALOGUE_DRIFT	class attribute	'catalogue_drift'
DESCRIPTOR_DRIFT	class attribute	'descriptor_drift'
INVALID_ARGUMENTS	class attribute	'invalid_arguments'
ALTERED_REPLAY	class attribute	'altered_replay'

Release source · Runtime guarantees · Capability guides

TargetedToolUseRequest

from cayu.tools import TargetedToolUseRequest

Bounded identities required to reserve one future effective invocation.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
tool_ref	str	required
session_id	str	required
interaction_id	str	required
generation_id	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
agent_name	str	required
task_id	str | None	None
environment_name	str | None	None
principal	str | None	None
tenant	str | None	None
catalogue_revision	str	required
descriptor_version	str	required
schema_fingerprint	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
tool_id	str	required
tool_name	str	required
model_step_id	str	required
outer_tool_call_id	str	required
arguments_sha256	str	Field(pattern=TARGETED_TOOL_DIGEST_PATTERN)
invocation_id	str	required
expected_run_epoch	StrictInt	Field(ge=0)

validate_tool_ref (method)

TargetedToolUseRequest.validate_tool_ref(value: str) -> str

validate_scope_identity (method)

TargetedToolUseRequest.validate_scope_identity(value: str, info) -> str

validate_execution_identity (method)

TargetedToolUseRequest.validate_execution_identity(value: str, info) -> str

validate_tool_id (method)

TargetedToolUseRequest.validate_tool_id(value: str) -> str

validate_catalogue_revision (method)

TargetedToolUseRequest.validate_catalogue_revision(value: str) -> str

validate_descriptor_version (method)

TargetedToolUseRequest.validate_descriptor_version(value: str) -> str

validate_optional_text (method)

TargetedToolUseRequest.validate_optional_text(value: str | None, info) -> str | None

Release source · Runtime guarantees · Capability guides

TargetedToolUseResult

from cayu.tools import TargetedToolUseResult

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
disposition	TargetedToolUseDisposition	required
reason	TargetedToolUseRejectionReason | None	None
grant	TargetedToolGrantRecord | None	None
binding	TargetedToolUseBinding | None	None
event	Event | None	None

copy_grant (method)

TargetedToolUseResult.copy_grant(value: object) -> object

copy_event_evidence (method)

TargetedToolUseResult.copy_event_evidence(value: object) -> object

validate_shape (method)

TargetedToolUseResult.validate_shape() -> TargetedToolUseResult

Release source · Runtime guarantees · Capability guides