### Local Documentation Preview Setup

Source: https://github.com/generative-computing/mellea/blob/main/docs/CONTRIBUTING_DOCS.md

Steps to set up a local preview of the documentation site. Includes installing dependencies and starting the development server.

```bash
cd docs
npm ci       # first time only
npm run start
# Site available at http://localhost:3000

```

--------------------------------

### Start Multimodal Image Example Server

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/m_serve/README.md

Command to start the Mellea server for the multimodal image example.

```bash
m serve docs/examples/m_serve/m_serve_example_multimodal_image.py
```

--------------------------------

### Start Streaming Example Server

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/m_serve/README.md

Command to start the Mellea server for the streaming example.

```bash
m serve docs/examples/m_serve/m_serve_example_streaming.py
```

--------------------------------

### Start Sampling Example Server

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/m_serve/README.md

Command to start the Mellea server for the simple sampling example.

```bash
m serve docs/examples/m_serve/m_serve_example_simple.py
```

--------------------------------

### Start Response Format Example Server

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/m_serve/README.md

Command to start the Mellea server for the response format example.

```bash
m serve docs/examples/m_serve/m_serve_example_response_format.py
```

--------------------------------

### Install Ollama and Setup Display

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/simple_email.ipynb

Installs Ollama, starts the server, and sets up custom CSS for displaying pre-formatted text in Colab. This is a prerequisite for using Mellea with Ollama.

```python
!curl -fsSL https://ollama.com/install.sh | sh > /dev/null
!nohup ollama serve >/dev/null 2>&1 &

from IPython.display import HTML, display


def set_css():
    display(HTML(
"""
<style>
 pre{
 white-space: pre-wrap;
}
</style>
""",
))


get_ipython().events.register("pre_run_cell", set_css)
```

--------------------------------

### Setup Mellea Environment

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/aLora/README.md

Clones the Mellea repository, sets up a virtual environment, installs dependencies, and navigates to the aLoRA example directory.

```bash
git clone github.com/generative-computing/mellea);
cd mellea;
uv venv .venv;
source .venv/bin/activate;
uv pip install -e .[all];
pushd docs/examples/aLora/;
```

--------------------------------

### Install and Start Jupyter Notebook

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/README.md

Installs Jupyter using uv pip and starts the Jupyter Notebook server in the specified directory. Alternatively, JupyterLab can be launched.

```bash
# Install Jupyter if needed
uv pip install jupyter

# Start Jupyter
jupyter notebook docs/examples/notebooks/

# Or use JupyterLab
jupyter lab docs/examples/notebooks/
```

--------------------------------

### OTLP Collector Setup Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/observability/metrics.md

Example configuration for an OpenTelemetry Collector to receive OTLP metrics and export them to Prometheus and debug.

```bash
cat > otel-collector-config.yaml <<EOF
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889
  debug:
    verbosity: detailed

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus, debug]
EOF

docker run -p 4317:4317 -p 8889:8889 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest
```

--------------------------------

### Mellea OpenTelemetry Example Setup

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/examples/traced-generation-loop.md

Provides the full Python script for demonstrating Mellea's OpenTelemetry tracing. Includes setup instructions for enabling tracing, exporting to OTLP, and console output.

