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

openaivec/_proxy.py

@@ -460,7 +460,20 @@ class BatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
         self.__process_owned(owned, map_func)
         self.__wait_for(wait_for, map_func)
 
-        return self.__values(items)
+        # Fetch results before purging None entries
+        results = self.__values(items)
+
+        # Remove None values from cache so they are recomputed on future calls
+        with self._lock:
+            if self._cache:  # micro-optimization
+                for k in set(items):
+                    try:
+                        if self._cache.get(k, object()) is None:
+                            del self._cache[k]
+                    except KeyError:
+                        pass
+
+        return results
 
 
 @dataclass
@@ -745,4 +758,13 @@ class AsyncBatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
         await self.__process_owned(owned, map_func)
         await self.__wait_for(wait_for, map_func)
 
-        return await self.__values(items)
+        results = await self.__values(items)
+
+        # Remove None values from cache after retrieval to avoid persisting incomplete results
+        async with self._lock:
+            if self._cache:
+                for k in set(items):
+                    if self._cache.get(k, object()) is None:
+                        self._cache.pop(k, None)
+
+        return results

openaivec/_schema.py

@@ -128,6 +128,12 @@ class InferredSchema(BaseModel):
             redundancy removed).
         examples_summary: Neutral description of structural / semantic patterns
             observed in the examples (domain, recurring signals, constraints).
+        examples_purpose_alignment: Analytical explanation of how the concrete
+            recurring patterns in the provided examples *justify*, *constrain*,
+            or *refine* the stated purpose. Should map purpose facets to
+            observed evidence (or explicitly note gaps) to discourage
+            hallucinated fields and anchor extraction scope. This is an
+            internal quality aid – downstream consumers typically ignore it.
         fields: Ordered list of ``FieldSpec`` objects comprising the schema's
             sole authoritative contract.
         inference_prompt: Self-contained extraction instructions enforcing an
@@ -147,6 +153,13 @@ class InferredSchema(BaseModel):
             "patterns, and notable constraints."
         )
     )
