memorer 0.4.0__tar.gz → 0.5.0__tar.gz

{memorer-0.4.0 → memorer-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memorer
-Version: 0.4.0
+Version: 0.5.0
 Summary: Semantic memory for conversational AI - remember, recall, forget. Sub-100ms retrieval with emotional ranking and graph reasoning.
 Project-URL: Homepage, https://memorer.ai
 Project-URL: Documentation, https://docs.memorer.ai

{memorer-0.4.0 → memorer-0.5.0}/memorer/__init__.py

@@ -36,9 +36,14 @@ from memorer.errors import (
     StreamingError,
     ValidationError,
 )
+from memorer.resources import ConversationClient
 from memorer.types import (
     Citation,
     ConsolidationReport,
+    Conversation,
+    ConversationContext,
+    ConversationList,
+    ConversationRecallResponse,
     DerivedMemory,
     Document,
     DuplicateGroup,
@@ -61,6 +66,8 @@ from memorer.types import (
     MemorySource,
     MemoryStats,
     MergeResponse,
+    Message,
+    MessageList,
     PaginatedResponse,
     Pagination,
     QueryResponse,
@@ -80,6 +87,7 @@ __all__ = [
     # Clients
     "Memorer",
     "UserClient",
+    "ConversationClient",
     # Errors
     "MemorerError",
     "AuthenticationError",
@@ -99,6 +107,13 @@ __all__ = [
     "RetrievalPath",
     "Scope",
     "TimingBreakdown",
+    # Conversation types
+    "Conversation",
+    "ConversationContext",
+    "ConversationList",
+    "ConversationRecallResponse",
+    "Message",
+    "MessageList",
     # Knowledge types
     "Citation",
     "Document",

{memorer-0.4.0 → memorer-0.5.0}/memorer/_config.py

@@ -4,14 +4,20 @@ Memorer SDK Configuration
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+import os
+from dataclasses import dataclass
 
 # Internal constants
-_API_BASE_URL = "https://api.memorer.ai"
+_DEFAULT_BASE_URL = "https://api.memorer.ai"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 2
 
 
+def _get_default_base_url() -> str:
+    """Get base URL from environment or use default."""
+    return os.getenv("MEMORER_BASE_URL", _DEFAULT_BASE_URL)
+
+
 @dataclass
 class ClientConfig:
     """
@@ -19,12 +25,18 @@ class ClientConfig:
 
     Args:
         api_key: API key for authentication (required).
+        base_url: API base URL. Defaults to MEMORER_BASE_URL env var
+            or https://api.memorer.ai
         timeout: Request timeout in seconds. Defaults to 30.
         max_retries: Maximum number of retries for transient failures.
             Defaults to 2. Set to 0 to disable retries.
     """
 
     api_key: str
+    base_url: str | None = None
     timeout: float = DEFAULT_TIMEOUT
     max_retries: int = DEFAULT_MAX_RETRIES
-    base_url: str = field(default=_API_BASE_URL, init=False)
+
+    def __post_init__(self) -> None:
+        if self.base_url is None:
+            self.base_url = _get_default_base_url()

{memorer-0.4.0 → memorer-0.5.0}/memorer/client.py

@@ -11,6 +11,8 @@ from typing import Any
 from memorer._config import ClientConfig
 from memorer._http import HTTPClient
 from memorer.resources import (
+    ConversationClient,
+    ConversationsResource,
     EntitiesResource,
     GraphResource,
     KnowledgeResource,
@@ -40,6 +42,7 @@ class UserClient:
         self.knowledge = KnowledgeResource(http, owner_id=owner_id)
         self.memories = MemoriesResource(http, owner_id=owner_id)
         self.entities = EntitiesResource(http, owner_id=owner_id)
+        self.conversations = ConversationsResource(http, owner_id=owner_id)
 
     @property
     def owner_id(self) -> str:
@@ -112,6 +115,33 @@ class UserClient:
         """
         self.memories.delete(memory_id)
 
+    def conversation(self, session_id: str | None = None) -> ConversationClient:
+        """
+        Get or create a conversation.
+
+        If session_id is provided, returns a client for that existing conversation.
+        If session_id is None, creates a new conversation and returns a client for it.
+
+        Args:
+            session_id: Optional conversation ID. If None, creates a new conversation.
+
+        Returns:
+            ConversationClient scoped to the conversation
+
+        Example:
+            >>> user = client.for_user("user-123")
+            >>> # Create new conversation
+            >>> conv = user.conversation()
+            >>> # Or use existing
+            >>> conv = user.conversation("conv-abc")
+            >>> conv.add("user", "Hello!")
+        """
+        if session_id is None:
+            # Create new conversation
+            new_conv = self.conversations.create()
+            return ConversationClient(self._http, self._owner_id, new_conv.id)
+        return ConversationClient(self._http, self._owner_id, session_id)
+
 
 class Memorer:
     """
@@ -143,6 +173,7 @@ class Memorer:
         self,
         api_key: str,
         *,
+        base_url: str | None = None,
         timeout: float = 30.0,
         max_retries: int = 2,
     ) -> None:
@@ -151,14 +182,19 @@ class Memorer:
 
         Args:
             api_key: Your Memorer API key (required).
+            base_url: API base URL. Defaults to MEMORER_BASE_URL env var
+                or https://api.memorer.ai. Useful for local development.
             timeout: Request timeout in seconds (default: 30)
             max_retries: Max retries for transient failures (default: 2)
 
         Example:
             >>> client = Memorer(api_key="mem_sk_...")
+            >>> # For local development:
+            >>> client = Memorer(api_key="...", base_url="http://localhost:8000")
         """
         self._config = ClientConfig(
             api_key=api_key,
+            base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
         )

{memorer-0.4.0 → memorer-0.5.0}/memorer/resources/__init__.py

@@ -4,12 +4,15 @@ Memorer SDK Resources
 All API resource classes.
 """
 
+from memorer.resources.conversations import ConversationClient, ConversationsResource
 from memorer.resources.entities import EntitiesResource
 from memorer.resources.graph import GraphResource
 from memorer.resources.knowledge import KnowledgeResource
 from memorer.resources.memories import MemoriesResource
 
 __all__ = [
+    "ConversationClient",
+    "ConversationsResource",
     "EntitiesResource",
     "GraphResource",
     "KnowledgeResource",

memorer-0.5.0/memorer/resources/conversations.py

@@ -0,0 +1,396 @@
+"""
+Conversations resource for managing conversation sessions and messages.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from memorer.resources._base import BaseResource
+from memorer.types.common import TimingBreakdown
+from memorer.types.conversations import (
+    Conversation,
+    ConversationContext,
+    ConversationList,
+    ConversationRecallResponse,
+    Message,
+    MessageList,
+)
+from memorer.types.knowledge import QueryResult
+
+if TYPE_CHECKING:
+    from memorer._http import HTTPClient
+
+
+def _parse_conversation(data: dict[str, Any]) -> Conversation:
+    """Parse raw response into Conversation."""
+    return Conversation(**data)
+
+
+def _parse_message(data: dict[str, Any]) -> Message:
+    """Parse raw response into Message."""
+    return Message(**data)
+
+
+def _parse_recall_response(data: dict[str, Any]) -> ConversationRecallResponse:
+    """Parse raw response into ConversationRecallResponse."""
+    conversation_context = [
+        ConversationContext(**c) for c in data.get("conversation_context", [])
+    ]
+    results = [QueryResult(**r) for r in data.get("results", [])]
+    timing = TimingBreakdown(**data["timing"]) if data.get("timing") else None
+
+    return ConversationRecallResponse(
+        conversation_context=conversation_context,
+        results=results,
+        context=data.get("context", ""),
+        timing=timing,
+    )
+
+
+class ConversationClient:
+    """
+    A client scoped to a specific conversation.
+
+    All operations on this client are automatically scoped to the conversation.
+
+    Example:
+        >>> user = client.for_user("user-123")
+        >>> conv = user.conversation("session-abc")
+        >>> conv.add("user", "I live in Seattle")
+        >>> result = conv.recall("where does the user live")
+    """
+
+    def __init__(
+        self,
+        http: HTTPClient,
+        owner_id: str,
+        conversation_id: str,
+    ) -> None:
+        self._http = http
+        self._owner_id = owner_id
+        self._conversation_id = conversation_id
+
+    @property
+    def id(self) -> str:
+        """The conversation ID."""
+        return self._conversation_id
+
+    def add(
+        self,
+        role: Literal["user", "assistant", "system"],
+        content: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+        extract_memories: bool = True,
+    ) -> Message:
+        """
+        Add a message to the conversation.
+
+        Args:
+            role: Who sent the message ("user", "assistant", or "system")
+            content: The message content
+            metadata: Optional metadata to attach
+            extract_memories: Auto-extract memories from the message (default: True)
+
+        Returns:
+            The created Message
+
+        Example:
+            >>> conv.add("user", "I just moved to Seattle")
+            >>> conv.add("assistant", "Welcome to Seattle!")
+        """
+        data: dict[str, Any] = {
+            "role": role,
+            "content": content,
+            "extract_memories": extract_memories,
+        }
+        if metadata:
+            data["metadata"] = metadata
+
+        response = self._http.post(
+            f"/v1/sdk/conversations/{self._conversation_id}/messages",
+            json_data=data,
+        )
+        return _parse_message(response)
+
+    def add_batch(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        extract_memories: bool = True,
+    ) -> MessageList:
+        """
+        Add multiple messages at once.
+
+        Args:
+            messages: List of message dicts with "role" and "content" keys
+            extract_memories: Auto-extract memories from messages (default: True)
+
+        Returns:
+            MessageList with all created messages
+
+        Example:
+            >>> conv.add_batch([
+            ...     {"role": "user", "content": "Hello"},
+            ...     {"role": "assistant", "content": "Hi there!"},
+            ... ])
+        """
+        data: dict[str, Any] = {
+            "messages": messages,
+            "extract_memories": extract_memories,
+        }
+        response = self._http.post(
+            f"/v1/sdk/conversations/{self._conversation_id}/messages/batch",
+            json_data=data,
+        )
+        return MessageList(
+            count=response.get("count", 0),
+            messages=[_parse_message(m) for m in response.get("messages", [])],
+        )
+
+    def messages(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> MessageList:
+        """
+        Get messages in the conversation.
+
+        Args:
+            limit: Maximum messages to return (default: 50)
+            offset: Pagination offset
+
+        Returns:
+            MessageList in chronological order (oldest first)
+
+        Example:
+            >>> messages = conv.messages(limit=20)
+            >>> for m in messages.messages:
+            ...     print(f"[{m.role}]: {m.content}")
+        """
+        response = self._http.get(
+            f"/v1/sdk/conversations/{self._conversation_id}/messages",
+            params={"limit": limit, "offset": offset},
+        )
+        return MessageList(
+            count=response.get("count", 0),
+            messages=[_parse_message(m) for m in response.get("messages", [])],
+        )
+
+    def recall(
+        self,
+        query: str,
+        *,
+        include_conversation_context: bool = True,
+        max_recent_messages: int = 10,
+        top_k: int = 10,
+        use_cache: bool = True,
+        use_reranker: bool = False,
+        use_graph_reasoning: bool = False,
+    ) -> ConversationRecallResponse:
+        """
+        Query with conversation context + long-term memories.
+
+        Combines recent messages (short-term) with semantic memory search (long-term).
+
+        Args:
+            query: What to recall
+            include_conversation_context: Include recent messages (default: True)
+            max_recent_messages: Number of recent messages to include (default: 10)
+            top_k: Number of semantic results (default: 10)
+            use_cache: Enable semantic cache (default: True)
+            use_reranker: Enable cross-encoder reranking (default: False)
+            use_graph_reasoning: Enable graph traversal (default: False)
+
+        Returns:
+            ConversationRecallResponse with conversation context, results, and assembled context
+
+        Example:
+            >>> result = conv.recall("where does the user live")
+            >>> print(result.context)  # Combined context for LLM
+        """
+        data: dict[str, Any] = {
+            "query": query,
+            "include_conversation_context": include_conversation_context,
+            "max_recent_messages": max_recent_messages,
+            "top_k": top_k,
+            "use_cache": use_cache,
+            "use_reranker": use_reranker,
+            "use_graph_reasoning": use_graph_reasoning,
+        }
+        response = self._http.post(
+            f"/v1/sdk/conversations/{self._conversation_id}/recall",
+            json_data=data,
+        )
+        return _parse_recall_response(response)
+
+    def get(self) -> Conversation:
+        """
+        Get the conversation details.
+
+        Returns:
+            Conversation with current state
+        """
+        response = self._http.get(f"/v1/sdk/conversations/{self._conversation_id}")
+        return _parse_conversation(response)
+
+    def update(
+        self,
+        *,
+        title: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Conversation:
+        """
+        Update conversation title or metadata.
+
+        Args:
+            title: New title (optional)
+            metadata: Metadata to merge (optional)
+
+        Returns:
+            Updated Conversation
+        """
+        data: dict[str, Any] = {}
+        if title is not None:
+            data["title"] = title
+        if metadata is not None:
+            data["metadata"] = metadata
+
+        response = self._http.request(
+            "PATCH",
+            f"/v1/sdk/conversations/{self._conversation_id}",
+            json_data=data,
+        )
+        return _parse_conversation(response)
+
+    def delete(self) -> None:
+        """Delete (soft-delete) the conversation."""
+        self._http.delete(f"/v1/sdk/conversations/{self._conversation_id}")
+
+
+class ConversationsResource(BaseResource):
+    """
+    Conversations resource for managing conversation sessions.
+
+    Example:
+        >>> user = client.for_user("user-123")
+        >>> conv = user.conversations.create()
+        >>> conv_list = user.conversations.list()
+    """
+
+    def create(
+        self,
+        *,
+        external_id: str | None = None,
+        title: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Conversation:
+        """
+        Create a new conversation.
+
+        Args:
+            external_id: Optional client-provided ID for idempotency
+            title: Optional title
+            metadata: Optional metadata dict
+
+        Returns:
+            The created Conversation
+
+        Example:
+            >>> conv = user.conversations.create(
+            ...     external_id="session-123",
+            ...     title="Support Chat",
+            ... )
+        """
+        if not self._owner_id:
+            raise ValueError(
+                "owner_id is required. Use client.for_user(owner_id) to create a scoped client."
+            )
+
+        data: dict[str, Any] = {"owner_id": self._owner_id}
+        if external_id:
+            data["external_id"] = external_id
+        if title:
+            data["title"] = title
+        if metadata:
+            data["metadata"] = metadata
+
+        response = self._post("/v1/sdk/conversations", json_data=data)
+        return _parse_conversation(response)
+
+    def list(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> ConversationList:
+        """
+        List conversations for the current owner.
+
+        Args:
+            limit: Maximum conversations to return (default: 50)
+            offset: Pagination offset
+
+        Returns:
+            ConversationList ordered by most recent activity
+
+        Example:
+            >>> conversations = user.conversations.list(limit=10)
+            >>> for c in conversations.conversations:
+            ...     print(f"{c.title}: {c.message_count} messages")
+        """
+        if not self._owner_id:
+            raise ValueError(
+                "owner_id is required. Use client.for_user(owner_id) to create a scoped client."
+            )
+
+        params: dict[str, Any] = {
+            "owner_id": self._owner_id,
+            "limit": limit,
+            "offset": offset,
+        }
+        response = self._get("/v1/sdk/conversations", params=params)
+        return ConversationList(
+            count=response.get("count", 0),
+            conversations=[_parse_conversation(c) for c in response.get("conversations", [])],
+        )
+
+    def get(self, conversation_id: str) -> Conversation:
+        """
+        Get a conversation by ID.
+
+        Args:
+            conversation_id: UUID of the conversation
+
+        Returns:
+            Conversation details
+        """
+        response = self._get(f"/v1/sdk/conversations/{conversation_id}")
+        return _parse_conversation(response)
+
+    def delete(self, conversation_id: str) -> None:
+        """
+        Delete (soft-delete) a conversation.
+
+        Args:
+            conversation_id: UUID of the conversation
+        """
+        self._delete(f"/v1/sdk/conversations/{conversation_id}")
+
+    def client(self, conversation_id: str) -> ConversationClient:
+        """
+        Get a client scoped to a specific conversation.
+
+        Args:
+            conversation_id: UUID of the conversation
+
+        Returns:
+            ConversationClient for the conversation
+        """
+        if not self._owner_id:
+            raise ValueError(
+                "owner_id is required. Use client.for_user(owner_id) to create a scoped client."
+            )
+        return ConversationClient(self._http, self._owner_id, conversation_id)

{memorer-0.4.0 → memorer-0.5.0}/memorer/types/__init__.py

@@ -13,6 +13,14 @@ from .common import (
     Scope,
     TimingBreakdown,
 )
+from .conversations import (
+    Conversation,
+    ConversationContext,
+    ConversationList,
+    ConversationRecallResponse,
+    Message,
+    MessageList,
+)
 from .entities import (
     DuplicateGroup,
     DuplicatesResponse,
@@ -58,6 +66,13 @@ __all__ = [
     "RetrievalPath",
     "Scope",
     "TimingBreakdown",
+    # Conversations
+    "Conversation",
+    "ConversationContext",
+    "ConversationList",
+    "ConversationRecallResponse",
+    "Message",
+    "MessageList",
     # Knowledge
     "Citation",
     "Document",

memorer-0.5.0/memorer/types/conversations.py

@@ -0,0 +1,70 @@
+"""
+Conversation and Message types for conversation support.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from memorer.types.common import TimingBreakdown
+from memorer.types.knowledge import QueryResult
+
+
+class Message(BaseModel):
+    """A message in a conversation."""
+
+    id: str
+    conversation_id: str
+    role: Literal["user", "assistant", "system"]
+    content: str
+    metadata: dict[str, Any] | None = None
+    created_at: datetime
+    extracted_entity_ids: list[str] | None = None
+
+
+class MessageList(BaseModel):
+    """Paginated list of messages."""
+
+    count: int
+    messages: list[Message]
+
+
+class Conversation(BaseModel):
+    """A conversation session."""
+
+    id: str
+    owner_id: str
+    external_id: str | None = None
+    title: str | None = None
+    metadata: dict[str, Any] | None = None
+    message_count: int = 0
+    started_at: datetime
+    last_message_at: datetime | None = None
+    created_at: datetime
+
+
+class ConversationList(BaseModel):
+    """Paginated list of conversations."""
+
+    count: int
+    conversations: list[Conversation]
+
+
+class ConversationContext(BaseModel):
+    """Message in conversation context format."""
+
+    role: str
+    content: str
+    timestamp: str
+
+
+class ConversationRecallResponse(BaseModel):
+    """Response from recall with conversation context."""
+
+    conversation_context: list[ConversationContext] = Field(default_factory=list)
+    results: list[QueryResult] = Field(default_factory=list)
+    context: str = ""
+    timing: TimingBreakdown | None = None

{memorer-0.4.0 → memorer-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memorer"
-version = "0.4.0"
+version = "0.5.0"
 description = "Semantic memory for conversational AI - remember, recall, forget. Sub-100ms retrieval with emotional ranking and graph reasoning."
 readme = "README.md"
 requires-python = ">=3.9"