couchbase-agent-memory 1.0.0__py3-none-any.whl

agentmemory/__init__.py

@@ -0,0 +1,131 @@
+"""Couchbase Agent Memory Client SDK.
+
+A Python SDK for interacting with the Couchbase Agent Memory server API.
+Provides a hierarchical, resource-based interface for managing users, sessions, and memory blocks.
+"""
+
+__version__ = "1.0.0"
+
+# Main clients
+from agentmemory.client import AgentMemoryClient, AsyncAgentMemoryClient
+
+# Resources
+from agentmemory.resources import (
+    UserResource,
+    AsyncUserResource,
+    SessionResource,
+    AsyncSessionResource,
+)
+
+# Models
+from agentmemory.models import (
+    # Enums
+    HealthStatus,
+    MemoryBlockStatus,
+    # User models
+    User,
+    UserList,
+    # Session models
+    Session,
+    SessionList,
+    # Memory models
+    ChatMessage,
+    MemoryBlock,
+    MemoryList,
+    AddMemoryResponse,
+    DeleteMemoryResponse,
+    UpdateMemoryResponse,
+    ListMemoriesResponse,
+    FilterOptions,
+    # Health models
+    AsyncBatchProcessorHealthResponse,
+    AsyncBatchQueueStats,
+    AsyncBatchRateBudget,
+    AsyncBatchStatistics,
+    HealthResponse,
+    ModelsHealth,
+    HealthPingResponse,
+)
+
+# Exceptions
+from agentmemory.exceptions import (
+    AgentMemoryError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ConflictError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UpstreamError,
+    ServerError,
+    ConnectionError,
+    TimeoutError,
+    ServerDownError,
+    ReadTimeoutError,
+)
+
+# Logging
+from agentmemory.logger import (
+    enable_logging,
+    disable_logging,
+    set_level,
+    is_logging_enabled,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "AgentMemoryClient",
+    "AsyncAgentMemoryClient",
+    # Resources
+    "UserResource",
+    "AsyncUserResource",
+    "SessionResource",
+    "AsyncSessionResource",
+    # Enums
+    "HealthStatus",
+    "MemoryBlockStatus",
+    # User models
+    "User",
+    "UserList",
+    # Session models
+    "Session",
+    "SessionList",
+    # Memory models
+    "ChatMessage",
+    "MemoryBlock",
+    "MemoryList",
+    "AddMemoryResponse",
+    "DeleteMemoryResponse",
+    "UpdateMemoryResponse",
+    "ListMemoriesResponse",
+    "FilterOptions",
+    # Health models
+    "AsyncBatchProcessorHealthResponse",
+    "AsyncBatchQueueStats",
+    "AsyncBatchRateBudget",
+    "AsyncBatchStatistics",
+    "HealthResponse",
+    "ModelsHealth",
+    "HealthPingResponse",
+    # Exceptions
+    "AgentMemoryError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "UpstreamError",
+    "ServerError",
+    "ConnectionError",
+    "TimeoutError",
+    "ServerDownError",
+    "ReadTimeoutError",
+    # Logging
+    "enable_logging",
+    "disable_logging",
+    "set_level",
+    "is_logging_enabled",
+]

agentmemory/client.py

