build: migrate type checker from mypy to pyright (strict)

Author: nikolay-e

.pre-commit-config.yaml

@@ -55,19 +55,25 @@ repos:
   # ============================================================================
   # STATIC TYPING
   # ============================================================================
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.408
     hooks:
-      - id: mypy
-        name: mypy (strict mode)
+      - id: pyright
+        name: pyright (strict mode)
+        pass_filenames: false
         additional_dependencies:
-          - types-PyYAML
-          - types-aiofiles
-          - types-colorama
-          - pytest
-          - pytest-asyncio
+          - litellm
+          - pyyaml
+          - colorama
+          - httpx
+          - tiktoken
+          - aiofiles
+          - scikit-learn
+          - markdown-it-py
+          - google-auth
           - pydantic
-        files: ^src/
+          - python-dotenv
+          - aiohttp
 
   # ============================================================================
   # LINT + FORMAT (Ruff: replaces flake8, isort, pyupgrade, and black)

CONTRIBUTING.md

@@ -73,7 +73,7 @@ Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
 |--------|---------|
 | `make dev` | Install dev dependencies + pre-commit hooks |
 | `make fmt` | Format + autofix code (`ruff format` + `ruff check --fix`) |
-| `make lint` | Lint + format check + type check (ruff, mypy) |
+| `make lint` | Lint + format check + type check (ruff, pyright) |
 | `make test` | Run tests with coverage |
 | `make test-quick` | Run tests without coverage |
 | `make clean` | Remove build artifacts |
@@ -106,7 +106,7 @@ We do not use docstrings or inline comments explaining "what" the code does. Ins
 
 ### Type Safety
 
-- All code must pass `mypy --strict`
+- All code must pass `pyright` in strict mode
 - Use proper type annotations on all public functions
 - Avoid `Any` unless absolutely necessary
 

Makefile

@@ -19,7 +19,7 @@ lint:  ## Run all linters
 	python scripts/lint_structure.py
 	ruff check $(PY_SOURCES)
 	ruff format --check $(PY_SOURCES)
-	mypy src/
+	pyright src/
 
 test:  ## Run tests with coverage
 	@echo "Running tests..."

pyproject.toml

