rememberstack 0.1.0__py3-none-any.whl

rememberstack/model/auth.py

@@ -0,0 +1,27 @@
+"""Provider-neutral values for the D50/D60 single-deployment auth perimeter."""
+
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import SecretBytes
+
+
+class PerimeterCredential(BaseModel):
+    """Opaque perimeter credential passed to the configured auth adapter."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    scheme: Annotated[str, Field(min_length=1)]
+    value: SecretBytes
+
+
+class AuthenticatedContext(BaseModel):
+    """Authenticated principal inside one deployment-wide trust domain."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    principal: Annotated[str, Field(min_length=1)]

rememberstack/model/blocks.py

@@ -0,0 +1,30 @@
+"""Typed block records — the deterministic identity atoms of a document (D57)."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+class BlockType(StrEnum):
+    """The structural kinds a blockizer emits (e1 §2)."""
+
+    PARAGRAPH = "paragraph"
+    HEADING = "heading"
+    TABLE = "table"
+    LIST_ITEM = "list_item"
+    CODE = "code"
+    QUOTE = "quote"
+
+
+class Block(BaseModel):
+    """One block: a slice of document.md with its deterministic identity hash."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    ordinal: int = Field(ge=0)
+    type: BlockType
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    block_hash: str

rememberstack/model/chunks.py

