Standardize provider factory methods in codebase

.github/workflows/evals.yml

@@ -28,6 +28,6 @@ jobs:
         run: uv sync --all-extras --dev
 
       - name: Run all tests
-        run: uv run pytest tests/
+        run: uv run pytest tests/ --asyncio-mode=auto
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

.github/workflows/test.yml

@@ -22,7 +22,11 @@ jobs:
       - name: Install the project
         run: uv sync --all-extras
       - name: Run core tests
-        run: uv run pytest tests/ -k 'not llm and not openai and not gemini and not anthropic and not cohere and not vertexai and not mistral and not xai and not docs'
+        run: >-
+          uv run pytest tests/ --asyncio-mode=auto -n auto
+          -k 'not test_core_providers and not test_openai and not test_anthropic
+          and not test_gemini and not test_genai and not test_writer and not
+          test_vertexai and not docs'
         env:
           INSTRUCTOR_ENV: CI
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -31,15 +35,110 @@ jobs:
           XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
           GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
 
+  # Core provider tests for OpenAI
+  core-openai:
+    name: Core Provider Tests (OpenAI)
+    runs-on: ubuntu-latest
+    needs: core-tests
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install the project
+        run: uv sync --all-extras
+      - name: Run core provider tests (OpenAI)
+        run: uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k "openai"
+        env:
+          INSTRUCTOR_ENV: CI
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+  # Core provider tests for Anthropic
+  core-anthropic:
+    name: Core Provider Tests (Anthropic)
+    runs-on: ubuntu-latest
+    needs: core-tests
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install the project
+        run: uv sync --all-extras
+      - name: Run core provider tests (Anthropic)
+        run: uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k "anthropic"
+        env:
+          INSTRUCTOR_ENV: CI
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+
+  # Core provider tests for Google
+  core-google:
+    name: Core Provider Tests (Google)
+    runs-on: ubuntu-latest
+    needs: core-tests
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install the project
+        run: uv sync --all-extras
+      - name: Run core provider tests (Google)
+        run: uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k "google"
+        env:
+          INSTRUCTOR_ENV: CI
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+
+  # Core provider tests for other providers
+  core-other:
+    name: Core Provider Tests (Other)
+    runs-on: ubuntu-latest
+    needs: core-tests
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.11
+      - name: Install the project
+        run: uv sync --all-extras
+      - name: Run core provider tests (Cohere, xAI, Mistral, etc)
+        run: uv run pytest tests/llm/test_core_providers -v --asyncio-mode=auto -n auto -k "cohere or xai or mistral or cerebras or fireworks or writer or perplexity"
+        env:
+          INSTRUCTOR_ENV: CI
+          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
+          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
+          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
+          CEREBRAS_API_KEY: ${{ secrets.CEREBRAS_API_KEY }}
+          FIREWORKS_API_KEY: ${{ secrets.FIREWORKS_API_KEY }}
+          WRITER_API_KEY: ${{ secrets.WRITER_API_KEY }}
+          PERPLEXITY_API_KEY: ${{ secrets.PERPLEXITY_API_KEY }}
+
   # Provider tests run in parallel
   provider-tests:
     name: ${{ matrix.provider.name }} Tests
     runs-on: ubuntu-latest
+    needs: [core-openai, core-anthropic, core-google, core-other]
     strategy:
       fail-fast: false
       matrix:
         provider:
-          - name: Openai
+          - name: OpenAI
             env_key: OPENAI_API_KEY
             test_path: tests/llm/test_openai
           - name: Anthropic
@@ -51,12 +150,12 @@ jobs:
           - name: Google GenAI
             env_key: GOOGLE_API_KEY
             test_path: tests/llm/test_genai
-          - name: Cohere
-            env_key: COHERE_API_KEY
-            test_path: tests/llm/test_cohere
-          - name: XAI
-            env_key: XAI_API_KEY
-            test_path: tests/llm/test_xai
+          - name: Vertex AI
+            env_key: GOOGLE_API_KEY
+            test_path: tests/llm/test_vertexai
+          - name: Writer
+            env_key: WRITER_API_KEY
+            test_path: tests/llm/test_writer
 
     steps:
       - uses: actions/checkout@v2
@@ -69,7 +168,7 @@ jobs:
       - name: Install the project
         run: uv sync --all-extras
       - name: Run ${{ matrix.provider.name }} tests
-        run: uv run pytest ${{ matrix.provider.test_path }} -n auto
+        run: uv run pytest ${{ matrix.provider.test_path }} --asyncio-mode=auto -n auto
         env:
           INSTRUCTOR_ENV: CI
           ${{ matrix.provider.env_key }}: ${{ secrets[matrix.provider.env_key] }}
@@ -78,6 +177,7 @@ jobs:
   auto-client-test:
     name: Auto Client Tests
     runs-on: ubuntu-latest
+    needs: [core-openai, core-anthropic, core-google, core-other]
 
     steps:
       - uses: actions/checkout@v2
@@ -90,7 +190,7 @@ jobs:
       - name: Install the project
         run: uv sync --all-extras
       - name: Run Auto Client tests
-        run: uv run pytest tests/test_auto_client.py
+        run: uv run pytest tests/test_auto_client.py --asyncio-mode=auto -n auto
         env:
           INSTRUCTOR_ENV: CI
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

.github/workflows/test_docs.yml

@@ -31,6 +31,6 @@ jobs:
       - name: Install the project
         run: uv sync --all-extras
       - name: Run tests
-        run: uv run pytest tests/docs
+        run: uv run pytest tests/docs --asyncio-mode=auto
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

CLAUDE.md

@@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Commands
 - Install deps: `uv pip install -e ".[dev,anthropic]"` or `poetry install --with dev,anthropic`
-- Run tests: `uv run pytest tests/`
+- Run tests: `uv run pytest tests/ -n auto`
 - Run specific test: `uv run pytest tests/path_to_test.py::test_name`
 - Skip LLM tests: `uv run pytest tests/ -k 'not llm and not openai'`
 - Type check: `uv run ty check`

docs/integrations/google.md

@@ -275,6 +275,16 @@ for user in users:
     #> name='Mike' age=28
 ```
 
+## Known Limitations (as of Nov 12, 2024)
+
+Google Gemini has the following known limitations when used with Instructor:
+
+1. **Union Types**: Gemini does not support Union types (except for Optional). Use separate response models or Literal types instead.
+2. **Enum Types**: Gemini returns string values instead of properly typed Enum instances. You may need to manually convert strings to enums after extraction.
+3. **Union Streaming**: Streaming is not supported for Union types with Iterable.
+
+These limitations are specific to Google Gemini and do not affect other providers like OpenAI or Anthropic. Tests automatically skip these features for Google to prevent failures.
+
 ## Instructor Modes
 
 We provide several modes to make it easy to work with the different response models that Gemini supports:

instructor/processing/function_calls.py

@@ -399,10 +399,7 @@ def parse_anthropic_json(
             # read: https://docs.anthropic.com/en/docs/build-with-claude/tool-use/web-search-tool#response
             text_blocks = [c for c in completion.content if c.type == "text"]
             last_block = text_blocks[-1]
-            # Strip raw control characters (0x00-0x1F) that would cause json.loads to fail
-            # Note: This preserves escaped sequences like \n in JSON strings, which are handled
-            # correctly by the JSON parser. Only raw, unescaped control bytes are removed.
-            text = re.sub(r"[\u0000-\u001F]", "", last_block.text)
+            text = last_block.text
 
         extra_text = extract_json_from_codeblock(text)
 
@@ -411,7 +408,7 @@ def parse_anthropic_json(
                 extra_text, context=validation_context, strict=True
             )
         else:
-            # Allow control characters.
+            # Allow control characters to pass through by using the non-strict JSON parser.
             parsed = json.loads(extra_text, strict=False)
             # Pydantic non-strict: https://docs.pydantic.dev/latest/concepts/strict_mode/
             model = cls.model_validate(parsed, context=validation_context, strict=False)