cayu.storage.PostgresKnowledgeStore
Part of cayu.storage.postgres. Read the Python API overview and install the required extra.
from cayu.storage import PostgresKnowledgeStorePostgres-backed durable knowledge store with full-text search.
Bases: _PostgresStoreBase, KnowledgeStore.
Fields and attributes
Section titled “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 |
|---|---|---|
resource_knowledge_access_version |
class attribute |
1 |
init (method)
Section titled “init (method)”PostgresKnowledgeStore.__init__(conninfo: str | None=None, *, pool: AsyncConnectionPool | None=None, min_size: int=1, max_size: int=8, schema_mode: schema.SchemaMode=schema.SchemaMode.VALIDATE, read_only: bool=False, access_scope: KnowledgeAccessScope | None=None, clock: Callable[[], datetime] | None=None) -> Noneensure_schema (method)
Section titled “ensure_schema (method)”async PostgresKnowledgeStore.ensure_schema() -> NoneOpen the pool and reconcile the schema now (per schema_mode).
Normally reconciliation happens lazily on first use; the cayu storage
CLI calls this to run a migrate (or validate) as an explicit step.
close (method)
Section titled “close (method)”async PostgresKnowledgeStore.close() -> Noneinspect_closure_sources (method)
Section titled “inspect_closure_sources (method)”async PostgresKnowledgeStore.inspect_closure_sources(query: KnowledgeClosureQuery) -> dict[str, object]bound_access_scope (method)
Section titled “bound_access_scope (method)”PostgresKnowledgeStore.bound_access_scope() -> KnowledgeAccessScope | NoneReturn the explicitly bound single-principal scope, if configured.
supported_search_modes (method)
Section titled “supported_search_modes (method)”PostgresKnowledgeStore.supported_search_modes() -> tuple[KnowledgeSearchMode, ...]Return search modes this store can execute directly.
create_entry (method)
Section titled “create_entry (method)”async PostgresKnowledgeStore.create_entry(entry: KnowledgeEntry, chunks: list[KnowledgeChunk] | None=None, *, evidence: list[KnowledgeEvidence] | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntryappend_entry_revision (method)
Section titled “append_entry_revision (method)”async PostgresKnowledgeStore.append_entry_revision(entry: KnowledgeEntry, chunks: list[KnowledgeChunk] | None=None, *, expected_revision: int, evidence: list[KnowledgeEvidence] | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntryget_entry (method)
Section titled “get_entry (method)”async PostgresKnowledgeStore.get_entry(entry_id: str, *, revision: int | None=None, max_bytes: int | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEntry | Nonesearch_revisions (method)
Section titled “search_revisions (method)”async PostgresKnowledgeStore.search_revisions(query: KnowledgeQuery, revision_refs: Sequence[KnowledgeRevisionRef], *, knowledge_sequence: int | None=None, index_readiness_sequence: int | None=None, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResultsearch_at_frontier (method)
Section titled “search_at_frontier (method)”async PostgresKnowledgeStore.search_at_frontier(query: KnowledgeQuery, *, knowledge_sequence: int, index_readiness_sequence: int, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResulttransition_entry_status (method)
Section titled “transition_entry_status (method)”async PostgresKnowledgeStore.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) -> KnowledgeEntrydelete_entry (method)
Section titled “delete_entry (method)”async PostgresKnowledgeStore.delete_entry(entry_id: str, *, expected_revision: int, access_scope: KnowledgeAccessScope | None=None, hard: bool=False) -> KnowledgeEntry | Nonepublish_entry_revision (method)
Section titled “publish_entry_revision (method)”async PostgresKnowledgeStore.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) -> KnowledgePublicationReceiptapprove_pending_entry (method)
Section titled “approve_pending_entry (method)”async PostgresKnowledgeStore.approve_pending_entry(authority: KnowledgeActivationAuthority, *, access_scope: KnowledgeAccessScope | None=None, expected_namespace: str | None=None, expected_labels: dict[str, str] | None=None) -> KnowledgeReviewApprovalload_activation_receipt (method)
Section titled “load_activation_receipt (method)”async PostgresKnowledgeStore.load_activation_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeActivationReceipt | Noneload_entry_publication_receipt (method)
Section titled “load_entry_publication_receipt (method)”async PostgresKnowledgeStore.load_entry_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgePublicationReceipt | Nonepublish_relations (method)
Section titled “publish_relations (method)”async PostgresKnowledgeStore.publish_relations(relations: list[KnowledgeRelation], *, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationPublicationReceiptload_relation_publication_receipt (method)
Section titled “load_relation_publication_receipt (method)”async PostgresKnowledgeStore.load_relation_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationPublicationReceipt | Noneread_relations (method)
Section titled “read_relations (method)”async PostgresKnowledgeStore.read_relations(query: KnowledgeRelationQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationResult | Noneinspect_lineage (method)
Section titled “inspect_lineage (method)”async PostgresKnowledgeStore.inspect_lineage(query: KnowledgeLineageQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeLineageResult | Nonepublish_maintenance_proposal (method)
Section titled “publish_maintenance_proposal (method)”async PostgresKnowledgeStore.publish_maintenance_proposal(entry: KnowledgeEntry, chunks: list[KnowledgeChunk], *, evidence: list[KnowledgeEvidence], proposal: KnowledgeMaintenanceProposal, accepted_plan: KnowledgeMaintenanceAcceptedPlan, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposalPublicationReceiptload_maintenance_proposal_publication (method)
Section titled “load_maintenance_proposal_publication (method)”async PostgresKnowledgeStore.load_maintenance_proposal_publication(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposalPublication | Noneapply_maintenance_decision (method)
Section titled “apply_maintenance_decision (method)”async PostgresKnowledgeStore.apply_maintenance_decision(proposal: KnowledgeMaintenanceProposal, decision: KnowledgeMaintenanceDecision, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecisionReceiptrecord_maintenance_governance_route (method)
Section titled “record_maintenance_governance_route (method)”async PostgresKnowledgeStore.record_maintenance_governance_route(authority: KnowledgeMaintenanceGovernanceAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceGovernanceReceiptload_maintenance_governance_route (method)
Section titled “load_maintenance_governance_route (method)”async PostgresKnowledgeStore.load_maintenance_governance_route(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceGovernanceReceipt | Nonerecord_semantic_watch_outcome (method)
Section titled “record_semantic_watch_outcome (method)”async PostgresKnowledgeStore.record_semantic_watch_outcome(authority: KnowledgeSemanticWatchAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceiptload_semantic_watch_receipt (method)
Section titled “load_semantic_watch_receipt (method)”async PostgresKnowledgeStore.load_semantic_watch_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt | Noneload_maintenance_proposal (method)
Section titled “load_maintenance_proposal (method)”async PostgresKnowledgeStore.load_maintenance_proposal(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposal | Noneload_maintenance_decision (method)
Section titled “load_maintenance_decision (method)”async PostgresKnowledgeStore.load_maintenance_decision(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecision | Noneload_maintenance_decision_receipt (method)
Section titled “load_maintenance_decision_receipt (method)”async PostgresKnowledgeStore.load_maintenance_decision_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecisionReceipt | Noneread_evidence (method)
Section titled “read_evidence (method)”async PostgresKnowledgeStore.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 | Noneread_chunks (method)
Section titled “read_chunks (method)”async PostgresKnowledgeStore.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]search (method)
Section titled “search (method)”async PostgresKnowledgeStore.search(query: KnowledgeQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResultlist_entries (method)
Section titled “list_entries (method)”async PostgresKnowledgeStore.list_entries(query: KnowledgeListQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeListResultread_changes (method)
Section titled “read_changes (method)”async PostgresKnowledgeStore.read_changes(*, after_sequence: int=0, limit: int=DEFAULT_KNOWLEDGE_LIMIT, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeBatchinitialize_change_consumer (method)
Section titled “initialize_change_consumer (method)”async PostgresKnowledgeStore.initialize_change_consumer(consumer_id: str, *, baseline_sequence: int, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStateclaim_change (method)
Section titled “claim_change (method)”async PostgresKnowledgeStore.claim_change(consumer_id: str, worker_id: str, *, lease_seconds: float=300.0, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeClaim | Noneacknowledge_change (method)
Section titled “acknowledge_change (method)”async PostgresKnowledgeStore.acknowledge_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStaterelease_change (method)
Section titled “release_change (method)”async PostgresKnowledgeStore.release_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStateload_change_consumer_state (method)
Section titled “load_change_consumer_state (method)”async PostgresKnowledgeStore.load_change_consumer_state(consumer_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState | Nonepublish_index_readiness (method)
Section titled “publish_index_readiness (method)”async PostgresKnowledgeStore.publish_index_readiness(update: KnowledgeIndexReadinessUpdate, *, expected_sequence: int | None, operation_id: str, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadinessload_index_readiness (method)
Section titled “load_index_readiness (method)”async PostgresKnowledgeStore.load_index_readiness(identity: KnowledgeEmbeddingIdentity, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadiness | Nonestore_embedding_projections (method)
Section titled “store_embedding_projections (method)”async PostgresKnowledgeStore.store_embedding_projections(projections: list[KnowledgeEmbeddingProjection], *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEmbeddingProjectionWriteResultPersist 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)
Section titled “backfill_embeddings (method)”async PostgresKnowledgeStore.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) -> KnowledgeEmbeddingBackfillResultRepair 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)
Section titled “read_index_readiness (method)”async PostgresKnowledgeStore.read_index_readiness(*, after_sequence: int=0, limit: int=DEFAULT_KNOWLEDGE_LIMIT, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadinessBatchprune_expired (method)
Section titled “prune_expired (method)”async PostgresKnowledgeStore.prune_expired(*, access_scope: KnowledgeAccessScope | None=None, now: datetime | None=None) -> int