openaivec 0.14.1__py3-none-any.whl → 0.14.3__py3-none-any.whl

openaivec/pandas_ext.py

@@ -74,6 +74,21 @@ __all__ = [
 _LOGGER = logging.getLogger(__name__)
 
 
+# ---------------------------------------------------------------------------
+# Internal helpers (not exported)
+# ---------------------------------------------------------------------------
+def _df_rows_to_json_series(df: pd.DataFrame) -> pd.Series:
+    """Return a Series of JSON strings (UTF-8, no ASCII escaping) representing DataFrame rows.
+
+    Each element is the JSON serialisation of the corresponding row as a dict. Index and
+    name are preserved so downstream operations retain alignment. This consolidates the
+    previously duplicated inline pipeline used by responses*/task* DataFrame helpers.
+    """
+    return pd.Series(df.to_dict(orient="records"), index=df.index, name="record").map(
+        lambda x: json.dumps(x, ensure_ascii=False)
+    )
+
+
 T = TypeVar("T")  # For pipe function return type
 
 
@@ -165,6 +180,7 @@ class OpenAIVecSeriesAccessor:
         response_format: Type[ResponseFormat] = str,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
+        **api_kwargs,
     ) -> pd.Series:
         client: BatchResponses = BatchResponses(
             client=CONTAINER.resolve(OpenAI),
@@ -176,7 +192,8 @@ class OpenAIVecSeriesAccessor:
             top_p=top_p,
         )
 
-        return pd.Series(client.parse(self._obj.tolist()), index=self._obj.index, name=self._obj.name)
+        # Forward any extra kwargs to the underlying Responses API.
+        return pd.Series(client.parse(self._obj.tolist(), **api_kwargs), index=self._obj.index, name=self._obj.name)
 
     def embeddings_with_cache(
         self,
@@ -229,6 +246,7 @@ class OpenAIVecSeriesAccessor:
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Call an LLM once for every Series element.
 
@@ -246,10 +264,6 @@ class OpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series of strings, each containing the
-            assistant's response to the corresponding input.
-            The model used is set by the `responses_model` function.
-            The default model is `gpt-4.1-mini`.
 
         Args:
             instructions (str): System prompt prepended to every user message.
@@ -271,46 +285,41 @@ class OpenAIVecSeriesAccessor:
             response_format=response_format,
             temperature=temperature,
             top_p=top_p,
+            **api_kwargs,
         )
 
     def task_with_cache(
         self,
         task: PreparedTask[ResponseFormat],
         cache: BatchingMapProxy[str, ResponseFormat],
+        **api_kwargs,
     ) -> pd.Series:
         """Execute a prepared task on every Series element using a provided cache.
 
-        This method allows external control over caching behavior by accepting
-        a pre-configured BatchingMapProxy instance, enabling cache sharing
-        across multiple operations or custom batch size management.
+        This mirrors ``responses_with_cache`` but uses the task's stored instructions,
+        response format, temperature and top_p. A supplied ``BatchingMapProxy`` enables
+        cross‑operation deduplicated reuse and external batch size / progress control.
 
         Args:
-            task (PreparedTask): A pre-configured task containing instructions,
-                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.
+            task (PreparedTask): Prepared task (instructions + response_format + sampling params).
+            cache (BatchingMapProxy[str, ResponseFormat]): Pre‑configured cache instance.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) forwarded verbatim to the underlying client. Core routing keys
+            (``model``, system instructions, user input) are managed internally and cannot be overridden.
 
         Returns:
-            pandas.Series: Series whose values are instances of the task's
-                response format, aligned with the original Series index.
+            pandas.Series: Task results aligned with the original Series index.
 
         Example:
             ```python
-            from openaivec._model import PreparedTask
             from openaivec._proxy import BatchingMapProxy
-
-            # Create a shared cache with custom batch size
             shared_cache = BatchingMapProxy(batch_size=64)
-
-            # Assume you have a prepared task for sentiment analysis
-            sentiment_task = PreparedTask(...)
-
-            reviews = pd.Series(["Great product!", "Not satisfied", "Amazing quality"])
-            results = reviews.ai.task_with_cache(sentiment_task, cache=shared_cache)
+            reviews.ai.task_with_cache(sentiment_task, cache=shared_cache)
             ```
         """
