cayu.knowledge.curator

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.

CandidatePolicyDisposition

from cayu import CandidatePolicyDisposition

Application-policy disposition before independent 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
ACCEPTED	class attribute	'accepted'
REJECTED	class attribute	'rejected'

Release source · Runtime guarantees · Capability guides

group_learning_signals

from cayu import group_learning_signals

Group copied signals deterministically by scope and bounded batch size.

group_learning_signals(signals: Iterable[LearningSignal], *, max_signals_per_batch: int=50) -> list[LearningBatch]

Release source · Runtime guarantees · Capability guides

KnowledgeCandidateGenerator

from cayu import KnowledgeCandidateGenerator

Provider-neutral candidate generation over one copied bounded batch.

Bases: Protocol.

generate_candidates (method)

async KnowledgeCandidateGenerator.generate_candidates(batch: LearningBatch) -> list[LearningCandidate]

Release source · Runtime guarantees · Capability guides

KnowledgeCandidatePolicy

from cayu import KnowledgeCandidatePolicy

Optional application-owned content rejection or transformation hook.

Bases: Protocol.

apply_candidate_policy (method)

async KnowledgeCandidatePolicy.apply_candidate_policy(candidate: LearningCandidate, signals: tuple[LearningSignal, ...]) -> KnowledgeCandidatePolicyDecision

Release source · Runtime guarantees · Capability guides

KnowledgeCandidatePolicyDecision

from cayu import KnowledgeCandidatePolicyDecision

Application-owned rejection or bounded transformation result.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
disposition	CandidatePolicyDisposition	required
code	StrictStr	required
notes	StrictStr | None	None
candidate	LearningCandidate | None	None

validate_code (method)

KnowledgeCandidatePolicyDecision.validate_code(value: str) -> str

validate_notes (method)

KnowledgeCandidatePolicyDecision.validate_notes(value: str | None) -> str | None

copy_candidate (method)

KnowledgeCandidatePolicyDecision.copy_candidate(value: object) -> object

validate_disposition (method)

KnowledgeCandidatePolicyDecision.validate_disposition() -> KnowledgeCandidatePolicyDecision

Release source · Runtime guarantees · Capability guides

KnowledgeCurator

from cayu import KnowledgeCurator

Explicit governed knowledge curation over Cayu’s revision store.

init (method)

KnowledgeCurator.__init__(store: _CuratorStore, *, candidate_generator: KnowledgeCandidateGenerator, evaluator: LearningEvaluator, config: KnowledgeCuratorConfig, access_scope: KnowledgeAccessScope | None=None, candidate_policy: KnowledgeCandidatePolicy | None=None, activation_policy: KnowledgeActivationPolicy | None=None, clock: Callable[[], datetime] | None=None) -> None

config (property)

KnowledgeCurator.config() -> KnowledgeCuratorConfig

access_scope (property)

KnowledgeCurator.access_scope() -> KnowledgeAccessScope

Return the exact copied access boundary enforced by this curator.

aclose (method)

async KnowledgeCurator.aclose(*, timeout_s: float=10.0) -> bool

Seal and drain publications retained beyond their curation callers.

aenter (method)

async KnowledgeCurator.__aenter__() -> KnowledgeCurator

aexit (method)

async KnowledgeCurator.__aexit__(*_exc_info: object) -> None

curate (method)

async KnowledgeCurator.curate(batch: LearningBatch) -> LearningBatchResult

Generate, independently evaluate, govern, and persist knowledge.

Release source · Runtime guarantees · Capability guides

KnowledgeCuratorConfig

from cayu import KnowledgeCuratorConfig

