atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/__init__.py

@@ -0,0 +1,166 @@
+"""atomicmemory — Python client SDK for AtomicMemory.
+
+Top-level re-exports for the public API. Users typically only need to
+import `AtomicMemoryClient` plus the type they're working with — every
+type they could need is re-exported here.
+"""
+
+from atomicmemory._version import __version__
+from atomicmemory.client.async_memory_client import AsyncMemoryClient, AsyncProviderStatus
+from atomicmemory.client.atomic_memory_client import (
+    AsyncAtomicMemoryClient,
+    AtomicMemoryClient,
+    AtomicMemoryClientConfig,
+    MemoryNamespaceConfig,
+)
+from atomicmemory.client.memory_client import MemoryClient, ProviderStatus
+from atomicmemory.core.errors import (
+    AtomicMemoryError,
+    ConfigError,
+    NetworkError,
+    NotInitializedError,
+    ProviderError,
+    RateLimitError,
+    ValidationError,
+)
+from atomicmemory.memory.filters import FieldFilter, FieldFilterOp, FilterExpr
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    ContextPackage,
+    GraphEdge,
+    GraphNode,
+    GraphResult,
+    GraphSearchRequest,
+    HealthStatus,
+    IngestBase,
+    IngestInput,
+    IngestResult,
+    Insight,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryKind,
+    MemoryRef,
+    MemoryVersion,
+    MemoryVersionEvent,
+    Message,
+    MessageIngest,
+    MessageRole,
+    PackageFormat,
+    PackageRequest,
+    Profile,
+    Provenance,
+    Scope,
+    SearchRequest,
+    SearchResult,
+    SearchResultPage,
+    TextIngest,
+    VerbatimIngest,
+)
+from atomicmemory.storage import (
+    ArtifactHead,
+    ArtifactInUseError,
+    ArtifactMetadata,
+    ArtifactNotFoundError,
+    ArtifactRange,
+    ArtifactRef,
+    AsyncStorageClient,
+    DeleteArtifactOptions,
+    DeleteArtifactPolicy,
+    DeleteArtifactResult,
+    FilecoinDirectStorageNotSupportedError,
+    PointerContentNotManagedError,
+    PutArtifactInput,
+    PutManagedInput,
+    PutPointerInput,
+    StorageArtifactStatus,
+    StorageCapabilities,
+    StorageClient,
+    StorageClientConfig,
+    StorageClientError,
+    StoredArtifact,
+    UnsupportedCapabilityError,
+    VerificationResult,
+    VerifyArtifactOptions,
+)
+
+__all__ = [
+    "ArtifactHead",
+    "ArtifactInUseError",
+    "ArtifactMetadata",
+    "ArtifactNotFoundError",
+    "ArtifactRange",
+    "ArtifactRef",
+    "AsyncAtomicMemoryClient",
+    "AsyncMemoryClient",
+    "AsyncProviderStatus",
+    "AsyncStorageClient",
+    "AtomicMemoryClient",
+    "AtomicMemoryClientConfig",
+    "AtomicMemoryError",
+    "Capabilities",
+    "CapabilitiesExtensions",
+    "CapabilitiesRequiredScope",
+    "ConfigError",
+    "ContextPackage",
+    "DeleteArtifactOptions",
+    "DeleteArtifactPolicy",
+    "DeleteArtifactResult",
+    "FieldFilter",
+    "FieldFilterOp",
+    "FilecoinDirectStorageNotSupportedError",
+    "FilterExpr",
+    "GraphEdge",
+    "GraphNode",
+    "GraphResult",
+    "GraphSearchRequest",
+    "HealthStatus",
+    "IngestBase",
+    "IngestInput",
+    "IngestResult",
+    "Insight",
+    "ListRequest",
+    "ListResultPage",
+    "Memory",
+    "MemoryClient",
+    "MemoryKind",
+    "MemoryNamespaceConfig",
+    "MemoryRef",
+    "MemoryVersion",
+    "MemoryVersionEvent",
+    "Message",
+    "MessageIngest",
+    "MessageRole",
+    "NetworkError",
+    "NotInitializedError",
+    "PackageFormat",
+    "PackageRequest",
+    "PointerContentNotManagedError",
+    "Profile",
+    "Provenance",
+    "ProviderError",
+    "ProviderStatus",
+    "PutArtifactInput",
+    "PutManagedInput",
+    "PutPointerInput",
+    "RateLimitError",
+    "Scope",
+    "SearchRequest",
+    "SearchResult",
+    "SearchResultPage",
+    "StorageArtifactStatus",
+    "StorageCapabilities",
+    "StorageClient",
+    "StorageClientConfig",
+    "StorageClientError",
+    "StoredArtifact",
+    "TextIngest",
+    "UnsupportedCapabilityError",
+    "ValidationError",
+    "VerbatimIngest",
+    "VerificationResult",
+    "VerifyArtifactOptions",
+    "__version__",
+]

atomicmemory/_version.py

@@ -0,0 +1,3 @@
+"""Version metadata for the atomicmemory Python SDK."""
+
+__version__ = "1.0.0"

atomicmemory/client/__init__.py

@@ -0,0 +1,22 @@
+"""Public client facades for memory and storage namespaces."""
+
+from atomicmemory.client.async_memory_client import AsyncMemoryClient, AsyncProviderStatus
+from atomicmemory.client.atomic_memory_client import (
+    AsyncAtomicMemoryClient,
+    AtomicMemoryClient,
+    AtomicMemoryClientConfig,
+    MemoryNamespaceConfig,
+)
+from atomicmemory.client.memory_client import MemoryClient, MemoryProviderConfigs, ProviderStatus
+
+__all__ = [
+    "AsyncAtomicMemoryClient",
+    "AsyncMemoryClient",
+    "AsyncProviderStatus",
+    "AtomicMemoryClient",
+    "AtomicMemoryClientConfig",
+    "MemoryClient",
+    "MemoryNamespaceConfig",
+    "MemoryProviderConfigs",
+    "ProviderStatus",
+]

atomicmemory/client/async_memory_client.py

@@ -0,0 +1,202 @@
+"""AsyncMemoryClient — async facade for the V3 memory layer.
+
+Mirrors :class:`atomicmemory.client.memory_client.MemoryClient` with
+``async def`` for every I/O method and a ``__aenter__`` / ``__aexit__``
+context manager. Dict coercion + Pydantic-error wrapping is identical
+to the sync client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any
+
+# Importing the provider packages registers both sync and async factories.
+import atomicmemory.providers.atomicmemory
+import atomicmemory.providers.mem0  # noqa: F401
+from atomicmemory.client.memory_client import (
+    _coerce_ingest,
+    _coerce_list_request,
+    _coerce_package,
+    _coerce_ref,
+    _coerce_search,
+)
+from atomicmemory.core.errors import ConfigError, NotInitializedError
+from atomicmemory.memory.provider import BaseAsyncMemoryProvider
+from atomicmemory.memory.registry import AsyncProviderRegistry, default_async_registry
+from atomicmemory.memory.service import AsyncMemoryService, MemoryServiceConfig
+from atomicmemory.memory.types import (
+    Capabilities,
+    ContextPackage,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    PackageRequest,
+    SearchRequest,
+    SearchResultPage,
+)
+from atomicmemory.providers.atomicmemory.async_handle_impl import AsyncAtomicMemoryHandle
+
+MemoryProviderConfigs = dict[str, Any]
+
+
+@dataclass
+class AsyncProviderStatus:
+    """Async-side mirror of :class:`ProviderStatus`."""
+
+    name: str
+    initialized: bool
+    capabilities: Capabilities | None
+
+
+_AsyncProviderStatusList = list[AsyncProviderStatus]
+
+
+class AsyncMemoryClient:
+    """Async entry point for the V3 memory API.
+
+    Example:
+        >>> async with AsyncMemoryClient(
+        ...     providers={"atomicmemory": {"api_url": "http://localhost:3050"}}
+        ... ) as memory:
+        ...     await memory.initialize()
+        ...     await 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(
+                "AsyncMemoryClient 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 = AsyncMemoryService(
+            MemoryServiceConfig(
+                default_provider=chosen_default,
+                provider_configs=dict(providers),
+            )
+        )
+        self._initialized = False
+
+    async def initialize(self, registry: AsyncProviderRegistry | None = None) -> None:
+        if self._initialized:
+            return
+        await self._service.initialize(registry if registry is not None else default_async_registry)
+        self._initialized = True
+
+    async def close(self) -> None:
+        if not self._initialized:
+            return
+        await self._service.close()
+        self._initialized = False
+
+    async def __aenter__(self) -> AsyncMemoryClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def ingest(self, input: IngestInput | dict[str, Any]) -> IngestResult:
+        self._assert_initialized()
+        return await self._service.ingest(_coerce_ingest(input))
+
+    async def ingest_direct(self, input: IngestInput | dict[str, Any]) -> IngestResult:
+        self._assert_initialized()
+        return await self._service.ingest(_coerce_ingest(input))
+
+    async def search(self, request: SearchRequest | dict[str, Any]) -> SearchResultPage:
+        self._assert_initialized()
+        return await self._service.search(_coerce_search(request))
+
+    async def search_direct(self, request: SearchRequest | dict[str, Any]) -> SearchResultPage:
+        self._assert_initialized()
+        return await self._service.search(_coerce_search(request))
+
+    async def package(self, request: PackageRequest | dict[str, Any]) -> ContextPackage:
+        self._assert_initialized()
+        return await self._service.package(_coerce_package(request))
+
+    async def package_direct(self, request: PackageRequest | dict[str, Any]) -> ContextPackage:
+        self._assert_initialized()
+        return await self._service.package(_coerce_package(request))
+
+    async def get(self, ref: MemoryRef | dict[str, Any]) -> Memory | None:
+        self._assert_initialized()
+        return await self._service.get(_coerce_ref(ref))
+
+    async def delete(self, ref: MemoryRef | dict[str, Any]) -> None:
+        self._assert_initialized()
+        await self._service.delete(_coerce_ref(ref))
+
+    async def list(self, request: ListRequest | dict[str, Any]) -> ListResultPage:
+        self._assert_initialized()
+        return await self._service.list(_coerce_list_request(request))
+
+    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()
+        return self._service.get_provider(provider_name).get_extension(extension_name)
+
+    def get_provider_status(self) -> _AsyncProviderStatusList:
+        configured = self._service.get_configured_providers()
+        if not self._initialized:
+            return [AsyncProviderStatus(name=n, initialized=False, capabilities=None) for n in configured]
+        available = set(self._service.get_available_providers())
+        statuses: _AsyncProviderStatusList = []
+        for n in configured:
+            if n not in available:
+                statuses.append(AsyncProviderStatus(name=n, initialized=False, capabilities=None))
+                continue
+            statuses.append(
+                AsyncProviderStatus(
+                    name=n,
+                    initialized=True,
+                    capabilities=self._service.get_provider(n).capabilities(),
+                )
+            )
+        return statuses
+
+    def get_provider(self, name: str | None = None) -> BaseAsyncMemoryProvider:
+        self._assert_initialized()
+        return self._service.get_provider(name)
+
+    @property
+    def atomicmemory(self) -> AsyncAtomicMemoryHandle | None:
+        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, AsyncAtomicMemoryHandle):
+            return None
+        return handle
+
+    def _assert_initialized(self) -> None:
+        if not self._initialized:
+            raise NotInitializedError("AsyncMemoryClient is not initialized. Call await 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/client/atomic_memory_client.py

@@ -0,0 +1,181 @@
+"""Primary clients that expose memory and storage sibling namespaces.
+
+This module mirrors the TypeScript SDK's `AtomicMemoryClient`: callers
+configure one core transport boundary and receive both ``memory`` and
+``storage`` namespaces backed by the same API URL, API key, and user
+scope.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import ValidationError as PydanticValidationError
+
+from atomicmemory.client.async_memory_client import AsyncMemoryClient
+from atomicmemory.client.memory_client import MemoryClient, MemoryProviderConfigs
+from atomicmemory.core.errors import ConfigError
+from atomicmemory.core.validation import sanitized_pydantic_errors
+from atomicmemory.storage import AsyncStorageClient, StorageClient, StorageClientConfig
+
+
+class MemoryNamespaceConfig(BaseModel):
+    """Configuration for the aggregator's ``memory`` namespace."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    providers: MemoryProviderConfigs
+    default_provider: str | None = Field(default=None, alias="defaultProvider")
+
+    @model_validator(mode="after")
+    def _require_providers(self) -> MemoryNamespaceConfig:
+        if not self.providers:
+            raise ValueError("memory.providers must not be empty")
+        return self
+
+
+class AtomicMemoryClientConfig(BaseModel):
+    """Configuration for :class:`AtomicMemoryClient` and its async peer."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    api_url: str = Field(alias="apiUrl")
+    api_key: str = Field(alias="apiKey")
+    user_id: str = Field(alias="userId")
+    timeout_seconds: float = Field(default=30.0, alias="timeoutSeconds")
+    memory: MemoryNamespaceConfig | None = None
+
+    @field_validator("api_url")
+    @classmethod
+    def _validate_api_url(cls, value: str) -> str:
+        stripped = value.strip()
+        parsed = urlparse(stripped)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("api_url must be an http(s) URL")
+        return stripped
+
+    @field_validator("api_key", "user_id")
+    @classmethod
+    def _validate_non_empty_secret(cls, value: str) -> str:
+        stripped = value.strip()
+        if stripped == "":
+            raise ValueError("value must not be empty")
+        return stripped
+
+    @field_validator("timeout_seconds")
+    @classmethod
+    def _validate_timeout(cls, value: float) -> float:
+        if value <= 0:
+            raise ValueError("timeout_seconds must be greater than zero")
+        return value
+
+    @model_validator(mode="after")
+    def _require_non_empty(self) -> AtomicMemoryClientConfig:
+        if not self.api_url:
+            raise ValueError("api_url is required")
+        if not self.api_key:
+            raise ValueError("api_key is required")
+        if not self.user_id:
+            raise ValueError("user_id is required")
+        return self
+
+
+class AtomicMemoryClient:
+    """Sync primary SDK entry point with ``memory`` and ``storage`` namespaces."""
+
+    def __init__(self, config: AtomicMemoryClientConfig | dict[str, Any]) -> None:
+        resolved = _coerce_atomic_config(config)
+        memory = _memory_config(resolved)
+        self.memory = MemoryClient(memory.providers, memory.default_provider)
+        self.storage = StorageClient(_storage_config(resolved))
+
+    def close(self) -> None:
+        try:
+            self.memory.close()
+        finally:
+            self.storage.close()
+
+    def __enter__(self) -> AtomicMemoryClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncAtomicMemoryClient:
+    """Async primary SDK entry point with ``memory`` and ``storage`` namespaces."""
+
+    def __init__(self, config: AtomicMemoryClientConfig | dict[str, Any]) -> None:
+        resolved = _coerce_atomic_config(config)
+        memory = _memory_config(resolved)
+        self.memory = AsyncMemoryClient(memory.providers, memory.default_provider)
+        self.storage = AsyncStorageClient(_storage_config(resolved))
+
+    async def close(self) -> None:
+        first_error: BaseException | None = None
+        try:
+            await self.memory.close()
+        except BaseException as exc:
+            first_error = exc
+        try:
+            await self.storage.close()
+        except BaseException as exc:
+            if first_error is not None:
+                raise first_error from exc
+            raise
+        if first_error is not None:
+            raise first_error
+
+    async def __aenter__(self) -> AsyncAtomicMemoryClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+
+def _coerce_atomic_config(config: AtomicMemoryClientConfig | dict[str, Any]) -> AtomicMemoryClientConfig:
+    if isinstance(config, AtomicMemoryClientConfig):
+        return config
+    try:
+        return AtomicMemoryClientConfig.model_validate(config)
+    except PydanticValidationError as exc:
+        raise ConfigError(
+            f"Invalid AtomicMemoryClientConfig: {exc}",
+            context={"type": "AtomicMemoryClientConfig", "errors": sanitized_pydantic_errors(exc)},
+        ) from exc
+
+
+def _memory_config(config: AtomicMemoryClientConfig) -> MemoryNamespaceConfig:
+    if config.memory is not None:
+        return config.memory
+    return MemoryNamespaceConfig(
+        providers={
+            "atomicmemory": {
+                "apiUrl": config.api_url,
+                "apiKey": config.api_key,
+                "timeoutSeconds": config.timeout_seconds,
+            }
+        }
+    )
+
+
+def _storage_config(config: AtomicMemoryClientConfig) -> StorageClientConfig:
+    return StorageClientConfig(
+        api_url=config.api_url,
+        api_key=config.api_key,
+        user_id=config.user_id,
+        timeout_seconds=config.timeout_seconds,
+    )