feat(thunk+types): add .parsed property and wire format= overloads for cast-free structured output

[planetf1]

Fixes #1273. Fixes #1274.

The problem

Getting a typed Pydantic instance from a format= call required two error-prone manual steps:

result = m.act(Instruction("Classify sentiment"), format=Sentiment)

# Step 1 — re-name the model (type and format= can silently drift apart):
parsed = Sentiment.model_validate_json(str(result))

# Step 2 — if result hasn't been awaited, str(result) is "" and this raises a
# confusing ValidationError with no hint that the thunk was uncomputed.
print(parsed.label)

The return type was ModelOutputThunk[Any] — no narrowing, no safety net.

What this PR delivers

result = m.act(Instruction("Classify sentiment"), format=Sentiment)
#        ^^^^ now typed ComputedModelOutputThunk[Sentiment]

label = result.parsed.label   # typed Sentiment | None — runtime-safe, no cast needed

Two things had to land together to make this work end-to-end:

1. .parsed property (ComputedModelOutputThunk) — validates self.value via model_validate_json against the format type that was used at generation time. Returns S | None. Only lives on ComputedModelOutputThunk, so it can't be called on an uncomputed thunk.

2. format= overloads in act / aact / instruct / ainstruct (both session.py and functional.py) — when format: type[BaseModelSubclass] is passed, the return type narrows to ComputedModelOutputThunk[BaseModelSubclass]. The narrowing is observable on .parsed (typed S | None) and parsed_repr (also S | None); .value stays str unconditionally.

Together: m.act(action, format=MyModel).parsed is typed MyModel | None and runtime-correct, with no cast at the call site.

Why these two PRs were collapsed

These were originally two separate PRs (#1282 for .parsed, #1284 for the overloads). Neither was useful alone:

• feat(thunk): add .parsed property to ComputedModelOutputThunk for structured output #1282 alone — .parsed exists at runtime but is typed str | None at every call site because the overloads don't yet bind S. Callers still need a cast.
• feat(thunk+types): add .parsed property and wire format= overloads for cast-free structured output #1284 alone — m.act(format=MyModel) narrows to ComputedModelOutputThunk[MyModel], but there is no .parsed to use that narrowing. Callers fall back to cast(MyModel, result.value), which raises AttributeError at runtime.

@jakelorocco flagged this during review. Both halves are here now.

Implementation notes

All five built-in backends set _format on the thunk in post_processing. Custom backends must set mot._format there too; the .parsed docstring has an explicit Note: for backend authors.

Downstream wrappers that forward a dynamic format value keep a # type: ignore[assignment] with inline rationale (the clean fix is branching on format is None; react.py and the m_serve example both have explanatory comments).

The parsed_repr attribute also narrows statically to S | None via the overloads, but has a runtime gap for the Instruction path: Instruction._parse currently ignores _format and returns str. Use .parsed for structured output — it is both statically typed and runtime-safe. The root cause is tracked in #1313.

Compatibility

• .value is unchanged — existing callers are unaffected.
• .parsed is new; nothing today relies on it.
• The overloads are type-only — no runtime behaviour changes.

Testing

• Unit tests: happy path, None fallback, invalid JSON, value unchanged, copy/deepcopy _format preservation
• E2E qualitative tests: test_parsed_returns_pydantic_instance for HuggingFace and Ollama backends
• Static assert_type checks in test/typing/ covering all four methods, the computed/uncomputed branches, and attribute-level narrowing of parsed_repr and .parsed

Test plan

• uv run pytest test/core/test_base.py -k parsed
• uv run pytest test/core/ test/typing/ -m "not qualitative"
• uv run pytest test/backends/test_ollama.py -k parsed -m qualitative (requires Ollama)
• uv run pytest test/backends/test_huggingface.py -k parsed -m qualitative (requires GPU)

[jakelorocco]

I read #1282 before this one. I think this encounters the same issue. We need to resolve disparate typing issues, decide what we want to have decide the output type of a mot, and then propagate the actual type to the model output thunk so that users can actually utilize it without casting / overriding / asserting a type.

[planetf1]

@markstur @AngeloDanducci @jakelorocco @ajbozarth — this PR has been open for 2 days with no reviews yet. Happy to answer questions or discuss the approach.

[ajbozarth]

Some feedback from Claude — follow-ups inline.

Headline concern: the overloads narrow the result generic to MyModel, but at runtime no attribute on the resulting thunk is actually a MyModel instance for an Instruction(format=MyModel) call — so the type promise the PR makes can't be cashed in without a cast on the unwrap, which is exactly the footgun #1274 was trying to remove. Details inline.

[ajbozarth]

The PR description's before/after says:

result, _ = act(action, ctx, backend, format=MyModel)
obj = result.value  # typed as MyModel

Under these overloads result does narrow to ComputedModelOutputThunk[MyModel], but ComputedModelOutputThunk.value is annotated -> str (mellea/core/base.py:875) — it doesn't depend on S. So result.value is still typed as str, and the only attribute the new S = MyModel actually narrows is parsed_repr: S | None.

But parsed_repr's runtime path is self._action._parse(self) (mellea/core/base.py:707), and Instruction._parse returns computed.value if computed.value is not None else "" (mellea/stdlib/components/instruction.py:236) — i.e., str, regardless of format=. So for the canonical m.act(Instruction(...), format=MyModel) pattern, result.parsed_repr is typed MyModel | None but is actually a str at runtime. pyright will accept result.parsed_repr.some_field, and it'll AttributeError at runtime — the exact silent-failure shape #1273 / #1274 were filed against, just relocated from .value to .parsed_repr.

The genstub path (where _parse calls model_validate_json) is the one place this narrowing is actually honored at runtime — and the PR has to # type: ignore the genstub return values anyway. So the PR ships a typed promise that's only kept for the one component type that already had a working unwrap.

Worth resolving with #1282's author before merge: a coherent end-state probably looks like making ComputedModelOutputThunk.parsed generic over S and returning S (so result.parsed: MyModel), backed by a runtime path that actually delivers a MyModel instance for Instruction(format=...). As-is, this PR removes the cast from the .value line at the cost of inviting one on .parsed_repr that the type system hides. Net safety is debatable.

[planetf1]

You're right — parsed_repr has the same runtime gap, just relocated. Looking into the best fix before this merges.

[planetf1]

The runtime gap is real — parsed_repr routes through Instruction._parse which always returns str, so the narrowing is a lie at runtime. The fix is in #1282, which adds a .parsed property backed by model_validate_json. Once that merges, the story is clean:

result = session.act(action, ctx, backend, format=MyModel)
obj = result.parsed  # MyModel | None — typed and runtime-correct, no cast

I'll retarget the overloads here to .parsed after #1282 is merged. Moving this to draft until then.

[planetf1]

Now resolved in this PR. The collapse of #1282 into this branch means .parsed is available right here — it's backed by model_validate_json so it's both statically typed S | None and runtime-correct. Updated in 72b0e66e:

• The session.py overload comment now names all three attributes and explicitly directs callers to .parsed (typed + runtime-safe) rather than parsed_repr (typed but runtime gap via Instruction._parse → str).
• check_session.py now asserts assert_type(r.parsed, _M | None) at the call site, confirming the end-to-end narrowing holds.

parsed_repr's runtime gap for the Instruction path remains — fixing that requires changing _parse to be format-aware, which is a wider change left for a follow-up. The important thing is callers now have a clear, correct path via .parsed.

[planetf1]

Filed #1313 to track the parsed_repr runtime gap for the Instruction path and explain why it wasn't fixed here. The issue covers the root cause (Instruction._parse ignores _format), why a proper fix needs Instruction to become generic, and that .parsed is the correct workaround in the meantime.

[planetf1]

@ajbozarth @jakelorocco lots of changes on this as I merged the two previously independent PRs. It's easier to see the objective and result in a single PR - so hope this is clearer

[jakelorocco]

I talked with Nathan about this. We want to maintain the existing behavior; which I'm assuming we don't have clearly documented and which lead to this issue/PR.

• format can determine the shape of the output (ie what tokens are allowed, etc...)
• a component can declare the shape of the object generated from it (ie a Message components declares that it will result in another Message)

These two are usually related (and we should maybe make it easier to express this so that if a component requires a specific schema to parse, you don't have to pass re-define / pass in separate format var). But a component can also declare arbitrary parsing rules that can operate on several formats.

If you want automatic typing on the output of the mot, you should pass in a specific component. Otherwise, you'll have to model_validate the output to get the type from the raw string.

[planetf1]

Thanks Jake. act() returns a JSON string, which is what the backend produces — that's the intended behaviour. The real problems are:

1. The docs imply otherwise. act-and-aact.md currently has print(result.value) # A Planet instance — which tells users .value gives them a model instance. It doesn't.

2. Getting it right first time is harder than it should be. Without .parsed, the correct pattern is MyModel.model_validate_json(result.value) — easy to miss, easy to get wrong, and not obvious from the API.

Three options:

A — keep .parsed, drop the overloads: .parsed stays as a convenience accessor that calls model_validate_json for you. No type inference from format=; the docs get corrected. Easier to use correctly.

B — A plus docs update: Same, plus update the structured-output guide with the recommended pattern end-to-end.

C — docs only: Fix the misleading comment and document the correct model_validate_json pattern explicitly. .parsed is dropped entirely.

Either way, the goal is that writing a Mellea app with structured output works correctly without surprises. What fits best?

[jakelorocco]

@planetf1; lets do Option C (docs only fix) for now please.

[planetf1]

@planetf1; lets do Option C (docs only fix) for now please.

Ok will start on that approach

[planetf1]

This PR has been superseded by the docs-only approach agreed with @jakelorocco (Option C).

Clean replacement: #1333 — same issues addressed, no code changes.

Closing this one.