@@ -0,0 +1,491 @@
+"""
+Main client class for interacting with the Couchbase Agent Memory server APIs
+Provides AgentMemoryClient and AsyncAgentMemoryClient classes
+"""
+
+from typing import Optional, Dict, Any, List, Union, Callable
+from urllib.parse import urlsplit, urlunsplit
+
+from agentmemory.defaults import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+)
+from agentmemory.exceptions import ValidationError
+from agentmemory.http import HTTPClient, AsyncHTTPClient
+from agentmemory.logger import logger
+from agentmemory.models import (
+    User,
+    UserList,
+    HealthPingResponse,
+)
+from agentmemory.resources.health import health_ping, async_health_ping, HealthEntity
+from agentmemory.resources.user import UserResource, AsyncUserResource
+
+
+def _require_non_blank(value: Optional[str], field: str) -> str:
+    if value is None or not value.strip():
+        raise ValidationError(f"{field} must not be blank")
+    if field.endswith("_id") and any(ch in value for ch in "/?#"):
+        raise ValidationError(f"{field} must not contain '/', '?', or '#'")
+    return value
+
+
+def _redact_url(url: str) -> str:
+    parts = urlsplit(url)
+    netloc = parts.netloc.rsplit("@", 1)[-1]
+    return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
+
+
+class AgentMemoryClient:
+    """Synchronous client for the Couchbase Agent Memory API.
+
+    Provides a hierarchical, resource-based interface for managing users,
+    sessions, and memory blocks.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[Union[str, Callable[[], str]]] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        client_id: Optional[str] = None,
+        verify: Union[bool, str] = True,
+    ):
+        """Initialize the Couchbase Agent Memory client.
+
+        Args:
+            base_url: Base URL of the Couchbase Agent Memory server
+            token: JWT bearer token for authentication. Can be:
+                - str: Static token string
+                - Callable[[], str]: Function that returns current token (for dynamic refresh)
+                - None: If auth is disabled in Couchbase Agent Memory server
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retries for failed requests
+            client_id: Optional client identifier for request tracking
+            verify: SSL certificate verification. Can be:
+                - True: Verify SSL certificates (default)
+                - False: Disable SSL verification (for self-signed certs in development)
+                - str: Path to a CA certificate file to trust
+        """
+        self.base_url = base_url
+        self._http = HTTPClient(
+            base_url=base_url,
+            token=token,
+            timeout=timeout,
+            max_retries=max_retries,
+            client_id=client_id,
+            verify=verify,
+        )
+        logger.info(
+            f"Couchbase Agent Memory client initialized: {_redact_url(base_url)}"
+        )
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._http.close()
+        logger.info("Couchbase Agent Memory client closed")
+
+    def __enter__(self) -> "AgentMemoryClient":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"AgentMemoryClient(base_url={self.base_url!r})"
+
+    # Health
+    def health_ping(
+        self,
+        entity: Optional[HealthEntity] = None,
+    ) -> HealthPingResponse:
+        """Check health of Couchbase Agent Memory server components.
+
+        By default, checks all components and returns a combined health status.
+        Optionally specify an entity to check only that component.
+
+        Args:
+            entity: Optional specific entity to check. One of:
+                - "server": Overall server health
+                - "couchbase": Database health
+                - "models": Embedding and LLM model services
+                - "async-batch-processor": Async batch processor readiness
+                - "async-batch-processor-stats": Async batch processor statistics
+                  (underscore aliases are also accepted)
+                - "memory": Memory service health
+                If None, checks all entities.
+
+        Returns:
+            HealthPingResponse with health status for checked components
+        """
+        return health_ping(self._http, entity)
+
+    # User ops
+    def create_user(
+        self,
+        user_id: str,
+        name: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> UserResource:
+        """Create a new user.
+
+        Args:
+            user_id: Unique identifier for the user
+            name: Display name for the user
+            metadata: Optional metadata dictionary
+
+        Returns:
+            UserResource for performing user operations
+
+        Raises:
+            ConflictError: If user already exists
+            ValidationError: If request is invalid
+        """
+        _require_non_blank(user_id, "user_id")
+        _require_non_blank(name, "name")
+
+        payload = {
+            "user_id": user_id,
+            "name": name,
+        }
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        user = self._http.post("/users", response_model=User, json=payload)
+        logger.info(f"Created user: {user_id} ({name})")
+        return UserResource(
+            self._http,
+            user_id,
+            user.name,
+            sessions=user.sessions,
+            metadata=user.metadata,
+        )
+
+    def get_user(self, user_id: str) -> UserResource:
+        """Get a user resource hydrated from the server.
+
+        Fetches the user record so the returned resource exposes
+        name, sessions, and metadata in addition to user_id.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            UserResource for performing user operations
+
+        Raises:
+            NotFoundError: If user doesn't exist
+        """
+        _require_non_blank(user_id, "user_id")
+
+        result = self._http.post("/users/search", json={"user_id": user_id})
+        user = User.model_validate(result)
+        logger.info(f"Retrieved user: {user_id}")
+        return UserResource(
+            self._http,
+            user_id,
+            user.name,
+            sessions=user.sessions,
+            metadata=user.metadata,
+        )
+
+    def list_users(self) -> UserList:
+        """List all users.
+
+        Returns:
+            UserList containing all users and count
+        """
+        result = self._http.get("/users", response_model=UserList)
+        logger.info(f"Listed {result.count} user(s)")
+        return result
+
+    def search_users(
+        self,
+        user_id: Optional[str] = None,
+        name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Union[User, List[User]]:
+        """Search for users by criteria.
+
+        At least one search criterion must be provided.
+
+        Args:
+            user_id: Filter by user ID
+            name: Filter by name
+            metadata: Filter by metadata fields
+
+        Returns:
+            Single User or list of Users matching criteria
+
+        Raises:
+            ValidationError: If no criteria provided
+            NotFoundError: If no users found
+        """
+        if user_id is not None and not user_id.strip():
+            raise ValidationError("user_id must not be blank if provided")
+        if name is not None and not name.strip():
+            raise ValidationError("name must not be blank if provided")
+
+        payload = {}
+        if user_id is not None:
+            payload["user_id"] = user_id
+        if name is not None:
+            payload["name"] = name
+        if metadata:
+            payload["metadata"] = metadata
+        if not payload:
+            raise ValidationError(
+                "at least one of user_id, name, or metadata must be provided"
+            )
+
+        result = self._http.post("/users/search", json=payload)
+
+        # Handle single user vs list
+        if isinstance(result, list):
+            users = [User.model_validate(u) for u in result]
+            logger.info(f"Found {len(users)} user(s) matching criteria")
+            return users
+        user = User.model_validate(result)
+        logger.info(f"Found user: {user.id}")
+        return user
+
+    def delete_user(self, user_id: str) -> None:
+        """Delete a user and all associated sessions and memories.
+
+        Args:
+            user_id: ID of user to delete
+
+        Raises:
+            NotFoundError: If user doesn't exist
+        """
+        _require_non_blank(user_id, "user_id")
+
+        self._http.delete(f"/users/{user_id}")
+        logger.info(f"Deleted user: {user_id} and all associated data")
+
+
+class AsyncAgentMemoryClient:
+    """Asynchronous client for the Couchbase Agent Memory API.
+
+    Provides a hierarchical, resource-based interface for managing users,
+    sessions, and memory blocks asynchronously.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: Optional[Union[str, Callable[[], str]]] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        client_id: Optional[str] = None,
+        verify: Union[bool, str] = True,
+    ):
+        """Initialize the async Couchbase Agent Memory client.
+
+        Args:
+            base_url: Base URL of the Couchbase Agent Memory server
+            token: JWT bearer token for authentication. Can be:
+                - str: Static token string
+                - Callable[[], str]: Function that returns current token (for dynamic refresh)
+                - None: If auth is disabled in Couchbase Agent Memory server
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retries for failed requests
+            client_id: Optional client identifier for request tracking
+            verify: SSL certificate verification. Can be:
+                - True: Verify SSL certificates (default)
+                - False: Disable SSL verification (for self-signed certs in development)
+                - str: Path to a CA certificate file to trust
+        """
+        self.base_url = base_url
+        self._http = AsyncHTTPClient(
+            base_url=base_url,
+            token=token,
+            timeout=timeout,
+            max_retries=max_retries,
+            client_id=client_id,
+            verify=verify,
+        )
+        logger.info(
+            f"Async Couchbase Agent Memory client initialized: {_redact_url(base_url)}"
+        )
+
+    async def close(self) -> None:
+        """Close the client and release resources."""
+        await self._http.close()
+        logger.info("Async Couchbase Agent Memory client closed")
+
+    async def __aenter__(self) -> "AsyncAgentMemoryClient":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncAgentMemoryClient(base_url={self.base_url!r})"
+
+    # Health
+    async def health_ping(
+        self,
+        entity: Optional[HealthEntity] = None,
+    ) -> HealthPingResponse:
+        """Check health of Couchbase Agent Memory server components.
+
+        By default, checks all components and returns a combined health status.
+        Optionally specify an entity to check only that component.
+
+        Args:
+            entity: Optional specific entity to check. One of:
+                - "server": Overall server health
+                - "couchbase": Database health
+                - "models": Embedding and LLM model services
+                - "async-batch-processor": Async batch processor readiness
+                - "async-batch-processor-stats": Async batch processor statistics
+                  (underscore aliases are also accepted)
+                - "memory": Memory service health
+                If None, checks all entities.
+
+        Returns:
+            HealthPingResponse with health status for checked components
+        """
+        return await async_health_ping(self._http, entity)
+
+    # User ops
+    async def create_user(
+        self,
+        user_id: str,
+        name: str,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> AsyncUserResource:
+        """Create a new user.
+
+        Args:
+            user_id: Unique identifier for the user
+            name: Display name for the user
+            metadata: Optional metadata dictionary
+
+        Returns:
+            AsyncUserResource for performing user operations
+
+        Raises:
+            ConflictError: If user already exists
+            ValidationError: If request is invalid
+        """
+        _require_non_blank(user_id, "user_id")
+        _require_non_blank(name, "name")
+
+        payload = {"user_id": user_id, "name": name}
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        user = await self._http.post("/users", response_model=User, json=payload)
+        logger.info(f"Created user: {user_id} ({name})")
+        return AsyncUserResource(
+            self._http,
+            user_id,
+            user.name,
+            sessions=user.sessions,
+            metadata=user.metadata,
+        )
+
+    async def get_user(self, user_id: str) -> AsyncUserResource:
+        """Get a user resource hydrated from the server.
+
+        Fetches the user record so the returned resource exposes
+        name, sessions, and metadata in addition to user_id.
+
+        Args:
+            user_id: User ID
+
+        Returns:
+            AsyncUserResource for performing user operations
+
+        Raises:
+            NotFoundError: If user doesn't exist
+        """
+        _require_non_blank(user_id, "user_id")
+
+        result = await self._http.post("/users/search", json={"user_id": user_id})
+        user = User.model_validate(result)
+        logger.info(f"Retrieved user: {user_id}")
+        return AsyncUserResource(
+            self._http,
+            user_id,
+            user.name,
+            sessions=user.sessions,
+            metadata=user.metadata,
+        )
+
+    async def list_users(self) -> UserList:
+        """List all users.
+
+        Returns:
+            UserList containing all users and count
+        """
+        result = await self._http.get("/users", response_model=UserList)
+        logger.info(f"Listed {result.count} user(s)")
+        return result
+
+    async def search_users(
+        self,
+        user_id: Optional[str] = None,
+        name: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Union[User, List[User]]:
+        """Search for users by criteria.
+
+        At least one search criterion must be provided.
+
+        Args:
+            user_id: Filter by user ID
+            name: Filter by name
+            metadata: Filter by metadata fields
+
+        Returns:
+            Single User or list of Users matching criteria
+
+        Raises:
+            ValidationError: If no criteria provided
+            NotFoundError: If no users found
+        """
+        if user_id is not None and not user_id.strip():
+            raise ValidationError("user_id must not be blank if provided")
+        if name is not None and not name.strip():
+            raise ValidationError("name must not be blank if provided")
+
+        payload = {}
+        if user_id is not None:
+            payload["user_id"] = user_id
+        if name is not None:
+            payload["name"] = name
+        if metadata:
+            payload["metadata"] = metadata
+        if not payload:
+            raise ValidationError(
+                "at least one of user_id, name, or metadata must be provided"
+            )
+
+        result = await self._http.post("/users/search", json=payload)
+
+        # Handle single user vs list
+        if isinstance(result, list):
+            users = [User.model_validate(u) for u in result]
+            logger.info(f"Found {len(users)} user(s) matching criteria")
+            return users
+        user = User.model_validate(result)
+        logger.info(f"Found user: {user.id}")
+        return user
+
+    async def delete_user(self, user_id: str) -> None:
+        """Delete a user and all associated sessions and memories.
+
+        Args:
+            user_id: ID of user to delete
+
+        Raises:
+            NotFoundError: If user doesn't exist
+        """
+        _require_non_blank(user_id, "user_id")
+
+        await self._http.delete(f"/users/{user_id}")
+        logger.info(f"Deleted user: {user_id} and all associated data")

agentmemory/defaults.py

@@ -0,0 +1,12 @@
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY = 0.5
+DEFAULT_HEALTH_CHECK_TIMEOUT = 5.0
+
+DEFAULT_LIST_MEMORIES_LIMIT = 20
+DEFAULT_LIST_MEMORIES_OFFSET = 0
+DEFAULT_LIST_MEMORIES_MAX_LIMIT = 200
+DEFAULT_MEMORY_ORDER_BY = "ingested_at"
+MEMORY_ORDER_BY_FIELDS = ("ingested_at", "created_at")
+
+DEFAULT_LOG_FORMAT = "[agentmemory] %(levelname)s: %(message)s"