docs(core): document _generate_from_context uncomputed-thunk contract

[ajbozarth]

Pull Request

Issue

Fixes #1229

Description

Documents the implementer contract for Backend._generate_from_context: the returned ModelOutputThunk is expected to be uncomputed and resolved through astream, which is where the generation_post_call hook fires.

#1229 reported that generation_post_call never fires when a backend returns an already-computed thunk. The root cause is an asymmetry: generation_pre_call fires in the public generate_from_context wrapper, but generation_post_call fires later in astream. A pre-computed thunk short-circuits avalue() and never enters astream, so it gets the pre-call but not the post-call.

The issue's proposed fix (also fire post_call from generate_from_context when is_computed()) goes against the intent of _generate_from_context, which is meant to return an uncomputed thunk wired to async generation. Enforcing that with a hard raise was considered and rejected: lightweight test/smoke backends legitimately return pre-computed thunks and do not depend on the hook, so a raise would break them to enforce a rule that production backends already follow.

This change records the contract where backend authors will see it (the abstract method they override), without altering behavior.

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)

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.

[ajbozarth]

@jakelorocco per our discussion earlier I tried inserting raising error block but it just broke all our tests that manually mock the MOTs. So instead I decided that based on our conversation just documenting the contract on the docstring was "good enough"

Since this is small I'll just mark it merge when ready, feel free to approve anytime