infinity-context 0.1.0__py3-none-any.whl

infinity_context_core/domain/capture.py

@@ -0,0 +1,321 @@
+"""Canonical auto-memory capture domain.
+
+Captures are immutable evidence envelopes. They are not active memory and they
+do not project directly into graph/vector engines.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from datetime import datetime
+from enum import StrEnum
+from typing import NewType
+
+from infinity_context_core.domain.entities import (
+    DataClassification,
+    MemoryScopeId,
+    SourceRef,
+    SpaceId,
+    ThreadId,
+    TrustLevel,
+)
+from infinity_context_core.domain.errors import MemoryValidationError
+
+MemoryCaptureId = NewType("MemoryCaptureId", str)
+
+MAX_CAPTURE_TEXT_CHARS = 20_000
+MAX_CAPTURE_METADATA_KEYS = 80
+
+
+class CaptureSourceKind(StrEnum):
+    HOOK = "hook"
+    MCP_TOOL = "mcp_tool"
+    TRANSCRIPT_TAIL = "transcript_tail"
+    MANUAL = "manual"
+    TOOL_RESULT = "tool_result"
+    DOCUMENT = "document"
+    IMPORT = "import"
+    COMPACTION = "compaction"
+    SUBAGENT = "subagent"
+
+
+class CaptureActorRole(StrEnum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+    SYSTEM = "system"
+    SUBAGENT = "subagent"
+    UNKNOWN = "unknown"
+
+
+class CaptureStatus(StrEnum):
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    REDACTED = "redacted"
+    PURGED = "purged"
+
+
+class ConsolidationStatus(StrEnum):
+    NOT_REQUIRED = "not_required"
+    PENDING = "pending"
+    RUNNING = "running"
+    CONSOLIDATED = "consolidated"
+    RETRY_PENDING = "retry_pending"
+    DEAD = "dead"
+    SKIPPED = "skipped"
+
+
+class CaptureSensitivity(StrEnum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    SECRET = "secret"
+
+
+class SourceAuthority(StrEnum):
+    EXPLICIT_USER_COMMAND = "explicit_user_command"
+    TOOL_VERIFIED = "tool_verified"
+    REPO_FILE = "repo_file"
+    USER_STATEMENT = "user_statement"
+    DOCUMENT = "document"
+    TRANSCRIPT_INFERENCE = "transcript_inference"
+    ASSISTANT_INFERENCE = "assistant_inference"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class CanonicalCapture:
+    id: MemoryCaptureId
+    space_id: SpaceId
+    memory_scope_id: MemoryScopeId
+    thread_id: ThreadId | None
+    source_agent: str
+    source_kind: CaptureSourceKind
+    event_type: str
+    actor_role: CaptureActorRole
+    text: str
+    evidence_refs: tuple[SourceRef, ...]
+    payload_hash: str
+    idempotency_key: str
+    status: CaptureStatus
+    consolidation_status: ConsolidationStatus
+    trust_level: TrustLevel
+    source_authority: SourceAuthority
+    sensitivity: CaptureSensitivity
+    data_classification: DataClassification
+    occurred_at: datetime
+    received_at: datetime
+    created_at: datetime
+    updated_at: datetime
+    metadata: Mapping[str, object]
+    source_event_id: str | None = None
+    source_actor_external_ref: str | None = None
+    client_instance_id: str | None = None
+    agent_session_external_ref: str | None = None
+    turn_external_ref: str | None = None
+    parent_capture_id: MemoryCaptureId | None = None
+    sequence_index: int | None = None
+    trace_id: str | None = None
+    schema_version: int = 1
+    parser_version: str = "capture-parser-v1"
+    redaction_version: str = "redaction-v1"
+    admission_version: str = "capture-admission-v1"
+    normalization_version: str = "capture-normalization-v1"
+    policy_version: str = "capture-policy-v1"
+    extractor_version: str | None = None
+    extractor_prompt_version: str | None = None
+    resolver_version: str | None = None
+    last_error_code: str | None = None
+    last_error_message: str | None = None
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        capture_id: MemoryCaptureId,
+        space_id: SpaceId,
+        memory_scope_id: MemoryScopeId,
+        thread_id: ThreadId | None,
+        source_agent: str,
+        source_kind: CaptureSourceKind,
+        event_type: str,
+        actor_role: CaptureActorRole,
+        text: str,
+        evidence_refs: tuple[SourceRef, ...],
+        payload_hash: str,
+        idempotency_key: str,
+        trust_level: TrustLevel,
+        source_authority: SourceAuthority,
+        sensitivity: CaptureSensitivity,
+        data_classification: DataClassification,
+        occurred_at: datetime,
+        now: datetime,
+        metadata: Mapping[str, object] | None = None,
+        consolidation_status: ConsolidationStatus = ConsolidationStatus.PENDING,
+        source_event_id: str | None = None,
+        source_actor_external_ref: str | None = None,
+        client_instance_id: str | None = None,
+        agent_session_external_ref: str | None = None,
+        turn_external_ref: str | None = None,
+        parent_capture_id: MemoryCaptureId | None = None,
+        sequence_index: int | None = None,
+        trace_id: str | None = None,
+    ) -> CanonicalCapture:
+        normalized_text = _bounded_text(text)
+        if not source_agent.strip():
+            raise MemoryValidationError("Capture source_agent is required")
+        if not event_type.strip():
+            raise MemoryValidationError("Capture event_type is required")
+        if not payload_hash.strip():
+            raise MemoryValidationError("Capture payload_hash is required")
+        if not idempotency_key.strip():
+            raise MemoryValidationError("Capture idempotency_key is required")
+        if sequence_index is not None and sequence_index < 0:
+            raise MemoryValidationError("Capture sequence_index must be non-negative")
+        safe_metadata = dict(metadata or {})
+        if len(safe_metadata) > MAX_CAPTURE_METADATA_KEYS:
+            raise MemoryValidationError("Capture metadata has too many keys")
+        return cls(
+            id=capture_id,
+            space_id=space_id,
+            memory_scope_id=memory_scope_id,
+            thread_id=thread_id,
+            source_agent=source_agent.strip(),
+            source_kind=source_kind,
+            event_type=event_type.strip(),
+            actor_role=actor_role,
+            text=normalized_text,
+            evidence_refs=evidence_refs,
+            payload_hash=payload_hash.strip(),
+            idempotency_key=idempotency_key.strip(),
+            status=CaptureStatus.ACCEPTED,
+            consolidation_status=consolidation_status,
+            trust_level=trust_level,
+            source_authority=source_authority,
+            sensitivity=sensitivity,
+            data_classification=data_classification,
+            occurred_at=occurred_at,
+            received_at=now,
+            created_at=now,
+            updated_at=now,
+            metadata=safe_metadata,
+            source_event_id=_optional_str(source_event_id),
+            source_actor_external_ref=_optional_str(source_actor_external_ref),
+            client_instance_id=_optional_str(client_instance_id),
+            agent_session_external_ref=_optional_str(agent_session_external_ref),
+            turn_external_ref=_optional_str(turn_external_ref),
+            parent_capture_id=parent_capture_id,
+            sequence_index=sequence_index,
+            trace_id=_optional_str(trace_id),
+        )
+
+    def mark_running(self, *, now: datetime) -> CanonicalCapture:
+        if self.consolidation_status not in {
+            ConsolidationStatus.PENDING,
+            ConsolidationStatus.RETRY_PENDING,
+        }:
+            return self
+        return replace(self, consolidation_status=ConsolidationStatus.RUNNING, updated_at=now)
+
+    def mark_consolidated(
+        self,
+        *,
+        now: datetime,
+        extractor_version: str | None,
+        extractor_prompt_version: str | None,
+        resolver_version: str,
+    ) -> CanonicalCapture:
+        return replace(
+            self,
+            consolidation_status=ConsolidationStatus.CONSOLIDATED,
+            extractor_version=extractor_version,
+            extractor_prompt_version=extractor_prompt_version,
+            resolver_version=resolver_version,
+            last_error_code=None,
+            last_error_message=None,
+            updated_at=now,
+        )
+
+    def mark_skipped(self, *, now: datetime, reason: str) -> CanonicalCapture:
+        return replace(
+            self,
+            consolidation_status=ConsolidationStatus.SKIPPED,
+            last_error_code=reason[:120],
+            last_error_message=None,
+            updated_at=now,
+        )
+
+    def mark_dead(
+        self,
+        *,
+        now: datetime,
+        code: str,
+        message: str | None = None,
+    ) -> CanonicalCapture:
+        return replace(
+            self,
+            consolidation_status=ConsolidationStatus.DEAD,
+            last_error_code=code[:120],
+            last_error_message=(message or "")[:400] or None,
+            updated_at=now,
+        )
+
+    def mark_retry_pending(
+        self,
+        *,
+        now: datetime,
+        code: str,
+        message: str | None = None,
+    ) -> CanonicalCapture:
+        return replace(
+            self,
+            consolidation_status=ConsolidationStatus.RETRY_PENDING,
+            last_error_code=code[:120],
+            last_error_message=(message or "")[:400] or None,
+            updated_at=now,
+        )
+
+    def mark_purged(self, *, now: datetime, reason: str = "privacy_purge") -> CanonicalCapture:
+        return replace(
+            self,
+            text="[purged]",
+            evidence_refs=tuple(_purged_source_ref(ref) for ref in self.evidence_refs),
+            status=CaptureStatus.PURGED,
+            consolidation_status=ConsolidationStatus.NOT_REQUIRED,
+            sensitivity=CaptureSensitivity.SECRET,
+            data_classification=DataClassification.RESTRICTED,
+            metadata={
+                **dict(self.metadata),
+                "privacy_purged_at": now.isoformat(),
+                "privacy_purge_reason": reason[:160],
+            },
+            last_error_code=None,
+            last_error_message=None,
+            updated_at=now,
+        )
+
+
+def _bounded_text(text: str) -> str:
+    stripped = text.strip()
+    if not stripped:
+        raise MemoryValidationError("Capture text is required")
+    if len(stripped) > MAX_CAPTURE_TEXT_CHARS:
+        return stripped[:MAX_CAPTURE_TEXT_CHARS].rstrip()
+    return stripped
+
+
+def _optional_str(value: str | None) -> str | None:
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def _purged_source_ref(ref: SourceRef) -> SourceRef:
+    return replace(
+        ref,
+        char_start=None,
+        char_end=None,
+        quote_preview="[purged]",
+    )

infinity_context_core/domain/distinct_set_membership.py

@@ -0,0 +1,69 @@
+"""Pure bounded reservation policy for distinct-set member evidence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_MAX_MEMBER_IDS_PER_CANDIDATE = 12
+
+
+@dataclass(frozen=True)
+class DistinctSetMemberCandidate:
+    """Provider-neutral evidence contribution from one canonical source family."""
+
+    candidate_id: str
+    source_family: str
+    member_ids: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not self.candidate_id.strip():
+            raise ValueError("distinct-set candidate_id is required")
+        if not self.source_family.strip():
+            raise ValueError("distinct-set source_family is required")
+        if not self.member_ids:
+            raise ValueError("distinct-set member_ids are required")
+        if len(self.member_ids) > _MAX_MEMBER_IDS_PER_CANDIDATE:
+            raise ValueError("distinct-set member_ids exceed bounded maximum")
+        if any(not value.strip() for value in self.member_ids):
+            raise ValueError("distinct-set member_ids cannot be blank")
+        if len(set(self.member_ids)) != len(self.member_ids):
+            raise ValueError("distinct-set member_ids must be unique")
+
+
+@dataclass(frozen=True)
+class DistinctSetMemberReservation:
+    selected_ids: tuple[str, ...]
+    reserved_member_ids: tuple[str, ...]
+
+
+class DistinctSetMemberReservationPolicy:
+    """Reserve source-backed candidates only when they add a target member."""
+
+    def select(
+        self,
+        candidates: tuple[DistinctSetMemberCandidate, ...],
+        *,
+        limit: int,
+    ) -> DistinctSetMemberReservation:
+        if limit <= 0:
+            return DistinctSetMemberReservation((), ())
+        selected: list[str] = []
+        covered_members: set[str] = set()
+        used_sources: set[str] = set()
+        for candidate in candidates:
+            if candidate.source_family in used_sources:
+                continue
+            novel_members = tuple(
+                member_id for member_id in candidate.member_ids if member_id not in covered_members
+            )
+            if not novel_members:
+                continue
+            selected.append(candidate.candidate_id)
+            used_sources.add(candidate.source_family)
+            covered_members.update(novel_members)
+            if len(selected) >= limit:
+                break
+        return DistinctSetMemberReservation(
+            selected_ids=tuple(selected),
+            reserved_member_ids=tuple(sorted(covered_members)),
+        )

