mdb-engine 0.7.4__py3-none-any.whl → 0.7.5__py3-none-any.whl

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/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/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/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/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.dist-info → mdb_engine-0.7.5.dist-info}/METADATA

@@ -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.dist-info → mdb_engine-0.7.5.dist-info}/RECORD

@@ -1,5 +1,5 @@
 mdb_engine/README.md,sha256=T3EFGcPopY9LslYW3lxgG3hohWkAOmBNbYG0FDMUJiY,3502
-mdb_engine/__init__.py,sha256=OkNHx17I4f8jI5IAJGK0HbSTrZrUVnl1QlvtPZLri-I,3097
+mdb_engine/__init__.py,sha256=hBCXmvmuddGc2c_heZv75UyxP3rDSi4PViu596O-16I,3097
 mdb_engine/config.py,sha256=DTAyxfKB8ogyI0v5QR9Y-SJOgXQr_eDBCKxNBSqEyLc,7269
 mdb_engine/constants.py,sha256=eaotvW57TVOg7rRbLziGrVNoP7adgw_G9iVByHezc_A,7837
 mdb_engine/dependencies.py,sha256=F2_hbtK-lyeqB_iPeJVCh8jFbHi7sx0fduCUCNCKoUc,14128
@@ -35,7 +35,7 @@ mdb_engine/auth/utils.py,sha256=YkexCo0xV37mpOJUI32cntRHVOUUS7r19TIMPWHcgpA,2734
 mdb_engine/auth/websocket_sessions.py,sha256=7eFNagY2K3Rp1x7d_cO5JcpT-DrYkc__cmVhl6pAC2M,15081
 mdb_engine/auth/websocket_tickets.py,sha256=VoIArcnQBtYqXRMs-5m7NSvCJB1dEeHrLl7j7yG-H-A,9887
 mdb_engine/cli/__init__.py,sha256=PANRi4THmL34d1mawlqxIrnuItXMdqoMTq5Z1zHd7rM,301
-mdb_engine/cli/main.py,sha256=4etDTeg4DIPQQ5HdWIwcpg9FWLx21NXF6f2fj4xG8gQ,811
+mdb_engine/cli/main.py,sha256=nT1Ws3jzYLblnHMXotqoPKaeI8CZlaek-fOOL0nFfAg,811
 mdb_engine/cli/utils.py,sha256=bNRGJgdzxUjXAOVe1aoxWJ5M_IqtAE-eW4pfAkwiDDM,2760
 mdb_engine/cli/commands/__init__.py,sha256=ZSzMhKdV9ILD5EbOSxDV9nURHo1e4bQ0c8AWpqsTEqM,115
 mdb_engine/cli/commands/generate.py,sha256=VEcn7qNQkIPQlLEK3oXUBgYMwD-G0FyomXQcWTtKsbs,17304
@@ -74,10 +74,10 @@ mdb_engine/indexes/README.md,sha256=r7duq-1vtqHhBk1cwoBMYYh_dfTzxiaQaPE3mLB_3JQ,
 mdb_engine/indexes/__init__.py,sha256=9QFJ6qo_yD26dZcKyKjj-hhesFpaomBt-mWTtYTQvqc,613
 mdb_engine/indexes/helpers.py,sha256=tJHqDm18jKLrW-P2ofmnUnaf4_-V5xDLjqP_WU8W9MM,4190
 mdb_engine/indexes/manager.py,sha256=ekrYBfKD-GOBpZMjXIZWSQ7UPLgrD5BINYzVteWkSI8,32508
-mdb_engine/memory/README.md,sha256=3NqI-Sm8Cy-4lsU1wAWxSg92XpRFK19OfDU_dLo3go0,20581
+mdb_engine/memory/README.md,sha256=-HTYbBF4SQICvimThgfyNIc4mUVXnNmGpJpkKZZQnWo,23842
 mdb_engine/memory/__init__.py,sha256=VEB8PuNBB6q1mSlIYXv9xWt14YmxdiSV5D9hrgmMW94,1328
-mdb_engine/memory/base.py,sha256=bI1Rl14mEAsRSMKe8_3jxzrs-N8LGdYWPwXXRziRDLs,5759
-mdb_engine/memory/service.py,sha256=9uReFG5FaTIs7Fl6Kz7sXES4Uj_4ao7bgcfs32Nvd9U,37164
+mdb_engine/memory/base.py,sha256=JXpACAB6gHb4jZPbxcSoltmIh1wsAv36qWOFCYN6LuQ,6768
+mdb_engine/memory/service.py,sha256=E1xsLrWp1s0_a_3YbT6AV8YDw7BJJxQ8Ea_Vt38ibOI,41201
 mdb_engine/observability/README.md,sha256=CMgQaC1H8ESmCitfbhJifz6-XoXH_FPNE4MvuZ-oFas,13085
 mdb_engine/observability/__init__.py,sha256=jjLsrW6Gy2ayrbfLrgHsDB61NxWWkYLHwv0q-N3fxjA,1213
 mdb_engine/observability/health.py,sha256=ORjxF_rHYA9vCoxUqel5p0n9g3PLmHsHQn68Q402b6g,9212
@@ -92,9 +92,9 @@ mdb_engine/routing/__init__.py,sha256=reupjHi_RTc2ZBA4AH5XzobAmqy4EQIsfSUcTkFknU
 mdb_engine/routing/websockets.py,sha256=w0m1XMpXKPpPrEBcZNIj8B8PwWeTNrseUZE1P8cipdM,53441
 mdb_engine/utils/__init__.py,sha256=lDxQSGqkV4fVw5TWIk6FA6_eey_ZnEtMY0fir3cpAe8,236
 mdb_engine/utils/mongo.py,sha256=Oqtv4tQdpiiZzrilGLEYQPo8Vmh8WsTQypxQs8Of53s,3369
-mdb_engine-0.7.4.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
-mdb_engine-0.7.4.dist-info/METADATA,sha256=T67AUeMaWC1ybxcQRAbPlYgKv9S5yWOJpWsIGCJVyrI,18843
-mdb_engine-0.7.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-mdb_engine-0.7.4.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
-mdb_engine-0.7.4.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
-mdb_engine-0.7.4.dist-info/RECORD,,
+mdb_engine-0.7.5.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+mdb_engine-0.7.5.dist-info/METADATA,sha256=H7O6Pdyms68A2xwX1m05mPfUO-yomSYFENoXqgHvIhQ,18843
+mdb_engine-0.7.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mdb_engine-0.7.5.dist-info/entry_points.txt,sha256=INCbYdFbBzJalwPwxliEzLmPfR57IvQ7RAXG_pn8cL8,48
+mdb_engine-0.7.5.dist-info/top_level.txt,sha256=PH0UEBwTtgkm2vWvC9He_EOMn7hVn_Wg_Jyc0SmeO8k,11
+mdb_engine-0.7.5.dist-info/RECORD,,