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

openaivec/responses.py

@@ -1,392 +0,0 @@
-import asyncio
-from dataclasses import dataclass, field
-from logging import Logger, getLogger
-from typing import Generic, List, Type, TypeVar, cast
-
-from openai import AsyncOpenAI, OpenAI, RateLimitError
-from openai.types.responses import ParsedResponse
-from pydantic import BaseModel
-
-from .log import observe
-from .task.model import PreparedTask
-from .util import backoff, backoff_async, map, map_async
-
-__all__ = [
-    "BatchResponses",
-    "AsyncBatchResponses",
-]
-
-_LOGGER: Logger = getLogger(__name__)
-
-
-def _vectorize_system_message(system_message: str) -> str:
-    """Return the system prompt that instructs the model to work on a batch.
-
-    The returned XML‐ish prompt explains two things to the LLM:
-
-    1. The *general* system instruction coming from the caller (`system_message`)
-       is preserved verbatim.
-    2. Extra instructions describe how the model should treat the incoming JSON
-       that contains multiple user messages and how it must shape its output.
-
-    Args:
-        system_message: A single‑instance system instruction the caller would
-            normally send to the model.
-
-    Returns:
-        A long, composite system prompt with embedded examples that can be
-        supplied to the `instructions=` field of the OpenAI **JSON mode**
-        endpoint.
-    """
-    return f"""
-<SystemMessage>
-    <ElementInstructions>
-        <Instruction>{system_message}</Instruction>
-    </ElementInstructions>
-    <BatchInstructions>
-        <Instruction>
-            You will receive multiple user messages at once.
-            Please provide an appropriate response to each message individually.
-        </Instruction>
-    </BatchInstructions>
-    <Examples>
-        <Example>
-            <Input>
-                {{
-                    "user_messages": [
-                        {{
-                            "id": 1,
-                            "body": "{{user_message_1}}"
-                        }},
-                        {{
-                            "id": 2,
-                            "body": "{{user_message_2}}"
-                        }}
-                    ]
-                }}
-            </Input>
-            <Output>
-                {{
-                    "assistant_messages": [
-                        {{
-                            "id": 1,
-                            "body": "{{assistant_response_1}}"
-                        }},
-                        {{
-                            "id": 2,
-                            "body": "{{assistant_response_2}}"
-                        }}
-                    ]
-                }}
-            </Output>
-        </Example>
-    </Examples>
-</SystemMessage>
-"""
-
-
-T = TypeVar("T")
-
-
-class Message(BaseModel, Generic[T]):
-    id: int
-    body: T
-
-
-class Request(BaseModel):
-    user_messages: List[Message[str]]
-
-
-class Response(BaseModel, Generic[T]):
-    assistant_messages: List[Message[T]]
-
-
-@dataclass(frozen=True)
-class BatchResponses(Generic[T]):
-    """Stateless façade that turns OpenAI's JSON‑mode API into a batched API.
-
-    This wrapper allows you to submit *multiple* user prompts in one JSON‑mode
-    request and receive the answers in the original order.
-
-    Example:
-        ```python
-        vector_llm = BatchResponses(
-            client=openai_client,
-            model_name="gpt‑4o‑mini",
-            system_message="You are a helpful assistant."
-        )
-        answers = vector_llm.parse(questions, batch_size=32)
-        ```
-
-    Attributes:
-        client: Initialised ``openai.OpenAI`` client.
-        model_name: Name of the model (or Azure deployment) to invoke.
-        system_message: System prompt prepended to every request.
-        temperature: Sampling temperature passed to the model.
-        top_p: Nucleus‑sampling parameter.
-        response_format: Expected Pydantic type of each assistant message
-            (defaults to ``str``).
-
-    Notes:
-        Internally the work is delegated to two helpers:
-
-        * ``_predict_chunk`` – fragments the workload and restores ordering.
-        * ``_request_llm`` – performs a single OpenAI API call.
-    """
-
-    client: OpenAI
-    model_name: str  # it would be the name of deployment for Azure
-    system_message: str
-    temperature: float = 0.0
-    top_p: float = 1.0
-    response_format: Type[T] = str
-    _vectorized_system_message: str = field(init=False)
-    _model_json_schema: dict = field(init=False)
-
-    @classmethod
-    def of_task(cls, client: OpenAI, model_name: str, task: PreparedTask) -> "BatchResponses":
-        """Create a BatchResponses instance from a PreparedTask."""
-        return cls(
-            client=client,
-            model_name=model_name,
-            system_message=task.instructions,
-            temperature=task.temperature,
-            top_p=task.top_p,
-            response_format=task.response_format,
-        )
-
-    def __post_init__(self):
-        object.__setattr__(
-            self,
-            "_vectorized_system_message",
-            _vectorize_system_message(self.system_message),
-        )
-
-    @observe(_LOGGER)
-    @backoff(exception=RateLimitError, scale=15, max_retries=8)
-    def _request_llm(self, user_messages: List[Message[str]]) -> ParsedResponse[Response[T]]:
-        """Make a single call to the OpenAI *JSON mode* endpoint.
-
-        Args:
-            user_messages: Sequence of `Message[str]` objects representing the
-                prompts for this minibatch.  Each message carries a unique `id`
-                so we can restore ordering later.
-
-        Returns:
-            ParsedResponse containing `Response[T]` which in turn holds the
-            assistant messages in arbitrary order.
-
-        Raises:
-            openai.RateLimitError: Transparently re‑raised after the
-                exponential back‑off decorator exhausts all retries.
-        """
-        response_format = self.response_format
-
-        class MessageT(BaseModel):
-            id: int
-            body: response_format  # type: ignore
-
-        class ResponseT(BaseModel):
-            assistant_messages: List[MessageT]
-
-        completion: ParsedResponse[ResponseT] = self.client.responses.parse(
-            model=self.model_name,
-            instructions=self._vectorized_system_message,
-            input=Request(user_messages=user_messages).model_dump_json(),
-            temperature=self.temperature,
-            top_p=self.top_p,
-            text_format=ResponseT,
-        )
-        return cast(ParsedResponse[Response[T]], completion)
-
-    @observe(_LOGGER)
-    def _predict_chunk(self, user_messages: List[str]) -> List[T]:
-        """Helper executed for every unique minibatch.
-
-        This method:
-        1. Converts plain strings into `Message[str]` with stable indices.
-        2. Delegates the request to `_request_llm`.
-        3. Reorders the responses so they match the original indices.
-
-        The function is *pure* – it has no side‑effects and the result depends
-        only on its arguments – which allows it to be used safely in both
-        serial and parallel execution paths.
-        """
-        messages = [Message(id=i, body=message) for i, message in enumerate(user_messages)]
-        responses: ParsedResponse[Response[T]] = self._request_llm(messages)
-        response_dict = {message.id: message.body for message in responses.output_parsed.assistant_messages}
-        sorted_responses = [response_dict.get(m.id, None) for m in messages]
-        return sorted_responses
-
-    @observe(_LOGGER)
-    def parse(self, inputs: List[str], batch_size: int) -> List[T]:
-        """Public API: batched predict.
-
-        Args:
-            inputs: All prompts that require a response.  Duplicate
-                entries are de‑duplicated under the hood to save tokens.
-            batch_size: Maximum number of *unique* prompts per LLM call.
-
-        Returns:
-            A list containing the assistant responses in the same order as
-                *inputs*.
-        """
-        return map(inputs, self._predict_chunk, batch_size)
-
-
-@dataclass(frozen=True)
-class AsyncBatchResponses(Generic[T]):
-    """Stateless façade that turns OpenAI's JSON-mode API into a batched API (Async version).
-
-    This wrapper allows you to submit *multiple* user prompts in one JSON-mode
-    request and receive the answers in the original order asynchronously. It also
-    controls the maximum number of concurrent requests to the OpenAI API.
-
-    Example:
-        ```python
-        import asyncio
-        from openai import AsyncOpenAI
-        from openaivec.aio.responses import AsyncBatchResponses
-
-        # Assuming openai_async_client is an initialized AsyncOpenAI client
-        openai_async_client = AsyncOpenAI() # Replace with your actual client initialization
-
-        vector_llm = AsyncBatchResponses(
-            client=openai_async_client,
-            model_name="gpt-4o-mini",
-            system_message="You are a helpful assistant.",
-            max_concurrency=5  # Limit concurrent requests
-        )
-        questions = ["What is the capital of France?", "Explain quantum physics simply."]
-        # Asynchronous call
-        async def main():
-            answers = await vector_llm.parse(questions, batch_size=32)
-            print(answers)
-
-        # Run the async function
-        asyncio.run(main())
-        ```
-
-    Attributes:
-        client: Initialised `openai.AsyncOpenAI` client.
-        model_name: Name of the model (or Azure deployment) to invoke.
-        system_message: System prompt prepended to every request.
-        temperature: Sampling temperature passed to the model.
-        top_p: Nucleus-sampling parameter.
-        response_format: Expected Pydantic type of each assistant message
-            (defaults to `str`).
-        max_concurrency: Maximum number of concurrent requests to the OpenAI API.
-    """
-
-    client: AsyncOpenAI
-    model_name: str  # it would be the name of deployment for Azure
-    system_message: str
-    temperature: float = 0.0
-    top_p: float = 1.0
-    response_format: Type[T] = str
-    max_concurrency: int = 8  # Default concurrency limit
-    _vectorized_system_message: str = field(init=False)
-    _model_json_schema: dict = field(init=False)
-    _semaphore: asyncio.Semaphore = field(init=False, repr=False)
-
-    @classmethod
-    def of_task(cls, client: AsyncOpenAI, model_name: str, task: PreparedTask, max_concurrency: int = 8) -> "AsyncBatchResponses":
-        """Create an AsyncBatchResponses instance from a PreparedTask."""
-        return cls(
-            client=client,
-            model_name=model_name,
-            system_message=task.instructions,
-            temperature=task.temperature,
-            top_p=task.top_p,
-            response_format=task.response_format,
-            max_concurrency=max_concurrency,
-        )
-
-    def __post_init__(self):
-        object.__setattr__(
-            self,
-            "_vectorized_system_message",
-            _vectorize_system_message(self.system_message),
-        )
-        # Initialize the semaphore after the object is created
-        # Use object.__setattr__ because the dataclass is frozen
-        object.__setattr__(self, "_semaphore", asyncio.Semaphore(self.max_concurrency))
-
-    @observe(_LOGGER)
-    @backoff_async(exception=RateLimitError, scale=15, max_retries=8)
-    async def _request_llm(self, user_messages: List[Message[str]]) -> ParsedResponse[Response[T]]:
-        """Make a single async call to the OpenAI *JSON mode* endpoint, respecting concurrency limits.
-
-        Args:
-            user_messages: Sequence of `Message[str]` objects representing the
-                prompts for this minibatch. Each message carries a unique `id`
-                so we can restore ordering later.
-
-        Returns:
-            ParsedResponse containing `Response[T]` which in turn holds the
-            assistant messages in arbitrary order.
-
-        Raises:
-            openai.RateLimitError: Transparently re-raised after the
-                exponential back-off decorator exhausts all retries.
-        """
-        response_format = self.response_format
-
-        class MessageT(BaseModel):
-            id: int
-            body: response_format  # type: ignore
-
-        class ResponseT(BaseModel):
-            assistant_messages: List[MessageT]
-
-        # Acquire semaphore before making the API call
-        async with self._semaphore:
-            # Directly await the async call instead of using asyncio.run()
-            completion: ParsedResponse[ResponseT] = await self.client.responses.parse(
-                model=self.model_name,
-                instructions=self._vectorized_system_message,
-                input=Request(user_messages=user_messages).model_dump_json(),
-                temperature=self.temperature,
-                top_p=self.top_p,
-                text_format=ResponseT,
-            )
-            return cast(ParsedResponse[Response[T]], completion)
-
-    @observe(_LOGGER)
-    async def _predict_chunk(self, user_messages: List[str]) -> List[T]:
-        """Helper executed asynchronously for every unique minibatch.
-
-        This method:
-        1. Converts plain strings into `Message[str]` with stable indices.
-        2. Delegates the request to `_request_llm`.
-        3. Reorders the responses so they match the original indices.
-
-        The function is *pure* – it has no side-effects and the result depends
-        only on its arguments.
-        """
-        messages = [Message(id=i, body=message) for i, message in enumerate(user_messages)]
-        responses: ParsedResponse[Response[T]] = await self._request_llm(messages)
-        response_dict = {message.id: message.body for message in responses.output_parsed.assistant_messages}
-        # Ensure proper handling for missing IDs - this shouldn't happen in normal operation
-        sorted_responses = [response_dict.get(m.id, None) for m in messages]
-        return sorted_responses
-
-    @observe(_LOGGER)
-    async def parse(self, inputs: List[str], batch_size: int) -> List[T]:
-        """Asynchronous public API: batched predict.
-
-        Args:
-            inputs: All prompts that require a response. Duplicate
-                entries are de-duplicated under the hood to save tokens.
-            batch_size: Maximum number of *unique* prompts per LLM call.
-
-        Returns:
-            A list containing the assistant responses in the same order as
-                *inputs*.
-        """
-
-        return await map_async(
-            inputs=inputs,
-            f=self._predict_chunk,
-            batch_size=batch_size,  # Use the batch_size argument passed to the method
-        )

openaivec/serialize.py

@@ -1,225 +0,0 @@
-"""Serialization utilities for Pydantic BaseModel classes.
-
-This module provides utilities for converting Pydantic BaseModel classes
-to and from JSON schema representations. It supports dynamic model creation
-from JSON schemas with special handling for enum fields, which are converted
-to Literal types for better type safety and compatibility.
-
-Example:
-    Basic serialization and deserialization:
-    
-    ```python
-    from pydantic import BaseModel
-    from typing import Literal
-    
-    class Status(BaseModel):
-        value: Literal["active", "inactive"]
-        description: str
-    
-    # Serialize to JSON schema
-    schema = serialize_base_model(Status)
-    
-    # Deserialize back to BaseModel class
-    DynamicStatus = deserialize_base_model(schema)
-    instance = DynamicStatus(value="active", description="User is active")
-    ```
-"""
-
-from typing import Any, Dict, List, Type, Literal
-
-from pydantic import BaseModel, Field, create_model
-
-__all__ = ["deserialize_base_model", "serialize_base_model"]
-
-
-def serialize_base_model(obj: Type[BaseModel]) -> Dict[str, Any]:
-    """Serialize a Pydantic BaseModel to JSON schema.
-    
-    Args:
-        obj: The Pydantic BaseModel class to serialize.
-        
-    Returns:
-        A dictionary containing the JSON schema representation of the model.
-        
-    Example:
-        ```python
-        from pydantic import BaseModel
-        
-        class Person(BaseModel):
-            name: str
-            age: int
-            
-        schema = serialize_base_model(Person)
-        ```
-    """
-    return obj.model_json_schema()
-
-
-def dereference_json_schema(json_schema: Dict[str, Any]) -> Dict[str, Any]:
-    """Dereference JSON schema by resolving $ref pointers.
-    
-    This function resolves all $ref references in a JSON schema by replacing
-    them with the actual referenced definitions from the $defs section.
-    
-    Args:
-        json_schema: The JSON schema containing potential $ref references.
-        
-    Returns:
-        A dereferenced JSON schema with all $ref pointers resolved.
-        
-    Example:
-        ```python
-        schema = {
-            "properties": {
-                "user": {"$ref": "#/$defs/User"}
-            },
-            "$defs": {
-                "User": {"type": "object", "properties": {"name": {"type": "string"}}}
-            }
-        }
-        dereferenced = dereference_json_schema(schema)
-        # user property will contain the actual User definition
-        ```
-    """
-    model_map = json_schema.get("$defs", {})
-
-    def dereference(obj):
-        if isinstance(obj, dict):
-            if "$ref" in obj:
-                ref = obj["$ref"].split("/")[-1]
-                return dereference(model_map[ref])
-            else:
-                return {k: dereference(v) for k, v in obj.items()}
-
-        elif isinstance(obj, list):
-            return [dereference(x) for x in obj]
-        else:
-            return obj
-
-    result = {}
-    for k, v in json_schema.items():
-        if k == "$defs":
-            continue
-
-        result[k] = dereference(v)
-
-    return result
-
-
-def parse_field(v: Dict[str, Any]) -> Any:
-    """Parse a JSON schema field definition to a Python type.
-    
-    Converts JSON schema field definitions to corresponding Python types
-    for use in Pydantic model creation.
-    
-    Args:
-        v: A dictionary containing the JSON schema field definition.
-        
-    Returns:
-        The corresponding Python type (str, int, float, bool, dict, List, or BaseModel).
-        
-    Raises:
-        ValueError: If the field type is not supported.
-        
-    Example:
-        ```python
-        field_def = {"type": "string"}
-        python_type = parse_field(field_def)  # Returns str
-        
-        array_def = {"type": "array", "items": {"type": "integer"}}
-        python_type = parse_field(array_def)  # Returns List[int]
-        ```
-    """
-    t = v["type"]
-    if t == "string":
-        return str
-    elif t == "integer":
-        return int
-    elif t == "number":
-        return float
-    elif t == "boolean":
-        return bool
-    elif t == "object":
-        # Check if it's a generic object (dict) or a nested model
-        if "properties" in v:
-            return deserialize_base_model(v)
-        else:
-            return dict
-    elif t == "array":
-        inner_type = parse_field(v["items"])
-        return List[inner_type]
-    else:
-        raise ValueError(f"Unsupported type: {t}")
-
-
-def deserialize_base_model(json_schema: Dict[str, Any]) -> Type[BaseModel]:
-    """Deserialize a JSON schema to a Pydantic BaseModel class.
-    
-    Creates a dynamic Pydantic BaseModel class from a JSON schema definition.
-    For enum fields, this function uses Literal types instead of Enum classes
-    for better type safety and compatibility with systems like Apache Spark.
-    
-    Args:
-        json_schema: A dictionary containing the JSON schema definition.
-        
-    Returns:
-        A dynamically created Pydantic BaseModel class.
-        
-    Example:
-        ```python
-        schema = {
-            "title": "Person",
-            "type": "object",
-            "properties": {
-                "name": {"type": "string", "description": "Person's name"},
-                "status": {
-                    "type": "string",
-                    "enum": ["active", "inactive"],
-                    "description": "Person's status"
-                }
-            }
-        }
-        
-        PersonModel = deserialize_base_model(schema)
-        person = PersonModel(name="John", status="active")
-        ```
-        
-    Note:
-        Enum fields are converted to Literal types for improved compatibility
-        and type safety. This ensures better integration with data processing
-        frameworks like Apache Spark.
-    """
-    fields = {}
-    properties = dereference_json_schema(json_schema).get("properties", {})
-
-    for k, v in properties.items():
-        if "enum" in v:
-            enum_values = v["enum"]
-            
-            # Always use Literal instead of Enum for better type safety and Spark compatibility
-            if len(enum_values) == 1:
-                literal_type = Literal[enum_values[0]]
-            else:
-                # Create Literal with multiple values
-                literal_type = Literal[tuple(enum_values)]
-            
-            description = v.get("description")
-            default_value = v.get("default")
-            
-            if default_value is not None:
-                field_info = Field(default=default_value, description=description) if description is not None else Field(default=default_value)
-            else:
-                field_info = Field(description=description) if description is not None else Field()
-            
-            fields[k] = (literal_type, field_info)
-        else:
-            description = v.get("description")
-            default_value = v.get("default")
-            
-            if default_value is not None:
-                field_info = Field(default=default_value, description=description) if description is not None else Field(default=default_value)
-            else:
-                field_info = Field(description=description) if description is not None else Field()
-            
-            fields[k] = (parse_field(v), field_info)
-    return create_model(json_schema["title"], **fields)

openaivec/task/model.py

@@ -1,84 +0,0 @@
-"""Task model module for openaivec.
-
-This module provides predefined task models for the OpenAI API.
-The `PreparedTask` class represents a complete task configuration including
-instructions, response format, and sampling parameters.
-
-Example:
-    Basic usage with a predefined task:
-    
-    ```python
-    from openai import OpenAI
-    from openaivec.task import nlp
-    from openaivec.responses import BatchResponses
-
-    translation_task: BatchResponses = BatchResponses.of_task(
-        client=OpenAI(),
-        model_name="gpt-4.1-mini",
-        task=nlp.MULTILINGUAL_TRANSLATION
-    )
-    ```
-
-Note:
-    This module uses Pydantic models for response format validation and
-    type safety.
-"""
-
-from dataclasses import dataclass
-from typing import Type, TypeVar
-from pydantic import BaseModel
-
-__all__ = ['PreparedTask']
-
-T = TypeVar('T', bound=BaseModel)
-
-
-
-@dataclass(frozen=True)
-class PreparedTask:
-    """A data class representing a complete task configuration for OpenAI API calls.
-    
-    This class encapsulates all the necessary parameters for executing a task,
-    including the instructions to be sent to the model, the expected response
-    format using Pydantic models, and sampling parameters for controlling
-    the model's output behavior.
-    
-    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[T]): A Pydantic model class that defines the expected
-            structure of the response. Must inherit from BaseModel.
-        temperature (float): Controls randomness in the model's output.
-            Range: 0.0 to 1.0. Lower values make output more deterministic.
-            Defaults to 0.0.
-        top_p (float): Controls diversity via nucleus sampling. Only tokens
-            comprising the top_p probability mass are considered.
-            Range: 0.0 to 1.0. Defaults to 1.0.
-    
-    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,
-            temperature=0.1,
-            top_p=0.9
-        )
-        ```
-    
-    Note:
-        This class is frozen (immutable) to ensure task configurations
-        cannot be accidentally modified after creation.
-    """
-    instructions: str
-    response_format: Type[T]
-    temperature: float = 0.0
-    top_p: float = 1.0