-        client = BatchResponses(
+        client: BatchResponses = BatchResponses(
             client=CONTAINER.resolve(OpenAI),
             model_name=CONTAINER.resolve(ResponsesModelName).value,
             system_message=task.instructions,
@@ -319,15 +328,17 @@ class OpenAIVecSeriesAccessor:
             temperature=task.temperature,
             top_p=task.top_p,
         )
-        return pd.Series(client.parse(self._obj.tolist()), index=self._obj.index, name=self._obj.name)
+        return pd.Series(client.parse(self._obj.tolist(), **api_kwargs), index=self._obj.index, name=self._obj.name)
 
-    def task(self, task: PreparedTask, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
+    def task(
+        self,
+        task: PreparedTask,
+        batch_size: int | None = None,
+        show_progress: bool = False,
+        **api_kwargs,
+    ) -> pd.Series:
         """Execute a prepared task on every Series element.
 
-        This method applies a pre-configured task to each element in the Series,
-        using the task's instructions and response format to generate structured
-        responses from the language model.
-
         Example:
             ```python
             from openaivec._model import PreparedTask
@@ -347,8 +358,6 @@ class OpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series containing the task results for each
-            corresponding input element, following the task's defined structure.
 
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
@@ -358,13 +367,19 @@ class OpenAIVecSeriesAccessor:
                 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``.
 
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client. Core batching / routing
+            keys (``model``, ``instructions`` / system message, user ``input``) are managed by the
+            library and cannot be overridden.
+
         Returns:
-            pandas.Series: Series whose values are instances of the task's
-                response format, aligned with the original Series index.
+            pandas.Series: Series whose values are instances of the task's response format.
         """
         return self.task_with_cache(
             task=task,
             cache=BatchingMapProxy(batch_size=batch_size, show_progress=show_progress),
+            **api_kwargs,
         )
 
     def embeddings(self, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
@@ -383,10 +398,6 @@ class OpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series of numpy arrays, each containing the
-            embedding vector for the corresponding input.
-            The embedding model is set by the `embeddings_model` function.
-            The default embedding model is `text-embedding-3-small`.
 
         Args:
             batch_size (int | None, optional): Number of inputs grouped into a
@@ -495,6 +506,7 @@ class OpenAIVecDataFrameAccessor:
         response_format: Type[ResponseFormat] = str,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
+        **api_kwargs,
     ) -> pd.Series:
         """Generate a response for each row after serialising it to JSON using a provided cache.
 
@@ -533,18 +545,13 @@ class OpenAIVecDataFrameAccessor:
             )
             ```
         """
-        return self._obj.pipe(
-            lambda df: (
-                df.pipe(lambda df: pd.Series(df.to_dict(orient="records"), index=df.index, name="record"))
-                .map(lambda x: json.dumps(x, ensure_ascii=False))
-                .ai.responses_with_cache(
-                    instructions=instructions,
-                    cache=cache,
-                    response_format=response_format,
-                    temperature=temperature,
-                    top_p=top_p,
-                )
-            )
+        return _df_rows_to_json_series(self._obj).ai.responses_with_cache(
+            instructions=instructions,
+            cache=cache,
+            response_format=response_format,
+            temperature=temperature,
+            top_p=top_p,
+            **api_kwargs,
         )
 
     def responses(
@@ -555,6 +562,7 @@ class OpenAIVecDataFrameAccessor:
         temperature: float | None = 0.0,
         top_p: float = 1.0,
         show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Generate a response for each row after serialising it to JSON.
 
@@ -576,11 +584,6 @@ class OpenAIVecDataFrameAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series of strings, each containing the
-            assistant's response to the corresponding input.
-            Each row is serialised to JSON before being sent to the assistant.
-            The model used is set by the `responses_model` function.
-            The default model is `gpt-4.1-mini`.
 
         Args:
             instructions (str): System prompt for the assistant.
@@ -602,16 +605,18 @@ class OpenAIVecDataFrameAccessor:
             response_format=response_format,
             temperature=temperature,
             top_p=top_p,
+            **api_kwargs,
         )
 
-    def task(self, task: PreparedTask, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
+    def task(
+        self,
+        task: PreparedTask,
+        batch_size: int | None = None,
+        show_progress: bool = False,
+        **api_kwargs,
+    ) -> 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,
-        using the task's instructions and response format to generate structured
-        responses from the language model. Each row is serialised to JSON before
-        being processed by the task.
-
         Example:
             ```python
             from openaivec._model import PreparedTask
@@ -624,10 +629,17 @@ class OpenAIVecDataFrameAccessor:
                 {"name": "dog", "legs": 4},
                 {"name": "elephant", "legs": 4},
             ])
+            # Basic usage
             results = df.ai.task(analysis_task)
+
+            # With progress bar for large datasets
+            large_df = pd.DataFrame({"id": list(range(1000))})
+            results = large_df.ai.task(
+                analysis_task,
+                batch_size=50,
+                show_progress=True
+            )
             ```
-            This method returns a Series containing the task results for each
-            corresponding row, following the task's defined structure.
 
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
@@ -637,19 +649,56 @@ class OpenAIVecDataFrameAccessor:
                 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``.
 
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client. Core batching / routing
+            keys (``model``, ``instructions`` / system message, user ``input``) are managed by the
+            library and cannot be overridden.
+
         Returns:
             pandas.Series: Series whose values are instances of the task's
                 response format, aligned with the DataFrame's original index.
         """
-        return self._obj.pipe(
-            lambda df: (
-                df.pipe(lambda df: pd.Series(df.to_dict(orient="records"), index=df.index, name="record"))
-                .map(lambda x: json.dumps(x, ensure_ascii=False))
-                .ai.task(task=task, batch_size=batch_size, show_progress=show_progress)
-            )
+        return _df_rows_to_json_series(self._obj).ai.task(
+            task=task,
+            batch_size=batch_size,
+            show_progress=show_progress,
+            **api_kwargs,
+        )
+
+    def task_with_cache(
+        self,
+        task: PreparedTask[ResponseFormat],
+        cache: BatchingMapProxy[str, ResponseFormat],
+        **api_kwargs,
+    ) -> pd.Series:
+        """Execute a prepared task on each DataFrame row after serializing it to JSON using a provided cache.
+
+        Args:
+            task (PreparedTask): Prepared task (instructions + response_format + sampling params).
+            cache (BatchingMapProxy[str, ResponseFormat]): Pre‑configured cache instance.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``) forwarded verbatim. Core routing keys are managed internally.
+
+        Returns:
+            pandas.Series: Task results aligned with the DataFrame's original index.
+        """
+        return _df_rows_to_json_series(self._obj).ai.task_with_cache(
+            task=task,
+            cache=cache,
+            **api_kwargs,
         )
 
-    def fillna(self, target_column_name: str, max_examples: int = 500, batch_size: int | None = None) -> pd.DataFrame:
+    def fillna(
+        self,
+        target_column_name: str,
+        max_examples: int = 500,
+        batch_size: int | None = None,
+        show_progress: bool = False,
+        **api_kwargs,
+    ) -> pd.DataFrame:
         """Fill missing values in a DataFrame column using AI-powered inference.
 
         This method uses machine learning to intelligently fill missing (NaN) values
@@ -666,6 +715,11 @@ class OpenAIVecDataFrameAccessor:
             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``.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying task execution.
 
         Returns:
             pandas.DataFrame: A new DataFrame with missing values filled in the target
@@ -681,6 +735,10 @@ class OpenAIVecDataFrameAccessor:
 
             # Fill missing values in the 'name' column
             filled_df = df.ai.fillna('name')
+
+            # With progress bar for large datasets
+            large_df = pd.DataFrame({'name': [None] * 1000, 'age': list(range(1000))})
+            filled_df = large_df.ai.fillna('name', batch_size=32, show_progress=True)
             ```
 
         Note:
@@ -693,7 +751,9 @@ class OpenAIVecDataFrameAccessor:
         if missing_rows.empty:
             return self._obj
 
-        filled_values: List[FillNaResponse] = missing_rows.ai.task(task=task, batch_size=batch_size)
+        filled_values: List[FillNaResponse] = missing_rows.ai.task(
+            task=task, batch_size=batch_size, show_progress=show_progress, **api_kwargs
+        )
 
         # get deep copy of the DataFrame to avoid modifying the original
         df = self._obj.copy()
@@ -754,6 +814,7 @@ class AsyncOpenAIVecSeriesAccessor:
         response_format: Type[ResponseFormat] = str,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
+        **api_kwargs,
     ) -> pd.Series:
         """Call an LLM once for every Series element using a provided cache (asynchronously).
 
@@ -769,24 +830,24 @@ class AsyncOpenAIVecSeriesAccessor:
                 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``.
+            temperature (float | None, optional): Sampling temperature. ``None`` omits the
+                parameter (recommended for reasoning models). Defaults to ``0.0``.
             top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
+            **api_kwargs: Additional keyword arguments forwarded verbatim to
+                ``AsyncOpenAI.responses.parse`` (e.g. ``max_output_tokens``, penalties,
+                future parameters). Core batching keys (model, instructions, input,
+                text_format) are protected and silently ignored if provided.
 
         Returns:
             pandas.Series: Series whose values are instances of ``response_format``.
 
         Example:
             ```python
-            from openaivec._proxy import AsyncBatchingMapProxy
-
-            # Create a shared cache with custom batch size and concurrency
-            shared_cache = AsyncBatchingMapProxy(batch_size=64, max_concurrency=4)
-
-            animals = pd.Series(["cat", "dog", "elephant"])
-            # Must be awaited
-            result = await animals.aio.responses_with_cache(
-                "translate to French",
-                cache=shared_cache
+            result = await series.aio.responses_with_cache(
+                "classify",
+                cache=shared,
+                max_output_tokens=256,
+                frequency_penalty=0.2,
             )
             ```
 
@@ -802,9 +863,7 @@ class AsyncOpenAIVecSeriesAccessor:
             temperature=temperature,
             top_p=top_p,
         )
-        # Await the async operation
-        results = await client.parse(self._obj.tolist())
-
+        results = await client.parse(self._obj.tolist(), **api_kwargs)
         return pd.Series(results, index=self._obj.index, name=self._obj.name)
 
     async def embeddings_with_cache(
@@ -864,6 +923,7 @@ class AsyncOpenAIVecSeriesAccessor:
         self,
         task: PreparedTask[ResponseFormat],
         cache: AsyncBatchingMapProxy[str, ResponseFormat],
+        **api_kwargs,
     ) -> pd.Series:
         """Execute a prepared task on every Series element using a provided cache (asynchronously).
 
@@ -879,6 +939,12 @@ class AsyncOpenAIVecSeriesAccessor:
                 instance for managing API call batching and deduplication.
                 Set cache.batch_size=None to enable automatic batch size optimization.
 
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client. Core batching / routing
+            keys (``model``, ``instructions`` / system message, user ``input``) are managed by the
+            library and cannot be overridden.
+
         Returns:
             pandas.Series: Series whose values are instances of the task's
                 response format, aligned with the original Series index.
@@ -911,9 +977,8 @@ class AsyncOpenAIVecSeriesAccessor:
             temperature=task.temperature,
             top_p=task.top_p,
         )
-
         # Await the async operation
-        results = await client.parse(self._obj.tolist())
+        results = await client.parse(self._obj.tolist(), **api_kwargs)
 
         return pd.Series(results, index=self._obj.index, name=self._obj.name)
 
@@ -926,6 +991,7 @@ class AsyncOpenAIVecSeriesAccessor:
         top_p: float = 1.0,
         max_concurrency: int = 8,
         show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Call an LLM once for every Series element (asynchronously).
 
@@ -944,10 +1010,6 @@ class AsyncOpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series of strings, each containing the
-            assistant's response to the corresponding input.
-            The model used is set by the `responses_model` function.
-            The default model is `gpt-4.1-mini`.
 
         Args:
             instructions (str): System prompt prepended to every user message.
@@ -976,6 +1038,7 @@ class AsyncOpenAIVecSeriesAccessor:
             response_format=response_format,
             temperature=temperature,
             top_p=top_p,
+            **api_kwargs,
         )
 
     async def embeddings(
@@ -997,10 +1060,6 @@ class AsyncOpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series of numpy arrays, each containing the
-            embedding vector for the corresponding input.
-            The embedding model is set by the `embeddings_model` function.
-            The default embedding model is `text-embedding-3-small`.
 
         Args:
             batch_size (int | None, optional): Number of inputs grouped into a
@@ -1024,14 +1083,15 @@ class AsyncOpenAIVecSeriesAccessor:
         )
 
     async def task(
-        self, task: PreparedTask, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
+        self,
+        task: PreparedTask,
+        batch_size: int | None = None,
+        max_concurrency: int = 8,
+        show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Execute a prepared task on every Series element (asynchronously).
 
-        This method applies a pre-configured task to each element in the Series,
-        using the task's instructions and response format to generate structured
-        responses from the language model.
-
         Example:
             ```python
             from openaivec._model import PreparedTask
@@ -1052,8 +1112,6 @@ class AsyncOpenAIVecSeriesAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series containing the task results for each
-            corresponding input element, following the task's defined structure.
 
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
@@ -1065,6 +1123,12 @@ class AsyncOpenAIVecSeriesAccessor:
                 requests. Defaults to 8.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
 
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client. Core batching / routing
+            keys (``model``, ``instructions`` / system message, user ``input``) are managed by the
+            library and cannot be overridden.
+
         Returns:
             pandas.Series: Series whose values are instances of the task's
                 response format, aligned with the original Series index.
@@ -1077,6 +1141,7 @@ class AsyncOpenAIVecSeriesAccessor:
             cache=AsyncBatchingMapProxy(
                 batch_size=batch_size, max_concurrency=max_concurrency, show_progress=show_progress
             ),
+            **api_kwargs,
         )
 
 
@@ -1094,6 +1159,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         response_format: Type[ResponseFormat] = str,
         temperature: float | None = 0.0,
         top_p: float = 1.0,
+        **api_kwargs,
     ) -> pd.Series:
         """Generate a response for each row after serialising it to JSON using a provided cache (asynchronously).
 
@@ -1137,20 +1203,14 @@ class AsyncOpenAIVecDataFrameAccessor:
         Note:
             This is an asynchronous method and must be awaited.
         """
-        series_of_json = self._obj.pipe(
-            lambda df: (
-                pd.Series(df.to_dict(orient="records"), index=df.index, name="record").map(
-                    lambda x: json.dumps(x, ensure_ascii=False)
-                )
-            )
-        )
         # Await the call to the async Series method using .aio
-        return await series_of_json.aio.responses_with_cache(
+        return await _df_rows_to_json_series(self._obj).aio.responses_with_cache(
             instructions=instructions,
             cache=cache,
             response_format=response_format,
             temperature=temperature,
             top_p=top_p,
+            **api_kwargs,
         )
 
     async def responses(
@@ -1162,33 +1222,29 @@ class AsyncOpenAIVecDataFrameAccessor:
         top_p: float = 1.0,
         max_concurrency: int = 8,
         show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Generate a response for each row after serialising it to JSON (asynchronously).
 
         Example:
             ```python
             df = pd.DataFrame([
-                {\"name\": \"cat\", \"legs\": 4},
-                {\"name\": \"dog\", \"legs\": 4},
-                {\"name\": \"elephant\", \"legs\": 4},
+                {"name": "cat", "legs": 4},
+                {"name": "dog", "legs": 4},
+                {"name": "elephant", "legs": 4},
             ])
             # Must be awaited
-            results = await df.aio.responses(\"what is the animal\'s name?\")
+            results = await df.aio.responses("what is the animal's name?")
 
             # With progress bar for large datasets
-            large_df = pd.DataFrame({\"id\": list(range(1000))})
+            large_df = pd.DataFrame({"id": list(range(1000))})
             results = await large_df.aio.responses(
-                \"generate a name for this ID\",
+                "generate a name for this ID",
                 batch_size=20,
                 max_concurrency=4,
                 show_progress=True
             )
             ```
-            This method returns a Series of strings, each containing the
-            assistant's response to the corresponding input.
-            Each row is serialised to JSON before being sent to the assistant.
-            The model used is set by the `responses_model` function.
-            The default model is `gpt-4.1-mini`.
 
         Args:
             instructions (str): System prompt for the assistant.
@@ -1217,18 +1273,19 @@ class AsyncOpenAIVecDataFrameAccessor:
             response_format=response_format,
             temperature=temperature,
             top_p=top_p,
+            **api_kwargs,
         )
 
     async def task(
-        self, task: PreparedTask, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
+        self,
+        task: PreparedTask,
+        batch_size: int | None = None,
+        max_concurrency: int = 8,
+        show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.Series:
         """Execute a prepared task on each DataFrame row after serialising it to JSON (asynchronously).
 
-        This method applies a pre-configured task to each row in the DataFrame,
-        using the task's instructions and response format to generate structured
-        responses from the language model. Each row is serialised to JSON before
-        being processed by the task.
-
         Example:
             ```python
             from openaivec._model import PreparedTask
@@ -1253,8 +1310,6 @@ class AsyncOpenAIVecDataFrameAccessor:
                 show_progress=True
             )
             ```
-            This method returns a Series containing the task results for each
-            corresponding row, following the task's defined structure.
 
         Args:
             task (PreparedTask): A pre-configured task containing instructions,
@@ -1266,6 +1321,12 @@ class AsyncOpenAIVecDataFrameAccessor:
                 requests. Defaults to 8.
             show_progress (bool, optional): Show progress bar in Jupyter notebooks. Defaults to ``False``.
 
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client. Core batching / routing
+            keys (``model``, ``instructions`` / system message, user ``input``) are managed by the
+            library and cannot be overridden.
+
         Returns:
             pandas.Series: Series whose values are instances of the task's
                 response format, aligned with the DataFrame's original index.
@@ -1273,19 +1334,40 @@ class AsyncOpenAIVecDataFrameAccessor:
         Note:
             This is an asynchronous method and must be awaited.
         """
-        series_of_json = self._obj.pipe(
-            lambda df: (
-                pd.Series(df.to_dict(orient="records"), index=df.index, name="record").map(
-                    lambda x: json.dumps(x, ensure_ascii=False)
-                )
-            )
-        )
         # Await the call to the async Series method using .aio
-        return await series_of_json.aio.task(
+        return await _df_rows_to_json_series(self._obj).aio.task(
             task=task,
             batch_size=batch_size,
             max_concurrency=max_concurrency,
             show_progress=show_progress,
+            **api_kwargs,
+        )
+
+    async def task_with_cache(
+        self,
+        task: PreparedTask[ResponseFormat],
+        cache: AsyncBatchingMapProxy[str, ResponseFormat],
+        **api_kwargs,
+    ) -> pd.Series:
+        """Execute a prepared task on each DataFrame row after serializing it to JSON using a provided cache (async).
+
+        Args:
+            task (PreparedTask): Prepared task (instructions + response_format + sampling params).
+            cache (AsyncBatchingMapProxy[str, ResponseFormat]): Pre‑configured async cache instance.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters forwarded verbatim. Core routing keys are protected.
+
+        Returns:
+            pandas.Series: Task results aligned with the DataFrame's original index.
+
+        Note:
+            This is an asynchronous method and must be awaited.
+        """
+        return await _df_rows_to_json_series(self._obj).aio.task_with_cache(
+            task=task,
+            cache=cache,
+            **api_kwargs,
         )
 
     async def pipe(self, func: Callable[[pd.DataFrame], Awaitable[T] | T]) -> T:
@@ -1371,7 +1453,13 @@ class AsyncOpenAIVecDataFrameAccessor:
         return df_current
 
     async def fillna(
-        self, target_column_name: str, max_examples: int = 500, batch_size: int | None = None, max_concurrency: int = 8
+        self,
+        target_column_name: str,
+        max_examples: int = 500,
+        batch_size: int | None = None,
+        max_concurrency: int = 8,
+        show_progress: bool = False,
+        **api_kwargs,
     ) -> pd.DataFrame:
         """Fill missing values in a DataFrame column using AI-powered inference (asynchronously).
 
@@ -1391,6 +1479,11 @@ class AsyncOpenAIVecDataFrameAccessor:
                 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``.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying task execution.
 
         Returns:
             pandas.DataFrame: A new DataFrame with missing values filled in the target
@@ -1406,6 +1499,15 @@ class AsyncOpenAIVecDataFrameAccessor:
 
             # Fill missing values in the 'name' column (must be awaited)
             filled_df = await df.aio.fillna('name')
+
+            # With progress bar for large datasets
+            large_df = pd.DataFrame({'name': [None] * 1000, 'age': list(range(1000))})
+            filled_df = await large_df.aio.fillna(
+                'name',
+                batch_size=32,
+                max_concurrency=4,
+                show_progress=True
+            )
             ```
 
         Note:
@@ -1420,7 +1522,7 @@ class AsyncOpenAIVecDataFrameAccessor:
             return self._obj
 
         filled_values: List[FillNaResponse] = await missing_rows.aio.task(
-            task=task, batch_size=batch_size, max_concurrency=max_concurrency
+            task=task, batch_size=batch_size, max_concurrency=max_concurrency, show_progress=show_progress, **api_kwargs
         )
 
         # get deep copy of the DataFrame to avoid modifying the original