openaivec 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

openaivec/_cache/proxy.py

@@ -186,11 +186,15 @@ class BatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
     performance (targeting 30-60 seconds per batch).
 
     Example:
-        >>> p = BatchingMapProxy[int, str](batch_size=3)
-        >>> def f(xs: list[int]) -> list[str]:
-        ...     return [f"v:{x}" for x in xs]
-        >>> p.map([1, 2, 2, 3, 4], f)
-        ['v:1', 'v:2', 'v:2', 'v:3', 'v:4']
+        ```python
+        p = BatchingMapProxy[int, str](batch_size=3)
+
+        def f(xs: list[int]) -> list[str]:
+            return [f"v:{x}" for x in xs]
+
+        p.map([1, 2, 2, 3, 4], f)
+        # ['v:1', 'v:2', 'v:2', 'v:3', 'v:4']
+        ```
     """
 
     # Number of items to process per call to map_func.
@@ -449,6 +453,21 @@ class BatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
 
         Raises:
             Exception: Propagates any exception raised by ``map_func``.
+
+        Example:
+            ```python
+            proxy: BatchingMapProxy[int, str] = BatchingMapProxy(batch_size=2)
+            calls: list[list[int]] = []
+
+            def mapper(chunk: list[int]) -> list[str]:
+                calls.append(chunk)
+                return [f"v:{x}" for x in chunk]
+
+            proxy.map([1, 2, 2, 3], mapper)
+            # ['v:1', 'v:2', 'v:2', 'v:3']
+            calls  # duplicate ``2`` is only computed once
+            # [[1, 2], [3]]
+            ```
         """
         if self.__all_cached(items):
             return self.__values(items)
@@ -490,16 +509,21 @@ class AsyncBatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
     performance (targeting 30-60 seconds per batch).
 
     Example:
-        >>> import asyncio
-        >>> from typing import List
-        >>> p = AsyncBatchingMapProxy[int, str](batch_size=2)
-        >>> async def af(xs: list[int]) -> list[str]:
-        ...     await asyncio.sleep(0)
-        ...     return [f"v:{x}" for x in xs]
-        >>> async def run():
-        ...     return await p.map([1, 2, 3], af)
-        >>> asyncio.run(run())
-        ['v:1', 'v:2', 'v:3']
+        ```python
+        import asyncio
+
+        p = AsyncBatchingMapProxy[int, str](batch_size=2)
+
+        async def af(xs: list[int]) -> list[str]:
+            await asyncio.sleep(0)
+            return [f"v:{x}" for x in xs]
+
+        async def run():
+            return await p.map([1, 2, 3], af)
+
+        asyncio.run(run())
+        # ['v:1', 'v:2', 'v:3']
+        ```
     """
 
     # Number of items to process per call to map_func.
@@ -747,6 +771,19 @@ class AsyncBatchingMapProxy(ProxyBase[S, T], Generic[S, T]):
 
         Returns:
             list[T]: Mapped values corresponding to ``items`` in the same order.
+
+        Example:
+            ```python
+            import asyncio
+
+            async def mapper(chunk: list[int]) -> list[str]:
+                await asyncio.sleep(0)
+                return [f"v:{x}" for x in chunk]
+
+            proxy: AsyncBatchingMapProxy[int, str] = AsyncBatchingMapProxy(batch_size=2)
+            asyncio.run(proxy.map([1, 1, 2], mapper))
+            # ['v:1', 'v:1', 'v:2']
+            ```
         """
         if await self.__all_cached(items):
             return await self.__values(items)

openaivec/spark.py

