galet-memory 0.1.0__py3-none-any.whl

galet_memory/__init__.py

@@ -0,0 +1,94 @@
+"""Provider-neutral memory abstractions and implementations."""
+
+from .episodic import (
+    EmbeddingDigestRecall,
+    EventScope,
+    EpisodicCurationRequest,
+    EpisodicCurationResult,
+    EpisodicConcurrencyError,
+    EpisodicDigest,
+    EpisodicEvent,
+    EpisodicMemory,
+    EpisodicMemoryManager,
+    EpisodicMemoryRequest,
+    EpisodicMemoryResult,
+    EpisodicSession,
+    EpisodicSessionQuery,
+    EpisodicCompatibilityError,
+    SqliteEpisodicMemory,
+)
+from .curation import (
+    CurationConflictError,
+    CurationError,
+    CurationResult,
+    CurationService,
+    CurationSessionNotFoundError,
+    CurationStorageError,
+    DigestGenerationError,
+    DigestGenerationRequest,
+    DigestGenerator,
+)
+from .procedural import (
+    ContextProceduralMemory,
+    ProceduralMemory,
+    ProceduralMemoryRequest,
+    ProceduralMemoryResult,
+    ProceduralSkill,
+)
+from .semantic import (
+    SemanticDocument,
+    SemanticMemory,
+    SemanticMemoryRequest,
+    SemanticMemoryResult,
+    VectorSemanticMemory,
+)
+from .ports import (
+    CachingEmbeddingProvider,
+    EmbeddingCache,
+    EmbeddingCacheInfo,
+    EmbeddingCacheKey,
+)
+
+__version__ = "0.1.0.dev0"
+
+__all__ = [
+    "CachingEmbeddingProvider",
+    "ContextProceduralMemory",
+    "CurationConflictError",
+    "CurationError",
+    "CurationResult",
+    "CurationService",
+    "CurationSessionNotFoundError",
+    "CurationStorageError",
+    "DigestGenerationError",
+    "DigestGenerationRequest",
+    "DigestGenerator",
+    "EmbeddingDigestRecall",
+    "EmbeddingCache",
+    "EmbeddingCacheInfo",
+    "EmbeddingCacheKey",
+    "EventScope",
+    "EpisodicCurationRequest",
+    "EpisodicCurationResult",
+    "EpisodicConcurrencyError",
+    "EpisodicDigest",
+    "EpisodicEvent",
+    "EpisodicMemory",
+    "EpisodicMemoryManager",
+    "EpisodicMemoryRequest",
+    "EpisodicMemoryResult",
+    "EpisodicSession",
+    "EpisodicSessionQuery",
+    "EpisodicCompatibilityError",
+    "SqliteEpisodicMemory",
+    "ProceduralMemory",
+    "ProceduralMemoryRequest",
+    "ProceduralMemoryResult",
+    "ProceduralSkill",
+    "SemanticDocument",
+    "SemanticMemory",
+    "SemanticMemoryRequest",
+    "SemanticMemoryResult",
+    "VectorSemanticMemory",
+    "__version__",
+]

galet_memory/curation.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional, Protocol, Sequence, runtime_checkable
+from uuid import uuid4
+
+from .episodic import EpisodicEvent, EpisodicMemoryManager, EpisodicSession
+from .episodic.management import EpisodicConcurrencyError
+
+
+class CurationError(RuntimeError):
+    """Base class for neutral curation failures."""
+
+
+class CurationSessionNotFoundError(CurationError):
+    """The session is missing or is not owned by the requested account."""
+
+
+class DigestGenerationError(CurationError):
+    """The digest generator failed or returned no usable text."""
+
+
+class CurationConflictError(CurationError):
+    """The session changed after the digest snapshot was taken."""
+
+
+class CurationStorageError(CurationError):
+    """The episodic store failed outside a recognised conflict."""
+
+
+@dataclass(frozen=True)
+class DigestGenerationRequest:
+    session_id: str
+    account_name: str
+    agent_name: str
+    friendly_name: str
+    events: Sequence[EpisodicEvent]
+    max_chars: int = 32000
+
+
+@runtime_checkable
+class DigestGenerator(Protocol):
+    def generate(self, request: DigestGenerationRequest) -> str:
+        """Return digest text without changing storage."""
+        ...
+
+
+@dataclass(frozen=True)
+class CurationResult:
+    action: Literal["digest", "archive"]
+    session_id: str
+    digest: str
+    boundary_event: Optional[EpisodicEvent] = None
+    idempotency_key: str = ""
+
+
+class CurationService:
+    """Generate digests and establish non-destructive archive boundaries."""
+
+    def __init__(
+        self,
+        episodic_store: EpisodicMemoryManager,
+        digest_generator: DigestGenerator,
+    ) -> None:
+        self.episodic_store = episodic_store
+        self.digest_generator = digest_generator
+
+    def produce_digest(
+        self,
+        *,
+        account_name: str,
+        session_id: str,
+        max_chars: int = 32000,
+    ) -> CurationResult:
+        session = self._load_owned_active_session(account_name, session_id)
+        digest = self._generate(session, max_chars=max_chars)
+        return CurationResult(
+            action="digest",
+            session_id=session.session_id,
+            digest=digest,
+        )
+
+    def archive(
+        self,
+        *,
+        account_name: str,
+        session_id: str,
+        max_chars: int = 32000,
+        idempotency_key: Optional[str] = None,
+    ) -> CurationResult:
+        operation_key = idempotency_key or str(uuid4())
+        session = self._load_owned_active_session(account_name, session_id)
+        existing = self._find_idempotent_boundary(
+            account_name, session_id, operation_key
+        )
+        if existing is not None:
+            return self._archive_result(session_id, existing, operation_key)
+
+        expected_tail = session.events[-1].event_id if session.events else None
+        digest = self._generate(session, max_chars=max_chars)
+        boundary = EpisodicEvent(
+            role="system",
+            actor="curation",
+            kind="session_digest",
+            content=digest,
+            metadata={
+                "visibility_boundary": True,
+                "curation_version": 1,
+                "idempotency_key": operation_key,
+            },
+        )
+        try:
+            stored = self.episodic_store.append_event_if_tail(
+                session_id,
+                boundary,
+                expected_last_event_id=expected_tail,
+            )
+        except EpisodicConcurrencyError as exc:
+            existing = self._find_idempotent_boundary(
+                account_name, session_id, operation_key
+            )
+            if existing is not None:
+                return self._archive_result(session_id, existing, operation_key)
+            raise CurationConflictError(str(exc)) from exc
+        except Exception as exc:
+            raise CurationStorageError(
+                f"failed to append digest boundary for session {session_id}"
+            ) from exc
+        return self._archive_result(session_id, stored, operation_key)
+
+    def _load_owned_active_session(
+        self, account_name: str, session_id: str
+    ) -> EpisodicSession:
+        try:
+            session = self.episodic_store.get_session(
+                session_id, include_events=True, event_scope="active"
+            )
+        except Exception as exc:
+            raise CurationStorageError(
+                f"failed to load session {session_id}"
+            ) from exc
+        if session is None or session.account_name != account_name:
+            raise CurationSessionNotFoundError(
+                f"session not found for account: {session_id}"
+            )
+        return session
+
+    def _generate(self, session: EpisodicSession, *, max_chars: int) -> str:
+        if max_chars <= 0:
+            raise ValueError("max_chars must be greater than zero")
+        request = DigestGenerationRequest(
+            session_id=session.session_id,
+            account_name=session.account_name,
+            agent_name=session.agent_name,
+            friendly_name=session.friendly_name or "",
+            events=tuple(session.events),
+            max_chars=max_chars,
+        )
+        try:
+            digest = self.digest_generator.generate(request)
+        except Exception as exc:
+            raise DigestGenerationError("digest generation failed") from exc
+        if not isinstance(digest, str) or not digest.strip():
+            raise DigestGenerationError("digest generator returned empty text")
+        return digest.strip()
+
+    def _find_idempotent_boundary(
+        self, account_name: str, session_id: str, idempotency_key: str
+    ) -> Optional[EpisodicEvent]:
+        try:
+            session = self.episodic_store.get_session(
+                session_id, include_events=True, event_scope="all"
+            )
+        except Exception as exc:
+            raise CurationStorageError(
+                f"failed to inspect session {session_id}"
+            ) from exc
+        if session is None or session.account_name != account_name:
+            raise CurationSessionNotFoundError(
+                f"session not found for account: {session_id}"
+            )
+        for event in reversed(session.events):
+            if (
+                event.kind == "session_digest"
+                and event.metadata.get("visibility_boundary") is True
+                and event.metadata.get("idempotency_key") == idempotency_key
+            ):
+                return event
+        return None
+
+    @staticmethod
+    def _archive_result(
+        session_id: str,
+        boundary: EpisodicEvent,
+        idempotency_key: str,
+    ) -> CurationResult:
+        return CurationResult(
+            action="archive",
+            session_id=session_id,
+            digest=str(boundary.content),
+            boundary_event=boundary,
+            idempotency_key=idempotency_key,
+        )
+
+
+__all__ = [
+    "CurationConflictError",
+    "CurationError",
+    "CurationResult",
+    "CurationService",
+    "CurationSessionNotFoundError",
+    "CurationStorageError",
+    "DigestGenerationError",
+    "DigestGenerationRequest",
+    "DigestGenerator",
+]

galet_memory/episodic/__init__.py

@@ -0,0 +1,36 @@
+from .interface import (
+    EpisodicDigest,
+    EpisodicEvent,
+    EpisodicMemory,
+    EpisodicMemoryRequest,
+    EpisodicMemoryResult,
+)
+from .management import (
+    EventScope,
+    EpisodicCurationRequest,
+    EpisodicCurationResult,
+    EpisodicConcurrencyError,
+    EpisodicMemoryManager,
+    EpisodicSession,
+    EpisodicSessionQuery,
+)
+from .embedding_digest_recall import EmbeddingDigestRecall
+from .sqlite import EpisodicCompatibilityError, SqliteEpisodicMemory
+
+__all__ = [
+    "EventScope",
+    "EpisodicCurationRequest",
+    "EpisodicCurationResult",
+    "EpisodicConcurrencyError",
+    "EpisodicDigest",
+    "EmbeddingDigestRecall",
+    "EpisodicEvent",
+    "EpisodicMemory",
+    "EpisodicMemoryManager",
+    "EpisodicMemoryRequest",
+    "EpisodicMemoryResult",
+    "EpisodicSession",
+    "EpisodicSessionQuery",
+    "EpisodicCompatibilityError",
+    "SqliteEpisodicMemory",
+]

galet_memory/episodic/embedding_digest_recall.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import logging
+
+from .interface import EpisodicDigest, EpisodicMemoryRequest
+from ..ports import EmbeddingIndex, EmbeddingProvider, TextLoader
+
+
+class EmbeddingDigestRecall:
+    def __init__(
+        self,
+        *,
+        embeddings: EmbeddingProvider,
+        index: EmbeddingIndex,
+        text_loader: TextLoader,
+        namespaces: list[str] | None = None,
+        score_threshold: float = 0.25,
+        embedding_model: str = "text-embedding-3-small",
+    ) -> None:
+        self.embeddings = embeddings
+        self.index = index
+        self.text_loader = text_loader
+        self.namespaces = list(namespaces or ["digests"])
+        self.score_threshold = score_threshold
+        self.embedding_model = embedding_model
+
+    def __call__(self, request: EpisodicMemoryRequest) -> list[EpisodicDigest]:
+        query = request.query.strip()
+        if not query:
+            return []
+        try:
+            vector = self.embeddings.embed(
+                [query], model=self.embedding_model
+            )[0]
+            matches = self.index.query(
+                account_name=request.account_name,
+                namespaces=self.namespaces,
+                vector=vector,
+                limit=request.digest_top_k,
+            )
+            digests: list[EpisodicDigest] = []
+            for match in matches:
+                if match.score < self.score_threshold:
+                    continue
+                metadata = dict(match.record.metadata)
+                path = metadata.get("path")
+                if not path:
+                    continue
+                snippet = self.text_loader.load(
+                    path, max_chars=request.digest_max_chars
+                )
+                if not snippet.text.strip():
+                    continue
+                digests.append(
+                    EpisodicDigest(
+                        session_id=match.record.source_id,
+                        snippet=snippet.text,
+                        score=float(match.score),
+                        truncated=snippet.truncated,
+                        metadata={
+                            **metadata,
+                            "namespace": "digests",
+                            "embedding_model": self.embedding_model,
+                        },
+                    )
+                )
+            return digests
+        except Exception as exc:
+            logging.warning(
+                "EmbeddingDigestRecall: failed for account=%s: %s",
+                request.account_name,
+                exc,
+            )
+            return []

galet_memory/episodic/interface.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class EpisodicMemoryRequest:
+    """Request for conversational or experiential memory."""
+
+    account_name: str
+    agent_name: str
+    conversation_id: str = ""
+    query: str = ""
+    max_events: int = 6
+    token_budget: Optional[int] = None
+    digest_top_k: int = 3
+    digest_max_chars: int = 3000
+    event_kinds: Optional[List[str]] = None
+    include_session_metadata: bool = True
+    include_recent_history: bool = True
+    include_archived_digests: bool = True
+
+
+@dataclass(frozen=True)
+class EpisodicEvent:
+    """Provider-neutral representation of a stored event."""
+
+    role: str
+    content: Any
+    kind: str = ""
+    actor: str = ""
+    event_id: str = ""
+    created_at: Optional[datetime] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class EpisodicDigest:
+    session_id: str
+    snippet: str
+    score: float = 0.0
+    truncated: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EpisodicMemoryResult:
+    session_id: str = ""
+    session_user_id: str = ""
+    session_account_name: str = ""
+    session_agent_name: str = ""
+    session_context_name: str = ""
+    session_type: str = ""
+    session_participants: List[str] = field(default_factory=list)
+    session_friendly_name: str = ""
+    session_tags: List[str] = field(default_factory=list)
+    session_updated_at: Optional[datetime] = None
+    events: List[EpisodicEvent] = field(default_factory=list)
+    digests: List[EpisodicDigest] = field(default_factory=list)
+    dropped_event_count: int = 0
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class EpisodicMemory(ABC):
+    """Prompt-time access to current and archived episodic memory."""
+
+    @abstractmethod
+    def recall(self, request: EpisodicMemoryRequest) -> EpisodicMemoryResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def save_overflow_digest(
+        self,
+        *,
+        account_name: str,
+        conversation_id: str,
+        snippet: str,
+    ) -> Optional[str]:
+        raise NotImplementedError

galet_memory/episodic/management.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional
+
+from .interface import EpisodicEvent
+
+
+EventScope = Literal["active", "all", "archived"]
+
+
+class EpisodicConcurrencyError(RuntimeError):
+    """Raised when a conditional write observes a different event tail."""
+
+
+@dataclass(frozen=True)
+class EpisodicSessionQuery:
+    account_name: str
+    agent_name: str = ""
+    query: str = ""
+    limit: int = 20
+
+
+@dataclass(frozen=True)
+class EpisodicSession:
+    session_id: str
+    account_name: str
+    agent_name: str
+    user_id: str = ""
+    friendly_name: Optional[str] = None
+    context_name: Optional[str] = None
+    session_type: str = "user"
+    participants: List[str] = field(default_factory=list)
+    links: Dict[str, Any] = field(default_factory=dict)
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    events: List[EpisodicEvent] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class EpisodicCurationRequest:
+    account_name: str
+    session_id: str = ""
+    friendly_name: str = ""
+    mode: str = "filter"
+    preview: bool = True
+    publish: bool = False
+    template_name: str = "default"
+    curation_rules: Dict[str, Any] = field(default_factory=dict)
+    max_chars: int = 32000
+
+
+@dataclass(frozen=True)
+class EpisodicCurationResult:
+    status: str
+    session_id: str = ""
+    note_text: str = ""
+    output_path: str = ""
+    summary: Dict[str, Any] = field(default_factory=dict)
+    error: str = ""
+
+
+class EpisodicMemoryManager(ABC):
+    """Provider-neutral episodic session and event store."""
+
+    @abstractmethod
+    def create_session(
+        self,
+        *,
+        account_name: str,
+        agent_name: str,
+        user_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        friendly_name: Optional[str] = None,
+        context_name: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        session_type: str = "user",
+        participants: Optional[List[str]] = None,
+        links: Optional[Dict[str, Any]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> EpisodicSession:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_session(
+        self,
+        session_id: str,
+        *,
+        include_events: bool = True,
+        event_scope: EventScope = "active",
+    ) -> Optional[EpisodicSession]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def list_sessions(self, query: EpisodicSessionQuery) -> List[EpisodicSession]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def session_exists(self, session_id: str) -> bool:
+        raise NotImplementedError
+
+    @abstractmethod
+    def append_event(
+        self, session_id: str, event: EpisodicEvent
+    ) -> EpisodicEvent:
+        raise NotImplementedError
+
+    @abstractmethod
+    def append_event_if_tail(
+        self,
+        session_id: str,
+        event: EpisodicEvent,
+        *,
+        expected_last_event_id: Optional[str],
+    ) -> EpisodicEvent:
+        """Append atomically only when the current event tail is expected."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def add_events(
+        self, session_id: str, events: List[EpisodicEvent]
+    ) -> List[EpisodicEvent]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def link_event(
+        self,
+        correlation_id: Optional[str],
+        session_id: str,
+        event_id: str,
+    ) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def update_session(
+        self, session_id: str, patch: Dict[str, Any]
+    ) -> EpisodicSession:
+        raise NotImplementedError
+
+    @abstractmethod
+    def reset_session(self, session_id: str) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_session(self, session_id: str) -> None:
+        raise NotImplementedError