openaivec 0.13.5__py3-none-any.whl → 0.13.7__py3-none-any.whl

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/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/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/log.py

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

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/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)

openaivec/pandas_ext.py

@@ -42,12 +42,19 @@ to easily interact with OpenAI APIs for tasks like generating responses or embed
 import inspect
 import json
 import logging
-from typing import Any, Awaitable, Callable, List, Type, TypeVar
+from typing import Awaitable, Callable, List, Type, TypeVar
 
 import numpy as np
 import pandas as pd
 import tiktoken
 from openai import AsyncOpenAI, OpenAI
+
+__all__ = [
+    "embeddings_model",
+    "responses_model",
+    "use",
+    "use_async",
+]
 from pydantic import BaseModel
 
 from openaivec.embeddings import AsyncBatchEmbeddings, BatchEmbeddings
@@ -184,6 +191,7 @@ class OpenAIVecSeriesAccessor:
         Args:
             cache (BatchingMapProxy[str, np.ndarray]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
 
         Returns:
             pandas.Series: Series whose values are ``np.ndarray`` objects
@@ -217,7 +225,7 @@ class OpenAIVecSeriesAccessor:
         self,
         instructions: str,
         response_format: Type[ResponseFormat] = str,
-        batch_size: int = 128,
+        batch_size: int | None = None,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         show_progress: bool = False,
@@ -247,8 +255,9 @@ class OpenAIVecSeriesAccessor:
             instructions (str): System prompt prepended to every user message.
             response_format (Type[ResponseFormat], optional): Pydantic model or built‑in
                 type the assistant should return. Defaults to ``str``.
-            batch_size (int, optional): Number of prompts grouped into a single
-                request. Defaults to ``128``.
+            batch_size (int | None, optional): Number of prompts grouped into a single
+                request. Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
             top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
@@ -266,7 +275,7 @@ class OpenAIVecSeriesAccessor:
 
     def task_with_cache(
         self,
-        task: PreparedTask,
+        task: PreparedTask[ResponseFormat],
         cache: BatchingMapProxy[str, ResponseFormat],
     ) -> pd.Series:
         """Execute a prepared task on every Series element using a provided cache.
@@ -280,6 +289,7 @@ class OpenAIVecSeriesAccessor:
                 response format, and other parameters for processing the inputs.
             cache (BatchingMapProxy[str, ResponseFormat]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
 
         Returns:
             pandas.Series: Series whose values are instances of the task's
@@ -311,7 +321,7 @@ class OpenAIVecSeriesAccessor:
         )
         return pd.Series(client.parse(self._obj.tolist()), index=self._obj.index, name=self._obj.name)
 
-    def task(self, task: PreparedTask, batch_size: int = 128, show_progress: bool = False) -> pd.Series:
+    def task(self, task: PreparedTask, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
         """Execute a prepared task on every Series element.
 
         This method applies a pre-configured task to each element in the Series,
@@ -343,8 +353,9 @@ class OpenAIVecSeriesAccessor:
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
                 response format, and other parameters for processing the inputs.
-            batch_size (int, optional): Number of prompts grouped into a single
-                request to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of prompts grouped into a single
+                request to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
 
         Returns:
@@ -356,7 +367,7 @@ class OpenAIVecSeriesAccessor:
             cache=BatchingMapProxy(batch_size=batch_size, show_progress=show_progress),
         )
 
-    def embeddings(self, batch_size: int = 128, show_progress: bool = False) -> pd.Series:
+    def embeddings(self, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
         """Compute OpenAI embeddings for every Series element.
 
         Example:
@@ -378,8 +389,9 @@ class OpenAIVecSeriesAccessor:
             The default embedding model is `text-embedding-3-small`.
 
         Args:
-            batch_size (int, optional): Number of inputs grouped into a
-                single request. Defaults to ``128``.
+            batch_size (int | None, optional): Number of inputs grouped into a
+                single request. Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
 
         Returns:
@@ -494,6 +506,7 @@ class OpenAIVecDataFrameAccessor:
             instructions (str): System prompt for the assistant.
             cache (BatchingMapProxy[str, ResponseFormat]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
             response_format (Type[ResponseFormat], optional): Desired Python type of the
                 responses. Defaults to ``str``.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
@@ -538,7 +551,7 @@ class OpenAIVecDataFrameAccessor:
         self,
         instructions: str,
         response_format: Type[ResponseFormat] = str,
-        batch_size: int = 128,
+        batch_size: int | None = None,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         show_progress: bool = False,
@@ -573,8 +586,9 @@ class OpenAIVecDataFrameAccessor:
             instructions (str): System prompt for the assistant.
             response_format (Type[ResponseFormat], optional): Desired Python type of the
                 responses. Defaults to ``str``.
-            batch_size (int, optional): Number of requests sent in one batch.
-                Defaults to ``128``.
+            batch_size (int | None, optional): Number of requests sent in one batch.
+                Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
             top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
@@ -590,7 +604,7 @@ class OpenAIVecDataFrameAccessor:
             top_p=top_p,
         )
 
-    def task(self, task: PreparedTask, batch_size: int = 128, show_progress: bool = False) -> pd.Series:
+    def task(self, task: PreparedTask, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
         """Execute a prepared task on each DataFrame row after serialising it to JSON.
 
         This method applies a pre-configured task to each row in the DataFrame,
@@ -618,8 +632,9 @@ class OpenAIVecDataFrameAccessor:
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
                 response format, and other parameters for processing the inputs.
-            batch_size (int, optional): Number of requests sent in one batch
-                to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of requests sent in one batch
+                to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
 
         Returns:
@@ -634,7 +649,7 @@ class OpenAIVecDataFrameAccessor:
             )
         )
 
