mdb-engine 0.1.7__py3-none-any.whl → 0.2.1__py3-none-any.whl

mdb_engine/di/providers.py

@@ -0,0 +1,205 @@
+"""
+Service Providers for Dependency Injection
+
+Providers are responsible for creating and managing service instances
+according to their configured scope.
+"""
+
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Callable, Dict, Generic, Optional, Type, TypeVar
+
+from .scopes import Scope, ScopeManager
+
+if TYPE_CHECKING:
+    from .container import Container
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class Provider(ABC, Generic[T]):
+    """
+    Abstract base class for service providers.
+
+    Providers know how to create instances of a service and manage
+    their lifecycle according to the configured scope.
+    """
+
+    def __init__(
+        self,
+        service_type: Type[T],
+        scope: Scope,
+        factory: Optional[Callable[..., T]] = None,
+    ):
+        self.service_type = service_type
+        self.scope = scope
+        self._factory = factory or service_type
+
+    @abstractmethod
+    def get(self, container: "Container") -> T:
+        """
+        Get or create a service instance.
+
+        Args:
+            container: The DI container for resolving dependencies
+
+        Returns:
+            Service instance
+        """
+        pass
+
+    def _create_instance(self, container: "Container") -> T:
+        """
+        Create a new instance, injecting dependencies.
+
+        Inspects the factory/constructor signature and resolves
+        any type-hinted parameters from the container.
+        """
+        # Get constructor signature
+        sig = inspect.signature(self._factory)
+        kwargs: Dict[str, Any] = {}
+
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+
+            # Check if parameter has a type annotation
+            if param.annotation != inspect.Parameter.empty:
+                param_type = param.annotation
+
+                # Skip primitive types and Optional markers
+                if param_type in (str, int, float, bool, type(None)):
+                    continue
+
+                # Handle Optional[X] - extract X
+                origin = getattr(param_type, "__origin__", None)
+                if origin is type(None):
+                    continue
+
+                # Try to resolve from container
+                try:
+                    kwargs[param_name] = container.resolve(param_type)
+                except KeyError:
+                    # If not registered and has default, skip
+                    if param.default != inspect.Parameter.empty:
+                        continue
+                    # If not registered and no default, re-raise
+                    raise
+
+        return self._factory(**kwargs)
+
+
+class SingletonProvider(Provider[T]):
+    """
+    Provider that creates a single instance shared across the application.
+
+    The instance is created lazily on first request and cached forever.
+    """
+
+    def __init__(
+        self,
+        service_type: Type[T],
+        factory: Optional[Callable[..., T]] = None,
+    ):
+        super().__init__(service_type, Scope.SINGLETON, factory)
+        self._instance: Optional[T] = None
+
+    def get(self, container: "Container") -> T:
+        if self._instance is None:
+            self._instance = self._create_instance(container)
+            logger.debug(f"Created singleton: {self.service_type.__name__}")
+        return self._instance
+
+    def reset(self) -> None:
+        """Reset the singleton (useful for testing)."""
+        self._instance = None
+
+
+class RequestProvider(Provider[T]):
+    """
+    Provider that creates one instance per request.
+
+    Uses ScopeManager to cache instances within the request scope.
+    """
+
+    def __init__(
+        self,
+        service_type: Type[T],
+        factory: Optional[Callable[..., T]] = None,
+    ):
+        super().__init__(service_type, Scope.REQUEST, factory)
+
+    def get(self, container: "Container") -> T:
+        return ScopeManager.get_or_create(
+            self.service_type, lambda: self._create_instance(container)
+        )
+
+
+class TransientProvider(Provider[T]):
+    """
+    Provider that creates a new instance every time.
+    """
+
+    def __init__(
+        self,
+        service_type: Type[T],
+        factory: Optional[Callable[..., T]] = None,
+    ):
+        super().__init__(service_type, Scope.TRANSIENT, factory)
+
+    def get(self, container: "Container") -> T:
+        instance = self._create_instance(container)
+        logger.debug(f"Created transient: {self.service_type.__name__}")
+        return instance
+
+
+class FactoryProvider(Provider[T]):
+    """
+    Provider that uses a custom factory function.
+
+    The factory is called with the container as the first argument,
+    allowing manual dependency resolution.
+
+    Usage:
+        def create_user_service(container: Container) -> UserService:
+            db = container.resolve(Database)
+            return UserService(db, custom_config=...)
+
+        container.register_factory(UserService, create_user_service, Scope.REQUEST)
+    """
+
+    def __init__(
+        self,
+        service_type: Type[T],
+        factory: Callable[["Container"], T],
+        scope: Scope,
+    ):
+        super().__init__(service_type, scope, None)
+        self._custom_factory = factory
+        self._singleton_instance: Optional[T] = None
+
+    def get(self, container: "Container") -> T:
+        if self.scope == Scope.SINGLETON:
+            if self._singleton_instance is None:
+                self._singleton_instance = self._custom_factory(container)
+            return self._singleton_instance
+
+        elif self.scope == Scope.REQUEST:
+            return ScopeManager.get_or_create(
+                self.service_type, lambda: self._custom_factory(container)
+            )
+
+        else:  # TRANSIENT
+            return self._custom_factory(container)
+
+
+__all__ = [
+    "Provider",
+    "SingletonProvider",
+    "RequestProvider",
+    "TransientProvider",
+    "FactoryProvider",
+]

mdb_engine/di/scopes.py

@@ -0,0 +1,139 @@
+"""
+Service Scopes for Dependency Injection
+
+Defines service lifetime scopes following enterprise patterns:
+- SINGLETON: Created once, shared across all requests
+- REQUEST: Created once per HTTP request, disposed after
+- TRANSIENT: Created fresh on every injection
+"""
+
+import logging
+from contextvars import ContextVar
+from enum import Enum
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Context variable for request-scoped instances
+_request_scope: ContextVar[Optional[Dict[type, Any]]] = ContextVar("request_scope", default=None)
+
+
+class Scope(Enum):
+    """
+    Service lifetime scopes.
+
+    SINGLETON: One instance for the entire application lifetime.
+               Use for: Database connections, configuration, caches.
+
+    REQUEST: One instance per HTTP request. Automatically disposed
+             when the request ends.
+             Use for: Unit of Work, request context, user session.
+
+    TRANSIENT: New instance created every time it's requested.
+               Use for: Stateless services, utilities.
+    """
+
+    SINGLETON = "singleton"
+    REQUEST = "request"
+    TRANSIENT = "transient"
+
+
+class ScopeManager:
+    """
+    Manages request-scoped instance lifecycles.
+
+    Usage with FastAPI middleware:
+        @app.middleware("http")
+        async def scope_middleware(request: Request, call_next):
+            async with ScopeManager.request_scope():
+                response = await call_next(request)
+            return response
+    """
+
+    @classmethod
+    def begin_request(cls) -> Dict[type, Any]:
+        """
+        Begin a new request scope.
+
+        Returns the scope dictionary for manual management if needed.
+        """
+        scope_dict: Dict[type, Any] = {}
+        _request_scope.set(scope_dict)
+        logger.debug("Request scope started")
+        return scope_dict
+
+    @classmethod
+    def end_request(cls) -> None:
+        """
+        End the current request scope and cleanup instances.
+
+        Calls dispose() on any instances that have it.
+        """
+        scope_dict = _request_scope.get()
+        if scope_dict:
+            for instance in scope_dict.values():
+                if hasattr(instance, "dispose"):
+                    try:
+                        instance.dispose()
+                    except (AttributeError, RuntimeError, TypeError) as e:
+                        logger.warning(f"Error disposing {type(instance).__name__}: {e}")
+            scope_dict.clear()
+        _request_scope.set(None)
+        logger.debug("Request scope ended")
+
+    @classmethod
+    def get_request_scope(cls) -> Optional[Dict[type, Any]]:
+        """Get the current request scope dictionary."""
+        return _request_scope.get()
+
+    @classmethod
+    def get_or_create(cls, key: type, factory: callable) -> Any:
+        """
+        Get an existing instance from request scope or create one.
+
+        Args:
+            key: The type to use as cache key
+            factory: Callable to create a new instance if not cached
+
+        Returns:
+            The cached or newly created instance
+
+        Raises:
+            RuntimeError: If called outside a request scope
+        """
+        scope_dict = _request_scope.get()
+        if scope_dict is None:
+            raise RuntimeError(
+                "No active request scope. Ensure ScopeManager.begin_request() "
+                "was called (usually via middleware)."
+            )
+
+        if key not in scope_dict:
+            scope_dict[key] = factory()
+            logger.debug(f"Created request-scoped instance: {key.__name__}")
+
+        return scope_dict[key]
+
+    @classmethod
+    async def request_scope(cls):
+        """
+        Async context manager for request scope.
+
+        Usage:
+            async with ScopeManager.request_scope():
+                # Request-scoped services available here
+                pass
+        """
+        return _RequestScopeContext()
+
+
+class _RequestScopeContext:
+    """Async context manager for request scope."""
+
+    async def __aenter__(self):
+        ScopeManager.begin_request()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        ScopeManager.end_request()
+        return False

mdb_engine/embeddings/README.md

@@ -9,6 +9,7 @@ Semantic text splitting and embedding generation for MDB_ENGINE applications.
 - **Token-Aware**: Never exceeds model token limits
 - **Batch Processing**: Efficient batch embedding generation
 - **MongoDB Integration**: Built-in support for storing embeddings with metadata
+- **Request-Scoped Dependencies**: Clean FastAPI integration via `mdb_engine.dependencies`
 
 ## Installation
 
@@ -38,7 +39,44 @@ Enable embedding service in your `manifest.json`:
 
 ## Usage
 
-### 1. Basic Usage (Auto-Detection)
+### 1. FastAPI Routes (Recommended)
+
+Use request-scoped dependencies from `mdb_engine.dependencies`:
+
+```python
+from fastapi import Depends
+from mdb_engine import MongoDBEngine
+from mdb_engine.dependencies import get_embedding_service, get_scoped_db
+
+engine = MongoDBEngine(mongo_uri=..., db_name=...)
+app = engine.create_app(slug="my_app", manifest=Path("manifest.json"))
+
+@app.post("/embed")
+async def embed_endpoint(
+    db=Depends(get_scoped_db),
+    embedding_service=Depends(get_embedding_service),
+):
+    # Services are automatically bound to the current app
+    result = await embedding_service.process_and_store(
+        text_content="Hello world",
+        source_id="doc_1",
+        collection=db.knowledge_base,
+    )
+    return {"chunks_created": result["chunks_created"]}
+
+@app.post("/search")
+async def search(
+    query: str,
+    db=Depends(get_scoped_db),
+    embedding_service=Depends(get_embedding_service),
+):
+    # Generate query embedding
+    vectors = await embedding_service.embed_chunks([query])
+    # Use vectors for vector search...
+    return {"query_vector_dims": len(vectors[0])}
+```
+
+### 2. Basic Usage (Standalone)
 
 ```python
 from mdb_engine.embeddings import EmbeddingService
@@ -56,7 +94,7 @@ chunks = await embedding_service.chunk_text(
 vectors = await embedding_service.embed_chunks(chunks, model="text-embedding-3-small")
 ```
 
-### 2. Process and Store in MongoDB
+### 3. Process and Store in MongoDB
 
 ```python
 from mdb_engine.embeddings import EmbeddingService
@@ -75,36 +113,28 @@ result = await embedding_service.process_and_store(
 print(f"Created {result['chunks_created']} chunks")
 ```
 
-### 3. Explicit Provider
+### 4. Utility Function (Background Tasks/CLI)
+
+For use outside of FastAPI request handlers:
 
 ```python
-from mdb_engine.embeddings import EmbeddingService, OpenAIEmbeddingProvider, EmbeddingProvider
+from mdb_engine.embeddings.dependencies import get_embedding_service_for_app
 
-# Use OpenAI explicitly
-openai_provider = OpenAIEmbeddingProvider(default_model="text-embedding-3-small")
-provider = EmbeddingProvider(embedding_provider=openai_provider)
-embedding_service = EmbeddingService(embedding_provider=provider)
+# In a background task or CLI tool
+service = get_embedding_service_for_app("my_app", engine)
+if service:
+    embeddings = await service.embed_chunks(["Hello world"])
 ```
 
