openaivec 0.13.5__tar.gz → 0.13.7__tar.gz

{openaivec-0.13.5 → openaivec-0.13.7}/.github/copilot-instructions.md

@@ -138,6 +138,32 @@ Don’t
 - Use `asyncio.run` in async tests (mirrors existing tests)
 - Optional integration tests can run with valid API keys; keep unit tests independent of network
 
+## Package Visibility Guidelines (`__all__`)
+
+### Public API Modules
+These modules are part of the public API and should have comprehensive `__all__` declarations:
+
+- `embeddings.py` - Batch embedding processing
+- `model.py` - Task configuration models  
+- `prompt.py` - Few-shot prompt building
+- `responses.py` - Batch response processing
+- `spark.py` - Apache Spark UDF builders
+- `pandas_ext.py` - Pandas DataFrame/Series extensions
+- `task/*` - All task modules (NLP, customer support, table operations)
+
+### Internal Modules
+These modules are for internal use only and should have `__all__ = []`:
+
+- All other modules not listed above (util.py, serialize.py, log.py, provider.py, proxy.py, di.py, optimize.py, etc.)
+
+### `__all__` Best Practices
+
+1. **Public modules**: Include all classes, functions, and constants intended for external use
+2. **Internal modules**: Use `__all__ = []` to explicitly mark as internal-only
+3. **Task modules**: Each task module should export its main classes/functions
+4. **Package `__init__.py`**: Re-export public API from all public modules
+5. **Consistency**: Maintain alphabetical ordering within `__all__` lists
+
 ## Documentation (MkDocs)
 
 - For new developer-facing APIs, update `docs/api/` and consider a short example under `docs/examples/`

{openaivec-0.13.5 → openaivec-0.13.7}/.github/workflows/python-test.yml

@@ -27,5 +27,8 @@ jobs:
       - name: Lint with ruff
         run: uv run ruff check .
 
+      - name: Type check with pyright
+        run: uv run pyright src/openaivec || echo "Type check completed with issues - see above"
+
       - name: Run tests
         run: uv run pytest

{openaivec-0.13.5 → openaivec-0.13.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openaivec
-Version: 0.13.5
+Version: 0.13.7
 Summary: Generative mutation for tabular calculation
 Project-URL: Homepage, https://microsoft.github.io/openaivec/
 Project-URL: Repository, https://github.com/microsoft/openaivec
@@ -159,7 +159,7 @@ client = BatchResponses.of(
     client=OpenAI(),
     model_name="gpt-4.1-mini",
     system_message="Please answer only with 'xx family' and do not output anything else.",
-    batch_size=32,
+    # batch_size defaults to None (automatic optimization)
 )
 
 result = client.parse(["panda", "rabbit", "koala"])
@@ -304,7 +304,7 @@ async def process_data():
     # Asynchronous processing with fine-tuned concurrency control
     results = await df["text"].aio.responses(
         "Analyze sentiment and classify as positive/negative/neutral",
-        batch_size=64,        # Process 64 items per API request
+        # batch_size defaults to None (automatic optimization)
         max_concurrency=12    # Allow up to 12 concurrent requests
     )
     return results
@@ -315,7 +315,7 @@ sentiments = asyncio.run(process_data())
 
 **Key Parameters for Performance Tuning:**
 
-- **`batch_size`** (default: 128): Controls how many inputs are grouped into a single API request. Higher values reduce API call overhead but increase memory usage and request processing time.
+- **`batch_size`** (default: None): Controls how many inputs are grouped into a single API request. When None (default), automatic batch size optimization adjusts based on execution time. Set to a positive integer for fixed batch size. Higher values reduce API call overhead but increase memory usage and request processing time.
 - **`max_concurrency`** (default: 8): Limits the number of concurrent API requests. Higher values increase throughput but may hit rate limits or overwhelm the API.
 
 **Performance Benefits:**
@@ -460,12 +460,12 @@ When using openaivec with Spark, proper configuration of `batch_size` and `max_c
 - **Transparent**: Works automatically without code changes - your existing UDFs become more efficient
 - **Partition-Level**: Each partition maintains its own cache, optimal for distributed processing patterns
 
-**`batch_size`** (default: 128):
+**`batch_size`** (default: None):
 
 - Controls how many rows are processed together in each API request within a partition
-- **Larger values**: Fewer API calls per partition, reduced overhead
-- **Smaller values**: More granular processing, better memory management
-- **Recommendation**: 32-128 depending on data complexity and partition size
+- **Default (None)**: Automatic batch size optimization adjusts based on execution time
+- **Positive integer**: Fixed batch size - larger values reduce API calls but increase memory usage
+- **Recommendation**: Use default automatic optimization, or set 32-128 for fixed batch size
 
 **`max_concurrency`** (default: 8):
 
@@ -483,7 +483,7 @@ spark.udf.register(
     "analyze_sentiment",
     responses_udf(
         instructions="Analyze sentiment as positive/negative/neutral",
-        batch_size=64,        # Good balance for most use cases
+        # batch_size defaults to None (automatic optimization)
         max_concurrency=8     # 80 total concurrent requests across cluster
     )
 )

{openaivec-0.13.5 → openaivec-0.13.7}/README.md

@@ -133,7 +133,7 @@ client = BatchResponses.of(
     client=OpenAI(),
     model_name="gpt-4.1-mini",
     system_message="Please answer only with 'xx family' and do not output anything else.",
-    batch_size=32,
+    # batch_size defaults to None (automatic optimization)
 )
 
 result = client.parse(["panda", "rabbit", "koala"])
@@ -278,7 +278,7 @@ async def process_data():
     # Asynchronous processing with fine-tuned concurrency control
     results = await df["text"].aio.responses(
         "Analyze sentiment and classify as positive/negative/neutral",
-        batch_size=64,        # Process 64 items per API request
+        # batch_size defaults to None (automatic optimization)
         max_concurrency=12    # Allow up to 12 concurrent requests
     )
     return results
@@ -289,7 +289,7 @@ sentiments = asyncio.run(process_data())
 
 **Key Parameters for Performance Tuning:**
 
-- **`batch_size`** (default: 128): Controls how many inputs are grouped into a single API request. Higher values reduce API call overhead but increase memory usage and request processing time.
+- **`batch_size`** (default: None): Controls how many inputs are grouped into a single API request. When None (default), automatic batch size optimization adjusts based on execution time. Set to a positive integer for fixed batch size. Higher values reduce API call overhead but increase memory usage and request processing time.
 - **`max_concurrency`** (default: 8): Limits the number of concurrent API requests. Higher values increase throughput but may hit rate limits or overwhelm the API.
 
 **Performance Benefits:**
@@ -434,12 +434,12 @@ When using openaivec with Spark, proper configuration of `batch_size` and `max_c
 - **Transparent**: Works automatically without code changes - your existing UDFs become more efficient
 - **Partition-Level**: Each partition maintains its own cache, optimal for distributed processing patterns
 
-**`batch_size`** (default: 128):
+**`batch_size`** (default: None):
 
 - Controls how many rows are processed together in each API request within a partition
-- **Larger values**: Fewer API calls per partition, reduced overhead
-- **Smaller values**: More granular processing, better memory management
-- **Recommendation**: 32-128 depending on data complexity and partition size
+- **Default (None)**: Automatic batch size optimization adjusts based on execution time
+- **Positive integer**: Fixed batch size - larger values reduce API calls but increase memory usage
+- **Recommendation**: Use default automatic optimization, or set 32-128 for fixed batch size
 
 **`max_concurrency`** (default: 8):
 
@@ -457,7 +457,7 @@ spark.udf.register(
     "analyze_sentiment",
     responses_udf(
         instructions="Analyze sentiment as positive/negative/neutral",
-        batch_size=64,        # Good balance for most use cases
+        # batch_size defaults to None (automatic optimization)
         max_concurrency=8     # 80 total concurrent requests across cluster
     )
 )

{openaivec-0.13.5 → openaivec-0.13.7}/pyproject.toml

@@ -39,6 +39,7 @@ dev = [
     "ipykernel>=6.29.5",
     "langdetect>=1.0.9",
     "pyarrow>=19.0.1",
+    "pyright>=1.1.403",
     "pyspark>=3.5.5",
     "pytest>=8.3.5",
     "pytest-asyncio",

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/__init__.py

@@ -1,9 +1,14 @@
 from .embeddings import AsyncBatchEmbeddings, BatchEmbeddings
+from .model import PreparedTask
+from .prompt import FewShotPrompt, FewShotPromptBuilder
 from .responses import AsyncBatchResponses, BatchResponses
 
 __all__ = [
-    "BatchResponses",
+    "AsyncBatchEmbeddings",
     "AsyncBatchResponses",
     "BatchEmbeddings",
-    "AsyncBatchEmbeddings",
+    "BatchResponses",
+    "FewShotPrompt",
+    "FewShotPromptBuilder",
+    "PreparedTask",
 ]

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/di.py

@@ -2,6 +2,8 @@ from dataclasses import dataclass, field
 from threading import RLock
 from typing import Any, Callable, Dict, Set, Type, TypeVar
 
+__all__ = []
+
 """Simple dependency injection container with singleton lifecycle management.
 
 This module provides a lightweight dependency injection container that manages

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/embeddings.py

@@ -31,16 +31,17 @@ class BatchEmbeddings:
 
     client: OpenAI
     model_name: str
-    cache: BatchingMapProxy[str, NDArray[np.float32]] = field(default_factory=lambda: BatchingMapProxy(batch_size=128))
+    cache: BatchingMapProxy[str, NDArray[np.float32]] = field(default_factory=lambda: BatchingMapProxy(batch_size=None))
 
     @classmethod
-    def of(cls, client: OpenAI, model_name: str, batch_size: int = 128) -> "BatchEmbeddings":
+    def of(cls, client: OpenAI, model_name: str, batch_size: int | None = None) -> "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, optional): Max unique inputs per API call. Defaults to 128.
+            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.
 
         Returns:
             BatchEmbeddings: Configured instance backed by a batching proxy.
@@ -127,7 +128,7 @@ class AsyncBatchEmbeddings:
     client: AsyncOpenAI
     model_name: str
     cache: AsyncBatchingMapProxy[str, NDArray[np.float32]] = field(
-        default_factory=lambda: AsyncBatchingMapProxy(batch_size=128, max_concurrency=8)
+        default_factory=lambda: AsyncBatchingMapProxy(batch_size=None, max_concurrency=8)
     )
 
     @classmethod
@@ -135,7 +136,7 @@ class AsyncBatchEmbeddings:
         cls,
         client: AsyncOpenAI,
         model_name: str,
-        batch_size: int = 128,
+        batch_size: int | None = None,
         max_concurrency: int = 8,
     ) -> "AsyncBatchEmbeddings":
         """Factory constructor.
@@ -143,7 +144,8 @@ class AsyncBatchEmbeddings:
         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, optional): Max unique inputs per API call. Defaults to 128.
+            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.
 
         Returns:
@@ -155,8 +157,8 @@ class AsyncBatchEmbeddings:
             cache=AsyncBatchingMapProxy(batch_size=batch_size, max_concurrency=max_concurrency),
         )
 