@@ -0,0 +1,190 @@
+"""E1 chunk-layer values: packing inputs/outputs, catalog records, P1 rows (D58).
+
+Chunks are non-overlapping runs of whole blocks within one section; their
+identity is the ordered block-hash sequence, which is what makes reuse (D56)
+a sequence comparison instead of a semantic judgment.
+"""
+
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from rememberstack.model.queue import UTCDateTime
+
+_NonEmpty = Annotated[str, Field(min_length=1)]
+
+
+class SectionSpan(BaseModel):
+    """One section's block range and signals, as the chunker consumes it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    section_id: UUID
+    node_path: str
+    role: str
+    block_start: int = Field(ge=0)
+    block_end: int = Field(ge=-1)
+
+
+class ChunkSource(BaseModel):
+    """Everything the chunk stage loads about its claimed representation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    representation_id: UUID
+    markdown_uri: str
+    blocks_uri: str
+    title: str | None
+    source_kind: str
+    source_modified_at: UTCDateTime | None
+    published_at: UTCDateTime | None
+    language: str | None
+    structurer_version: str
+    sections: tuple[SectionSpan, ...]
+
+
+class PackedChunk(BaseModel):
+    """One packed run of whole blocks: the chunker's pure output."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    ordinal: int = Field(ge=0)
+    section_id: UUID
+    block_start: int = Field(ge=0)
+    block_end: int = Field(ge=0)
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    chunk_content_hash: _NonEmpty
+    token_count: int = Field(ge=0)
+
+
+class ChunkRecord(BaseModel):
+    """One chunk row for the spine ledger (text and vectors live elsewhere, D37/D8)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    chunk_id: UUID
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    representation_id: UUID
+    section_id: UUID
+    ordinal: int = Field(ge=0)
+    block_start: int = Field(ge=0)
+    block_end: int = Field(ge=0)
+    chunk_content_hash: _NonEmpty
+    extraction_input_hash: _NonEmpty
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    token_count: int = Field(ge=0)
+    chunker_version: _NonEmpty
+
+
+class ChunkForEmbedding(BaseModel):
+    """One chunk row as the embed stage loads it (spans + signals, no body)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    chunk_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    ordinal: int = Field(ge=0)
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    chunk_content_hash: str
+    extraction_input_hash: str
+    section_role: str
+    section_path: str
+    context_prefix: str | None
+    prefixer_version: str | None
+
+
+class CarryForwardSource(BaseModel):
+    """A prior version's chunk whose LLM-derived context is carried forward.
+
+    D56/A3: for an unchanged chunk (same content hash within the lineage) the
+    stored prefix and embedding are REUSED, never regenerated — LLM output is
+    non-deterministic, so regenerating would both pay again and produce
+    different bytes.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    chunk_id: UUID
+    context_prefix: str
+
+
+class EmbeddingUpdate(BaseModel):
+    """The embed stage's write-back onto one chunk row."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    chunk_id: UUID
+    embedding_ref: _NonEmpty
+    embedding_version: _NonEmpty
+    context_prefix: _NonEmpty
+    prefixer_version: _NonEmpty
+
+
+class ContextPrefix(BaseModel):
+    """The structured response of the E1 context-prefix call (D58/D63)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    prefix: _NonEmpty
+
+
+class P1ChunkRow(BaseModel):
+    """One row of the P1 chunk table: text + vector + filter scalars (D8)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    chunk_id: UUID
+    deployment_id: UUID
+    doc_id: UUID
+    version_id: UUID
+    section_role: str
+    text: _NonEmpty
+    vector: Annotated[tuple[float, ...], Field(min_length=1)]
+
+
+class ChunkSourceNotFoundError(Exception):
+    """The chunk stage referenced a representation the spine does not know."""
+
+
+class P1ClaimRow(BaseModel):
+    """One row of the P1 claims channel: the needle index (D8/D58).
+
+    `is_current_testimony` is the scalar the DEFAULT claims channel filters
+    on (retrieval §5): current-testimony-only unless a recipe asks otherwise.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: UUID
+    deployment_id: UUID
+    doc_id: UUID
+    chunk_id: UUID
+    text: Annotated[str, Field(min_length=1)]
+    is_current_testimony: bool
+    is_attributed: bool
+    vector: Annotated[tuple[float, ...], Field(min_length=1)]
+
+
+class P1FactRow(BaseModel):
+    """One row of the P1 facts channel: fact/observation labels (D8)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    fact_id: UUID
+    deployment_id: UUID
+    kind: Annotated[str, Field(min_length=1)]  # relation | observation
+    label: Annotated[str, Field(min_length=1)]
+    status: Annotated[str, Field(min_length=1)]  # active | invalidated
+    vector: Annotated[tuple[float, ...], Field(min_length=1)]

rememberstack/model/claims.py

@@ -0,0 +1,162 @@
+"""E2 claim-extraction values: call responses, grounding, and ledger records (D31-D35)."""
+
+from enum import StrEnum
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+_NonEmpty = Annotated[str, Field(min_length=1)]
+
+
+class SelectionVerdict(StrEnum):
+    """Selection's per-candidate outcome (D31/D35)."""
+
+    KEEP = "keep"
+    KEEP_FLAGGED = "keep_flagged"
+    DROP = "drop"
+
+
+class SelectionCandidate(BaseModel):
+    """One proposition Selection judged inside the target chunk."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    source_span: _NonEmpty
+    verdict: SelectionVerdict
+    drop_reason: str | None = None
+    protected_class: str | None = None
+
+
+class SelectionResponse(BaseModel):
+    """The Selection call's structured output: every judged candidate."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    candidates: tuple[SelectionCandidate, ...]
+
+
+class AddedContext(BaseModel):
+    """One substring decontextualization added, tagged with its bundle source (D32)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    text: _NonEmpty
+    source_kind: _NonEmpty  # header | neighbour | prefix | hint
+    source_ref: str | None = None
+
+
+class CandidateClaim(BaseModel):
+    """One decontextualized, decomposed claim before the deterministic gate."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_text: _NonEmpty
+    source_span: _NonEmpty
+    added_context: tuple[AddedContext, ...] = ()
+    entailment_self_verdict: bool
+    is_attributed: bool = False
+
+
+class ClaimifyResponse(BaseModel):
+    """The fused call's structured output: decontextualize + decompose + ground."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claims: tuple[CandidateClaim, ...]
+
+
+class ClaimRecord(BaseModel):
+    """One accepted claim row: past the deterministic grounding gate (D32)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: UUID
+    deployment_id: UUID
+    doc_id: UUID
+    chunk_id: UUID
+    section_id: UUID | None
+    claim_text: _NonEmpty
+    source_span: _NonEmpty
+    char_start: int = Field(ge=0)
+    char_end: int = Field(ge=0)
+    added_context: tuple[AddedContext, ...]
+    is_attributed: bool
+    entailment_self_verdict: bool
+    kept_flagged: bool
+    extractor_version: _NonEmpty
+
+
+class DecisionType(StrEnum):
+    """The D33 ledger's decision kinds."""
+
+    SELECTION_DROP = "selection_drop"
+    SELECTION_KEEP_FLAGGED = "selection_keep_flagged"
+    DECONTEXT_EDIT = "decontext_edit"
+
+
+class DecisionRecord(BaseModel):
+    """One append-only extraction-transcript row (D33)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    decision_id: UUID
+    deployment_id: UUID
+    doc_id: UUID
+    chunk_id: UUID
+    claim_id: UUID | None
+    decision_type: DecisionType
+    source_span: str | None
+    reason: str | None
+    edit_detail: dict[str, object] | None
+    protected_class: str | None
+    extractor_version: _NonEmpty
+
+
+class ClaimForEmbedding(BaseModel):
+    """One claim row as the claim-embed stage loads it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    claim_id: UUID
+    doc_id: UUID
+    chunk_id: UUID
+    claim_text: _NonEmpty
+    is_current_testimony: bool
+    is_attributed: bool
+
+
+class FactForLabeling(BaseModel):
+    """One relation as the label stage loads it (names resolved for the label)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    relation_id: UUID
+    subject_name: _NonEmpty
+    predicate: _NonEmpty
+    object_name: _NonEmpty
+    status: _NonEmpty
+
+
+class ObservationForEmbedding(BaseModel):
+    """One observation as the label stage loads it (obs_label is the text)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    observation_id: UUID
+    obs_label: _NonEmpty
+    status: _NonEmpty
+
+
+class FactLabelResponse(BaseModel):
+    """The fact-labeler call's structured output: one readable sentence."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    label: _NonEmpty
+
+
+class OtherPredicateGrammarError(Exception):
+    """An other:<freetext> escape value violating the D5 grammar."""

rememberstack/model/client.py

@@ -0,0 +1,98 @@
+"""Client-surface values that are safe in the dependency-light base install."""
+
+from typing import Literal
+from typing import Self
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import JsonValue
+from pydantic import model_validator
+
+_SECRET_CONFIGURATION_KEYS = frozenset(
+    {
+        "accesstoken",
+        "apikey",
+        "credential",
+        "credentials",
+        "password",
+        "refreshtoken",
+        "secret",
+        "token",
+    }
+)
+
+
+class ConnectorNotFoundError(Exception):
+    """A connector id is not present in this deployment."""
+
+
+class ToolDescriptor(BaseModel):
+    """One deployment recipe rendered as a typed SDK/MCP tool."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str
+    description: str
+    input_schema: dict[str, object]
+    output_grain: str
+    answer_intent: str
+
+
+class ConnectorCreate(BaseModel):
+    """Deployment-side connector configuration sent by a client.
+
+    ``credential_ref`` names a secret already held by the deployment. Raw
+    credentials never become client-surface configuration.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    configuration: dict[str, JsonValue] = Field(default_factory=dict)
+    credential_ref: str | None = None
+
+    @model_validator(mode="after")
+    def _credentials_are_references(self) -> Self:
+        """Reject conventional secret fields at any configuration depth."""
+        secret_key = _find_secret_key(self.configuration)
+        if secret_key is not None:
+            raise ValueError(
+                f"configuration field {secret_key!r} looks like a credential;"
+                " store it deployment-side and use credential_ref"
+            )
+        return self
+
+
+class ConnectorDescriptor(BaseModel):
+    """One managed connector, never an instruction to execute it client-side."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    connector_id: UUID
+    kind: str
+    name: str
+    status: Literal["active", "paused", "error"]
+    configuration: dict[str, JsonValue] = Field(default_factory=dict)
+    credential_ref: str | None = None
+    message: str | None = None
+
+
+def _find_secret_key(value: object) -> str | None:
+    """Return the first conventional credential key in nested JSON-like data."""
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            normalized = key.casefold().replace("-", "").replace("_", "")
+            if normalized in _SECRET_CONFIGURATION_KEYS:
+                return key
+            found = _find_secret_key(nested)
+            if found is not None:
+                return found
+    elif isinstance(value, (list, tuple)):
+        for nested in value:
+            found = _find_secret_key(nested)
+            if found is not None:
+                return found
+    return None