Application-owned policy and resource bounds for reviewed curation.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
candidate_generator_identity	StrictStr	required
evaluator_identity	StrictStr	required
policy_identity	StrictStr | None	None
pipeline_version	StrictStr	'cayu.knowledge-curator.v1'
namespace	StrictStr	DEFAULT_KNOWLEDGE_NAMESPACE
labels	dict[str, str]	Field(default_factory=dict)
visibility	KnowledgeVisibility	KnowledgeVisibility.GLOBAL
allowed_kinds	tuple[StrictStr, ...]	BUILTIN_KNOWLEDGE_KINDS
created_by	StrictStr	'knowledge_curator'
governance	KnowledgeGovernanceConfig	Field(default_factory=KnowledgeGovernanceConfig)
max_signals	StrictInt	50
max_signal_bytes	StrictInt	16 * 1024
max_batch_bytes	StrictInt	256 * 1024
max_candidates	StrictInt	20
max_candidate_bytes	StrictInt	64 * 1024
max_candidate_text_bytes	StrictInt	32 * 1024
max_candidate_title_bytes	StrictInt	4 * 1024
max_candidate_batch_bytes	StrictInt	512 * 1024
max_source_references_per_signal	StrictInt	20
max_source_references_per_candidate	StrictInt	100
max_source_reference_bytes	StrictInt	16 * 1024
max_metadata_bytes	StrictInt	16 * 1024
max_evaluator_notes_bytes	StrictInt	16 * 1024
max_evaluator_concurrency	StrictInt	4
max_in_flight_publications	StrictInt	100
candidate_generator_timeout_seconds	StrictFloat	120.0
evaluator_timeout_seconds	StrictFloat	120.0
candidate_policy_timeout_seconds	StrictFloat	30.0
chunk_target_bytes	StrictInt	DEFAULT_KNOWLEDGE_CHUNK_TARGET_BYTES
chunk_overlap_bytes	StrictInt	DEFAULT_KNOWLEDGE_CHUNK_OVERLAP_BYTES
max_chunks	StrictInt	100

validate_identity (method)

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

validate_policy_identity (method)

KnowledgeCuratorConfig.validate_policy_identity(value: str | None) -> str | None

copy_labels (method)

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

copy_governance (method)

KnowledgeCuratorConfig.copy_governance(value: object) -> object

copy_allowed_kinds (method)

KnowledgeCuratorConfig.copy_allowed_kinds(value: object) -> tuple[str, ...]

validate_positive_int (method)

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

validate_text_capacity (method)

KnowledgeCuratorConfig.validate_text_capacity(value: int, info) -> int

validate_nonnegative_overlap (method)

KnowledgeCuratorConfig.validate_nonnegative_overlap(value: int) -> int

validate_timeout (method)

KnowledgeCuratorConfig.validate_timeout(value: float, info) -> float

validate_bounds (method)

KnowledgeCuratorConfig.validate_bounds() -> KnowledgeCuratorConfig

fingerprint (property)

KnowledgeCuratorConfig.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

LearningBatch

from cayu import LearningBatch

One already-grouped, explicitly submitted curation batch.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
id	StrictStr	required
signals	tuple[LearningSignal, ...]	required

validate_id (method)

LearningBatch.validate_id(value: str) -> str

copy_signals (method)

LearningBatch.copy_signals(value: object) -> object

validate_signal_identity (method)

LearningBatch.validate_signal_identity() -> LearningBatch

scope (property)

LearningBatch.scope() -> str

fingerprint (property)

LearningBatch.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

LearningBatchOutcome

from cayu import LearningBatchOutcome

Outcome of the batch-wide candidate-generation boundary.

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
COMPLETED	class attribute	'completed'
GENERATOR_FAILED	class attribute	'generator_failed'
GENERATOR_TIMED_OUT	class attribute	'generator_timed_out'
GENERATOR_INVALID	class attribute	'generator_invalid'

Release source · Runtime guarantees · Capability guides

LearningBatchResult

from cayu import LearningBatchResult

Bounded public result for one explicit curation invocation.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
batch_id	StrictStr	required
batch_fingerprint	StrictStr	required
configuration_fingerprint	StrictStr	required
scope	StrictStr	required
outcome	LearningBatchOutcome	required
code	StrictStr	required
signal_count	StrictInt	required
candidate_count	StrictInt	required
signals	tuple[LearningSignalResult, ...]	required
candidates	tuple[LearningCandidateResult, ...]	()
processed_at	datetime	required

validate_identity (method)

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

validate_fingerprint (method)

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

copy_candidates (method)

LearningBatchResult.copy_candidates(value: object) -> object

copy_signals (method)

LearningBatchResult.copy_signals(value: object) -> object

validate_processed_at (method)

LearningBatchResult.validate_processed_at(value: datetime) -> datetime

validate_count (method)

LearningBatchResult.validate_count(value: int, info) -> int

validate_result_contract (method)

LearningBatchResult.validate_result_contract() -> LearningBatchResult

Release source · Runtime guarantees · Capability guides

LearningCandidate

from cayu import LearningCandidate

One generator-proposed reusable knowledge item.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
proposal_key	StrictStr	required
text	StrictStr	required
signal_ids	tuple[StrictStr, ...]	required
title	StrictStr | None	None
kind	StrictStr	'fact'
aspects	tuple[StrictStr, ...]	()
impact_targets	tuple[StrictStr, ...]	()
confidence_hint	StrictFloat | None	None
source_references	tuple[LearningSourceReference, ...]	()
metadata	dict[str, Any]	Field(default_factory=dict)

validate_identity (method)

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

validate_text (method)

LearningCandidate.validate_text(value: str) -> str

validate_title (method)

LearningCandidate.validate_title(value: str | None) -> str | None

copy_signal_ids (method)

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

copy_taxonomy (method)

LearningCandidate.copy_taxonomy(value: object, info) -> tuple[str, ...]

copy_source_references (method)

LearningCandidate.copy_source_references(value: object) -> object

validate_confidence_hint (method)

LearningCandidate.validate_confidence_hint(value: float | None) -> float | None

copy_metadata (method)

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

validate_sources (method)

LearningCandidate.validate_sources() -> LearningCandidate

fingerprint (property)

LearningCandidate.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

LearningCandidateOutcome

from cayu import LearningCandidateOutcome

Durable or fail-closed outcome for one generated candidate.

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
PENDING_PERSISTED	class attribute	'pending_persisted'
ACTIVE_PERSISTED	class attribute	'active_persisted'
EXISTING_PENDING	class attribute	'existing_pending'
EXISTING_ACTIVE	class attribute	'existing_active'
EXISTING_ARCHIVED	class attribute	'existing_archived'
EXISTING_DELETED	class attribute	'existing_deleted'
EVALUATOR_REJECTED	class attribute	'evaluator_rejected'
POLICY_REJECTED	class attribute	'policy_rejected'
ACTIVATION_REJECTED	class attribute	'activation_rejected'
INVALID	class attribute	'invalid'
FAILED	class attribute	'failed'
CONFLICT	class attribute	'conflict'

Release source · Runtime guarantees · Capability guides

LearningCandidateResult

from cayu import LearningCandidateResult

Bounded public result for one generated candidate.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
proposal_key	StrictStr	required
candidate_fingerprint	StrictStr	required
outcome	LearningCandidateOutcome	required
code	StrictStr	required
decision	LearningDecision | None	None
entry_id	StrictStr | None	None
entry_revision	StrictInt | None	None
entry_status	KnowledgeStatus | None	None
warning_code	StrictStr | None	None

validate_required_identity (method)

LearningCandidateResult.validate_required_identity(value: str, info) -> str

validate_fingerprint (method)

LearningCandidateResult.validate_fingerprint(value: str) -> str

copy_decision (method)

LearningCandidateResult.copy_decision(value: object) -> object

validate_optional_identity (method)

LearningCandidateResult.validate_optional_identity(value: str | None, info) -> str | None

validate_revision (method)

LearningCandidateResult.validate_revision(value: int | None) -> int | None

validate_outcome_contract (method)

LearningCandidateResult.validate_outcome_contract() -> LearningCandidateResult

Release source · Runtime guarantees · Capability guides

LearningDecision

from cayu import LearningDecision

One independent evaluator decision for one exact candidate.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
verdict	LearningVerdict	required
code	StrictStr	required
notes	StrictStr | None	None
confidence	StrictFloat | None	None
metadata	dict[str, Any]	Field(default_factory=dict)

validate_code (method)

LearningDecision.validate_code(value: str) -> str

validate_notes (method)

LearningDecision.validate_notes(value: str | None) -> str | None

validate_confidence (method)

LearningDecision.validate_confidence(value: float | None) -> float | None

copy_metadata (method)

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

Release source · Runtime guarantees · Capability guides

LearningEvaluator

from cayu import LearningEvaluator

Independent evaluation of one candidate against its copied signals.

Bases: Protocol.

evaluate_candidate (method)

async LearningEvaluator.evaluate_candidate(candidate: LearningCandidate, signals: tuple[LearningSignal, ...]) -> LearningDecision

Release source · Runtime guarantees · Capability guides

LearningSignal

from cayu import LearningSignal

One deterministic application observation; it is not knowledge.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
id	StrictStr	required
deduplication_key	StrictStr	required
kind	StrictStr	required
scope	StrictStr	required
summary	StrictStr	required
source_references	tuple[LearningSourceReference, ...]	required
occurred_at	datetime	required
metadata	dict[str, Any]	Field(default_factory=dict)

validate_identity (method)

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

validate_summary (method)

LearningSignal.validate_summary(value: str) -> str

copy_source_references (method)

LearningSignal.copy_source_references(value: object) -> object

copy_metadata (method)

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

validate_occurred_at (method)

LearningSignal.validate_occurred_at(value: datetime) -> datetime

validate_sources (method)

LearningSignal.validate_sources() -> LearningSignal

fingerprint (property)

LearningSignal.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

LearningSignalOutcome

from cayu import LearningSignalOutcome

Participation outcome for one submitted signal.

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
CANDIDATE_GENERATED	class attribute	'candidate_generated'
NO_CANDIDATE_GENERATED	class attribute	'no_candidate_generated'
BATCH_FAILED	class attribute	'batch_failed'

Release source · Runtime guarantees · Capability guides

LearningSignalResult

from cayu import LearningSignalResult

How one submitted signal participated in an explicit curation call.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
signal_id	StrictStr	required
signal_fingerprint	StrictStr	required
outcome	LearningSignalOutcome	required
code	StrictStr	required
candidate_proposal_keys	tuple[StrictStr, ...]	()

validate_identity (method)

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

validate_fingerprint (method)

LearningSignalResult.validate_fingerprint(value: str) -> str

copy_candidate_proposal_keys (method)

LearningSignalResult.copy_candidate_proposal_keys(value: object) -> tuple[str, ...]

validate_outcome (method)

LearningSignalResult.validate_outcome() -> LearningSignalResult

Release source · Runtime guarantees · Capability guides

LearningSourceReference

from cayu import LearningSourceReference

One bounded exact source reference carried into KnowledgeEvidence.

Bases: _CuratorModel.

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]	LEARNING_SCHEMA_VERSION
source_type	StrictStr	required
source_id	StrictStr | None	None
source_uri	StrictStr | None	None
source_revision	StrictStr | None	None
source_hash	StrictStr | None	None
locator	dict[str, Any]	Field(default_factory=dict)
role	KnowledgeEvidenceRole	KnowledgeEvidenceRole.ORIGIN
metadata	dict[str, Any]	Field(default_factory=dict)

validate_source_type (method)

LearningSourceReference.validate_source_type(value: str) -> str

validate_optional_identity (method)

LearningSourceReference.validate_optional_identity(value: str | None, info) -> str | None

validate_source_uri (method)

LearningSourceReference.validate_source_uri(value: str | None) -> str | None

copy_json_fields (method)

LearningSourceReference.copy_json_fields(value: Any, info) -> dict[str, Any]

validate_exact_source (method)

LearningSourceReference.validate_exact_source() -> LearningSourceReference

identity_material (method)

LearningSourceReference.identity_material() -> dict[str, Any]

fingerprint (property)

LearningSourceReference.fingerprint() -> str

Release source · Runtime guarantees · Capability guides

LearningVerdict

from cayu import LearningVerdict

Independent evaluator verdict for one exact candidate.

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
ACCEPTED	class attribute	'accepted'
REJECTED	class attribute	'rejected'

Release source · Runtime guarantees · Capability guides

validate_learning_batch

from cayu import validate_learning_batch

Copy and validate a batch against one curator’s pre-provider bounds.

Durable job producers use the same boundary as KnowledgeCurator before enqueueing work, so an oversized request cannot consume queue storage and fail only after a worker has claimed it.

validate_learning_batch(batch: LearningBatch, *, config: KnowledgeCuratorConfig) -> LearningBatch

Release source · Runtime guarantees · Capability guides