-    @observe(_LOGGER)
     @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.
 
@@ -186,4 +188,4 @@ class AsyncBatchEmbeddings:
         Returns:
             List[NDArray[np.float32]]: Embedding vectors aligned to ``inputs``.
         """
-        return await self.cache.map(inputs, self._embed_chunk)
+        return await self.cache.map(inputs, self._embed_chunk)  # type: ignore[arg-type]

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/log.py

@@ -5,7 +5,7 @@ import uuid
 from logging import Logger
 from typing import Callable
 
-__all__ = ["observe"]
+__all__ = []
 
 
 def observe(logger: Logger):

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/model.py

@@ -1,13 +1,15 @@
 from dataclasses import dataclass
-from typing import Type, TypeVar
+from typing import Generic, Type, TypeVar
 
-from pydantic import BaseModel
+__all__ = [
+    "PreparedTask",
+]
 
-ResponseFormat = TypeVar("ResponseFormat", bound=BaseModel | str)
+ResponseFormat = TypeVar("ResponseFormat")
 
 
 @dataclass(frozen=True)
-class PreparedTask:
+class PreparedTask(Generic[ResponseFormat]):
     """A data class representing a complete task configuration for OpenAI API calls.
 
     This class encapsulates all the necessary parameters for executing a task,
@@ -84,10 +86,10 @@ class OpenAIAPIKey:
     """Container for OpenAI API key configuration.
 
     Attributes:
-        value (str): The API key for OpenAI services.
+        value (str | None): The API key for OpenAI services.
     """
 
-    value: str
+    value: str | None
 
 
 @dataclass(frozen=True)
@@ -95,10 +97,10 @@ class AzureOpenAIAPIKey:
     """Container for Azure OpenAI API key configuration.
 
     Attributes:
-        value (str): The API key for Azure OpenAI services.
+        value (str | None): The API key for Azure OpenAI services.
     """
 
-    value: str
+    value: str | None
 
 
 @dataclass(frozen=True)
@@ -106,10 +108,10 @@ class AzureOpenAIBaseURL:
     """Container for Azure OpenAI base URL configuration.
 
     Attributes:
-        value (str): The base URL for Azure OpenAI services.
+        value (str | None): The base URL for Azure OpenAI services.
     """
 
-    value: str
+    value: str | None
 
 
 @dataclass(frozen=True)

{openaivec-0.13.5 → openaivec-0.13.7}/src/openaivec/optimize.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import List
 
+__all__ = []
+
 
 @dataclass(frozen=True)
 class PerformanceMetric:
@@ -20,8 +22,8 @@ class BatchSizeSuggester:
     min_batch_size: int = 10
     min_duration: float = 30.0
     max_duration: float = 60.0
-    step_ratio: float = 0.1
-    sample_size: int = 10
+    step_ratio: float = 0.2
+    sample_size: int = 4
     _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)