openaivec 0.10.0__py3-none-any.whl → 1.0.10__py3-none-any.whl

openaivec/_di.py

@@ -0,0 +1,326 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from threading import RLock
+from typing import Any, TypeVar
+
+__all__ = []
+
+"""Simple dependency injection container with singleton lifecycle management.
+
+This module provides a lightweight dependency injection container that manages
+service instances with singleton lifecycle semantics. All registered services
+are created once and reused across multiple resolve calls.
+
+Example:
+    ```python
+    from openaivec.di import Container
+
+    class DatabaseService:
+        def __init__(self):
+            self.connection = "database://localhost"
+
+    container = Container()
+    container.register(DatabaseService, lambda: DatabaseService())
+
+    db1 = container.resolve(DatabaseService)
+    db2 = container.resolve(DatabaseService)
+    print(db1 is db2)  # True - same instance
+    ```
+"""
+
+__all__ = ["Container", "Provider", "CircularDependencyError", "ProviderError"]
+
+T = TypeVar("T")
+Provider = Callable[[], T]
+
+
+class CircularDependencyError(Exception):
+    """Raised when a circular dependency is detected during service resolution.
+
+    This exception is thrown when the container detects that service resolution
+    would result in an infinite loop due to circular dependencies between services.
+
+    Attributes:
+        message: A descriptive error message including the dependency chain.
+
+    Example:
+        ```python
+        # ServiceA depends on ServiceB, ServiceB depends on ServiceA
+        try:
+            container.resolve(ServiceA)
+        except CircularDependencyError as e:
+            print(f"Circular dependency: {e}")
+        ```
+    """
+
+    pass
+
+
+class ProviderError(Exception):
+    """Raised when a provider function fails to create a service instance.
+
+    This exception wraps any underlying exception that occurs during service
+    instantiation, providing additional context about which service failed.
+
+    Attributes:
+        message: A descriptive error message including the service name.
+
+    Example:
+        ```python
+        def failing_provider():
+            raise ValueError("Database connection failed")
+        container.register(DatabaseService, failing_provider)
+        try:
+            container.resolve(DatabaseService)
+        except ProviderError as e:
+            print(f"Service creation failed: {e}")
+        ```
+    """
+
+    pass
+
+
+@dataclass
+class Container:
+    """A simple dependency injection container with singleton lifecycle and thread safety.
+
+    This container manages service registration and resolution with automatic singleton
+    lifecycle management. All registered services are created once and cached for
+    subsequent resolves. The container is thread-safe and detects circular dependencies.
+
+    Attributes:
+        _instances: Cache of created singleton instances.
+        _providers: Registry of provider functions for each service type.
+        _lock: Thread synchronization lock for safe concurrent access.
+        _resolving: Set of services currently being resolved (for cycle detection).
+
+    Example:
+        Basic container usage:
+        ```python
+        container = Container()
+        container.register(str, lambda: "Hello, World!")
+        message = container.resolve(str)
+        print(message)  # Hello, World!
+        ```
+
+        Dependency injection:
+        ```python
+        class DatabaseService:
+            def __init__(self):
+                self.connected = True
+
+        class UserService:
+            def __init__(self, db: DatabaseService):
+                self.db = db
+
+        container.register(DatabaseService, lambda: DatabaseService())
+        container.register(UserService, lambda: UserService(container.resolve(DatabaseService)))
+        user_service = container.resolve(UserService)
+        print(user_service.db.connected)  # True
+        ```
+    """
+
+    _instances: dict[type[Any], Any] = field(default_factory=dict)
+    _providers: dict[type[Any], Provider[Any]] = field(default_factory=dict)
+    _lock: RLock = field(default_factory=RLock)
+    _resolving: set[type[Any]] = field(default_factory=set)
+
+    def register(self, cls: type[T], provider: Provider[T]) -> None:
+        """Register a provider function for a service type.
+
+        The provider function will be called once to create the singleton instance
+        when the service is first resolved. Subsequent resolves will return the
+        cached instance. If the service is already registered, it will be overwritten.
+
+        Args:
+            cls: The service class/type to register.
+            provider: A callable that creates and returns an instance of the service.
+
+        Example:
+            ```python
+            container = Container()
+            container.register(str, lambda: "Hello")
+            container.register(int, lambda: 42)
+            # Overwrite existing registration
+            container.register(str, lambda: "World")
+            ```
+        """
+        with self._lock:
+            if cls in self._providers and cls in self._instances:
+                del self._instances[cls]
+
+            self._providers[cls] = provider
+
+    def register_instance(self, cls: type[T], instance: T) -> None:
+        """Register a pre-created instance for a service type.
+
+        The provided instance will be stored directly in the container and returned
+        for all future resolve calls. This is useful when you have a pre-configured
+        instance or when you want to register instances that require complex initialization.
+        If the service is already registered, it will be overwritten.
+
+        Args:
+            cls: The service class/type to register.
+            instance: The pre-created instance to register.
+
+        Example:
+            ```python
+            container = Container()
+            db_service = DatabaseService("production://db")
+            container.register_instance(DatabaseService, db_service)
+            resolved = container.resolve(DatabaseService)
+            print(resolved is db_service)  # True - same instance
+            # Overwrite existing registration
+            new_db_service = DatabaseService("staging://db")
+            container.register_instance(DatabaseService, new_db_service)
+            ```
+        """
+        with self._lock:
+            self._instances[cls] = instance
+            self._providers[cls] = lambda: instance
+
+    def resolve(self, cls: type[T]) -> T:
+        """Resolve a service instance, creating it if necessary.
+
+        Returns the singleton instance for the requested service type. If this is
+        the first time the service is resolved, the provider function is called
+        to create the instance, which is then cached for future resolves.
+
+        Args:
+            cls: The service class/type to resolve.
+
+        Returns:
+            The singleton instance of the requested service type.
+
+        Raises:
+            ValueError: If no provider is registered for the service type.
+            CircularDependencyError: If a circular dependency is detected.
+            ProviderError: If the provider function fails to create the instance.
+
+        Example:
+            ```python
+            container = Container()
+            container.register(str, lambda: "Hello, World!")
+            message1 = container.resolve(str)
+            message2 = container.resolve(str)
+            print(message1 is message2)  # True - same instance
+            ```
+        """
+        with self._lock:
+            if cls in self._resolving:
+                dependency_chain = " -> ".join(c.__name__ for c in self._resolving) + f" -> {cls.__name__}"
+                raise CircularDependencyError(f"Circular dependency detected: {dependency_chain}")
+
+            if cls not in self._providers:
+                raise ValueError(f"No provider registered for class {cls.__name__}.")
+
+            if cls in self._instances:
+                return self._instances[cls]
+
+            self._resolving.add(cls)
+
+            try:
+                instance = self._providers[cls]()
+
+                self._instances[cls] = instance
+
+                return instance
+
+            except CircularDependencyError:
+                raise
+            except Exception as e:
+                raise ProviderError(f"Failed to create instance of {cls.__name__}: {str(e)}") from e
+            finally:
+                self._resolving.discard(cls)
+
+    def is_registered(self, cls: type[Any]) -> bool:
+        """Check if a service type is registered in the container.
+
+        Args:
+            cls: The service class/type to check.
+
+        Returns:
+            True if the service type has a registered provider, False otherwise.
+
+        Example:
+            ```python
+            container = Container()
+            print(container.is_registered(str))  # False
+            container.register(str, lambda: "Hello")
+            print(container.is_registered(str))  # True
+            ```
+        """
+        with self._lock:
+            return cls in self._providers
+
+    def unregister(self, cls: type[Any]) -> None:
+        """Unregister a service type from the container.
+
+        Removes the provider function and any cached singleton instance for
+        the specified service type.
+
+        Args:
+            cls: The service class/type to unregister.
+
+        Raises:
+            ValueError: If the service type is not registered.
+
+        Example:
+            ```python
+            container = Container()
+            container.register(str, lambda: "Hello")
+            container.unregister(str)
+            print(container.is_registered(str))  # False
+            ```
+        """
+        with self._lock:
+            if cls not in self._providers:
+                raise ValueError(f"Class {cls.__name__} is not registered.")
+
+            del self._providers[cls]
+
+            if cls in self._instances:
+                del self._instances[cls]
+
+    def clear(self) -> None:
+        """Clear all registrations and cached instances from the container.
+
+        Removes all registered providers and their associated singleton instances.
+        After calling this method, the container will be empty and ready for
+        new registrations.
+
+        Example:
+            ```python
+            container = Container()
+            container.register(str, lambda: "Hello")
+            container.register(int, lambda: 42)
+            container.clear()
+            print(container.is_registered(str))  # False
+            print(container.is_registered(int))  # False
+            ```
+        """
+        with self._lock:
+            self._providers.clear()
+            self._instances.clear()
+            self._resolving.clear()
+
+    def clear_singletons(self) -> None:
+        """Clear all cached singleton instances from the container.
+
+        Removes all cached singleton instances while keeping the registered
+        providers intact. After calling this method, the next resolve call
+        for any service will create a new instance using the provider function.
+
+        Example:
+            ```python
+            container = Container()
+            container.register(str, lambda: "Hello")
+            instance1 = container.resolve(str)
+            container.clear_singletons()
+            instance2 = container.resolve(str)
+            print(instance1 is instance2)
+            # False - different instances after clearing singletons
+            ```
+        """
+        with self._lock:
+            self._instances.clear()