-### 4. In FastAPI Routes
+### 5. Explicit Provider
 
 ```python
-from fastapi import FastAPI, Depends
-from mdb_engine.embeddings.dependencies import get_embedding_service_dependency
-from mdb_engine.embeddings import EmbeddingService
-
-app = FastAPI()
-
-# Set global engine during startup
-from mdb_engine.embeddings.dependencies import set_global_engine
-set_global_engine(engine, app_slug="my_app")
+from mdb_engine.embeddings import EmbeddingService, OpenAIEmbeddingProvider, EmbeddingProvider
 
-@app.post("/embed")
-async def embed_endpoint(
-    embedding_service: EmbeddingService = Depends(get_embedding_service_dependency("my_app"))
-):
-    embeddings = await embedding_service.embed_chunks(["Hello world"])
-    return {"embeddings": embeddings}
+# Use OpenAI explicitly
+openai_provider = OpenAIEmbeddingProvider(default_model="text-embedding-3-small")
+provider = EmbeddingProvider(embedding_provider=openai_provider)
+embedding_service = EmbeddingService(embedding_provider=provider)
 ```
 
 ## Environment Variables

mdb_engine/embeddings/__init__.py

@@ -7,6 +7,22 @@ Examples should implement their own LLM clients directly using the OpenAI SDK.
 For memory functionality, use mdb_engine.memory.Mem0MemoryService which
 handles embeddings and LLM via environment variables (.env).
 
+FastAPI Dependency Injection:
+    # RECOMMENDED: Use request-scoped dependencies
+    from mdb_engine.dependencies import get_embedding_service
+
+    @app.post("/embed")
+    async def embed_text(embedding_service=Depends(get_embedding_service)):
+        embeddings = await embedding_service.embed_chunks(["Hello world"])
+        return {"embeddings": embeddings}
+
+Standalone Usage:
+    from mdb_engine.embeddings import EmbeddingService, get_embedding_service
+
+    # Auto-detects OpenAI or Azure from environment variables
+    service = get_embedding_service(config={"default_embedding_model": "text-embedding-3-small"})
+    embeddings = await service.embed_chunks(["Hello world"])
+
 Example LLM implementation:
     from openai import AzureOpenAI
     from dotenv import load_dotenv
@@ -24,25 +40,9 @@ Example LLM implementation:
         model=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
         messages=[...]
     )
-
-Example EmbeddingService usage:
-    from mdb_engine.embeddings import EmbeddingService, get_embedding_service
-
-    # In FastAPI route
-    @app.post("/embed")
-    async def embed_text(embedding_service: EmbeddingService = Depends(get_embedding_service)):
-        embeddings = await embedding_service.embed_chunks(["Hello world"])
-        return {"embeddings": embeddings}
 """
 
-from .dependencies import (
-    create_embedding_dependency,
-    get_embedding_service_dep,
-    get_embedding_service_dependency,
-    get_embedding_service_for_app,
-    get_global_engine,
-    set_global_engine,
-)
+from .dependencies import get_embedding_service_for_app
 from .service import (
     AzureOpenAIEmbeddingProvider,
     BaseEmbeddingProvider,
@@ -54,17 +54,16 @@ from .service import (
 )
 
 __all__ = [
+    # Core service classes
     "EmbeddingService",
     "EmbeddingServiceError",
+    "EmbeddingProvider",
+    # Embedding providers
     "BaseEmbeddingProvider",
     "OpenAIEmbeddingProvider",
     "AzureOpenAIEmbeddingProvider",
-    "EmbeddingProvider",
+    # Factory function
     "get_embedding_service",
+    # Utility for standalone usage
     "get_embedding_service_for_app",
-    "create_embedding_dependency",
-    "set_global_engine",
-    "get_global_engine",
-    "get_embedding_service_dependency",
-    "get_embedding_service_dep",
 ]