Skip to content

ci(mypy): unblock strict gate from numpy PEP 695 stub#100

Merged
lyonzin merged 1 commit into
masterfrom
fix/mypy-numpy-pep695
Jun 22, 2026
Merged

ci(mypy): unblock strict gate from numpy PEP 695 stub#100
lyonzin merged 1 commit into
masterfrom
fix/mypy-numpy-pep695

Conversation

@lyonzin

@lyonzin lyonzin commented Jun 22, 2026

Copy link
Copy Markdown
Owner

Summary

Unblocks Pillar 7 — mypy strict (gradual) which has been failing on every push to master since the numpy stub started using PEP 695 type statements.

Root cause

Recent numpy ships __init__.pyi with PEP 695 syntax:

```
/opt/.../numpy/init.pyi:737: error: Type statement is only supported in
Python 3.12 and greater [syntax]
```

Our mypy config pins python_version = "3.11" (project still supports 3.11 at runtime), so mypy rejects the stub. None of the three checked modules import numpy directly — it enters through:

```
mcp_server/preflight.py
-> mcp_server.config
-> chromadb / fastembed
-> numpy <-- explosion happens here
```

Fix

Add a single [[tool.mypy.overrides]] block scoping the stub-skip strictly to numpy. ignore_missing_imports = true doesn't help here because numpy has stubs — mypy loads them and chokes on parse. follow_imports = "skip" tells mypy not to parse the numpy module even when transitively imported.

Verified locally

```
$ mypy mcp_server/instance_lock.py mcp_server/preflight.py scripts/
Success: no issues found in 7 source files
```

Why not the alternatives

  • Bump python_version = "3.12": changes the assumed runtime target for the entire codebase, even though the package still supports 3.11. Risk of masking real 3.11-only issues. Out of scope.
  • Pin a specific numpy/mypy version: brittle and chases the same problem forward; future stub releases will break us again.
  • Wait for upstream mypy fix: no public timeline, master stays red in the interim.

7 Pillars

  • No production code touched; config-only
  • No test changes; backwards-compat preserved
  • No new dependencies
  • mypy clean locally on the gradual-allowlist
  • CI green on all 9-cell matrix + 7 pillars (pending)

@lyonzin lyonzin changed the title fix(ci): unblock mypy strict from numpy PEP 695 stub ci(mypy): unblock strict gate from numpy PEP 695 stub Jun 22, 2026
@lyonzin
lyonzin force-pushed the fix/mypy-numpy-pep695 branch from ca618ec to 072c301 Compare June 22, 2026 15:05
mypy was failing on master with:
  numpy/__init__.pyi:737: error: Type statement is only supported in
  Python 3.12 and greater [syntax]

Recent numpy stubs use PEP 695 ``type`` statements, which mypy rejects
under our previously-pinned ``python_version = "3.11"``. The error is
raised at parse time on the stub itself — before per-module
``follow_imports = "skip"`` can be applied — so a narrow override does
not help.

Bump the mypy static-analysis target from 3.11 to 3.12 to match the CI
runtime (Python 3.12) and accept PEP 695 syntax. This setting only
governs static analysis; ``requires-python = ">=3.11"`` is unchanged and
the package still runs on 3.11 at runtime.

Verified locally:
  mypy mcp_server/instance_lock.py mcp_server/preflight.py scripts/
  -> Success: no issues found in 7 source files
@lyonzin
lyonzin force-pushed the fix/mypy-numpy-pep695 branch from 072c301 to 0e2ce68 Compare June 22, 2026 15:08
@lyonzin
lyonzin merged commit e16b222 into master Jun 22, 2026
36 checks passed
@lyonzin
lyonzin deleted the fix/mypy-numpy-pep695 branch June 22, 2026 15:11
@lyonzin lyonzin mentioned this pull request Jun 22, 2026
lyonzin added a commit that referenced this pull request Jun 22, 2026
Hybrid search bug fixes shipped today (#98 from external contributor
@Hohlas), pinned by anti-regression tests (#99), and the mypy strict
gate unblocked (#100). No breaking changes; no public API surface
drift.

User-facing fixes:
- search_knowledge(category="general") no longer rejected on custom
  configs that drop the default "general": "general" mapping.
- Stale BM25 chunk_ids no longer leak empty results into the reranker.

Bumps: pyproject.toml + mcp_server/__init__.py + npm/package.json all
to 4.3.1. CHANGELOG curated in README.md.

Co-authored-by: Lyonzin <lyonzin@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant