openaivec 1.0.9__tar.gz → 1.0.11__tar.gz

openaivec-1.0.11/.github/workflows/test-pr.yml

@@ -0,0 +1,71 @@
+name: ci-integration
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: read
+
+jobs:
+  test:
+    if: >
+      github.event.issue.pull_request &&
+      contains(github.event.comment.body, '/run-integration') &&
+      (github.event.comment.author_association == 'MEMBER' ||
+       github.event.comment.author_association == 'OWNER'  ||
+       github.event.comment.author_association == 'COLLABORATOR')
+
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: Comment workflow run link
+        shell: bash
+        run: |
+          set -euo pipefail
+          COMMENTS_URL="${{ github.event.issue.comments_url }}"
+          RUN_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          export RUN_URL
+          PAYLOAD="$(python -c 'import json,os; print(json.dumps({\"body\": f\"Integration workflow started: {os.environ[\\\"RUN_URL\\\"]}\"}))')"
+          curl -sS -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+               -H "Accept: application/vnd.github+json" \
+               -d "$PAYLOAD" \
+               "$COMMENTS_URL"
+
+      - name: Fetch PR head SHA
+        id: pr
+        shell: bash
+        run: |
+          set -euo pipefail
+          PR_API_URL="${{ github.event.issue.pull_request.url }}"
+          JSON="$(curl -sS -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+                       -H "Accept: application/vnd.github+json" "$PR_API_URL")"
+          echo "sha=$(python -c 'import json,sys; print(json.load(sys.stdin)[\"head\"][\"sha\"])' <<<\"$JSON\")" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout PR head commit
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.pr.outputs.sha }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.10
+
+      - name: Install dependencies via uv
+        run: uv sync --all-extras --dev
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Type check with pyright
+        run: uv run pyright src/openaivec || echo "Type check completed with issues - see above"
+
+      - name: Run tests
+        run: uv run pytest

{openaivec-1.0.9 → openaivec-1.0.11}/.github/workflows/test.yml

@@ -11,6 +11,7 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    environment: integration
     env:
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 