-    def fillna(self, target_column_name: str, max_examples: int = 500, batch_size: int = 128) -> pd.DataFrame:
+    def fillna(self, target_column_name: str, max_examples: int = 500, batch_size: int | None = None) -> pd.DataFrame:
         """Fill missing values in a DataFrame column using AI-powered inference.
 
         This method uses machine learning to intelligently fill missing (NaN) values
@@ -648,8 +663,9 @@ class OpenAIVecDataFrameAccessor:
             max_examples (int, optional): The maximum number of example rows to use
                 for context when predicting missing values. Higher values may improve
                 accuracy but increase API costs and processing time. Defaults to 500.
-            batch_size (int, optional): Number of requests sent in one batch
-                to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of requests sent in one batch
+                to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
 
         Returns:
             pandas.DataFrame: A new DataFrame with missing values filled in the target
@@ -721,7 +737,7 @@ class OpenAIVecDataFrameAccessor:
         return self._obj.apply(
             lambda row: np.dot(row[col1], row[col2]) / (np.linalg.norm(row[col1]) * np.linalg.norm(row[col2])),
             axis=1,
-        ).rename("similarity")
+        ).rename("similarity")  # type: ignore[arg-type]
 
 
 @pd.api.extensions.register_series_accessor("aio")
@@ -750,6 +766,7 @@ class AsyncOpenAIVecSeriesAccessor:
             instructions (str): System prompt prepended to every user message.
             cache (AsyncBatchingMapProxy[str, ResponseFormat]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
             response_format (Type[ResponseFormat], optional): Pydantic model or built‑in
                 type the assistant should return. Defaults to ``str``.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
@@ -804,6 +821,7 @@ class AsyncOpenAIVecSeriesAccessor:
         Args:
             cache (AsyncBatchingMapProxy[str, np.ndarray]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
 
         Returns:
             pandas.Series: Series whose values are ``np.ndarray`` objects
@@ -844,7 +862,7 @@ class AsyncOpenAIVecSeriesAccessor:
 
     async def task_with_cache(
         self,
-        task: PreparedTask,
+        task: PreparedTask[ResponseFormat],
         cache: AsyncBatchingMapProxy[str, ResponseFormat],
     ) -> pd.Series:
         """Execute a prepared task on every Series element using a provided cache (asynchronously).
@@ -859,6 +877,7 @@ class AsyncOpenAIVecSeriesAccessor:
                 response format, and other parameters for processing the inputs.
             cache (AsyncBatchingMapProxy[str, ResponseFormat]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
 
         Returns:
             pandas.Series: Series whose values are instances of the task's
@@ -902,7 +921,7 @@ class AsyncOpenAIVecSeriesAccessor:
         self,
         instructions: str,
         response_format: Type[ResponseFormat] = str,
-        batch_size: int = 128,
+        batch_size: int | None = None,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         max_concurrency: int = 8,
@@ -934,8 +953,9 @@ class AsyncOpenAIVecSeriesAccessor:
             instructions (str): System prompt prepended to every user message.
             response_format (Type[ResponseFormat], optional): Pydantic model or built‑in
                 type the assistant should return. Defaults to ``str``.
-            batch_size (int, optional): Number of prompts grouped into a single
-                request. Defaults to ``128``.
+            batch_size (int | None, optional): Number of prompts grouped into a single
+                request. Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
             top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
             max_concurrency (int, optional): Maximum number of concurrent
@@ -959,7 +979,7 @@ class AsyncOpenAIVecSeriesAccessor:
         )
 
     async def embeddings(
-        self, batch_size: int = 128, max_concurrency: int = 8, show_progress: bool = False
+        self, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
     ) -> pd.Series:
         """Compute OpenAI embeddings for every Series element (asynchronously).
 
@@ -983,8 +1003,9 @@ class AsyncOpenAIVecSeriesAccessor:
             The default embedding model is `text-embedding-3-small`.
 
         Args:
-            batch_size (int, optional): Number of inputs grouped into a
-                single request. Defaults to ``128``.
+            batch_size (int | None, optional): Number of inputs grouped into a
+                single request. Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             max_concurrency (int, optional): Maximum number of concurrent
                 requests. Defaults to ``8``.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
@@ -1003,7 +1024,7 @@ class AsyncOpenAIVecSeriesAccessor:
         )
 
     async def task(
-        self, task: PreparedTask, batch_size: int = 128, max_concurrency: int = 8, show_progress: bool = False
+        self, task: PreparedTask, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
     ) -> pd.Series:
         """Execute a prepared task on every Series element (asynchronously).
 
