fix(stdlib): resolve postponed annotations in generative stub signature

[planetf1]

Pull Request

Issue

Fixes #1503

Description

Under from __future__ import annotations (PEP 563 postponed annotations), @generative stub signatures were corrupted before being sent to the model.

• describe_function() used inspect.signature(func), which renders postponed annotations as literal strings — (product_description: str) -> list[Requirement] became (product_description: 'str') -> 'list[Requirement]' in the prompt.
• get_argument() had the same issue at the parameter level: param.annotation was the string "str" rather than the type str, so the param_type is str check failed and string arguments were rendered unquoted (value: Alice instead of value: "Alice").

Both are fixed by passing eval_str=True to inspect.signature(), which resolves the annotation strings back to real types — the same resolution create_response_format() already gets for free via typing.get_type_hints().

Why eval_str=True is safe here: any annotation that would raise under eval_str=True (e.g. TYPE_CHECKING-only imports, forward references to not-yet-defined classes) already raises the identical NameError from the pre-existing get_type_hints(func) call in create_response_format(), which every @generative-decorated function goes through at decoration time. So this cannot break any function that could previously be decorated with @generative — it only changes which of two co-located calls raises first.

The two other inspect.signature(func) call sites in this file (bind_function_arguments() and GenerativeStub.__init__'s disallowed-param-name check) are deliberately left unchanged — neither inspects .annotation, so PEP 563 doesn't affect them, and adding eval_str there would only add a failure mode for no benefit.

Follow-ups (out of scope here):

• mellea/backends/tools.py's convert_function_to_ollama_tool has the same root-cause bug for tool-schema generation from annotated functions — filed as convert_function_to_ollama_tool breaks under from __future__ import annotations (PEP 563) #1507, fixed in fix(backends): resolve postponed annotations in ollama tool schema #1509.
• No test currently exercises the full @generative → prompt-template chain under PEP 563 (the new tests call describe_function/get_argument directly); worth adding later.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Added test/stdlib/components/_pep563_fixtures.py, a fixture module with from __future__ import annotations (isolated in its own file since the import is a module-level directive), and two regression tests in test/stdlib/components/test_genstub_unit.py — each with a precondition guard on __annotations__ so they can't pass vacuously if PEP 563 is later dropped from the fixture module.

uv run python -m pytest test/stdlib/components/test_genstub_unit.py -v — 33 passed. uv run ruff format --check, uv run ruff check, uv run mypy — all clean on the three changed files.

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.