```python
# pytest: ollama, e2e

"""Example demonstrating OpenTelemetry tracing in Mellea.

This example shows the two trace scopes populated when tracing is enabled:
1. Application trace - tracks user-facing operations
2. Backend trace - tracks LLM backend interactions

Run with different configurations:

# Enable tracing
export MELLEA_TRACES_ENABLED=true
python telemetry_example.py

# Export to OTLP endpoint (e.g., Jaeger)
export MELLEA_TRACES_ENABLED=true
export MELLEA_TRACES_OTLP=true
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
python telemetry_example.py

# Enable console output for debugging
export MELLEA_TRACES_ENABLED=true
export MELLEA_TRACES_CONSOLE=true
python telemetry_example.py
"""

from mellea import generative, start_session
from mellea.stdlib.requirements import req
from mellea.telemetry import is_tracing_enabled


@generative
def classify_sentiment(text: str) -> str:
    """Classify the sentiment of the given text as positive, negative, or neutral."""


@generative
def extract_entities(text: str) -> list[str]:
    """Extract named entities from the text."""


def main():
    """Run example with telemetry instrumentation."""
    print("=" * 60)
    print("Mellea OpenTelemetry Example")
    print("=" * 60)

    print(f"Tracing enabled: {is_tracing_enabled()}")
    print("=" * 60)

    # Start a session - this will be traced if application tracing is enabled
    with start_session() as m:
        # Example 1: Simple instruction with requirements
        print("\n1. Simple instruction with requirements...")
        email = m.instruct(
            "Write a professional email to {{name}} about {{topic}}",
            requirements=[req("Must be formal"), req("Must be under 100 words")],
            user_variables={"name": "Alice", "topic": "project update"},
        )
        print(f"Generated email: {str(email)[:100]}...")

        # Example 2: Using @generative function
        print("\n2. Using @generative function...")
        sentiment = classify_sentiment(
            m, text="I absolutely love this product! It's amazing!"
        )
        print(f"Sentiment: {sentiment}")

        # Example 3: Multiple operations
        print("\n3. Multiple operations...")
        text = "Apple Inc. announced new products in Cupertino, California."
        entities = extract_entities(m, text=text)
        print(f"Entities: {entities}")

        # Example 4: Chat interaction
        print("\n4. Chat interaction...")
        response1 = m.chat("What is 2+2?")
        print(f"Response 1: {response1!s}")

        response2 = m.chat("Multiply that by 3")
        print(f"Response 2: {response2!s}")

    print("\n" + "=" * 60)
    print("Example complete!")
    print("=" * 60)
    print("\nTrace data has been exported based on your configuration.")
    print("If OTEL_EXPORTER_OTLP_TRACES_ENDPOINT is set, check your trace backend.")
    print("If MELLEA_TRACES_CONSOLE=true, traces are printed above.")


if __name__ == "__main__":
    main()
```

--------------------------------

### Install MCP SDK

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/mcp/README.md

Install the MCP SDK to enable Mellea as an MCP server. This is a prerequisite for running the poem server example.

```bash
uv pip install "mcp[cli]"
```

--------------------------------

### Full Example Pointer Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/CONTRIBUTING_DOCS.md

Shows how to link to a full, CI-tested example located in the `docs/examples/` directory. This provides users with access to complete, runnable code.

```text
> **Full example:** [`docs/examples/tutorial/simple_email.py`](https://github.com/generative-computing/mellea/blob/main/docs/examples/tutorial/simple_email.py)
```

--------------------------------

### Install Ollama and Configure Display

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/model_options_example.ipynb

Installs Ollama, starts it in the background, and sets up custom CSS for displaying preformatted text in Colab output.

```bash
!curl -fsSL https://ollama.com/install.sh | sh > /dev/null
!nohup ollama serve >/dev/null 2>&1 &
```

```python
from IPython.display import HTML, display

def set_css():
    display(HTML(
<style>
 pre{
 white-space: pre-wrap;
}
</style>
))

get_ipython().events.register("pre_run_cell", set_css)
```

--------------------------------

### Start WatsonX Session with start_session()

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/watsonx.md

Quickly start a Mellea session with the WatsonX backend using `start_session()`. Ensure `mellea[watsonx]` is installed. The model ID `ibm/granite-4-h-small` is used by default.

```python
# Requires: mellea[watsonx]
# Returns: str
from mellea import start_session

m = start_session(
    backend_name="watsonx",
    model_id="ibm/granite-4-h-small",
)
result = m.instruct("Summarise this document in three bullet points.")
print(str(result))
```

--------------------------------

### Install Ollama and Serve

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/compositionality_with_generative_stubs.ipynb

Installs Ollama using a curl script and starts the Ollama server in the background. It also registers a CSS style to ensure proper display of preformatted text in Colab.

