mdb-engine 0.1.6__py3-none-any.whl → 0.2.0__py3-none-any.whl

mdb_engine/embeddings/dependencies.py

@@ -1,97 +1,60 @@
 """
-Embedding Service Dependency Injection for FastAPI
+Embedding Service Utilities
 
-This module provides FastAPI dependency functions to inject embedding services
-into route handlers. The embedding service is automatically initialized from
-the app's manifest.json configuration.
-"""
+This module provides utility functions for creating embedding services.
+For FastAPI dependency injection, use the request-scoped dependencies
+from `mdb_engine.dependencies` instead.
 
-from typing import Any, Optional
+Usage:
+    # For FastAPI routes (RECOMMENDED):
+    from mdb_engine.dependencies import get_embedding_service
 
-# Optional FastAPI import (only needed if FastAPI is available)
-try:
-    from fastapi import Depends, HTTPException
+    @app.post("/embed")
+    async def embed(embedding_service=Depends(get_embedding_service)):
+        ...
 
-    FASTAPI_AVAILABLE = True
-except ImportError:
-    FASTAPI_AVAILABLE = False
+    # For standalone/utility usage:
+    from mdb_engine.embeddings.dependencies import get_embedding_service_for_app
 
-    # Stub for when FastAPI is not available
-    def Depends(*args, **kwargs):
-        return None
+    service = get_embedding_service_for_app("my_app", engine)
+"""
 
-    class HTTPException(Exception):
-        pass
+from typing import TYPE_CHECKING, Optional
 
+if TYPE_CHECKING:
+    from ..core.engine import MongoDBEngine
 
 from .service import EmbeddingService, get_embedding_service
 
-# Global engine registry (for apps that don't pass engine explicitly)
-_global_engine: Optional[Any] = None
-_global_app_slug: Optional[str] = None
-
-
-def set_global_engine(engine: Any, app_slug: Optional[str] = None) -> None:
-    """
-    Set global MongoDBEngine instance for embedding dependency injection.
-
-    This is useful when you have a single engine instance that you want
-    to use across all apps. Call this during application startup.
-
-    Args:
-        engine: MongoDBEngine instance
-        app_slug: Optional app slug
-    """
-    global _global_engine, _global_app_slug
-    _global_engine = engine
-    _global_app_slug = app_slug
-
-
-def get_global_engine() -> Optional[Any]:
-    """
-    Get global MongoDBEngine instance.
-
-    Returns:
-        MongoDBEngine instance if set, None otherwise
-    """
-    return _global_engine
-
 
 def get_embedding_service_for_app(
-    app_slug: str, engine: Optional[Any] = None
+    app_slug: str, engine: "MongoDBEngine"
 ) -> Optional[EmbeddingService]:
     """
-    Get embedding service for a specific app.
+    Get embedding service for a specific app using the engine instance.
 
-    This is a helper function that can be used with FastAPI's Depends()
-    to inject the embedding service into route handlers.
+    This is a utility function for cases where you need to create an
+    embedding service outside of a FastAPI request context (e.g., in
+    background tasks, CLI tools, or tests).
+
+    For FastAPI routes, use `mdb_engine.dependencies.get_embedding_service` instead.
 
     Args:
-        app_slug: App slug (typically extracted from route context)
-        engine: MongoDBEngine instance (optional, will try to get from context)
+        app_slug: App slug to get embedding config from
+        engine: MongoDBEngine instance
 
     Returns:
-        EmbeddingService instance if embedding is enabled for this app, None otherwise
+        EmbeddingService instance if embedding is enabled, None otherwise
 
     Example:
-        ```python
-        from fastapi import Depends
-        from mdb_engine.embeddings.dependencies import get_embedding_service_for_app
-
-        @app.post("/embed")
-        async def embed_endpoint(
-            embedding_service = Depends(lambda: get_embedding_service_for_app("my_app"))
-        ):
-            if not embedding_service:
-                raise HTTPException(503, "Embedding service not available")
-            embeddings = await embedding_service.embed_chunks(["Hello world"])
-            return {"embeddings": embeddings}
-        ```
-    """
-    # Try to get engine from context if not provided
-    if engine is None:
-        engine = _global_engine
+        # In a background task or CLI
+        engine = MongoDBEngine(...)
+        await engine.initialize()
 
+        service = get_embedding_service_for_app("my_app", engine)
+        if service:
+            embeddings = await service.embed_chunks(["Hello world"])
+    """
     if engine is None:
         return None
 
