DSPy: The framework for programming—not prompting—language models
Python
Add incremental internal typing with ty in CI and pre-commit (#10673)
Isaac Millerab1ca173e60e
diff --git a/.github/workflows/run_tests.yml b/.github/workflows/run_tests.ymlindex e38c73201..68c7b222a 100644--- a/.github/workflows/run_tests.yml+++ b/.github/workflows/run_tests.yml@@ -66,6 +66,8 @@ jobs:echo "Then commit and push the changes."exit 1)+ - name: Check internal types+ run: uv run --locked --extra dev ty checktest:name: Run Testsdiff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 5b07e462e..9aabce050 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -12,6 +12,15 @@ repos:exclude: ^(dspy/__metadata__\.py|dspy/_vendor/.*|tests/reliability/.*\.py)$args: [--fix-only]+ - repo: local+ hooks:+ - id: ty+ name: ty (internal types)+ entry: uv run --locked --extra dev ty check+ language: system+ pass_filenames: false+ always_run: true+- repo: https://github.com/pre-commit/pre-commit-hooksrev: v5.0.0hooks:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1272c78c0..17871cd55 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -72,6 +72,19 @@ You can also run the hooks manually:Please ensure all pre-commit checks pass before creating your pull request. If you're unsure about anyformatting issues, feel free to commit your changes and let the pre-commit hooks fix them automatically.+### Internal Type Checking++We are incrementally type-checking DSPy's internals with [Astral's ty](https://docs.astral.sh/ty/).+The goal is to make inputs and outputs clear to contributors, editors, and coding agents without requiring+them to trace an implementation. Run the same check as CI:++```shell+uv run --locked --extra dev ty check+```++The pre-commit hook runs this same command and requires `uv` on your PATH. It checks the entire configured+typing scope on every commit, rather than only staged files, because changes to imported code can affect types.+### Step 4. Create a Pull RequestOnce your changes are ready, open a pull request from your branch in your fork to the main branch in the@@ -176,5 +189,3 @@ AI-assisted contributions are welcome under these conditions:code is compatible with DSPy's MIT license.PRs that violate this policy will be closed without review.--diff --git a/dspy/dsp/utils/settings.py b/dspy/dsp/utils/settings.pyindex ee951c558..54c76184a 100644--- a/dspy/dsp/utils/settings.py+++ b/dspy/dsp/utils/settings.py@@ -47,7 +47,9 @@ config_owner_async_task = None# Global lock for settings configurationglobal_lock = threading.Lock()-thread_local_overrides = contextvars.ContextVar("context_overrides", default=dotdict())+thread_local_overrides: contextvars.ContextVar[dict[str, Any]] = contextvars.ContextVar(+ "context_overrides", default=dotdict()+)class Settings:diff --git a/dspy/utils/asyncify.py b/dspy/utils/asyncify.pyindex 9bc3ae435..327ef87df 100644--- a/dspy/utils/asyncify.py+++ b/dspy/utils/asyncify.py@@ -1,23 +1,29 @@+from __future__ import annotations+import functools-from typing import TYPE_CHECKING, Any, Awaitable, Callable+from typing import TYPE_CHECKING, Any, Callable, Coroutine, ParamSpec, TypeVar, castfrom dspy.utils.lazy_import import require-anyio = require("anyio")-if TYPE_CHECKING:- from dspy.primitives.module import Module+ import anyio.to_thread+else:+ anyio = require("anyio")++P = ParamSpec("P")+T = TypeVar("T")-_limiter = None+_limiter: anyio.CapacityLimiter | None = None-def get_async_max_workers():- import dspy+def get_async_max_workers() -> int:+ from dspy.dsp.utils.settings import settings- return dspy.settings.async_max_workers+ # Settings is an open mapping; narrow this known setting at its consumer.+ return cast(int, settings.async_max_workers)-def get_limiter():+def get_limiter() -> anyio.CapacityLimiter:async_max_workers = get_async_max_workers()global _limiter@@ -29,7 +35,7 @@ def get_limiter():return _limiter-def asyncify(program: "Module") -> Callable[[Any, Any], Awaitable[Any]]:+def asyncify(program: Callable[P, T]) -> Callable[P, Coroutine[Any, Any, T]]:"""Wraps a DSPy program so that it can be called asynchronously. This is useful for running aprogram in parallel with another task (e.g., another DSPy program).@@ -44,13 +50,13 @@ def asyncify(program: "Module") -> Callable[[Any, Any], Awaitable[Any]]:The current thread's configuration context is inherited for each call."""- async def async_program(*args, **kwargs) -> Any:+ async def async_program(*args: P.args, **kwargs: P.kwargs) -> T:# Capture the current overrides at call-time.from dspy.dsp.utils.settings import thread_local_overridesparent_overrides = thread_local_overrides.get().copy()- def wrapped_program(*a, **kw):+ def wrapped_program(*a: P.args, **kw: P.kwargs) -> T:from dspy.dsp.utils.settings import thread_local_overridesoriginal_overrides = thread_local_overrides.get()diff --git a/dspy/utils/usage_tracker.py b/dspy/utils/usage_tracker.pyindex dcc72e637..e99f08600 100644--- a/dspy/utils/usage_tracker.py+++ b/dspy/utils/usage_tracker.py@@ -2,7 +2,7 @@from collections import defaultdictfrom contextlib import contextmanager-from typing import Any, Generator+from typing import Any, Generator, TypeGuardfrom pydantic import BaseModel@@ -12,7 +12,7 @@ from dspy.dsp.utils.settings import settingsclass UsageTracker:"""Tracks LM usage data within a context."""- def __init__(self):+ def __init__(self) -> None:# Map of LM name to list of usage entries. For example:# {# "openai/gpt-4o-mini": [@@ -20,10 +20,11 @@ class UsageTracker:# {"prompt_tokens": 300, "completion_tokens": 400},# ],# }- self.usage_data = defaultdict(list)+ # Providers can include arbitrary extra fields, not just token counts.+ self.usage_data: defaultdict[str, list[dict[str, Any]]] = defaultdict(list)def _flatten_usage_entry(self, usage_entry: dict[str, Any]) -> dict[str, Any]:- result = {}+ result: dict[str, Any] = {}for key, value in usage_entry.items():if isinstance(value, BaseModel):# Convert Pydantic models to dicts, like `PromptTokensDetailsWrapper` from litellm.@@ -33,7 +34,7 @@ class UsageTracker:return result@staticmethod- def _is_summable(value: Any) -> bool:+ def _is_summable(value: object) -> TypeGuard[int | float]:"""Whether a usage value is a count that can be added across entries.`bool` is excluded even though it is an `int` subclass: providers report flags@@ -72,9 +73,9 @@ class UsageTracker:def get_total_tokens(self) -> dict[str, dict[str, Any]]:"""Calculate total tokens from all tracked usage."""- total_usage_by_lm = {}+ total_usage_by_lm: dict[str, dict[str, Any]] = {}for lm, usage_entries in self.usage_data.items():- total_usage = {}+ total_usage: dict[str, Any] = {}for usage_entry in usage_entries:total_usage = self._merge_usage_entries(total_usage, usage_entry)total_usage_by_lm[lm] = total_usage@@ -90,7 +91,7 @@ def track_usage() -> Generator[UsageTracker, None, None]:"""tracker = UsageTracker()- parent = settings.usage_tracker+ parent: UsageTracker | None = settings.usage_trackerwith settings.context(usage_tracker=tracker):try:yield trackerdiff --git a/pyproject.toml b/pyproject.tomlindex 89b210951..d90c64616 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -56,6 +56,7 @@ dev = ["pytest-asyncio>=0.26.0","pytest-xdist>=3.5.0","ruff>=0.3.0",+ "ty==0.0.89","pre-commit>=3.7.0","pillow>=10.1.0","datamodel_code_generator>=0.26.3",@@ -134,6 +135,20 @@ filterwarnings = ["ignore:.+class-based `config` is deprecated, use ConfigDict:DeprecationWarning",]+[tool.ty.src]+# Expand this list as internal modules are migrated. Dynamic Signature-derived+# inputs/outputs are not part of this initial type-checking contract.+include = [+ "dspy/utils/asyncify.py",+ "dspy/utils/usage_tracker.py",+ "tests/typing",+]++[tool.ty.rules]+missing-type-argument = "error"+unsound-return-statement = "error"+unused-ignore-comment = "error"+[tool.ruff]include = ["dspy/**/*.py", "tests/**/*.py"]exclude = [diff --git a/tests/typing/asyncify.py b/tests/typing/asyncify.pynew file mode 100644index 000000000..e301b087c--- /dev/null+++ b/tests/typing/asyncify.py@@ -0,0 +1,25 @@+"""Static contracts, checked by ty rather than executed by pytest.++Unused-ignore errors make the deliberately invalid calls fail if type safety is lost.+"""++import asyncio++from typing_extensions import assert_type++from dspy import asyncify+++def format_count(count: int, /, *, prefix: str) -> str:+ return f"{prefix}: {count}"+++async def check_asyncify() -> None:+ wrapped = asyncify(format_count)+ assert_type(await wrapped(3, prefix="count"), str)+ assert_type(await asyncio.create_task(wrapped(3, prefix="count")), str)++ await wrapped("three", prefix="count") # ty: ignore[invalid-argument-type]+ await wrapped(3) # ty: ignore[missing-argument]+ await wrapped(3, "count", prefix="count") # ty: ignore[too-many-positional-arguments]+ await wrapped(count=3, prefix="count") # ty: ignore[positional-only-parameter-as-kwarg]diff --git a/uv.lock b/uv.lockindex 70df8afae..06594e364 100644--- a/uv.lock+++ b/uv.lock@@ -3,7 +3,8 @@ revision = 3requires-python = ">=3.10, <3.16"resolution-markers = ["python_full_version >= '3.15' and sys_platform != 'win32'",- "python_full_version >= '3.14' and sys_platform == 'win32'",+ "python_full_version >= '3.15' and sys_platform == 'win32'",+ "python_full_version == '3.14.*' and sys_platform == 'win32'","python_full_version == '3.14.*' and sys_platform == 'emscripten'","python_full_version == '3.14.*' and sys_platform != 'emscripten' and sys_platform != 'win32'","python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'win32'",@@ -939,6 +940,7 @@ dev = [{ name = "pytest-mock" },{ name = "pytest-xdist" },{ name = "ruff" },+ { name = "ty" },]langchain = [{ name = "langchain-core" },@@ -1022,6 +1024,7 @@ requires-dist = [{ name = "ruff", marker = "extra == 'dev'", specifier = ">=0.3.0" },{ name = "tenacity", specifier = ">=8.2.3" },{ name = "tqdm", specifier = ">=4.66.1" },+ { name = "ty", marker = "extra == 'dev'", specifier = "==0.0.89" },{ name = "weaviate-client", marker = "extra == 'weaviate'", specifier = ">=4.5.4,<4.22.0" },]provides-extras = ["anthropic", "weaviate", "mcp", "deno", "langchain", "optuna", "numpy", "litellm", "dev", "test-extras"]@@ -2615,7 +2618,8 @@ version = "2.5.2"source = { registry = "https://pypi.org/simple" }resolution-markers = ["python_full_version >= '3.15' and sys_platform != 'win32'",- "python_full_version >= '3.14' and sys_platform == 'win32'",+ "python_full_version >= '3.15' and sys_platform == 'win32'",+ "python_full_version == '3.14.*' and sys_platform == 'win32'","python_full_version == '3.14.*' and sys_platform == 'emscripten'","python_full_version == '3.14.*' and sys_platform != 'emscripten' and sys_platform != 'win32'","python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'win32'",@@ -2890,7 +2894,8 @@ version = "3.0.5"source = { registry = "https://pypi.org/simple" }resolution-markers = ["python_full_version >= '3.15' and sys_platform != 'win32'",- "python_full_version >= '3.14' and sys_platform == 'win32'",+ "python_full_version >= '3.15' and sys_platform == 'win32'",+ "python_full_version == '3.14.*' and sys_platform == 'win32'","python_full_version == '3.14.*' and sys_platform == 'emscripten'","python_full_version == '3.14.*' and sys_platform != 'emscripten' and sys_platform != 'win32'","python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'win32'",@@ -3336,7 +3341,8 @@ version = "26.0.0"source = { registry = "https://pypi.org/simple" }resolution-markers = ["python_full_version >= '3.15' and sys_platform != 'win32'",- "python_full_version >= '3.14' and sys_platform == 'win32'",+ "python_full_version >= '3.15' and sys_platform == 'win32'",+ "python_full_version == '3.14.*' and sys_platform == 'win32'","python_full_version == '3.14.*' and sys_platform == 'emscripten'","python_full_version == '3.14.*' and sys_platform != 'emscripten' and sys_platform != 'win32'","python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'win32'",@@ -4231,7 +4237,8 @@ version = "2026.6.3"source = { registry = "https://pypi.org/simple" }resolution-markers = ["python_full_version >= '3.15' and sys_platform != 'win32'",- "python_full_version >= '3.14' and sys_platform == 'win32'",+ "python_full_version >= '3.15' and sys_platform == 'win32'",+ "python_full_version == '3.14.*' and sys_platform == 'win32'","python_full_version == '3.14.*' and sys_platform == 'emscripten'","python_full_version == '3.14.*' and sys_platform != 'emscripten' and sys_platform != 'win32'","python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'win32'",@@ -4691,6 +4698,31 @@ wheels = [{ url = "https://files.pythonhosted.org/packages/f9/1c/01bfd571a64e7f270e6bab5e33777debe0edc56759233ce84f27dec92d14/tqdm-4.70.0-py3-none-any.whl", hash = "sha256:7f585706bfddbdebf89daac705b2dfcc16890130727d3197ca62c732b4310953", size = 80184, upload-time = "2026-07-27T11:33:13.167Z" },]+[[package]]+name = "ty"+version = "0.0.89"+source = { registry = "https://pypi.org/simple" }+sdist = { url = "https://files.pythonhosted.org/packages/67/ea/dfb9bdbc168c50a568809466596751afa0c7da60da03b8c12906d1decde4/ty-0.0.89.tar.gz", hash = "sha256:bc1027b1ea95cca25c2a3a0b41433c809cf4b86a384d2b2434eba4bcd34548d4", size = 7978241, upload-time = "2026-10-16T10:35:05.249Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/c5/84/e199d9a3dc3c94c804ddd9e94b63dbe543ae7f39329574963b6a6a95872f/ty-0.0.89-py3-none-linux_armv6l.whl", hash = "sha256:739b087e8873e177ffda99ff8a3600a4a7704d06523a8e88c4493021eee40b8a", size = 14254879, upload-time = "2026-10-16T10:34:24.813Z" },+ { url = "https://files.pythonhosted.org/packages/e5/d5/5afe09bf5c83c4e3a9e5913386a460e240a7029f2ae5fc96df5b43563a91/ty-0.0.89-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:47ebc98480c8a301955e18a8bdd67ef07090071ad47349b3254f325d3d5ab4e7", size = 13790417, upload-time = "2026-10-16T10:34:27.672Z" },+ { url = "https://files.pythonhosted.org/packages/7e/f9/88648f0ba9400dfd642c1e8dc0aeecb87945b121f3ff51f3902883c016d6/ty-0.0.89-py3-none-macosx_11_0_arm64.whl", hash = "sha256:b0631291af5c850a15007c0ffb906d813966466e4ec12173c44977c0c5a2d51d", size = 12856900, upload-time = "2026-10-16T10:34:29.871Z" },+ { url = "https://files.pythonhosted.org/packages/6a/89/baae2b407101c4cb02f19216123900c147af8fd87cdb1ed7eba139472734/ty-0.0.89-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3d768300ae16274ce656006e9199869ad68684b74400d963e1c82deddf3a22ad", size = 13653330, upload-time = "2026-10-16T10:34:32.296Z" },+ { url = "https://files.pythonhosted.org/packages/ed/1d/293516c2e10a77134cfc40d22c3fc08edd8c5eadae9c75531ec8a9263348/ty-0.0.89-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3dd4c57ba58bab8f6c816b2c254db52b58834b5dbf8268287382f7a2f9735c8f", size = 13986215, upload-time = "2026-10-16T10:34:34.506Z" },+ { url = "https://files.pythonhosted.org/packages/2f/c3/da911c8fc22d2664692432570619576b25c7cd0a586401cab08987763094/ty-0.0.89-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1af774c24117d366b69142d4f35edee518617f8b926d13560d0334cbe5aa3f85", size = 14905008, upload-time = "2026-10-16T10:34:36.632Z" },+ { url = "https://files.pythonhosted.org/packages/5c/c3/aed8d920b9bbf7b582e9fc0305acb2f2c748ede788e7dba9d6952e939c78/ty-0.0.89-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a8147811b9b3bc2dc9338cd01c7893ac931fc3fae7aace169047ecbd627e6628", size = 15278217, upload-time = "2026-10-16T10:34:39.144Z" },+ { url = "https://files.pythonhosted.org/packages/96/92/c6b4320f08fca44ffe279e5ddeb3eae12869c6341f596931accdefea1182/ty-0.0.89-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:6d5f178c91d50fb62461b5e579028b7d2e92872e1d8f02e96ace26464c2277a6", size = 15206289, upload-time = "2026-10-16T10:34:41.626Z" },+ { url = "https://files.pythonhosted.org/packages/3e/61/da22c714fd4f4dff642d60fb0d8bf8da1985d126f21cc89237f8bf707c92/ty-0.0.89-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:95a410f10b26cc3861757b626727db9d979deba7d2a3ab59f964fac8f0514fdc", size = 14510395, upload-time = "2026-10-16T10:34:44.063Z" },+ { url = "https://files.pythonhosted.org/packages/f0/32/5f9ce2377a77ad9ff36d8996edf86b1f069c1e8716e37c7d6d668402b110/ty-0.0.89-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:a70ab1a402746d7837407dc169e461fdf90945bc1eef0d3c0f1be543490060bf", size = 14767366, upload-time = "2026-10-16T10:34:46.154Z" },+ { url = "https://files.pythonhosted.org/packages/63/72/2b28c71d6ebd97b5bb1378f1806598c5dd90278f7b99a431dd3879dddcfc/ty-0.0.89-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:b55c28a49bd2676eac9b3540a1dcc4cc053e4671c65dcec9fdad3dfe55fb148c", size = 13670284, upload-time = "2026-10-16T10:34:48.225Z" },+ { url = "https://files.pythonhosted.org/packages/34/cc/68b8ebf98c9bc582fddc3d2b93f6e0f53719d1ddee1c5037dfa2e1cb8467/ty-0.0.89-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:4c9f22edeb8176f8ab189337e8cbd8f92b66744534a2886df9e252b52ade991c", size = 13997891, upload-time = "2026-10-16T10:34:50.556Z" },+ { url = "https://files.pythonhosted.org/packages/cf/4d/a1d61e06092fd5726f48a8711bd32eac6af132308eb222a0027caba4f42d/ty-0.0.89-py3-none-musllinux_1_2_i686.whl", hash = "sha256:0c186185cad57a1469b851096b51345de7b625e353c1f4acd338402daed22fa7", size = 14326247, upload-time = "2026-10-16T10:34:53.005Z" },+ { url = "https://files.pythonhosted.org/packages/f8/d2/466d3762e330504a2c114dbbd0f0383229f9652dccd56277dde008bfe0da/ty-0.0.89-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:5e38302ac218d2404758241093b5542ed0345d4f569096589f1810034244e998", size = 14661527, upload-time = "2026-10-16T10:34:55.555Z" },+ { url = "https://files.pythonhosted.org/packages/b1/d5/dfd7ed5e4af472b20a11ef651da4bca55f9dc8be485cd152337f94caddde/ty-0.0.89-py3-none-win32.whl", hash = "sha256:0146637ed2321717280bfe4e4b20a18813b741da280e8039d7df2bf22b0251f1", size = 13224078, upload-time = "2026-10-16T10:34:57.735Z" },+ { url = "https://files.pythonhosted.org/packages/b4/14/1ee663c422e3a2d910c5cc27e7d84bd7709a3df0aca28a713843c6c3fa5d/ty-0.0.89-py3-none-win_amd64.whl", hash = "sha256:9fc56322a1aff29a19088d2025f3c42a6d25a7035668048bb908c9f8b66f480d", size = 13727433, upload-time = "2026-10-16T10:35:00.15Z" },+ { url = "https://files.pythonhosted.org/packages/09/93/af8f7250920823ca6d582bcf0abf803fb92c8b99415ba7f40f2304102c6f/ty-0.0.89-py3-none-win_arm64.whl", hash = "sha256:1d4967c8f7bfd67c9708115b41d7049197c5d20c76fb2e136fe78b0437ada05b", size = 13287101, upload-time = "2026-10-16T10:35:02.918Z" },+]+[[package]]name = "typeguard"version = "4.6.0"