```python
!curl -fsSL https://ollama.com/install.sh | sh > /dev/null
!nohup ollama serve >/dev/null 2>&1 &

from IPython.display import HTML, display


def set_css():
    display(HTML(
"""
<style>
 pre{
 white-space: pre-wrap;
}
</style>
"""
    ))


get_ipython().events.register("pre_run_cell", set_css)
```

--------------------------------

### Install Backend Dependencies

Source: https://github.com/generative-computing/mellea/blob/main/AGENTS.md

Install only the backend dependencies for Mellea using `uv`. This provides a lighter setup if all dependencies are not immediately needed.

```bash
uv sync --extra backends --all-groups
```

--------------------------------

### Start a default Mellea session

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/concepts/context-and-sessions.md

Use `start_session()` for the standard Mellea entry point. It's suitable for quick setup, when built-in backend selection is sufficient, or when configuring the model with basic parameters.

```python
from mellea import start_session

m = start_session()
result = m.instruct("Summarise this paragraph in one sentence.")
```

--------------------------------

### Setup OTLP Collector with Docker

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/observability/logging.md

This example demonstrates how to set up an OpenTelemetry collector using Docker. It configures receivers, exporters (debug and file), and service pipelines, then runs the collector with a custom configuration file.

```yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  debug:
    verbosity: detailed
  file:
    path: ./mellea-logs.json

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [debug, file]
```

```bash
docker run -p 4317:4317 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  -v $(pwd):/logs \
  otel/opentelemetry-collector:latest
```

--------------------------------

### Async Instruct Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/how-to/use-async-and-streaming.md

Demonstrates making an asynchronous instruction call using `ainstruct()` and printing the result. Ensure Mellea is installed and an Ollama server is running locally.

```python
# Requires: mellea
# Returns: None
import asyncio
import mellea

async def main():
    m = mellea.start_session()
    result = await m.ainstruct("Write a haiku about concurrency.")
    print(str(result))
    # Output will vary — LLM responses depend on model and temperature.

asyncio.run(main())
```

--------------------------------

### Install Mellea with Tools Support

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/mcp/README.md

Install Mellea with the necessary dependencies for tool support. This is required for the GitHub activity summary example, which consumes MCP server tools.

```bash
pip install 'mellea[tools]'
```

--------------------------------

### Installing Optional Mellea Dependencies

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/troubleshooting/common-errors.md

Install optional backend dependencies for Mellea using `pip install` with extras. Examples include HuggingFace, LiteLLM, WatsonX, tools, and telemetry.

```text
ImportError: The 'hf' backend requires extra dependencies.
Please install them with: pip install 'mellea[hf]'
```

```bash
pip install "mellea[hf]"         # HuggingFace / local inference
pip install "mellea[litellm]"    # LiteLLM multi-provider
pip install "mellea[watsonx]"    # IBM WatsonX
pip install "mellea[tools]"      # Tool / agent dependencies
pip install "mellea[telemetry]"  # OpenTelemetry tracing + metrics
```

--------------------------------

### Run Python Example with uv

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/README.md

Execute Python example scripts using the 'uv' command for faster execution.

```bash
uv run docs/examples/tutorial/simple_email.py
```

--------------------------------

### Install Ollama, Mellea, and Download Models

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/georgia_tech.ipynb

Installs ollama, downloads specified model weights, installs the Mellea library, and performs an initial Docling setup. Includes CSS for better display in Colab.

```python
# Install ollama.
!curl -fsSL https://ollama.com/install.sh | sh > /dev/null
!nohup ollama serve >/dev/null 2>&1 &

# Download the granite:3.3:8b weights.
!ollama pull granite4.1:3b
!ollama pull llama3.2:3b

# install Mellea.
!uv pip install "mellea[all]" -q

# Run docling once to download model weights.
from mellea.stdlib.components.docs.richdocument import RichDocument

RichDocument.from_document_file("https://mellea.ai")

# Some UI niceness.
from IPython.display import HTML, display  # noqa: E402


def set_css():
    display(HTML(
<style>
 pre{
 white-space: pre-wrap;
}
</style>
    ))


get_ipython().events.register("pre_run_cell", set_css)

```

--------------------------------

### Cross-linking Convention for Guide Pages

