cayu.knowledge.semantic_watch

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.

decide_knowledge_semantic_watch

from cayu import decide_knowledge_semantic_watch

async decide_knowledge_semantic_watch(request: KnowledgeSemanticWatchRequest, *, config: KnowledgeSemanticWatchConfig, policy: KnowledgeSemanticWatchPolicy | None) -> KnowledgeSemanticWatchAuthority

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchAuthority

from cayu import KnowledgeSemanticWatchAuthority

Durable-safe request evidence and accepted application decision.

Bases: _WatchModel.

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]	1
invocation	KnowledgeSemanticWatchInvocation	required
evidence	KnowledgeSemanticWatchEvidence	required
decision	KnowledgeSemanticWatchDecision	required

validate_schema_version (method)

KnowledgeSemanticWatchAuthority.validate_schema_version(value: object) -> object

copy_models (method)

KnowledgeSemanticWatchAuthority.copy_models(value: object) -> object

validate_authority (method)

KnowledgeSemanticWatchAuthority.validate_authority() -> KnowledgeSemanticWatchAuthority

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchCandidate

from cayu import KnowledgeSemanticWatchCandidate

Durable-safe exact knowledge match presented to application policy.

Bases: _WatchModel.

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
reference	KnowledgeRevisionRef	required
record_type	Literal['knowledge_entry', 'knowledge_chunk']	required
record_id	str	required
representation	str	required
content_hash	str	required
fused_rank	int	required
fused_score	float	required
best_rank	int	required
channel_matches	tuple[KnowledgeSemanticWatchChannelMatch, ...]	required

copy_reference (method)

KnowledgeSemanticWatchCandidate.copy_reference(value: object) -> object

validate_identity (method)

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

validate_content_hash (method)

KnowledgeSemanticWatchCandidate.validate_content_hash(value: str) -> str

validate_rank (method)

KnowledgeSemanticWatchCandidate.validate_rank(value: object, info) -> int

validate_score (method)

KnowledgeSemanticWatchCandidate.validate_score(value: object) -> float

copy_channel_matches (method)

KnowledgeSemanticWatchCandidate.copy_channel_matches(value: object) -> tuple[KnowledgeSemanticWatchChannelMatch, ...]

validate_reference_identity (method)

KnowledgeSemanticWatchCandidate.validate_reference_identity() -> KnowledgeSemanticWatchCandidate

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchChannelMatch

from cayu import KnowledgeSemanticWatchChannelMatch

Safe rank evidence from one independently ranked recall lane.

Bases: _WatchModel.

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
channel	str	required
index_version	str	required
rank	int	required
reasons	tuple[str, ...]	required
raw_score	float | None	None

validate_identity (method)

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

validate_rank (method)

KnowledgeSemanticWatchChannelMatch.validate_rank(value: object) -> int

validate_reasons (method)

KnowledgeSemanticWatchChannelMatch.validate_reasons(value: object) -> tuple[str, ...]

validate_raw_score (method)

KnowledgeSemanticWatchChannelMatch.validate_raw_score(value: object) -> float | None

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchConfig

from cayu import KnowledgeSemanticWatchConfig

Application-owned identities and bounds for one watch profile.

Bases: _WatchModel.

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]	1
watch_identity	str	required
watch_version	str	required
recall_profile_identity	str	required
recall_profile_version	str	required
policy_identity	str	required
policy_version	str	required
policy_timeout_seconds	float	5.0
max_candidates	int	10
knowledge_namespace	str	DEFAULT_KNOWLEDGE_NAMESPACE
knowledge_aspect_groups	tuple[tuple[str, ...], ...]	()
required_channels	tuple[str, ...]	(KNOWLEDGE_LEXICAL_CHANNEL,)

validate_schema_version (method)

KnowledgeSemanticWatchConfig.validate_schema_version(value: object) -> object

validate_identity (method)

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

validate_timeout (method)

KnowledgeSemanticWatchConfig.validate_timeout(value: object) -> float

validate_max_candidates (method)

KnowledgeSemanticWatchConfig.validate_max_candidates(value: object) -> int

validate_aspect_groups (method)

KnowledgeSemanticWatchConfig.validate_aspect_groups(value: object) -> tuple[tuple[str, ...], ...]

validate_required_channels (method)

KnowledgeSemanticWatchConfig.validate_required_channels(value: object) -> tuple[str, ...]

validate_authority_separation (method)

KnowledgeSemanticWatchConfig.validate_authority_separation() -> KnowledgeSemanticWatchConfig

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchConflict

from cayu import KnowledgeSemanticWatchConflict

A watch operation conflicts with an immutable durable outcome.

Bases: ValueError.

init (method)

KnowledgeSemanticWatchConflict.__init__(code: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchDecision

from cayu import KnowledgeSemanticWatchDecision

Exact application-policy route for one watch request.

Bases: _WatchModel.

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]	1
request_sha256	str	required
disposition	KnowledgeSemanticWatchDisposition	required
policy_identity	str	required
policy_version	str	required
code	str	required
annotations	Mapping[str, Any]	Field(default_factory=dict)

validate_schema_version (method)

KnowledgeSemanticWatchDecision.validate_schema_version(value: object) -> object

validate_request_sha256 (method)

KnowledgeSemanticWatchDecision.validate_request_sha256(value: str) -> str

validate_identity (method)

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

copy_annotations (method)

KnowledgeSemanticWatchDecision.copy_annotations(value: object) -> dict[str, Any]

freeze_annotations (method)

KnowledgeSemanticWatchDecision.freeze_annotations(value: Mapping[str, Any]) -> Mapping[str, Any]

serialize_annotations (method)

KnowledgeSemanticWatchDecision.serialize_annotations(value: Mapping[str, Any]) -> dict[str, Any]

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchDisposition

from cayu import KnowledgeSemanticWatchDisposition

Application-policy disposition for one bounded watch evaluation.

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
IGNORE	class attribute	'ignore'
EMIT	class attribute	'emit'
ROUTE_TO_REVIEW	class attribute	'route_to_review'

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchEvaluator

from cayu import KnowledgeSemanticWatchEvaluator

Explicit orchestration over existing recall and application policy.

init (method)

KnowledgeSemanticWatchEvaluator.__init__(store: KnowledgeStore, recall_engine: RecallEngine, *, config: KnowledgeSemanticWatchConfig, policy: KnowledgeSemanticWatchPolicy | None) -> None

config (property)

KnowledgeSemanticWatchEvaluator.config() -> KnowledgeSemanticWatchConfig

evaluate (method)

async KnowledgeSemanticWatchEvaluator.evaluate(*, operation_id: str, observation_id: str, observation_source_type: str, observation_source_id: str, observation_text: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchEvidence

from cayu import KnowledgeSemanticWatchEvidence

Safe bounded projection of one exact recall result.

Bases: _WatchModel.

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]	1
engine_version	str	required
situation_sha256	str	required
fusion	RetrievalFusionDiagnostics	required
sources	tuple[RecallSourceDiagnostic, ...]	required
required_channels	tuple[str, ...]	required
candidates	tuple[KnowledgeSemanticWatchCandidate, ...]	required
recall_candidate_count	int	required
omitted_candidate_count	int	required
complete	bool	required
truncation_reasons	tuple[str, ...]	()

validate_schema_version (method)

KnowledgeSemanticWatchEvidence.validate_schema_version(value: object) -> object

validate_engine_version (method)

KnowledgeSemanticWatchEvidence.validate_engine_version(value: str) -> str

validate_situation_sha256 (method)

KnowledgeSemanticWatchEvidence.validate_situation_sha256(value: str) -> str

copy_fusion (method)

KnowledgeSemanticWatchEvidence.copy_fusion(value: object) -> object

copy_sources (method)

KnowledgeSemanticWatchEvidence.copy_sources(value: object) -> tuple[RecallSourceDiagnostic, ...]

validate_required_channels (method)

KnowledgeSemanticWatchEvidence.validate_required_channels(value: object) -> tuple[str, ...]

copy_candidates (method)

KnowledgeSemanticWatchEvidence.copy_candidates(value: object) -> tuple[KnowledgeSemanticWatchCandidate, ...]

validate_counts (method)

KnowledgeSemanticWatchEvidence.validate_counts(value: object, info) -> int

validate_complete (method)

KnowledgeSemanticWatchEvidence.validate_complete(value: object) -> bool

validate_truncation_reasons (method)

KnowledgeSemanticWatchEvidence.validate_truncation_reasons(value: object) -> tuple[str, ...]

validate_evidence (method)

KnowledgeSemanticWatchEvidence.validate_evidence() -> KnowledgeSemanticWatchEvidence

fingerprint (property)

KnowledgeSemanticWatchEvidence.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchInvocation

from cayu import KnowledgeSemanticWatchInvocation

Durable-safe identity for an observation before recall or policy execution.

Bases: _WatchModel.

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]	1
operation_id	str	required
observation_id	str	required
observation_source_type	str	required
observation_source_id	str	required
observation_sha256	str	required
observation_bytes	int	required
watch_identity	str	required
watch_version	str	required
recall_profile_identity	str	required
recall_profile_version	str	required
policy_identity	str	required
policy_version	str	required
knowledge_namespace	str	required
knowledge_aspect_groups	tuple[tuple[str, ...], ...]	required
required_channels	tuple[str, ...]	required
max_candidates	int	required
access_scope	KnowledgeAccessScope	required

validate_schema_version (method)

KnowledgeSemanticWatchInvocation.validate_schema_version(value: object) -> object

validate_identity (method)

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

validate_observation_sha256 (method)

KnowledgeSemanticWatchInvocation.validate_observation_sha256(value: str) -> str

validate_observation_bytes (method)

KnowledgeSemanticWatchInvocation.validate_observation_bytes(value: object) -> int

validate_max_candidates (method)

KnowledgeSemanticWatchInvocation.validate_max_candidates(value: object) -> int

validate_aspect_groups (method)

KnowledgeSemanticWatchInvocation.validate_aspect_groups(value: object) -> tuple[tuple[str, ...], ...]

validate_required_channels (method)

KnowledgeSemanticWatchInvocation.validate_required_channels(value: object) -> tuple[str, ...]

copy_access_scope (method)

KnowledgeSemanticWatchInvocation.copy_access_scope(value: object) -> object

freeze_access_scope (method)

KnowledgeSemanticWatchInvocation.freeze_access_scope(value: KnowledgeAccessScope) -> KnowledgeAccessScope

serialize_access_scope (method)

KnowledgeSemanticWatchInvocation.serialize_access_scope(value: KnowledgeAccessScope) -> dict[str, Any]

fingerprint (property)

KnowledgeSemanticWatchInvocation.fingerprint() -> str

access_scope_sha256 (property)

KnowledgeSemanticWatchInvocation.access_scope_sha256() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchPolicy

from cayu import KnowledgeSemanticWatchPolicy

Application authority for one copied, bounded watch request.

Bases: Protocol.

decide_semantic_watch (method)

async KnowledgeSemanticWatchPolicy.decide_semantic_watch(request: KnowledgeSemanticWatchRequest) -> KnowledgeSemanticWatchDecision

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchPolicyError

from cayu import KnowledgeSemanticWatchPolicyError

Watch evaluation failed closed before durable routing.

Bases: RuntimeError.

init (method)

KnowledgeSemanticWatchPolicyError.__init__(code: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchReceipt

from cayu import KnowledgeSemanticWatchReceipt

Store-authored immutable outcome for one exact watch invocation.

Bases: _WatchModel.

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]	1
operation_id	str	required
invocation_sha256	str	required
request_sha256	str	required
authority	KnowledgeSemanticWatchAuthority	required
committed_at	datetime	required
replayed	bool	False

validate_schema_version (method)

KnowledgeSemanticWatchReceipt.validate_schema_version(value: object) -> object

validate_operation_id (method)

KnowledgeSemanticWatchReceipt.validate_operation_id(value: str) -> str

validate_sha256 (method)

KnowledgeSemanticWatchReceipt.validate_sha256(value: str, info) -> str

copy_authority (method)

KnowledgeSemanticWatchReceipt.copy_authority(value: object) -> object

validate_committed_at (method)

KnowledgeSemanticWatchReceipt.validate_committed_at(value: datetime) -> datetime

validate_replayed (method)

KnowledgeSemanticWatchReceipt.validate_replayed(value: object) -> bool

validate_receipt (method)

KnowledgeSemanticWatchReceipt.validate_receipt() -> KnowledgeSemanticWatchReceipt

Release source · Runtime guarantees · Capability guides

KnowledgeSemanticWatchRequest

from cayu import KnowledgeSemanticWatchRequest

Copied bounded policy input; observation text is never persisted by Cayu.

Bases: _WatchModel.

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]	1
invocation	KnowledgeSemanticWatchInvocation	required
observation_text	str	required
recall_situation	RecallSituation	required
evidence	KnowledgeSemanticWatchEvidence	required

validate_schema_version (method)

KnowledgeSemanticWatchRequest.validate_schema_version(value: object) -> object

copy_models (method)

KnowledgeSemanticWatchRequest.copy_models(value: object) -> object

copy_recall_situation (method)

KnowledgeSemanticWatchRequest.copy_recall_situation(value: object) -> object

validate_observation_text (method)

KnowledgeSemanticWatchRequest.validate_observation_text(value: str) -> str

validate_binding (method)

KnowledgeSemanticWatchRequest.validate_binding() -> KnowledgeSemanticWatchRequest

fingerprint (property)

KnowledgeSemanticWatchRequest.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

load_knowledge_semantic_watch_receipt

from cayu import load_knowledge_semantic_watch_receipt

async load_knowledge_semantic_watch_receipt(store: KnowledgeStore, *, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt | None

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_SEMANTIC_WATCH_ANNOTATION_BYTES

from cayu import MAX_KNOWLEDGE_SEMANTIC_WATCH_ANNOTATION_BYTES

MAX_KNOWLEDGE_SEMANTIC_WATCH_ANNOTATION_BYTES = 4096

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_SEMANTIC_WATCH_CANDIDATES

from cayu import MAX_KNOWLEDGE_SEMANTIC_WATCH_CANDIDATES

MAX_KNOWLEDGE_SEMANTIC_WATCH_CANDIDATES = 20

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_SEMANTIC_WATCH_OBSERVATION_BYTES

from cayu import MAX_KNOWLEDGE_SEMANTIC_WATCH_OBSERVATION_BYTES

MAX_KNOWLEDGE_SEMANTIC_WATCH_OBSERVATION_BYTES = RECALL_MAX_QUERY_BYTES

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_SEMANTIC_WATCH_POLICY_REQUEST_BYTES

from cayu import MAX_KNOWLEDGE_SEMANTIC_WATCH_POLICY_REQUEST_BYTES

MAX_KNOWLEDGE_SEMANTIC_WATCH_POLICY_REQUEST_BYTES = 256000

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_SEMANTIC_WATCH_RECEIPT_BYTES

from cayu import MAX_KNOWLEDGE_SEMANTIC_WATCH_RECEIPT_BYTES

MAX_KNOWLEDGE_SEMANTIC_WATCH_RECEIPT_BYTES = 384000

Release source · Runtime guarantees · Capability guides

prepare_knowledge_semantic_watch_invocation

from cayu import prepare_knowledge_semantic_watch_invocation

prepare_knowledge_semantic_watch_invocation(*, operation_id: str, observation_id: str, observation_source_type: str, observation_source_id: str, observation_text: str, access_scope: KnowledgeAccessScope, config: KnowledgeSemanticWatchConfig) -> KnowledgeSemanticWatchInvocation

Release source · Runtime guarantees · Capability guides

project_knowledge_semantic_watch_evidence

from cayu import project_knowledge_semantic_watch_evidence

project_knowledge_semantic_watch_evidence(result: RecallResult, *, max_candidates: int, required_channels: Sequence[str]=(KNOWLEDGE_LEXICAL_CHANNEL,)) -> KnowledgeSemanticWatchEvidence

Release source · Runtime guarantees · Capability guides