Codex
82e2c91f42
Publish documentation / publish (push) Successful in 1m27s
Add PostgreSQL-backed memory, editable evidence with source review and activation, and human-approved archive repairs across the harness, API, and UI. Include migrations, deployment support, regression coverage, and validation documentation. Refresh permissions from validated session roles so existing administrator logins can access newly deployed archive management features.
114 lines
3.2 KiB
Python
114 lines
3.2 KiB
Python
"""Transport-neutral vector-store contract and canonical vector models."""
|
|
|
|
from dataclasses import dataclass
|
|
from typing import Protocol, runtime_checkable
|
|
|
|
from tht.vectorstore.records import VectorRecord
|
|
from tht.vectorstore.store import VectorHit
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class VectorCapabilities:
|
|
search: bool = True
|
|
existing_hashes: bool = False
|
|
upsert: bool = False
|
|
metadata_filter: bool = False
|
|
delete_generation: bool = False
|
|
list_evidence_generations: bool = False
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class VectorHealth:
|
|
ok: bool
|
|
detail: str | None = None
|
|
read_configured: bool = False
|
|
read_reachable: bool | None = None
|
|
read_detail: str | None = None
|
|
write_configured: bool = False
|
|
write_reachable: bool | None = None
|
|
write_detail: str | None = None
|
|
expected_dimension: int | None = None
|
|
observed_dimensions: tuple[int, ...] = ()
|
|
dimension_compatible: bool | None = None
|
|
bm25_compatible: bool | None = None
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class VectorWriteRecord:
|
|
"""A canonical record plus transport-neutral, precomputed vector data."""
|
|
|
|
record: VectorRecord
|
|
embedding: list[float]
|
|
content_hash: str
|
|
sparse_text: str | None = None
|
|
sparse_language: str | None = None
|
|
|
|
|
|
class VectorStoreError(Exception):
|
|
"""Base error exposed by vector adapters."""
|
|
|
|
|
|
class VectorWriteUnavailable(VectorStoreError):
|
|
"""Raised when a deployment has no vector writer credential."""
|
|
|
|
|
|
class VectorReadUnavailable(VectorStoreError):
|
|
"""Raised when a deployment has no vector reader credential."""
|
|
|
|
|
|
def require_positive_limit(limit: int) -> None:
|
|
"""Reject coercible values: vector limits are exact positive integers."""
|
|
if type(limit) is not int or limit <= 0:
|
|
raise ValueError("Vector search limit must be a positive integer")
|
|
|
|
|
|
@runtime_checkable
|
|
class VectorStore(Protocol):
|
|
@property
|
|
def capabilities(self) -> VectorCapabilities: ...
|
|
|
|
def health(self) -> VectorHealth: ...
|
|
|
|
def search(
|
|
self,
|
|
collections: list[str],
|
|
embedding: list[float],
|
|
*,
|
|
limit: int,
|
|
kinds: list[str] | None = None,
|
|
metadata_filter: dict[str, object] | None = None,
|
|
query_text: str | None = None,
|
|
query_language: str | None = None,
|
|
retrieval_mode: str = "fused",
|
|
) -> list[VectorHit]: ...
|
|
|
|
def existing_hashes(self, collection: str, kinds: list[str]) -> dict[str, str]: ...
|
|
|
|
def upsert(self, collection: str, records: list[VectorWriteRecord]) -> int: ...
|
|
|
|
def delete_kinds(self, collection: str, kinds: list[str]) -> int: ...
|
|
|
|
def prepare_memory_index(self) -> None: ...
|
|
|
|
def delete_memory_records(self, record_keys: list[str]) -> None: ...
|
|
|
|
def delete_generation(self, collection: str, generation: str, workspace_id: str) -> int: ...
|
|
|
|
def list_evidence_generations(self, collection: str, workspace_id: str) -> list[str]: ...
|
|
|
|
def clear_reference(self) -> bool: ...
|
|
|
|
|
|
__all__ = [
|
|
"VectorCapabilities",
|
|
"VectorHealth",
|
|
"VectorHit",
|
|
"VectorReadUnavailable",
|
|
"VectorRecord",
|
|
"VectorStore",
|
|
"VectorStoreError",
|
|
"VectorWriteRecord",
|
|
"VectorWriteUnavailable",
|
|
"require_positive_limit",
|
|
]
|