fix(types): make ComputedModelOutputThunk.parsed generic over the format type

`.parsed` previously returned `pydantic.BaseModel | None`, so callers still
needed `cast(MyModel, result.parsed)` for static narrowing — the gap
@ajbozarth flagged on PR generative-computing#1282.

Thread the format type through the thunk's existing type parameter `S`:
`_format` is now `type[S] | None` and `.parsed` returns `S | None`. Reusing
`S` (rather than a second TypeVar) composes with the companion `format=`
overloads on generative-computing#1274, which bind `S` to the supplied model so
`m.act(action, format=MyModel)` yields `ComputedModelOutputThunk[MyModel]`
and `.parsed` is typed `MyModel | None`.

The `.parsed` body narrows `_format` to a pydantic type to call
`model_validate_json`, then re-asserts the result as `S` — `S` is unbounded
(it is `str` for plain instructions) so neither cast can be elided.

Add `test/typing/check_parsed.py` asserting `.parsed` tracks the type
parameter for both a model-parameterized and a `str` thunk.

Assisted-by: Claude Code

Author: planetf1

mellea/core/base.py

@@ -29,6 +29,7 @@
     ParamSpec,
     Protocol,
     TypeVar,
+    cast,
     runtime_checkable,
 )
 
@@ -402,7 +403,7 @@ def __init__(
         # Mellea-side hook correlation ID; distinct from the provider-assigned
         # `GenerationMetadata.response_id`.
         self._generation_id: str | None = None
-        self._format: type[pydantic.BaseModel] | None = None
+        self._format: type[S] | None = None
 
     def _record_ttfb(self) -> None:
         """Record time-to-first-byte if streaming and not yet recorded."""
@@ -893,15 +894,18 @@ def value(self, v: str):
         self._underlying_value = v
 
     @property
-    def parsed(self) -> pydantic.BaseModel | None:
+    def parsed(self) -> S | None:
         """Returns the result as a validated Pydantic instance when ``format=`` was set.
 
-        Returns ``None`` when no ``format=`` type was provided to the originating
-        ``act()`` / ``instruct()`` call.  Use this instead of casting ``.value``
+        The return type tracks the format type supplied at the originating call
+        site: ``m.act(action, format=MyModel)`` yields a
+        ``ComputedModelOutputThunk[MyModel]`` whose ``.parsed`` is typed
+        ``MyModel | None`` — no ``cast()`` required. Returns ``None`` when no
+        ``format=`` type was provided.  Use this instead of casting ``.value``
         manually::
 
             result = m.act(Instruction("Say yes or no"), format=MyModel)
-            obj = result.parsed  # no manual model_validate_json needed
+            obj = result.parsed  # typed MyModel | None, no model_validate_json needed
 
         Note:
             This property relies on the originating backend storing the format
@@ -911,16 +915,20 @@ def parsed(self) -> pydantic.BaseModel | None:
             ``format=`` was supplied.
 
         Returns:
-            A ``pydantic.BaseModel`` instance produced by ``model_validate_json``,
-            or ``None`` if no format type was set.
+            An instance of the format type (``S``) produced by
+            ``model_validate_json``, or ``None`` if no format type was set.
 
         Raises:
             pydantic.ValidationError: If the raw JSON value does not conform to
                 the format model (e.g. the model returned malformed structured output).
         """
         if self._format is None:
             return None
-        return self._format.model_validate_json(self.value)
+        # `_format` is a pydantic model type in every code path that sets it (the
+        # `format=` overloads bind `S` to that model), but `S` itself is unbounded,
+        # so we narrow to call `model_validate_json` and re-assert the result as `S`.
+        fmt = cast("type[pydantic.BaseModel]", self._format)
+        return cast("S", fmt.model_validate_json(self.value))
 
     def is_computed(self) -> Literal[True]:
         """Returns `True` since thunk is always computed.

test/typing/check_parsed.py

@@ -0,0 +1,28 @@
+"""Mypy checks that `ComputedModelOutputThunk.parsed` tracks the type parameter.
+
+`.parsed` is typed `S | None`, so a thunk parameterized with a Pydantic model
+(`ComputedModelOutputThunk[MyModel]`) exposes `.parsed` as `MyModel | None` —
+callers need no `cast()`. The `format=` overloads in `session.py` /
+`functional.py` bind `S` to the format model (companion issue #1274), at which
+point these checks hold end-to-end from the call site.
+"""
+
+from typing import assert_type, cast
+
+import pydantic
+
+from mellea.core import ComputedModelOutputThunk
+
+
+class _Person(pydantic.BaseModel):
+    name: str
+
+
+def check_parsed_tracks_format_model() -> None:
+    thunk = cast(ComputedModelOutputThunk[_Person], None)
+    assert_type(thunk.parsed, _Person | None)
+
+
+def check_parsed_is_str_for_str_thunk() -> None:
+    thunk = cast(ComputedModelOutputThunk[str], None)
+    assert_type(thunk.parsed, str | None)