mdb-engine 0.1.7__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 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).
 
-    This is a helper function that can be used with FastAPI's Depends()
-    to inject the embedding service into route handlers.
+    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,84 +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/repositories/__init__.py

@@ -0,0 +1,34 @@
+"""
+MDB Engine Repository Pattern
+
+Provides abstract repository interfaces and MongoDB implementations
+for clean data access patterns.
+
+Usage:
+    from mdb_engine.repositories import Repository, MongoRepository
+
+    # In domain services
+    class UserService:
+        def __init__(self, users: Repository[User]):
+            self._users = users
+
+        async def get_user(self, id: str) -> User:
+            return await self._users.get(id)
+
+    # In FastAPI routes using UnitOfWork
+    @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
+"""
+
+from .base import Entity, Repository
+from .mongo import MongoRepository
+from .unit_of_work import UnitOfWork
+
+__all__ = [
+    "Repository",
+    "Entity",
+    "MongoRepository",
+    "UnitOfWork",
+]

mdb_engine/repositories/base.py

@@ -0,0 +1,325 @@
+"""
+Abstract Repository Pattern
+
+Defines the repository interface that abstracts data access operations.
+This allows domain services to work with any data store implementation.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, Generic, List, Optional, TypeVar
+
+from bson import ObjectId
+
+
+@dataclass
+class Entity:
+    """
+    Base class for domain entities.
+
+    All entities have an ID and timestamps. Subclass this for your domain models.
+
+    Example:
+        @dataclass
+        class User(Entity):
+            email: str
+            name: str
+            role: str = "user"
+    """
+
+    id: Optional[str] = None
+    created_at: Optional[datetime] = field(default=None)
+    updated_at: Optional[datetime] = field(default=None)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert entity to dictionary for storage."""
+        data = {}
+        for key, value in self.__dict__.items():
+            if value is not None:
+                if key == "id":
+                    # Convert string ID to ObjectId for MongoDB
+                    if value and ObjectId.is_valid(value):
+                        data["_id"] = ObjectId(value)
+                    else:
+                        data["_id"] = value
+                else:
+                    data[key] = value
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Entity":
+        """Create entity from dictionary (e.g., from database)."""
+        if data is None:
+            return None
+
+        # Convert _id to id
+        if "_id" in data:
+            data["id"] = str(data.pop("_id"))
+
+        # Get field names from dataclass
+        import dataclasses
+
+        field_names = {f.name for f in dataclasses.fields(cls)}
+
+        # Filter to only known fields
+        filtered_data = {k: v for k, v in data.items() if k in field_names}
+
+        return cls(**filtered_data)
+
+
+T = TypeVar("T", bound=Entity)
+
+
+class Repository(ABC, Generic[T]):
+    """
+    Abstract repository interface for data access.
+
+    This interface defines standard CRUD operations that can be
+    implemented for any data store (MongoDB, PostgreSQL, in-memory, etc.)
+
+    Type parameter T should be an Entity subclass.
+
+    Example:
+        class UserRepository(Repository[User]):
+            async def find_by_email(self, email: str) -> Optional[User]:
+                users = await self.find({"email": email}, limit=1)
+                return users[0] if users else None
+    """
+
+    @abstractmethod
+    async def get(self, id: str) -> Optional[T]:
+        """
+        Get a single entity by ID.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def find(
+        self,
+        filter: Optional[Dict[str, Any]] = None,
+        skip: int = 0,
+        limit: int = 100,
+        sort: Optional[List[tuple]] = None,
+    ) -> List[T]:
+        """
+        Find entities matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+            skip: Number of documents to skip
+            limit: Maximum documents to return
+            sort: List of (field, direction) tuples
+
+        Returns:
+            List of matching entities
+        """
+        pass
+
+    @abstractmethod
+    async def find_one(
+        self,
+        filter: Dict[str, Any],
+    ) -> Optional[T]:
+        """
+        Find a single entity matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+
+        Returns:
+            First matching entity or None
+        """
+        pass
+
+    @abstractmethod
+    async def add(self, entity: T) -> str:
+        """
+        Add a new entity.
+
+        Args:
+            entity: Entity to add
+
+        Returns:
+            ID of the created entity
+        """
+        pass
+
+    @abstractmethod
+    async def add_many(self, entities: List[T]) -> List[str]:
+        """
+        Add multiple entities.
+
+        Args:
+            entities: List of entities to add
+
+        Returns:
+            List of created entity IDs
+        """
+        pass
+
+    @abstractmethod
+    async def update(self, id: str, entity: T) -> bool:
+        """
+        Update an existing entity.
+
+        Args:
+            id: Entity ID
+            entity: Updated entity data
+
+        Returns:
+            True if entity was updated, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def update_fields(self, id: str, fields: Dict[str, Any]) -> bool:
+        """
+        Update specific fields of an entity.
+
+        Args:
+            id: Entity ID
+            fields: Dictionary of fields to update
+
+        Returns:
+            True if entity was updated, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def delete(self, id: str) -> bool:
+        """
+        Delete an entity by ID.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            True if entity was deleted, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def count(self, filter: Optional[Dict[str, Any]] = None) -> int:
+        """
+        Count entities matching a filter.
+
+        Args:
+            filter: MongoDB-style filter dictionary
+
+        Returns:
+            Count of matching entities
+        """
+        pass
+
+    @abstractmethod
+    async def exists(self, id: str) -> bool:
+        """
+        Check if an entity exists.
+
+        Args:
+            id: Entity ID
+
+        Returns:
+            True if entity exists
+        """
+        pass
+
+
+class InMemoryRepository(Repository[T]):
+    """
+    In-memory repository implementation for testing.
+
+    Stores entities in a dictionary, useful for unit tests
+    without database dependencies.
+    """
+
+    def __init__(self, entity_class: type):
+        self._entity_class = entity_class
+        self._storage: Dict[str, Dict[str, Any]] = {}
+        self._counter = 0
+
+    async def get(self, id: str) -> Optional[T]:
+        data = self._storage.get(id)
+        if data is None:
+            return None
+        return self._entity_class.from_dict(data)
+
+    async def find(
+        self,
+        filter: Optional[Dict[str, Any]] = None,
+        skip: int = 0,
+        limit: int = 100,
+        sort: Optional[List[tuple]] = None,
+    ) -> List[T]:
+        results = []
+        for data in self._storage.values():
+            if filter is None or self._matches_filter(data, filter):
+                results.append(self._entity_class.from_dict(data))
+
+        # Apply skip and limit
+        return results[skip : skip + limit]
+
+    async def find_one(self, filter: Dict[str, Any]) -> Optional[T]:
+        results = await self.find(filter, limit=1)
+        return results[0] if results else None
+
+    async def add(self, entity: T) -> str:
+        self._counter += 1
+        id = str(self._counter)
+        entity.id = id
+        entity.created_at = datetime.utcnow()
+        self._storage[id] = entity.to_dict()
+        return id
+
+    async def add_many(self, entities: List[T]) -> List[str]:
+        return [await self.add(e) for e in entities]
+
+    async def update(self, id: str, entity: T) -> bool:
+        if id not in self._storage:
+            return False
+        entity.id = id
+        entity.updated_at = datetime.utcnow()
+        self._storage[id] = entity.to_dict()
+        return True
+
+    async def update_fields(self, id: str, fields: Dict[str, Any]) -> bool:
+        if id not in self._storage:
+            return False
+        self._storage[id].update(fields)
+        self._storage[id]["updated_at"] = datetime.utcnow()
+        return True
+
+    async def delete(self, id: str) -> bool:
+        if id not in self._storage:
+            return False
+        del self._storage[id]
+        return True
+
+    async def count(self, filter: Optional[Dict[str, Any]] = None) -> int:
+        if filter is None:
+            return len(self._storage)
+        return len(await self.find(filter, limit=999999))
+
+    async def exists(self, id: str) -> bool:
+        return id in self._storage
+
+    def _matches_filter(self, data: Dict[str, Any], filter: Dict[str, Any]) -> bool:
+        """Simple filter matching for testing."""
+        for key, value in filter.items():
+            if key not in data:
+                return False
+            if data[key] != value:
+                return False
+        return True
+
+    def clear(self) -> None:
+        """Clear all entities (useful for test setup)."""
+        self._storage.clear()
+        self._counter = 0