cayu.knowledge.base

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.

KnowledgeStore

from cayu.storage import KnowledgeStore

Searchable knowledge contract.

Bases: ABC.

inspect_closure_sources (method)

async KnowledgeStore.inspect_closure_sources(query: KnowledgeClosureQuery) -> dict[str, object]

Inventory retained evidence and projections for exact source identities.

This administrative seam does not expose source payloads, knowledge content, metadata, or vectors. Unsupported stores must refuse rather than acknowledge an empty inventory.

bound_access_scope (method)

KnowledgeStore.bound_access_scope() -> KnowledgeAccessScope | None

Return the explicitly bound single-principal scope, if configured.

supported_search_modes (method)

KnowledgeStore.supported_search_modes() -> tuple[KnowledgeSearchMode, ...]

Return search modes this store can execute directly.

create_entry (method)

async KnowledgeStore.create_entry(entry: KnowledgeEntry, chunks: list[KnowledgeChunk] | None=None, *, evidence: list[KnowledgeEvidence] | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntry

Create revision 1 of a previously unoccupied logical entry id.

append_entry_revision (method)

async KnowledgeStore.append_entry_revision(entry: KnowledgeEntry, chunks: list[KnowledgeChunk] | None=None, *, expected_revision: int, evidence: list[KnowledgeEvidence] | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntry

Append exactly one revision using compare-and-swap.

get_entry (method)

async KnowledgeStore.get_entry(entry_id: str, *, revision: int | None=None, max_bytes: int | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntry | None

Load one revision, optionally refusing its content before copying it.

search_revisions (method)

async KnowledgeStore.search_revisions(query: KnowledgeQuery, revision_refs: Sequence[KnowledgeRevisionRef], *, knowledge_sequence: int | None=None, index_readiness_sequence: int | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResult

Search referenced current revisions, optionally at one captured frontier.

This narrow operation exists for delta retrieval. Implementations must apply revision eligibility before ranking; searching globally and filtering the returned top-k candidates is not conformant. When frontier sequences are supplied, both must be supplied and neither authoritative materialization nor semantic readiness may cross them.

search_at_frontier (method)

async KnowledgeStore.search_at_frontier(query: KnowledgeQuery, *, knowledge_sequence: int, index_readiness_sequence: int, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResult

Search current records whose authoritative inputs existed at a captured frontier.

This narrow operation exists for full-index checkpoint recall. Implementations must exclude current revisions materialized after knowledge_sequence and semantic readiness published after index_readiness_sequence. Falling back to an ordinary current search is not conformant because it can cross the captured processing frontier.

transition_entry_status (method)

async KnowledgeStore.transition_entry_status(entry_id: str, *, expected_revision: int, access_scope: KnowledgeAccessScope | None=None, from_status: KnowledgeStatus, to_status: KnowledgeStatus, expected_namespace: str | None=None, expected_labels: dict[str, str] | None=None) -> KnowledgeEntry

Append one lifecycle-only revision using compare-and-swap.

delete_entry (method)

async KnowledgeStore.delete_entry(entry_id: str, *, expected_revision: int, access_scope: KnowledgeAccessScope | None=None, hard: bool=False) -> KnowledgeEntry | None

Append a tombstone by default, or physically erase after a CAS check.

Hard deletion also erases governed activation history retained after expiration pruning. In that case the canonical entry is already absent, so a successful, idempotent audit purge returns None.

publish_entry_revision (method)

async KnowledgeStore.publish_entry_revision(entry: KnowledgeEntry, chunks: list[KnowledgeChunk], *, evidence: list[KnowledgeEvidence] | None=None, access_scope: KnowledgeAccessScope | None=None, operation_id: str, expected_revision: int | None=None, activation_authority: KnowledgeActivationAuthority | None=None) -> KnowledgePublicationReceipt

Publish one create/append exactly once with immutable replay evidence.

Implementations commit the revision, chunks, evidence, current pointer, metadata-only change, and receipt atomically. expected_revision=None creates revision 1; a positive value appends exactly its successor. Use prepare_knowledge_publication to copy and bind the canonical authority tuple before entering the store transaction.

approve_pending_entry (method)

async KnowledgeStore.approve_pending_entry(authority: KnowledgeActivationAuthority, *, access_scope: KnowledgeAccessScope | None=None, expected_namespace: str | None=None, expected_labels: dict[str, str] | None=None) -> KnowledgeReviewApproval

Atomically append one active successor under explicit reviewed authority.

load_activation_receipt (method)

async KnowledgeStore.load_activation_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeActivationReceipt | None

Load immutable activation attribution for one exact operation.

load_entry_publication_receipt (method)

async KnowledgeStore.load_entry_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgePublicationReceipt | None

Load immutable publication evidence for one operation id.

publish_relations (method)

async KnowledgeStore.publish_relations(relations: list[KnowledgeRelation], *, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationPublicationReceipt

Atomically publish one bounded immutable relation batch exactly once.

load_relation_publication_receipt (method)

async KnowledgeStore.load_relation_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationPublicationReceipt | None

Load immutable replay evidence for one relation publication.

read_relations (method)

async KnowledgeStore.read_relations(query: KnowledgeRelationQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationResult | None

Read one bounded page around an exact authorized revision.

inspect_lineage (method)

async KnowledgeStore.inspect_lineage(query: KnowledgeLineageQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeLineageResult | None

Inspect safe lineage around one exact authorized revision.

publish_maintenance_proposal (method)

async KnowledgeStore.publish_maintenance_proposal(entry: KnowledgeEntry, chunks: list[KnowledgeChunk], *, evidence: list[KnowledgeEvidence], proposal: KnowledgeMaintenanceProposal, accepted_plan: KnowledgeMaintenanceAcceptedPlan, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposalPublicationReceipt

Atomically persist one accepted plan as a pending review artifact.

load_maintenance_proposal_publication (method)

async KnowledgeStore.load_maintenance_proposal_publication(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposalPublication | None

Load one exact pending or decided maintenance proposal artifact.

apply_maintenance_decision (method)

async KnowledgeStore.apply_maintenance_decision(proposal: KnowledgeMaintenanceProposal, decision: KnowledgeMaintenanceDecision, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecisionReceipt

Apply one exact reviewed maintenance decision atomically.

record_maintenance_governance_route (method)

async KnowledgeStore.record_maintenance_governance_route(authority: KnowledgeMaintenanceGovernanceAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceGovernanceReceipt

Atomically retain route-to-review authority without lifecycle changes.

load_maintenance_governance_route (method)

async KnowledgeStore.load_maintenance_governance_route(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceGovernanceReceipt | None

Load immutable route-to-review attribution in scope.

record_semantic_watch_outcome (method)

async KnowledgeStore.record_semantic_watch_outcome(authority: KnowledgeSemanticWatchAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt

Atomically retain one exact policy-governed semantic-watch outcome.

load_semantic_watch_receipt (method)

async KnowledgeStore.load_semantic_watch_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt | None

Load immutable semantic-watch attribution for one scoped operation.

load_maintenance_proposal (method)

async KnowledgeStore.load_maintenance_proposal(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposal | None

Load one durably published or decided maintenance proposal in scope.

load_maintenance_decision (method)

async KnowledgeStore.load_maintenance_decision(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecision | None

Load one durable maintenance decision in scope.

load_maintenance_decision_receipt (method)

async KnowledgeStore.load_maintenance_decision_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecisionReceipt | None

Load immutable maintenance application evidence in scope.

read_evidence (method)

async KnowledgeStore.read_evidence(entry_id: str, *, revision: int | None=None, access_scope: KnowledgeAccessScope | None=None, max_records: int=DEFAULT_KNOWLEDGE_LIMIT, max_bytes: int=DEFAULT_KNOWLEDGE_MAX_BYTES) -> KnowledgeEvidenceResult | None

Read evidence for the current or one exact authorized revision.

read_chunks (method)

async KnowledgeStore.read_chunks(entry_id: str, *, revision: int | None=None, access_scope: KnowledgeAccessScope | None=None, chunk_index: int | None=None, around: int=0, max_chunks: int=DEFAULT_KNOWLEDGE_LIMIT, max_bytes: int=DEFAULT_KNOWLEDGE_MAX_BYTES) -> list[KnowledgeChunk]

Read bounded chunks for the current or one exact historical revision.

search (method)

async KnowledgeStore.search(query: KnowledgeQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResult

Search knowledge and return a bounded result envelope.

list_entries (method)

async KnowledgeStore.list_entries(query: KnowledgeListQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeListResult

List entries/facets for discovery without requiring a lexical search term.

read_changes (method)

async KnowledgeStore.read_changes(*, after_sequence: int=0, limit: int=DEFAULT_KNOWLEDGE_LIMIT, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeBatch

Read one bounded ordered page of accessible canonical changes.

initialize_change_consumer (method)

async KnowledgeStore.initialize_change_consumer(consumer_id: str, *, baseline_sequence: int, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState

Bind a consumer and its cursor to a captured full-scan high-water mark.

claim_change (method)

async KnowledgeStore.claim_change(consumer_id: str, worker_id: str, *, lease_seconds: float=300.0, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeClaim | None

Lease the consumer’s next accessible change with at-least-once semantics.

acknowledge_change (method)

async KnowledgeStore.acknowledge_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState

Fenced acknowledgement that advances one consumer cursor.

release_change (method)

async KnowledgeStore.release_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState

Release a live claim without advancing its consumer cursor.

load_change_consumer_state (method)

async KnowledgeStore.load_change_consumer_state(consumer_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState | None

Load one scope-bound consumer cursor and lease state.

publish_index_readiness (method)

async KnowledgeStore.publish_index_readiness(update: KnowledgeIndexReadinessUpdate, *, expected_sequence: int | None, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadiness

Publish one fenced derived-index state transition.

This hook is intentionally optional so lexical-only custom stores do not have to pretend they own derived indexes. Implementations that advertise semantic retrieval must provide equivalent durable semantics.

load_index_readiness (method)

async KnowledgeStore.load_index_readiness(identity: KnowledgeEmbeddingIdentity, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadiness | None

Load the latest accessible readiness for one exact identity.

store_embedding_projections (method)

async KnowledgeStore.store_embedding_projections(projections: list[KnowledgeEmbeddingProjection], *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEmbeddingProjectionWriteResult

Persist already-computed vectors for exact current pending attempts.

Stale, superseded, and unauthorized projections are omitted from the returned accepted identities. Readiness remains a separate fenced publication step so a vector cannot become searchable prematurely.

backfill_embeddings (method)

async KnowledgeStore.backfill_embeddings(query: KnowledgeListQuery | None=None, *, access_scope: KnowledgeAccessScope | None=None, limit: int=DEFAULT_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT, refresh_existing: bool=False, cursor: str | None=None) -> KnowledgeEmbeddingBackfillResult

Repair one bounded page of current embedding projections.

Pass the previous result’s next_cursor to continue the exact same query, scope, projection configuration, and refresh mode.

read_index_readiness (method)

async KnowledgeStore.read_index_readiness(*, after_sequence: int=0, limit: int=DEFAULT_KNOWLEDGE_LIMIT, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadinessBatch

Read accessible readiness events through a captured high-water mark.

prune_expired (method)

async KnowledgeStore.prune_expired(*, access_scope: KnowledgeAccessScope | None=None, now: datetime | None=None) -> int

Hard-delete entries whose expires_at is at or before now (default: current UTC).

Returns the count removed. Read-time expiry filtering only hides expired entries; this reclaims their storage. Hosts call it on a schedule or opportunistically. now is injectable for deterministic tests.

Default raises NotImplementedError so out-of-tree stores keep working.

Release source · Runtime guarantees · Capability guides