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

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

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

{mdb_engine-0.7.4 → mdb_engine-0.7.5}/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.4"
+__version__ = "0.7.5"
 
 __all__ = [
     # Core Engine

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

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

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

@@ -16,6 +16,14 @@ The memory service now uses an abstract base class pattern, enabling future memo
 - **📝 Type Safety**: Better IDE support and type checking with abstract base class
 - **🎯 Consistent API**: All memory providers implement the same interface
 
+### v0.7.5 Enhancements
+
+**Memory Injection and Enhanced Delete Capabilities!**
+
+- **💉 Inject Method**: New `inject()` method for manual memory insertion without LLM inference - perfect for adding facts, preferences, or structured data directly
+- **🗑️ Enhanced Delete**: Comprehensive delete functionality with improved documentation and user experience
+- **🧠 Memory Explorer UI**: Added memory explorer interface in chit_chat example with inject and delete buttons
+
 ### v0.7.4 Enhancements
 
 **Enhanced Mem0 Integration - Production Ready!**
@@ -169,6 +177,45 @@ memories = await memory_service.add_all(
 )
 ```
 
+### Inject Memory (Manual Insertion)
+
+Manually inject memories without LLM inference. This is useful when you want to directly add facts, preferences, or structured data without going through the inference pipeline:
+
+```python
+# Inject memory as a string
+memory = await memory_service.inject(
+    memory="The user prefers dark mode interfaces",
+    user_id="user123",
+    metadata={"source": "manual", "category": "preference"}
+)
+
+# Inject memory as a dict
+memory = await memory_service.inject(
+    memory={"memory": "Project deadline is next Friday", "category": "work"},
+    user_id="user123",
+    metadata={"source": "manual", "type": "deadline"}
+)
+
+# Returns: {"id": "...", "memory": "...", "metadata": {...}, ...}
+```
+
+**Key Differences from `add()`:**
+- **`inject()`**: Direct insertion without LLM inference (faster, no API costs)
+- **`add()`**: Uses LLM inference to extract facts from messages (slower, costs API calls)
+- **`inject()`**: Returns a single memory dict
+- **`add()`**: Returns a list of extracted memories
+
+**When to use `inject()`:**
+- Adding known facts or preferences directly
+- Importing structured data
+- When you want to avoid LLM inference costs
+- When you have pre-formatted memory content
+
+**When to use `add()`:**
+- Extracting memories from conversations
+- When you want the LLM to identify key facts
+- Processing unstructured text into memories
+
 ### Search Memories
 
 Semantic search across stored memories:
@@ -278,16 +325,48 @@ updated = memory_service.update(
 
 ### Delete Memory
 
-Remove memories:
+Remove memories from storage. Both methods return `True` on success, `False` on failure:
 
 ```python
-# Delete single memory
-await memory_service.delete(memory_id="memory_123", user_id="user123")
-
-# Delete all memories for user
-await memory_service.delete_all(user_id="user123")
+# Delete single memory by ID
+success = await memory_service.delete(memory_id="memory_123", user_id="user123")
+if success:
+    print("Memory deleted successfully")
+else:
+    print("Failed to delete memory (may not exist)")
+
+# Delete all memories for a user (use with caution!)
+success = await memory_service.delete_all(user_id="user123")
+if success:
+    print("All memories deleted successfully")
+
+# Delete with error handling
+try:
+    success = await memory_service.delete(memory_id="memory_123", user_id="user123")
+    if not success:
+        logger.warning(f"Memory {memory_id} not found or already deleted")
+except Mem0MemoryServiceError as e:
+    logger.error(f"Error deleting memory: {e}")
 ```
 
+**Key Features:**
+- **User Scoping**: Both methods respect `user_id` for security
+- **Safe Deletion**: Returns `False` if memory doesn't exist (doesn't raise exception)
+- **Bulk Deletion**: `delete_all()` removes all memories for a user
+- **Idempotent**: Safe to call multiple times (returns `False` if already deleted)
+
+**When to use `delete()`:**
+- Removing a specific memory by ID
+- Cleaning up outdated or incorrect memories
+- User-initiated memory removal
+
+**When to use `delete_all()`:**
+- Resetting user memory (e.g., account deletion)
+- Clearing test data
+- Bulk cleanup operations
+
+**Note**: Deletion is permanent and cannot be undone. Consider implementing soft deletes if you need to recover deleted memories.
+
 ### Bucket Organization
 
 Organize memories into buckets for better management:
@@ -481,6 +560,7 @@ memory_service = get_memory_service(
 #### Methods
 
 - `add(messages, user_id, metadata=None, bucket_id=None, bucket_type=None, store_raw_content=False, raw_content=None)` - Add single memory with optional bucket and raw content storage
+- `inject(memory, user_id, metadata=None)` - Manually inject a memory without LLM inference
 - `add_with_raw_content(messages, raw_content, user_id, bucket_id=None, bucket_type=None)` - Store both extracted facts and raw content
 - `get_buckets(user_id, bucket_type=None, limit=None)` - Get all buckets for a user
 - `get_bucket_memories(bucket_id, user_id, include_raw_content=False, limit=None)` - Get all memories in a bucket

{mdb_engine-0.7.4 → mdb_engine-0.7.5}/mdb_engine/memory/base.py

@@ -57,6 +57,36 @@ class BaseMemoryService(ABC):
         """
         pass
 
+    @abstractmethod
+    def inject(
+        self,
+        memory: str | dict[str, Any],
+        user_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Manually inject a memory without LLM inference.
+
+        This method allows direct insertion of memories without going through
+        the inference pipeline. Useful for manually adding facts, preferences,
+        or other structured data.
+
+        Args:
+            memory: Memory content as a string or dict with memory/text/content key
+            user_id: User ID for scoping (optional but recommended)
+            metadata: Additional metadata to store with the memory
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            Created memory object with ID and metadata
+
+        Raises:
+            MemoryServiceError: If injection operation fails
+            ValueError: If memory content is invalid or empty
+        """
+        pass
+
     @abstractmethod
     def get_all(
         self,

{mdb_engine-0.7.4 → mdb_engine-0.7.5}/mdb_engine/memory/service.py

@@ -4,6 +4,9 @@ Production-ready wrapper for Mem0.ai with strict metadata schema for MongoDB.
 
 v0.7.4: Enhanced with hybrid update pattern and direct MongoDB access for reliable
 memory operations. Properly handles Mem0's MongoDB structure (_id, payload).
+
+v0.7.5: Added inject() method for manual memory insertion without LLM inference,
+and enhanced delete functionality with comprehensive documentation.
 """
 
 import logging
@@ -419,6 +422,100 @@ class Mem0MemoryService(BaseMemoryService):
                 logger.exception("Mem0 Add Failed")
                 raise Mem0MemoryServiceError(f"Add failed: {e}") from e
 
+    def inject(
+        self,
+        memory: str | dict[str, Any],
+        user_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """
+        Manually inject a memory without LLM inference.
+
+        This method allows direct insertion of memories without going through
+        the inference pipeline. Useful for manually adding facts, preferences,
+        or other structured data.
+
+        Args:
+            memory: Memory content as a string or dict with memory/text/content key
+            user_id: User ID for scoping (optional but recommended)
+            metadata: Additional metadata to store with the memory
+            **kwargs: Additional provider-specific arguments
+
+        Returns:
+            Created memory object with ID and metadata
+
+        Raises:
+            Mem0MemoryServiceError: If injection operation fails
+            ValueError: If memory content is invalid or empty
+        """
+        # Normalize input: convert dict to string if needed
+        if isinstance(memory, dict):
+            # Extract memory content from dict (support multiple key formats)
+            memory_content = (
+                memory.get("memory") or memory.get("text") or memory.get("content") or str(memory)
+            )
+            if not memory_content or not isinstance(memory_content, str):
+                raise ValueError(
+                    "Memory dict must contain 'memory', 'text', or 'content' key with string value"
+                )
+            # Merge any metadata from the dict
+            if "metadata" in memory and isinstance(memory["metadata"], dict):
+                final_metadata = dict(metadata) if metadata else {}
+                final_metadata.update(memory["metadata"])
+                metadata = final_metadata
+        elif isinstance(memory, str):
+            memory_content = memory.strip()
+            if not memory_content:
+                raise ValueError("Memory content cannot be empty")
+        else:
+            raise TypeError(f"Memory must be a string or dict, got {type(memory).__name__}")
+
+        # Convert to messages format for add() method
+        messages = [{"role": "user", "content": memory_content}]
+
+        try:
+            # Call add() with infer=False to bypass LLM inference
+            logger.debug(
+                f"Injecting memory without inference for user_id={user_id}, "
+                f"memory_length={len(memory_content)}"
+            )
+            result = self.add(
+                messages=messages,
+                user_id=user_id,
+                metadata=metadata,
+                infer=False,  # Explicitly disable inference
+                **kwargs,
+            )
+
+            # Return the first created memory (normalized format)
+            if result and isinstance(result, list) and len(result) > 0:
+                injected_memory = result[0]
+                logger.info(
+                    f"Successfully injected memory with id={injected_memory.get('id')} "
+                    f"for user_id={user_id}"
+                )
+                return injected_memory
+            else:
+                # This shouldn't happen, but handle gracefully
+                logger.warning(
+                    f"add() returned empty result for inject() call. "
+                    f"user_id={user_id}, memory_length={len(memory_content)}"
+                )
+                raise Mem0MemoryServiceError("Failed to inject memory: add() returned empty result")
+        except (ValueError, TypeError):
+            # Re-raise validation errors as-is
+            raise
+        except (
+            ConnectionError,
+            OSError,
+            AttributeError,
+            RuntimeError,
+            KeyError,
+        ) as e:
+            logger.exception("Mem0 inject failed")
+            raise Mem0MemoryServiceError(f"Inject failed: {e}") from e
+
     def get_all(
         self,
         user_id: str | None = None,

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

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

{mdb_engine-0.7.4 → mdb_engine-0.7.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mdb-engine"
-version = "0.7.4"
+version = "0.7.5"
 description = "MongoDB Engine"
 readme = "README.md"
 requires-python = ">=3.10"

{mdb_engine-0.7.4 → mdb_engine-0.7.5}/setup.py

@@ -14,7 +14,7 @@ if readme_file.exists():
 
 setup(
     name="mdb-engine",
-    version="0.7.4",
+    version="0.7.5",
     description="MongoDB Engine",
     long_description=long_description,
     long_description_content_type="text/markdown",