chore(typing): replace pyright with ty (#1978)

jxnl · web-flow · commit 7ca2dcc6dfbd · 2026-01-04T09:58:54.000-05:00
diff --git a/.github/workflows/ruff.yml b/.github/workflows/ruff.yml
@@ -7,8 +7,6 @@ on:
 
 env:
   WORKING_DIRECTORY: "."
-  RUFF_OUTPUT_FILENAME: "ruff.log"
-  CUSTOM_FLAGS: ""
   CUSTOM_PACKAGES: "instructor examples tests"
 
 jobs:
@@ -25,10 +23,7 @@ jobs:
         run: uv python install 3.9
       - name: Install the project
         run: uv sync --all-extras
-      - name: Run Continuous Integration Action
-        uses: astral-sh/ruff-action@v3
-      - name: Upload Artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: ruff-log
-          path: ${{ env.WORKING_DIRECTORY }}/${{ env.RUFF_OUTPUT_FILENAME }}
+      - name: Ruff lint
+        run: uv run ruff check ${{ env.CUSTOM_PACKAGES }}
+      - name: Ruff format
+        run: uv run ruff format --check ${{ env.CUSTOM_PACKAGES }}
diff --git a/.github/workflows/ty.yml b/.github/workflows/ty.yml
@@ -1,4 +1,4 @@
-name: Type Check
+name: ty
 
 on:
   pull_request:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -33,3 +33,11 @@ repos:
         language: system
         files: ^pyproject\.toml$
         pass_filenames: false
+
+      - id: ty-check
+        name: Run Type Check (ty)
+        entry: uv
+        args: [run, ty, check]
+        language: system
+        files: ^instructor/
+        pass_filenames: false
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -251,7 +251,7 @@ We encourage contributions to our evaluation tests:
 We use automated tools to maintain consistent code style:
 
 - **Ruff**: For linting and formatting
-- **PyRight**: For type checking
+- **ty**: For type checking
 - **Black**: For code formatting (enforced by Ruff)
 
 General guidelines:
@@ -396,4 +396,4 @@ For more details, see our Cursor rules in `.cursor/rules/`.
 
 ## License
 
-By contributing to Instructor, you agree that your contributions will be licensed under the project's MIT License. 
+By contributing to Instructor, you agree that your contributions will be licensed under the project's MIT License. 
diff --git a/docs/blog/posts/migrating-to-uv.md b/docs/blog/posts/migrating-to-uv.md
@@ -30,7 +30,7 @@ In general I'd say that we saw a ~3x speedup with approximately 67% reduction in
 | Job              | Time (Poetry)                                                                                 | Time (UV)                                                                                            |
 | ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
 | Ruff Formatting  | [1m16s](https://github.com/instructor-ai/instructor/actions/runs/12386936314)                 | [28s](https://github.com/instructor-ai/instructor/actions/runs/12501982235) (-63%)                   |
-| Pyright          | [3m3s](https://github.com/instructor-ai/instructor/actions/runs/12488572568)                  | [39s](https://github.com/instructor-ai/instructor/actions/runs/12501974285) (-79%)                   |
+| Type checking    | [3m3s](https://github.com/instructor-ai/instructor/actions/runs/12488572568)                  | [39s](https://github.com/instructor-ai/instructor/actions/runs/12501974285) (-79%)                   |
 | Test Python 3.9  | [1m21s](https://github.com/instructor-ai/instructor/actions/runs/12251767751/job/34177033359) | [32s](https://github.com/instructor-ai/instructor/actions/runs/12501974279/job/34880278051) (-61%)   |
 | Test Python 3.10 | [1m32s](https://github.com/instructor-ai/instructor/actions/runs/12251767751/job/34177033359) | [33s](https://github.com/instructor-ai/instructor/actions/runs/12501974279/job/34880278299) (-64%)   |
 | Test Python 3.11 | [3m19](https://github.com/instructor-ai/instructor/actions/runs/12251767751/job/34177034094)  | [2m48s](https://github.com/instructor-ai/instructor/actions/runs/12501974279/job/34880278480) (-16%) |
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -295,7 +295,7 @@ For detailed documentation on each script, see the `scripts/README.md` file in t
 We use the following tools to maintain code quality:
 
 - **Ruff**: For linting and formatting
-- **PyRight**: For type checking
+- **ty**: For type checking
 - **Pre-commit**: For automatic checks before committing
 
 ```bash
diff --git a/instructor/auto_client.py b/instructor/auto_client.py
@@ -158,32 +158,69 @@ def from_provider(
     if provider == "openai":
         try:
             import openai
+            import httpx
             from instructor import from_openai  # type: ignore[attr-defined]
+            from openai import DEFAULT_MAX_RETRIES, NotGiven, Timeout, not_given
+            from collections.abc import Mapping
+            from typing import cast
 
             # Extract base_url and other OpenAI client parameters from kwargs
             base_url = kwargs.pop("base_url", None)
-            openai_client_kwargs = {}
-            for key in (
-                "organization",
-                "timeout",
-                "max_retries",
-                "default_headers",
-                "http_client",
-                "app_info",
-            ):
-                if key in kwargs:
-                    openai_client_kwargs[key] = kwargs.pop(key)
+            organization = cast(str | None, kwargs.pop("organization", None))
 
-            # Build client kwargs, including base_url if provided
-            client_kwargs = {"api_key": api_key, **openai_client_kwargs}
-            if base_url is not None:
-                client_kwargs["base_url"] = base_url
+            timeout_raw = kwargs.pop("timeout", not_given)
+            timeout: float | Timeout | None | NotGiven
+            timeout = (
+                not_given
+                if timeout_raw is not_given
+                else cast(float | Timeout | None, timeout_raw)
+            )
 
-            client = (
-                openai.AsyncOpenAI(**client_kwargs)
-                if async_client
-                else openai.OpenAI(**client_kwargs)
+            max_retries_raw = kwargs.pop("max_retries", None)
+            max_retries = (
+                DEFAULT_MAX_RETRIES
+                if max_retries_raw is None
+                else int(cast(int, max_retries_raw))
+            )
+
+            default_headers = cast(
+                Mapping[str, str] | None, kwargs.pop("default_headers", None)
+            )
+            default_query = cast(
+                Mapping[str, object] | None, kwargs.pop("default_query", None)
             )
+            http_client_raw = kwargs.pop("http_client", None)
+            strict_response_validation = bool(
+                kwargs.pop("_strict_response_validation", False)
+            )
+
+            if async_client:
+                http_client = cast(httpx.AsyncClient | None, http_client_raw)
+                client = openai.AsyncOpenAI(
+                    api_key=api_key,
+                    base_url=base_url,
+                    organization=organization,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                    default_headers=default_headers,
+                    default_query=default_query,
+                    http_client=http_client,
+                    _strict_response_validation=strict_response_validation,
+                )
+            else:
+                http_client = cast(httpx.Client | None, http_client_raw)
+                client = openai.OpenAI(
+                    api_key=api_key,
+                    base_url=base_url,
+                    organization=organization,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                    default_headers=default_headers,
+                    default_query=default_query,
+                    http_client=http_client,
+                    _strict_response_validation=strict_response_validation,
+                )
+
             result = from_openai(
                 client,
                 model=model_name,
diff --git a/instructor/processing/schema.py b/instructor/processing/schema.py
@@ -9,7 +9,7 @@
 
 import functools
 import warnings
-from typing import Any
+from typing import Any, cast
 
 from docstring_parser import parse
 from pydantic import BaseModel
@@ -112,7 +112,9 @@ def generate_gemini_schema(model: type[BaseModel]) -> Any:
     )
 
     try:
-        import google.generativeai.types as genai_types
+        import importlib
+
+        genai_types = cast(Any, importlib.import_module("google.generativeai.types"))
 
         # Use OpenAI schema
         openai_schema = generate_openai_schema(model)
diff --git a/instructor/providers/gemini/utils.py b/instructor/providers/gemini/utils.py
@@ -236,6 +236,42 @@ def transform_schema_node(node: Any) -> Any:
     return FunctionSchema(**schema).model_dump(exclude_none=True, exclude_unset=True)
 
 
+if TYPE_CHECKING:
+    from google.genai import types as genai_types
+
+
+def map_to_genai_schema(obj: dict[str, Any]) -> genai_types.Schema:
+    from google.genai import types
+
+    schema = map_to_gemini_function_schema(obj)
+
+    def normalize(node: Any) -> Any:
+        if isinstance(node, list):
+            return [normalize(item) for item in node]
+
+        if not isinstance(node, dict):
+            return node
+
+        key_map = {
+            "anyOf": "any_of",
+            "$ref": "ref",
+            "$defs": "defs",
+            "maxItems": "max_items",
+            "minItems": "min_items",
+            "maxLength": "max_length",
+            "minLength": "min_length",
+            "maxProperties": "max_properties",
+            "minProperties": "min_properties",
+        }
+
+        normalized: dict[str, Any] = {}
+        for key, value in node.items():
+            normalized[key_map.get(key, key)] = normalize(value)
+        return normalized
+
+    return types.Schema.model_validate(normalize(schema))
+
+
 def update_genai_kwargs(
     kwargs: dict[str, Any], base_config: dict[str, Any]
 ) -> dict[str, Any]:
@@ -583,7 +619,7 @@ def reask_vertexai_tools(
     Kwargs modifications:
     - Adds: "contents" (tool response messages indicating validation errors)
     """
-    from instructor.client_vertexai import vertexai_function_response_parser
+    from ..vertexai.client import vertexai_function_response_parser
 
     kwargs = kwargs.copy()
     reask_msgs = [
@@ -605,7 +641,7 @@ def reask_vertexai_json(
     Kwargs modifications:
     - Adds: "contents" (user message requesting JSON correction)
     """
-    from instructor.client_vertexai import vertexai_message_parser
+    from ..vertexai.client import vertexai_message_parser
 
     kwargs = kwargs.copy()
 
@@ -931,7 +967,7 @@ def handle_genai_tools(
     if "thinking_config" not in new_kwargs and user_thinking_config is not None:
         new_kwargs["thinking_config"] = user_thinking_config
 
-    schema = map_to_gemini_function_schema(_get_model_schema(response_model))
+    schema = map_to_genai_schema(_get_model_schema(response_model))
     function_definition = types.FunctionDeclaration(
         name=_get_model_name(response_model),
         description=getattr(response_model, "__doc__", None),
@@ -951,7 +987,8 @@ def handle_genai_tools(
         "tools": [types.Tool(function_declarations=[function_definition])],
         "tool_config": types.ToolConfig(
             function_calling_config=types.FunctionCallingConfig(
-                mode="ANY", allowed_function_names=[_get_model_name(response_model)]
+                mode=types.FunctionCallingConfigMode.ANY,
+                allowed_function_names=[_get_model_name(response_model)],
             ),
         ),
     }
@@ -989,7 +1026,7 @@ def handle_vertexai_parallel_tools(
     """
     from typing import get_args
 
-    from instructor.client_vertexai import vertexai_process_response
+    from ..vertexai.client import vertexai_process_response
     from instructor.dsl.parallel import VertexAIParallelModel
 
     if new_kwargs.get("stream", False):
@@ -1010,7 +1047,7 @@ def handle_vertexai_parallel_tools(
 def handle_vertexai_tools(
     response_model: type[Any] | None, new_kwargs: dict[str, Any]
 ) -> tuple[type[Any] | None, dict[str, Any]]:
-    from instructor.client_vertexai import vertexai_process_response
+    from ..vertexai.client import vertexai_process_response
 
     """
     Handle Vertex AI tools mode.
diff --git a/instructor/providers/mistral/client.py b/instructor/providers/mistral/client.py
@@ -56,7 +56,7 @@ def from_mistral(
     if use_async:
 
         async def async_wrapper(
-            *args: Any, **kwargs: dict[str, Any]
+            *args: Any, **kwargs: Any
         ):  # Handler for async streaming
             if kwargs.pop("stream", False):
                 return await client.chat.stream_async(*args, **kwargs)
@@ -70,9 +70,7 @@ async def async_wrapper(
             **kwargs,
         )
 
-    def sync_wrapper(
-        *args: Any, **kwargs: dict[str, Any]
-    ):  # Handler for sync streaming
+    def sync_wrapper(*args: Any, **kwargs: Any):  # Handler for sync streaming
         if kwargs.pop("stream", False):
             return client.chat.stream(*args, **kwargs)
         return client.chat.complete(*args, **kwargs)
diff --git a/instructor/providers/vertexai/client.py b/instructor/providers/vertexai/client.py
@@ -10,7 +10,7 @@
 import jsonref
 
 
-def _create_gemini_json_schema(model: BaseModel):
+def _create_gemini_json_schema(model: type[BaseModel]) -> dict[str, Any]:
     # Add type check to ensure we have a concrete model class
     if get_origin(model) is not None:
         raise TypeError(f"Expected concrete model class, got type hint {model}")
@@ -28,27 +28,27 @@ def _create_gemini_json_schema(model: BaseModel):
 
 
 def _create_vertexai_tool(
-    models: BaseModel | list[BaseModel] | type,
+    models: type[BaseModel] | list[type[BaseModel]] | Any,
 ) -> gm.Tool:  # noqa: UP007
     """Creates a tool with function declarations for single model or list of models"""
     # Handle Iterable case first
     if get_origin(models) is not None:
-        model_list = list(get_types_array(models))  # type: ignore
+        model_list = list(get_types_array(models))
     else:
         # Handle both single model and list of models
         model_list = models if isinstance(models, list) else [models]
 
     declarations = []
-    for model in model_list:  # type: ignore
-        parameters = _create_gemini_json_schema(model)  # type: ignore
+    for model in model_list:
+        parameters = _create_gemini_json_schema(model)
         declaration = gm.FunctionDeclaration(
-            name=model.__name__,  # type: ignore
-            description=model.__doc__,  # type: ignore
+            name=model.__name__,
+            description=model.__doc__,
             parameters=parameters,
         )
-        declarations.append(declaration)  # type: ignore
+        declarations.append(declaration)
 
-    return gm.Tool(function_declarations=declarations)  # type: ignore
+    return gm.Tool(function_declarations=declarations)
 
 
 def vertexai_message_parser(
@@ -103,7 +103,7 @@ def vertexai_function_response_parser(
 
 def vertexai_process_response(
     _kwargs: dict[str, Any],
-    model: Union[BaseModel, list[BaseModel], type],  # noqa: UP007
+    model: Union[type[BaseModel], list[type[BaseModel]], Any],  # noqa: UP007
 ):
     messages: list[dict[str, str]] = _kwargs.pop("messages")
     contents = _vertexai_message_list_parser(messages)  # type: ignore
@@ -118,7 +118,7 @@ def vertexai_process_response(
     return contents, [tool], tool_config
 
 
-def vertexai_process_json_response(_kwargs: dict[str, Any], model: BaseModel):
+def vertexai_process_json_response(_kwargs: dict[str, Any], model: type[BaseModel]):
     messages: list[dict[str, str]] = _kwargs.pop("messages")
     contents = _vertexai_message_list_parser(messages)  # type: ignore
 
diff --git a/pyrightconfig.json b/pyrightconfig.json
diff --git a/requirements-examples.txt b/requirements-examples.txt
@@ -5,8 +5,7 @@ rich
 aiohttp
 ruff==0.14.2
 pre-commit==4.3.0
-pyright==1.1.407
 typer
 cohere
 datasets
-trafilatura
+trafilatura
diff --git a/tests/test_genai_config_merging.py b/tests/test_genai_config_merging.py
diff --git a/tests/v2/test_provider_modes.py b/tests/v2/test_provider_modes.py
diff --git a/ty.toml b/ty.toml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name: Type Check`
	`1`	`+name: ty`
`2`	`2`
`3`	`3`	`on:`
`4`	`4`	`pull_request:`