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

mdb_engine/dependencies.py

@@ -0,0 +1,427 @@
+"""
+FastAPI Dependencies for MDB Engine
+
+Provides:
+1. RequestContext - All-in-one request-scoped dependency
+2. Individual dependencies for fine-grained control
+3. DI container integration
+
+Usage:
+    from fastapi import Depends
+    from mdb_engine.dependencies import RequestContext
+
+    @app.get("/users/{user_id}")
+    async def get_user(user_id: str, ctx: RequestContext = Depends()):
+        user = await ctx.uow.users.get(user_id)
+        return user
+"""
+
+import logging
+import os
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+
+from fastapi import HTTPException, Request
+
+from .di import Container
+from .repositories import UnitOfWork
+
+if TYPE_CHECKING:
+    from openai import AzureOpenAI, OpenAI
+
+    from .auth.provider import AuthorizationProvider
+    from .core.engine import MongoDBEngine
+    from .database.scoped_wrapper import ScopedMongoWrapper
+    from .embeddings.service import EmbeddingService
+    from .memory.service import Mem0MemoryService
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+# =============================================================================
+# Core Engine Dependencies
+# =============================================================================
+
+
+async def get_engine(request: Request) -> "MongoDBEngine":
+    """Get the MongoDBEngine instance from app state."""
+    engine = getattr(request.app.state, "engine", None)
+    if not engine:
+        raise HTTPException(503, "Engine not initialized")
+    if not engine.initialized:
+        raise HTTPException(503, "Engine not fully initialized")
+    return engine
+
+
+async def get_app_slug(request: Request) -> str:
+    """Get the current app's slug."""
+    slug = getattr(request.app.state, "app_slug", None)
+    if not slug:
+        raise HTTPException(503, "App slug not configured")
+    return slug
+
+
+async def get_app_config(request: Request) -> dict[str, Any]:
+    """Get the app's manifest configuration."""
+    manifest = getattr(request.app.state, "manifest", None)
+    if manifest is None:
+        engine = getattr(request.app.state, "engine", None)
+        slug = getattr(request.app.state, "app_slug", None)
+        if engine and slug:
+            manifest = engine.get_app(slug)
+    if manifest is None:
+        raise HTTPException(503, "App configuration not available")
+    return manifest
+
+
+# =============================================================================
+# Database Dependencies
+# =============================================================================
+
+
+async def get_scoped_db(request: Request) -> "ScopedMongoWrapper":
+    """Get a scoped database wrapper for the current app."""
+    engine = await get_engine(request)
+    slug = await get_app_slug(request)
+    return engine.get_scoped_db(slug)
+
+
+async def get_unit_of_work(request: Request) -> UnitOfWork:
+    """Get a request-scoped UnitOfWork."""
+    db = await get_scoped_db(request)
+    return UnitOfWork(db)
+
+
+# =============================================================================
+# AI/ML Service Dependencies
+# =============================================================================
+
+
+async def get_embedding_service(request: Request) -> "EmbeddingService":
+    """Get the EmbeddingService for text embeddings."""
+    engine = await get_engine(request)
+    slug = await get_app_slug(request)
+
+    app_config = engine.get_app(slug)
+    if not app_config:
+        raise HTTPException(503, f"App configuration not found for '{slug}'")
+
+    embedding_config = app_config.get("embedding_config", {})
+    if not embedding_config.get("enabled", True):
+        raise HTTPException(503, "Embedding service is disabled")
+
+    from .embeddings.service import EmbeddingServiceError
+    from .embeddings.service import get_embedding_service as create_service
+
+    try:
+        return create_service(config=embedding_config)
+    except (EmbeddingServiceError, ValueError, RuntimeError, ImportError, AttributeError) as e:
+        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."""
+    engine = getattr(request.app.state, "engine", None)
+    slug = getattr(request.app.state, "app_slug", None)
+    if not engine or not slug:
+        return None
+    return engine.get_memory_service(slug)
+
+
+async def get_llm_client(request: Request) -> Union["AzureOpenAI", "OpenAI"]:
+    """Get an OpenAI/AzureOpenAI client."""
+    azure_key = os.getenv("AZURE_OPENAI_API_KEY")
+    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
+
+    if azure_key and azure_endpoint:
+        from openai import AzureOpenAI
+
+        return AzureOpenAI(
+            api_key=azure_key,
+            azure_endpoint=azure_endpoint,
+            api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-02-01"),
+        )
+
+    openai_key = os.getenv("OPENAI_API_KEY")
+    if openai_key:
+        from openai import OpenAI
+
+        return OpenAI(api_key=openai_key)
+
+    raise HTTPException(503, "No LLM API key configured")
+
+
+def get_llm_model_name() -> str:
+    """Get the configured LLM model/deployment name."""
+    if os.getenv("AZURE_OPENAI_API_KEY"):
+        return os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME", "gpt-4o")
+    return os.getenv("OPENAI_MODEL", "gpt-4o")
+
+
+# =============================================================================
+# Auth Dependencies
+# =============================================================================
+
+
+async def get_authz_provider(request: Request) -> Optional["AuthorizationProvider"]:
+    """Get the authorization provider if configured."""
+    return getattr(request.app.state, "authz_provider", None)
+
+
+async def get_current_user(request: Request) -> dict[str, Any] | None:
+    """Get the current authenticated user."""
+    return getattr(request.state, "user", None)
+
+
+async def get_user_roles(request: Request) -> list[str]:
+    """Get the current user's roles."""
+    return getattr(request.state, "user_roles", [])
+
+
+def require_user():
+    """Dependency that requires authentication."""
+
+    async def _require_user(request: Request) -> dict[str, Any]:
+        user = await get_current_user(request)
+        if not user:
+            raise HTTPException(401, "Authentication required")
+        return user
+
+    return _require_user
+
+
+def require_role(*roles: str):
+    """Dependency that requires specific roles."""
+
+    async def _require_role(request: Request) -> dict[str, Any]:
+        user = await get_current_user(request)
+        if not user:
+            raise HTTPException(401, "Authentication required")
+        user_roles = set(await get_user_roles(request))
+        if not any(role in user_roles for role in roles):
+            raise HTTPException(403, f"Required role: {' or '.join(roles)}")
+        return user
+
+    return _require_role
+
+
+# =============================================================================
+# RequestContext - All-in-One Dependency (Regular class, not dataclass!)
+# =============================================================================
+
+
+class RequestContext:
+    """
+    All-in-one request context with lazy-loaded dependencies.
+
+    This is NOT a dataclass to avoid FastAPI trying to analyze
+    fields as Pydantic types.
+
+    Usage:
+        @app.post("/documents")
+        async def create_doc(data: DocCreate, ctx: RequestContext = Depends()):
+            doc_id = await ctx.uow.documents.add(doc)
+            return {"id": doc_id}
+    """
+
+    def __init__(self, request: Request):
+        self.request = request
+        self._uow = None
+        self._engine = None
+        self._db = None
+        self._slug = None
+        self._config = None
+        self._embedding_service = None
+        self._memory = None
+        self._llm = None
+        self._user = None
+        self._authz = None
+
+    @property
+    def engine(self):
+        """Get the MongoDBEngine instance."""
+        if self._engine is None:
+            engine = getattr(self.request.app.state, "engine", None)
+            if not engine or not engine.initialized:
+                raise HTTPException(503, "Engine not initialized")
+            self._engine = engine
+        return self._engine
+
+    @property
+    def slug(self) -> str:
+        """Get the current app's slug."""
+        if self._slug is None:
+            self._slug = getattr(self.request.app.state, "app_slug", None)
+            if not self._slug:
+                raise HTTPException(503, "App slug not configured")
+        return self._slug
+
+    @property
+    def db(self):
+        """Get the scoped database wrapper."""
+        if self._db is None:
+            self._db = self.engine.get_scoped_db(self.slug)
+        return self._db
+
+    @property
+    def uow(self) -> UnitOfWork:
+        """Get the Unit of Work for repository access."""
+        if self._uow is None:
+            self._uow = UnitOfWork(self.db)
+        return self._uow
+
+    @property
+    def config(self) -> dict[str, Any]:
+        """Get the app's manifest configuration."""
+        if self._config is None:
+            self._config = getattr(self.request.app.state, "manifest", None)
+            if self._config is None:
+                self._config = self.engine.get_app(self.slug) or {}
+        return self._config
+
+    @property
+    def embedding_service(self):
+        """Get the embedding service (None if not configured)."""
+        if self._embedding_service is None:
+            embedding_config = self.config.get("embedding_config", {})
+            if embedding_config.get("enabled", True):
+                try:
+                    from .embeddings.service import (
+                        EmbeddingServiceError,
+                        get_embedding_service,
+                    )
+
+                    self._embedding_service = get_embedding_service(config=embedding_config)
+                except (EmbeddingServiceError, ValueError, RuntimeError, ImportError):
+                    pass
+        return self._embedding_service
+
+    @property
+    def memory(self):
+        """Get the memory service (None if not configured)."""
+        if self._memory is None:
+            self._memory = self.engine.get_memory_service(self.slug)
+        return self._memory
+
+    @property
+    def llm(self):
+        """Get the LLM client (None if not configured)."""
+        if self._llm is None:
+            azure_key = os.getenv("AZURE_OPENAI_API_KEY")
+            azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
+
+            if azure_key and azure_endpoint:
+                from openai import AzureOpenAI
+
+                self._llm = AzureOpenAI(
+                    api_key=azure_key,
+                    azure_endpoint=azure_endpoint,
+                    api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-02-01"),
+                )
+            elif os.getenv("OPENAI_API_KEY"):
+                from openai import OpenAI
+
+                self._llm = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+        return self._llm
+
+    @property
+    def llm_model(self) -> str:
+        """Get the LLM model/deployment name."""
+        return get_llm_model_name()
+
+    @property
+    def user(self) -> dict[str, Any] | None:
+        """Get the current authenticated user."""
+        if self._user is None:
+            self._user = getattr(self.request.state, "user", None)
+        return self._user
+
+    @property
+    def user_roles(self) -> list[str]:
+        """Get the current user's roles."""
+        return getattr(self.request.state, "user_roles", [])
+
+    @property
+    def authz(self):
+        """Get the authorization provider."""
+        if self._authz is None:
+            self._authz = getattr(self.request.app.state, "authz_provider", None)
+        return self._authz
+
+    def require_user(self) -> dict[str, Any]:
+        """Require authentication, raising 401 if not authenticated."""
+        if not self.user:
+            raise HTTPException(401, "Authentication required")
+        return self.user
+
+    def require_role(self, *roles: str) -> dict[str, Any]:
+        """Require specific roles, raising 403 if not authorized."""
+        user = self.require_user()
+        user_roles = set(self.user_roles)
+        if not any(role in user_roles for role in roles):
+            roles_str = " or ".join(roles)
+            raise HTTPException(403, f"Required role: {roles_str}")
+        return user
+
+    async def check_permission(
+        self, resource: str, action: str, subject: str | None = None
+    ) -> bool:
+        """Check if current user has permission for an action."""
+        if not self.authz:
+            return True
+        if subject is None:
+            user = self.user
+            subject = user.get("email", "anonymous") if user else "anonymous"
+        return await self.authz.check(subject, resource, action)
+
+
+async def _get_request_context(request: Request) -> RequestContext:
+    """Create a RequestContext for the current request."""
+    return RequestContext(request=request)
+
+
+# Make RequestContext usable with Depends()
+RequestContext.__call__ = staticmethod(_get_request_context)
+
+
+# =============================================================================
+# DI Container Integration
+# =============================================================================
+
+
+def inject(service_type: type[T]) -> Callable[..., T]:
+    """Create a dependency that resolves a service from the DI container."""
+
+    async def _resolve(request: Request) -> T:
+        container = getattr(request.app.state, "container", None)
+        if container is None:
+            container = Container.get_global()
+        return container.resolve(service_type)
+
+    return _resolve
+
+
+Inject = inject
+
+
+__all__ = [
+    "get_engine",
+    "get_app_slug",
+    "get_app_config",
+    "get_scoped_db",
+    "get_unit_of_work",
+    "get_embedding_service",
+    "get_memory_service",
+    "get_llm_client",
+    "get_llm_model_name",
+    "get_authz_provider",
+    "get_current_user",
+    "get_user_roles",
+    "require_user",
+    "require_role",
+    "RequestContext",
+    "inject",
+    "Inject",
+]

