atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/client/memory_client.py

@@ -0,0 +1,292 @@
+"""MemoryClient — sync facade for the V3 memory layer.
+
+Port of `atomicmemory-sdk/src/client/memory-client.ts`. Wraps a
+:class:`atomicmemory.memory.service.MemoryService` and the configured
+providers, providing the public API users construct in application
+code. Async users get the same surface via
+``atomicmemory.AsyncMemoryClient`` (Phase 4).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any
+
+from pydantic import TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+
+# Importing the provider packages registers their factories.
+import atomicmemory.providers.atomicmemory
+import atomicmemory.providers.mem0  # noqa: F401
+from atomicmemory.core.errors import ConfigError, NotInitializedError, ValidationError
+from atomicmemory.core.validation import sanitized_pydantic_errors
+from atomicmemory.memory.provider import BaseMemoryProvider
+from atomicmemory.memory.registry import ProviderRegistry, default_registry
+from atomicmemory.memory.service import MemoryService, MemoryServiceConfig
+from atomicmemory.memory.types import (
+    Capabilities,
+    ContextPackage,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    PackageRequest,
+    SearchRequest,
+    SearchResultPage,
+)
+from atomicmemory.providers.atomicmemory.handle_impl import AtomicMemoryHandle
+
+# IngestInput is a discriminated union; TypeAdapter is the only way to
+# validate from a plain dict since BaseModel.model_validate would not
+# know which variant to pick.
+_INGEST_ADAPTER: TypeAdapter[IngestInput] = TypeAdapter(IngestInput)
+
+
+def _wrap_pydantic_error(type_name: str, exc: PydanticValidationError) -> ValidationError:
+    """Translate a Pydantic ValidationError into the SDK's ValidationError.
+
+    The SDK contract is that every SDK-raised exception inherits from
+    `AtomicMemoryError`. Without this wrapping, callers passing an
+    invalid dict at the client boundary would see Pydantic's exception
+    leak directly out of `MemoryClient`.
+    """
+    return ValidationError(
+        f"Invalid {type_name}: {exc}",
+        context={"type": type_name, "errors": sanitized_pydantic_errors(exc)},
+    )
+
+
+def _coerce_ingest(value: IngestInput | dict[str, Any]) -> IngestInput:
+    if isinstance(value, dict):
+        try:
+            return _INGEST_ADAPTER.validate_python(value)
+        except PydanticValidationError as exc:
+            raise _wrap_pydantic_error("IngestInput", exc) from exc
+    return value
+
+
+def _coerce_search(value: SearchRequest | dict[str, Any]) -> SearchRequest:
+    if isinstance(value, dict):
+        try:
+            return SearchRequest.model_validate(value)
+        except PydanticValidationError as exc:
+            raise _wrap_pydantic_error("SearchRequest", exc) from exc
+    return value
+
+
+def _coerce_package(value: PackageRequest | dict[str, Any]) -> PackageRequest:
+    if isinstance(value, dict):
+        try:
+            return PackageRequest.model_validate(value)
+        except PydanticValidationError as exc:
+            raise _wrap_pydantic_error("PackageRequest", exc) from exc
+    return value
+
+
+def _coerce_ref(value: MemoryRef | dict[str, Any]) -> MemoryRef:
+    if isinstance(value, dict):
+        try:
+            return MemoryRef.model_validate(value)
+        except PydanticValidationError as exc:
+            raise _wrap_pydantic_error("MemoryRef", exc) from exc
+    return value
+
+
+def _coerce_list_request(value: ListRequest | dict[str, Any]) -> ListRequest:
+    if isinstance(value, dict):
+        try:
+            return ListRequest.model_validate(value)
+        except PydanticValidationError as exc:
+            raise _wrap_pydantic_error("ListRequest", exc) from exc
+    return value
+
+
+MemoryProviderConfigs = dict[str, Any]
+"""Map of provider name → provider config (model or dict)."""
+
+
+@dataclass
+class ProviderStatus:
+    """Summary of one configured provider's runtime state."""
+
+    name: str
+    initialized: bool
+    capabilities: Capabilities | None
+
+
+# Module-level alias so `MemoryClient.list` (the method) does not shadow
+# the builtin `list` in return-type annotations within the class body.
+_ProviderStatusList = list[ProviderStatus]
+
+
+class MemoryClient:
+    """Sync entry point for the V3 memory API.
+
+    Example:
+        >>> with MemoryClient(providers={"atomicmemory": {"api_url": "http://localhost:3050"}}) as memory:
+        ...     memory.initialize()
+        ...     memory.ingest({"mode": "text", "content": "hi", "scope": {"user": "u1"}})
+    """
+
+    def __init__(
+        self,
+        providers: MemoryProviderConfigs,
+        default_provider: str | None = None,
+    ) -> None:
+        if not providers:
+            raise ConfigError(
+                'MemoryClient requires at least one provider config. Pass e.g. {"atomicmemory": {"api_url": "..."}}.'
+            )
+        chosen_default = default_provider or _pick_first_provider_key(providers)
+        if chosen_default is None:
+            raise ConfigError("No usable provider config supplied")
+        self._service = MemoryService(
+            MemoryServiceConfig(
+                default_provider=chosen_default,
+                provider_configs=dict(providers),
+            )
+        )
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def initialize(self, registry: ProviderRegistry | None = None) -> None:
+        """Initialize all configured providers. Idempotent."""
+        if self._initialized:
+            return
+        self._service.initialize(registry if registry is not None else default_registry)
+        self._initialized = True
+
+    def close(self) -> None:
+        """Close every initialized provider; safe to call multiple times."""
+        if not self._initialized:
+            return
+        self._service.close()
+        self._initialized = False
+
+    def __enter__(self) -> MemoryClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Core operations (each pair: gated + direct mirror to TS surface)
+    # ------------------------------------------------------------------
+
+    def ingest(self, input: IngestInput | dict[str, Any]) -> IngestResult:
+        self._assert_initialized()
+        return self._service.ingest(_coerce_ingest(input))
+
+    def ingest_direct(self, input: IngestInput | dict[str, Any]) -> IngestResult:
+        """Identical to :meth:`ingest`; preserved for wrapper-subclass parity with TS."""
+        self._assert_initialized()
+        return self._service.ingest(_coerce_ingest(input))
+
+    def search(self, request: SearchRequest | dict[str, Any]) -> SearchResultPage:
+        self._assert_initialized()
+        return self._service.search(_coerce_search(request))
+
+    def search_direct(self, request: SearchRequest | dict[str, Any]) -> SearchResultPage:
+        """Identical to :meth:`search`; preserved for wrapper-subclass parity with TS."""
+        self._assert_initialized()
+        return self._service.search(_coerce_search(request))
+
+    def package(self, request: PackageRequest | dict[str, Any]) -> ContextPackage:
+        self._assert_initialized()
+        return self._service.package(_coerce_package(request))
+
+    def package_direct(self, request: PackageRequest | dict[str, Any]) -> ContextPackage:
+        """Identical to :meth:`package`; preserved for wrapper-subclass parity with TS."""
+        self._assert_initialized()
+        return self._service.package(_coerce_package(request))
+
+    def get(self, ref: MemoryRef | dict[str, Any]) -> Memory | None:
+        self._assert_initialized()
+        return self._service.get(_coerce_ref(ref))
+
+    def delete(self, ref: MemoryRef | dict[str, Any]) -> None:
+        self._assert_initialized()
+        self._service.delete(_coerce_ref(ref))
+
+    def list(self, request: ListRequest | dict[str, Any]) -> ListResultPage:
+        self._assert_initialized()
+        return self._service.list(_coerce_list_request(request))
+
+    # ------------------------------------------------------------------
+    # Capability + provider inspection
+    # ------------------------------------------------------------------
+
+    def capabilities(self, provider_name: str | None = None) -> Capabilities:
+        self._assert_initialized()
+        return self._service.get_provider(provider_name).capabilities()
+
+    def get_extension(self, extension_name: str, provider_name: str | None = None) -> Any | None:
+        self._assert_initialized()
+        provider = self._service.get_provider(provider_name)
+        return provider.get_extension(extension_name)
+
+    def get_provider_status(self) -> _ProviderStatusList:
+        configured = self._service.get_configured_providers()
+        if not self._initialized:
+            return [ProviderStatus(name=n, initialized=False, capabilities=None) for n in configured]
+        available = set(self._service.get_available_providers())
+        statuses: _ProviderStatusList = []
+        for n in configured:
+            if n not in available:
+                statuses.append(ProviderStatus(name=n, initialized=False, capabilities=None))
+                continue
+            statuses.append(
+                ProviderStatus(
+                    name=n,
+                    initialized=True,
+                    capabilities=self._service.get_provider(n).capabilities(),
+                )
+            )
+        return statuses
+
+    def get_provider(self, name: str | None = None) -> BaseMemoryProvider:
+        self._assert_initialized()
+        return self._service.get_provider(name)
+
+    @property
+    def atomicmemory(self) -> AtomicMemoryHandle | None:
+        """Typed access to AtomicMemory-specific routes.
+
+        Returns ``None`` when the client is not yet initialized or the
+        ``atomicmemory`` provider was not configured.
+        """
+        if not self._initialized:
+            return None
+        if "atomicmemory" not in self._service.get_configured_providers():
+            return None
+        provider = self._service.get_provider("atomicmemory")
+        handle = provider.get_extension("atomicmemory.base")
+        if not isinstance(handle, AtomicMemoryHandle):
+            return None
+        return handle
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _assert_initialized(self) -> None:
+        if not self._initialized:
+            raise NotInitializedError("MemoryClient is not initialized. Call client.initialize() first.")
+
+
+def _pick_first_provider_key(providers: MemoryProviderConfigs) -> str | None:
+    for key, value in providers.items():
+        if value is not None and key != "default":
+            return key
+    return None

atomicmemory/core/__init__.py

@@ -0,0 +1,34 @@
+"""Cross-cutting building blocks: errors, retry, events, logging.
+
+Port of `atomicmemory-sdk/src/core/`. These modules are the only ones every
+other layer depends on; they intentionally have no inward dependencies on
+`memory/`, `providers/`, `client/`, etc.
+"""
+
+from atomicmemory.core.errors import (
+    AtomicMemoryError,
+    ConfigError,
+    NetworkError,
+    NotInitializedError,
+    ProviderError,
+    RateLimitError,
+    ValidationError,
+)
+from atomicmemory.core.events import EventEmitter
+from atomicmemory.core.logging import configure_logging, get_logger
+from atomicmemory.core.retry import RetryConfig, with_retry
+
+__all__ = [
+    "AtomicMemoryError",
+    "ConfigError",
+    "EventEmitter",
+    "NetworkError",
+    "NotInitializedError",
+    "ProviderError",
+    "RateLimitError",
+    "RetryConfig",
+    "ValidationError",
+    "configure_logging",
+    "get_logger",
+    "with_retry",
+]

atomicmemory/core/errors.py

@@ -0,0 +1,122 @@
+"""Error hierarchy for the atomicmemory SDK.
+
+Port of `atomicmemory-sdk/src/core/error-handling/`. Every SDK-raised
+exception inherits from `AtomicMemoryError` so callers can catch the
+whole surface with one type.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AtomicMemoryError(Exception):
+    """Base class for every error raised by this SDK.
+
+    Attributes:
+        message: Human-readable description.
+        context: Free-form structured data (e.g. provider name, route,
+            request body fingerprint) that aids debugging without leaking
+            secrets.
+    """
+
+    def __init__(self, message: str, *, context: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.context: dict[str, Any] = dict(context) if context else {}
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r}, context={self.context!r})"
+
+
+class ConfigError(AtomicMemoryError):
+    """Configuration is missing, malformed, or self-inconsistent."""
+
+
+class ValidationError(AtomicMemoryError):
+    """Input failed schema or invariant validation before any I/O."""
+
+
+class NotInitializedError(AtomicMemoryError):
+    """A client method was called before `initialize()` completed."""
+
+
+class ProviderError(AtomicMemoryError):
+    """A backing provider returned an error or the request was rejected.
+
+    Wraps backend HTTP errors. `status_code` and `response_body` are
+    populated when the underlying transport surfaced them.
+
+    Attributes:
+        provider: Provider name, e.g. ``"atomicmemory"`` or ``"mem0"``.
+        status_code: HTTP status code if the failure originated from a
+            response; ``None`` for transport-level failures (use
+            `NetworkError` for those).
+        response_body: Decoded response body when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        status_code: int | None = None,
+        response_body: Any | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        merged: dict[str, Any] = {"provider": provider}
+        if status_code is not None:
+            merged["status_code"] = status_code
+        if context:
+            merged.update(context)
+        super().__init__(message, context=merged)
+        self.provider = provider
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class NetworkError(AtomicMemoryError):
+    """A transport-level failure (timeout, connection refused, DNS, etc.)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        cause: BaseException | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        merged: dict[str, Any] = {"provider": provider}
+        if context:
+            merged.update(context)
+        super().__init__(message, context=merged)
+        self.provider = provider
+        self.__cause__ = cause
+
+
+class RateLimitError(ProviderError):
+    """The backend returned HTTP 429 (rate limited).
+
+    `retry_after_seconds` is populated when the response carried a
+    `Retry-After` header (in seconds). Callers may use it to drive a
+    deferred retry.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limited",
+        *,
+        provider: str,
+        retry_after_seconds: float | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        merged: dict[str, Any] = dict(context) if context else {}
+        if retry_after_seconds is not None:
+            merged["retry_after_seconds"] = retry_after_seconds
+        super().__init__(
+            message,
+            provider=provider,
+            status_code=429,
+            context=merged,
+        )
+        self.retry_after_seconds = retry_after_seconds

atomicmemory/core/events.py

@@ -0,0 +1,65 @@
+"""Lightweight typed event emitter.
+
+Port of `atomicmemory-sdk/src/core/events.ts`. Sync-only by design — the
+SDK emits events for cache hits, search completions, and similar
+diagnostic hooks; async listeners can schedule themselves via the event
+loop if needed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+Listener = Callable[..., None]
+
+
+class EventEmitter:
+    """Minimal pub/sub for diagnostic events.
+
+    Not thread-safe. Listeners are invoked synchronously in registration
+    order; an exception in one listener does not prevent the others from
+    running, but the first exception is re-raised after all have been
+    called.
+    """
+
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[Listener]] = {}
+
+    def on(self, event: str, listener: Listener) -> None:
+        """Register a listener for ``event``."""
+        self._listeners.setdefault(event, []).append(listener)
+
+    def off(self, event: str, listener: Listener) -> None:
+        """Remove a previously registered listener.
+
+        No-op when the listener was not registered.
+        """
+        if event not in self._listeners:
+            return
+        try:
+            self._listeners[event].remove(listener)
+        except ValueError:
+            return
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> None:
+        """Invoke every listener registered for ``event``.
+
+        Raises:
+            BaseException: Re-raises the first listener exception after
+                all listeners have been invoked.
+        """
+        listeners = list(self._listeners.get(event, ()))
+        first_exc: BaseException | None = None
+        for listener in listeners:
+            try:
+                listener(*args, **kwargs)
+            except BaseException as exc:
+                if first_exc is None:
+                    first_exc = exc
+        if first_exc is not None:
+            raise first_exc
+
+    def listener_count(self, event: str) -> int:
+        """Number of listeners registered for ``event``."""
+        return len(self._listeners.get(event, ()))

atomicmemory/core/logging.py

@@ -0,0 +1,37 @@
+"""Logging helpers for the SDK.
+
+Port of `atomicmemory-sdk/src/utils/logger.ts`. Wraps stdlib `logging` so
+SDK callers get a consistent logger name prefix without forcing handler
+configuration on the host application.
+"""
+
+from __future__ import annotations
+
+import logging
+
+_ROOT_LOGGER_NAME = "atomicmemory"
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger under the ``atomicmemory`` namespace.
+
+    Args:
+        name: Optional dotted suffix appended to ``atomicmemory.``.
+            ``None`` returns the root SDK logger.
+
+    Returns:
+        Configured `logging.Logger`. Handler attachment is the host
+        application's responsibility; the SDK never adds default handlers.
+    """
+    if name is None or name == "":
+        return logging.getLogger(_ROOT_LOGGER_NAME)
+    return logging.getLogger(f"{_ROOT_LOGGER_NAME}.{name}")
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Set the SDK root logger's level.
+
+    Useful as a one-liner during development. Production callers should
+    configure their own handlers via stdlib `logging` directly.
+    """
+    get_logger().setLevel(level)

atomicmemory/core/retry.py

@@ -0,0 +1,124 @@
+"""Retry primitives with exponential backoff.
+
+Port of `atomicmemory-sdk/src/storage/retry-engine.ts`. Used by the HTTP
+transports for idempotent operations (GET, search, list); never wrap
+non-idempotent calls without a caller-supplied `should_retry` predicate.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class RetryConfig:
+    """Knobs for `with_retry`.
+
+    Attributes:
+        max_attempts: Total attempts, including the initial call. Must be
+            ``>= 1``. ``1`` disables retry.
+        initial_delay_seconds: Delay before the *second* attempt.
+        max_delay_seconds: Upper bound on any single backoff delay.
+        backoff_multiplier: Each successive delay is multiplied by this.
+            ``2.0`` doubles the wait per attempt.
+    """
+
+    max_attempts: int = 3
+    initial_delay_seconds: float = 0.25
+    max_delay_seconds: float = 5.0
+    backoff_multiplier: float = 2.0
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.initial_delay_seconds < 0:
+            raise ValueError("initial_delay_seconds must be >= 0")
+        if self.max_delay_seconds < self.initial_delay_seconds:
+            raise ValueError("max_delay_seconds must be >= initial_delay_seconds")
+        if self.backoff_multiplier <= 0:
+            raise ValueError("backoff_multiplier must be > 0")
+
+
+def _delays(config: RetryConfig) -> list[float]:
+    """Return the sequence of sleep durations between attempts."""
+    delays: list[float] = []
+    delay = config.initial_delay_seconds
+    for _ in range(config.max_attempts - 1):
+        delays.append(min(delay, config.max_delay_seconds))
+        delay *= config.backoff_multiplier
+    return delays
+
+
+def with_retry(
+    func: Callable[[], T],
+    *,
+    config: RetryConfig | None = None,
+    should_retry: Callable[[BaseException], bool] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> T:
+    """Run a callable with retry on transient failures.
+
+    Args:
+        func: Zero-argument callable to invoke.
+        config: Retry configuration. Defaults to :class:`RetryConfig`'s
+            defaults when ``None``.
+        should_retry: Predicate that decides whether a given exception is
+            transient. ``None`` means "never retry exceptions" — only
+            useful for testing the success path.
+        sleep: Sleep function. Pluggable for deterministic testing.
+
+    Returns:
+        Whatever ``func`` returns on its first successful attempt.
+
+    Raises:
+        BaseException: Re-raises the last exception if every attempt fails
+            or if ``should_retry`` rejects it.
+    """
+    cfg = config or RetryConfig()
+    delays = _delays(cfg)
+    last_exc: BaseException | None = None
+    for attempt in range(cfg.max_attempts):
+        try:
+            return func()
+        except BaseException as exc:
+            last_exc = exc
+            is_last = attempt == cfg.max_attempts - 1
+            if is_last or should_retry is None or not should_retry(exc):
+                raise
+            sleep(delays[attempt])
+    assert last_exc is not None
+    raise last_exc
+
+
+async def awith_retry(
+    func: Callable[[], Awaitable[T]],
+    *,
+    config: RetryConfig | None = None,
+    should_retry: Callable[[BaseException], bool] | None = None,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> T:
+    """Async counterpart of :func:`with_retry`.
+
+    Behaviour mirrors the sync version; both use the same backoff schedule
+    and the same predicate signature.
+    """
+    cfg = config or RetryConfig()
+    delays = _delays(cfg)
+    last_exc: BaseException | None = None
+    for attempt in range(cfg.max_attempts):
+        try:
+            return await func()
+        except BaseException as exc:
+            last_exc = exc
+            is_last = attempt == cfg.max_attempts - 1
+            if is_last or should_retry is None or not should_retry(exc):
+                raise
+            await sleep(delays[attempt])
+    assert last_exc is not None
+    raise last_exc

atomicmemory/core/validation.py

@@ -0,0 +1,22 @@
+"""Validation helpers shared by public SDK boundaries.
+
+Pydantic errors can include caller input under the ``input`` key. Public
+SDK exceptions should expose useful schema diagnostics without copying
+API keys, metadata, or byte bodies into structured error context.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError as PydanticValidationError
+
+_DROPPED_ERROR_KEYS = {"input", "ctx", "url"}
+
+
+def sanitized_pydantic_errors(exc: PydanticValidationError) -> list[dict[str, Any]]:
+    """Return Pydantic errors stripped of caller-supplied values."""
+    sanitized: list[dict[str, Any]] = []
+    for error in exc.errors():
+        sanitized.append({key: value for key, value in error.items() if key not in _DROPPED_ERROR_KEYS})
+    return sanitized