cayu.knowledge.maintenance

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.

KNOWLEDGE_MAINTENANCE_ROUTING_SCHEMA_VERSION

from cayu import KNOWLEDGE_MAINTENANCE_ROUTING_SCHEMA_VERSION

KNOWLEDGE_MAINTENANCE_ROUTING_SCHEMA_VERSION = 1

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceCandidateSignal

from cayu import KnowledgeMaintenanceCandidateSignal

One exact, application-produced candidate hint.

Similarity scores are retained only as diagnostics. The router never uses them as evidence that entries are equivalent, contradictory, or true.

Bases: _RoutingModel.

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_MAINTENANCE_ROUTING_SCHEMA_VERSION
id	StrictStr	required
kind	KnowledgeMaintenanceSignalKind	required
references	tuple[KnowledgeRevisionRef, ...]	required
producer_id	StrictStr	required
producer_version	StrictStr	required
reason_code	StrictStr	required
observed_at	datetime	required
threshold_at	datetime | None	None
relation_id	StrictStr | None	None
raw_score	StrictFloat | None	None
score_kind	StrictStr | None	None

validate_schema_version (method)

KnowledgeMaintenanceCandidateSignal.validate_schema_version(value: object) -> object

validate_identity (method)

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

validate_reason_code (method)

KnowledgeMaintenanceCandidateSignal.validate_reason_code(value: str) -> str

validate_relation_id (method)

KnowledgeMaintenanceCandidateSignal.validate_relation_id(value: str | None) -> str | None

validate_score_kind (method)

KnowledgeMaintenanceCandidateSignal.validate_score_kind(value: str | None) -> str | None

copy_references (method)

KnowledgeMaintenanceCandidateSignal.copy_references(value: object) -> tuple[KnowledgeRevisionRef, ...]

validate_timestamps (method)

KnowledgeMaintenanceCandidateSignal.validate_timestamps(value: datetime | None, info) -> datetime | None

validate_raw_score (method)

KnowledgeMaintenanceCandidateSignal.validate_raw_score(value: float | None) -> float | None

validate_signal_shape (method)

KnowledgeMaintenanceCandidateSignal.validate_signal_shape() -> KnowledgeMaintenanceCandidateSignal

fingerprint (property)

KnowledgeMaintenanceCandidateSignal.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutedCandidate

from cayu import KnowledgeMaintenanceRoutedCandidate

One authorized current candidate and its deterministic signal support.

Bases: _RoutingModel.

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
entry	KnowledgeEntry	required
signal_ids	tuple[StrictStr, ...]	required
signal_kinds	tuple[KnowledgeMaintenanceSignalKind, ...]	required

copy_reference (method)

KnowledgeMaintenanceRoutedCandidate.copy_reference(value: object) -> KnowledgeRevisionRef

copy_entry (method)

KnowledgeMaintenanceRoutedCandidate.copy_entry(value: object) -> object

copy_signal_ids (method)

KnowledgeMaintenanceRoutedCandidate.copy_signal_ids(value: object) -> tuple[str, ...]

copy_signal_kinds (method)

KnowledgeMaintenanceRoutedCandidate.copy_signal_kinds(value: object) -> tuple[KnowledgeMaintenanceSignalKind, ...]

validate_entry_reference (method)

KnowledgeMaintenanceRoutedCandidate.validate_entry_reference() -> KnowledgeMaintenanceRoutedCandidate

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRouter

from cayu import KnowledgeMaintenanceRouter

Authorize, verify, and bound exact maintenance candidates without writes.

init (method)

KnowledgeMaintenanceRouter.__init__(store: _KnowledgeMaintenanceRoutingStore, *, config: KnowledgeMaintenanceRouterConfig | None=None) -> None

config (property)

KnowledgeMaintenanceRouter.config() -> KnowledgeMaintenanceRouterConfig

route (method)

async KnowledgeMaintenanceRouter.route(request: KnowledgeMaintenanceRoutingRequest) -> KnowledgeMaintenanceRoutingResult

Route one explicit request or fail without returning a partial payload.

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRouterConfig

from cayu import KnowledgeMaintenanceRouterConfig

Application-owned deterministic priority and resource ceilings.

