Mellea — build predictable AI without guesswork
Inside every AI-powered pipeline, the unreliable part is the same: the LLM call itself. Silent failures, untestable outputs, no guarantees. Mellea is a Python library for writing generative programs — replacing brittle prompts and flaky agents with structured, testable AI workflows built around type-annotated outputs, verifiable requirements, and automatic retries.
Install
uv pip install mellea
See installation docs for additional options, such as installing all extras via uv pip install 'mellea[all]'.
For source installation directly from this repo, see CONTRIBUTING.md.
Example
The @generative decorator turns a typed Python function into a structured LLM call.
Docstrings become prompts, type hints become schemas — no templates, no parsers:
from pydantic import BaseModel
from mellea import generative, start_session
class UserProfile(BaseModel):
name: str
age: int
@generative
def extract_user(text: str) -> UserProfile:
"""Extract the user's name and age from the text."""
m = start_session()
user = extract_user(m, text="User log 42: Alice is 31 years old.")
print(user.name) # Alice
print(user.age) # 31 — always an int, guaranteed by the schema
start_session() is the convenience entry point: it returns a MelleaSession
with sensible defaults you can override as needed.
What Mellea Does
- Structured output —
@generativeturns typed functions into LLM calls; Pydantic schemas are enforced at generation time - Requirements & repair — attach natural-language requirements to any call; Mellea validates and retries automatically
- Sampling strategies — run a generation multiple times and pick the best result; swap between rejection sampling, majority voting, and more with one parameter change
- Multiple backends — Ollama, OpenAI, HuggingFace, WatsonX, LiteLLM, Bedrock
- Legacy integration — easily drop Mellea into existing codebases with
mify - MCP compatible — expose any generative program as an MCP tool
Learn More
| Resource | Description |
|---|---|
| docs.mellea.ai | Full docs — vision, tutorials, API reference, how-to guides |
| Colab notebooks | Interactive examples you can run immediately |
| Code examples | Runnable examples: RAG, agents, Instruct-Validate-Repair (IVR), MObjects, and more |
Contributing
We welcome contributions of all kinds — bug fixes, new backends, standard library components, examples, and docs.
- Contributing Guide — development setup, workflow, and coding standards
- Building Extensions — create reusable components in your own repo
- mellea-contribs — community library for shared components
Questions? See GitHub Discussions.
IBM ❤️ Open Source AI
Mellea was started by IBM Research in Cambridge, MA.
Licensed under the Apache-2.0 License. Copyright © 2026 Mellea.
3 maintainers
Release files for mellea 0.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mellea-0.8.0.tar.gz | 676.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mellea-0.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / mellea-0.8.0.tar.gz
| Download URL | mellea-0.8.0.tar.gz |
|---|---|
| Size | 676.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ffce4a18adfd7f0985c942d98cfff826f12c2564d7d1f3a643f2245dbaf9149a
|
|
BLAKE2b-256 checksum How to use checksums |
8d950af95584600a11b9755fb7bb0983ba7f188e430c81a459b8204c74d5ffd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / mellea-0.8.0-py3-none-any.whl
| Download URL | mellea-0.8.0-py3-none-any.whl |
|---|---|
| Size | 863.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d8fc50a4563e1bbeb4bf7a2561b52310055e75aa47f2fbb0b250c150d94d0357
|
|
BLAKE2b-256 checksum How to use checksums |
af597e024174c3408b97cea8d014458811570c9231c47b3ddf9a0185a814ed88
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