{openaivec-1.0.9 → openaivec-1.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openaivec
-Version: 1.0.9
+Version: 1.0.11
 Summary: Generative mutation for tabular calculation
 Project-URL: Homepage, https://microsoft.github.io/openaivec/
 Project-URL: Repository, https://github.com/microsoft/openaivec
@@ -60,9 +60,10 @@ sentiment = reviews.ai.responses(
     reasoning={"effort": "none"},  # Mirrors OpenAI SDK for reasoning models
 )
 print(sentiment.tolist())
+# Output: ['Positive sentiment', 'Negative sentiment']
 ```
 
-**Try it live:** https://microsoft.github.io/openaivec/examples/pandas/
+**Pandas tutorial (GitHub Pages):** https://microsoft.github.io/openaivec/examples/pandas/
 
 ## Benchmarks
 
@@ -81,6 +82,7 @@ Batching alone removes most HTTP overhead, and letting batching overlap with con
 ## Contents
 
 - [Why openaivec?](#why-openaivec)
+- [Overview](#overview)
 - [Core Workflows](#core-workflows)
 - [Using with Apache Spark UDFs](#using-with-apache-spark-udfs)
 - [Building Prompts](#building-prompts)
@@ -92,14 +94,13 @@ Batching alone removes most HTTP overhead, and letting batching overlap with con
 ## Why openaivec?
 
 - Drop-in `.ai` and `.aio` accessors keep pandas analysts in familiar tooling.
-- OpenAI batch-optimized: `BatchingMapProxy`/`AsyncBatchingMapProxy` coalesce requests, dedupe prompts, and keep column order stable.
-- Smart batching (`BatchingMapProxy`/`AsyncBatchingMapProxy`) dedupes prompts, preserves order, and releases waiters on failure.
+- OpenAI batch-optimized: `BatchingMapProxy`/`AsyncBatchingMapProxy` coalesce requests, dedupe prompts, preserve order, and release waiters on failure.
 - Reasoning support mirrors the OpenAI SDK; structured outputs accept Pydantic `response_format`.
 - Built-in caches and retries remove boilerplate; helpers reuse caches across pandas, Spark, and async flows.
 - Spark UDFs and Microsoft Fabric guides move notebooks into production-scale ETL.
 - Prompt tooling (`FewShotPromptBuilder`, `improve`) and the task library ship curated prompts with validated outputs.
 
-# Overview
+## Overview
 
 Vectorized OpenAI batch processing so you handle many inputs per call instead of one-by-one. Batching proxies dedupe inputs, enforce ordered outputs, and unblock waiters even on upstream errors. Cache helpers (`responses_with_cache`, Spark UDF builders) plug into the same layer so expensive prompts are reused across pandas, Spark, and async flows. Reasoning models honor SDK semantics. Requires Python 3.10+.
 
@@ -185,7 +186,7 @@ result = df.assign(
 
 ### Using with reasoning models
 
-Reasoning models (o1-preview, o1-mini, o3-mini, etc.) work without special flags. `reasoning` mirrors the OpenAI SDK.
+Reasoning models (o1-preview, o1-mini, o3-mini, etc.) follow OpenAI SDK semantics. Pass `reasoning` when you want to override model defaults.
 
 ```python
 pandas_ext.set_responses_model("o1-mini")  # Set your reasoning model
@@ -193,7 +194,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": "none"}  # Optional: mirrors the OpenAI SDK argument
+        reasoning={"effort": "none"},  # Optional: mirrors the OpenAI SDK argument
     )
 )
 ```
@@ -253,7 +254,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": "none"},  # Required for gpt-5.1
+        reasoning={"effort": "none"},  # Recommended for reasoning models
         max_concurrency=12    # Allow up to 12 concurrent requests
     )
 

{openaivec-1.0.9 → openaivec-1.0.11}/README.md

@@ -34,9 +34,10 @@ sentiment = reviews.ai.responses(
     reasoning={"effort": "none"},  # Mirrors OpenAI SDK for reasoning models
 )
 print(sentiment.tolist())
+# Output: ['Positive sentiment', 'Negative sentiment']
 ```
 
-**Try it live:** https://microsoft.github.io/openaivec/examples/pandas/
+**Pandas tutorial (GitHub Pages):** https://microsoft.github.io/openaivec/examples/pandas/
 
 ## Benchmarks
 