Bases: _RoutingModel.

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_MAINTENANCE_ROUTING_SCHEMA_VERSION
router_version	StrictStr	'cayu.knowledge-maintenance-router.v1'
signal_priority	tuple[KnowledgeMaintenanceSignalKind, ...]	tuple(KnowledgeMaintenanceSignalKind)
max_signals	StrictInt	100
max_candidate_reads	StrictInt	100
max_candidates	StrictInt	20
max_candidate_bytes	StrictInt	256 * 1024
max_candidate_load_bytes	StrictInt	MAX_KNOWLEDGE_MAINTENANCE_ROUTING_BYTES
max_concurrency	StrictInt	8
timeout_seconds	StrictFloat	10.0
relation_page_limit	StrictInt	50
max_relation_records_per_signal	StrictInt	200
relation_page_max_bytes	StrictInt	256 * 1024
max_relation_load_bytes	StrictInt	MAX_KNOWLEDGE_MAINTENANCE_ROUTING_BYTES

validate_schema_version (method)

KnowledgeMaintenanceRouterConfig.validate_schema_version(value: object) -> object

validate_router_version (method)

KnowledgeMaintenanceRouterConfig.validate_router_version(value: str) -> str

copy_signal_priority (method)

KnowledgeMaintenanceRouterConfig.copy_signal_priority(value: object) -> tuple[KnowledgeMaintenanceSignalKind, ...]

validate_positive_int (method)

KnowledgeMaintenanceRouterConfig.validate_positive_int(value: int, info) -> int

validate_timeout (method)

KnowledgeMaintenanceRouterConfig.validate_timeout(value: float) -> float

validate_bounds (method)

KnowledgeMaintenanceRouterConfig.validate_bounds() -> KnowledgeMaintenanceRouterConfig

fingerprint (property)

KnowledgeMaintenanceRouterConfig.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingLimitExceeded

from cayu import KnowledgeMaintenanceRoutingLimitExceeded

A request exceeds a configured pre-read work ceiling.

Bases: ValueError.

init (method)

KnowledgeMaintenanceRoutingLimitExceeded.__init__(limit: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingOmission

from cayu import KnowledgeMaintenanceRoutingOmission

One exhaustive, content-free signal disposition.

Bases: _RoutingModel.

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
signal_id	StrictStr	required
signal_kind	KnowledgeMaintenanceSignalKind	required
reason	KnowledgeMaintenanceRoutingOmissionReason	required

validate_signal_id (method)

KnowledgeMaintenanceRoutingOmission.validate_signal_id(value: str) -> str

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingOmissionReason

from cayu import KnowledgeMaintenanceRoutingOmissionReason

Privacy-safe reason why one submitted signal did not reach the planner.

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
UNAVAILABLE	class attribute	'unavailable'
STALE_REVISION	class attribute	'stale_revision'
SCOPE_MISMATCH	class attribute	'scope_mismatch'
LIFECYCLE_MISMATCH	class attribute	'lifecycle_mismatch'
CONDITION_NOT_MET	class attribute	'condition_not_met'
RELATION_COVERAGE_INCOMPLETE	class attribute	'relation_coverage_incomplete'
CANDIDATE_LIMIT	class attribute	'candidate_limit'
CANDIDATE_BYTES	class attribute	'candidate_bytes'

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingRequest

from cayu import KnowledgeMaintenanceRoutingRequest

One explicit bounded routing request within an application-owned scope.

Bases: _RoutingModel.

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_MAINTENANCE_ROUTING_SCHEMA_VERSION
id	StrictStr	required
policy_id	StrictStr	required
namespace	StrictStr	required
labels	dict[str, str]	Field(default_factory=dict)
access_scope	KnowledgeAccessScope	required
signals	tuple[KnowledgeMaintenanceCandidateSignal, ...]	()
created_at	datetime	required

validate_schema_version (method)

KnowledgeMaintenanceRoutingRequest.validate_schema_version(value: object) -> object

validate_identity (method)

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

copy_labels (method)

KnowledgeMaintenanceRoutingRequest.copy_labels(value: Any) -> dict[str, str]

copy_access_scope (method)

KnowledgeMaintenanceRoutingRequest.copy_access_scope(value: object) -> object

copy_signals (method)

KnowledgeMaintenanceRoutingRequest.copy_signals(value: object) -> tuple[KnowledgeMaintenanceCandidateSignal, ...]

validate_created_at (method)

KnowledgeMaintenanceRoutingRequest.validate_created_at(value: datetime) -> datetime

validate_signals (method)

KnowledgeMaintenanceRoutingRequest.validate_signals() -> KnowledgeMaintenanceRoutingRequest

fingerprint (property)

KnowledgeMaintenanceRoutingRequest.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingResult

from cayu import KnowledgeMaintenanceRoutingResult

Bounded deterministic routing output ready for an injected planner.

Bases: _RoutingModel.

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_MAINTENANCE_ROUTING_SCHEMA_VERSION
request_id	StrictStr	required
request_fingerprint	StrictStr	required
configuration_fingerprint	StrictStr	required
candidates	tuple[KnowledgeMaintenanceRoutedCandidate, ...]	()
routed_signals	tuple[KnowledgeMaintenanceCandidateSignal, ...]	()
omissions	tuple[KnowledgeMaintenanceRoutingOmission, ...]	()
signal_count	StrictInt	required
loaded_reference_count	StrictInt	required
candidate_payload_bytes	StrictInt	required
relation_payload_bytes	StrictInt	required
max_candidates	StrictInt	required
max_candidate_bytes	StrictInt	required
max_relation_load_bytes	StrictInt	required
truncated	bool	False

validate_schema_version (method)

KnowledgeMaintenanceRoutingResult.validate_schema_version(value: object) -> object

validate_request_id (method)

KnowledgeMaintenanceRoutingResult.validate_request_id(value: str) -> str

validate_fingerprint (method)

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

copy_candidates (method)

KnowledgeMaintenanceRoutingResult.copy_candidates(value: object) -> tuple[KnowledgeMaintenanceRoutedCandidate, ...]

copy_routed_signals (method)

KnowledgeMaintenanceRoutingResult.copy_routed_signals(value: object) -> tuple[KnowledgeMaintenanceCandidateSignal, ...]

copy_omissions (method)

KnowledgeMaintenanceRoutingResult.copy_omissions(value: object) -> tuple[KnowledgeMaintenanceRoutingOmission, ...]

validate_nonnegative_int (method)

KnowledgeMaintenanceRoutingResult.validate_nonnegative_int(value: int, info) -> int

validate_positive_int (method)

KnowledgeMaintenanceRoutingResult.validate_positive_int(value: int, info) -> int

validate_truncated (method)

KnowledgeMaintenanceRoutingResult.validate_truncated(value: object) -> bool

validate_result (method)

KnowledgeMaintenanceRoutingResult.validate_result() -> KnowledgeMaintenanceRoutingResult

fingerprint (property)

KnowledgeMaintenanceRoutingResult.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceRoutingTimeout

from cayu import KnowledgeMaintenanceRoutingTimeout

Candidate routing did not complete within its configured deadline.

Bases: TimeoutError.

init (method)

KnowledgeMaintenanceRoutingTimeout.__init__() -> None

Release source · Runtime guarantees · Capability guides

KnowledgeMaintenanceSignalKind

from cayu import KnowledgeMaintenanceSignalKind

A deterministic hint for why exact knowledge revisions merit review.

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
EXACT_REFERENCE	class attribute	'exact_reference'
CONTRADICTION	class attribute	'contradiction'
DUPLICATE_HINT	class attribute	'duplicate_hint'
EXPIRY	class attribute	'expiry'
LOW_USAGE	class attribute	'low_usage'

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_BYTES

from cayu import MAX_KNOWLEDGE_MAINTENANCE_ROUTING_BYTES

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_BYTES = 4 * 1024 * 1024

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_CANDIDATE_READS

from cayu import MAX_KNOWLEDGE_MAINTENANCE_ROUTING_CANDIDATE_READS

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_CANDIDATE_READS = 512

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_SIGNALS

from cayu import MAX_KNOWLEDGE_MAINTENANCE_ROUTING_SIGNALS

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_SIGNALS = 256

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_TIMEOUT_SECONDS

from cayu import MAX_KNOWLEDGE_MAINTENANCE_ROUTING_TIMEOUT_SECONDS

MAX_KNOWLEDGE_MAINTENANCE_ROUTING_TIMEOUT_SECONDS = 300.0

Release source · Runtime guarantees · Capability guides