mdb-engine 0.7.3__tar.gz → 0.7.4__tar.gz

{mdb_engine-0.7.3/mdb_engine.egg-info → mdb_engine-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mdb-engine
-Version: 0.7.3
+Version: 0.7.4
 Summary: MongoDB Engine
 Home-page: https://github.com/ranfysvalle02/mdb-engine
 Author: Fabian Valle

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/__init__.py

@@ -81,7 +81,7 @@ from .repositories import Entity, MongoRepository, Repository, UnitOfWork
 # Utilities
 from .utils import clean_mongo_doc, clean_mongo_docs
 
-__version__ = "0.7.3"
+__version__ = "0.7.4"
 
 __all__ = [
     # Core Engine

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/cli/main.py

@@ -15,7 +15,7 @@ from .commands.validate import validate
 
 
 @click.group()
-@click.version_option(version="0.7.3", prog_name="mdb")
+@click.version_option(version="0.7.4", prog_name="mdb")
 def cli() -> None:
     """
     MDB_ENGINE CLI - Manifest management tool.

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/core/engine.py

@@ -910,13 +910,14 @@ class MongoDBEngine:
 
     def get_memory_service(self, slug: str) -> Any | None:
         """
-        Get Mem0 memory service for an app.
+        Get memory service for an app (returns BaseMemoryService instance).
 
         Args:
             slug: App slug
 
         Returns:
-            Mem0MemoryService instance if memory is enabled for this app, None otherwise
+            BaseMemoryService instance (currently Mem0MemoryService) if memory is enabled
+            for this app, None otherwise
 
         Example:
             ```python

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/core/service_initialization.py

@@ -63,10 +63,10 @@ class ServiceInitializer:
         self, slug: str, memory_config: dict[str, Any] | None
     ) -> None:
         """
-        Initialize Mem0 memory service for an app.
+        Initialize memory service for an app (defaults to Mem0 implementation).
 
         Memory support is OPTIONAL - only processes if dependencies are available.
-        mem0 handles embeddings and LLM via environment variables (.env).
+        Currently uses Mem0.ai which handles embeddings and LLM via environment variables (.env).
 
         Args:
             slug: App slug
@@ -356,13 +356,14 @@ class ServiceInitializer:
 
     def get_memory_service(self, slug: str) -> Any | None:
         """
-        Get Mem0 memory service for an app.
+        Get memory service for an app (returns BaseMemoryService instance).
 
         Args:
             slug: App slug
 
         Returns:
-            Mem0MemoryService instance if memory is enabled for this app, None otherwise
+            BaseMemoryService instance (currently Mem0MemoryService) if memory is enabled
+            for this app, None otherwise
         """
         try:
             service = self._memory_services.get(slug)

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/core/types.py

@@ -11,9 +11,9 @@ This module is part of MDB_ENGINE - MongoDB Engine.
 from typing import TYPE_CHECKING, Any, Literal, TypedDict
 
 if TYPE_CHECKING:
-    from ..memory import Mem0MemoryService
+    from ..memory import BaseMemoryService
 else:
-    Mem0MemoryService = Any
+    BaseMemoryService = Any
 
 
 # ============================================================================

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/dependencies.py

@@ -33,7 +33,7 @@ if TYPE_CHECKING:
     from .core.engine import MongoDBEngine
     from .database.scoped_wrapper import ScopedMongoWrapper
     from .embeddings.service import EmbeddingService
-    from .memory.service import Mem0MemoryService
+    from .memory import BaseMemoryService
 
 logger = logging.getLogger(__name__)
 
@@ -121,8 +121,8 @@ async def get_embedding_service(request: Request) -> "EmbeddingService":
         raise HTTPException(503, f"Failed to initialize embedding service: {e}") from e
 
 
-async def get_memory_service(request: Request) -> Optional["Mem0MemoryService"]:
-    """Get the Mem0 memory service if configured."""
+async def get_memory_service(request: Request) -> Optional["BaseMemoryService"]:
+    """Get the memory service if configured (defaults to Mem0 implementation)."""
     engine = getattr(request.app.state, "engine", None)
     slug = getattr(request.app.state, "app_slug", None)
     if not engine or not slug:

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/memory/README.md

@@ -2,9 +2,37 @@
 
 Mem0.ai integration for intelligent memory management in MDB_ENGINE applications. Provides semantic memory storage, retrieval, and inference capabilities with MongoDB integration.
 
+## 🎉 What's New
+
+### Extensible Architecture (Latest)
+
+**Base Class Pattern for Future Extensibility!**
+
+The memory service now uses an abstract base class pattern, enabling future memory provider implementations while maintaining backward compatibility:
+
+- **🏗️ BaseMemoryService**: Abstract base class defining the memory service interface
+- **🔌 Provider Extensibility**: Easy to add new memory providers (LangChain, custom implementations, etc.)
+- **✅ Backward Compatible**: All existing code continues to work without changes
+- **📝 Type Safety**: Better IDE support and type checking with abstract base class
+- **🎯 Consistent API**: All memory providers implement the same interface
+
+### v0.7.4 Enhancements
+
+**Enhanced Mem0 Integration - Production Ready!**
+
+- **🔧 Hybrid Update Pattern**: Content updates via Mem0 (triggers re-embedding), metadata updates via direct MongoDB (full control, no API limitations)
+- **📊 Direct MongoDB Access**: Reliable data retrieval directly from MongoDB, bypassing Mem0 API inconsistencies
+- **🏷️ Full Metadata Support**: Update any metadata field without restrictions - not limited by Mem0's API
+- **✅ Correct Mem0 Structure**: Properly handles Mem0's MongoDB structure (`_id` as document ID, `payload` for memory data)
+- **🛡️ Robust Error Handling**: Specific exception handling with proper KeyboardInterrupt/SystemExit propagation
+- **🔍 Reliable Returns**: Always returns normalized documents fetched directly from MongoDB (guaranteed structure)
+
+> 📖 **Want to understand why we use manual MongoDB access?** See the [Mem0 Implementation Guide](../../docs/guides/MEM0_IMPLEMENTATION.md) for detailed explanations of our architectural decisions, Mem0's MongoDB structure, and things to watch out for.
+
 ## Features
 
-- **Mem0 Integration**: Wrapper around Mem0.ai for intelligent memory management
+- **Extensible Architecture**: Base class pattern allows for multiple memory provider implementations
+- **Mem0 Integration**: Default implementation using Mem0.ai for intelligent memory management
 - **MongoDB Storage**: Built-in MongoDB vector store integration
 - **Auto-Detection**: Automatically detects OpenAI or Azure OpenAI from environment variables
 - **Semantic Search**: Vector-based semantic memory search
@@ -67,7 +95,7 @@ Enable memory service in your `manifest.json`:
 ### Basic Usage
 
 ```python
-from mdb_engine.memory import Mem0MemoryService
+from mdb_engine.memory import BaseMemoryService  # Base class for type hints
 from mdb_engine.core import MongoDBEngine
 
 # Initialize engine
@@ -75,7 +103,8 @@ engine = MongoDBEngine(mongo_uri="...", db_name="...")
 await engine.initialize()
 
 # Get memory service (automatically configured from manifest)
-memory_service = engine.get_memory_service("my_app")
+# Returns BaseMemoryService instance (currently Mem0MemoryService)
+memory_service: BaseMemoryService = engine.get_memory_service("my_app")
 
 # Add memory
 memory = await memory_service.add(
@@ -163,14 +192,17 @@ results = await memory_service.search(
 
 ### Get Memories
 
-Retrieve memories for a user:
+Retrieve memories for a user. The service automatically normalizes Mem0's MongoDB structure (`_id`, `payload`) into a consistent API format:
 
 ```python
 # Get all memories
 all_memories = await memory_service.get_all(user_id="user123")
+# Returns normalized format: [{"id": "...", "memory": "...", "metadata": {...}, ...}]
 
 # Get specific memory
 memory = await memory_service.get(memory_id="memory_123", user_id="user123")
+# Returns normalized format: {"id": "...", "memory": "...", "metadata": {...}, ...}
+# Note: memory_id can be either Mem0's _id or the normalized id field
 
 # Get memories with filters
 memories = await memory_service.get_all(
@@ -179,9 +211,16 @@ memories = await memory_service.get_all(
 )
 ```
 
+**Note**: The service handles Mem0's internal MongoDB structure (`_id` as document ID, `payload` containing memory data) automatically. All methods return normalized documents with consistent `id`, `memory`, `text`, and `metadata` fields.
+
 ### Update Memory
 
-Update existing memories in-place while preserving the original memory ID and creation timestamp:
+Update existing memories using a **hybrid approach** that combines Mem0's embedding capabilities with direct MongoDB control:
+
+**Architecture:**
+- **Content Updates**: Routed via Mem0 (triggers automatic re-embedding)
+- **Metadata Updates**: Routed via direct PyMongo (full control, no API limitations)
+- **Return Value**: Always fetched from MongoDB (guaranteed correct structure)
 
 ```python
 # Update memory content and metadata
@@ -200,14 +239,21 @@ updated = memory_service.update(
     metadata={"updated": True}
 )
 
-# Update only metadata (content unchanged)
+# Update only metadata (content unchanged) - FULLY SUPPORTED
+updated = memory_service.update(
+    memory_id="memory_123",
+    user_id="user123",
+    metadata={"category": "updated", "priority": "high"}
+)
+
+# Update only content (no metadata changes)
 updated = memory_service.update(
     memory_id="memory_123",
     user_id="user123",
-    metadata={"category": "updated"}
+    memory="Updated content only"
 )
 
-# Backward compatibility: using 'data' parameter
+# Using 'data' parameter
 updated = memory_service.update(
     memory_id="memory_123",
     user_id="user123",
@@ -217,12 +263,18 @@ updated = memory_service.update(
 ```
 
 **Key Features:**
+- **Hybrid Architecture**: Mem0 handles embeddings, MongoDB handles data persistence
+- **Full Metadata Support**: Update any metadata field (not limited by Mem0 API)
 - **Preserves Memory ID**: The original memory ID is maintained
 - **Preserves Creation Timestamp**: `created_at` is not modified
 - **Updates Timestamp**: `updated_at` is automatically set to current time
-- **Recomputes Embeddings**: If content changes, the embedding vector is automatically recomputed
-- **Metadata Merging**: New metadata is merged with existing metadata (doesn't replace)
+- **Recomputes Embeddings**: If content changes, the embedding vector is automatically recomputed via Mem0
+- **Reliable Returns**: Always returns the actual document from MongoDB (not Mem0's response format)
 - **Partial Updates**: Can update content only, metadata only, or both
+- **Security**: Validates user_id ownership before allowing updates
+- **Mem0 Structure Aware**: Correctly handles Mem0's MongoDB structure (`_id` as document ID, `payload` for memory data)
+- **Direct MongoDB Access**: Uses PyMongo for reliable data operations, ensuring consistency
+- **Normalized Responses**: All methods return consistent document structure regardless of Mem0's internal format
 
 ### Delete Memory
 
@@ -336,25 +388,93 @@ for memory in insights:
     print(f"Insights: {memory.get('insights')}")
 ```
 
+## Architecture
+
+### Base Class Pattern
+
+The memory service uses an abstract base class pattern for extensibility:
+
+```python
+from mdb_engine.memory import BaseMemoryService, MemoryServiceError
+
+# BaseMemoryService defines the interface
+# Mem0MemoryService implements it (default provider)
+# Future providers can inherit from BaseMemoryService
+```
+
+**Benefits:**
+- **Type Safety**: Use `BaseMemoryService` for type hints
+- **Extensibility**: Easy to add new providers (LangChain, custom, etc.)
+- **Consistency**: All providers implement the same interface
+- **Backward Compatible**: Existing code works without changes
+
+### Creating Custom Memory Providers
+
+To create a custom memory provider, inherit from `BaseMemoryService`:
+
+```python
+from mdb_engine.memory import BaseMemoryService, MemoryServiceError
+
+class CustomMemoryService(BaseMemoryService):
+    """Custom memory service implementation."""
+    
+    def __init__(self, mongo_uri: str, db_name: str, app_slug: str, config: dict | None = None):
+        # Initialize your custom implementation
+        pass
+    
+    def add(self, messages, user_id=None, metadata=None, **kwargs):
+        # Implement add method
+        pass
+    
+    # Implement all other abstract methods...
+    def get_all(self, user_id=None, limit=100, filters=None, **kwargs):
+        pass
+    
+    def search(self, query, user_id=None, limit=5, filters=None, **kwargs):
+        pass
+    
+    def get(self, memory_id, user_id=None, **kwargs):
+        pass
+    
+    def delete(self, memory_id, user_id=None, **kwargs):
+        pass
+    
+    def delete_all(self, user_id=None, **kwargs):
+        pass
+    
+    def update(self, memory_id, user_id=None, memory=None, metadata=None, **kwargs):
+        pass
+```
+
 ## API Reference
 
+### BaseMemoryService
+
+Abstract base class for all memory service implementations. Defines the standard interface.
+
 ### Mem0MemoryService
 
+Default implementation using Mem0.ai. Inherits from `BaseMemoryService`.
+
 #### Initialization
 
 ```python
 Mem0MemoryService(
     mongo_uri: str,
     db_name: str,
-    collection_name: str = "memories",
-    app_slug: str = None,
-    embedding_model: str = "text-embedding-3-small",
-    embedding_dimensions: int = None,
-    chat_model: str = "gpt-4",
-    temperature: float = 0.7,
-    infer: bool = True,
-    enable_graph: bool = False,
-    config: dict = None
+    app_slug: str,
+    config: dict = None  # Optional configuration
+)
+
+# Or use the factory function
+from mdb_engine.memory import get_memory_service
+
+memory_service = get_memory_service(
+    mongo_uri="...",
+    db_name="...",
+    app_slug="...",
+    config={...},
+    provider="mem0"  # Default, future providers can be specified here
 )
 ```
 
@@ -513,15 +633,19 @@ knowledge = await memory_service.search(
 ## Error Handling
 
 ```python
-from mdb_engine.memory import Mem0MemoryServiceError
+from mdb_engine.memory import MemoryServiceError, Mem0MemoryServiceError
 
 try:
     memory = await memory_service.add(
         messages=[{"role": "user", "content": "Test"}],
         user_id="user123"
     )
-except Mem0MemoryServiceError as e:
+except MemoryServiceError as e:
+    # Base exception for all memory service errors
     print(f"Memory service error: {e}")
+except Mem0MemoryServiceError as e:
+    # Specific exception for Mem0 implementation
+    print(f"Mem0 memory service error: {e}")
 except (ValueError, TypeError, ConnectionError) as e:
     print(f"Configuration or connection error: {e}")
 ```

{mdb_engine-0.7.3 → mdb_engine-0.7.4}/mdb_engine/memory/__init__.py

@@ -14,16 +14,25 @@ Key Features:
 - **Optional LLM Inference**: Can leverage LLM service for automatic memory
   extraction (set infer: false to disable)
 - **Graph Support**: Optional knowledge graph construction for entity relationships
+- **Extensible Architecture**: Base class allows for future memory provider implementations
 
 Dependencies:
     pip install mem0ai
 """
 
+# Import base classes
+from .base import BaseMemoryService, MemoryServiceError
+
 # Import service components (mem0 import is lazy within service.py)
 from .service import Mem0MemoryService, Mem0MemoryServiceError, get_memory_service
 
 __all__ = [
+    # Base classes (for extensibility)
+    "BaseMemoryService",
+    "MemoryServiceError",
+    # Mem0 implementation (default)
     "Mem0MemoryService",
     "Mem0MemoryServiceError",
+    # Factory function
     "get_memory_service",
 ]

mdb_engine-0.7.4/mdb_engine/memory/base.py

@@ -0,0 +1,194 @@
+"""
+Base Memory Service Interface
+
+Abstract base class for memory service implementations.
+This allows for extensibility with different memory providers (Mem0, LangChain, custom, etc.)
+while maintaining a consistent API.
+
+This module is part of MDB_ENGINE - MongoDB Engine.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class MemoryServiceError(Exception):
+    """Base exception for all memory service errors."""
+
+    pass
+
+
+class BaseMemoryService(ABC):
+    """
+    Abstract base class for memory service implementations.
+
+    This class defines the interface that all memory service implementations must follow.
+    Concrete implementations (e.g., Mem0MemoryService) inherit from this class and
+    implement the abstract methods.
+
+    All memory operations are scoped per user_id for safety and data isolation.
+    """
+
+    @abstractmethod
+    def add(
+        self,
+        messages: str | list[dict[str, str]],
+        user_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        bucket_id: str | None = None,
+        bucket_type: str | None = None,
+        raw_content: str | None = None,
+        **kwargs,
+    ) -> list[dict[str, Any]]:
+        """
+        Add memories with user scoping and metadata convenience.
+
+        Args:
+            messages: Memory content as a string or list of message dicts
+            user_id: User ID for scoping (optional but recommended)
+            metadata: Additional metadata to store with the memory
+            bucket_id: Bucket ID for organizing memories
+            bucket_type: Type of bucket (e.g., "general", "file", "conversation")
+            raw_content: Raw content to store alongside extracted facts
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            List of created memory objects with their IDs and metadata
+        """
+        pass
+
+    @abstractmethod
+    def get_all(
+        self,
+        user_id: str | None = None,
+        limit: int = 100,
+        filters: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> list[dict[str, Any]]:
+        """
+        Get all memories with optional filtering.
+
+        Args:
+            user_id: User ID to filter memories (optional)
+            limit: Maximum number of memories to return
+            filters: Additional filters to apply (provider-specific)
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            List of memory objects
+        """
+        pass
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        user_id: str | None = None,
+        limit: int = 5,
+        filters: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> list[dict[str, Any]]:
+        """
+        Perform semantic search across memories.
+
+        Args:
+            query: Search query string
+            user_id: User ID to scope search (optional)
+            limit: Maximum number of results to return
+            filters: Additional metadata filters to apply
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            List of memory objects matching the query, ordered by relevance
+        """
+        pass
+
+    @abstractmethod
+    def get(
+        self,
+        memory_id: str,
+        user_id: str | None = None,
+        **kwargs,
+    ) -> dict[str, Any] | None:
+        """
+        Get a single memory by ID.
+
+        Args:
+            memory_id: Unique identifier for the memory
+            user_id: User ID for security scoping (optional)
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            Memory object if found, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    def delete(
+        self,
+        memory_id: str,
+        user_id: str | None = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Delete a single memory by ID.
+
+        Args:
+            memory_id: Unique identifier for the memory to delete
+            user_id: User ID for security scoping (optional)
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            True if deletion was successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def delete_all(
+        self,
+        user_id: str | None = None,
+        **kwargs,
+    ) -> bool:
+        """
+        Delete all memories for a user.
+
+        Args:
+            user_id: User ID whose memories should be deleted (optional)
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            True if deletion was successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def update(
+        self,
+        memory_id: str,
+        user_id: str | None = None,
+        memory: str | None = None,
+        data: str | dict[str, Any] | None = None,
+        messages: str | list[dict[str, str]] | None = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> dict[str, Any] | None:
+        """
+        Update an existing memory's content and/or metadata.
+
+        Args:
+            memory_id: Unique identifier for the memory to update (required)
+            user_id: User ID for security scoping (optional)
+            memory: New memory content as a string (optional)
+            data: Alternative parameter for content (string or dict) (optional)
+            messages: Alternative way to provide content as messages (optional)
+            metadata: Metadata updates (optional)
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            Updated memory object if successful, None if memory not found
+
+        Raises:
+            MemoryServiceError: If update operation fails
+            ValueError: If memory_id is invalid or empty
+        """
+        pass