Mellea IBM Research Workspace — Testable Generative Programs and Agentic Workflows

This repository is my IBM/Mellea research workspace for building structured, testable LLM workflows with IBM Research's open-source Mellea generative-programming library.

Note: this is my experimental workspace built on top of Mellea. The upstream open-source Mellea project is maintained separately by IBM Research / generative-computing.

Why this repo exists

Traditional LLM agents often fail silently: brittle prompts, untyped outputs, weak validation, and no reliable way to test intermediate behavior. Mellea approaches this through generative programming: typed functions, verifiable requirements, automatic retries, and structured LLM calls.

This repo explores how those ideas can be used for:

• ReAct-style agents
• evaluator loops
• structured LLM programs
• MCP/tool demonstrations
• validation and repair workflows
• reproducible agent experiments

My focus

My work here is focused on turning prompt-heavy agent workflows into more maintainable programs.

Area	What this repo demonstrates
Generative programs	Type-annotated functions with LLM-filled outputs
Validation	Requirement checks before accepting model output
Agent workflows	ReAct-style reasoning and tool-use demos
MCP integration	Exposing Mellea tools through MCP demos
Debugging	Tutorial notebooks for step-by-step inspection
Research use	Patterns useful for evaluator-driven agent systems

Repository contents

mellea-IBM/
├── mellea_complete_tutorial.ipynb
├── demo_interactive.ipynb
├── demo_agent.py
├── demo_mcp.py
├── AGENTS.md
└── README.md

Update this tree after cleanup if files differ.

Quick start

1. Create an environment

python -m venv .venv
source .venv/bin/activate

2. Install dependencies

uv pip install "mellea[all]"

[all] includes extras for document processing, HuggingFace support, and MCP demos.

3. Run the tutorial notebook

uv run jupyter notebook mellea_complete_tutorial.ipynb

4. Run the ReAct-style agent demo

uv run python demo_agent.py

5. Run the MCP demo

uv run mcp dev demo_mcp.py

Key experiments

1. Complete tutorial notebook

A walk-through of Mellea primitives:

• basic chat/instruction calls
• generative functions
• typed outputs
• requirement-driven validation
• debugging and inspection
• composing reusable LLM workflows

2. ReAct agent demo

A standalone agent example showing how structured Mellea calls can be used inside reasoning/action loops.

3. MCP demo

A minimal demo for exposing Mellea-backed tools through MCP and inspecting them externally.

Connection to my IBM research work

This workspace supports my broader IBM research direction around LLM-driven algorithm evolution and agentic evaluator loops, where models propose, mutate, judge, and validate candidate algorithms.

The same reliability problems appear in both settings:

• candidate outputs need structure
• evaluator behavior needs validation
• prompt-only systems are hard to debug
• agent steps need traceability
• repeated experiments need reproducible artifacts

Mellea-style generative programming provides a useful foundation for these workflows.

What to add next

To make this repo stronger for reviewers and ATS scorers, add:

• screenshots of notebook output
• one short demo GIF
• exact experiment logs
• a docs/ page explaining each demo
• a comparison table: raw prompting vs Mellea validation
• links to upstream Mellea docs and IBM Research blog
• your own feature list, not only upstream Mellea features

Status

Experimental research workspace. The repo is intended to show practical usage patterns and agent experiments built around Mellea, not to replace the upstream Mellea project.

Author

Arush Sharma