+    examples_purpose_alignment: str = Field(
+        description=(
+            "Explanation of how observable recurring patterns in the examples substantiate and bound the stated "
+            "purpose. Should reference purpose facets and cite supporting example evidence (or note any gaps) to "
+            "reduce hallucinated fields. Internal diagnostic / quality aid; not required for downstream extraction."
+        )
+    )
     fields: List[FieldSpec] = Field(
         description=(
             "Ordered list of proposed fields derived strictly from observable, repeatable signals in the "
@@ -234,7 +247,7 @@ class InferredSchema(BaseModel):
                 py_type = enum_cls
             else:
                 py_type = type_map[spec.type]
-            fields[spec.name] = (py_type, ...)
+            fields[spec.name] = (py_type, Field(description=spec.description))
 
         model = create_model("InferredSchema", **fields)  # type: ignore[call-arg]
         return model
@@ -281,11 +294,15 @@ You are a schema inference engine.
 Task:
 1. Normalize the user's purpose (eliminate ambiguity, redundancy, contradictions).
 2. Objectively summarize observable patterns in the example texts.
-3. Propose a minimal flat set of scalar fields (no nesting / arrays) that are reliably extractable.
-4. Skip fields likely missing in a large share (>~20%) of realistic inputs.
-5. Provide enum_values ONLY when a small stable closed categorical set (2–24 lowercase tokens)
+3. Produce an "examples_purpose_alignment" explanation that explicitly maps purpose facets
+   to concrete recurring evidence in the examples (or flags gaps). Use concise bullet‑style
+   sentences (still a plain string) such as: "purpose facet -> supporting pattern / gap".
+   This MUST NOT introduce new domain facts beyond the examples & purpose.
+4. Propose a minimal flat set of scalar fields (no nesting / arrays) that are reliably extractable.
+5. Skip fields likely missing in a large share (>~20%) of realistic inputs.
+6. Provide enum_values ONLY when a small stable closed categorical set (2–24 lowercase tokens)
     is clearly evidenced; never invent.
-6. If the purpose indicates prediction (predict / probability / likelihood), output only
+7. If the purpose indicates prediction (predict / probability / likelihood), output only
     explanatory features (no target restatement).
 
 Rules:
@@ -305,6 +322,7 @@ Output contract:
 Return exactly an InferredSchema object with JSON keys:
     - purpose (string)
     - examples_summary (string)
+    - examples_purpose_alignment (string)
     - fields (array of FieldSpec objects: name, type, description, enum_values?)
     - inference_prompt (string)
 """.strip()
@@ -359,10 +377,31 @@ class SchemaInferer:
             raise ValueError("max_retries must be >= 1")
 
         last_err: Exception | None = None
+        previous_errors: list[str] = []
         for attempt in range(max_retries):
+            if attempt == 0:
+                instructions = _INFER_INSTRUCTIONS
+            else:
+                # Provide structured feedback for correction. Keep concise and prohibit speculative expansion.
+                feedback_lines = [
+                    "--- PRIOR VALIDATION FEEDBACK ---",
+                ]
+                for i, err in enumerate(previous_errors[-5:], 1):  # include last up to 5 errors
+                    feedback_lines.append(f"{i}. {err}")
+                feedback_lines.extend(
+                    [
+                        "Adjust ONLY listed issues; avoid adding brand-new fields unless essential.",
+                        "Don't hallucinate or broaden enum_values unless enum rule caused failure.",
+                        "Duplicate names: minimally rename; keep semantics.",
+                        "Unsupported type: change to string|integer|float|boolean (no new facts).",
+                        "Bad enum length: drop enum or constrain to 2–24 evidenced tokens.",
+                    ]
+                )
+                instructions = _INFER_INSTRUCTIONS + "\n\n" + "\n".join(feedback_lines)
+
             response: ParsedResponse[InferredSchema] = self.client.responses.parse(
                 model=self.model_name,
-                instructions=_INFER_INSTRUCTIONS,
+                instructions=instructions,
                 input=data.model_dump_json(),
                 text_format=InferredSchema,
                 *args,
@@ -371,8 +410,10 @@ class SchemaInferer:
             parsed = response.output_parsed
             try:
                 _basic_field_list_validation(parsed)
+                parsed.build_model()  # ensure dynamic model creation succeeds
             except ValueError as e:
                 last_err = e
+                previous_errors.append(str(e))
                 if attempt == max_retries - 1:
                     raise
                 continue

openaivec/pandas_ext.py

@@ -182,6 +182,27 @@ class OpenAIVecSeriesAccessor:
         top_p: float = 1.0,
         **api_kwargs,
     ) -> pd.Series:
+        """Call an LLM once for every Series element using a provided cache.
+
+        This is a lower-level method that allows explicit cache management for advanced
+        use cases. Most users should use the standard ``responses`` method instead.
+
+        Args:
+            instructions (str): System prompt prepended to every user message.
+            cache (BatchingMapProxy[str, ResponseFormat]): Explicit cache instance for
+                batching and deduplication control.
+            response_format (Type[ResponseFormat], optional): Pydantic model or built-in
+                type the assistant should return. Defaults to ``str``.
+            temperature (float | None, optional): Sampling temperature. Defaults to ``0.0``.
+            top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
+
+        Additional Keyword Args:
+            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
+            ``seed``, etc.) are forwarded verbatim to the underlying client.
+
+        Returns:
+            pandas.Series: Series whose values are instances of ``response_format``.
+        """
         client: BatchResponses = BatchResponses(
             client=CONTAINER.resolve(OpenAI),
             model_name=CONTAINER.resolve(ResponsesModelName).value,
@@ -195,6 +216,56 @@ class OpenAIVecSeriesAccessor:
         # 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 responses(
+        self,
+        instructions: str,
+        response_format: Type[ResponseFormat] = str,
+        batch_size: int | None = None,
+        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.
+
+        Example:
+            ```python
+            animals = pd.Series(["cat", "dog", "elephant"])
+            # Basic usage
+            animals.ai.responses("translate to French")
+
+            # With progress bar in Jupyter notebooks
+            large_series = pd.Series(["data"] * 1000)
+            large_series.ai.responses(
+                "analyze this data",
+                batch_size=32,
+                show_progress=True
+            )
+            ```
+
+        Args:
+            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 | 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 | None, 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``.
+
+        Returns:
+            pandas.Series: Series whose values are instances of ``response_format``.
+        """
+        return self.responses_with_cache(
+            instructions=instructions,
+            cache=BatchingMapProxy(batch_size=batch_size, show_progress=show_progress),
+            response_format=response_format,
+            temperature=temperature,
+            top_p=top_p,
+            **api_kwargs,
+        )
+
     def embeddings_with_cache(
         self,
         cache: BatchingMapProxy[str, np.ndarray],
@@ -205,15 +276,6 @@ class OpenAIVecSeriesAccessor:
         a pre-configured BatchingMapProxy instance, enabling cache sharing
         across multiple operations or custom batch size management.
 
-        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
-                (dtype ``float32``).
-
         Example:
             ```python
             from openaivec._proxy import BatchingMapProxy
@@ -225,6 +287,15 @@ class OpenAIVecSeriesAccessor:
             animals = pd.Series(["cat", "dog", "elephant"])
             embeddings = animals.ai.embeddings_with_cache(cache=shared_cache)
             ```
+
+        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
+                (dtype ``float32``).
         """
         client: BatchEmbeddings = BatchEmbeddings(
             client=CONTAINER.resolve(OpenAI),
@@ -238,54 +309,35 @@ class OpenAIVecSeriesAccessor:
             name=self._obj.name,
         )
 
-    def responses(
-        self,
-        instructions: str,
-        response_format: Type[ResponseFormat] = str,
-        batch_size: int | None = None,
-        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.
+    def embeddings(self, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
+        """Compute OpenAI embeddings for every Series element.
 
         Example:
             ```python
             animals = pd.Series(["cat", "dog", "elephant"])
             # Basic usage
-            animals.ai.responses("translate to French")
+            animals.ai.embeddings()
 
-            # With progress bar in Jupyter notebooks
-            large_series = pd.Series(["data"] * 1000)
-            large_series.ai.responses(
-                "analyze this data",
-                batch_size=32,
+            # With progress bar for large datasets
+            large_texts = pd.Series(["text"] * 5000)
+            embeddings = large_texts.ai.embeddings(
+                batch_size=100,
                 show_progress=True
             )
             ```
 
         Args:
-            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 | None, optional): Number of prompts grouped into a single
-                request. Defaults to ``None`` (automatic batch size optimization
+            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.
-            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``.
 
         Returns:
-            pandas.Series: Series whose values are instances of ``response_format``.
+            pandas.Series: Series whose values are ``np.ndarray`` objects
+                (dtype ``float32``).
         """
-        return self.responses_with_cache(
-            instructions=instructions,
+        return self.embeddings_with_cache(
             cache=BatchingMapProxy(batch_size=batch_size, show_progress=show_progress),
-            response_format=response_format,
-            temperature=temperature,
-            top_p=top_p,
-            **api_kwargs,
         )
 
     def task_with_cache(
@@ -300,6 +352,13 @@ class OpenAIVecSeriesAccessor:
         response format, temperature and top_p. A supplied ``BatchingMapProxy`` enables
         cross‑operation deduplicated reuse and external batch size / progress control.
 
+        Example:
+            ```python
+            from openaivec._proxy import BatchingMapProxy
+            shared_cache = BatchingMapProxy(batch_size=64)
+            reviews.ai.task_with_cache(sentiment_task, cache=shared_cache)
+            ```
+
         Args:
             task (PreparedTask): Prepared task (instructions + response_format + sampling params).
             cache (BatchingMapProxy[str, ResponseFormat]): Pre‑configured cache instance.
@@ -311,13 +370,6 @@ class OpenAIVecSeriesAccessor:
 
         Returns:
             pandas.Series: Task results aligned with the original Series index.
-
-        Example:
-            ```python
-            from openaivec._proxy import BatchingMapProxy
-            shared_cache = BatchingMapProxy(batch_size=64)
-            reviews.ai.task_with_cache(sentiment_task, cache=shared_cache)
-            ```
         """
         client: BatchResponses = BatchResponses(
             client=CONTAINER.resolve(OpenAI),
@@ -382,37 +434,6 @@ class OpenAIVecSeriesAccessor:
             **api_kwargs,
         )
 
-    def embeddings(self, batch_size: int | None = None, show_progress: bool = False) -> pd.Series:
-        """Compute OpenAI embeddings for every Series element.
-
-        Example:
-            ```python
-            animals = pd.Series(["cat", "dog", "elephant"])
-            # Basic usage
-            animals.ai.embeddings()
-
-            # With progress bar for large datasets
-            large_texts = pd.Series(["text"] * 5000)
-            embeddings = large_texts.ai.embeddings(
-                batch_size=100,
-                show_progress=True
-            )
-            ```
-
-        Args:
-            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:
-            pandas.Series: Series whose values are ``np.ndarray`` objects
-                (dtype ``float32``).
-        """
-        return self.embeddings_with_cache(
-            cache=BatchingMapProxy(batch_size=batch_size, show_progress=show_progress),
-        )
-
     def count_tokens(self) -> pd.Series:
         """Count `tiktoken` tokens per row.
 
@@ -467,38 +488,6 @@ class OpenAIVecDataFrameAccessor:
     def __init__(self, df_obj: pd.DataFrame):
         self._obj = df_obj
 
-    def extract(self, column: str) -> pd.DataFrame:
-        """Flatten one column of Pydantic models/dicts into top‑level columns.
-
-        Example:
-            ```python
-            df = pd.DataFrame([
-                {"animal": {"name": "cat", "legs": 4}},
-                {"animal": {"name": "dog", "legs": 4}},
-                {"animal": {"name": "elephant", "legs": 4}},
-            ])
-            df.ai.extract("animal")
-            ```
-            This method returns a DataFrame with the same index as the original,
-            where each column corresponds to a key in the dictionaries.
-            The source column is dropped.
-
-        Args:
-            column (str): Column to expand.
-
-        Returns:
-            pandas.DataFrame: Original DataFrame with the extracted columns; the source column is dropped.
-        """
-        if column not in self._obj.columns:
-            raise ValueError(f"Column '{column}' does not exist in the DataFrame.")
-
-        return (
-            self._obj.pipe(lambda df: df.reset_index(drop=True))
-            .pipe(lambda df: df.join(df[column].ai.extract()))
-            .pipe(lambda df: df.set_index(self._obj.index))
-            .pipe(lambda df: df.drop(columns=[column], axis=1))
-        )
-
     def responses_with_cache(
         self,
         instructions: str,
@@ -508,25 +497,12 @@ class OpenAIVecDataFrameAccessor:
         top_p: float = 1.0,
         **api_kwargs,
     ) -> pd.Series:
-        """Generate a response for each row after serialising it to JSON using a provided cache.
+        """Generate a response for each row after serializing it to JSON 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.
 
-        Args:
-            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``.
-            top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
-
-        Returns:
-            pandas.Series: Responses aligned with the DataFrame's original index.
-
         Example:
             ```python
             from openaivec._proxy import BatchingMapProxy
@@ -544,6 +520,19 @@ class OpenAIVecDataFrameAccessor:
                 cache=shared_cache
             )
             ```
+
+        Args:
+            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 | None, optional): Sampling temperature. Defaults to ``0.0``.
+            top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
+
+        Returns:
+            pandas.Series: Responses aligned with the DataFrame's original index.
         """
         return _df_rows_to_json_series(self._obj).ai.responses_with_cache(
             instructions=instructions,
@@ -564,7 +553,7 @@ class OpenAIVecDataFrameAccessor:
         show_progress: bool = False,
         **api_kwargs,
     ) -> pd.Series:
-        """Generate a response for each row after serialising it to JSON.
+        """Generate a response for each row after serializing it to JSON.
 
         Example:
             ```python
@@ -592,7 +581,7 @@ class OpenAIVecDataFrameAccessor:
             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``.
+            temperature (float | None, 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``.
 
@@ -608,6 +597,31 @@ class OpenAIVecDataFrameAccessor:
             **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 task(
         self,
         task: PreparedTask,
@@ -615,7 +629,7 @@ class OpenAIVecDataFrameAccessor:
         show_progress: bool = False,
         **api_kwargs,
     ) -> pd.Series:
-        """Execute a prepared task on each DataFrame row after serialising it to JSON.
+        """Execute a prepared task on each DataFrame row after serializing it to JSON.
 
         Example:
             ```python
@@ -666,29 +680,36 @@ class OpenAIVecDataFrameAccessor:
             **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.
+    def extract(self, column: str) -> pd.DataFrame:
+        """Flatten one column of Pydantic models/dicts into top‑level columns.
 
-        Args:
-            task (PreparedTask): Prepared task (instructions + response_format + sampling params).
-            cache (BatchingMapProxy[str, ResponseFormat]): Pre‑configured cache instance.
+        Example:
+            ```python
+            df = pd.DataFrame([
+                {"animal": {"name": "cat", "legs": 4}},
+                {"animal": {"name": "dog", "legs": 4}},
+                {"animal": {"name": "elephant", "legs": 4}},
+            ])
+            df.ai.extract("animal")
+            ```
+            This method returns a DataFrame with the same index as the original,
+            where each column corresponds to a key in the dictionaries.
+            The source column is dropped.
 
-        Additional Keyword Args:
-            Arbitrary OpenAI Responses API parameters (e.g. ``frequency_penalty``, ``presence_penalty``,
-            ``seed``) forwarded verbatim. Core routing keys are managed internally.
+        Args:
+            column (str): Column to expand.
 
         Returns:
-            pandas.Series: Task results aligned with the DataFrame's original index.
+            pandas.DataFrame: Original DataFrame with the extracted columns; the source column is dropped.
         """
-        return _df_rows_to_json_series(self._obj).ai.task_with_cache(
-            task=task,
-            cache=cache,
-            **api_kwargs,
+        if column not in self._obj.columns:
+            raise ValueError(f"Column '{column}' does not exist in the DataFrame.")
+
+        return (
+            self._obj.pipe(lambda df: df.reset_index(drop=True))
+            .pipe(lambda df: df.join(df[column].ai.extract()))
+            .pipe(lambda df: df.set_index(self._obj.index))
+            .pipe(lambda df: df.drop(columns=[column], axis=1))
         )
 
     def fillna(
@@ -776,15 +797,6 @@ class OpenAIVecDataFrameAccessor:
         two columns of the DataFrame. The vectors should be numpy arrays or
         array-like objects that support dot product operations.
 
-        Args:
-            col1 (str): Name of the first column containing embedding vectors.
-            col2 (str): Name of the second column containing embedding vectors.
-
-        Returns:
-            pandas.Series: Series containing cosine similarity scores between
-                corresponding vectors in col1 and col2, with values ranging
-                from -1 to 1, where 1 indicates identical direction.
-
         Example:
             ```python
             df = pd.DataFrame({
@@ -793,6 +805,15 @@ class OpenAIVecDataFrameAccessor:
             })
             similarities = df.ai.similarity('vec1', 'vec2')
             ```
+
+        Args:
+            col1 (str): Name of the first column containing embedding vectors.
+            col2 (str): Name of the second column containing embedding vectors.
+
+        Returns:
+            pandas.Series: Series containing cosine similarity scores between
+                corresponding vectors in col1 and col2, with values ranging
+                from -1 to 1, where 1 indicates identical direction.
         """
         return self._obj.apply(
             lambda row: np.dot(row[col1], row[col2]) / (np.linalg.norm(row[col1]) * np.linalg.norm(row[col2])),
@@ -823,163 +844,47 @@ class AsyncOpenAIVecSeriesAccessor:
         across multiple operations or custom batch size management. The concurrency
         is controlled by the cache instance itself.
 
-        Args:
-            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 | 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
             result = await series.aio.responses_with_cache(
                 "classify",
-                cache=shared,
-                max_output_tokens=256,
-                frequency_penalty=0.2,
-            )
-            ```
-
-        Note:
-            This is an asynchronous method and must be awaited.
-        """
-        client: AsyncBatchResponses = AsyncBatchResponses(
-            client=CONTAINER.resolve(AsyncOpenAI),
-            model_name=CONTAINER.resolve(ResponsesModelName).value,
-            system_message=instructions,
-            response_format=response_format,
-            cache=cache,
-            temperature=temperature,
-            top_p=top_p,
-        )
-        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(
-        self,
-        cache: AsyncBatchingMapProxy[str, np.ndarray],
-    ) -> pd.Series:
-        """Compute OpenAI embeddings for every Series element using a provided cache (asynchronously).
-
-        This method allows external control over caching behavior by accepting
-        a pre-configured AsyncBatchingMapProxy instance, enabling cache sharing
-        across multiple operations or custom batch size management. The concurrency
-        is controlled by the cache instance itself.
-
-        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
-                (dtype ``float32``).
-
-        Example:
-            ```python
-            from openaivec._proxy import AsyncBatchingMapProxy
-            import numpy as np
-
-            # Create a shared cache with custom batch size and concurrency
-            shared_cache = AsyncBatchingMapProxy[str, np.ndarray](
-                batch_size=64, max_concurrency=4
-            )
-
-            animals = pd.Series(["cat", "dog", "elephant"])
-            # Must be awaited
-            embeddings = await animals.aio.embeddings_with_cache(cache=shared_cache)
-            ```
-
-        Note:
-            This is an asynchronous method and must be awaited.
-        """
-        client: AsyncBatchEmbeddings = AsyncBatchEmbeddings(
-            client=CONTAINER.resolve(AsyncOpenAI),
-            model_name=CONTAINER.resolve(EmbeddingsModelName).value,
-            cache=cache,
-        )
-
-        # Await the async operation
-        results = await client.create(self._obj.tolist())
-
-        return pd.Series(
-            results,
-            index=self._obj.index,
-            name=self._obj.name,
-        )
-
-    async def task_with_cache(
-        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).
-
-        This method allows external control over caching behavior by accepting
-        a pre-configured AsyncBatchingMapProxy instance, enabling cache sharing
-        across multiple operations or custom batch size management. The concurrency
-        is controlled by the cache instance itself.
+                cache=shared,
+                max_output_tokens=256,
+                frequency_penalty=0.2,
+            )
+            ```
 
         Args:
-            task (PreparedTask): A pre-configured task containing instructions,
-                response format, and other parameters for processing the inputs.
+            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.
-
-        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.
+            response_format (Type[ResponseFormat], optional): Pydantic model or built‑in
+                type the assistant should return. Defaults to ``str``.
+            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 the task's
-                response format, aligned with the original Series index.
-
-        Example:
-            ```python
-            from openaivec._model import PreparedTask
-            from openaivec._proxy import AsyncBatchingMapProxy
-
-            # Create a shared cache with custom batch size and concurrency
-            shared_cache = AsyncBatchingMapProxy(batch_size=64, max_concurrency=4)
-
-            # Assume you have a prepared task for sentiment analysis
-            sentiment_task = PreparedTask(...)
-
-            reviews = pd.Series(["Great product!", "Not satisfied", "Amazing quality"])
-            # Must be awaited
-            results = await reviews.aio.task_with_cache(sentiment_task, cache=shared_cache)
-            ```
+            pandas.Series: Series whose values are instances of ``response_format``.
 
         Note:
             This is an asynchronous method and must be awaited.
         """
-        client = AsyncBatchResponses(
+        client: AsyncBatchResponses = AsyncBatchResponses(
             client=CONTAINER.resolve(AsyncOpenAI),
             model_name=CONTAINER.resolve(ResponsesModelName).value,
-            system_message=task.instructions,
-            response_format=task.response_format,
+            system_message=instructions,
+            response_format=response_format,
             cache=cache,
-            temperature=task.temperature,
-            top_p=task.top_p,
+            temperature=temperature,
+            top_p=top_p,
         )
-        # Await the async operation
         results = await client.parse(self._obj.tolist(), **api_kwargs)
-
         return pd.Series(results, index=self._obj.index, name=self._obj.name)
 
     async def responses(
@@ -1018,7 +923,7 @@ class AsyncOpenAIVecSeriesAccessor:
             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``.
+            temperature (float | None, 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
                 requests. Defaults to ``8``.
@@ -1041,6 +946,59 @@ class AsyncOpenAIVecSeriesAccessor:
             **api_kwargs,
         )
 
+    async def embeddings_with_cache(
+        self,
+        cache: AsyncBatchingMapProxy[str, np.ndarray],
+    ) -> pd.Series:
+        """Compute OpenAI embeddings for every Series element using a provided cache (asynchronously).
+
+        This method allows external control over caching behavior by accepting
+        a pre-configured AsyncBatchingMapProxy instance, enabling cache sharing
+        across multiple operations or custom batch size management. The concurrency
+        is controlled by the cache instance itself.
+
+        Example:
+            ```python
+            from openaivec._proxy import AsyncBatchingMapProxy
+            import numpy as np
+
+            # Create a shared cache with custom batch size and concurrency
+            shared_cache = AsyncBatchingMapProxy[str, np.ndarray](
+                batch_size=64, max_concurrency=4
+            )
+
+            animals = pd.Series(["cat", "dog", "elephant"])
+            # Must be awaited
+            embeddings = await animals.aio.embeddings_with_cache(cache=shared_cache)
+            ```
+
+        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
+                (dtype ``float32``).
+
+        Note:
+            This is an asynchronous method and must be awaited.
+        """
+        client: AsyncBatchEmbeddings = AsyncBatchEmbeddings(
+            client=CONTAINER.resolve(AsyncOpenAI),
+            model_name=CONTAINER.resolve(EmbeddingsModelName).value,
+            cache=cache,
+        )
+
+        # Await the async operation
+        results = await client.create(self._obj.tolist())
+
+        return pd.Series(
+            results,
+            index=self._obj.index,
+            name=self._obj.name,
+        )
+
     async def embeddings(
         self, batch_size: int | None = None, max_concurrency: int = 8, show_progress: bool = False
     ) -> pd.Series:
@@ -1082,6 +1040,69 @@ class AsyncOpenAIVecSeriesAccessor:
             ),
         )
 
+    async def task_with_cache(
+        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).
+
+        This method allows external control over caching behavior by accepting
+        a pre-configured AsyncBatchingMapProxy instance, enabling cache sharing
+        across multiple operations or custom batch size management. The concurrency
+        is controlled by the cache instance itself.
+
+        Args:
+            task (PreparedTask): A pre-configured task containing instructions,
+                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.
+
+        Example:
+            ```python
+            from openaivec._model import PreparedTask
+            from openaivec._proxy import AsyncBatchingMapProxy
+
+            # Create a shared cache with custom batch size and concurrency
+            shared_cache = AsyncBatchingMapProxy(batch_size=64, max_concurrency=4)
+
+            # Assume you have a prepared task for sentiment analysis
+            sentiment_task = PreparedTask(...)
+
+            reviews = pd.Series(["Great product!", "Not satisfied", "Amazing quality"])
+            # Must be awaited
+            results = await reviews.aio.task_with_cache(sentiment_task, cache=shared_cache)
+            ```
+
+        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.
+
+        Note:
+            This is an asynchronous method and must be awaited.
+        """
+        client = AsyncBatchResponses(
+            client=CONTAINER.resolve(AsyncOpenAI),
+            model_name=CONTAINER.resolve(ResponsesModelName).value,
+            system_message=task.instructions,
+            response_format=task.response_format,
+            cache=cache,
+            temperature=task.temperature,
+            top_p=task.top_p,
+        )
+        # Await the async operation
+        results = await client.parse(self._obj.tolist(), **api_kwargs)
+
+        return pd.Series(results, index=self._obj.index, name=self._obj.name)
+
     async def task(
         self,
         task: PreparedTask,
@@ -1161,26 +1182,13 @@ class AsyncOpenAIVecDataFrameAccessor:
         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).
+        """Generate a response for each row after serializing it to JSON using a provided cache (asynchronously).
 
         This method allows external control over caching behavior by accepting
         a pre-configured AsyncBatchingMapProxy instance, enabling cache sharing
         across multiple operations or custom batch size management. The concurrency
         is controlled by the cache instance itself.
 
-        Args:
-            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``.
-            top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
-
-        Returns:
-            pandas.Series: Responses aligned with the DataFrame's original index.
-
         Example:
             ```python
             from openaivec._proxy import AsyncBatchingMapProxy
@@ -1200,6 +1208,19 @@ class AsyncOpenAIVecDataFrameAccessor:
             )
             ```
 
+        Args:
+            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 | None, optional): Sampling temperature. Defaults to ``0.0``.
+            top_p (float, optional): Nucleus sampling parameter. Defaults to ``1.0``.
+
+        Returns:
+            pandas.Series: Responses aligned with the DataFrame's original index.
+
         Note:
             This is an asynchronous method and must be awaited.
         """
@@ -1224,7 +1245,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         show_progress: bool = False,
         **api_kwargs,
     ) -> pd.Series:
-        """Generate a response for each row after serialising it to JSON (asynchronously).
+        """Generate a response for each row after serializing it to JSON (asynchronously).
 
         Example:
             ```python
@@ -1253,7 +1274,7 @@ class AsyncOpenAIVecDataFrameAccessor:
             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``.
+            temperature (float | None, 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
                 requests. Defaults to ``8``.
@@ -1276,6 +1297,35 @@ class AsyncOpenAIVecDataFrameAccessor:
             **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 using a provided cache (asynchronously).
+
+        After serializing each row to JSON, this method executes the prepared task.
+
+        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 task(
         self,
         task: PreparedTask,
@@ -1284,7 +1334,7 @@ class AsyncOpenAIVecDataFrameAccessor:
         show_progress: bool = False,
         **api_kwargs,
     ) -> pd.Series:
-        """Execute a prepared task on each DataFrame row after serialising it to JSON (asynchronously).
+        """Execute a prepared task on each DataFrame row after serializing it to JSON (asynchronously).
 
         Example:
             ```python
@@ -1343,40 +1393,24 @@ class AsyncOpenAIVecDataFrameAccessor:
             **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:
-        """
-        Apply a function to the DataFrame, supporting both synchronous and asynchronous functions.
+        """Apply a function to the DataFrame, supporting both synchronous and asynchronous functions.
 
         This method allows chaining operations on the DataFrame, similar to pandas' `pipe` method,
         but with support for asynchronous functions.
 
+        Example:
+            ```python
+            async def process_data(df):
+                # Simulate an asynchronous computation
+                await asyncio.sleep(1)
+                return df.dropna()
+
+            df = pd.DataFrame({"col": [1, 2, None, 4]})
+            # Must be awaited
+            result = await df.aio.pipe(process_data)
+            ```
+
         Args:
             func (Callable[[pd.DataFrame], Awaitable[T] | T]): A function that takes a DataFrame
                 as input and returns either a result or an awaitable result.

{openaivec-0.14.3.dist-info → openaivec-0.14.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openaivec
-Version: 0.14.3
+Version: 0.14.4
 Summary: Generative mutation for tabular calculation
 Project-URL: Homepage, https://microsoft.github.io/openaivec/
 Project-URL: Repository, https://github.com/microsoft/openaivec

{openaivec-0.14.3.dist-info → openaivec-0.14.4.dist-info}/RECORD

@@ -6,12 +6,12 @@ openaivec/_model.py,sha256=xg3s9Ljqb2xK1t_a5bwWxGJfFSIuaNrFGMgQq4nQKrM,3351
 openaivec/_optimize.py,sha256=-mKjD5YV_d1Z2nqfGfAcmx6mTKn6AODjFTrIKJPbAXQ,3851
 openaivec/_prompt.py,sha256=KoJbFK4gTEDRtu9OMweJq_jQLkSPFy2Kcvao30qKhAQ,20844
 openaivec/_provider.py,sha256=dNr9Y2C97GK-pkY81odurKoDup59dLK31V3EGT2HOwE,6711
-openaivec/_proxy.py,sha256=giOxRlCCO11XQ0gNVf2IksjZZj9RwvTHkHbmbQXadEk,28916
+openaivec/_proxy.py,sha256=J0qGDcZqSab26ScA8OXxzornfwuXtrVycqup-JPq464,29719
 openaivec/_responses.py,sha256=xtkiOn01RkauHq2FAKRAcjPglH8rmbaSz0-VE0ClTe8,24026
-openaivec/_schema.py,sha256=Q1UgCxldjeQ3YNNRF9memq5CsjKIysrD6xAN5wBHacc,17939
+openaivec/_schema.py,sha256=9enwqE2idLLUKbQxjiNn09uhdKz14kihEwUXglRqxx0,20543
 openaivec/_serialize.py,sha256=NLCKl4opc1WS24_duwpI2UGBepQ8SBh4YRxBlLwzDLw,8403
 openaivec/_util.py,sha256=dFWwjouJyvF-tqNPs2933OAt5Fw9I2Q2BvmGIfGH5k4,6423
-openaivec/pandas_ext.py,sha256=n_D2zvwNTrW2FITKm4w1Gz0dJaLQFg8QqGD5GQ1mGQs,61750
+openaivec/pandas_ext.py,sha256=m4H6mrE__Jmr5R6hl6d8yc2JhVT0-wdf5GOKWIITeLU,63366
 openaivec/spark.py,sha256=lI-noacLvuxu6gBztKdcYd9vfK3eNI3aCGwJylkzv7E,25367
 openaivec/task/__init__.py,sha256=lrgoc9UIox7XnxZ96dQRl88a-8QfuZRFBHshxctpMB8,6178
 openaivec/task/customer_support/__init__.py,sha256=KWfGyXPdZyfGdRH17x7hPpJJ1N2EP9PPhZx0fvBAwSI,884
@@ -30,7 +30,7 @@ openaivec/task/nlp/sentiment_analysis.py,sha256=BNwWtNT-MNA76eIJbb31641upukmRwM9
 openaivec/task/nlp/translation.py,sha256=XTZM11JFjbgTK9wHnxFgVDabXZ5bqbabXK_bq2nEkyQ,6627
 openaivec/task/table/__init__.py,sha256=kJz15WDJXjyC7UIHKBvlTRhCf347PCDMH5T5fONV2sU,83
 openaivec/task/table/fillna.py,sha256=ZVcOpuh7ULVhrt1VsWy5fPhk53XNaiD7kXGCPhh83M8,6636
-openaivec-0.14.3.dist-info/METADATA,sha256=0lDWogR9ysS8ysInwOahPSNZwgxQJ9Y8N6sbzVRU5KQ,27566
-openaivec-0.14.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openaivec-0.14.3.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
-openaivec-0.14.3.dist-info/RECORD,,
+openaivec-0.14.4.dist-info/METADATA,sha256=RF6rZDL5B4qYCqXIbC0jexv-IzHv48WBDV-MZtNHcvY,27566
+openaivec-0.14.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openaivec-0.14.4.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+openaivec-0.14.4.dist-info/RECORD,,