CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a DSPy framework demonstration using marimo interactive notebooks. DSPy automates prompt tuning for LLM applications through data-driven optimization rather than manual prompt engineering.

Development Commands

Setup

# Install dependencies
uv sync

# Create .env from template
cp .env.example .env
# Edit .env with your Azure OpenAI or OpenAI credentials

Running marimo notebooks

# Run a specific notebook
uv run marimo edit notebooks/01_chatbot/01_before_tuning.py

# Or from within the notebook directory
cd notebooks/01_chatbot
uv run marimo edit 01_before_tuning.py

Quality checks

# Lint check
uv run ruff check .

# Type check (excludes notebooks/)
uv run mypy .

Architecture

Core Components

common/config.py: LM configuration abstraction

Provides
```
configure_lm()
```
for unified Azure OpenAI / OpenAI setup
Controlled by
```
PROVIDER_NAME
```
environment variable ("azure" or "openai")

Default models:

SMART_MODEL=gpt-4.1

FAST_MODEL=gpt-4.1-nano

common/model_saver.py: Model persistence with versioning

```
save_model_with_timestamp()
```
: Saves DSPy models with timestamp + optional score
Creates symlink
```
{prefix}_latest.json
```
pointing to newest model
```
load_latest_model()
```
: Loads via the latest symlink
Models stored in
```
notebooks/{demo}/artifact/
```
directories (version controlled)

DSPy Module Pattern

All DSPy modules follow this structure:

class MySignature(dspy.Signature):
    """Description of task"""
    input_field = dspy.InputField(desc="...")
    output_field = dspy.OutputField(desc="...")

class MyModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.predictor = dspy.Predict(MySignature)

    def forward(self, input_field: str) -> dspy.Prediction:
        return self.predictor(input_field=input_field)

marimo Notebook Patterns

Critical: UIElement Display Pattern

marimo requires that the last expression in a cell be evaluated for display. These patterns cause nothing to display:

# ❌ WRONG - return statement prevents display
if condition:
    mo.md("content")
else:
    mo.md("")
return

# ❌ WRONG - if/else is a statement, not evaluated
if condition:
    mo.md("content")
else:
    mo.md("")

# ✅ CORRECT - assign to variable and evaluate
if condition:
    display = mo.md("content")
else:
    display = mo.md("")

display  # Last expression gets displayed

Button Trigger Pattern

Buttons must use

mo.state()

triggers, NOT

.value

checking:

# Cell 1: Create trigger and button (depends only on mo - stable)
@app.cell
def _(mo):
    get_trigger, set_trigger = mo.state(0)

    button = mo.ui.button(
        label="Execute",
        on_change=lambda _: set_trigger(lambda v: v + 1)  # Increment on click
    )

    return get_trigger, button

# Cell 2: Process on trigger change
@app.cell
def _(mo, get_trigger, other_dependencies):
    trigger_value = get_trigger()  # Reference trigger to watch for changes

    if trigger_value > 0:
        # Execute action
        result = perform_action()
        display = mo.md(f"Result: {result}")
    else:
        display = mo.md("")

    display  # Last expression displayed

Why this pattern works:

Trigger state is created in a cell that depends only on
```
mo
```
(stable, won't re-execute)
If state is in a cell depending on variables that change,
```
mo.state()
```
recreates on re-execution, breaking reactivity
Processing cell watches the trigger getter, auto-executes when trigger changes

Path Resolution

Notebooks use

__file__

to build absolute paths, ensuring they work regardless of execution directory:

import os
notebook_dir = os.path.dirname(os.path.abspath(__file__))
artifact_dir = os.path.join(notebook_dir, "artifact")

Workflow: 01_chatbot Demo

01_before_tuning.py: Run baseline chatbot (unoptimized prompts)
02_tuning.py: Execute MIPROv2 optimization on training data, save optimized model to
```
artifact/
```
03_after_tuning.py: Load optimized model, compare before/after results

Each notebook is self-contained and can be run from project root or notebook directory.

Environment Variables

Required in

.env

Azure OpenAI:

PROVIDER_NAME=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_API_VERSION=2025-04-01-preview

OpenAI:

PROVIDER_NAME=openai
OPENAI_API_KEY=your-api-key

Optional overrides:

```
SMART_MODEL
```
: Default "gpt-4.1"
```
FAST_MODEL
```
: Default "gpt-4.1-nano"
```
EMBEDDING_MODEL
```
: Default "text-embedding-3-small"

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Install dependencies
uv sync

# Create .env from template
cp .env.example .env
# Edit .env with your Azure OpenAI or OpenAI credentials

Running marimo notebooks

# Run a specific notebook
uv run marimo edit notebooks/01_chatbot/01_before_tuning.py

# Or from within the notebook directory
cd notebooks/01_chatbot
uv run marimo edit 01_before_tuning.py

Quality checks

# Lint check
uv run ruff check .

# Type check (excludes notebooks/)
uv run mypy .

Architecture

Core Components

common/config.py: LM configuration abstraction

Provides
```
configure_lm()
```
for unified Azure OpenAI / OpenAI setup
Controlled by
```
PROVIDER_NAME
```
environment variable ("azure" or "openai")

Default models:

SMART_MODEL=gpt-4.1

FAST_MODEL=gpt-4.1-nano

common/model_saver.py: Model persistence with versioning

```
save_model_with_timestamp()
```
: Saves DSPy models with timestamp + optional score
Creates symlink
```
{prefix}_latest.json
```
pointing to newest model
```
load_latest_model()
```
: Loads via the latest symlink
Models stored in
```
notebooks/{demo}/artifact/
```
directories (version controlled)

DSPy Module Pattern

All DSPy modules follow this structure:

class MySignature(dspy.Signature):
    """Description of task"""
    input_field = dspy.InputField(desc="...")
    output_field = dspy.OutputField(desc="...")

class MyModule(dspy.Module):
    def __init__(self):
        super().__init__()
        self.predictor = dspy.Predict(MySignature)

    def forward(self, input_field: str) -> dspy.Prediction:
        return self.predictor(input_field=input_field)

marimo Notebook Patterns

Critical: UIElement Display Pattern

marimo requires that the last expression in a cell be evaluated for display. These patterns cause nothing to display:

# ❌ WRONG - return statement prevents display
if condition:
    mo.md("content")
else:
    mo.md("")
return

# ❌ WRONG - if/else is a statement, not evaluated
if condition:
    mo.md("content")
else:
    mo.md("")

# ✅ CORRECT - assign to variable and evaluate
if condition:
    display = mo.md("content")
else:
    display = mo.md("")

display  # Last expression gets displayed

Button Trigger Pattern

Buttons must use

mo.state()

triggers, NOT

.value

checking:

# Cell 1: Create trigger and button (depends only on mo - stable)
@app.cell
def _(mo):
    get_trigger, set_trigger = mo.state(0)

    button = mo.ui.button(
        label="Execute",
        on_change=lambda _: set_trigger(lambda v: v + 1)  # Increment on click
    )

    return get_trigger, button

# Cell 2: Process on trigger change
@app.cell
def _(mo, get_trigger, other_dependencies):
    trigger_value = get_trigger()  # Reference trigger to watch for changes

    if trigger_value > 0:
        # Execute action
        result = perform_action()
        display = mo.md(f"Result: {result}")
    else:
        display = mo.md("")

    display  # Last expression displayed

Why this pattern works:

Trigger state is created in a cell that depends only on
```
mo
```
(stable, won't re-execute)
If state is in a cell depending on variables that change,
```
mo.state()
```
recreates on re-execution, breaking reactivity
Processing cell watches the trigger getter, auto-executes when trigger changes

Path Resolution

Notebooks use

__file__

to build absolute paths, ensuring they work regardless of execution directory:

import os
notebook_dir = os.path.dirname(os.path.abspath(__file__))
artifact_dir = os.path.join(notebook_dir, "artifact")

Workflow: 01_chatbot Demo

01_before_tuning.py: Run baseline chatbot (unoptimized prompts)
02_tuning.py: Execute MIPROv2 optimization on training data, save optimized model to
```
artifact/
```
03_after_tuning.py: Load optimized model, compare before/after results

Each notebook is self-contained and can be run from project root or notebook directory.

Environment Variables

Required in

.env

Azure OpenAI:

PROVIDER_NAME=azure
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_API_VERSION=2025-04-01-preview

OpenAI:

PROVIDER_NAME=openai
OPENAI_API_KEY=your-api-key

Optional overrides:

```
SMART_MODEL
```
: Default "gpt-4.1"
```
FAST_MODEL
```
: Default "gpt-4.1-nano"
```
EMBEDDING_MODEL
```
: Default "text-embedding-3-small"

CLAUDE.md

CLAUDE.md

Project Overview

Development Commands

Setup

Running marimo notebooks

Quality checks

Architecture

Core Components

DSPy Module Pattern

marimo Notebook Patterns

Critical: UIElement Display Pattern

Button Trigger Pattern

Path Resolution

Workflow: 01_chatbot Demo

Environment Variables

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Development Commands

Setup

Running marimo notebooks

Quality checks

Architecture

Core Components

DSPy Module Pattern

marimo Notebook Patterns

Critical: UIElement Display Pattern

Button Trigger Pattern

Path Resolution

Workflow: 01_chatbot Demo

Environment Variables