Mellea: typed Python functions as LLM calls, with requirements and retries

The failure Mellea is aimed at: the LLM call in the middle of a pipeline

The README states the problem in one line: inside every AI-powered pipeline, the unreliable part is the same, the LLM call itself. The listed symptoms are silent failures, untestable outputs and no guarantees. That framing tells you who the library is for. It is for engineers who already have a working pipeline and a known output contract, and who are tired of writing parsers and ad hoc retry loops around a call that returns prose. It is not aimed at people exploring what a model can do. The example in the README makes the target concrete: a UserProfile model with name and age, and a function that extracts both from a log line. The comment next to the age print says it is always an int, guaranteed by the schema. That guarantee, not the prompt, is the product.

How @generative turns a function signature into a schema

The mechanism visible in the README is short. You import generative and start_session from mellea, define a Pydantic BaseModel, and decorate a typed function with @generative. The docstring becomes the prompt. The type hints become the schema. The README claims there are no templates and no parsers in the loop. When you call the decorated function you pass the session object first, then the keyword arguments, so extract_user(m, text="...") returns a UserProfile instance rather than a string. Pydantic enforcement happens at generation time according to the feature list, which is a stronger claim than validating after the fact: the library is described as constraining generation, not repairing a bad string afterwards. start_session() is the convenience entry point and returns a MelleaSession with defaults you can override. That session object is the seam where backend choice, requirements and sampling strategy attach, which is why it is threaded through every call rather than created implicitly.

Requirements, repair and sampling: what happens on a bad generation

Structured output alone would be a thin wrapper over any JSON-mode API. The second layer is the one that changes behaviour. The README says you can attach natural-language requirements to any call, and that Mellea validates and retries automatically. This is the Instruct-Validate-Repair pattern named in the examples directory, and it is the part with real cost implications: every failed validation is another generation, so a strict requirement set multiplies token spend and latency in a way a plain schema check does not. Sampling strategies sit alongside it. You can run a generation multiple times and pick the best result, and the README says you swap between rejection sampling, majority voting and more with one parameter change. The honest reading is that Mellea does not make the model more reliable. It makes the unreliability explicit and gives you a place to put the policy: how many attempts, which requirement failed, which sample wins. If you do not want to pay for retries, the requirements feature is the part to leave alone.

Backends, mify and MCP: the integration surface

The README lists Ollama, OpenAI, HuggingFace, WatsonX, LiteLLM and Bedrock as supported backends. That spread matters because it means the same generative program can be pointed at a local Ollama model during development and a hosted endpoint in production without rewriting the function. The trade-off is that backend behaviour is not uniform: schema enforcement quality depends on what the underlying model and API actually support, and the README does not say how Mellea handles a backend that cannot constrain decoding. Treat that as something to verify per backend rather than assume. Two further integration points are named. mify is described as a way to drop Mellea into existing codebases, which is the migration path for teams that cannot restructure their call sites. MCP compatibility means any generative program can be exposed as an MCP tool, so a typed function becomes callable by an agent host without a separate wrapper. Both are claims from the feature list; the docs are the place to check the actual signatures.

Getting it running

Installation is a single command, and the README uses uv rather than pip: uv pip install mellea. There is an extras path for pulling everything in, quoted in the README as uv pip install 'mellea[all]', with the installation docs covering the individual options. Source installation is deferred to CONTRIBUTING.md. The minimal program from the README imports generative and start_session, defines the Pydantic model, decorates the function, calls start_session() with no arguments to get defaults, and then calls the decorated function with the session as the first positional argument. The only config key the README names is that session: backend selection, requirements and sampling strategy are all described as things you override on the MelleaSession rather than as module-level settings or environment variables. The repo also ships Colab notebooks under docs/examples/notebooks/ and runnable examples under docs/examples/ covering RAG, agents, Instruct-Validate-Repair and MObjects, which is the fastest way to see the session configuration in practice without reading the API reference first.

Where Mellea is the wrong tool

Two cases stand out. The first is open-ended generation. If the useful output is a paragraph, a design sketch or a conversation turn, there is no schema to enforce and no requirement that a validator can check cheaply. Wrapping that in @generative adds a Pydantic model you will immediately unwrap, and the retry loop has nothing meaningful to reject on. The second is latency-sensitive paths with tight budgets. Automatic retries on failed requirements mean the worst-case cost of a call is the best-case cost multiplied by the attempt count, and the README does not state a default cap. Anything user-facing and synchronous needs that number pinned down before it ships. There is also a maturity caveat that the release history makes plain: 0.5.0 on 2026-05-05, 0.6.0 on 2026-05-19, 0.7.0 on 2026-07-13. Three minor releases in about ten weeks is a fast-moving surface, and the README does not carry a stability or deprecation policy. Pinning the version is not optional here.

The alternative: plain Pydantic parsing over a raw client

The obvious comparison is a hand-rolled stack: call the provider SDK directly, pass a JSON schema through the API's structured-output parameter, and validate the response with Pydantic. That gives you the same type guarantee and nothing else. The difference in approach is where the policy lives. In the hand-rolled version, the retry loop, the validation rules and the prompt text sit in your application code, usually scattered across call sites, and the prompt is a string you assemble. In Mellea, the docstring is the prompt, the type hints are the schema, and requirements are attached to the call as first-class objects that the library validates and retries against. If your validation rules are already expressed as code and your prompts are already templates you maintain deliberately, the hand-rolled path is less machinery. Mellea earns its place when the same validate-and-retry shape repeats across many calls and you want one place to change it. The README also positions Mellea against flaky agents generally, but it names no specific agent framework for comparison, so treat that as positioning rather than a benchmark.

Licence, maintenance and what to check before adopting

Mellea is Apache-2.0, copyright 2026 Mellea, and the README notes it was started by IBM Research in Cambridge, MA. Apache-2.0 is permissive and includes an explicit patent grant, which is usually what matters for a library you embed in a commercial product. That is a description of the licence text, not legal advice; if you are redistributing or modifying it, read the LICENSE file and your own counsel's view. On maintenance, the signals available are the release cadence and the fact that the repository is not archived, with a last push in September 2026. The README points contributors at CONTRIBUTING.md, a building-extensions guide on the docs site, and a separate mellea-contribs repository for shared components. That structure suggests the maintainers expect the core to stay small and extensions to live elsewhere, which is good for upgrade cost if you build against the documented extension points and bad if you reach into internals. Before adopting, verify which backend you will run and how it handles schema enforcement, what the retry cap actually is, and whether mify covers the call sites you cannot rewrite.

Editorial conclusion

Adopt Mellea if your pipeline already knows the shape of the answer and you want the schema and the retry policy expressed in Python types rather than in prompt text. Do not adopt it if your task is open-ended generation where no schema exists, or if you need a stable API today, since 0.5.0, 0.6.0 and 0.7.0 all landed inside roughly two months. Before committing, verify three things against the docs at docs.mellea.ai: which backend you will actually run against, how requirements are attached and counted on retry, and whether mify can wrap the existing call sites you do not want to rewrite.

Official sources

1. generative-computing/mellea on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases