cayu.knowledge.enrichment

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.

`DEFAULT_KNOWLEDGE_ENRICHMENT_TASK_TYPE`

from cayu import DEFAULT_KNOWLEDGE_ENRICHMENT_TASK_TYPE

DEFAULT_KNOWLEDGE_ENRICHMENT_TASK_TYPE = 'cayu.knowledge-enrichment.v1'

Release source · Runtime guarantees · Capability guides

`knowledge_enrichment_profile`

from cayu import knowledge_enrichment_profile

Derive the stable worker profile from existing curator contracts.

knowledge_enrichment_profile(config: KnowledgeCuratorConfig, access_scope: KnowledgeAccessScope) -> KnowledgeEnrichmentProfile

Release source · Runtime guarantees · Capability guides

`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`

from cayu import KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION

KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentConflict`

from cayu import KnowledgeEnrichmentConflict

Durable task evidence conflicts with the requested enrichment job.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentExceptionClassifier`

from cayu import KnowledgeEnrichmentExceptionClassifier

Optional application policy for retrying escaped infrastructure failures.

Bases: Protocol.

call (method)

KnowledgeEnrichmentExceptionClassifier.__call__(error: Exception) -> KnowledgeEnrichmentFailureDecision

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentFailure`

from cayu import KnowledgeEnrichmentFailure

Bounded diagnostic safe for durable task error payloads.

Bases: _EnrichmentModel.

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]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`request_sha256`	`StrictStr \| None`	`None`
`code`	`StrictStr`	`required`
`category`	`KnowledgeEnrichmentFailureCategory`	`required`
`retryable`	`StrictBool`	`required`
`annotation`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_request_sha256 (method)

KnowledgeEnrichmentFailure.validate_request_sha256(value: str | None) -> str | None

validate_code (method)

KnowledgeEnrichmentFailure.validate_code(value: str) -> str

copy_annotation (method)

KnowledgeEnrichmentFailure.copy_annotation(value: object) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentFailureCategory`

from cayu import KnowledgeEnrichmentFailureCategory

Content-safe worker failure classes.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`INVALID_JOB`	`class attribute`	`'invalid_job'`
`PROFILE_CONFLICT`	`class attribute`	`'profile_conflict'`
`DEPENDENCY_UNAVAILABLE`	`class attribute`	`'dependency_unavailable'`
`SEMANTIC_OUTCOME_UNKNOWN`	`class attribute`	`'semantic_outcome_unknown'`
`RESULT_LIMIT_EXCEEDED`	`class attribute`	`'result_limit_exceeded'`
`CANCELLED`	`class attribute`	`'cancelled'`
`INTERNAL_ERROR`	`class attribute`	`'internal_error'`

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentFailureDecision`

from cayu import KnowledgeEnrichmentFailureDecision

Application classification for an exception that escaped the curator.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`code`	`StrictStr`	`required`
`category`	`KnowledgeEnrichmentFailureCategory`	`required`
`retryable`	`StrictBool`	`False`
`retry_after_seconds`	`StrictFloat \| None`	`Field(default=None, ge=0, le=86400)`

validate_code (method)

KnowledgeEnrichmentFailureDecision.validate_code(value: str) -> str

validate_retry_delay (method)

KnowledgeEnrichmentFailureDecision.validate_retry_delay() -> KnowledgeEnrichmentFailureDecision

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentFeedbackAuthorization`

from cayu import KnowledgeEnrichmentFeedbackAuthorization

Application policy evidence for explicitly declared memory-derived input.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`policy_identity`	`StrictStr`	`required`
`policy_version`	`StrictStr`	`required`
`independent_source_fingerprints`	`tuple[StrictStr, ...]`	`Field(min_length=1, max_length=MAX_LEARNING_SIGNALS)`

validate_identity (method)

KnowledgeEnrichmentFeedbackAuthorization.validate_identity(value: str, info) -> str

copy_source_fingerprints (method)

KnowledgeEnrichmentFeedbackAuthorization.copy_source_fingerprints(value: object) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentJob`

from cayu import KnowledgeEnrichmentJob

Current, defensively copied view of one complete enrichment retry series.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`id`	`StrictStr`	`required`
`current_task_id`	`StrictStr`	`required`
`operation_id`	`StrictStr`	`required`
`request_sha256`	`StrictStr`	`required`
`status`	`KnowledgeEnrichmentJobStatus`	`required`
`request`	`KnowledgeEnrichmentRequest`	`required`
`attempts`	`tuple[KnowledgeEnrichmentAttempt, ...]`	`Field(min_length=1, max_length=100)`
`result`	`KnowledgeEnrichmentJobResult \| None`	`None`
`failure`	`KnowledgeEnrichmentFailure \| None`	`None`
`next_eligible_at`	`datetime \| None`	`None`

validate_identity (method)

KnowledgeEnrichmentJob.validate_identity(value: str, info) -> str

validate_request_sha256 (method)

KnowledgeEnrichmentJob.validate_request_sha256(value: str) -> str

copy_request (method)

KnowledgeEnrichmentJob.copy_request(value: object) -> object

copy_attempts (method)

KnowledgeEnrichmentJob.copy_attempts(value: object) -> object

copy_result (method)

KnowledgeEnrichmentJob.copy_result(value: object) -> object

copy_failure (method)

KnowledgeEnrichmentJob.copy_failure(value: object) -> object

normalize_next_eligible_at (method)

KnowledgeEnrichmentJob.normalize_next_eligible_at(value: datetime | None) -> datetime | None

validate_terminal_shape (method)

KnowledgeEnrichmentJob.validate_terminal_shape() -> KnowledgeEnrichmentJob

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentJobRejected`

from cayu import KnowledgeEnrichmentJobRejected

A claimed malformed job was durably rejected instead of representing idle work.

Bases: RuntimeError.

init (method)

KnowledgeEnrichmentJobRejected.__init__(task_id: str) -> None

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentJobResult`

from cayu import KnowledgeEnrichmentJobResult

Exact bounded curation result committed with task-series settlement.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`request_sha256`	`StrictStr`	`required`
`task_id`	`StrictStr`	`required`
`attempt`	`StrictInt`	`Field(ge=1, le=100)`
`curation`	`LearningBatchResult`	`required`

validate_request_sha256 (method)

KnowledgeEnrichmentJobResult.validate_request_sha256(value: str) -> str

validate_task_id (method)

KnowledgeEnrichmentJobResult.validate_task_id(value: str) -> str

copy_curation (method)

KnowledgeEnrichmentJobResult.copy_curation(value: object) -> object

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentJobStatus`

from cayu import KnowledgeEnrichmentJobStatus

Current projection of one complete enrichment retry series.

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`PENDING`	`class attribute`	`'pending'`
`PROCESSING`	`class attribute`	`'processing'`
`RETRY_SCHEDULED`	`class attribute`	`'retry_scheduled'`
`COMPLETED`	`class attribute`	`'completed'`
`FAILED`	`class attribute`	`'failed'`
`CANCELLED`	`class attribute`	`'cancelled'`

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentProfile`

from cayu import KnowledgeEnrichmentProfile

Exact application-owned curator and access policy expected by a worker.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`curator_configuration_fingerprint`	`StrictStr`	`required`
`access_scope_sha256`	`StrictStr`	`required`
`candidate_generator_identity`	`StrictStr`	`required`
`evaluator_identity`	`StrictStr`	`required`
`candidate_policy_identity`	`StrictStr \| None`	`None`
`governance_mode`	`KnowledgeGovernanceMode`	`required`
`activation_policy_identity`	`StrictStr \| None`	`None`
`activation_policy_version`	`StrictStr \| None`	`None`

validate_fingerprint (method)

KnowledgeEnrichmentProfile.validate_fingerprint(value: str, info) -> str

validate_identity (method)

KnowledgeEnrichmentProfile.validate_identity(value: str | None, info) -> str | None

validate_governance_identity (method)

KnowledgeEnrichmentProfile.validate_governance_identity() -> KnowledgeEnrichmentProfile

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentQueue`

from cayu import KnowledgeEnrichmentQueue

Submit and inspect exact enrichment jobs in an existing TaskStore.

init (method)

KnowledgeEnrichmentQueue.__init__(task_store: TaskStore, *, curator_config: KnowledgeCuratorConfig, access_scope: KnowledgeAccessScope, config: KnowledgeEnrichmentQueueConfig | None=None) -> None

task_store (property)

KnowledgeEnrichmentQueue.task_store() -> TaskStore

config (property)

KnowledgeEnrichmentQueue.config() -> KnowledgeEnrichmentQueueConfig

profile (property)

KnowledgeEnrichmentQueue.profile() -> KnowledgeEnrichmentProfile

task_type (property)

KnowledgeEnrichmentQueue.task_type() -> str

Return the effective execution-domain route claimed by this queue’s workers.

submit (method)

async KnowledgeEnrichmentQueue.submit(request: KnowledgeEnrichmentRequest) -> KnowledgeEnrichmentJob

Create or exactly replay one durable enrichment retry series.

load (method)

async KnowledgeEnrichmentQueue.load(operation_id: str) -> KnowledgeEnrichmentJob | None

Load the complete bounded retry series for one operation identity.

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentQueueConfig`

from cayu import KnowledgeEnrichmentQueueConfig

Queue route namespace plus finite payload and retry ceilings.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`task_type`	`StrictStr`	`Field(default=DEFAULT_KNOWLEDGE_ENRICHMENT_TASK_TYPE, description='Application route namespace; KnowledgeEnrichmentQueue.task_type is the profile- and configuration-derived effective TaskStore route.')`
`max_request_bytes`	`StrictInt`	`Field(default=512 * 1024, ge=1)`
`max_result_bytes`	`StrictInt`	`Field(default=MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES, ge=MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES, le=MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES)`
`max_reclaims_per_poll`	`StrictInt`	`Field(default=100, ge=1, le=MAX_KNOWLEDGE_ENRICHMENT_RECLAIMS_PER_POLL)`
`retry_policy`	`TaskRetryPolicy`	`Field(default_factory=lambda: TaskRetryPolicy(max_attempts=3, initial_backoff_seconds=1.0, backoff_multiplier=2.0, max_backoff_seconds=30.0))`
`terminalization_retry_policy`	`TaskTerminalizationRetryPolicy`	`Field(default_factory=TaskTerminalizationRetryPolicy)`

validate_task_type (method)

KnowledgeEnrichmentQueueConfig.validate_task_type(value: str) -> str

copy_retry_policy (method)

KnowledgeEnrichmentQueueConfig.copy_retry_policy(value: object) -> object

copy_terminalization_policy (method)

KnowledgeEnrichmentQueueConfig.copy_terminalization_policy(value: object) -> object

validate_byte_ceilings (method)

KnowledgeEnrichmentQueueConfig.validate_byte_ceilings() -> KnowledgeEnrichmentQueueConfig

fingerprint (property)

KnowledgeEnrichmentQueueConfig.fingerprint() -> str

Bind behavior-bearing durable queue settings, excluding local I/O retries.

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentRequest`

from cayu import KnowledgeEnrichmentRequest

One bounded, exact, application-submitted enrichment operation.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`operation_id`	`StrictStr`	`required`
`batch`	`LearningBatch`	`required`
`trigger`	`KnowledgeEnrichmentTrigger`	`required`
`profile`	`KnowledgeEnrichmentProfile`	`required`
`submitted_at`	`datetime`	`required`
`execution_source`	`TaskExecutionSource`	`TaskExecutionSource.SDK_TASK`
`invocation_origin`	`InvocationOriginClaim \| None`	`None`
`feedback_authorization`	`KnowledgeEnrichmentFeedbackAuthorization \| None`	`None`

validate_operation_id (method)

KnowledgeEnrichmentRequest.validate_operation_id(value: str) -> str

copy_batch (method)

KnowledgeEnrichmentRequest.copy_batch(value: object) -> object

copy_trigger (method)

KnowledgeEnrichmentRequest.copy_trigger(value: object) -> object

copy_profile (method)

KnowledgeEnrichmentRequest.copy_profile(value: object) -> object

copy_feedback_authorization (method)

KnowledgeEnrichmentRequest.copy_feedback_authorization(value: object) -> object

copy_invocation_origin (method)

KnowledgeEnrichmentRequest.copy_invocation_origin(value: object) -> object

normalize_submitted_at (method)

KnowledgeEnrichmentRequest.normalize_submitted_at(value: datetime) -> datetime

validate_execution_source (method)

KnowledgeEnrichmentRequest.validate_execution_source(value: TaskExecutionSource) -> TaskExecutionSource

validate_feedback_boundary (method)

KnowledgeEnrichmentRequest.validate_feedback_boundary() -> KnowledgeEnrichmentRequest

fingerprint (property)

KnowledgeEnrichmentRequest.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentTrigger`

from cayu import KnowledgeEnrichmentTrigger

Application-declared boundary that caused one batch to be submitted.

Bases: _EnrichmentModel.

Fields and attributes

Name	Type	Default
`schema_version`	`Literal[1]`	`KNOWLEDGE_ENRICHMENT_SCHEMA_VERSION`
`kind`	`StrictStr`	`required`
`source_type`	`StrictStr`	`required`
`source_id`	`StrictStr`	`required`
`source_revision`	`StrictStr \| None`	`None`
`source_hash`	`StrictStr \| None`	`None`
`occurred_at`	`datetime`	`required`
`includes_recalled_material`	`StrictBool`	`False`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_identity (method)

KnowledgeEnrichmentTrigger.validate_identity(value: str | None, info) -> str | None

normalize_occurred_at (method)

KnowledgeEnrichmentTrigger.normalize_occurred_at(value: datetime) -> datetime

copy_metadata (method)

KnowledgeEnrichmentTrigger.copy_metadata(value: object) -> dict[str, Any]

validate_source_frontier (method)

KnowledgeEnrichmentTrigger.validate_source_frontier() -> KnowledgeEnrichmentTrigger

completed_interaction (method)

KnowledgeEnrichmentTrigger.completed_interaction(*, session_id: str, interaction_id: str, terminal_event_id: str, occurred_at: datetime, terminal_event_hash: str | None=None, includes_recalled_material: bool=False, metadata: dict[str, Any] | None=None) -> KnowledgeEnrichmentTrigger

Build an exact trigger without reading or copying interaction history.

Release source · Runtime guarantees · Capability guides

`KnowledgeEnrichmentWorker`

from cayu import KnowledgeEnrichmentWorker

Lease-fenced processor for one configured enrichment queue.

init (method)

KnowledgeEnrichmentWorker.__init__(queue: KnowledgeEnrichmentQueue, curator: KnowledgeCurator, *, exception_classifier: KnowledgeEnrichmentExceptionClassifier | None=None) -> None

queue (property)

KnowledgeEnrichmentWorker.queue() -> KnowledgeEnrichmentQueue

process_next (method)

async KnowledgeEnrichmentWorker.process_next(*, worker_id: str, lease_seconds: int=300, reclaim: bool=True) -> KnowledgeEnrichmentJob | None

Claim and settle at most one job, returning None only when idle.

A malformed task on this queue’s private execution route is durably failed and raises KnowledgeEnrichmentJobRejected so callers do not mistake handled work for an empty queue.

run (method)

async KnowledgeEnrichmentWorker.run(*, worker_id: str, lease_seconds: int=300, poll_interval_s: float=1.0, reclaim: bool=True, stop: asyncio.Event | None=None, max_jobs: int | None=None) -> int

Process jobs until stopped and return the number of claims handled.

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_FAILURE_ANNOTATION_BYTES`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_FAILURE_ANNOTATION_BYTES

MAX_KNOWLEDGE_ENRICHMENT_FAILURE_ANNOTATION_BYTES = 4 * 1024

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_IDENTITY_BYTES`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_IDENTITY_BYTES

MAX_KNOWLEDGE_ENRICHMENT_IDENTITY_BYTES = 1024

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_RECLAIMS_PER_POLL`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_RECLAIMS_PER_POLL

MAX_KNOWLEDGE_ENRICHMENT_RECLAIMS_PER_POLL = 100

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_REQUEST_BYTES`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_REQUEST_BYTES

MAX_KNOWLEDGE_ENRICHMENT_REQUEST_BYTES = MAX_LEARNING_BATCH_BYTES + 256 * 1024

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES

MAX_KNOWLEDGE_ENRICHMENT_RESULT_BYTES = 32 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENRICHMENT_TRIGGER_METADATA_BYTES`

from cayu import MAX_KNOWLEDGE_ENRICHMENT_TRIGGER_METADATA_BYTES

MAX_KNOWLEDGE_ENRICHMENT_TRIGGER_METADATA_BYTES = 16 * 1024

Release source · Runtime guarantees · Capability guides