mdb_engine/di/__init__.py

@@ -0,0 +1,34 @@
+"""
+MDB Engine Dependency Injection Module
+
+Enterprise-grade DI container with proper service lifetimes:
+- SINGLETON: One instance per application lifetime
+- REQUEST: One instance per HTTP request
+- TRANSIENT: New instance on every injection
+
+Usage:
+    from mdb_engine.di import Container, Scope, inject
+
+    # Register services
+    container = Container()
+    container.register(DatabaseService, scope=Scope.SINGLETON)
+    container.register(UserService, scope=Scope.REQUEST)
+
+    # In FastAPI routes
+    @app.get("/users")
+    async def get_users(user_svc: UserService = inject(UserService)):
+        return await user_svc.list_all()
+"""
+
+from .container import Container
+from .providers import FactoryProvider, Provider, SingletonProvider
+from .scopes import Scope, ScopeManager
+
+__all__ = [
+    "Container",
+    "Scope",
+    "ScopeManager",
+    "Provider",
+    "FactoryProvider",
+    "SingletonProvider",
+]

mdb_engine/di/container.py

@@ -0,0 +1,247 @@
+"""
+Dependency Injection Container
+
+A lightweight, FastAPI-native DI container with proper service lifetimes.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any, Optional, TypeVar
+
+from .providers import Provider
+from .scopes import Scope
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class Container:
+    """
+    Dependency Injection Container with proper service lifetimes.
+
+    Supports three scopes:
+    - SINGLETON: One instance for app lifetime
+    - REQUEST: One instance per HTTP request
+    - TRANSIENT: New instance on every resolve
+
+    Usage:
+        container = Container()
+
+        # Register with auto-detection
+        container.register(UserService)  # Singleton by default
+        container.register(RequestContext, scope=Scope.REQUEST)
+
+        # Register with factory
+        container.register_factory(
+            Database,
+            lambda c: Database(c.resolve(Config).db_url),
+            scope=Scope.SINGLETON
+        )
+
+        # Register instance directly
+        container.register_instance(Config, config_instance)
+
+        # Resolve
+        user_svc = container.resolve(UserService)
+    """
+
+    _global_instance: Optional["Container"] = None
+
+    def __init__(self):
+        self._providers: dict[type, Provider] = {}
+        self._instances: dict[type, Any] = {}  # For register_instance
+
+    @classmethod
+    def get_global(cls) -> "Container":
+        """Get the global container instance."""
+        if cls._global_instance is None:
+            cls._global_instance = Container()
+        return cls._global_instance
+
+    @classmethod
+    def set_global(cls, container: "Container") -> None:
+        """Set the global container instance."""
+        cls._global_instance = container
+
+    @classmethod
+    def reset_global(cls) -> None:
+        """Reset the global container (useful for testing)."""
+        cls._global_instance = None
+
+    def register(
+        self,
+        service_type: type[T],
+        implementation: type[T] | None = None,
+        scope: Scope = Scope.SINGLETON,
+    ) -> "Container":
+        """
+        Register a service type with the container.
+
+        Args:
+            service_type: The type to register (interface or concrete class)
+            implementation: Optional implementation class (defaults to service_type)
+            scope: Service lifetime scope
+
+        Returns:
+            Self for chaining
+
+        Example:
+            container.register(UserService)
+            container.register(IRepository, MongoRepository, Scope.REQUEST)
+        """
+        from .providers import RequestProvider, SingletonProvider, TransientProvider
+
+        impl = implementation or service_type
+
+        if scope == Scope.SINGLETON:
+            self._providers[service_type] = SingletonProvider(service_type, impl)
+        elif scope == Scope.REQUEST:
+            self._providers[service_type] = RequestProvider(service_type, impl)
+        else:
+            self._providers[service_type] = TransientProvider(service_type, impl)
+
+        logger.debug(f"Registered {service_type.__name__} as {scope.value}")
+        return self
+
+    def register_factory(
+        self,
+        service_type: type[T],
+        factory: Callable[["Container"], T],
+        scope: Scope = Scope.SINGLETON,
+    ) -> "Container":
+        """
+        Register a service with a custom factory function.
+
+        The factory receives the container and can resolve dependencies manually.
+
+        Args:
+            service_type: The type to register
+            factory: Factory function (container) -> instance
+            scope: Service lifetime scope
+
+        Returns:
+            Self for chaining
+
+        Example:
+            container.register_factory(
+                Database,
+                lambda c: Database(c.resolve(Config).connection_string),
+                Scope.SINGLETON
+            )
+        """
+        from .providers import FactoryProvider
+
+        self._providers[service_type] = FactoryProvider(service_type, factory, scope)
+        logger.debug(f"Registered factory for {service_type.__name__} as {scope.value}")
+        return self
+
+    def register_instance(self, service_type: type[T], instance: T) -> "Container":
+        """
+        Register an existing instance as a singleton.
+
+        Useful for configuration objects or externally created instances.
+
+        Args:
+            service_type: The type to register
+            instance: The instance to use
+
+        Returns:
+            Self for chaining
+        """
+        self._instances[service_type] = instance
+        logger.debug(f"Registered instance for {service_type.__name__}")
+        return self
+
+    def resolve(self, service_type: type[T]) -> T:
+        """
+        Resolve a service instance.
+
+        Args:
+            service_type: The type to resolve
+
+        Returns:
+            Service instance
+
+        Raises:
+            KeyError: If service is not registered
+        """
+        # Check direct instances first
+        if service_type in self._instances:
+            return self._instances[service_type]
+
+        # Check providers
+        if service_type not in self._providers:
+            raise KeyError(
+                f"Service {service_type.__name__} is not registered. "
+                f"Call container.register({service_type.__name__}) first."
+            )
+
+        return self._providers[service_type].get(self)
+
+    def try_resolve(self, service_type: type[T]) -> T | None:
+        """
+        Try to resolve a service, returning None if not registered.
+
+        Args:
+            service_type: The type to resolve
+
+        Returns:
+            Service instance or None
+        """
+        try:
+            return self.resolve(service_type)
+        except KeyError:
+            return None
+
+    def is_registered(self, service_type: type) -> bool:
+        """Check if a service type is registered."""
+        return service_type in self._providers or service_type in self._instances
+
+    def reset(self) -> None:
+        """
+        Reset all registrations and cached instances.
+
+        Useful for testing.
+        """
+        for provider in self._providers.values():
+            if hasattr(provider, "reset"):
+                provider.reset()
+        self._providers.clear()
+        self._instances.clear()
+        logger.debug("Container reset")
+
+    def __contains__(self, service_type: type) -> bool:
+        """Support 'in' operator for checking registration."""
+        return self.is_registered(service_type)
+
+
+# FastAPI integration helpers
+def inject(service_type: type[T]) -> T:
+    """
+    FastAPI dependency that resolves a service from the global container.
+
+    Usage:
+        @app.get("/users")
+        async def get_users(user_svc: UserService = Depends(inject(UserService))):
+            return await user_svc.list_all()
+
+    Or with the shorthand:
+        @app.get("/users")
+        async def get_users(user_svc: UserService = Inject(UserService)):
+            return await user_svc.list_all()
+    """
+    from fastapi import Request
+
+    async def _dependency(request: Request) -> T:
+        # Get container from app state or use global
+        container = getattr(request.app.state, "container", None)
+        if container is None:
+            container = Container.get_global()
+        return container.resolve(service_type)
+
+    return _dependency
+
+
+# Alias for cleaner syntax
+Inject = inject