cayu.knowledge.relations

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.

KnowledgeLineageCurrentness

from cayu.storage import KnowledgeLineageCurrentness

Whether both exact relation endpoints are still their logical current revisions.

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
CURRENT	class attribute	'current'
STALE	class attribute	'stale'

Release source · Runtime guarantees · Capability guides

KnowledgeLineageLink

from cayu.storage import KnowledgeLineageLink

Privacy-safe relation projection around one exact inspected revision.

The projection deliberately excludes entry text, relation metadata, actors, and policy payloads. It is therefore suitable for recall explanations without granting ordinary read access to an archived predecessor’s content.

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
relation_id	str	required
kind	KnowledgeRelationKind	required
role	KnowledgeLineageRole	required
counterpart	KnowledgeRevisionRef	required
counterpart_current	KnowledgeRevisionRef	required
counterpart_status	KnowledgeStatus	required
currentness	KnowledgeLineageCurrentness	required
unresolved_contradiction	bool	False
created_at	datetime	required

validate_relation_id (method)

KnowledgeLineageLink.validate_relation_id(value: str) -> str

copy_reference (method)

KnowledgeLineageLink.copy_reference(value)

validate_unresolved_contradiction (method)

KnowledgeLineageLink.validate_unresolved_contradiction(value) -> bool

validate_created_at (method)

KnowledgeLineageLink.validate_created_at(value: datetime) -> datetime

validate_projection (method)

KnowledgeLineageLink.validate_projection() -> KnowledgeLineageLink

Release source · Runtime guarantees · Capability guides

KnowledgeLineageQuery

from cayu.storage import KnowledgeLineageQuery

Bounded filters for safe exact-revision lineage inspection.

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
reference	KnowledgeRevisionRef	required
direction	KnowledgeRelationDirection	KnowledgeRelationDirection.BOTH
kinds	list[KnowledgeRelationKind]	Field(default_factory=list)
currentnesses	list[KnowledgeLineageCurrentness]	Field(default_factory=lambda: list(KnowledgeLineageCurrentness))
counterpart_statuses	list[KnowledgeStatus]	Field(default_factory=lambda: list(KnowledgeStatus))
unresolved_only	bool	False
limit	int	DEFAULT_KNOWLEDGE_LIMIT
max_bytes	int	DEFAULT_KNOWLEDGE_MAX_BYTES
cursor	str | None	None

copy_reference (method)

KnowledgeLineageQuery.copy_reference(value)

copy_kinds (method)

KnowledgeLineageQuery.copy_kinds(value) -> list[KnowledgeRelationKind]

copy_currentnesses (method)

KnowledgeLineageQuery.copy_currentnesses(value) -> list[KnowledgeLineageCurrentness]

copy_counterpart_statuses (method)

KnowledgeLineageQuery.copy_counterpart_statuses(value) -> list[KnowledgeStatus]

validate_nonempty_filters (method)

KnowledgeLineageQuery.validate_nonempty_filters(value: list[Any], info) -> list[Any]

validate_unresolved_only (method)

KnowledgeLineageQuery.validate_unresolved_only(value) -> bool

validate_limit (method)

KnowledgeLineageQuery.validate_limit(value: int) -> int

validate_max_bytes (method)

KnowledgeLineageQuery.validate_max_bytes(value: int) -> int

validate_cursor (method)

KnowledgeLineageQuery.validate_cursor(value: str | None) -> str | None

validate_unresolved_filter (method)

KnowledgeLineageQuery.validate_unresolved_filter() -> KnowledgeLineageQuery

Release source · Runtime guarantees · Capability guides

KnowledgeLineageResult

from cayu.storage import KnowledgeLineageResult

One bounded safe lineage page for an authorized exact revision.

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
query	KnowledgeLineageQuery	required
reference_current	KnowledgeRevisionRef	required
reference_status	KnowledgeStatus	required
links	list[KnowledgeLineageLink]	Field(default_factory=list)
truncated	bool	False
next_cursor	str | None	None

copy_query (method)

KnowledgeLineageResult.copy_query(value)

copy_reference (method)

KnowledgeLineageResult.copy_reference(value)

copy_links (method)

KnowledgeLineageResult.copy_links(value)

validate_truncated (method)

KnowledgeLineageResult.validate_truncated(value) -> bool

validate_next_cursor (method)

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

validate_page (method)

KnowledgeLineageResult.validate_page() -> KnowledgeLineageResult

Release source · Runtime guarantees · Capability guides

KnowledgeLineageRole

from cayu.storage import KnowledgeLineageRole

Meaning of one relation from the inspected revision’s perspective.

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
SUPERSEDES	class attribute	'supersedes'
SUPERSEDED_BY	class attribute	'superseded_by'
DERIVED_FROM	class attribute	'derived_from'
DERIVATION_SOURCE_FOR	class attribute	'derivation_source_for'
CONTRADICTS	class attribute	'contradicts'

Release source · Runtime guarantees · Capability guides

KnowledgeRelation

from cayu.storage import KnowledgeRelation

Immutable semantic lineage between two exact entry revisions.

Direction is meaningful: a replacement supersedes its predecessor and a derived revision derived_from its source. contradicts is symmetric; stores canonicalize its endpoint order before publication.

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
id	str	required
subject	KnowledgeRevisionRef	required
object	KnowledgeRevisionRef	required
kind	KnowledgeRelationKind	required
created_by_type	KnowledgeActorType	KnowledgeActorType.APP
created_by	str	'app'
policy_id	str | None	None
created_at	datetime	Field(default_factory=lambda: datetime.now(UTC))
metadata	dict[str, Any]	Field(default_factory=dict)

validate_id (method)

KnowledgeRelation.validate_id(value: str) -> str

copy_reference (method)

KnowledgeRelation.copy_reference(value)

validate_created_by (method)

KnowledgeRelation.validate_created_by(value: str) -> str

validate_policy_id (method)

KnowledgeRelation.validate_policy_id(value: str | None) -> str | None

validate_created_at (method)

KnowledgeRelation.validate_created_at(value: datetime) -> datetime

copy_metadata (method)

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

validate_relation (method)

KnowledgeRelation.validate_relation() -> KnowledgeRelation

Release source · Runtime guarantees · Capability guides

KnowledgeRelationConflict

from cayu.storage import KnowledgeRelationConflict

A relation publication conflicts with immutable durable state.

Bases: RuntimeError.

init (method)

KnowledgeRelationConflict.__init__(reason: str) -> None

Release source · Runtime guarantees · Capability guides

KnowledgeRelationDirection

from cayu.storage import KnowledgeRelationDirection

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
OUTGOING	class attribute	'outgoing'
INCOMING	class attribute	'incoming'
BOTH	class attribute	'both'

Release source · Runtime guarantees · Capability guides

KnowledgeRelationKind

from cayu.storage import KnowledgeRelationKind

Closed semantic vocabulary for exact cross-entry knowledge lineage.

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
SUPERSEDES	class attribute	'supersedes'
DERIVED_FROM	class attribute	'derived_from'
CONTRADICTS	class attribute	'contradicts'

Release source · Runtime guarantees · Capability guides

KnowledgeRelationPublicationReceipt

from cayu.storage import KnowledgeRelationPublicationReceipt

Immutable replay evidence for one atomic relation batch publication.

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
operation_id	str	required
relation_ids	list[str]	required
request_sha256	str	required
committed_at	datetime	required
replayed	bool	False

validate_operation_id (method)

KnowledgeRelationPublicationReceipt.validate_operation_id(value: str) -> str

validate_relation_ids (method)

KnowledgeRelationPublicationReceipt.validate_relation_ids(value) -> list[str]

validate_request_sha256 (method)

KnowledgeRelationPublicationReceipt.validate_request_sha256(value: str) -> str

validate_committed_at (method)

KnowledgeRelationPublicationReceipt.validate_committed_at(value: datetime) -> datetime

validate_replayed (method)

KnowledgeRelationPublicationReceipt.validate_replayed(value) -> bool

Release source · Runtime guarantees · Capability guides

KnowledgeRelationQuery

from cayu.storage import KnowledgeRelationQuery

Bounded exact-revision relation lookup.

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
reference	KnowledgeRevisionRef	required
direction	KnowledgeRelationDirection	KnowledgeRelationDirection.BOTH
kinds	list[KnowledgeRelationKind]	Field(default_factory=list)
limit	int	DEFAULT_KNOWLEDGE_LIMIT
max_bytes	int	DEFAULT_KNOWLEDGE_MAX_BYTES
cursor	str | None	None

copy_reference (method)

KnowledgeRelationQuery.copy_reference(value)

copy_kinds (method)

KnowledgeRelationQuery.copy_kinds(value) -> list[KnowledgeRelationKind]

validate_limit (method)

KnowledgeRelationQuery.validate_limit(value: int) -> int

validate_max_bytes (method)

KnowledgeRelationQuery.validate_max_bytes(value: int) -> int

validate_cursor (method)

KnowledgeRelationQuery.validate_cursor(value: str | None) -> str | None

Release source · Runtime guarantees · Capability guides

KnowledgeRelationResult

from cayu.storage import KnowledgeRelationResult

One honest bounded page of accessible revision-bound relations.

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
query	KnowledgeRelationQuery	required
relations	list[KnowledgeRelation]	Field(default_factory=list)
truncated	bool	False
next_cursor	str | None	None

copy_query (method)

KnowledgeRelationResult.copy_query(value)

copy_relations (method)

KnowledgeRelationResult.copy_relations(value)

validate_truncated (method)

KnowledgeRelationResult.validate_truncated(value) -> bool

validate_next_cursor (method)

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

validate_page (method)

KnowledgeRelationResult.validate_page() -> KnowledgeRelationResult

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_RELATION_BATCH

from cayu.storage import MAX_KNOWLEDGE_RELATION_BATCH

MAX_KNOWLEDGE_RELATION_BATCH = 100

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_RELATION_BYTES

from cayu.storage import MAX_KNOWLEDGE_RELATION_BYTES

MAX_KNOWLEDGE_RELATION_BYTES = 8192

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_RELATION_CURSOR_BYTES

from cayu.storage import MAX_KNOWLEDGE_RELATION_CURSOR_BYTES

MAX_KNOWLEDGE_RELATION_CURSOR_BYTES = 2048

Release source · Runtime guarantees · Capability guides

MAX_KNOWLEDGE_RELATION_LIMIT

from cayu.storage import MAX_KNOWLEDGE_RELATION_LIMIT

MAX_KNOWLEDGE_RELATION_LIMIT = 1000

Release source · Runtime guarantees · Capability guides

prepare_knowledge_relations

from cayu.storage import prepare_knowledge_relations

Copy, canonicalize, bound, and fingerprint one relation publication.

prepare_knowledge_relations(relations: list[KnowledgeRelation], *, operation_id: str) -> tuple[str, list[KnowledgeRelation], str]

Release source · Runtime guarantees · Capability guides