cayu.knowledge.records

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.

`BUILTIN_KNOWLEDGE_KINDS`

from cayu.storage import BUILTIN_KNOWLEDGE_KINDS

BUILTIN_KNOWLEDGE_KINDS = ('fact', 'preference', 'procedure', 'instruction', 'skill', 'document', 'example', 'warning', 'decision', 'event', 'summary')

Release source · Runtime guarantees · Capability guides

`copy_knowledge_revision_refs`

from cayu.storage import copy_knowledge_revision_refs

Copy, bound, deduplicate, and canonically order exact revision references.

copy_knowledge_revision_refs(value: Sequence[KnowledgeRevisionRef]) -> tuple[KnowledgeRevisionRef, ...]

Release source · Runtime guarantees · Capability guides

`DEFAULT_KNOWLEDGE_KIND`

from cayu.storage import DEFAULT_KNOWLEDGE_KIND

DEFAULT_KNOWLEDGE_KIND = 'fact'

Release source · Runtime guarantees · Capability guides

`DEFAULT_KNOWLEDGE_LIMIT`

from cayu.storage import DEFAULT_KNOWLEDGE_LIMIT

DEFAULT_KNOWLEDGE_LIMIT = 10

Release source · Runtime guarantees · Capability guides

`DEFAULT_KNOWLEDGE_MAX_BYTES`

from cayu.storage import DEFAULT_KNOWLEDGE_MAX_BYTES

DEFAULT_KNOWLEDGE_MAX_BYTES = 20000

Release source · Runtime guarantees · Capability guides

`DEFAULT_KNOWLEDGE_NAMESPACE`

from cayu.storage import DEFAULT_KNOWLEDGE_NAMESPACE

DEFAULT_KNOWLEDGE_NAMESPACE = 'default'

Release source · Runtime guarantees · Capability guides

`KnowledgeActorType`

from cayu.storage import KnowledgeActorType

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
`APP`	`class attribute`	`'app'`
`USER`	`class attribute`	`'user'`
`MODEL`	`class attribute`	`'model'`
`SYSTEM`	`class attribute`	`'system'`

Release source · Runtime guarantees · Capability guides

`KnowledgeChunk`

from cayu.storage import KnowledgeChunk

Immutable chunk belonging to one exact knowledge revision.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`id`	`str`	`required`
`entry_id`	`str`	`required`
`entry_revision`	`int`	`1`
`text`	`str`	`required`
`chunk_index`	`int`	`required`
`content_hash`	`str \| None`	`None`
`source_uri`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

copy_metadata (method)

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

validate_id (method)

KnowledgeChunk.validate_id(value: str) -> str

validate_clean_nonblank_fields (method)

KnowledgeChunk.validate_clean_nonblank_fields(value: str, info) -> str

validate_nonblank_text (method)

KnowledgeChunk.validate_nonblank_text(value: str, info) -> str

validate_optional_clean_nonblank_fields (method)

KnowledgeChunk.validate_optional_clean_nonblank_fields(value: str | None, info) -> str | None

validate_chunk_index (method)

KnowledgeChunk.validate_chunk_index(value: int, info) -> int

validate_entry_revision (method)

KnowledgeChunk.validate_entry_revision(value: int) -> int

Release source · Runtime guarantees · Capability guides

`KnowledgeChunkConflict`

from cayu.storage import KnowledgeChunkConflict

A knowledge write conflicts with an occupied global chunk identity.

Bases: RuntimeError.

init (method)

KnowledgeChunkConflict.__init__(operation: str) -> None

Release source · Runtime guarantees · Capability guides

`KnowledgeEntry`

from cayu.storage import KnowledgeEntry

Immutable snapshot of one exact logical knowledge revision.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`id`	`str`	`required`
`revision`	`int`	`1`
`text`	`str`	`required`
`namespace`	`str`	`DEFAULT_KNOWLEDGE_NAMESPACE`
`labels`	`dict[str, str]`	`Field(default_factory=dict)`
`kind`	`str`	`DEFAULT_KNOWLEDGE_KIND`
`visibility`	`KnowledgeVisibility`	`KnowledgeVisibility.GLOBAL`
`status`	`KnowledgeStatus`	`KnowledgeStatus.ACTIVE`
`created_by_type`	`KnowledgeActorType`	`KnowledgeActorType.APP`
`created_by`	`str`	`'app'`
`created_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`updated_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`source_type`	`str \| None`	`None`
`source_uri`	`str \| None`	`None`
`source_id`	`str \| None`	`None`
`source_hash`	`str \| None`	`None`
`aspects`	`list[str]`	`Field(default_factory=list)`
`impact_targets`	`list[str]`	`Field(default_factory=list)`
`importance`	`float \| None`	`None`
`importance_source`	`str \| None`	`None`
`confidence`	`float \| None`	`None`
`last_used_at`	`datetime \| None`	`None`
`expires_at`	`datetime \| None`	`None`
`title`	`str \| None`	`None`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

copy_metadata (method)

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

copy_labels (method)

KnowledgeEntry.copy_labels(value) -> dict[str, str]

validate_id (method)

KnowledgeEntry.validate_id(value: str) -> str

validate_clean_nonblank_fields (method)

KnowledgeEntry.validate_clean_nonblank_fields(value: str, info) -> str

validate_created_by (method)

KnowledgeEntry.validate_created_by(value: object) -> str

validate_revision (method)

KnowledgeEntry.validate_revision(value: int) -> int

validate_nonblank_text (method)

KnowledgeEntry.validate_nonblank_text(value: str, info) -> str

validate_optional_clean_nonblank_fields (method)

KnowledgeEntry.validate_optional_clean_nonblank_fields(value: str | None, info) -> str | None

copy_string_list (method)

KnowledgeEntry.copy_string_list(value, info) -> list[str]

validate_optional_unit_interval (method)

KnowledgeEntry.validate_optional_unit_interval(value, info) -> float | None

validate_timezone_aware_datetime (method)

KnowledgeEntry.validate_timezone_aware_datetime(value: datetime | None, info) -> datetime | None

validate_timestamp_order (method)

KnowledgeEntry.validate_timestamp_order() -> KnowledgeEntry

Release source · Runtime guarantees · Capability guides

`KnowledgeEntryReadLimitExceeded`

from cayu.storage import KnowledgeEntryReadLimitExceeded

An authorized entry exceeds a caller-owned read byte ceiling.

Bases: ValueError.

init (method)

KnowledgeEntryReadLimitExceeded.__init__(entry_id: str, *, revision: int, payload_bytes: int, max_bytes: int) -> None

Release source · Runtime guarantees · Capability guides

`KnowledgeEvidence`

from cayu.storage import KnowledgeEvidence

Immutable exact source evidence for one knowledge revision.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`id`	`str`	`required`
`entry_id`	`str`	`required`
`entry_revision`	`int`	`1`
`chunk_id`	`str \| None`	`None`
`role`	`KnowledgeEvidenceRole`	`KnowledgeEvidenceRole.ORIGIN`
`source_type`	`str`	`required`
`source_id`	`str \| None`	`None`
`source_uri`	`str \| None`	`None`
`source_revision`	`str \| None`	`None`
`source_hash`	`str \| None`	`None`
`locator`	`dict[str, Any]`	`Field(default_factory=dict)`
`disposition`	`KnowledgeEvidenceDisposition`	`KnowledgeEvidenceDisposition.LIVE`
`created_at`	`datetime`	`Field(default_factory=lambda: datetime.now(UTC))`
`metadata`	`dict[str, Any]`	`Field(default_factory=dict)`

validate_required_identity (method)

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

validate_entry_id (method)

KnowledgeEvidence.validate_entry_id(value: str) -> str

validate_optional_identity (method)

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

validate_chunk_id (method)

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

validate_entry_revision (method)

KnowledgeEvidence.validate_entry_revision(value: int) -> int

copy_json_objects (method)

KnowledgeEvidence.copy_json_objects(value: dict[str, Any], info) -> dict[str, Any]

validate_created_at (method)

KnowledgeEvidence.validate_created_at(value: datetime) -> datetime

validate_stable_source_identity (method)

KnowledgeEvidence.validate_stable_source_identity() -> KnowledgeEvidence

Release source · Runtime guarantees · Capability guides

`KnowledgeEvidenceConflict`

from cayu.storage import KnowledgeEvidenceConflict

A knowledge write conflicts with an occupied global evidence identity.

Bases: RuntimeError.

init (method)

KnowledgeEvidenceConflict.__init__(operation: str) -> None

Release source · Runtime guarantees · Capability guides

`KnowledgeEvidenceDisposition`

from cayu.storage import KnowledgeEvidenceDisposition

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`LIVE`	`class attribute`	`'live'`
`DETACHED`	`class attribute`	`'detached'`
`RETAINED`	`class attribute`	`'retained'`

Release source · Runtime guarantees · Capability guides

`KnowledgeEvidenceResult`

from cayu.storage import KnowledgeEvidenceResult

Bounded evidence for one exact authorized knowledge revision.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`entry_id`	`str`	`required`
`entry_revision`	`int`	`required`
`evidence`	`list[KnowledgeEvidence]`	`Field(default_factory=list)`
`truncated`	`bool`	`False`
`limit`	`int`	`required`
`max_bytes`	`int`	`required`
`total_evidence_known`	`int`	`required`

validate_entry_id (method)

KnowledgeEvidenceResult.validate_entry_id(value: str) -> str

validate_entry_revision (method)

KnowledgeEvidenceResult.validate_entry_revision(value: int) -> int

copy_evidence (method)

KnowledgeEvidenceResult.copy_evidence(value) -> list[KnowledgeEvidence]

validate_limits (method)

KnowledgeEvidenceResult.validate_limits(value: int, info) -> int

validate_total (method)

KnowledgeEvidenceResult.validate_total(value: int) -> int

validate_truncated (method)

KnowledgeEvidenceResult.validate_truncated(value) -> bool

validate_result (method)

KnowledgeEvidenceResult.validate_result() -> KnowledgeEvidenceResult

Release source · Runtime guarantees · Capability guides

`KnowledgeEvidenceRole`

from cayu.storage import KnowledgeEvidenceRole

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`ORIGIN`	`class attribute`	`'origin'`
`SUPPORTING`	`class attribute`	`'supporting'`

Release source · Runtime guarantees · Capability guides

`KnowledgeRevisionConflict`

from cayu.storage import KnowledgeRevisionConflict

A canonical write lost a compare-and-swap race.

Bases: RuntimeError.

init (method)

KnowledgeRevisionConflict.__init__(entry_id: str, *, expected_revision: int | None, actual_revision: int | None) -> None

Release source · Runtime guarantees · Capability guides

`KnowledgeRevisionRef`

from cayu.storage import KnowledgeRevisionRef

Stable reference to one immutable revision of one logical entry.

Bases: BaseModel.

Fields and attributes

Name	Type	Default
`entry_id`	`str`	`required`
`revision`	`int`	`required`

validate_entry_id (method)

KnowledgeRevisionRef.validate_entry_id(value: str) -> str

validate_revision (method)

KnowledgeRevisionRef.validate_revision(value: int) -> int

Release source · Runtime guarantees · Capability guides

`KnowledgeStatus`

from cayu.storage import KnowledgeStatus

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`ACTIVE`	`class attribute`	`'active'`
`PENDING`	`class attribute`	`'pending'`
`ARCHIVED`	`class attribute`	`'archived'`
`DELETED`	`class attribute`	`'deleted'`

Release source · Runtime guarantees · Capability guides

`KnowledgeVisibility`

from cayu.storage import KnowledgeVisibility

Bases: StrEnum.

Fields and attributes

Name	Type	Default
`GLOBAL`	`class attribute`	`'global'`
`ORGANIZATION`	`class attribute`	`'organization'`
`PROJECT`	`class attribute`	`'project'`
`WORKSPACE`	`class attribute`	`'workspace'`
`USER`	`class attribute`	`'user'`
`SESSION`	`class attribute`	`'session'`
`TASK`	`class attribute`	`'task'`

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ACTIVATION_IDENTITY_BYTES`

from cayu.storage import MAX_KNOWLEDGE_ACTIVATION_IDENTITY_BYTES

MAX_KNOWLEDGE_ACTIVATION_IDENTITY_BYTES = 256

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_CHUNK_ID_BYTES`

from cayu.storage import MAX_KNOWLEDGE_CHUNK_ID_BYTES

MAX_KNOWLEDGE_CHUNK_ID_BYTES = 512

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_CHUNK_INDEX`

from cayu.storage import MAX_KNOWLEDGE_CHUNK_INDEX

MAX_KNOWLEDGE_CHUNK_INDEX = 2 ** 31 - 1

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_ENTRY_ID_BYTES`

from cayu.storage import MAX_KNOWLEDGE_ENTRY_ID_BYTES

MAX_KNOWLEDGE_ENTRY_ID_BYTES = 256

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_EVIDENCE_BYTES`

from cayu.storage import MAX_KNOWLEDGE_EVIDENCE_BYTES

MAX_KNOWLEDGE_EVIDENCE_BYTES = DEFAULT_KNOWLEDGE_MAX_BYTES

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_EVIDENCE_JSON_BYTES`

from cayu.storage import MAX_KNOWLEDGE_EVIDENCE_JSON_BYTES

MAX_KNOWLEDGE_EVIDENCE_JSON_BYTES = 16384

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_REVISION`

from cayu.storage import MAX_KNOWLEDGE_REVISION

MAX_KNOWLEDGE_REVISION = 2 ** 31 - 1

Release source · Runtime guarantees · Capability guides

`MAX_KNOWLEDGE_REVISION_SEARCH_REFS`

from cayu.storage import MAX_KNOWLEDGE_REVISION_SEARCH_REFS

MAX_KNOWLEDGE_REVISION_SEARCH_REFS = 250

Release source · Runtime guarantees · Capability guides