@@ -51,10 +51,7 @@ dev = [
     "hypothesis~=6.0",
     "coverage[toml]~=7.13",
     "ruff>=0.15.10,<1.0",
-    "mypy>=1.11,<3.0",
-    "types-colorama~=0.4",
-    "types-PyYAML~=6.0",
-    "types-aiofiles~=25.1",
+    "pyright>=1.1.408",
     "pre-commit~=4.5",
     "mutmut~=3.5",
     "radon~=6.0",
@@ -190,39 +187,21 @@ quote-style = "double"
 indent-style = "space"
 line-ending = "lf"
 
-[tool.mypy]
-strict = true
-warn_unreachable = true
-warn_redundant_casts = true
-warn_unused_ignores = false
-disallow_any_generics = true
-disallow_untyped_defs = true
-disallow_incomplete_defs = true
-check_untyped_defs = true
-no_implicit_optional = true
-files = ["src/"]
-exclude = ["tests/", "^docs/", "^benchmarks/"]
-
-[[tool.mypy.overrides]]
-module = [
-    "litellm", "litellm.*",
-    "sklearn", "sklearn.*",
-    "markdown_it", "markdown_it.*",
-    "httpx", "httpx.*",
-    "dotenv", "dotenv.*",
-    "yaml", "yaml.*",
-    "colorama", "colorama.*",
-    "pydantic", "pydantic.*",
-    "bcrypt", "bcrypt.*",
-    "jwt", "jwt.*",
-    "psycopg2", "psycopg2.*",
-]
-ignore_missing_imports = true
-disable_error_code = ["attr-defined"]
-
-[[tool.mypy.overrides]]
-module = "certamen.infrastructure.config.models"
-disable_error_code = ["misc"]
+[tool.pyright]
+include = ["src"]
+exclude = ["**/__pycache__", "tests", "docs", "benchmarks", "build", "dist"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+# Untyped third-party libs (litellm, sklearn, bcrypt, jwt, psycopg2) ship no
+# stubs. The prior mypy config treated them as Any via ignore_missing_imports;
+# silencing the Unknown-type reports keeps that stance so strict checking still
+# applies fully to our own annotated code without drowning in external noise.
+reportMissingTypeStubs = "none"
+reportMissingModuleSource = "none"
+reportUnknownMemberType = "none"
+reportUnknownVariableType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownLambdaType = "none"
 
 # Mutation testing configuration
 # Evidence: Mutation score correlates with real fault detection

src/certamen/application/bootstrap.py

@@ -1,8 +1,9 @@
+import importlib
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 # Import providers to trigger registration at bootstrap time
-import certamen.infrastructure.llm.providers  # noqa: F401
+importlib.import_module("certamen.infrastructure.llm.providers")
 
 if TYPE_CHECKING:
     from certamen.engine import Certamen
@@ -235,10 +236,8 @@ async def build_certamen(
                 f"Invalid configuration provided. Missing or invalid sections:\n  - {error_details}\n\n"
                 f"Required sections: models, retry, features, prompts, outputs_dir"
             )
-    elif isinstance(config, Config):
-        config_obj = config
     else:
-        raise TypeError(f"Unsupported config type: {type(config)}")
+        config_obj = config
 
     config_data = config_obj.config_data
 

src/certamen/application/workflow/nodes/__init__.py

@@ -5,31 +5,27 @@
     PortType,
 )
 
+_NODE_MODULES = (
+    "disagreement",
+    "evaluation",
+    "flow",
+    "generation",
+    "input",
+    "interrogation",
+    "knowledge",
+    "llm",
+    "output",
+    "synthesis",
+)
+
 
 def register_all() -> None:
-    import certamen.application.workflow.nodes.disagreement
-    import certamen.application.workflow.nodes.evaluation
-    import certamen.application.workflow.nodes.flow
-    import certamen.application.workflow.nodes.generation
-    import certamen.application.workflow.nodes.input
-    import certamen.application.workflow.nodes.interrogation
-    import certamen.application.workflow.nodes.knowledge
-    import certamen.application.workflow.nodes.llm
-    import certamen.application.workflow.nodes.output
-    import certamen.application.workflow.nodes.synthesis
+    import importlib
 
-    del (
-        certamen.application.workflow.nodes.disagreement,
-        certamen.application.workflow.nodes.evaluation,
-        certamen.application.workflow.nodes.flow,
-        certamen.application.workflow.nodes.generation,
-        certamen.application.workflow.nodes.input,
-        certamen.application.workflow.nodes.interrogation,
-        certamen.application.workflow.nodes.knowledge,
-        certamen.application.workflow.nodes.llm,
-        certamen.application.workflow.nodes.output,
-        certamen.application.workflow.nodes.synthesis,
-    )
+    for module_name in _NODE_MODULES:
+        importlib.import_module(
+            f"certamen.application.workflow.nodes.{module_name}"
+        )
 
 
 __all__ = ["BaseNode", "ExecutionContext", "Port", "PortType", "register_all"]

src/certamen/application/workflow/registry.py

@@ -20,6 +20,9 @@ def register(self, node_class: type[BaseNode]) -> type[BaseNode]:
     def get(self, node_type: str) -> type[BaseNode] | None:
         return self._nodes.get(node_type)
 
+    def node_types(self) -> list[str]:
+        return list(self._nodes.keys())
+
     def create(
         self,
         node_type: str,

src/certamen/application/workflow/schema.py

@@ -4,11 +4,11 @@
 
 
 def list_node_types() -> list[str]:
-    return sorted(registry._nodes.keys())
+    return sorted(registry.node_types())
 
 
 def get_node_schema(node_type: str) -> dict[str, Any] | None:
-    node_class = registry._nodes.get(node_type)
+    node_class = registry.get(node_type)
     if not node_class:
         return None
 

src/certamen/infrastructure/llm/litellm_adapter.py

@@ -304,15 +304,17 @@ async def _execute_completion(
         prompt_tokens = 0
         completion_tokens = 0
         total_tokens = 0
-        if hasattr(response, "usage") and response.usage:
-            prompt_tokens = getattr(response.usage, "prompt_tokens", 0)
-            completion_tokens = getattr(response.usage, "completion_tokens", 0)
-            total_tokens = getattr(response.usage, "total_tokens", 0)
+        usage = getattr(response, "usage", None)
+        if usage:
+            prompt_tokens = getattr(usage, "prompt_tokens", 0)
+            completion_tokens = getattr(usage, "completion_tokens", 0)
+            total_tokens = getattr(usage, "total_tokens", 0)
 
         # Extract rate limit headers if available
         rate_limit_info = ""
-        if hasattr(response, "_hidden_params"):
-            headers = getattr(response._hidden_params, "headers", {})
+        hidden_params = getattr(response, "_hidden_params", None)
+        if hidden_params is not None:
+            headers = getattr(hidden_params, "headers", {})
             if headers:
                 rate_limit_headers = {
                     k: v

src/certamen/infrastructure/llm/retry.py

@@ -60,12 +60,9 @@ def _get_backoff_multiplier(error_type: str, provider: str) -> float:
         provider_mult = multiplier_value.get(
             provider, multiplier_value["default"]
         )
-        return float(provider_mult) if provider_mult is not None else 1.5
+        return float(provider_mult)
 
-    if isinstance(multiplier_value, (int, float)):
-        return float(multiplier_value)
-
-    return 1.5
+    return float(multiplier_value)
 
 
 def _get_jitter_range(error_type: str, provider: str) -> float: