Examples

Complete working programs demonstrating Mellea patterns in production-like scenarios.

Each example in this section is a complete, runnable Python program. The pages walk through the code section by section so you can see how the pieces fit together. Copy any example as a starting point for your own project.

Examples in this section

Example	What it shows
Data extraction pipeline	Use @generative with a typed return to pull structured data from unstructured text
Legacy code integration	Apply @mify to existing Python classes so the model can act on them
Resilient RAG with fallback	Build a FAISS retrieval pipeline with an LLM relevance filter before generation
Traced generation loop	Enable OpenTelemetry application and backend traces with two environment variables

All example categories

The repository contains many more runnable examples than the four documented above. Every category has its own README.md and one or more .py files ready to run.

Core concepts

Category	What it shows
instruct_validate_repair/	The IVR loop end-to-end: basic generation, adding requirements, automatic repair on failure, custom validators
generative_stubs/	@generative functions with typed returns, pipeline composition, ChatContext persona injection, pre/postcondition checks
context/	Context inspection, sampling with context trees, parallel context branches
sessions/	Custom session types and backend selection
async/	How to utilize basic async capabilities
streaming/	stream_with_chunking() with per-chunk validation, typed event vocabulary, early-exit on fail

Data and documents

Category	What it shows
information_extraction/	Named entity recognition and type-safe structured extraction with Pydantic
mobject/	Table queries and transformations using MObject structured data types
mify/	@mify on existing classes — custom string representations, field filtering, funcs_include
rag/	FAISS vector search, @generative bool relevance filter, grounding_context for grounded generation

Agents and tools

Category	What it shows
agents/	ReACT reasoning-and-acting loop, multi-turn tool workflows
tools/	@tool definition, code interpreter integration, tool argument validation, safe eval patterns
mini_researcher/	Complete research assistant: multi-model architecture, document retrieval, safety checks, custom validation pipeline

Extensibility

Category	What it shows
plugins/	Plugin system end-to-end: function hooks, class-based plugins, payload modification, scoped and session-scoped plugins, PluginSet composition, execution modes, tool hooks, and testing patterns

Safety and validation

Category	What it shows
intrinsics/	Guardian Intrinsics: guardian_check() for harm, jailbreak, social bias, groundedness; policy_guardrails(); factuality_detection() / factuality_correction()
safety/	(Examples removed — see Guardian how-to guide for the current API. The RepairTemplateStrategy gap is tracked in #1071.)

Integration and deployment

Category	What it shows
m_serve/	Deploying Mellea programs as REST APIs with production deployment patterns
m_decompose/	Decomposing complex prompts into sub-tasks via the CLI and Python API
library_interop/	LangChain message conversion, OpenAI format compatibility, cross-library workflows
mcp/	MCP tool creation, Claude Desktop integration, Langflow integration
bedrock/	Amazon Bedrock backend configuration and usage

Performance and advanced sampling

Category	What it shows
aLora/	Training aLoRA adapters for fast constraint checking; performance optimisation
intrinsics/	(Non-Guardian) Answer relevance, hallucination detection, citation validation, context relevance — specialised adapter-backed checks. For Guardian safety functions see Safety and validation above
granite-switch/	Running intrinsics via OpenAI backend with Granite Switch embedded adapters
sofai/	Two-tier sampling: fast-model iteration with escalation to a slow model; cost optimisation

Multimodal

Category	What it shows
image_text_models/	Vision-language models, ImageBlock, multimodal prompting, backend support matrix

Observability

Category	What it shows
telemetry/	OpenTelemetry application and backend traces; span export configuration

Experimental

Category	What it shows
melp/	⚠️ Experimental lazy evaluation — thunks, deferred execution, advanced control flow

Getting started and tutorials

Category	What it shows
hello_world.py	Minimal single-file starting point
tutorial/	Python script versions of the tutorials: email generation, IVR, generative stubs, contexts, MObjects, model options, and more
notebooks/	Jupyter notebook versions of the same tutorials for interactive, cell-by-cell exploration

---

Running the examples

All examples are in the docs/examples/ directory of the repository. Unless otherwise noted, run them with:

python docs/examples/<folder>/<file>.py

Some examples declare inline script dependencies using the PEP 723 /// script block and can be run with uv run instead:

uv run docs/examples/<folder>/<file>.py

Default backend: start_session() with no arguments connects to a local Ollama instance running IBM Granite 4 Micro (granite4.1:3b). Make sure Ollama is running before you execute any example.