cayu.storage.PostgresEmbeddingKnowledgeStore
Part of cayu.storage.postgres. Read the Python API overview and install the required extra.
from cayu.storage import PostgresEmbeddingKnowledgeStorePostgres knowledge store with pgvector-backed semantic chunk search.
Bases: PostgresKnowledgeStore.
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)”PostgresEmbeddingKnowledgeStore.__init__(conninfo: str | None=None, *, pool: AsyncConnectionPool | None=None, min_size: int=1, max_size: int=8, schema_mode: schema.SchemaMode=schema.SchemaMode.VALIDATE, embedding_provider: TextEmbeddingProvider, embedding_model: str, embedding_dimensions: int, access_scope: KnowledgeAccessScope | None=None, clock: Callable[[], datetime] | None=None, hybrid_keyword_weight: float=0.35, semantic_min_score: float=0.55) -> Noneensure_schema (method)
Section titled “ensure_schema (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.close() -> Noneinspect_closure_sources (method)
Section titled “inspect_closure_sources (method)”async PostgresEmbeddingKnowledgeStore.inspect_closure_sources(query: KnowledgeClosureQuery) -> dict[str, object]bound_access_scope (method)
Section titled “bound_access_scope (method)”PostgresEmbeddingKnowledgeStore.bound_access_scope() -> KnowledgeAccessScope | NoneReturn the explicitly bound single-principal scope, if configured.
supported_search_modes (method)
Section titled “supported_search_modes (method)”PostgresEmbeddingKnowledgeStore.supported_search_modes() -> tuple[KnowledgeSearchMode, ...]create_entry (method)
Section titled “create_entry (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.load_entry_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgePublicationReceipt | Nonepublish_relations (method)
Section titled “publish_relations (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.load_relation_publication_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationPublicationReceipt | Noneread_relations (method)
Section titled “read_relations (method)”async PostgresEmbeddingKnowledgeStore.read_relations(query: KnowledgeRelationQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeRelationResult | Noneinspect_lineage (method)
Section titled “inspect_lineage (method)”async PostgresEmbeddingKnowledgeStore.inspect_lineage(query: KnowledgeLineageQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeLineageResult | Nonepublish_maintenance_proposal (method)
Section titled “publish_maintenance_proposal (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.load_maintenance_proposal_publication(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposalPublication | Noneapply_maintenance_decision (method)
Section titled “apply_maintenance_decision (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.record_maintenance_governance_route(authority: KnowledgeMaintenanceGovernanceAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceGovernanceReceiptload_maintenance_governance_route (method)
Section titled “load_maintenance_governance_route (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.record_semantic_watch_outcome(authority: KnowledgeSemanticWatchAuthority, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceiptload_semantic_watch_receipt (method)
Section titled “load_semantic_watch_receipt (method)”async PostgresEmbeddingKnowledgeStore.load_semantic_watch_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSemanticWatchReceipt | Noneload_maintenance_proposal (method)
Section titled “load_maintenance_proposal (method)”async PostgresEmbeddingKnowledgeStore.load_maintenance_proposal(proposal_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceProposal | Noneload_maintenance_decision (method)
Section titled “load_maintenance_decision (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.load_maintenance_decision_receipt(operation_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeMaintenanceDecisionReceipt | Noneread_evidence (method)
Section titled “read_evidence (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.search(query: KnowledgeQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeSearchResultlist_entries (method)
Section titled “list_entries (method)”async PostgresEmbeddingKnowledgeStore.list_entries(query: KnowledgeListQuery, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeListResultread_changes (method)
Section titled “read_changes (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.initialize_change_consumer(consumer_id: str, *, baseline_sequence: int, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStateclaim_change (method)
Section titled “claim_change (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.acknowledge_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStaterelease_change (method)
Section titled “release_change (method)”async PostgresEmbeddingKnowledgeStore.release_change(claim: KnowledgeChangeClaim, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerStateload_change_consumer_state (method)
Section titled “load_change_consumer_state (method)”async PostgresEmbeddingKnowledgeStore.load_change_consumer_state(consumer_id: str, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeChangeConsumerState | Nonepublish_index_readiness (method)
Section titled “publish_index_readiness (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.load_index_readiness(identity: KnowledgeEmbeddingIdentity, *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeIndexReadiness | Nonestore_embedding_projections (method)
Section titled “store_embedding_projections (method)”async PostgresEmbeddingKnowledgeStore.store_embedding_projections(projections: list[KnowledgeEmbeddingProjection], *, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEmbeddingProjectionWriteResultPersist vectors only while their exact authorized attempt is pending.
backfill_embeddings (method)
Section titled “backfill_embeddings (method)”async PostgresEmbeddingKnowledgeStore.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) -> KnowledgeEmbeddingBackfillResultEmbed a bounded batch of existing chunks matching knowledge filters.
By default this only fills missing or stale embedding rows. Set
refresh_existing=True to re-embed current rows for the configured
model and dimensions.
read_index_readiness (method)
Section titled “read_index_readiness (method)”async PostgresEmbeddingKnowledgeStore.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 PostgresEmbeddingKnowledgeStore.prune_expired(*, access_scope: KnowledgeAccessScope | None=None, now: datetime | None=None) -> intprocess_embedding_changes (method)
Section titled “process_embedding_changes (method)”async PostgresEmbeddingKnowledgeStore.process_embedding_changes(consumer_id: str, worker_id: str, *, limit: int=DEFAULT_KNOWLEDGE_LIMIT, record_limit: int=DEFAULT_KNOWLEDGE_EMBEDDING_WORK_RECORD_LIMIT, lease_seconds: float=300.0, access_scope: KnowledgeAccessScope | None=None) -> KnowledgeEmbeddingWorkerResultConsume a bounded page of canonical changes into the vector index.