openaivec/_embeddings.py

@@ -0,0 +1,203 @@
+from dataclasses import dataclass, field
+from logging import Logger, getLogger
+
+import numpy as np
+from numpy.typing import NDArray
+from openai import AsyncOpenAI, InternalServerError, OpenAI, RateLimitError
+
+from openaivec._cache import AsyncBatchingMapProxy, BatchingMapProxy
+from openaivec._log import observe
+from openaivec._util import backoff, backoff_async
+
+__all__ = [
+    "BatchEmbeddings",
+    "AsyncBatchEmbeddings",
+]
+
+_LOGGER: Logger = getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class BatchEmbeddings:
+    """Thin wrapper around the OpenAI embeddings endpoint (synchronous).
+
+    Attributes:
+        client (OpenAI): Configured OpenAI client.
+        model_name (str): For Azure OpenAI, use your deployment name. For OpenAI, use the model name
+            (e.g., ``"text-embedding-3-small"``).
+        cache (BatchingMapProxy[str, NDArray[np.float32]]): Batching proxy for ordered, cached mapping.
+        api_kwargs (dict[str, Any]): Additional OpenAI API parameters stored at initialization.
+    """
+
+    client: OpenAI
+    model_name: str
+    cache: BatchingMapProxy[str, NDArray[np.float32]] = field(default_factory=lambda: BatchingMapProxy(batch_size=None))
+    api_kwargs: dict[str, int | float | str | bool] = field(default_factory=dict)
+
+    @classmethod
+    def of(cls, client: OpenAI, model_name: str, batch_size: int | None = None, **api_kwargs) -> "BatchEmbeddings":
+        """Factory constructor.
+
+        Args:
+            client (OpenAI): OpenAI client.
+            model_name (str): For Azure OpenAI, use your deployment name. For OpenAI, use the model name.
+            batch_size (int | None, optional): Max unique inputs per API call. Defaults to None
+                (automatic batch size optimization). Set to a positive integer for fixed batch size.
+            **api_kwargs: Additional OpenAI API parameters (e.g., dimensions for text-embedding-3 models).
+
+        Returns:
+            BatchEmbeddings: Configured instance backed by a batching proxy.
+        """
+        return cls(
+            client=client,
+            model_name=model_name,
+            cache=BatchingMapProxy(batch_size=batch_size),
+            api_kwargs=api_kwargs,
+        )
+
+    @observe(_LOGGER)
+    @backoff(exceptions=[RateLimitError, InternalServerError], scale=1, max_retries=12)
+    def _embed_chunk(self, inputs: list[str]) -> list[NDArray[np.float32]]:
+        """Embed one minibatch of strings.
+
+        This private helper is the unit of work used by the map/parallel
+        utilities.  Exponential back‑off is applied automatically when
+        ``openai.RateLimitError`` is raised.
+
+        Args:
+            inputs (list[str]): Input strings to be embedded. Duplicates allowed.
+
+        Returns:
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+        """
+        responses = self.client.embeddings.create(input=inputs, model=self.model_name, **self.api_kwargs)
+        return [np.array(d.embedding, dtype=np.float32) for d in responses.data]
+
+    @observe(_LOGGER)
+    def create(self, inputs: list[str]) -> list[NDArray[np.float32]]:
+        """Generate embeddings for inputs using cached, ordered batching.
+
+        Args:
+            inputs (list[str]): Input strings. Duplicates allowed.
+
+        Returns:
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+        """
+        return self.cache.map(inputs, self._embed_chunk)
+
+
+@dataclass(frozen=True)
+class AsyncBatchEmbeddings:
+    """Thin wrapper around the OpenAI embeddings endpoint (asynchronous).
+
+    This class provides an asynchronous interface for generating embeddings using
+    OpenAI models. It manages concurrency, handles rate limits automatically,
+    and efficiently processes batches of inputs, including de-duplication.
+
+    Example:
+        ```python
+        import asyncio
+        import numpy as np
+        from openai import AsyncOpenAI
+        from openaivec import AsyncBatchEmbeddings
+
+        # Assuming openai_async_client is an initialized AsyncOpenAI client
+        openai_async_client = AsyncOpenAI() # Replace with your actual client initialization
+
+        embedder = AsyncBatchEmbeddings.of(
+            client=openai_async_client,
+            model_name="text-embedding-3-small",
+            batch_size=128,
+            max_concurrency=8,
+        )
+        texts = ["This is the first document.", "This is the second document.", "This is the first document."]
+
+        # Asynchronous call
+        async def main():
+            embeddings = await embedder.create(texts)
+            # embeddings will be a list of numpy arrays (float32)
+            # The embedding for the third text will be identical to the first
+            # due to automatic de-duplication.
+            print(f"Generated {len(embeddings)} embeddings.")
+            print(f"Shape of first embedding: {embeddings[0].shape}")
+            assert np.array_equal(embeddings[0], embeddings[2])
+
+        # Run the async function
+        asyncio.run(main())
+        ```
+
+    Attributes:
+        client (AsyncOpenAI): Configured OpenAI async client.
+        model_name (str): For Azure OpenAI, use your deployment name. For OpenAI, use the model name.
+        cache (AsyncBatchingMapProxy[str, NDArray[np.float32]]): Async batching proxy.
+        api_kwargs (dict): Additional OpenAI API parameters stored at initialization.
+    """
+
+    client: AsyncOpenAI
+    model_name: str
+    cache: AsyncBatchingMapProxy[str, NDArray[np.float32]] = field(
+        default_factory=lambda: AsyncBatchingMapProxy(batch_size=None, max_concurrency=8)
+    )
+    api_kwargs: dict[str, int | float | str | bool] = field(default_factory=dict)
+
+    @classmethod
+    def of(
+        cls,
+        client: AsyncOpenAI,
+        model_name: str,
+        batch_size: int | None = None,
+        max_concurrency: int = 8,
+        **api_kwargs,
+    ) -> "AsyncBatchEmbeddings":
+        """Factory constructor.
+
+        Args:
+            client (AsyncOpenAI): OpenAI async client.
+            model_name (str): For Azure OpenAI, use your deployment name. For OpenAI, use the model name.
+            batch_size (int | None, optional): Max unique inputs per API call. Defaults to None
+                (automatic batch size optimization). Set to a positive integer for fixed batch size.
+            max_concurrency (int, optional): Max concurrent API calls. Defaults to 8.
+            **api_kwargs: Additional OpenAI API parameters (e.g., dimensions for text-embedding-3 models).
+
+        Returns:
+            AsyncBatchEmbeddings: Configured instance with an async batching proxy.
+        """
+        return cls(
+            client=client,
+            model_name=model_name,
+            cache=AsyncBatchingMapProxy(batch_size=batch_size, max_concurrency=max_concurrency),
+            api_kwargs=api_kwargs,
+        )
+
+    @backoff_async(exceptions=[RateLimitError, InternalServerError], scale=1, max_retries=12)
+    @observe(_LOGGER)
+    async def _embed_chunk(self, inputs: list[str]) -> list[NDArray[np.float32]]:
+        """Embed one minibatch of strings asynchronously.
+
+        This private helper handles the actual API call for a batch of inputs.
+        Exponential back-off is applied automatically when ``openai.RateLimitError``
+        is raised.
+
+        Args:
+            inputs (list[str]): Input strings to be embedded. Duplicates allowed.
+
+        Returns:
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+
+        Raises:
+            RateLimitError: Propagated if retries are exhausted.
+        """
+        responses = await self.client.embeddings.create(input=inputs, model=self.model_name, **self.api_kwargs)
+        return [np.array(d.embedding, dtype=np.float32) for d in responses.data]
+
+    @observe(_LOGGER)
+    async def create(self, inputs: list[str]) -> list[NDArray[np.float32]]:
+        """Generate embeddings for inputs using proxy batching (async).
+
+        Args:
+            inputs (list[str]): Input strings. Duplicates allowed.
+
+        Returns:
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+        """
+        return await self.cache.map(inputs, self._embed_chunk)  # type: ignore[arg-type]