@@ -181,6 +181,20 @@ def setup(
             If provided, registers `ResponsesModelName` in the DI container.
         embeddings_model_name (str | None): Default model name for embeddings.
             If provided, registers `EmbeddingsModelName` in the DI container.
+
+    Example:
+        ```python
+        from pyspark.sql import SparkSession
+        from openaivec.spark import setup
+
+        spark = SparkSession.builder.getOrCreate()
+        setup(
+            spark,
+            api_key="sk-***",
+            responses_model_name="gpt-4.1-mini",
+            embeddings_model_name="text-embedding-3-small",
+        )
+        ```
     """
 
     CONTAINER.register(SparkSession, lambda: spark)
@@ -221,6 +235,22 @@ def setup_azure(
             If provided, registers `ResponsesModelName` in the DI container.
         embeddings_model_name (str | None): Default model name for embeddings.
             If provided, registers `EmbeddingsModelName` in the DI container.
+
+    Example:
+        ```python
+        from pyspark.sql import SparkSession
+        from openaivec.spark import setup_azure
+
+        spark = SparkSession.builder.getOrCreate()
+        setup_azure(
+            spark,
+            api_key="azure-key",
+            base_url="https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/",
+            api_version="preview",
+            responses_model_name="gpt4-deployment",
+            embeddings_model_name="embedding-deployment",
+        )
+        ```
     """
 
     CONTAINER.register(SparkSession, lambda: spark)
@@ -375,6 +405,19 @@ def responses_udf(
     Raises:
         ValueError: If `response_format` is not `str` or a Pydantic `BaseModel`.
 
+    Example:
+        ```python
+        from pyspark.sql import SparkSession
+        from openaivec.spark import responses_udf, setup
+
+        spark = SparkSession.builder.getOrCreate()
+        setup(spark, api_key="sk-***", responses_model_name="gpt-4.1-mini")
+        udf = responses_udf("Reply with one word.")
+        spark.udf.register("short_answer", udf)
+        df = spark.createDataFrame([("hello",), ("bye",)], ["text"])
+        df.selectExpr("short_answer(text) as reply").show()
+        ```
+
     Note:
         For optimal performance in distributed environments:
         - **Automatic Caching**: Duplicate inputs within each partition are cached,
@@ -533,6 +576,20 @@ def infer_schema(
 
     Returns:
         InferredSchema: An object containing the inferred schema and response format.
+
+    Example:
+        ```python
+        from pyspark.sql import SparkSession
+
+        spark = SparkSession.builder.getOrCreate()
+        spark.createDataFrame([("great product",), ("bad service",)], ["text"]).createOrReplaceTempView("examples")
+        infer_schema(
+            instructions="Classify sentiment as positive or negative.",
+            example_table_name="examples",
+            example_field_name="text",
+            max_examples=2,
+        )
+        ```
     """
 
     spark = CONTAINER.resolve(SparkSession)
@@ -595,6 +652,23 @@ def parse_udf(
             forwarded verbatim to the underlying API calls. These parameters are applied to
             all API requests made by the UDF and override any parameters set in the
             response_format or example data.
+    Example:
+        ```python
+        from pyspark.sql import SparkSession
+
+        spark = SparkSession.builder.getOrCreate()
+        spark.createDataFrame(
+            [("Order #123 delivered",), ("Order #456 delayed",)],
+            ["body"],
+        ).createOrReplaceTempView("messages")
+        udf = parse_udf(
+            instructions="Extract order id as `order_id` and status as `status`.",
+            example_table_name="messages",
+            example_field_name="body",
+        )
+        spark.udf.register("parse_ticket", udf)
+        spark.sql("SELECT parse_ticket(body) AS parsed FROM messages").show()
+        ```
     Returns:
         UserDefinedFunction: A Spark pandas UDF configured to parse responses asynchronously.
             Output schema is `StringType` for str response format or a struct derived from

{openaivec-1.0.1.dist-info → openaivec-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openaivec
-Version: 1.0.1
+Version: 1.0.3
 Summary: Generative mutation for tabular calculation
 Project-URL: Homepage, https://microsoft.github.io/openaivec/
 Project-URL: Repository, https://github.com/microsoft/openaivec
@@ -57,13 +57,27 @@ reviews = pd.Series([
 
 sentiment = reviews.ai.responses(
     "Summarize sentiment in one short sentence.",
-    reasoning={"effort": "medium"},  # Mirrors OpenAI SDK for reasoning models
+    reasoning={"effort": "none"},  # Mirrors OpenAI SDK for reasoning models
 )
 print(sentiment.tolist())
 ```
 
 **Try it live:** https://microsoft.github.io/openaivec/examples/pandas/
 
+## Benchmarks
+
+Simple task benchmark from [benchmark.ipynb](https://github.com/microsoft/openaivec/blob/main/docs/examples/benchmark.ipynb) (100 numeric strings → integer literals, `Series.aio.responses`, model `gpt-5.1`):
+
+| Mode                | Settings                                        | Time (s) |
+| ------------------- | ----------------------------------------------- | -------- |
+| Serial              | `batch_size=1`, `max_concurrency=1`             | ~141     |
+| Batching            | default `batch_size`, `max_concurrency=1`       | ~15      |
+| Concurrent batching | default `batch_size`, default `max_concurrency` | ~6       |
+
+Batching alone removes most HTTP overhead, and letting batching overlap with concurrency cuts total runtime to a few seconds while still yielding one output per input.
+
+![Benchmark comparison for simple task](https://private-user-images.githubusercontent.com/6128022/519474214-d1931e34-6f9e-4695-8042-88b771e002c3.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NjQyMDc5ODAsIm5iZiI6MTc2NDIwNzY4MCwicGF0aCI6Ii82MTI4MDIyLzUxOTQ3NDIxNC1kMTkzMWUzNC02ZjllLTQ2OTUtODA0Mi04OGI3NzFlMDAyYzMucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI1MTEyNyUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNTExMjdUMDE0MTIwWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9Y2JhYmU2YjZhNDUxNDkxZDg5NGMxZGI1OTUzODgyYjQ4OTVhYzEzZjU3NmRkMjE1M2Y1ZDI3ZTdiNWI0M2VlMCZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.yuxT4AbDIBNsRGCIxPMjpGiHFqLcQUCLg_DjpqH02Lw)
+
 ## Contents
 
 - [Why openaivec?](#why-openaivec)
@@ -109,7 +123,7 @@ client = BatchResponses.of(
 
 result = client.parse(
     ["panda", "rabbit", "koala"],
-    reasoning={"effort": "medium"},  # Required for gpt-5.1
+    reasoning={"effort": "none"},
 )
 print(result)  # Expected output: ['bear family', 'rabbit family', 'koala family']
 ```
@@ -147,15 +161,15 @@ df = pd.DataFrame({"name": ["panda", "rabbit", "koala"]})
 result = df.assign(
     family=lambda df: df.name.ai.responses(
         "What animal family? Answer with 'X family'",
-        reasoning={"effort": "medium"},
+        reasoning={"effort": "none"},
     ),
     habitat=lambda df: df.name.ai.responses(
         "Primary habitat in one word",
-        reasoning={"effort": "medium"},
+        reasoning={"effort": "none"},
     ),
     fun_fact=lambda df: df.name.ai.responses(
         "One interesting fact in 10 words or less",
-        reasoning={"effort": "medium"},
+        reasoning={"effort": "none"},
     ),
 )
 ```
@@ -178,7 +192,7 @@ pandas_ext.set_responses_model("o1-mini")  # Set your reasoning model
 result = df.assign(
     analysis=lambda df: df.text.ai.responses(
         "Analyze this text step by step",
-        reasoning={"effort": "medium"}  # Optional: mirrors the OpenAI SDK argument
+        reasoning={"effort": "none"}  # Optional: mirrors the OpenAI SDK argument
     )
 )
 ```
@@ -232,7 +246,7 @@ df = pd.DataFrame({"text": [
 async def process_data():
     return await df["text"].aio.responses(
         "Analyze sentiment and classify as positive/negative/neutral",
-        reasoning={"effort": "medium"},  # Required for gpt-5.1
+        reasoning={"effort": "none"},  # Required for gpt-5.1
         max_concurrency=12    # Allow up to 12 concurrent requests
     )
 
@@ -284,7 +298,7 @@ spark.udf.register(
     "extract_brand",
     responses_udf(
         instructions="Extract the brand name from the product. Return only the brand name.",
-        reasoning={"effort": "medium"},  # Recommended with gpt-5.1
+        reasoning={"effort": "none"},  # Recommended with gpt-5.1
     )
 )
 
@@ -298,7 +312,7 @@ spark.udf.register(
     responses_udf(
         instructions="Translate the text to English, French, and Japanese.",
         response_format=Translation,
-        reasoning={"effort": "medium"},  # Recommended with gpt-5.1
+        reasoning={"effort": "none"},  # Recommended with gpt-5.1
     )
 )
 
@@ -336,7 +350,7 @@ prompt = (
 
 ## Using with Microsoft Fabric
 
-[Microsoft Fabric](https://www.microsoft.com/en-us/microsoft-fabric/) is a unified, cloud-based analytics platform. Add `openaivec` from PyPI in your Fabric environment, select it in your notebook, and use `openaivec.spark` like standard Spark. Detailed walkthrough: 📓 **[Fabric guide →](https://microsoft.github.io/openaivec/examples/fabric/)**.
+[Microsoft Fabric](https://www.microsoft.com/en-us/microsoft-fabric/) is a unified, cloud-based analytics platform. Add `openaivec` from PyPI in your Fabric environment, select it in your notebook, and use `openaivec.spark` like standard Spark.
 
 ## Contributing
 
@@ -374,4 +388,4 @@ uv run pytest -m "not slow and not requires_api"
 
 ## Community
 
-Join our Discord community for support and announcements: https://discord.gg/vbb83Pgn
+Join our Discord community for support and announcements: https://discord.gg/hXCS9J6Qek

{openaivec-1.0.1.dist-info → openaivec-1.0.3.dist-info}/RECORD

@@ -9,10 +9,10 @@ openaivec/_responses.py,sha256=Lb37ajlFQoVVac_p9oVf3scUDS3AI1ro4tRlk_UBqVg,20412
 openaivec/_serialize.py,sha256=u2Om94Sc_QgJkTlW2BAGw8wd6gYDhc6IRqvS-qevFSs,8399
 openaivec/_util.py,sha256=XfueAycVCQvgRLS7wF7e306b53lebORvZOBzbQjy4vE,6438
 openaivec/pandas_ext.py,sha256=XEmB08FS6lFtk6V7zzM4XHnzPkLCZ08OFFlkX-f0Oko,86730
-openaivec/spark.py,sha256=PIZxy3pVSrUv9PB2KBXQNM8beEvn_abaCYGS1DZmanY,32764
+openaivec/spark.py,sha256=OsEuwRRBzNs8Zv-hwDDsXR7A-dqZT651sdRmGkziTOo,35236
 openaivec/_cache/__init__.py,sha256=IYUH5GKsJXuCX-k3XtT259rEz49EZm9KW2TIOTGW4uQ,314
 openaivec/_cache/optimize.py,sha256=3nS8VehbS7iGC1tPDDQh-iAgyKHbVYmMbCRBWM77U_U,3827
-openaivec/_cache/proxy.py,sha256=mBUaYNFLrix6ZDblSHXmKlrd4qraaoVpbHGJ-_RlK-s,29666
+openaivec/_cache/proxy.py,sha256=aVjH_hmJIIso6SetV_-Ct3VaOSG-n9Dpil7TttnbYkE,30556
 openaivec/_schema/__init__.py,sha256=XUj3Jv6ZVDjyYzSmH6Q5lmDj-hBMfUg_eBNeZACXR6Q,368
 openaivec/_schema/infer.py,sha256=gcrpw0OVJMWdmUlzimP-C14cuCAAOnHQd8-bUNR220o,15705
 openaivec/_schema/spec.py,sha256=7ZaC59w2Edemnao57XeZVO4qmSOA-Kus6TchZC3Dd5o,14821
@@ -33,7 +33,7 @@ openaivec/task/nlp/sentiment_analysis.py,sha256=1igoAhns-VgsDE8XI47Dw-zeOcR5wEY9
 openaivec/task/nlp/translation.py,sha256=TtV7F6bmKPqLi3_Ok7GoOqT_GKJiemotVq-YEbKd6IA,6617
 openaivec/task/table/__init__.py,sha256=kJz15WDJXjyC7UIHKBvlTRhCf347PCDMH5T5fONV2sU,83
 openaivec/task/table/fillna.py,sha256=4j27fWT5IzOhQqCPwLhomjBOAWPBslyIBbBMspjqtbw,6877
-openaivec-1.0.1.dist-info/METADATA,sha256=xLWrSZd9aX_mgAElLZgHft-jUbvrZfumvx_uJbr8C1Y,12991
-openaivec-1.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openaivec-1.0.1.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
-openaivec-1.0.1.dist-info/RECORD,,
+openaivec-1.0.3.dist-info/METADATA,sha256=p07OFXtO0GMy4uiWIs-XooTcpJr-SnFIvd9-4x2W9-8,14484
+openaivec-1.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openaivec-1.0.3.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+openaivec-1.0.3.dist-info/RECORD,,

{openaivec-1.0.1.dist-info → openaivec-1.0.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any