Skip to content

armgit / dspy

Public Imported from GitHub
0

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.yml
index 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 check
test:
name: Run Tests
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 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-hooks
rev: v5.0.0
hooks:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 any
formatting 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 Request
Once 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.py
index 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 configuration
global_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.py
index 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, cast
from 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 a
program 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_overrides
parent_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_overrides
original_overrides = thread_local_overrides.get()
diff --git a/dspy/utils/usage_tracker.py b/dspy/utils/usage_tracker.py
index dcc72e637..e99f08600 100644
--- a/dspy/utils/usage_tracker.py
+++ b/dspy/utils/usage_tracker.py
@@ -2,7 +2,7 @@
from collections import defaultdict
from contextlib import contextmanager
-from typing import Any, Generator
+from typing import Any, Generator, TypeGuard
from pydantic import BaseModel
@@ -12,7 +12,7 @@ from dspy.dsp.utils.settings import settings
class 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_tracker
with settings.context(usage_tracker=tracker):
try:
yield tracker
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
new file mode 100644
index 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.lock
index 70df8afae..06594e364 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3,7 +3,8 @@ revision = 3
requires-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"