@@ -1037,8 +1058,9 @@ class AsyncOpenAIVecSeriesAccessor:
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
                 response format, and other parameters for processing the inputs.
-            batch_size (int, optional): Number of prompts grouped into a single
-                request to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of prompts grouped into a single
+                request to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
             max_concurrency (int, optional): Maximum number of concurrent
                 requests. Defaults to 8.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
@@ -1084,6 +1106,7 @@ class AsyncOpenAIVecDataFrameAccessor:
             instructions (str): System prompt for the assistant.
             cache (AsyncBatchingMapProxy[str, ResponseFormat]): Pre-configured cache
                 instance for managing API call batching and deduplication.
+                Set cache.batch_size=None to enable automatic batch size optimization.
             response_format (Type[ResponseFormat], optional): Desired Python type of the
                 responses. Defaults to ``str``.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
@@ -1134,7 +1157,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         self,
         instructions: str,
         response_format: Type[ResponseFormat] = str,
-        batch_size: int = 128,
+        batch_size: int | None = None,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         max_concurrency: int = 8,
@@ -1171,8 +1194,9 @@ class AsyncOpenAIVecDataFrameAccessor:
             instructions (str): System prompt for the assistant.
             response_format (Type[ResponseFormat], optional): Desired Python type of the
                 responses. Defaults to ``str``.
-            batch_size (int, optional): Number of requests sent in one batch.
-                Defaults to ``128``.
+            batch_size (int | None, optional): Number of requests sent in one batch.
+                Defaults to ``None`` (automatic batch size optimization
+                based on execution time). Set to a positive integer for fixed batch size.
             temperature (float, optional): Sampling temperature. Defaults to ``0.0``.
             top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
             max_concurrency (int, optional): Maximum number of concurrent
@@ -1196,7 +1220,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         )
 
     async def task(
-        self, task: PreparedTask, batch_size: int = 128, max_concurrency: int = 8, show_progress: bool = False
+        self, task: PreparedTask, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
     ) -> pd.Series:
         """Execute a prepared task on each DataFrame row after serialising it to JSON (asynchronously).
 
@@ -1235,8 +1259,9 @@ class AsyncOpenAIVecDataFrameAccessor:
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
                 response format, and other parameters for processing the inputs.
-            batch_size (int, optional): Number of requests sent in one batch
-                to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of requests sent in one batch
+                to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
             max_concurrency (int, optional): Maximum number of concurrent
                 requests. Defaults to 8.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
@@ -1286,7 +1311,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         else:
             return result
 
-    async def assign(self, **kwargs: Any) -> pd.DataFrame:
+    async def assign(self, **kwargs) -> pd.DataFrame:
         """Asynchronously assign new columns to the DataFrame, evaluating sequentially.
 
         This method extends pandas' `assign` method by supporting asynchronous
@@ -1321,7 +1346,7 @@ class AsyncOpenAIVecDataFrameAccessor:
             ```
 
         Args:
-            **kwargs: Any. Column names as keys and either static values or callables
+            **kwargs: Column names as keys and either static values or callables
                 (synchronous or asynchronous) as values.
 
         Returns:
@@ -1346,7 +1371,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         return df_current
 
     async def fillna(
-        self, target_column_name: str, max_examples: int = 500, batch_size: int = 128, max_concurrency: int = 8
+        self, target_column_name: str, max_examples: int = 500, batch_size: int | None = None, max_concurrency: int = 8
     ) -> pd.DataFrame:
         """Fill missing values in a DataFrame column using AI-powered inference (asynchronously).
 
@@ -1361,8 +1386,9 @@ class AsyncOpenAIVecDataFrameAccessor:
             max_examples (int, optional): The maximum number of example rows to use
                 for context when predicting missing values. Higher values may improve
                 accuracy but increase API costs and processing time. Defaults to 500.
-            batch_size (int, optional): Number of requests sent in one batch
-                to optimize API usage. Defaults to 128.
+            batch_size (int | None, optional): Number of requests sent in one batch
+                to optimize API usage. Defaults to ``None`` (automatic batch size
+                optimization based on execution time). Set to a positive integer for fixed batch size.
             max_concurrency (int, optional): Maximum number of concurrent
                 requests. Defaults to 8.