infinity_context_core/domain/entities.py

@@ -0,0 +1,103 @@
+"""Core domain entities and value objects.
+
+This module intentionally uses only Python stdlib. Provider SDKs, HTTP frameworks
+and persistence models belong outside infinity_context_core.
+"""
+
+from __future__ import annotations
+
+from infinity_context_core.domain.anchor_entities import MemoryAnchor
+from infinity_context_core.domain.entity_types import (
+    MAX_SOURCE_REFS_PER_ITEM,
+    MAX_SUGGESTION_REVIEW_EVENTS,
+    MAX_SUGGESTION_REVIEW_REASON_CHARS,
+    Confidence,
+    DataClassification,
+    FactRelationType,
+    FactStatus,
+    LifecycleStatus,
+    MemoryAnchorId,
+    MemoryAnchorKind,
+    MemoryChunkId,
+    MemoryChunkKind,
+    MemoryDocumentId,
+    MemoryEpisodeId,
+    MemoryFactId,
+    MemoryFactRelationId,
+    MemoryKind,
+    MemoryScopeId,
+    MemorySourceType,
+    MemorySuggestionId,
+    SpaceId,
+    SpaceMembershipId,
+    SpaceMembershipRole,
+    SpeakerRole,
+    SuggestionOperation,
+    SuggestionStatus,
+    ThreadId,
+    TrustLevel,
+    UserId,
+    UserStatus,
+)
+from infinity_context_core.domain.memory_item_entities import (
+    MemoryChunk,
+    MemoryDocument,
+    MemoryEpisode,
+    MemoryFact,
+    MemoryFactRelation,
+)
+from infinity_context_core.domain.source_refs import SourceRef
+from infinity_context_core.domain.suggestion_entities import MemorySuggestion
+from infinity_context_core.domain.workspace_entities import (
+    MemoryScope,
+    MemorySpace,
+    MemoryThread,
+    SpaceMembership,
+    User,
+)
+
+__all__ = [
+    "SpaceId",
+    "UserId",
+    "SpaceMembershipId",
+    "MemoryScopeId",
+    "ThreadId",
+    "MemoryFactId",
+    "MemoryFactRelationId",
+    "MemoryEpisodeId",
+    "MemoryDocumentId",
+    "MemoryChunkId",
+    "MemorySuggestionId",
+    "MemoryAnchorId",
+    "MAX_SOURCE_REFS_PER_ITEM",
+    "MAX_SUGGESTION_REVIEW_EVENTS",
+    "MAX_SUGGESTION_REVIEW_REASON_CHARS",
+    "FactStatus",
+    "FactRelationType",
+    "LifecycleStatus",
+    "UserStatus",
+    "SpaceMembershipRole",
+    "SuggestionStatus",
+    "SuggestionOperation",
+    "Confidence",
+    "TrustLevel",
+    "DataClassification",
+    "MemoryKind",
+    "MemorySourceType",
+    "MemoryChunkKind",
+    "MemoryAnchorKind",
+    "SpeakerRole",
+    "SourceRef",
+    "MemorySpace",
+    "User",
+    "SpaceMembership",
+    "MemoryScope",
+    "MemoryThread",
+    "MemoryAnchor",
+    "MemoryFact",
+    "MemoryFactRelation",
+    "MemoryEpisode",
+    "MemoryDocument",
+    "MemoryChunk",
+    "MemorySuggestion",
+]

