---

name: generative-programming description: "Use Mellea 0.8.0.dev0 to build typed, composable generative programs with sessions, contexts, validation repair, asynchronous thunks, streaming, and legacy MObjects." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Generative programming

Use this route when the task mentions a typed LLM function, structured output, @generative, a generative stub, start_session, MelleaSession, context, validation retry, lazy computation, streaming, mify, or legacy integration. This route covers the execution layer; it does not choose a provider, configure credentials, design tool policies, or run evaluations.

Read the smallest useful reference

• Public classes, signatures, return contracts, and imports: api-reference.md.
• End-to-end recipes and sync/async/streaming decisions: workflows.md.
• Typed schemas, formatter output, thunks, and validation results: data-and-output.md.
• Symptoms, likely causes, and recovery actions: troubleshooting.md.

Choose the operating level

1. Prefer @generative for a named, reusable function with stable typed inputs and outputs.
2. Prefer MelleaSession.instruct() for a dynamic prompt, grounding context, user variables, requirements, or format=....
3. Prefer chat() only for unvalidated conversational turns. Use ChatContext when history must persist; the default SimpleContext isolates calls.
4. Use act()/aact() when you already have an explicit Component such as Instruction, SimpleComponent, Message, a generative stub, or an MObject.
5. Use stream() only when partial output and early per-chunk validation are requirements. For ordinary incremental output, use ModelOption.STREAM and a single reader of the returned thunk.

Provider/model construction belongs to the sibling backends-and-models route. Tool definitions, tool execution, ReAct loops, and safety policy belong to tools-and-agents. Sampling presets and evaluator/LLM-judge workflows belong to sampling-and-evaluation.

Minimal typed program

from pydantic import BaseModel
from mellea import generative, start_session

class Person(BaseModel):
    name: str
    age: int

@generative
def extract_person(text: str) -> Person:
    """Extract the person's name and age from the text."""
    ...

with start_session() as m:
    person = extract_person(m, text="Alice is 31 years old.")
assert isinstance(person, Person)

The decorated function body is a declaration. The function name, signature, docstring, annotations, and keyword arguments become the generation contract. The session is the first call argument; original function arguments should be passed by keyword. An async decorated function returns an awaitable parsed result.

Required checkpoints

• Before generation: choose the context policy, validate untrusted inputs with precondition_requirements where applicable, and verify the provider route has the required optional dependency/service.
• At the output boundary: use Pydantic/Literal annotations for shape; use requirements and deterministic simple_validate functions for semantic constraints; do not confuse a schema-valid value with a task-correct value.
• On repair: provide a SamplingStrategy, normally RejectionSamplingStrategy(loop_budget=N), whenever requirements must be evaluated and retried. Set return_sampling_results=True when fallback or per-attempt diagnostics matter.
• Before concurrency: use SimpleContext for independent concurrent calls; with ChatContext, await one call fully before starting the next.
• Before streaming: select one consumer per thunk, use async with around iterators, and decide whether a final full-output validation or per-chunk stream() validation is needed.

Context and lifecycle quick choice

from mellea import start_session
from mellea.stdlib.context import ChatContext

with start_session(ctx=ChatContext(window_size=10)) as m:
    m.chat("Remember that the project codename is Orion.")
    answer = m.chat("What is the codename?")
    print(str(answer))

start_session(...) returns a MelleaSession and can be used directly or as a context manager. The manager makes the session available to nested convenience code and performs cleanup. Use m.reset() to preserve backend configuration while clearing history, m.clone() to branch a conversation, and m.ctx.last_output()/m.ctx.last_turn() for inspection.

Composition and legacy surface

Compose typed functions with ordinary Python, passing one parsed result into the next. Use Instruction for a full prompt component, SimpleComponent(**parts) for named ad-hoc spans, Message for chat turns, and m.act(component) when a component must be executed explicitly. @generative is the canonical name; mellea.stdlib.components.genslot is a deprecated compatibility shim whose slot aliases should be migrated to genstub.

Use @mify or mify(obj, ...) to expose selected fields and documented methods of an existing object. Then use m.query(obj, question) or m.transform(obj, instruction). Expose only the fields/functions needed by the model; direct Python methods remain preferable when no generation is needed.

Verification posture

Keep unit tests deterministic: assert types, schema fields, allowed Literal values, validator reasons, context isolation, thunk state, and exact option forwarding. Mark model-quality assertions as qualitative. Use a fake or dummy backend for API/control-flow tests; never make a real model call merely to test routing, parsing, or retry bookkeeping. For a safe installed-package signature check, run:

cd sub-skills/generative-programming
python scripts/inspect_api.py --help
python scripts/inspect_api.py

If the task crosses into backend setup, tool execution, sampling/evaluation, or serving, hand off rather than duplicating those routes.