infinity-context 0.1.0__py3-none-any.whl

infinity_context_core/memory_scope_snapshots.py

@@ -0,0 +1,206 @@
+"""Portable memory_scope snapshot manifest helpers.
+
+The manifest is a boundary artifact for backup, git-sync and migration flows.
+It deliberately hashes the canonical JSON snapshot only; derived vector/graph
+indexes remain rebuildable projections and are not part of the portable truth.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+MANIFEST_SCHEMA_VERSION = "infinity_context.memory_scope_snapshot_manifest.v1"
+SNAPSHOT_COUNT_KEYS = (
+    "threads",
+    "facts",
+    "documents",
+    "episodes",
+    "chunks",
+    "assets",
+    "asset_blobs",
+    "asset_extraction_jobs",
+    "extraction_artifacts",
+    "extraction_artifact_blobs",
+    "captures",
+    "anchors",
+    "context_links",
+    "context_link_suggestions",
+    "relations",
+    "source_refs",
+)
+
+
+def default_manifest_path(snapshot_path: Path) -> Path:
+    return snapshot_path.with_name(f"{snapshot_path.name}.manifest.json")
+
+
+def write_snapshot_bundle(
+    *,
+    snapshot: dict[str, Any],
+    snapshot_path: Path,
+    manifest_path: Path | None,
+    space_slug: str,
+    memory_scope_external_ref: str,
+    redacted: bool,
+) -> dict[str, Any] | None:
+    snapshot_path.parent.mkdir(parents=True, exist_ok=True)
+    snapshot_bytes = stable_snapshot_bytes(snapshot)
+    snapshot_path.write_bytes(snapshot_bytes)
+    if manifest_path is None:
+        return None
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest = build_snapshot_manifest(
+        snapshot=snapshot,
+        snapshot_bytes=snapshot_bytes,
+        space_slug=space_slug,
+        memory_scope_external_ref=memory_scope_external_ref,
+        redacted=redacted,
+        snapshot_file=snapshot_path.name,
+    )
+    manifest_path.write_bytes(stable_json_bytes(manifest))
+    return manifest
+
+
+def build_snapshot_manifest(
+    *,
+    snapshot: dict[str, Any],
+    snapshot_bytes: bytes | None = None,
+    space_slug: str,
+    memory_scope_external_ref: str,
+    redacted: bool,
+    snapshot_file: str | None = None,
+) -> dict[str, Any]:
+    payload_bytes = (
+        snapshot_bytes if snapshot_bytes is not None else stable_snapshot_bytes(snapshot)
+    )
+    manifest: dict[str, Any] = {
+        "schema_version": MANIFEST_SCHEMA_VERSION,
+        "created_at": datetime.now(tz=UTC).isoformat(),
+        "snapshot_sha256": hashlib.sha256(payload_bytes).hexdigest(),
+        "snapshot_bytes": len(payload_bytes),
+        "space_slug": space_slug,
+        "memory_scope_external_ref": memory_scope_external_ref,
+        "redacted": redacted,
+        "snapshot_schema_version": snapshot.get("schema_version"),
+        "counts": snapshot_counts(snapshot),
+    }
+    if snapshot_file is not None:
+        manifest["snapshot_file"] = snapshot_file
+    return manifest
+
+
+def verify_snapshot_manifest(
+    *,
+    snapshot_path: Path,
+    manifest_path: Path,
+) -> dict[str, Any]:
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "ok": False,
+            "errors": [f"manifest_unreadable:{exc.__class__.__name__}"],
+        }
+    if not isinstance(manifest, dict):
+        return {"ok": False, "errors": ["manifest_not_object"]}
+    try:
+        snapshot_bytes = snapshot_path.read_bytes()
+    except OSError as exc:
+        return {
+            "ok": False,
+            "errors": [f"snapshot_unreadable:{exc.__class__.__name__}"],
+            "manifest": manifest,
+        }
+    return verify_snapshot_manifest_payload(
+        snapshot_bytes=snapshot_bytes,
+        manifest=manifest,
+        expected_snapshot_file=snapshot_path.name,
+    )
+
+
+def verify_snapshot_manifest_payload(
+    *,
+    snapshot: dict[str, Any] | None = None,
+    snapshot_bytes: bytes | None = None,
+    manifest: dict[str, Any],
+    expected_snapshot_file: str | None = None,
+) -> dict[str, Any]:
+    errors: list[str] = []
+    if manifest.get("schema_version") != MANIFEST_SCHEMA_VERSION:
+        errors.append("unsupported_manifest_schema")
+    if (
+        expected_snapshot_file is not None
+        and manifest.get("snapshot_file") is not None
+        and manifest.get("snapshot_file") != expected_snapshot_file
+    ):
+        errors.append("snapshot_file_mismatch")
+    payload_bytes = snapshot_bytes
+    if payload_bytes is None:
+        if snapshot is None:
+            errors.append("snapshot_missing")
+            payload_bytes = b""
+        else:
+            payload_bytes = stable_snapshot_bytes(snapshot)
+    actual_sha256 = hashlib.sha256(payload_bytes).hexdigest()
+    expected_sha256 = str(manifest.get("snapshot_sha256") or "")
+    if expected_sha256 != actual_sha256:
+        errors.append("snapshot_sha256_mismatch")
+    expected_size = manifest.get("snapshot_bytes")
+    if isinstance(expected_size, int) and expected_size != len(payload_bytes):
+        errors.append("snapshot_size_mismatch")
+    if snapshot is not None:
+        errors.extend(_snapshot_manifest_contract_errors(snapshot=snapshot, manifest=manifest))
+    return {
+        "ok": not errors,
+        "errors": errors,
+        "expected_sha256": expected_sha256,
+        "actual_sha256": actual_sha256,
+        "snapshot_bytes": len(payload_bytes),
+        "manifest": manifest,
+    }
+
+
+def stable_snapshot_bytes(payload: dict[str, Any]) -> bytes:
+    return stable_json_bytes(payload)
+
+
+def stable_json_bytes(payload: dict[str, Any]) -> bytes:
+    return (json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode(
+        "utf-8"
+    )
+
+
+def snapshot_counts(snapshot: dict[str, Any]) -> dict[str, int]:
+    return {key: _list_count(snapshot.get(key)) for key in SNAPSHOT_COUNT_KEYS}
+
+
+def _snapshot_manifest_contract_errors(
+    *,
+    snapshot: dict[str, Any],
+    manifest: dict[str, Any],
+) -> list[str]:
+    errors: list[str] = []
+    manifest_schema_version = manifest.get("snapshot_schema_version")
+    if manifest_schema_version is not None and manifest_schema_version != snapshot.get(
+        "schema_version"
+    ):
+        errors.append("snapshot_schema_version_mismatch")
+    manifest_redacted = manifest.get("redacted")
+    if manifest_redacted is not None and manifest_redacted != bool(snapshot.get("redacted")):
+        errors.append("redacted_mismatch")
+    manifest_counts = manifest.get("counts")
+    if not isinstance(manifest_counts, dict):
+        errors.append("counts_missing")
+        return errors
+    for key, actual_count in snapshot_counts(snapshot).items():
+        if manifest_counts.get(key) != actual_count:
+            errors.append(f"count_mismatch:{key}")
+    return errors
+
+
+def _list_count(value: object) -> int:
+    return len(value) if isinstance(value, list) else 0

infinity_context_core/ports/__init__.py

@@ -0,0 +1,164 @@
+"""Ports exposed by infinity_context_core."""
+
+from infinity_context_core.ports.adapters import (
+    AdapterCapabilities,
+    GraphCandidate,
+    GraphSearchResult,
+    MemoryAdapterPort,
+    PortDiagnostic,
+    PortStatus,
+    VectorCandidate,
+    VectorSearchResult,
+)
+from infinity_context_core.ports.auth import AuthPort, MemoryUser, MemoryWriteScope, ReadScope
+from infinity_context_core.ports.auto_memory import (
+    ALLOWED_TTL_POLICIES,
+    FactExtractionPort,
+    MemoryCandidate,
+    MemoryClassifierPort,
+    MemoryExtractorPort,
+    SourceProvenance,
+)
+from infinity_context_core.ports.benchmark_runs import (
+    BenchmarkCleanupCounts,
+    BenchmarkCleanupReceipt,
+    BenchmarkRunRegistryRecord,
+    BenchmarkRunRepositoryPort,
+    BenchmarkRunState,
+    ProjectionCleanupState,
+    is_managed_benchmark_space_id,
+)
+from infinity_context_core.ports.capabilities import (
+    CapabilityDescriptor,
+    CapabilityDiagnostic,
+    CapabilityMode,
+    CapabilityRecallCandidate,
+    CapabilityRecallQuery,
+    CapabilityRecallResult,
+    CapabilityStatus,
+    ConsistencyMode,
+    DocumentMemoryPort,
+    DocumentMemoryWrite,
+    EngineHealthPort,
+    EngineHealthSnapshot,
+    FactProjectionPort,
+    FactProjectionWrite,
+    MemoryCapability,
+    MemoryScopeFilter,
+    ProjectionForgetPort,
+    ProjectionForgetRequest,
+    ProjectionForgetResult,
+    ProjectionFreshness,
+    ProjectionWriteResult,
+    RagRecallPort,
+    SessionMemoryPort,
+    TemporalFactGraphPort,
+    VectorRecallPort,
+)
+from infinity_context_core.ports.clock import ClockPort
+from infinity_context_core.ports.derived_projection_policy import (
+    DERIVED_NOT_PROJECTED_POLICY_SCHEMA_VERSION,
+    DerivedProjectionLaneDisposition,
+    DerivedProjectionLanePolicyError,
+    derived_not_projected_policy_sha256,
+)
+from infinity_context_core.ports.extraction import (
+    AssetExtractionRepositoryPort,
+    ContentExtractionPort,
+    ExtractedElement,
+    ExtractionArtifactCandidate,
+    ExtractionLimits,
+    ExtractionRequest,
+    ExtractionResult,
+    FileTypeDetectionRequest,
+    FileTypeDetectionResult,
+    FileTypeDetectorPort,
+)
+from infinity_context_core.ports.ids import IdGeneratorPort
+from infinity_context_core.ports.projection_fence import (
+    ProjectionFencePermit,
+    ProjectionFencePort,
+)
+from infinity_context_core.ports.transcription import (
+    SpeechTranscriptionPort,
+    SpeechTranscriptionRequest,
+    SpeechTranscriptionResult,
+    SpeechTranscriptSegment,
+)
+from infinity_context_core.ports.usage import UsageRepositoryPort
+
+__all__ = [
+    "AdapterCapabilities",
+    "ALLOWED_TTL_POLICIES",
+    "AuthPort",
+    "BenchmarkCleanupCounts",
+    "BenchmarkCleanupReceipt",
+    "BenchmarkRunRegistryRecord",
+    "BenchmarkRunRepositoryPort",
+    "BenchmarkRunState",
+    "AssetExtractionRepositoryPort",
+    "CapabilityDescriptor",
+    "CapabilityDiagnostic",
+    "CapabilityMode",
+    "CapabilityRecallCandidate",
+    "CapabilityRecallQuery",
+    "CapabilityRecallResult",
+    "CapabilityStatus",
+    "ClockPort",
+    "ConsistencyMode",
+    "ContentExtractionPort",
+    "DocumentMemoryPort",
+    "DocumentMemoryWrite",
+    "DERIVED_NOT_PROJECTED_POLICY_SCHEMA_VERSION",
+    "DerivedProjectionLaneDisposition",
+    "DerivedProjectionLanePolicyError",
+    "derived_not_projected_policy_sha256",
+    "EngineHealthPort",
+    "EngineHealthSnapshot",
+    "ExtractedElement",
+    "ExtractionArtifactCandidate",
+    "ExtractionLimits",
+    "ExtractionRequest",
+    "ExtractionResult",
+    "FactExtractionPort",
+    "FactProjectionPort",
+    "FactProjectionWrite",
+    "FileTypeDetectionRequest",
+    "FileTypeDetectionResult",
+    "FileTypeDetectorPort",
+    "GraphCandidate",
+    "GraphSearchResult",
+    "IdGeneratorPort",
+    "MemoryAdapterPort",
+    "MemoryCandidate",
+    "MemoryCapability",
+    "MemoryClassifierPort",
+    "MemoryExtractorPort",
+    "MemoryUser",
+    "MemoryWriteScope",
+    "MemoryScopeFilter",
+    "PortDiagnostic",
+    "PortStatus",
+    "ProjectionFencePermit",
+    "ProjectionFencePort",
+    "ProjectionCleanupState",
+    "is_managed_benchmark_space_id",
+    "ProjectionForgetPort",
+    "ProjectionForgetRequest",
+    "ProjectionForgetResult",
+    "ProjectionFreshness",
+    "ProjectionWriteResult",
+    "RagRecallPort",
+    "ReadScope",
+    "SessionMemoryPort",
+    "SpeechTranscriptSegment",
+    "SpeechTranscriptionPort",
+    "SpeechTranscriptionRequest",
+    "SpeechTranscriptionResult",
+    "SourceProvenance",
+    "TemporalFactGraphPort",
+    "UsageRepositoryPort",
+    "VectorCandidate",
+    "VectorRecallPort",
+    "VectorSearchResult",
+]

infinity_context_core/ports/adapters.py

@@ -0,0 +1,217 @@
+"""Provider adapter ports and adapter result DTOs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Protocol
+
+
+class PortStatus(StrEnum):
+    OK = "ok"
+    DEGRADED = "degraded"
+    UNAVAILABLE = "unavailable"
+
+
+@dataclass(frozen=True)
+class PortDiagnostic:
+    code: str
+    safe_message: str
+    retryable: bool
+    details: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AdapterCapabilities:
+    name: str
+    enabled: bool
+    healthy: bool
+    supports_upsert: bool
+    supports_delete: bool
+    supports_search: bool
+    supports_filters: bool
+    supports_temporal_queries: bool = False
+    degraded_reason: str | None = None
+
+
+class MemoryAdapterPort(Protocol):
+    async def capabilities(self) -> AdapterCapabilities:
+        """Return safe adapter capability metadata."""
+
+
+@dataclass(frozen=True)
+class EmbeddingResult:
+    status: PortStatus
+    vectors: tuple[tuple[float, ...], ...]
+    model: str | None = None
+    dimensions: int | None = None
+    diagnostics: tuple[PortDiagnostic, ...] = ()
+
+    @classmethod
+    def degraded(cls, code: str, retryable: bool = True) -> EmbeddingResult:
+        return cls(
+            status=PortStatus.DEGRADED,
+            vectors=(),
+            diagnostics=(
+                PortDiagnostic(
+                    code=code,
+                    safe_message="Embedding generation degraded",
+                    retryable=retryable,
+                ),
+            ),
+        )
+
+
+class EmbeddingPort(MemoryAdapterPort, Protocol):
+    async def embed_texts(self, texts: tuple[str, ...]) -> EmbeddingResult:
+        """Return embeddings for query or chunk texts."""
+
+
+@dataclass(frozen=True)
+class VectorCandidate:
+    chunk_id: str
+    space_id: str
+    memory_scope_id: str
+    score: float
+    projection_version: str
+    preview: str | None = None
+
+
+@dataclass(frozen=True)
+class GraphCandidate:
+    source_fact_ids: tuple[str, ...]
+    source_chunk_ids: tuple[str, ...]
+    relation_label: str
+    score: float
+    diagnostics: dict[str, str]
+
+
+@dataclass(frozen=True)
+class VectorSearchResult:
+    status: PortStatus
+    items: tuple[VectorCandidate, ...]
+    diagnostics: tuple[PortDiagnostic, ...] = ()
+
+    @classmethod
+    def ok(cls, items: list[VectorCandidate]) -> VectorSearchResult:
+        return cls(status=PortStatus.OK, items=tuple(items))
+
+    @classmethod
+    def degraded(cls, code: str, retryable: bool = True) -> VectorSearchResult:
+        return cls(
+            status=PortStatus.DEGRADED,
+            items=(),
+            diagnostics=(
+                PortDiagnostic(
+                    code=code,
+                    safe_message="Vector retrieval degraded",
+                    retryable=retryable,
+                ),
+            ),
+        )
+
+
+@dataclass(frozen=True)
+class VectorUpsertItem:
+    chunk_id: str
+    space_id: str
+    memory_scope_id: str
+    thread_id: str | None
+    text: str
+    vector: tuple[float, ...]
+    projection_version: str
+    metadata: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class VectorWriteResult:
+    status: PortStatus
+    affected_count: int
+    diagnostics: tuple[PortDiagnostic, ...] = ()
+
+    @classmethod
+    def ok(cls, affected_count: int) -> VectorWriteResult:
+        return cls(status=PortStatus.OK, affected_count=affected_count)
+
+    @classmethod
+    def degraded(cls, code: str, retryable: bool = True) -> VectorWriteResult:
+        return cls(
+            status=PortStatus.DEGRADED,
+            affected_count=0,
+            diagnostics=(
+                PortDiagnostic(
+                    code=code,
+                    safe_message="Vector write degraded",
+                    retryable=retryable,
+                ),
+            ),
+        )
+
+
+class VectorMemoryPort(MemoryAdapterPort, Protocol):
+    async def upsert_chunks(self, items: tuple[VectorUpsertItem, ...]) -> VectorWriteResult:
+        """Upsert derived chunk vectors. Never owns canonical lifecycle."""
+
+    async def delete_chunks(self, chunk_ids: tuple[str, ...]) -> VectorWriteResult:
+        """Delete derived chunk vectors by canonical chunk ids."""
+
+    async def search_chunks(
+        self,
+        *,
+        space_id: str,
+        memory_scope_ids: tuple[str, ...],
+        thread_id: str | None = None,
+        query_vector: tuple[float, ...],
+        query_text: str | None = None,
+        limit: int,
+    ) -> VectorSearchResult:
+        """Search derived vector candidates."""
+
+
+@dataclass(frozen=True)
+class GraphSearchResult:
+    status: PortStatus
+    items: tuple[GraphCandidate, ...]
+    diagnostics: tuple[PortDiagnostic, ...] = ()
+
+    @classmethod
+    def ok(cls, items: list[GraphCandidate]) -> GraphSearchResult:
+        return cls(status=PortStatus.OK, items=tuple(items))
+
+    @classmethod
+    def degraded(cls, code: str, retryable: bool = True) -> GraphSearchResult:
+        return cls(
+            status=PortStatus.DEGRADED,
+            items=(),
+            diagnostics=(
+                PortDiagnostic(
+                    code=code,
+                    safe_message="Graph retrieval degraded",
+                    retryable=retryable,
+                ),
+            ),
+        )
+
+
+class GraphMemoryPort(MemoryAdapterPort, Protocol):
+    async def upsert_fact(
+        self,
+        fact_id: str,
+        text: str,
+        metadata: dict[str, str],
+    ) -> VectorWriteResult:
+        """Upsert a fact-derived graph node or episode. Derived only."""
+
+    async def delete_fact(self, fact_id: str) -> VectorWriteResult:
+        """Delete or tombstone a fact-derived graph projection."""
+
+    async def search(
+        self,
+        *,
+        space_id: str,
+        memory_scope_ids: tuple[str, ...],
+        thread_id: str | None = None,
+        query: str,
+        limit: int,
+    ) -> GraphSearchResult:
+        """Search graph candidates that must be hydrated through Postgres."""