Source: https://github.com/generative-computing/mellea/blob/main/docs/CONTRIBUTING_DOCS.md

Example of how guide pages should link to the CLI Reference in their 'See also' footer, using relative paths.

```markdown
**See also:** [Other Page](../path/to-page) | [CLI Reference](../reference/cli)

```

--------------------------------

### Run Poem Server Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/mcp/README.md

Run the Mellea poem server example using the MCP debug UI. This command starts the server, making the Mellea instruct-validate-repair loop accessible as an MCP tool.

```bash
uv run mcp dev docs/examples/mcp/mcp_example.py
```

--------------------------------

### Run the Qiskit Code Validation Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/instruct_validate_repair/qiskit_code_validation/README.md

Execute the main Python script for the Qiskit code validation example. Dependencies are automatically installed.

```bash
uv run docs/examples/instruct_validate_repair/qiskit_code_validation/qiskit_code_validation.py
```

--------------------------------

### Start vLLM Server for Granite Switch Models

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/openai.md

Launch a vLLM server with a Granite Switch model, enabling intrinsic functions through an OpenAI-compatible API. Use the specified command-line arguments for optimal setup.

```bash
python -m vllm.entrypoints.openai.api_server \
    --model <granite-switch-model-id> \
    --dtype bfloat16 \
    --enable-prefix-caching
```

--------------------------------

### Run Python Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/README.md

Execute any Python example script using the standard Python interpreter.

```bash
python docs/examples/tutorial/simple_email.py
```

--------------------------------

### Start Mellea Session and Instruct

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/concepts/architecture-vs-agents.md

Initiates a Mellea session and uses the instruct method to get a response with specified requirements. Suitable for greenfield projects.

```python
import mellea

m = mellea.start_session()
result = m.instruct("Analyse customer feedback.", requirements=["..."])
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/community/contributing-guide.md

Install all project dependencies, including extras and all groups, using uv sync. Alternatively, install only backend dependencies.

```bash
# Install all dependencies (recommended for development)
uv sync --all-extras --all-groups

# Or install only backend dependencies
uv sync --extra backends --all-groups
```

--------------------------------

### Install Ollama, MCP, and Configure Display

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/mcp_example.ipynb

Installs Ollama, serves it in the background, installs the MCP package, and sets up CSS for better display of preformatted text in the environment.

```python
!curl -fsSL https://ollama.com/install.sh | sh > /dev/null
!nohup ollama serve >/dev/null 2>&1 &
!uv pip install mcp -q

from IPython.display import HTML, display


def set_css():
    display(HTML(
<style>
 pre{
 white-space: pre-wrap;
}
</style>
))


get_ipython().events.register("pre_run_cell", set_css)
```

--------------------------------

### Run Tracing Example (Enabled)

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/telemetry/README.md

Enables distributed tracing for the telemetry example.

```bash
export MELLEA_TRACES_ENABLED=true
python telemetry_example.py
```

--------------------------------

### Run Docusaurus Dev Server

Source: https://github.com/generative-computing/mellea/blob/main/docs/PUBLISHING.md

Starts the Docusaurus development server for local documentation preview. Run `npm ci` in the `docs` directory the first time to install dependencies.

```bash
cd docs && npm ci   # first time only
npm run start
# → http://localhost:3000
```

--------------------------------

### Install all Mellea extras

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/getting-started/installation.md

Install all available extras for Mellea using the 'all' alias.

```bash
pip install "mellea[all]"
```

--------------------------------

### Install Mellea with Extras

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/examples/traced-generation-loop.md

Install Mellea with all extras, including OpenTelemetry dependencies, using uv.

```bash
uv sync --all-extras
```

--------------------------------

### Run Basic Tracing Example (No Tracing)

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/telemetry/README.md

Executes the telemetry example without enabling tracing.

```bash
python telemetry_example.py
```

--------------------------------

### View Contributing Guide

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/troubleshooting/faq.md

Display the content of the contributing guide to understand how to contribute to the project.

```bash
cat docs/CONTRIBUTING_DOCS.md
```

--------------------------------

### Install WatsonX Backend

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/watsonx.md

Install the WatsonX backend for Mellea. This command ensures the necessary `ibm-watson-machine-learning` package is included.

```bash
pip install 'mellea[watsonx]'
```

--------------------------------

### Initialize LocalHFBackend

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/advanced/intrinsics.md

Sets up the LocalHFBackend for using adapter-accelerated operations. Requires 'mellea[hf]' installation. A GPU or Apple Silicon Mac is recommended.

```python
# Requires: mellea[hf]
# Returns: LocalHFBackend
from mellea.backends.huggingface import LocalHFBackend

backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
```

--------------------------------

### Install Dependencies with Conda/Mamba

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/community/contributing-guide.md

Use the provided installation script for environment setup, dependency installation, and pre-commit hook installation when using conda or mamba.

```bash
conda/install.sh
```

--------------------------------

### View m serve Help

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/m-serve.md

Command to display all available options and configurations for the `m serve` command, allowing users to customize server behavior.

```bash
m serve --help
```

--------------------------------

### Run Token Metrics Example (Console Output)

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/telemetry/README.md

Enables token usage metrics and directs output to the console for the metrics example.

```bash
export MELLEA_METRICS_ENABLED=true
export MELLEA_METRICS_CONSOLE=true
python metrics_example.py
```

--------------------------------

### Run Token Metrics Example (OTLP Export)

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/telemetry/README.md

Enables token usage metrics and configures OTLP export to a specified endpoint.

```bash
export MELLEA_METRICS_ENABLED=true
export MELLEA_METRICS_OTLP=true
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4317
python metrics_example.py
```

--------------------------------

### Start Mellea Session with Backend Name and Options

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/how-to/backends-and-configuration.md

Demonstrates starting a Mellea session using a backend name and specifying model options. Requires 'mellea' and its backend dependencies.

```python
# Requires: mellea
# Returns: MelleaSession
import mellea
from mellea.backends import ModelOption
from mellea.stdlib.context import ChatContext

m = mellea.start_session(
    backend_name="ollama",
    model_id="phi4-mini:latest",
    ctx=ChatContext(),
    model_options={ModelOption.TEMPERATURE: 0.1},
)
```

--------------------------------

### Enable and Run Telemetry Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/observability/tracing.md

Commands to enable Mellea traces and run the telemetry example script. Ensure Mellea traces are enabled and configured to output to the console.

```bash
export MELLEA_TRACES_ENABLED=true
export MELLEA_TRACES_CONSOLE=true
uv run python docs/examples/telemetry/telemetry_example.py
```

--------------------------------

### Prerequisites Block Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/CONTRIBUTING_DOCS.md

Procedural documentation pages should begin with a prerequisites block before the first code example. This block specifies essential software or installations needed for the page's content.

```markdown
**Prerequisites:** [Ollama](https://ollama.ai) installed and running, `pip install mellea` complete.
```

--------------------------------

### Start Session and Classify Sentiment

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/sentiment_classifier.ipynb

Starts a Mellea session, uses the defined classify_sentiment function to predict the sentiment of a given text, and prints the result. This demonstrates the practical application of the Mellea setup.

```python
m = start_session()
sentiment = classify_sentiment(m, text="I love this!")
print("Output sentiment is:", sentiment)
```

--------------------------------

### Initialize OpenAIBackend with Embedded Adapters

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/advanced/intrinsics.md

Sets up the OpenAIBackend for using adapter-accelerated operations with a Granite Switch model served via vLLM. Requires 'load_embedded_adapters=True'.

```python
from mellea.backends.openai import OpenAIBackend
from mellea.backends.model_ids import IBM_GRANITE_SWITCH_4_1_3B_PREVIEW
from mellea.formatters import TemplateFormatter

backend = OpenAIBackend(
    model_id=IBM_GRANITE_SWITCH_4_1_3B_PREVIEW.hf_model_name,
    formatter=TemplateFormatter(model_id=IBM_GRANITE_SWITCH_4_1_3B_PREVIEW.hf_model_name),
    base_url="http://localhost:8000/v1",  # vLLM server
    api_key="EMPTY",
    load_embedded_adapters=True,
)
```

--------------------------------

### Install Dependencies with uv run

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/examples/resilient-rag-fallback.md

This snippet shows how to declare Python package dependencies using a PEP 723 compliant script block. It's designed to be used with `uv run` for automatic environment setup and dependency installation, eliminating the need for manual pip installs.

```python
# Requires: faiss-cpu, sentence-transformers, mellea
# Returns: N/A
# pytest: skip_always
# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "faiss-cpu",
#     "sentence_transformers",
#     "mellea"
# ]
# ///
```

--------------------------------

### Install All Dependencies for Tests

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/community/contributing-guide.md

Installs all project dependencies, including extras and all groups, using uv. This command is required before running tests.

```bash
uv sync --all-extras --all-groups
```

--------------------------------

### One-Shot Examples in Docstring for Model Guidance

Source: https://github.com/generative-computing/mellea/blob/main/docs/AGENTS_TEMPLATE.md

Improve LLM performance on difficult tasks by providing one-shot examples directly within the function's docstring. This guides the model's output format and content.

```python
@generative
def identify_fruit(text: str) -> str | None:
    """
    Extract fruit from text, or None if none mentioned.
    Ex: "I ate an apple" -> "apple"
    Ex: "The sky is blue" -> None
    """
    ...
```

--------------------------------

### Initialize Mellea with Vertex AI LiteLLM Backend

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/vertex-ai.md

Set up a MelleaSession using the LiteLLMBackend for Vertex AI. Ensure VERTEXAI_PROJECT and VERTEXAI_LOCATION environment variables are set.

```python
import os

from pydantic import BaseModel

from mellea import MelleaSession
from mellea.backends.litellm import LiteLLMBackend


class KeyPoints(BaseModel):
    points: list[str]
    source_quality: str


backend = LiteLLMBackend(
    model_id="vertex_ai/gemini-1.5-pro",
    model_options={
        "vertex_project": os.environ["VERTEXAI_PROJECT"],
        "vertex_location": os.environ["VERTEXAI_LOCATION"],
    },
)
m = MelleaSession(backend=backend)

result = m.instruct(
    "Extract the key points from this text: {{text}}",
    format=KeyPoints,
    user_variables={"text": "...your document..."},
)
parsed = KeyPoints.model_validate_json(str(result))
print(parsed.points)
```

--------------------------------

### Enforce Model Policy with session_pre_init Hook

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/concepts/plugins.mdx

Use the `session_pre_init` hook to enforce policies on model usage before a session starts. This example blocks the use of 'gpt-4'.

```python
@hook(HookType.SESSION_PRE_INIT)
async def enforce_model_policy(payload, ctx):
    if "gpt-4" in str(payload.model_id):
        return block("GPT-4 usage not permitted", code="MODEL_POLICY")
```

--------------------------------

### Generative Function with Specific Docstring

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/troubleshooting/faq.md

Provide a specific docstring with clear instructions and an example output format to guide the model's response for `@generative` functions.

```python
from mellea import generative

# Specific — the model knows exactly what format is expected
@generative
def extract_keywords(text: str) -> list[str]:
    """Extract the five most important keywords from the text.
    Return only a Python list of strings with no extra commentary.
    Example output: ["machine learning", "neural networks", "training"]
    """
```

--------------------------------

### Directly Construct OllamaModelBackend for Mellea

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/how-to/backends-and-configuration.md

Illustrates constructing an OllamaModelBackend directly and passing it to MelleaSession. Requires 'mellea' and its backend dependencies.

```python
# Requires: mellea
# Returns: MelleaSession
import mellea
from mellea.backends.ollama import OllamaModelBackend
from mellea.stdlib.context import ChatContext

backend = OllamaModelBackend(model_id="phi4-mini:latest")
m = mellea.MelleaSession(backend=backend, ctx=ChatContext())
```

--------------------------------

### Create an Instruction Component

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/reference/glossary.md

Use the Instruction class to wrap a prompt description, requirements, and examples for execution by m.act().

```python
from mellea.stdlib.components.instruction import Instruction
instr = Instruction(
    description="Summarise the following text: {{text}}",
    requirements=[req("Must be under 50 words.")],
    user_variables={"text": "..."},
)
result = m.act(instr)
```

--------------------------------

### Simple Prompt: List Fake Backends

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/instruct_validate_repair/qiskit_code_validation/README.md

Use this prompt to generate Qiskit code for listing available fake backends.

```python
prompt = "use qiskit to list fake backends"
```

--------------------------------

### Streaming Output Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/how-to/use-async-and-streaming.md

Demonstrates how to enable and consume streaming output from an asynchronous instruction call. Set `ModelOption.STREAM: True` and use `mot.astream()` to get incremental chunks of the response.

```python
# Requires: mellea
# Returns: None
import asyncio
import mellea
from mellea.backends import ModelOption

async def main():
    m = mellea.start_session()
    mot = await m.ainstruct(
        "Write a short story about a robot learning to cook.",
        model_options={ModelOption.STREAM: True},
    )

    # Consume chunks as they arrive
    while not mot.is_computed():
        chunk = await mot.astream()
        print(chunk, end="", flush=True)

    print()  # newline after streaming completes

asyncio.run(main())
```

--------------------------------

### Run Context Sampling Example

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/context/README.md

Execute the Python script that demonstrates context retrieval with sampling and validation.

```bash
python docs/examples/context/contexts_with_sampling.py
```

--------------------------------

### Full Example File

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/examples/data-extraction-pipeline.md

This snippet shows the complete Python file for the data extraction pipeline example, including imports, session initialization, function definition, and execution.

```python
# pytest: ollama, llm

"""Simple Example of information extraction with Mellea using generative stubs."""

from mellea import generative, start_session
from mellea.backends import model_ids

m = start_session()


@generative
def extract_all_person_names(doc: str) -> list[str]:
    """Given a document, extract names of ALL mentioned persons. Return these names as list of strings."""


# ref: https://www.nytimes.com/2012/05/20/world/world-leaders-at-us-meeting-urge-growth-not-austerity.html
NYTimes_text = "CAMP DAVID, Md. — Leaders of the world's richest countries banded together on Saturday to press Germany to back more pro-growth policies to halt the deepening debt crisis in Europe, as President Obama for the first time gained widespread support for his argument that Europe, and the United States by extension, cannot afford Chancellor Angela Merkel's one-size-fits-all approach emphasizing austerity."

person_names = extract_all_person_names(m, doc=NYTimes_text)

print(f"person_names = {person_names}")
# out: person_names = ['President Obama', 'Angela Merkel']
```

--------------------------------

### Quickstart Plugin: Log LLM Call Summary

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/concepts/plugins.mdx

This plugin logs a summary of the LLM action before each generation call. It requires the 'hooks' extra to be installed. The hook function receives a payload and context, and implicitly returns None to allow execution to continue.

```python
## file: https://github.com/generative-computing/mellea/blob/main/docs/examples/plugins/quickstart.py
import logging

from mellea import start_session
from mellea.plugins import HookType, hook, register

log = logging.getLogger("quickstart")

@hook(HookType.GENERATION_PRE_CALL)
async def log_generation(payload, ctx):
    """Log a one-line summary before every LLM call."""
    action_preview = str(payload.action)[:80].replace("\n", " ")
    log.info("[log_generation] About to call LLM: %r", action_preview)

register(log_generation)

with start_session() as m:
    result = m.instruct("What is the capital of France?")
    log.info("Result: %s", result)
```

--------------------------------

### Example Mellea serve Program

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/m-serve.md

An example Mellea program demonstrating how to implement the `serve()` function. It initializes a Mellea session, processes incoming chat messages, applies requirements (like word count limits), and returns the sampling result.

```python
import mellea
from cli.serve.models import ChatMessage
from mellea.core import ModelOutputThunk, Requirement, SamplingResult
from mellea.stdlib.context import ChatContext
from mellea.stdlib.requirements import simple_validate
from mellea.stdlib.sampling import RejectionSamplingStrategy

session = mellea.start_session(ctx=ChatContext())

def serve(
    input: list[ChatMessage],
    requirements: list[str] | None = None,
    model_options: dict | None = None,
) -> ModelOutputThunk | SamplingResult:
    """Takes a prompt as input and runs it through a Mellea program."""
    message = input[-1].content
    reqs = [
        Requirement(
            "Keep this under 50 words",
            validation_fn=simple_validate(lambda x: len(x.split()) < 50),
        ),
        *(requirements or []),
    ]
    return session.instruct(
        description=message,
        requirements=reqs,
        strategy=RejectionSamplingStrategy(loop_budget=3),
        model_options=model_options,
    )
```

--------------------------------

### Initialize LocalHFBackend

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/how-to/safety-guardrails.md

Set up the evaluation backend once and reuse it across all checks in your application. Requires `pip install "mellea[hf]"`.

```python
from mellea.backends.huggingface import LocalHFBackend

guardian_backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
```

--------------------------------

### Transform Table with Mellea and Llama 3

Source: https://github.com/generative-computing/mellea/blob/main/docs/examples/notebooks/georgia_tech.ipynb

Transform a table by adding a 'Model' column using Mellea and the Llama 3 model. This example demonstrates iterating with different seeds and handling potential non-useful output. Requires 'mellea' and an Ollama backend setup.

```python
from mellea.backends import ModelOption
from mellea.backends.model_ids import META_LLAMA_3_2_3B
from mellea.backends.ollama import OllamaModelBackend

# You can use multiple different models at the same time!
m_llama = mellea.MelleaSession(backend=OllamaModelBackend(model_id=META_LLAMA_3_2_3B))

for seed in [x * 12 for x in range(5)]:
    table2 = m_llama.transform(
        table1,
        "Add a 'Model' column as the last column that extracts which model was used for that feature or 'None' if none.",
        model_options={ModelOption.SEED: seed},
    )
    if isinstance(table2, Table):
        print(table2.to_markdown())
    else:
        print("==== TRYING AGAIN after non-useful output.====")
```

--------------------------------

### Install Mellea with uv

Source: https://github.com/generative-computing/mellea/blob/main/README.md

Installs the Mellea library using the uv package manager. Additional extras can be installed with 'mellea[all]'.

```bash
uv pip install mellea
```

--------------------------------

### Example Test File with Markers

Source: https://github.com/generative-computing/mellea/blob/main/test/README.md

An example Python file demonstrating how to opt-in examples for pytest collection using a '# pytest:' comment to specify markers.

```python
# pytest: e2e, ollama, qualitative
"""Greeting example — demonstrates session.instruct()."""
```

--------------------------------

### Install google-cloud-aiplatform

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/vertex-ai.md

Install the google-cloud-aiplatform package if you encounter a ModuleNotFoundError.

```bash
pip install google-cloud-aiplatform
```

--------------------------------

### Install Ollama on macOS

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/ollama.md

Installs Ollama using Homebrew on macOS.

```bash
# macOS
brew install ollama
```

--------------------------------

### Connect Mellea to Vertex AI using LiteLLMBackend with instruct()

Source: https://github.com/generative-computing/mellea/blob/main/docs/docs/integrations/vertex-ai.md

Initialize LiteLLMBackend with a Vertex AI model and use MelleaSession to send an instruction. This example demonstrates connecting to 'vertex_ai/gemini-1.5-pro'.

```python
# Requires: mellea[litellm], google-cloud-aiplatform
# Returns: ModelOutputThunk
import os

from mellea import MelleaSession
from mellea.backends.litellm import LiteLLMBackend

backend = LiteLLMBackend(
    model_id="vertex_ai/gemini-1.5-pro",
    model_options={
        "vertex_project": os.environ["VERTEXAI_PROJECT"],
        "vertex_location": os.environ["VERTEXAI_LOCATION"],
    },
)
m = MelleaSession(backend=backend)

result = m.instruct("Summarise the key points of the Vertex AI documentation.")
print(str(result))
# Output will vary — LLM responses depend on model and temperature.
```