openaivec 0.14.7__py3-none-any.whl → 0.14.9__py3-none-any.whl

openaivec/_di.py

@@ -1,6 +1,7 @@
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from threading import RLock
-from typing import Any, Callable, Dict, Set, Type, TypeVar
+from typing import Any, TypeVar
 
 __all__ = []
 
@@ -119,12 +120,12 @@ class Container:
         ```
     """
 
-    _instances: Dict[Type[Any], Any] = field(default_factory=dict)
-    _providers: Dict[Type[Any], Provider[Any]] = field(default_factory=dict)
+    _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)
+    _resolving: set[type[Any]] = field(default_factory=set)
 
-    def register(self, cls: Type[T], provider: Provider[T]) -> None:
+    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
@@ -150,7 +151,7 @@ class Container:
 
             self._providers[cls] = provider
 
-    def register_instance(self, cls: Type[T], instance: T) -> None:
+    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
@@ -178,7 +179,7 @@ class Container:
             self._instances[cls] = instance
             self._providers[cls] = lambda: instance
 
-    def resolve(self, cls: Type[T]) -> T:
+    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
@@ -232,7 +233,7 @@ class Container:
             finally:
                 self._resolving.discard(cls)
 
-    def is_registered(self, cls: Type[Any]) -> bool:
+    def is_registered(self, cls: type[Any]) -> bool:
         """Check if a service type is registered in the container.
 
         Args:
@@ -252,7 +253,7 @@ class Container:
         with self._lock:
             return cls in self._providers
 
-    def unregister(self, cls: Type[Any]) -> None:
+    def unregister(self, cls: type[Any]) -> None:
         """Unregister a service type from the container.
 
         Removes the provider function and any cached singleton instance for

openaivec/_dynamic.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+import re
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field, create_model
+
+__all__: list[str] = []
+
+_MAX_ENUM_VALUES = 24
+
+
+class FieldSpec(BaseModel):
+    name: str = Field(
+        description=(
+            "Field name in lower_snake_case. Rules: (1) Use only lowercase letters, numbers, and underscores; "
+            "must start with a letter. (2) For numeric quantities append an explicit unit (e.g. 'duration_seconds', "
+            "'price_usd'). (3) Boolean fields use an affirmative 'is_' prefix (e.g. 'is_active'); avoid negative / "
+            "ambiguous forms like 'is_deleted' (prefer 'is_active', 'is_enabled'). (4) Name must be unique within the "
+            "containing object."
+        )
+    )
+    type: Literal[
+        "string",
+        "integer",
+        "float",
+        "boolean",
+        "enum",
+        "object",
+        "string_array",
+        "integer_array",
+        "float_array",
+        "boolean_array",
+        "enum_array",
+        "object_array",
+    ] = Field(
+        description=(
+            "Logical data type. Allowed values: string | integer | float | boolean | enum | object | string_array | "
+            "integer_array | float_array | boolean_array | enum_array | object_array. *_array variants represent a "
+            "homogeneous list of the base type. 'enum' / 'enum_array' require 'enum_spec'. 'object' / 'object_array' "
+            "require 'object_spec'. Primitives must not define 'enum_spec' or 'object_spec'."
+        )
+    )
+    description: str = Field(
+        description=(
+            "Human‑readable, concise explanation of the field's meaning and business intent. Should clarify units, "
+            "value semantics, and any domain constraints not captured by type. 1–2 sentences; no implementation notes."
+        )
+    )
+    enum_spec: EnumSpec | None = Field(
+        default=None,
+        description=(
+            "Enumeration specification for 'enum' / 'enum_array'. Must be provided (non-empty) for those types and "
+            "omitted for all others. Maximum size enforced by constant."
+        ),
+    )
+    object_spec: ObjectSpec | None = Field(
+        default=None,
+        description=(
+            "Nested object schema. Required for 'object' / 'object_array'; must be omitted for every other type. The "
+            "contained 'name' is used to derive the generated nested Pydantic model class name."
+        ),
+    )
+
+
+class EnumSpec(BaseModel):
+    """Enumeration specification for enum / enum_array field types.
+
+    Attributes:
+        name: Required Enum class name (UpperCamelCase). Must match ^[A-Z][A-Za-z0-9]*$. Previously optional; now
+            explicit to remove implicit coupling to the field name and make schemas self‑describing.
+        values: Raw label values (1–_MAX_ENUM_VALUES before de‑dup). Values are uppercased then
+            de-duplicated using a set; ordering of generated Enum members is not guaranteed. Any
+            casing variants collapse silently to a single member.
+    """
+
+    name: str = Field(
+        description=("Required Enum class name (UpperCamelCase). Valid pattern: ^[A-Z][A-Za-z0-9]*$."),
+    )
+    values: list[str] = Field(
+        description=(
+            f"Raw enum label values (1–{_MAX_ENUM_VALUES}). Uppercased then deduplicated; order of members "
+            "not guaranteed."
+        )
+    )
+
+
+class ObjectSpec(BaseModel):
+    name: str = Field(
+        description=(
+            "Object model class name in UpperCamelCase (singular noun). Must match ^[A-Z][A-Za-z0-9]*$ and is used "
+            "directly as the generated Pydantic model class name (no transformation)."
+        )
+    )
+    fields: list[FieldSpec] = Field(
+        description=(
+            "Non-empty list of FieldSpec definitions composing the object. Each field name must be unique; order is "
+            "preserved in the generated model."
+        )
+    )
+
+
+def _build_model(object_spec: ObjectSpec) -> type[BaseModel]:
+    lower_sname_pattern = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$")
+    upper_camel_pattern = re.compile(r"^[A-Z][A-Za-z0-9]*$")
+    type_map: dict[str, type] = {
+        "string": str,
+        "integer": int,
+        "float": float,
+        "boolean": bool,
+        "string_array": list[str],
+        "integer_array": list[int],
+        "float_array": list[float],
+        "boolean_array": list[bool],
+    }
+    output_fields: dict[str, tuple[type, object]] = {}
+
+    field_names: list[str] = [field.name for field in object_spec.fields]
+
+    # Assert that names of fields are not duplicated
+    if len(field_names) != len(set(field_names)):
+        raise ValueError("Field names must be unique within the object spec.")
+
+    for field in object_spec.fields:
+        # Assert that field names are lower_snake_case
+        if not lower_sname_pattern.match(field.name):
+            raise ValueError(f"Field name '{field.name}' must be in lower_snake_case format (e.g., 'my_field_name').")
+
+        # (EnumSpec.name now mandatory; no need to derive a fallback name from the field.)
+        match field:
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                description=description,
+                enum_spec=None,
+                object_spec=None,
+            ):
+                field_type = type_map[field.type]
+                output_fields[name] = (field_type, Field(description=description))
+
+            case FieldSpec(name=name, type="enum", description=description, enum_spec=enum_spec, object_spec=None) if (
+                enum_spec
+                and 0 < len(enum_spec.values) <= _MAX_ENUM_VALUES
+                and upper_camel_pattern.match(enum_spec.name)
+            ):
+                member_names = list({v.upper() for v in enum_spec.values})
+                enum_type = Enum(enum_spec.name, member_names)
+                output_fields[name] = (enum_type, Field(description=description))
+
+            case FieldSpec(
+                name=name, type="enum_array", description=description, enum_spec=enum_spec, object_spec=None
+            ) if (
+                enum_spec
+                and 0 < len(enum_spec.values) <= _MAX_ENUM_VALUES
+                and upper_camel_pattern.match(enum_spec.name)
+            ):
+                member_names = list({v.upper() for v in enum_spec.values})
+                enum_type = Enum(enum_spec.name, member_names)
+                output_fields[name] = (list[enum_type], Field(description=description))
+
+            case FieldSpec(
+                name=name, type="object", description=description, enum_spec=None, object_spec=object_spec
+            ) if object_spec and upper_camel_pattern.match(object_spec.name):
+                nested_model = _build_model(object_spec)
+                output_fields[name] = (nested_model, Field(description=description))
+
+            case FieldSpec(
+                name=name, type="object_array", description=description, enum_spec=None, object_spec=object_spec
+            ) if object_spec and upper_camel_pattern.match(object_spec.name):
+                nested_model = _build_model(object_spec)
+                output_fields[name] = (list[nested_model], Field(description=description))
+
+            # ---- Error cases (explicit reasons) ----
+            # Enum type without enum_spec (None or empty)
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if not enum_spec or not enum_spec.values:
+                raise ValueError(f"Field '{name}': enum type requires non-empty enum_spec values list.")
+            # Enum type exceeding max length
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and len(enum_spec.values) > _MAX_ENUM_VALUES:
+                raise ValueError(
+                    (
+                        f"Field '{name}': enum type supports at most {_MAX_ENUM_VALUES} enum_spec values "
+                        f"(got {len(enum_spec.values)})."
+                    )
+                )
+            # Enum type invalid explicit name pattern
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and not upper_camel_pattern.match(enum_spec.name):
+                raise ValueError(
+                    (f"Field '{name}': enum_spec.name '{enum_spec.name}' invalid – must match ^[A-Z][A-Za-z0-9]*$")
+                )
+            # Enum type incorrectly provides an object_spec
+            case FieldSpec(
+                name=name,
+                type="enum",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': enum type must not provide object_spec (got object_spec={object_spec!r})."
+                )
+            # Enum array type without enum_spec
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if not enum_spec or not enum_spec.values:
+                raise ValueError(f"Field '{name}': enum_array type requires non-empty enum_spec values list.")
+            # Enum array type exceeding max length
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and len(enum_spec.values) > _MAX_ENUM_VALUES:
+                raise ValueError(
+                    (
+                        f"Field '{name}': enum_array type supports at most {_MAX_ENUM_VALUES} enum_spec values "
+                        f"(got {len(enum_spec.values)})."
+                    )
+                )
+            # Enum array type invalid explicit name pattern
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ) if enum_spec and not upper_camel_pattern.match(enum_spec.name):
+                raise ValueError(
+                    (f"Field '{name}': enum_spec.name '{enum_spec.name}' invalid – must match ^[A-Z][A-Za-z0-9]*$")
+                )
+            # Enum array type incorrectly provides an object_spec
+            case FieldSpec(
+                name=name,
+                type="enum_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': enum_array type must not provide object_spec (got object_spec={object_spec!r})."
+                )
+            # Object type missing object_spec
+            case FieldSpec(
+                name=name,
+                type="object",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ):
+                raise ValueError(f"Field '{name}': object type requires object_spec (got object_spec=None).")
+            # Object array type missing object_spec
+            case FieldSpec(
+                name=name,
+                type="object_array",
+                enum_spec=enum_spec,
+                object_spec=None,
+            ):
+                raise ValueError(f"Field '{name}': object_array type requires object_spec (got object_spec=None).")
+            # Object/object_array provided but invalid name pattern
+            case FieldSpec(
+                name=name,
+                type="object" | "object_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if object_spec is not None and not upper_camel_pattern.match(object_spec.name):
+                raise ValueError(
+                    (
+                        f"Field '{name}': object_spec.name '{object_spec.name}' must be UpperCamelCase "
+                        "(regex ^[A-Z][A-Za-z0-9]*$) and contain only letters and digits."
+                    )
+                )
+            # Object/object_array types must not provide enum_spec
+            case FieldSpec(
+                name=name,
+                type="object" | "object_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if enum_spec is not None:
+                raise ValueError(
+                    f"Field '{name}': {field.type} must not define enum_spec (got enum_spec={enum_spec!r})."
+                )
+            # Primitive / simple array types must not have enum_spec
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                enum_spec=enum_spec,
+                object_spec=object_spec,
+            ) if enum_spec is not None:
+                raise ValueError(
+                    (f"Field '{name}': type '{field.type}' must not define enum_spec (got enum_spec={enum_spec!r}).")
+                )
+            # Primitive / simple array types must not have object_spec
+            case FieldSpec(
+                name=name,
+                type="string"
+                | "integer"
+                | "float"
+                | "boolean"
+                | "string_array"
+                | "integer_array"
+                | "float_array"
+                | "boolean_array",
+                enum_spec=None,
+                object_spec=object_spec,
+            ) if object_spec is not None:
+                raise ValueError(
+                    (
+                        f"Field '{name}': type '{field.type}' must not define object_spec "
+                        f"(got object_spec={object_spec!r})."
+                    )
+                )
+            # Any other unmatched combination
+            case FieldSpec() as f:
+                raise ValueError(
+                    (
+                        "Field configuration invalid / unrecognized combination: "
+                        f"name={f.name!r}, type={f.type!r}, enum_spec={'set' if f.enum_spec else None}, "
+                        f"object_spec={'set' if f.object_spec else None}."
+                    )
+                )
+
+    return create_model(object_spec.name, **output_fields)

openaivec/_embeddings.py

@@ -1,6 +1,5 @@
 from dataclasses import dataclass, field
 from logging import Logger, getLogger
-from typing import List
 
 import numpy as np
 from numpy.typing import NDArray
@@ -50,7 +49,7 @@ class BatchEmbeddings:
 
     @observe(_LOGGER)
     @backoff(exceptions=[RateLimitError, InternalServerError], scale=1, max_retries=12)
-    def _embed_chunk(self, inputs: List[str]) -> List[NDArray[np.float32]]:
+    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
@@ -58,23 +57,23 @@ class BatchEmbeddings:
         ``openai.RateLimitError`` is raised.
 
         Args:
-            inputs (List[str]): Input strings to be embedded. Duplicates allowed.
+            inputs (list[str]): Input strings to be embedded. Duplicates allowed.
 
         Returns:
-            List[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
         """
         responses = self.client.embeddings.create(input=inputs, model=self.model_name)
         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]]:
+    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.
+            inputs (list[str]): Input strings. Duplicates allowed.
 
         Returns:
-            List[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
         """
         return self.cache.map(inputs, self._embed_chunk)
 
@@ -159,7 +158,7 @@ class AsyncBatchEmbeddings:
 
     @backoff_async(exceptions=[RateLimitError, InternalServerError], scale=1, max_retries=12)
     @observe(_LOGGER)
-    async def _embed_chunk(self, inputs: List[str]) -> List[NDArray[np.float32]]:
+    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.
@@ -167,10 +166,10 @@ class AsyncBatchEmbeddings:
         is raised.
 
         Args:
-            inputs (List[str]): Input strings to be embedded. Duplicates allowed.
+            inputs (list[str]): Input strings to be embedded. Duplicates allowed.
 
         Returns:
-            List[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+            list[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
 
         Raises:
             RateLimitError: Propagated if retries are exhausted.
@@ -179,13 +178,13 @@ class AsyncBatchEmbeddings:
         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]]:
+    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.
+            inputs (list[str]): Input strings. Duplicates allowed.
 
         Returns:
-            List[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
+            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

@@ -2,8 +2,8 @@ import functools
 import json
 import time
 import uuid
+from collections.abc import Callable
 from logging import Logger
-from typing import Callable
 
 __all__ = []
 

openaivec/_model.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Generic, Type, TypeVar
+from typing import Generic, TypeVar
 
 __all__ = [
     "PreparedTask",
@@ -20,7 +20,7 @@ class PreparedTask(Generic[ResponseFormat]):
     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
+        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.
         temperature (float): Controls randomness in the model's output.
             Range: 0.0 to 1.0. Lower values make output more deterministic.
@@ -54,7 +54,7 @@ class PreparedTask(Generic[ResponseFormat]):
     """
 
     instructions: str
-    response_format: Type[ResponseFormat]
+    response_format: type[ResponseFormat]
     temperature: float = 0.0
     top_p: float = 1.0
 

openaivec/_optimize.py

@@ -3,7 +3,6 @@ import time
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import List
 
 __all__ = []
 
@@ -24,7 +23,7 @@ class BatchSizeSuggester:
     max_duration: float = 60.0
     step_ratio: float = 0.2
     sample_size: int = 4
-    _history: List[PerformanceMetric] = field(default_factory=list)
+    _history: list[PerformanceMetric] = field(default_factory=list)
     _lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
     _batch_size_changed_at: datetime | None = field(default=None, init=False)
 
@@ -65,9 +64,9 @@ class BatchSizeSuggester:
                 )
 
     @property
-    def samples(self) -> List[PerformanceMetric]:
+    def samples(self) -> list[PerformanceMetric]:
         with self._lock:
-            selected: List[PerformanceMetric] = []
+            selected: list[PerformanceMetric] = []
             for metric in reversed(self._history):
                 if metric.exception is not None:
                     continue

openaivec/_prompt.py

@@ -44,7 +44,6 @@ this will produce an XML string that looks like this:
 
 import difflib
 import logging
-from typing import List
 from xml.etree import ElementTree
 
 from openai import OpenAI
@@ -90,8 +89,8 @@ class FewShotPrompt(BaseModel):
     """
 
     purpose: str
-    cautions: List[str]
-    examples: List[Example]
+    cautions: list[str]
+    examples: list[Example]
 
 
 class Step(BaseModel):
@@ -116,7 +115,7 @@ class Request(BaseModel):
 
 
 class Response(BaseModel):
-    iterations: List[Step]
+    iterations: list[Step]
 
 
 _PROMPT: str = """
@@ -358,7 +357,7 @@ class FewShotPromptBuilder:
     """
 
     _prompt: FewShotPrompt
-    _steps: List[Step]
+    _steps: list[Step]
 
     def __init__(self):
         """Initialize an empty FewShotPromptBuilder.