cayu.knowledge.indexing

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_EMBEDDING_WORK_RECORD_LIMIT

from cayu.storage import DEFAULT_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT

DEFAULT_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT = 500

Release source · Runtime guarantees · Capability guides

knowledge_chunk_embedding_identity

from cayu.storage import knowledge_chunk_embedding_identity

Build the built-in canonical chunk-text embedding identity.

knowledge_chunk_embedding_identity(chunk: KnowledgeChunk, *, embedding_model: str, dimensions: int) -> KnowledgeEmbeddingIdentity

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_CHUNK_TEXT_GENERATOR

from cayu.storage import KNOWLEDGE_CHUNK_TEXT_GENERATOR

KNOWLEDGE_CHUNK_TEXT_GENERATOR = 'cayu:canonical-knowledge-chunk'

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_CHUNK_TEXT_GENERATOR_VERSION

from cayu.storage import KNOWLEDGE_CHUNK_TEXT_GENERATOR_VERSION

KNOWLEDGE_CHUNK_TEXT_GENERATOR_VERSION = '1'

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_CHUNK_TEXT_PREPROCESSING_VERSION

from cayu.storage import KNOWLEDGE_CHUNK_TEXT_PREPROCESSING_VERSION

KNOWLEDGE_CHUNK_TEXT_PREPROCESSING_VERSION = 'cayu:knowledge-chunk-text:v1'

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_CHUNK_TEXT_PROJECTION

from cayu.storage import KNOWLEDGE_CHUNK_TEXT_PROJECTION

KNOWLEDGE_CHUNK_TEXT_PROJECTION = 'knowledge_chunk_text'

Release source · Runtime guarantees · Capability guides

KNOWLEDGE_VECTOR_INDEX_REPRESENTATION_VERSION

from cayu.storage import KNOWLEDGE_VECTOR_INDEX_REPRESENTATION_VERSION

KNOWLEDGE_VECTOR_INDEX_REPRESENTATION_VERSION = 'float32-cosine-v1'

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingBackfillResult

from cayu.storage import KnowledgeEmbeddingBackfillResult

Portable outcome from one bounded embedding repair/backfill pass.

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
scanned_records	int	required
indexed_records	int	required
failed_records	int	required
skipped_records	int	required
limit	int	required
refresh_existing	bool	required
next_cursor	str | None	None

validate_count (method)

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

validate_limit (method)

KnowledgeEmbeddingBackfillResult.validate_limit(value: int) -> int

validate_refresh_existing (method)

KnowledgeEmbeddingBackfillResult.validate_refresh_existing(value) -> bool

validate_next_cursor (method)

KnowledgeEmbeddingBackfillResult.validate_next_cursor(value: str | None) -> str | None

validate_partition (method)

KnowledgeEmbeddingBackfillResult.validate_partition() -> KnowledgeEmbeddingBackfillResult

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingIdentity

from cayu.storage import KnowledgeEmbeddingIdentity

Complete identity of one durable knowledge embedding projection.

Content hashes alone are not sufficient reuse keys. Comparable vectors must agree on the canonical revision, projected content, embedding space, the projection generator, preprocessing, and the stored index representation.

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
entry_id	str	required
entry_revision	int	required
chunk_id	str | None	None
projection_type	str	required
projection_content_hash	str	required
embedding_model	str	required
dimensions	int	required
preprocessing_version	str	required
generator	str	required
generator_version	str	required
index_representation_version	str	required

validate_entry_id (method)

KnowledgeEmbeddingIdentity.validate_entry_id(value: str) -> str

validate_entry_revision (method)

KnowledgeEmbeddingIdentity.validate_entry_revision(value: int) -> int

validate_chunk_id (method)

KnowledgeEmbeddingIdentity.validate_chunk_id(value: str | None) -> str | None

validate_identity_component (method)

KnowledgeEmbeddingIdentity.validate_identity_component(value: str, info) -> str

validate_dimensions (method)

KnowledgeEmbeddingIdentity.validate_dimensions(value: int) -> int

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingProjection

from cayu.storage import KnowledgeEmbeddingProjection

One externally computed vector fenced to an exact pending projection attempt.

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
identity	KnowledgeEmbeddingIdentity	required
readiness_sequence	int	required
attempt_id	str	required
vector	list[float]	required

copy_identity (method)

KnowledgeEmbeddingProjection.copy_identity(value: KnowledgeEmbeddingIdentity) -> KnowledgeEmbeddingIdentity

validate_readiness_sequence (method)

KnowledgeEmbeddingProjection.validate_readiness_sequence(value: int) -> int

validate_attempt_id (method)

KnowledgeEmbeddingProjection.validate_attempt_id(value: str) -> str

copy_vector (method)

KnowledgeEmbeddingProjection.copy_vector(value) -> list[float]

validate_vector_dimensions (method)

KnowledgeEmbeddingProjection.validate_vector_dimensions() -> KnowledgeEmbeddingProjection

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingProjectionConflict

from cayu.storage import KnowledgeEmbeddingProjectionConflict

A projection attempt was reused with a different immutable vector payload.

Bases: RuntimeError.

init (method)

KnowledgeEmbeddingProjectionConflict.__init__(reason: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingProjectionWriteResult

from cayu.storage import KnowledgeEmbeddingProjectionWriteResult

Accepted identities from one bounded projection persistence request.

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
submitted_records	int	required
stored_identities	list[KnowledgeEmbeddingIdentity]	Field(default_factory=list)

validate_submitted_records (method)

KnowledgeEmbeddingProjectionWriteResult.validate_submitted_records(value: int) -> int

copy_stored_identities (method)

KnowledgeEmbeddingProjectionWriteResult.copy_stored_identities(value) -> list[KnowledgeEmbeddingIdentity]

validate_stored_partition (method)

KnowledgeEmbeddingProjectionWriteResult.validate_stored_partition() -> KnowledgeEmbeddingProjectionWriteResult

Release source · Runtime guarantees · Capability guides

KnowledgeEmbeddingWorkerResult

from cayu.storage import KnowledgeEmbeddingWorkerResult

Bounded outcome from consuming canonical changes into one embedding index.

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
consumer_id	str	required
worker_id	str	required
claimed_changes	int	required
acknowledged_changes	int	required
indexed_records	int	required
failed_records	int	required
removed_records	int	required
limit	int	required
processed_records	int	required
record_limit	int	required

validate_identity (method)

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

validate_count (method)

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

validate_limit (method)

KnowledgeEmbeddingWorkerResult.validate_limit(value: int) -> int

validate_record_limit (method)

KnowledgeEmbeddingWorkerResult.validate_record_limit(value: int) -> int

validate_claims (method)

KnowledgeEmbeddingWorkerResult.validate_claims() -> KnowledgeEmbeddingWorkerResult

Release source · Runtime guarantees · Capability guides

KnowledgeIndexCoverage

from cayu.storage import KnowledgeIndexCoverage

Machine-readable semantic-index coverage for one search projection.

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
projection_type	str	required
embedding_model	str	required
dimensions	int	required
preprocessing_version	str	required
generator	str	required
generator_version	str	required
index_representation_version	str	required
eligible_records	int	required
ready_records	int	required
pending_records	int	required
failed_records	int	required
high_water_sequence	int	required
complete	bool	required

validate_space_identity (method)

KnowledgeIndexCoverage.validate_space_identity(value: str, info) -> str

validate_dimensions (method)

KnowledgeIndexCoverage.validate_dimensions(value: int) -> int

validate_counts (method)

KnowledgeIndexCoverage.validate_counts(value: int, info) -> int

validate_high_water_sequence (method)

KnowledgeIndexCoverage.validate_high_water_sequence(value: int) -> int

validate_complete (method)

KnowledgeIndexCoverage.validate_complete(value) -> bool

validate_complete_partition (method)

KnowledgeIndexCoverage.validate_complete_partition() -> KnowledgeIndexCoverage

Release source · Runtime guarantees · Capability guides

KnowledgeIndexReadiness

from cayu.storage import KnowledgeIndexReadiness

Immutable sequenced evidence of one derived-index state transition.

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
sequence	int	required
identity	KnowledgeEmbeddingIdentity	required
state	KnowledgeIndexState	required
attempt_id	str	required
failure_code	str | None	None
operation_id	str	required
published_at	datetime	required

validate_sequence (method)

KnowledgeIndexReadiness.validate_sequence(value: int) -> int

copy_identity (method)

KnowledgeIndexReadiness.copy_identity(value: KnowledgeEmbeddingIdentity) -> KnowledgeEmbeddingIdentity

validate_required_identity (method)

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

validate_failure_code (method)

KnowledgeIndexReadiness.validate_failure_code(value: str | None) -> str | None

validate_published_at (method)

KnowledgeIndexReadiness.validate_published_at(value: datetime) -> datetime

validate_failure_state (method)

KnowledgeIndexReadiness.validate_failure_state() -> KnowledgeIndexReadiness

Release source · Runtime guarantees · Capability guides

KnowledgeIndexReadinessBatch

from cayu.storage import KnowledgeIndexReadinessBatch

Bounded ordered readiness events through one captured high-water mark.

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
readiness	list[KnowledgeIndexReadiness]	Field(default_factory=list)
after_sequence	int	0
next_after_sequence	int	0
high_water_sequence	int	0
truncated	bool	False
limit	int	required

copy_readiness (method)

KnowledgeIndexReadinessBatch.copy_readiness(value: list[KnowledgeIndexReadiness]) -> list[KnowledgeIndexReadiness]

validate_sequences (method)

KnowledgeIndexReadinessBatch.validate_sequences(value: int, info) -> int

validate_limit (method)

KnowledgeIndexReadinessBatch.validate_limit(value: int) -> int

validate_truncated (method)

KnowledgeIndexReadinessBatch.validate_truncated(value) -> bool

validate_page (method)

KnowledgeIndexReadinessBatch.validate_page() -> KnowledgeIndexReadinessBatch

Release source · Runtime guarantees · Capability guides

KnowledgeIndexReadinessConflict

from cayu.storage import KnowledgeIndexReadinessConflict

A readiness publication conflicts with its identity or sequence fence.

Bases: RuntimeError.

init (method)

KnowledgeIndexReadinessConflict.__init__(reason: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeIndexReadinessUpdate

from cayu.storage import KnowledgeIndexReadinessUpdate

One requested state transition for an exact embedding identity.

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
identity	KnowledgeEmbeddingIdentity	required
state	KnowledgeIndexState	required
attempt_id	str	required
failure_code	str | None	None

copy_identity (method)

KnowledgeIndexReadinessUpdate.copy_identity(value: KnowledgeEmbeddingIdentity) -> KnowledgeEmbeddingIdentity

validate_attempt_id (method)

KnowledgeIndexReadinessUpdate.validate_attempt_id(value: str) -> str

validate_failure_code (method)

KnowledgeIndexReadinessUpdate.validate_failure_code(value: str | None) -> str | None

validate_failure_state (method)

KnowledgeIndexReadinessUpdate.validate_failure_state() -> KnowledgeIndexReadinessUpdate

Release source · Runtime guarantees · Capability guides

KnowledgeIndexState

from cayu.storage import KnowledgeIndexState

Publication state for one exact derived-index identity.

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	class attribute	'pending'
READY	class attribute	'ready'
FAILED	class attribute	'failed'

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_EMBEDDING_DIMENSIONS

from cayu.storage import MAX_KNOWLEDGE_EMBEDDING_DIMENSIONS

MAX_KNOWLEDGE_EMBEDDING_DIMENSIONS = 2 ** 31 - 1

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT

from cayu.storage import MAX_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT

MAX_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT = 10000

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_INDEX_READINESS_LIMIT

from cayu.storage import MAX_KNOWLEDGE_INDEX_READINESS_LIMIT

MAX_KNOWLEDGE_INDEX_READINESS_LIMIT = 1000

Release source · Runtime guarantees · Capability guides