@@ -55,6 +56,7 @@ Batching alone removes most HTTP overhead, and letting batching overlap with con
 ## Contents
 
 - [Why openaivec?](#why-openaivec)
+- [Overview](#overview)
 - [Core Workflows](#core-workflows)
 - [Using with Apache Spark UDFs](#using-with-apache-spark-udfs)
 - [Building Prompts](#building-prompts)
@@ -66,14 +68,13 @@ Batching alone removes most HTTP overhead, and letting batching overlap with con
 ## Why openaivec?
 
 - Drop-in `.ai` and `.aio` accessors keep pandas analysts in familiar tooling.
-- OpenAI batch-optimized: `BatchingMapProxy`/`AsyncBatchingMapProxy` coalesce requests, dedupe prompts, and keep column order stable.
-- Smart batching (`BatchingMapProxy`/`AsyncBatchingMapProxy`) dedupes prompts, preserves order, and releases waiters on failure.
+- OpenAI batch-optimized: `BatchingMapProxy`/`AsyncBatchingMapProxy` coalesce requests, dedupe prompts, preserve order, and release waiters on failure.
 - Reasoning support mirrors the OpenAI SDK; structured outputs accept Pydantic `response_format`.
 - Built-in caches and retries remove boilerplate; helpers reuse caches across pandas, Spark, and async flows.
 - Spark UDFs and Microsoft Fabric guides move notebooks into production-scale ETL.
 - Prompt tooling (`FewShotPromptBuilder`, `improve`) and the task library ship curated prompts with validated outputs.
 
-# Overview
+## Overview
 
 Vectorized OpenAI batch processing so you handle many inputs per call instead of one-by-one. Batching proxies dedupe inputs, enforce ordered outputs, and unblock waiters even on upstream errors. Cache helpers (`responses_with_cache`, Spark UDF builders) plug into the same layer so expensive prompts are reused across pandas, Spark, and async flows. Reasoning models honor SDK semantics. Requires Python 3.10+.
 
@@ -159,7 +160,7 @@ result = df.assign(
 
 ### Using with reasoning models
 
-Reasoning models (o1-preview, o1-mini, o3-mini, etc.) work without special flags. `reasoning` mirrors the OpenAI SDK.
+Reasoning models (o1-preview, o1-mini, o3-mini, etc.) follow OpenAI SDK semantics. Pass `reasoning` when you want to override model defaults.
 
 ```python
 pandas_ext.set_responses_model("o1-mini")  # Set your reasoning model
@@ -167,7 +168,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": "none"}  # Optional: mirrors the OpenAI SDK argument
+        reasoning={"effort": "none"},  # Optional: mirrors the OpenAI SDK argument
     )
 )
 ```
@@ -227,7 +228,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": "none"},  # Required for gpt-5.1
+        reasoning={"effort": "none"},  # Recommended for reasoning models
         max_concurrency=12    # Allow up to 12 concurrent requests
     )
 

{openaivec-1.0.9 → openaivec-1.0.11}/src/openaivec/_cache/optimize.py

@@ -21,7 +21,10 @@ class BatchSizeSuggester:
     min_batch_size: int = 10
     min_duration: float = 30.0
     max_duration: float = 60.0
-    step_ratio: float = 0.2
+    step_ratio_up: float = 0.1
+    step_ratio_down: float = 0.2
+    max_step: int | None = None
+    min_step: int = 1
     sample_size: int = 4
     _history: list[PerformanceMetric] = field(default_factory=list)
     _lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
@@ -34,8 +37,14 @@ class BatchSizeSuggester:
             raise ValueError("current_batch_size must be >= min_batch_size")
         if self.sample_size <= 0:
             raise ValueError("sample_size must be > 0")
-        if self.step_ratio <= 0:
-            raise ValueError("step_ratio must be > 0")
+        if self.step_ratio_up <= 0:
+            raise ValueError("step_ratio_up must be > 0")
+        if self.step_ratio_down <= 0:
+            raise ValueError("step_ratio_down must be > 0")
+        if self.max_step is not None and self.max_step <= 0:
+            raise ValueError("max_step must be > 0")
+        if self.min_step <= 0:
+            raise ValueError("min_step must be > 0")
         if self.min_duration <= 0 or self.max_duration <= 0:
             raise ValueError("min_duration and max_duration must be > 0")
         if self.min_duration >= self.max_duration:
@@ -94,9 +103,15 @@ class BatchSizeSuggester:
             current_size = self.current_batch_size
 
             if average_duration < self.min_duration:
-                new_batch_size = int(current_size * (1 + self.step_ratio))
+                delta = max(self.min_step, int(current_size * self.step_ratio_up))
+                if self.max_step is not None:
+                    delta = min(delta, self.max_step)
+                new_batch_size = current_size + delta
             elif average_duration > self.max_duration:
-                new_batch_size = int(current_size * (1 - self.step_ratio))
+                delta = max(self.min_step, int(current_size * self.step_ratio_down))
+                if self.max_step is not None:
+                    delta = min(delta, self.max_step)
+                new_batch_size = current_size - delta
             else:
                 new_batch_size = current_size
 

{openaivec-1.0.9 → openaivec-1.0.11}/src/openaivec/_provider.py

@@ -21,6 +21,51 @@ __all__ = []
 CONTAINER = di.Container()
 
 
+def _build_missing_credentials_error(
+    openai_api_key: str | None,
+    azure_api_key: str | None,
+    azure_base_url: str | None,
+    azure_api_version: str | None,
+) -> str:
+    """Build a detailed error message for missing credentials.
+
+    Args:
+        openai_api_key (str | None): The OpenAI API key value.
+        azure_api_key (str | None): The Azure OpenAI API key value.
+        azure_base_url (str | None): The Azure OpenAI base URL value.
+        azure_api_version (str | None): The Azure OpenAI API version value.
+
+    Returns:
+        str: A detailed error message with missing variables and setup instructions.
+    """
+    lines = ["No valid OpenAI or Azure OpenAI credentials found.", ""]
+
+    # Check OpenAI
+    lines.append("Option 1: Set OPENAI_API_KEY for OpenAI")
+    if openai_api_key:
+        lines.append("  ✓ OPENAI_API_KEY is set")
+    else:
+        lines.append("  ✗ OPENAI_API_KEY is not set")
+        lines.append('    Example: export OPENAI_API_KEY="sk-..."')
+    lines.append("")
+
+    # Check Azure OpenAI
+    lines.append("Option 2: Set all Azure OpenAI variables")
+    azure_vars = [
+        ("AZURE_OPENAI_API_KEY", azure_api_key, '"your-azure-api-key"'),
+        ("AZURE_OPENAI_BASE_URL", azure_base_url, '"https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/"'),
+        ("AZURE_OPENAI_API_VERSION", azure_api_version, '"2024-12-01-preview"'),
+    ]
+    for var_name, var_value, example in azure_vars:
+        if var_value:
+            lines.append(f"  ✓ {var_name} is set")
+        else:
+            lines.append(f"  ✗ {var_name} is not set")
+            lines.append(f"    Example: export {var_name}={example}")
+
+    return "\n".join(lines)
+
+
 def _check_azure_v1_api_url(base_url: str) -> None:
     """Check if Azure OpenAI base URL uses the recommended v1 API format.
 
@@ -81,9 +126,12 @@ def provide_openai_client() -> OpenAI:
         )
 
     raise ValueError(
-        "No valid OpenAI or Azure OpenAI environment variables found. "
-        "Please set either OPENAI_API_KEY or AZURE_OPENAI_API_KEY, "
-        "AZURE_OPENAI_BASE_URL, and AZURE_OPENAI_API_VERSION."
+        _build_missing_credentials_error(
+            openai_api_key=openai_api_key.value,
+            azure_api_key=azure_api_key.value,
+            azure_base_url=azure_base_url.value,
+            azure_api_version=azure_api_version.value,
+        )
     )
 
 
@@ -124,9 +172,12 @@ def provide_async_openai_client() -> AsyncOpenAI:
         )
 
     raise ValueError(
-        "No valid OpenAI or Azure OpenAI environment variables found. "
-        "Please set either OPENAI_API_KEY or AZURE_OPENAI_API_KEY, "
-        "AZURE_OPENAI_BASE_URL, and AZURE_OPENAI_API_VERSION."
+        _build_missing_credentials_error(
+            openai_api_key=openai_api_key.value,
+            azure_api_key=azure_api_key.value,
+            azure_base_url=azure_base_url.value,
+            azure_api_version=azure_api_version.value,
+        )
     )
 
 

{openaivec-1.0.9 → openaivec-1.0.11}/tests/_cache/test_optimize.py

@@ -33,21 +33,35 @@ class TestBatchSizeSuggester:
         assert suggester.min_batch_size == 10
         assert suggester.min_duration == 30.0
         assert suggester.max_duration == 60.0
-        assert suggester.step_ratio == 0.2
+        assert suggester.step_ratio_up == 0.1
+        assert suggester.step_ratio_down == 0.2
+        assert suggester.max_step is None
+        assert suggester.min_step == 1
         assert suggester.sample_size == 4
         assert len(suggester._history) == 0
         assert suggester._batch_size_changed_at is None
 
     def test_custom_initialization(self):
         suggester = BatchSizeSuggester(
-            current_batch_size=20, min_batch_size=5, min_duration=15.0, max_duration=45.0, step_ratio=0.2, sample_size=5
+            current_batch_size=20,
+            min_batch_size=5,
+            min_duration=15.0,
+            max_duration=45.0,
+            step_ratio_up=0.15,
+            step_ratio_down=0.25,
+            min_step=2,
+            max_step=5,
+            sample_size=5,
         )
 
         assert suggester.current_batch_size == 20
         assert suggester.min_batch_size == 5
         assert suggester.min_duration == 15.0
         assert suggester.max_duration == 45.0
-        assert suggester.step_ratio == 0.2
+        assert suggester.step_ratio_up == 0.15
+        assert suggester.step_ratio_down == 0.25
+        assert suggester.min_step == 2
+        assert suggester.max_step == 5
         assert suggester.sample_size == 5
 
     @pytest.mark.parametrize(
@@ -56,7 +70,10 @@ class TestBatchSizeSuggester:
             ({"min_batch_size": 0}, "min_batch_size must be > 0"),
             ({"current_batch_size": 5, "min_batch_size": 10}, "current_batch_size must be >= min_batch_size"),
             ({"sample_size": 0}, "sample_size must be > 0"),
-            ({"step_ratio": 0}, "step_ratio must be > 0"),
+            ({"step_ratio_up": 0}, "step_ratio_up must be > 0"),
+            ({"step_ratio_down": 0}, "step_ratio_down must be > 0"),
+            ({"min_step": 0}, "min_step must be > 0"),
+            ({"max_step": 0}, "max_step must be > 0"),
             ({"min_duration": 0}, "min_duration and max_duration must be > 0"),
             ({"max_duration": 0}, "min_duration and max_duration must be > 0"),
             ({"min_duration": 60, "max_duration": 30}, "min_duration must be < max_duration"),
@@ -190,7 +207,8 @@ class TestBatchSizeSuggester:
             min_batch_size=min_batch_size,
             min_duration=0.5,  # 0.5 seconds (test scale)
             max_duration=1.0,  # 1.0 seconds (test scale)
-            step_ratio=0.1,
+            step_ratio_up=0.1,
+            step_ratio_down=0.1,
             sample_size=3,
         )
 
@@ -214,7 +232,7 @@ class TestBatchSizeSuggester:
             min_batch_size=5,
             min_duration=0.5,  # 0.5 seconds (test scale)
             max_duration=1.0,  # 1.0 seconds (test scale)
-            step_ratio=0.5,  # Large step to force below minimum
+            step_ratio_down=0.5,  # Large step to force below minimum
             sample_size=3,
         )
 
@@ -227,6 +245,60 @@ class TestBatchSizeSuggester:
         assert new_size == 5  # Should not go below min_batch_size
         assert suggester.current_batch_size == 5
 
+    def test_min_step_enforces_minimum_delta_on_increase(self):
+        suggester = BatchSizeSuggester(
+            current_batch_size=10,
+            min_batch_size=1,
+            min_duration=0.5,
+            max_duration=1.0,
+            step_ratio_up=0.1,  # 10 * 0.1 = 1
+            min_step=5,  # force delta to 5
+            sample_size=3,
+        )
+
+        for i in range(3):
+            with suggester.record(batch_size=10):
+                time.sleep(0.1)  # fast -> increase
+
+        new_size = suggester.suggest_batch_size()
+        assert new_size == 15
+
+    def test_min_step_enforces_minimum_delta_on_decrease(self):
+        suggester = BatchSizeSuggester(
+            current_batch_size=20,
+            min_batch_size=1,
+            min_duration=0.5,
+            max_duration=1.0,
+            step_ratio_down=0.1,  # 20 * 0.1 = 2
+            min_step=5,  # force delta to 5
+            sample_size=3,
+        )
+
+        for i in range(3):
+            with suggester.record(batch_size=20):
+                time.sleep(1.5)  # slow -> decrease
+
+        new_size = suggester.suggest_batch_size()
+        assert new_size == 15
+
+    def test_max_step_caps_delta(self):
+        suggester = BatchSizeSuggester(
+            current_batch_size=50,
+            min_batch_size=1,
+            min_duration=0.5,
+            max_duration=1.0,
+            step_ratio_up=0.5,  # 50 * 0.5 = 25
+            max_step=10,  # cap delta at 10
+            sample_size=3,
+        )
+
+        for i in range(3):
+            with suggester.record(batch_size=50):
+                time.sleep(0.1)  # fast -> increase
+
+        new_size = suggester.suggest_batch_size()
+        assert new_size == 60
+
     def test_thread_safety(self):
         suggester = BatchSizeSuggester(sample_size=10)
         results = []

{openaivec-1.0.9 → openaivec-1.0.11}/tests/_cache/test_proxy_suggester.py

@@ -42,7 +42,8 @@ def test_sync_proxy_suggester_adapts_batch_size():
     proxy.suggester.min_duration = 0.001  # 1ms
     proxy.suggester.max_duration = 0.002  # 2ms
     proxy.suggester.sample_size = 2
-    proxy.suggester.step_ratio = 0.5
+    proxy.suggester.step_ratio_up = 0.5
+    proxy.suggester.step_ratio_down = 0.5
 
     import time
 

{openaivec-1.0.9 → openaivec-1.0.11}/tests/test_provider.py

@@ -4,7 +4,12 @@ import warnings
 import pytest
 from openai import AsyncAzureOpenAI, AsyncOpenAI, AzureOpenAI, OpenAI
 
-from openaivec._provider import provide_async_openai_client, provide_openai_client, set_default_registrations
+from openaivec._provider import (
+    _build_missing_credentials_error,
+    provide_async_openai_client,
+    provide_openai_client,
+    set_default_registrations,
+)
 
 
 class TestProvideOpenAIClient:
@@ -80,7 +85,7 @@ class TestProvideOpenAIClient:
         with pytest.raises(ValueError) as context:
             provide_openai_client()
 
-        assert "No valid OpenAI or Azure OpenAI environment variables found" in str(context.value)
+        assert "No valid OpenAI or Azure OpenAI credentials found" in str(context.value)
 
     def test_provide_openai_client_with_azure_keys_default_version(self):
         """Test creating Azure OpenAI client with default API version when not specified."""
@@ -98,12 +103,16 @@ class TestProvideOpenAIClient:
         with pytest.raises(ValueError) as context:
             provide_openai_client()
 
-        expected_message = (
-            "No valid OpenAI or Azure OpenAI environment variables found. "
-            "Please set either OPENAI_API_KEY or AZURE_OPENAI_API_KEY, "
-            "AZURE_OPENAI_BASE_URL, and AZURE_OPENAI_API_VERSION."
-        )
-        assert str(context.value) == expected_message
+        error_message = str(context.value)
+        # Check that the error message contains helpful information
+        assert "No valid OpenAI or Azure OpenAI credentials found" in error_message
+        assert "OPENAI_API_KEY" in error_message
+        assert "AZURE_OPENAI_API_KEY" in error_message
+        assert "AZURE_OPENAI_BASE_URL" in error_message
+        assert "AZURE_OPENAI_API_VERSION" in error_message
+        # Check that setup examples are provided
+        assert "export OPENAI_API_KEY" in error_message
+        assert "export AZURE_OPENAI_API_KEY" in error_message
 
     def test_provide_openai_client_with_empty_openai_key(self):
         """Test that empty OPENAI_API_KEY is treated as not set."""
@@ -199,7 +208,7 @@ class TestProvideAsyncOpenAIClient:
         with pytest.raises(ValueError) as context:
             provide_async_openai_client()
 
-        assert "No valid OpenAI or Azure OpenAI environment variables found" in str(context.value)
+        assert "No valid OpenAI or Azure OpenAI credentials found" in str(context.value)
 
     def test_provide_async_openai_client_with_azure_keys_default_version(self):
         """Test creating async Azure OpenAI client with default API version when not specified."""
@@ -217,12 +226,16 @@ class TestProvideAsyncOpenAIClient:
         with pytest.raises(ValueError) as context:
             provide_async_openai_client()
 
-        expected_message = (
-            "No valid OpenAI or Azure OpenAI environment variables found. "
-            "Please set either OPENAI_API_KEY or AZURE_OPENAI_API_KEY, "
-            "AZURE_OPENAI_BASE_URL, and AZURE_OPENAI_API_VERSION."
-        )
-        assert str(context.value) == expected_message
+        error_message = str(context.value)
+        # Check that the error message contains helpful information
+        assert "No valid OpenAI or Azure OpenAI credentials found" in error_message
+        assert "OPENAI_API_KEY" in error_message
+        assert "AZURE_OPENAI_API_KEY" in error_message
+        assert "AZURE_OPENAI_BASE_URL" in error_message
+        assert "AZURE_OPENAI_API_VERSION" in error_message
+        # Check that setup examples are provided
+        assert "export OPENAI_API_KEY" in error_message
+        assert "export AZURE_OPENAI_API_KEY" in error_message
 
     def test_provide_async_openai_client_with_empty_openai_key(self):
         """Test that empty OPENAI_API_KEY is treated as not set."""
@@ -399,3 +412,78 @@ class TestAzureV1ApiWarning:
             assert "v1 API is recommended" in str(w[0].message)
 
         set_default_registrations()
+
+
+class TestBuildMissingCredentialsError:
+    """Test the _build_missing_credentials_error helper function."""
+
+    def test_all_variables_missing(self):
+        """Test error message when all variables are missing."""
+        message = _build_missing_credentials_error(
+            openai_api_key=None,
+            azure_api_key=None,
+            azure_base_url=None,
+            azure_api_version=None,
+        )
+
+        assert "No valid OpenAI or Azure OpenAI credentials found" in message
+        assert "✗ OPENAI_API_KEY is not set" in message
+        assert "✗ AZURE_OPENAI_API_KEY is not set" in message
+        assert "✗ AZURE_OPENAI_BASE_URL is not set" in message
+        assert "✗ AZURE_OPENAI_API_VERSION is not set" in message
+        assert 'export OPENAI_API_KEY="sk-..."' in message
+
+    def test_only_openai_key_set(self):
+        """Test error message when only OpenAI key is set (but this shouldn't trigger error)."""
+        message = _build_missing_credentials_error(
+            openai_api_key="sk-test",
+            azure_api_key=None,
+            azure_base_url=None,
+            azure_api_version=None,
+        )
+
+        assert "✓ OPENAI_API_KEY is set" in message
+        assert "✗ AZURE_OPENAI_API_KEY is not set" in message
+
+    def test_partial_azure_config(self):
+        """Test error message when Azure config is partially set."""
+        message = _build_missing_credentials_error(
+            openai_api_key=None,
+            azure_api_key="test-key",
+            azure_base_url=None,
+            azure_api_version="preview",
+        )
+
+        assert "✗ OPENAI_API_KEY is not set" in message
+        assert "✓ AZURE_OPENAI_API_KEY is set" in message
+        assert "✗ AZURE_OPENAI_BASE_URL is not set" in message
+        assert "✓ AZURE_OPENAI_API_VERSION is set" in message
+        # Should include example for missing URL
+        assert "export AZURE_OPENAI_BASE_URL=" in message
+
+    def test_all_azure_variables_set(self):
+        """Test error message when all Azure variables are set."""
+        message = _build_missing_credentials_error(
+            openai_api_key=None,
+            azure_api_key="test-key",
+            azure_base_url="https://test.openai.azure.com/openai/v1/",
+            azure_api_version="preview",
+        )
+
+        assert "✗ OPENAI_API_KEY is not set" in message
+        assert "✓ AZURE_OPENAI_API_KEY is set" in message
+        assert "✓ AZURE_OPENAI_BASE_URL is set" in message
+        assert "✓ AZURE_OPENAI_API_VERSION is set" in message
+
+    def test_error_message_includes_examples(self):
+        """Test that error message includes setup examples."""
+        message = _build_missing_credentials_error(
+            openai_api_key=None,
+            azure_api_key=None,
+            azure_base_url=None,
+            azure_api_version=None,
+        )
+
+        assert "Option 1: Set OPENAI_API_KEY for OpenAI" in message
+        assert "Option 2: Set all Azure OpenAI variables" in message
+        assert "Example:" in message