infinity_context_core/domain/entity_policies.py

@@ -0,0 +1,119 @@
+"""Shared domain entity policy helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import datetime
+
+from infinity_context_core.domain.entity_types import (
+    _AUDIT_SECRET_MARKERS,
+    Confidence,
+    DataClassification,
+)
+from infinity_context_core.domain.errors import MemoryValidationError
+
+
+def _max_confidence(current: Confidence, observed: Confidence | None) -> Confidence:
+    if observed is None:
+        return current
+    rank = {
+        Confidence.LOW: 0,
+        Confidence.MEDIUM: 1,
+        Confidence.HIGH: 2,
+    }
+    return observed if rank[observed] > rank[current] else current
+
+def _latest_datetime(current: datetime, observed: datetime | None) -> datetime:
+    if observed is None:
+        return current
+    comparable_current = current
+    comparable_observed = observed
+    if comparable_current.tzinfo is None and comparable_observed.tzinfo is not None:
+        comparable_current = comparable_current.replace(tzinfo=comparable_observed.tzinfo)
+    elif comparable_current.tzinfo is not None and comparable_observed.tzinfo is None:
+        comparable_observed = comparable_observed.replace(tzinfo=comparable_current.tzinfo)
+    return observed if comparable_observed > comparable_current else current
+
+def _merge_temporal_window(
+    *,
+    current_from: datetime | None,
+    current_to: datetime | None,
+    observed_from: datetime | None,
+    observed_to: datetime | None,
+) -> tuple[datetime | None, datetime | None]:
+    if observed_from is None and observed_to is None:
+        return current_from, current_to
+    starts = tuple(item for item in (current_from, observed_from) if item is not None)
+    next_from = min(starts) if starts else None
+    next_to = None if current_to is None or observed_to is None else max(current_to, observed_to)
+    return next_from, next_to
+
+def _optional_str(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+def _unique_strings(values: tuple[str, ...]) -> tuple[str, ...]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        safe = value.strip()
+        if not safe or safe in seen:
+            continue
+        seen.add(safe)
+        result.append(safe)
+        if len(result) >= 50:
+            break
+    return tuple(result)
+
+def _append_anchor_audit(
+    metadata: Mapping[str, object],
+    *,
+    key: str,
+    event: Mapping[str, object],
+    extra: Mapping[str, object] | None = None,
+) -> dict[str, object]:
+    next_metadata = {**dict(metadata), **dict(extra or {})}
+    existing = metadata.get(key)
+    events = list(existing) if isinstance(existing, list) else []
+    events.append(dict(event))
+    next_metadata[key] = events[-20:]
+    return next_metadata
+
+def _safe_audit_text(value: str, *, max_chars: int) -> str:
+    normalized = value.strip()[:max_chars]
+    lowered = normalized.lower()
+    if any(marker in lowered for marker in _AUDIT_SECRET_MARKERS):
+        return "[redacted]"
+    return normalized
+
+def _classification_value(value: str) -> str:
+    try:
+        return DataClassification(value).value
+    except ValueError as exc:
+        raise MemoryValidationError("Unknown data classification") from exc
+
+def _validate_taxonomy(*, tags: tuple[str, ...], ttl_policy: str | None) -> None:
+    if len(tags) > 10:
+        raise MemoryValidationError("Fact tags exceed limit")
+    if any(len(tag) > 48 for tag in tags):
+        raise MemoryValidationError("Fact tag exceeds max length")
+    if ttl_policy is not None and len(ttl_policy) > 80:
+        raise MemoryValidationError("Fact ttl_policy exceeds max length")
+
+def _validate_temporal_range(
+    *,
+    valid_from: datetime | None,
+    valid_to: datetime | None,
+) -> None:
+    if valid_from is None or valid_to is None:
+        return
+    comparable_from = valid_from
+    comparable_to = valid_to
+    if comparable_from.tzinfo is None and comparable_to.tzinfo is not None:
+        comparable_from = comparable_from.replace(tzinfo=comparable_to.tzinfo)
+    elif comparable_from.tzinfo is not None and comparable_to.tzinfo is None:
+        comparable_to = comparable_to.replace(tzinfo=comparable_from.tzinfo)
+    if comparable_to <= comparable_from:
+        raise MemoryValidationError("Temporal valid_to must be after valid_from")