@@ -108,86 +71,6 @@ def get_embedding_service_for_app(
     return get_embedding_service(config=embedding_config)
 
 
-def create_embedding_dependency(app_slug: str, engine: Optional[Any] = None):
-    """
-    Create a FastAPI dependency function for embedding service.
-
-    This creates a dependency function that can be used with Depends()
-    to inject the embedding service into route handlers.
-
-    Args:
-        app_slug: App slug
-        engine: MongoDBEngine instance (optional)
-
-    Returns:
-        Dependency function that returns EmbeddingService or raises HTTPException
-
-    Example:
-        ```python
-        from fastapi import Depends
-        from mdb_engine.embeddings.dependencies import create_embedding_dependency
-
-        embedding_dep = create_embedding_dependency("my_app", engine)
-
-        @app.post("/embed")
-        async def embed_endpoint(embedding_service = Depends(embedding_dep)):
-            embeddings = await embedding_service.embed_chunks(["Hello world"])
-            return {"embeddings": embeddings}
-        ```
-    """
-
-    def _get_embedding_service() -> EmbeddingService:
-        embedding_service = get_embedding_service_for_app(app_slug, engine)
-        if embedding_service is None:
-            if FASTAPI_AVAILABLE:
-                raise HTTPException(
-                    status_code=503,
-                    detail=f"Embedding service not available for app '{app_slug}'. "
-                    "Ensure 'embedding_config.enabled' is true in manifest.json and "
-                    "embedding dependencies are installed.",
-                )
-            else:
-                raise RuntimeError(
-                    f"Embedding service not available for app '{app_slug}'"
-                )
-        return embedding_service
-
-    return _get_embedding_service
-
-
-def get_embedding_service_dependency(app_slug: str):
-    """
-    Get embedding service dependency using global engine.
-
-    This is a convenience function that uses the global engine registry.
-    Set the engine with set_global_engine() during app startup.
-
-    Args:
-        app_slug: App slug
-
-    Returns:
-        Dependency function for FastAPI Depends()
-
-    Example:
-        ```python
-        from fastapi import FastAPI, Depends
-        from mdb_engine.embeddings.dependencies import (
-            set_global_engine, get_embedding_service_dependency
-        )
-
-        app = FastAPI()
-
-        # During startup
-        set_global_engine(engine, app_slug="my_app")
-
-        # In routes
-        @app.post("/embed")
-        async def embed(embedding_service = Depends(get_embedding_service_dependency("my_app"))):
-            return await embedding_service.embed_chunks(["Hello world"])
-        ```
-    """
-    return create_embedding_dependency(app_slug, _global_engine)
-
-
-# Alias for backward compatibility
-get_embedding_service_dep = get_embedding_service_dependency
+__all__ = [
+    "get_embedding_service_for_app",
+]

mdb_engine/embeddings/service.py

@@ -134,7 +134,7 @@ class OpenAIEmbeddingProvider(BaseEmbeddingProvider):
             ConnectionError,
             OSError,
         ) as e:
-            logger.error(f"OpenAI embedding failed: {e}")
+            logger.exception(f"OpenAI embedding failed: {e}")
             raise EmbeddingServiceError(f"OpenAI embedding failed: {str(e)}") from e
 
 
@@ -217,10 +217,8 @@ class AzureOpenAIEmbeddingProvider(BaseEmbeddingProvider):
             ConnectionError,
             OSError,
         ) as e:
-            logger.error(f"Azure OpenAI embedding failed: {e}")
-            raise EmbeddingServiceError(
-                f"Azure OpenAI embedding failed: {str(e)}"
-            ) from e
+            logger.exception(f"Azure OpenAI embedding failed: {e}")
+            raise EmbeddingServiceError(f"Azure OpenAI embedding failed: {str(e)}") from e
 
 
 def _detect_provider_from_env() -> str:
@@ -281,24 +279,16 @@ class EmbeddingProvider:
         else:
             # Auto-detect provider from environment variables
             provider_type = _detect_provider_from_env()
-            default_model = (config or {}).get(
-                "default_embedding_model", "text-embedding-3-small"
-            )
+            default_model = (config or {}).get("default_embedding_model", "text-embedding-3-small")
 
             if provider_type == "azure":
-                self.embedding_provider = AzureOpenAIEmbeddingProvider(
-                    default_model=default_model
-                )
+                self.embedding_provider = AzureOpenAIEmbeddingProvider(default_model=default_model)
                 logger.info(
                     f"Auto-detected Azure OpenAI embedding provider (model: {default_model})"
                 )
             else:
-                self.embedding_provider = OpenAIEmbeddingProvider(
-                    default_model=default_model
-                )
-                logger.info(
-                    f"Auto-detected OpenAI embedding provider (model: {default_model})"
-                )
+                self.embedding_provider = OpenAIEmbeddingProvider(default_model=default_model)
+                logger.info(f"Auto-detected OpenAI embedding provider (model: {default_model})")
 
         # Store config for potential future use
         self.config = config or {}
@@ -341,7 +331,7 @@ class EmbeddingProvider:
             return vectors
 
         except (AttributeError, TypeError, ValueError, RuntimeError, KeyError) as e:
-            logger.error(f"EMBED_FAILED: {str(e)}")
+            logger.exception(f"EMBED_FAILED: {str(e)}")
             raise EmbeddingServiceError(f"Embedding failed: {str(e)}") from e
 
 
@@ -573,7 +563,7 @@ class EmbeddingService:
             ConnectionError,
             OSError,
         ) as e:
-            logger.error(f"Failed to generate embeddings for {source_id}: {e}")
+            logger.exception(f"Failed to generate embeddings for {source_id}: {e}")
             raise EmbeddingServiceError(f"Embedding generation failed: {str(e)}") from e
 
         if len(vectors) != len(chunks):
@@ -614,9 +604,7 @@ class EmbeddingService:
                 result = await collection.insert_many(documents_to_insert)
                 inserted_count = len(result.inserted_ids)
 
-            logger.info(
-                f"Successfully inserted {inserted_count} documents for source: {source_id}"
-            )
+            logger.info(f"Successfully inserted {inserted_count} documents for source: {source_id}")
 
             return {
                 "chunks_created": len(chunks),
@@ -632,9 +620,7 @@ class EmbeddingService:
             KeyError,
             ConnectionError,
         ) as e:
-            logger.error(
-                f"Failed to store documents for {source_id}: {e}", exc_info=True
-            )
+            logger.error(f"Failed to store documents for {source_id}: {e}", exc_info=True)
             raise EmbeddingServiceError(f"Storage failed: {str(e)}") from e
 
     async def process_text(

mdb_engine/exceptions.py

@@ -165,3 +165,95 @@ class ConfigurationError(MongoDBEngineError):
         super().__init__(message, context=context)
         self.config_key = config_key
         self.config_value = config_value
+
+
+class QueryValidationError(MongoDBEngineError):
+    """
+    Raised when a query fails validation checks.
+
+    This exception is raised when a query contains dangerous operators,
+    exceeds complexity limits, or violates security policies.
+
+    Attributes:
+        message: Error message
+        query_type: Type of query that failed (filter, pipeline, etc.)
+        operator: Dangerous operator that was found (if applicable)
+        path: JSON path where the issue was found (if applicable)
+        context: Additional context information
+    """
+
+    def __init__(
+        self,
+        message: str,
+        query_type: Optional[str] = None,
+        operator: Optional[str] = None,
+        path: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Initialize the query validation error.
+
+        Args:
+            message: Error message
+            query_type: Type of query that failed (filter, pipeline, etc.)
+            operator: Dangerous operator that was found (if applicable)
+            path: JSON path where the issue was found (if applicable)
+            context: Additional context information
+        """
+        context = context or {}
+        if query_type:
+            context["query_type"] = query_type
+        if operator:
+            context["operator"] = operator
+        if path:
+            context["path"] = path
+        super().__init__(message, context=context)
+        self.query_type = query_type
+        self.operator = operator
+        self.path = path
+
+
+class ResourceLimitExceeded(MongoDBEngineError):
+    """
+    Raised when a resource limit is exceeded.
+
+    This exception is raised when queries exceed timeouts, result sizes,
+    or other resource limits.
+
+    Attributes:
+        message: Error message
+        limit_type: Type of limit that was exceeded (timeout, size, etc.)
+        limit_value: The limit value that was exceeded
+        actual_value: The actual value that exceeded the limit
+        context: Additional context information
+    """
+
+    def __init__(
+        self,
+        message: str,
+        limit_type: Optional[str] = None,
+        limit_value: Optional[Any] = None,
+        actual_value: Optional[Any] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Initialize the resource limit exceeded error.
+
+        Args:
+            message: Error message
+            limit_type: Type of limit that was exceeded (timeout, size, etc.)
+            limit_value: The limit value that was exceeded
+            actual_value: The actual value that exceeded the limit
+            context: Additional context information
+        """
+        context = context or {}
+        if limit_type:
+            context["limit_type"] = limit_type
+        if limit_value is not None:
+            context["limit_value"] = limit_value
+        if actual_value is not None:
+            context["actual_value"] = actual_value
+        super().__init__(message, context=context)
+        self.limit_type = limit_type
+        self.limit_value = limit_value
+        self.actual_value = actual_value

mdb_engine/indexes/README.md

@@ -573,7 +573,7 @@ try:
         collection_name="users",
         index_definitions=index_definitions
     )
-except Exception as e:
+except (PyMongoError, ValueError, TypeError) as e:
     logger.error(f"Failed to create indexes: {e}", exc_info=True)
     raise
 ```
@@ -613,12 +613,20 @@ index_definitions = [
     }
 ]
 
-await run_index_creation_for_collection(
-    db=engine.mongo_db,
-    slug="my_app",
-    collection_name="users",
-    index_definitions=index_definitions
-)
+# Get scoped database and collection
+db = engine.get_scoped_db("my_app")
+collection = db.users
+
+# Use collection.index_manager for index operations
+index_manager = collection.index_manager
+for index_def in index_definitions:
+    if index_def["type"] == "regular":
+        await index_manager.create_index(
+            keys=list(index_def["keys"].items()),
+            name=index_def.get("name"),
+            **index_def.get("options", {})
+        )
+    # Handle other index types similarly...
 ```
 
 ### Multiple Collections
@@ -635,13 +643,22 @@ collections_with_indexes = {
     ]
 }
 
+# Get scoped database
+db = engine.get_scoped_db("my_app")
+
+# Use collection.index_manager for each collection
 for collection_name, index_definitions in collections_with_indexes.items():
-    await run_index_creation_for_collection(
-        db=engine.mongo_db,
-        slug="my_app",
-        collection_name=collection_name,
-        index_definitions=index_definitions
-    )
+    collection = getattr(db, collection_name)
+    index_manager = collection.index_manager
+    
+    for index_def in index_definitions:
+        if index_def["type"] == "regular":
+            await index_manager.create_index(
+                keys=list(index_def["keys"].items()),
+                name=index_def.get("name"),
+                **index_def.get("options", {})
+            )
+        # Handle other index types similarly...
 ```
 
 ## Related Modules

mdb_engine/indexes/__init__.py

@@ -8,6 +8,7 @@ This module is part of MDB_ENGINE - MongoDB Engine.
 
 # Re-export index managers from database module for convenience
 from ..database.scoped_wrapper import AsyncAtlasIndexManager, AutoIndexManager
+
 # Export high-level management functions
 from .manager import normalize_json_def, run_index_creation_for_collection
 

mdb_engine/indexes/helpers.py

@@ -12,7 +12,7 @@ logger = logging.getLogger(__name__)
 
 
 def normalize_keys(
-    keys: Union[Dict[str, Any], List[Tuple[str, Any]]]
+    keys: Union[Dict[str, Any], List[Tuple[str, Any]]],
 ) -> List[Tuple[str, Any]]:
     """
     Normalize index keys to a consistent format.