type stubs for some third-party libraries

[lars20070]

Problem

The codebase previously relied on # type: ignore and # pyright: ignore comments to suppress type errors from third-party libraries lacking type hints (llama_cpp, mlx, mlx_lm, outlines, transformers, and vllm).

• Reduced code clarity: Type ignore comments obscure the intended types, making it harder to understand the expected interfaces
• Maintenance burden: Suppressed type errors can hide real issues when APIs change
• Failed type checking: In the Linux dev container, make typecheck failed due to missing type information from mlx and vllm. Both dependencies are absent in the Linux dev container.

Solution

This PR introduces type stub files .pyi for these libraries. Type stubs provide type information to static type checkers without modifying the runtime behavior.

• Created stub files mirroring the original library APIs (only type annotations, no functional code)
• Type information sourced from upstream library implementations. For example, SamplingParams from vllm.
• Stubbed only the APIs actively used in the codebase to minimize maintenance overhead. Alternatively, I can add automation with a uv run stubgen target in Makefile. But this generates all stubs and not merely the ones used in the codebase. More thoughts here.
• make typecheck now passes successfully in the Linux dev container

Added

• New stubs/ directory containing type stub files for llama_cpp, mlx, mlx_lm, outlines, transformers and vllm.
• Updated pyproject.toml to configure stub search paths for pyright and mypy

Changed

• The Apple Silicon dependency condition for outlines-mlxlm has been updated in both pyproject.toml files.
• The uv.lock file has been updated to reflect these dependency changes.

Removed

• # pyright: ignore and # type: ignore comments from outlines.py and test_outlines.py.

[DouweM]

@lars20070 Thanks Lars, this is great.

[DouweM]

Can we call it type_stubs or something like that to make it more clear what it's about?

[lars20070]

There is no PEP rule demanding a ./stubs folder. But PEP 484 is linking to typeshed which is using ./stubs. So are mypy and the Microsoft's stubs collection. On the other hand, Pyright goes with ./typings.

The name ./stubs is not required, but a convention. I have explained the folder in the corresponding README. It's like renaming the src folder to source. Yes, possible. But why do it?

[DouweM]

These will inevitably get outdated -- could you add some docs (can just be a readme in this dir) on how you generated them, how we can validate they're still valid, and how to regenerate/update them?

[lars20070]

@DouweM I have added a README to the ./stubs folder.

Either update any API changes manually from the source code, or give Copilot access to a Context7 MCP server and let the coding agent do the updates.

[lars20070]

FYI, the rebase introduced new outlines code. I have added the necessary stubs.

[lars20070]

@DouweM I have added validation of the stubs here.