atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/memory/provider.py

@@ -0,0 +1,397 @@
+"""V3 memory provider interface and base classes (sync + async).
+
+Port of `atomicmemory-sdk/src/memory/provider.ts`. Defines the
+``MemoryProvider`` interface, every standard V3 extension Protocol, and
+two abstract base classes — one sync, one async — that share scope
+validation, ready-state enforcement, and error wrapping.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from typing import Any, Protocol, TypeVar, runtime_checkable
+
+from atomicmemory.core.errors import NotInitializedError, ProviderError, ValidationError
+from atomicmemory.memory.types import (
+    Capabilities,
+    ContextPackage,
+    GraphResult,
+    GraphSearchRequest,
+    HealthStatus,
+    IngestInput,
+    IngestResult,
+    Insight,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    MemoryVersion,
+    PackageRequest,
+    Profile,
+    Scope,
+    SearchRequest,
+    SearchResultPage,
+)
+
+T = TypeVar("T")
+
+# ---------------------------------------------------------------------------
+# Standard extension Protocols (sync + async)
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Updater(Protocol):
+    def update(self, ref: MemoryRef, content: str) -> Memory: ...
+
+
+@runtime_checkable
+class AsyncUpdater(Protocol):
+    async def update(self, ref: MemoryRef, content: str) -> Memory: ...
+
+
+@runtime_checkable
+class Packager(Protocol):
+    def package(self, request: PackageRequest) -> ContextPackage: ...
+
+
+@runtime_checkable
+class AsyncPackager(Protocol):
+    async def package(self, request: PackageRequest) -> ContextPackage: ...
+
+
+@runtime_checkable
+class TemporalSearch(Protocol):
+    def search_as_of(self, request: SearchRequest, as_of: datetime) -> SearchResultPage: ...
+
+
+@runtime_checkable
+class AsyncTemporalSearch(Protocol):
+    async def search_as_of(self, request: SearchRequest, as_of: datetime) -> SearchResultPage: ...
+
+
+@runtime_checkable
+class GraphSearch(Protocol):
+    def search_graph(self, request: GraphSearchRequest) -> GraphResult: ...
+
+
+@runtime_checkable
+class AsyncGraphSearch(Protocol):
+    async def search_graph(self, request: GraphSearchRequest) -> GraphResult: ...
+
+
+@runtime_checkable
+class Forgetter(Protocol):
+    def forget(self, ref: MemoryRef, reason: str | None = None) -> None: ...
+
+
+@runtime_checkable
+class AsyncForgetter(Protocol):
+    async def forget(self, ref: MemoryRef, reason: str | None = None) -> None: ...
+
+
+@runtime_checkable
+class Profiler(Protocol):
+    def profile(self, scope: Scope, instructions: list[str] | None = None) -> Profile: ...
+
+
+@runtime_checkable
+class AsyncProfiler(Protocol):
+    async def profile(self, scope: Scope, instructions: list[str] | None = None) -> Profile: ...
+
+
+@runtime_checkable
+class Reflector(Protocol):
+    def reflect(self, query: str, scope: Scope) -> list[Insight]: ...
+
+
+@runtime_checkable
+class AsyncReflector(Protocol):
+    async def reflect(self, query: str, scope: Scope) -> list[Insight]: ...
+
+
+@runtime_checkable
+class Versioner(Protocol):
+    def history(self, ref: MemoryRef) -> list[MemoryVersion]: ...
+
+
+@runtime_checkable
+class AsyncVersioner(Protocol):
+    async def history(self, ref: MemoryRef) -> list[MemoryVersion]: ...
+
+
+@runtime_checkable
+class BatchOps(Protocol):
+    def batch_ingest(self, inputs: list[IngestInput]) -> list[IngestResult]: ...
+    def batch_delete(self, refs: list[MemoryRef]) -> None: ...
+
+
+@runtime_checkable
+class AsyncBatchOps(Protocol):
+    async def batch_ingest(self, inputs: list[IngestInput]) -> list[IngestResult]: ...
+    async def batch_delete(self, refs: list[MemoryRef]) -> None: ...
+
+
+@runtime_checkable
+class Health(Protocol):
+    def health(self) -> HealthStatus: ...
+
+
+@runtime_checkable
+class AsyncHealth(Protocol):
+    async def health(self) -> HealthStatus: ...
+
+
+# ---------------------------------------------------------------------------
+# Shared scope validation
+# ---------------------------------------------------------------------------
+
+
+def _missing_scope_fields(scope: Scope, required: list[str]) -> list[str]:
+    """Return required fields that are missing/empty on ``scope``."""
+    missing: list[str] = []
+    for field in required:
+        value = getattr(scope, field, None)
+        if not value:
+            missing.append(field)
+    return missing
+
+
+# Operations whose name conflicts with a Python builtin/keyword and is
+# stored under a trailing-underscore field name on the model.
+_OPERATION_FIELD_OVERRIDES: dict[str, str] = {"list": "list_"}
+
+
+def _required_for(capabilities: Capabilities, operation: str) -> list[str]:
+    """Look up the required-scope list for ``operation``.
+
+    Falls back to ``capabilities.required_scope.default`` when the
+    operation has no override.
+    """
+    field = _OPERATION_FIELD_OVERRIDES.get(operation, operation)
+    op_specific: list[str] | None = getattr(capabilities.required_scope, field, None)
+    if op_specific is not None:
+        return op_specific
+    return capabilities.required_scope.default
+
+
+# ---------------------------------------------------------------------------
+# Sync base class
+# ---------------------------------------------------------------------------
+
+
+class BaseMemoryProvider(ABC):
+    """Sync abstract base for synchronous V3 memory providers.
+
+    Subclasses implement the ``do_*`` hooks; this base wires
+    ready-state, scope validation, and error normalization through
+    ``_run_operation``.
+    """
+
+    name: str = ""
+    _initialized: bool = True
+
+    @abstractmethod
+    def do_ingest(self, input: IngestInput) -> IngestResult: ...
+
+    @abstractmethod
+    def do_search(self, request: SearchRequest) -> SearchResultPage: ...
+
+    @abstractmethod
+    def do_get(self, ref: MemoryRef) -> Memory | None: ...
+
+    @abstractmethod
+    def do_delete(self, ref: MemoryRef) -> None: ...
+
+    @abstractmethod
+    def do_list(self, request: ListRequest) -> ListResultPage: ...
+
+    @abstractmethod
+    def capabilities(self) -> Capabilities: ...
+
+    def initialize(self) -> None:  # noqa: B027 — override-or-pass is intentional
+        """Optional async setup hook. Default is a no-op."""
+
+    def close(self) -> None:  # noqa: B027 — override-or-pass is intentional
+        """Optional teardown hook. Default is a no-op."""
+
+    def ingest(self, input: IngestInput) -> IngestResult:
+        return self._run_operation("ingest", input.scope, lambda: self.do_ingest(input))
+
+    def search(self, request: SearchRequest) -> SearchResultPage:
+        return self._run_operation("search", request.scope, lambda: self.do_search(request))
+
+    def get(self, ref: MemoryRef) -> Memory | None:
+        return self._run_operation("get", ref.scope, lambda: self.do_get(ref))
+
+    def delete(self, ref: MemoryRef) -> None:
+        self._run_operation("delete", ref.scope, lambda: self.do_delete(ref))
+
+    def list(self, request: ListRequest) -> ListResultPage:
+        return self._run_operation("list", request.scope, lambda: self.do_list(request))
+
+    def get_extension(self, name: str) -> Any | None:
+        return self._resolve_extension(name)
+
+    def _resolve_extension(self, name: str) -> Any | None:
+        caps = self.capabilities()
+        if getattr(caps.extensions, name, False):
+            return self
+        return None
+
+    def _run_operation(
+        self,
+        operation: str,
+        scope: Scope | None,
+        fn: Callable[[], T],
+    ) -> T:
+        self._assert_ready()
+        if scope is not None:
+            self._validate_scope(scope, operation)
+        try:
+            return fn()
+        except (ProviderError, ValidationError, NotInitializedError):
+            raise
+        except Exception as exc:
+            raise ProviderError(str(exc), provider=self.name, context={"operation": operation}) from exc
+
+    def _assert_ready(self) -> None:
+        if not self._initialized:
+            raise NotInitializedError(f"{self.name} is not initialized. Call initialize() first.")
+
+    def _validate_scope(self, scope: Scope, operation: str) -> None:
+        required = _required_for(self.capabilities(), operation)
+        if not required:
+            return
+        missing = _missing_scope_fields(scope, required)
+        if missing:
+            raise ValidationError(
+                f"{self.name}: scope is missing required fields for '{operation}': {missing}",
+                context={"operation": operation, "missing": missing, "provider": self.name},
+            )
+
+
+# ---------------------------------------------------------------------------
+# Async base class
+# ---------------------------------------------------------------------------
+
+
+class BaseAsyncMemoryProvider(ABC):
+    """Async abstract base for asynchronous V3 memory providers."""
+
+    name: str = ""
+    _initialized: bool = True
+
+    @abstractmethod
+    async def do_ingest(self, input: IngestInput) -> IngestResult: ...
+
+    @abstractmethod
+    async def do_search(self, request: SearchRequest) -> SearchResultPage: ...
+
+    @abstractmethod
+    async def do_get(self, ref: MemoryRef) -> Memory | None: ...
+
+    @abstractmethod
+    async def do_delete(self, ref: MemoryRef) -> None: ...
+
+    @abstractmethod
+    async def do_list(self, request: ListRequest) -> ListResultPage: ...
+
+    @abstractmethod
+    def capabilities(self) -> Capabilities: ...
+
+    async def initialize(self) -> None:  # noqa: B027 — override-or-pass is intentional
+        """Optional async setup hook. Default is a no-op."""
+
+    async def close(self) -> None:  # noqa: B027 — override-or-pass is intentional
+        """Optional async teardown hook. Default is a no-op."""
+
+    async def ingest(self, input: IngestInput) -> IngestResult:
+        return await self._run_operation("ingest", input.scope, lambda: self.do_ingest(input))
+
+    async def search(self, request: SearchRequest) -> SearchResultPage:
+        return await self._run_operation("search", request.scope, lambda: self.do_search(request))
+
+    async def get(self, ref: MemoryRef) -> Memory | None:
+        return await self._run_operation("get", ref.scope, lambda: self.do_get(ref))
+
+    async def delete(self, ref: MemoryRef) -> None:
+        await self._run_operation("delete", ref.scope, lambda: self.do_delete(ref))
+
+    async def list(self, request: ListRequest) -> ListResultPage:
+        return await self._run_operation("list", request.scope, lambda: self.do_list(request))
+
+    def get_extension(self, name: str) -> Any | None:
+        return self._resolve_extension(name)
+
+    def _resolve_extension(self, name: str) -> Any | None:
+        caps = self.capabilities()
+        if getattr(caps.extensions, name, False):
+            return self
+        return None
+
+    async def _run_operation(
+        self,
+        operation: str,
+        scope: Scope | None,
+        fn: Callable[[], Awaitable[T]],
+    ) -> T:
+        self._assert_ready()
+        if scope is not None:
+            self._validate_scope(scope, operation)
+        try:
+            return await fn()
+        except (ProviderError, ValidationError, NotInitializedError):
+            raise
+        except Exception as exc:
+            raise ProviderError(str(exc), provider=self.name, context={"operation": operation}) from exc
+
+    def _assert_ready(self) -> None:
+        if not self._initialized:
+            raise NotInitializedError(f"{self.name} is not initialized. Call initialize() first.")
+
+    def _validate_scope(self, scope: Scope, operation: str) -> None:
+        required = _required_for(self.capabilities(), operation)
+        if not required:
+            return
+        missing = _missing_scope_fields(scope, required)
+        if missing:
+            raise ValidationError(
+                f"{self.name}: scope is missing required fields for '{operation}': {missing}",
+                context={"operation": operation, "missing": missing, "provider": self.name},
+            )
+
+
+# Type alias for any provider — useful for client/service signatures that
+# don't care which flavor.
+MemoryProvider = BaseMemoryProvider
+AsyncMemoryProvider = BaseAsyncMemoryProvider
+
+__all__ = [
+    "AsyncBatchOps",
+    "AsyncForgetter",
+    "AsyncGraphSearch",
+    "AsyncHealth",
+    "AsyncMemoryProvider",
+    "AsyncPackager",
+    "AsyncProfiler",
+    "AsyncReflector",
+    "AsyncTemporalSearch",
+    "AsyncUpdater",
+    "AsyncVersioner",
+    "BaseAsyncMemoryProvider",
+    "BaseMemoryProvider",
+    "BatchOps",
+    "Forgetter",
+    "GraphSearch",
+    "Health",
+    "MemoryProvider",
+    "Packager",
+    "Profiler",
+    "Reflector",
+    "TemporalSearch",
+    "Updater",
+    "Versioner",
+]

atomicmemory/memory/registry.py

@@ -0,0 +1,95 @@
+"""Provider registry — name → factory mapping.
+
+Port of `atomicmemory-sdk/src/memory/providers/registry.ts`. Concrete
+provider modules register themselves here so the client can wire them
+up by name from a config dict.
+
+Two registries live side-by-side: one for sync providers and one for
+async providers. Each maps a provider name (e.g. ``"atomicmemory"``,
+``"mem0"``) to a factory that takes the provider's config object and
+returns a `ProviderRegistration`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from atomicmemory.memory.pipeline import NOOP_PIPELINE, MemoryProcessingPipeline
+from atomicmemory.memory.provider import (
+    BaseAsyncMemoryProvider,
+    BaseMemoryProvider,
+)
+
+
+@dataclass(frozen=True)
+class ProviderRegistration:
+    """Result of a provider factory call."""
+
+    provider: BaseMemoryProvider
+    pipeline: MemoryProcessingPipeline = NOOP_PIPELINE
+
+
+@dataclass(frozen=True)
+class AsyncProviderRegistration:
+    """Async counterpart of `ProviderRegistration`."""
+
+    provider: BaseAsyncMemoryProvider
+    pipeline: MemoryProcessingPipeline = NOOP_PIPELINE
+
+
+SyncProviderFactory = Callable[[Any], ProviderRegistration]
+AsyncProviderFactory = Callable[[Any], AsyncProviderRegistration]
+
+
+class ProviderRegistry:
+    """Mutable registry of sync provider factories.
+
+    Each provider package (e.g. ``atomicmemory.providers.atomicmemory``)
+    calls :meth:`register` on import to add itself to the default
+    registry; callers can also create their own registry instances for
+    test isolation.
+    """
+
+    def __init__(self) -> None:
+        self._factories: dict[str, SyncProviderFactory] = {}
+
+    def register(self, name: str, factory: SyncProviderFactory) -> None:
+        if name in self._factories:
+            raise ValueError(f"Provider '{name}' is already registered")
+        self._factories[name] = factory
+
+    def get(self, name: str) -> SyncProviderFactory | None:
+        return self._factories.get(name)
+
+    def names(self) -> list[str]:
+        return sorted(self._factories.keys())
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._factories
+
+
+class AsyncProviderRegistry:
+    """Async counterpart of `ProviderRegistry`."""
+
+    def __init__(self) -> None:
+        self._factories: dict[str, AsyncProviderFactory] = {}
+
+    def register(self, name: str, factory: AsyncProviderFactory) -> None:
+        if name in self._factories:
+            raise ValueError(f"Async provider '{name}' is already registered")
+        self._factories[name] = factory
+
+    def get(self, name: str) -> AsyncProviderFactory | None:
+        return self._factories.get(name)
+
+    def names(self) -> list[str]:
+        return sorted(self._factories.keys())
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._factories
+
+
+default_registry = ProviderRegistry()
+default_async_registry = AsyncProviderRegistry()

atomicmemory/memory/service.py

@@ -0,0 +1,199 @@
+"""Provider routing service.
+
+Port of `atomicmemory-sdk/src/memory/memory-service.ts`. Provides one
+sync `MemoryService` and one async `AsyncMemoryService`. Each owns the
+provider→pipeline map, dispatches calls to the named (or default)
+provider, and synthesizes the V3 ``package`` extension from
+provider.get_extension.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from atomicmemory.core.errors import ConfigError, ProviderError
+from atomicmemory.memory.pipeline import NOOP_PIPELINE, MemoryProcessingPipeline
+from atomicmemory.memory.provider import (
+    BaseAsyncMemoryProvider,
+    BaseMemoryProvider,
+)
+from atomicmemory.memory.registry import (
+    AsyncProviderRegistry,
+    ProviderRegistry,
+    default_async_registry,
+    default_registry,
+)
+from atomicmemory.memory.types import (
+    ContextPackage,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    PackageRequest,
+    SearchRequest,
+    SearchResultPage,
+)
+
+
+@dataclass
+class MemoryServiceConfig:
+    """Inputs to construct a service."""
+
+    default_provider: str
+    provider_configs: dict[str, Any]
+
+
+class _ServiceBase:
+    """Shared state + lookup helpers for sync and async services."""
+
+    def __init__(self, config: MemoryServiceConfig) -> None:
+        if not config.provider_configs:
+            raise ConfigError("MemoryService requires at least one provider config")
+        if config.default_provider not in config.provider_configs:
+            raise ConfigError(f"default_provider '{config.default_provider}' is not in provider_configs")
+        self._config = config
+        self._default_provider_name = config.default_provider
+
+    @property
+    def default_provider_name(self) -> str:
+        return self._default_provider_name
+
+    def get_configured_providers(self) -> list[str]:
+        return list(self._config.provider_configs.keys())
+
+
+class MemoryService(_ServiceBase):
+    """Sync provider router."""
+
+    def __init__(self, config: MemoryServiceConfig) -> None:
+        super().__init__(config)
+        self._providers: dict[str, BaseMemoryProvider] = {}
+        self._pipelines: dict[str, MemoryProcessingPipeline] = {}
+
+    def initialize(self, registry: ProviderRegistry | None = None) -> None:
+        reg = registry if registry is not None else default_registry
+        for name, provider_config in self._config.provider_configs.items():
+            factory = reg.get(name)
+            if factory is None:
+                continue
+            registration = factory(provider_config)
+            self._providers[name] = registration.provider
+            self._pipelines[name] = registration.pipeline
+            registration.provider.initialize()
+
+    def close(self) -> None:
+        for provider in self._providers.values():
+            provider.close()
+
+    def get_provider(self, name: str | None = None) -> BaseMemoryProvider:
+        provider_name = name or self._default_provider_name
+        provider = self._providers.get(provider_name)
+        if provider is None:
+            raise ConfigError(f"Provider '{provider_name}' is not registered")
+        return provider
+
+    def get_available_providers(self) -> list[str]:
+        return sorted(self._providers.keys())
+
+    def ingest(self, input: IngestInput, provider_name: str | None = None) -> IngestResult:
+        provider = self.get_provider(provider_name)
+        return provider.ingest(input)
+
+    def search(self, request: SearchRequest, provider_name: str | None = None) -> SearchResultPage:
+        provider = self.get_provider(provider_name)
+        return provider.search(request)
+
+    def get(self, ref: MemoryRef, provider_name: str | None = None) -> Memory | None:
+        provider = self.get_provider(provider_name)
+        return provider.get(ref)
+
+    def delete(self, ref: MemoryRef, provider_name: str | None = None) -> None:
+        provider = self.get_provider(provider_name)
+        provider.delete(ref)
+
+    def list(self, request: ListRequest, provider_name: str | None = None) -> ListResultPage:
+        provider = self.get_provider(provider_name)
+        return provider.list(request)
+
+    def package(self, request: PackageRequest, provider_name: str | None = None) -> ContextPackage:
+        provider = self.get_provider(provider_name)
+        packager = provider.get_extension("package")
+        if packager is None or not hasattr(packager, "package"):
+            raise ProviderError(
+                f"Provider '{provider.name}' does not support the 'package' extension",
+                provider=provider.name,
+                context={"operation": "package"},
+            )
+        return packager.package(request)  # type: ignore[no-any-return]
+
+    def _pipeline(self, name: str | None) -> MemoryProcessingPipeline:
+        provider_name = name or self._default_provider_name
+        return self._pipelines.get(provider_name, NOOP_PIPELINE)
+
+
+class AsyncMemoryService(_ServiceBase):
+    """Async provider router."""
+
+    def __init__(self, config: MemoryServiceConfig) -> None:
+        super().__init__(config)
+        self._providers: dict[str, BaseAsyncMemoryProvider] = {}
+        self._pipelines: dict[str, MemoryProcessingPipeline] = {}
+
+    async def initialize(self, registry: AsyncProviderRegistry | None = None) -> None:
+        reg = registry if registry is not None else default_async_registry
+        for name, provider_config in self._config.provider_configs.items():
+            factory = reg.get(name)
+            if factory is None:
+                continue
+            registration = factory(provider_config)
+            self._providers[name] = registration.provider
+            self._pipelines[name] = registration.pipeline
+            await registration.provider.initialize()
+
+    async def close(self) -> None:
+        for provider in self._providers.values():
+            await provider.close()
+
+    def get_provider(self, name: str | None = None) -> BaseAsyncMemoryProvider:
+        provider_name = name or self._default_provider_name
+        provider = self._providers.get(provider_name)
+        if provider is None:
+            raise ConfigError(f"Provider '{provider_name}' is not registered")
+        return provider
+
+    def get_available_providers(self) -> list[str]:
+        return sorted(self._providers.keys())
+
+    async def ingest(self, input: IngestInput, provider_name: str | None = None) -> IngestResult:
+        provider = self.get_provider(provider_name)
+        return await provider.ingest(input)
+
+    async def search(self, request: SearchRequest, provider_name: str | None = None) -> SearchResultPage:
+        provider = self.get_provider(provider_name)
+        return await provider.search(request)
+
+    async def get(self, ref: MemoryRef, provider_name: str | None = None) -> Memory | None:
+        provider = self.get_provider(provider_name)
+        return await provider.get(ref)
+
+    async def delete(self, ref: MemoryRef, provider_name: str | None = None) -> None:
+        provider = self.get_provider(provider_name)
+        await provider.delete(ref)
+
+    async def list(self, request: ListRequest, provider_name: str | None = None) -> ListResultPage:
+        provider = self.get_provider(provider_name)
+        return await provider.list(request)
+
+    async def package(self, request: PackageRequest, provider_name: str | None = None) -> ContextPackage:
+        provider = self.get_provider(provider_name)
+        packager = provider.get_extension("package")
+        if packager is None or not hasattr(packager, "package"):
+            raise ProviderError(
+                f"Provider '{provider.name}' does not support the 'package' extension",
+                provider=provider.name,
+                context={"operation": "package"},
+            )
+        return await packager.package(request)  # type: ignore[no-any-return]