rememberstack/model/clustering.py

@@ -0,0 +1,54 @@
+"""Clustering values (D21): config, merge outcomes, and neighborhood reports.
+
+The asymmetry every number serves: over-merging is catastrophic and silent;
+under-merging is gradual and recoverable — so the machinery is paranoid in
+one direction, and every merge is reversible.
+"""
+
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+
+class ClusterConfig(BaseModel):
+    """The decide-stage parameters (starting points to measure, D22).
+
+    `distance_cut` is the HAC cut on cosine DISTANCE (1 - similarity):
+    pieces below the cut are one entity. `blob_cap` is the black-hole
+    guard; `blast_radius_cap` routes big merges to human review (D24).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    distance_cut: Annotated[float, Field(ge=0.0, le=2.0)] = 0.15
+    blob_cap: Annotated[int, Field(ge=2)] = 50
+    blast_radius_cap: Annotated[int, Field(ge=1)] = 100
+
+
+class MergeProposal(BaseModel):
+    """One decide-stage grouping: entities the cut placed in one piece."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    survivor_id: UUID
+    absorbed_ids: tuple[UUID, ...]
+    blast_radius: int = Field(ge=0)
+    mean_distance: float
+
+
+class NeighborhoodReport(BaseModel):
+    """What one neighborhood re-decision did (nDR, registries §6)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    members: int
+    merged: tuple[UUID, ...] = ()  # merge_event ids written
+    queued_for_review: int = 0
+    black_hole_tightened: bool = False
+
+
+class UnmergeError(Exception):
+    """The merge event cannot be reversed (already reversed, or unknown)."""

rememberstack/model/component_version.py

@@ -0,0 +1,124 @@
+"""Typed values and errors for immutable pipeline component versions."""
+
+from collections.abc import Mapping
+from datetime import datetime
+from enum import StrEnum
+import re
+from typing import Annotated
+from typing import Any
+from typing import Self
+from typing import TypeAlias
+from uuid import UUID
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import field_validator
+from pydantic import model_validator
+from pydantic import StringConstraints
+
+NonEmptyStrictString: TypeAlias = Annotated[
+    str, StringConstraints(strict=True, min_length=1)
+]
+
+
+class PipelineComponent(StrEnum):
+    """Exact values of the binding Postgres ``pipeline_component`` enum."""
+
+    INGESTER = "ingester"
+    CONVERTER = "converter"
+    BLOCKIZER = "blockizer"
+    STRUCTURER = "structurer"
+    CROSSREFERENCER = "crossreferencer"
+    CHUNKER = "chunker"
+    CONTEXT_PREFIXER = "context_prefixer"
+    EXTRACTOR = "extractor"
+    GROUNDER = "grounder"
+    RESOLVER = "resolver"
+    NORMALIZER = "normalizer"
+    ADJUDICATOR = "adjudicator"
+    EMBEDDER = "embedder"
+    FACT_LABELER = "fact_labeler"
+    PROFILE_SUMMARIZER = "profile_summarizer"
+    COMMUNITY_DETECTOR = "community_detector"
+    SNAPSHOT_BUILDER = "snapshot_builder"
+    KNOWLEDGE_PLANNER = "knowledge_planner"
+    KNOWLEDGE_WRITER = "knowledge_writer"
+    KNOWLEDGE_REFLECTOR = "knowledge_reflector"
+    KNOWLEDGE_LINTER = "knowledge_linter"
+    JUDGE = "judge"
+    FORGETTER = "forgetter"
+
+
+class RegisterComponentVersionInput(BaseModel):
+    """One explicit immutable pipeline component definition to register."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    component: PipelineComponent
+    version: NonEmptyStrictString
+    model_name: str | None = None
+    prompt_hash: str | None = None
+    embedding_dim: int | None = None
+    params: Mapping[str, Any] = Field(default_factory=dict)
+    notes: str | None = None
+
+    @field_validator("prompt_hash")
+    @classmethod
+    def require_lowercase_sha256(cls, value: str | None) -> str | None:
+        """Require an exact lowercase hexadecimal SHA-256 when one is supplied."""
+        if value is not None and re.fullmatch(r"[0-9a-f]{64}", value) is None:
+            raise ValueError(
+                "prompt_hash must be exactly 64 lowercase hexadecimal characters"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def require_embedder_for_embedding_dimension(self) -> Self:
+        """Allow an embedding dimension only on the embedder component."""
+        if (
+            self.embedding_dim is not None
+            and self.component is not PipelineComponent.EMBEDDER
+        ):
+            raise ValueError("embedding_dim is allowed only for the embedder component")
+        return self
+
+
+class RegisterComponentVersionResult(BaseModel):
+    """Identity and creation disposition for one registration attempt."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    component: PipelineComponent
+    version: str
+    created: bool
+
+
+class ComponentVersionRecord(BaseModel):
+    """A resolved immutable component definition including its database timestamp."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    deployment_id: UUID
+    component: PipelineComponent
+    version: str
+    model_name: str | None
+    prompt_hash: str | None
+    embedding_dim: int | None
+    params: Mapping[str, Any]
+    notes: str | None
+    configured_at: datetime
+
+
+class ComponentVersionError(RuntimeError):
+    """Base class for a known component-version catalog failure."""
+
+
+class ComponentVersionConflictError(ComponentVersionError):
+    """An existing key has a different immutable component definition."""
+
+
+class ComponentVersionNotFoundError(ComponentVersionError):
+    """No component version exists for the requested primary-key triple."""