openaivec/{log.py → _log.py}

@@ -2,10 +2,10 @@ import functools
 import json
 import time
 import uuid
+from collections.abc import Callable
 from logging import Logger
-from typing import Callable
 
-__all__ = ["observe"]
+__all__ = []
 
 
 def observe(logger: Logger):

openaivec/_model.py

@@ -0,0 +1,113 @@
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+__all__ = [
+    "PreparedTask",
+]
+
+ResponseFormat = TypeVar("ResponseFormat")
+
+
+@dataclass(frozen=True)
+class PreparedTask(Generic[ResponseFormat]):
+    """A data class representing a complete task configuration for OpenAI API calls.
+
+    This class encapsulates the instructions and expected response format for
+    executing a task against the OpenAI Responses API.
+
+    Attributes:
+        instructions (str): The prompt or instructions to send to the OpenAI model.
+            This should contain clear, specific directions for the task.
+        response_format (type[ResponseFormat]): A Pydantic model class or str type that defines the expected
+            structure of the response. Can be either a BaseModel subclass or str.
+
+    Example:
+        Creating a custom task:
+
+        ```python
+        from pydantic import BaseModel
+
+        class TranslationResponse(BaseModel):
+            translated_text: str
+            source_language: str
+            target_language: str
+
+        custom_task = PreparedTask(
+            instructions="Translate the following text to French:",
+            response_format=TranslationResponse,
+        )
+        ```
+
+    Note:
+        This class is frozen (immutable) to ensure task configurations
+        cannot be accidentally modified after creation.
+    """
+
+    instructions: str
+    response_format: type[ResponseFormat]
+
+
+@dataclass(frozen=True)
+class ResponsesModelName:
+    """Container for responses model name configuration.
+
+    Attributes:
+        value (str): The model name for OpenAI responses API.
+    """
+
+    value: str
+
+
+@dataclass(frozen=True)
+class EmbeddingsModelName:
+    """Container for embeddings model name configuration.
+
+    Attributes:
+        value (str): The model name for OpenAI embeddings API.
+    """
+
+    value: str
+
+
+@dataclass(frozen=True)
+class OpenAIAPIKey:
+    """Container for OpenAI API key configuration.
+
+    Attributes:
+        value (str | None): The API key for OpenAI services.
+    """
+
+    value: str | None
+
+
+@dataclass(frozen=True)
+class AzureOpenAIAPIKey:
+    """Container for Azure OpenAI API key configuration.
+
+    Attributes:
+        value (str | None): The API key for Azure OpenAI services.
+    """
+
+    value: str | None
+
+
+@dataclass(frozen=True)
+class AzureOpenAIBaseURL:
+    """Container for Azure OpenAI base URL configuration.
+
+    Attributes:
+        value (str | None): The base URL for Azure OpenAI services.
+    """
+
+    value: str | None
+
+
+@dataclass(frozen=True)
+class AzureOpenAIAPIVersion:
+    """Container for Azure OpenAI API version configuration.
+
+    Attributes:
+        value (str): The API version for Azure OpenAI services.
+    """
+
+    value: str