openaivec 1.0.1__tar.gz → 1.0.2__tar.gz

{openaivec-1.0.1 → openaivec-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openaivec
-Version: 1.0.1
+Version: 1.0.2
 Summary: Generative mutation for tabular calculation
 Project-URL: Homepage, https://microsoft.github.io/openaivec/
 Project-URL: Repository, https://github.com/microsoft/openaivec
@@ -57,7 +57,7 @@ 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())
 ```
@@ -109,7 +109,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 +147,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 +178,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 +232,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 +284,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 +298,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 +336,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 +374,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 → openaivec-1.0.2}/README.md

@@ -31,7 +31,7 @@ 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())
 ```
@@ -83,7 +83,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']
 ```
@@ -121,15 +121,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"},
     ),
 )
 ```
@@ -152,7 +152,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
     )
 )
 ```
@@ -206,7 +206,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
     )
 
@@ -258,7 +258,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
     )
 )
 
@@ -272,7 +272,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
     )
 )
 
@@ -310,7 +310,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
 
@@ -348,4 +348,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 → openaivec-1.0.2}/src/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-1.0.1 → openaivec-1.0.2}/src/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