synth-ai 0.2.9.dev0__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

examples/tunnel_gepa_banking77/README.md

@@ -0,0 +1,106 @@
+# Banking77 GEPA Optimization via Cloudflare Tunnel
+
+This example demonstrates how to use Cloudflare Tunnel to expose a local Banking77 task app to Synth's production backend for GEPA prompt optimization.
+
+## Overview
+
+Instead of deploying to Modal or running a local backend, this example:
+1. Deploys the Banking77 task app locally
+2. Exposes it via Cloudflare Tunnel (free quick tunnels)
+3. Runs GEPA optimization against Synth's production backend
+
+## Prerequisites
+
+- `cloudflared` installed ([install guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/create-local-tunnel/))
+- `SYNTH_API_KEY` set (get from [Synth Dashboard](https://app.usesynth.ai/api-keys))
+- `ENVIRONMENT_API_KEY` set (or auto-generated)
+- `GROQ_API_KEY` set (optional, for LLM-guided mutations)
+
+## Quick Start
+
+```bash
+# Run the example
+./examples/tunnel_gepa_banking77/run_gepa_with_tunnel.sh
+```
+
+The script will:
+1. ✅ Check prerequisites
+2. 🌐 Deploy Banking77 via Cloudflare Tunnel (quick mode)
+3. 📝 Create GEPA config with tunnel URL
+4. 🎯 Run GEPA optimization against prod backend
+5. 📊 Show results
+
+## What Happens
+
+1. **Tunnel Deployment**: Creates an ephemeral `*.trycloudflare.com` URL
+2. **Config Generation**: Creates `banking77_gepa_tunnel.toml` with the tunnel URL
+3. **GEPA Training**: Runs prompt optimization using Synth's production backend
+4. **Results**: View results in the Synth dashboard
+
+## Manual Steps
+
+If you prefer to run steps manually:
+
+### Step 1: Deploy Tunnel
+
+```bash
+uvx synth-ai deploy \
+    --task-app examples/task_apps/banking77/banking77_task_app.py \
+    --runtime tunnel \
+    --tunnel-mode quick \
+    --port 8102 \
+    --env .env.tunnel
+```
+
+This will write `TASK_APP_URL` to `.env.tunnel`.
+
+### Step 2: Run GEPA
+
+```bash
+export BACKEND_BASE_URL="https://api.usesynth.ai"
+export TASK_APP_URL=$(grep TASK_APP_URL .env.tunnel | cut -d'=' -f2)
+
+uvx synth-ai train \
+    --type prompt_learning \
+    --config examples/tunnel_gepa_banking77/banking77_gepa_tunnel.toml \
+    --backend https://api.usesynth.ai \
+    --poll
+```
+
+## Configuration
+
+The generated config (`banking77_gepa_tunnel.toml`) includes:
+- **Task App URL**: Cloudflare Tunnel URL (e.g., `https://abc123.trycloudflare.com`)
+- **Backend**: Production backend (`https://api.usesynth.ai`)
+- **GEPA Settings**: Standard Banking77 optimization parameters
+
+## Notes
+
+- **Quick Tunnels**: Ephemeral, free, no account needed
+- **Tunnel Lifetime**: Tunnel closes when deployment process stops
+- **Production Backend**: Uses Synth's hosted backend (no local setup needed)
+- **Credentials**: Saved to `.env.tunnel` for reuse
+
+## Troubleshooting
+
+### Tunnel not accessible
+- Check `cloudflared` is installed: `which cloudflared`
+- Verify tunnel process is running
+- Check firewall/network settings
+
+### Backend connection failed
+- Verify `SYNTH_API_KEY` is set correctly
+- Check network connectivity to `https://api.usesynth.ai`
+- Ensure API key has proper permissions
+
+### Task app health check fails
+- Verify `ENVIRONMENT_API_KEY` matches the one used in deployment
+- Check task app logs for errors
+- Ensure task app has `/health` endpoint
+
+## Related Examples
+
+- Local deployment: `examples/blog_posts/gepa/deploy_banking77_task_app.sh`
+- Modal deployment: `examples/blog_posts/gepa/run_gepa_banking77_pipeline.sh`
+- GEPA configs: `examples/blog_posts/gepa/configs/`
+

examples/tunnel_gepa_banking77/banking77_gepa_tunnel.toml

@@ -0,0 +1,95 @@
+[prompt_learning]
+algorithm = "gepa"
+task_app_url = "https://contains-voluntary-lip-carey.trycloudflare.com"
+task_app_id = "banking77"
+
+# Initial prompt pattern (pattern-based mode)
+[prompt_learning.initial_prompt]
+id = "banking77_pattern"
+name = "Banking77 Classification Pattern"
+
+[[prompt_learning.initial_prompt.messages]]
+role = "system"
+pattern = "You are an expert banking assistant. \n\n**Available Banking Intents:**\n{available_intents}\n\n**Task:**\nCall the `banking77_classify` tool with the `intent` parameter set to ONE of the intent labels listed above that best matches the customer query. The intent must be an exact match from the list."
+order = 0
+
+[[prompt_learning.initial_prompt.messages]]
+role = "user"
+pattern = "Customer Query: {query}\n\nClassify this query by calling the tool with the correct intent label from the list above."
+order = 1
+
+[prompt_learning.initial_prompt.wildcards]
+query = "REQUIRED"  # Will be provided by task app at runtime
+available_intents = "OPTIONAL"  # Intent list (numbered 1-77) will be provided by task app
+
+# Policy configuration (model, provider, etc.)
+[prompt_learning.policy]
+inference_mode = "synth_hosted"
+model = "openai/gpt-oss-20b"
+provider = "groq"
+temperature = 0.0
+max_completion_tokens = 512
+policy_name = "banking77-classifier"  # Required for Banking77 task app
+
+# Training split config
+[prompt_learning.env_config]
+pool = "train"
+
+# GEPA-specific configuration with nested subsections (mirrors RL structure)
+[prompt_learning.gepa]
+env_name = "banking77"
+proposer_type = "dspy"
+
+# Rollout configuration (mirrors RL [rollout] section)
+[prompt_learning.gepa.rollout]
+budget = 100
+max_concurrent = 20
+minibatch_size = 10
+
+# Evaluation configuration (mirrors RL [evaluation] section)
+[prompt_learning.gepa.evaluation]
+seeds = [
+  50, 51, 52, 53, 54, 55, 56, 57, 58, 59,
+  60, 61, 62, 63, 64, 65, 66, 67, 68, 69,
+  70, 71, 72, 73, 74, 75, 76, 77, 78, 79
+]  # Training seeds (30 seeds from train pool)
+validation_seeds = [
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+  10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
+  20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
+  30, 31, 32, 33, 34, 35, 36, 37, 38, 39,
+  40, 41, 42, 43, 44, 45, 46, 47, 48, 49
+]  # Held-out validation seeds (50 seeds from validation pool - not in training)
+validation_pool = "validation"
+validation_top_k = 3
+test_pool = [2, 3]  # Test pool for final evaluation (small held-out set)
+
+# Mutation configuration (LLM-guided mutation settings)
+[prompt_learning.gepa.mutation]
+rate = 0.3
+llm_model = "openai/gpt-oss-120b"
+llm_provider = "groq"
+llm_inference_url = "https://api.groq.com/openai/v1"
+
+# Population configuration (evolution parameters)
+[prompt_learning.gepa.population]
+initial_size = 10
+num_generations = 3
+children_per_generation = 12
+crossover_rate = 0.5
+selection_pressure = 1.0
+patience_generations = 3
+
+# Archive configuration (Pareto archive settings)
+[prompt_learning.gepa.archive]
+size = 40
+pareto_set_size = 32
+pareto_eps = 1e-6
+feedback_fraction = 0.5
+
+# Token and budget configuration
+[prompt_learning.gepa.token]
+# max_limit = 1000  # Uncomment to set a token limit
+counting_model = "gpt-4"
+enforce_pattern_limit = true
+# max_spend_usd = 100.0  # Uncomment to set a budget cap

examples/tunnel_gepa_banking77/keep_tunnel_running.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Helper script to deploy tunnel and keep it running while training runs."""
+import asyncio
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+# Add repo to path
+repo_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(repo_root))
+
+from synth_ai.cfgs import CloudflareTunnelDeployCfg
+from synth_ai.tunnel_deploy import deploy_app_tunnel, _TUNNEL_PROCESSES
+from synth_ai.tunnel import stop_tunnel
+
+
+async def main():
+    """Deploy tunnel and keep it running."""
+    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8102
+    env_file = Path(sys.argv[2]) if len(sys.argv) > 2 else Path(".env.tunnel")
+    task_app_path = Path(sys.argv[3]) if len(sys.argv) > 3 else Path("examples/task_apps/banking77/banking77_task_app.py")
+    env_api_key = os.environ.get("ENVIRONMENT_API_KEY", "test-key")
+    
+    cfg = CloudflareTunnelDeployCfg.create(
+        task_app_path=task_app_path,
+        env_api_key=env_api_key,
+        mode="quick",
+        port=port,
+        trace=False
+    )
+    
+    try:
+        print(f"🚀 Deploying tunnel on port {port}...")
+        url = await deploy_app_tunnel(cfg, env_file)
+        print(f"✅ Tunnel ready: {url}")
+        print(f"📝 URL written to: {env_file}")
+        print(f"⏳ Keeping tunnel running... (Press Ctrl+C to stop)")
+        
+        # Keep process alive
+        while True:
+            # Check if processes are still running
+            if port in _TUNNEL_PROCESSES:
+                proc = _TUNNEL_PROCESSES[port]
+                if proc.poll() is not None:
+                    print(f"❌ Tunnel process exited with code {proc.returncode}")
+                    break
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\n🛑 Stopping tunnel...")
+    finally:
+        if port in _TUNNEL_PROCESSES:
+            stop_tunnel(_TUNNEL_PROCESSES[port])
+            _TUNNEL_PROCESSES.pop(port, None)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+

examples/tunnel_gepa_banking77/run_gepa_with_tunnel.sh

@@ -0,0 +1,226 @@
+#!/bin/bash
+# Deploy Banking77 task app via Cloudflare Tunnel and run GEPA optimization
+# This example demonstrates using Cloudflare Tunnel to expose a local task app
+# to Synth's production backend for prompt optimization.
+
+set -e
+
+echo "🚀 Banking77 GEPA Optimization via Cloudflare Tunnel"
+echo "====================================================="
+echo ""
+
+# Load .env file if it exists
+ENV_FILES=(".env" "$(dirname "$0")/../../../.env" "$HOME/.synth-ai/.env")
+for env_file in "${ENV_FILES[@]}"; do
+    if [ -f "$env_file" ]; then
+        echo "📝 Loading environment from: $env_file"
+        set -a
+        source "$env_file"
+        set +a
+        break
+    fi
+done
+
+# Check required environment variables
+if [ -z "$SYNTH_API_KEY" ]; then
+    echo "❌ ERROR: SYNTH_API_KEY not set"
+    echo "   Get your API key from: https://app.usesynth.ai/api-keys"
+    exit 1
+fi
+
+if [ -z "$ENVIRONMENT_API_KEY" ]; then
+    echo "⚠️  ENVIRONMENT_API_KEY not set, generating one..."
+    export ENVIRONMENT_API_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')
+    echo "✅ Generated ENVIRONMENT_API_KEY: ${ENVIRONMENT_API_KEY:0:20}..."
+fi
+
+if [ -z "$GROQ_API_KEY" ]; then
+    echo "⚠️  Warning: GROQ_API_KEY not set (needed for LLM-guided mutations in GEPA)"
+    echo "   Set it with: export GROQ_API_KEY=your_key"
+fi
+
+# Use production backend
+BACKEND_URL="${BACKEND_BASE_URL:-https://api.usesynth.ai}"
+echo "📍 Backend URL: $BACKEND_URL"
+echo "✅ SYNTH_API_KEY: ${SYNTH_API_KEY:0:20}..."
+echo "✅ ENVIRONMENT_API_KEY: ${ENVIRONMENT_API_KEY:0:20}..."
+echo ""
+
+# Navigate to repo root (script is at examples/tunnel_gepa_banking77/run_gepa_with_tunnel.sh)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$REPO_ROOT"
+
+# Check if cloudflared is installed
+if ! command -v cloudflared &> /dev/null; then
+    echo "❌ ERROR: cloudflared not found"
+    echo "   Install it:"
+    echo "     macOS: brew install cloudflare/cloudflare/cloudflared"
+    echo "     Linux/Windows: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/create-local-tunnel/"
+    exit 1
+fi
+
+echo "✅ cloudflared found: $(which cloudflared)"
+echo ""
+
+# Deploy task app via Cloudflare Tunnel
+echo "🌐 Deploying Banking77 task app via Cloudflare Tunnel..."
+echo ""
+
+TASK_APP_PATH="$REPO_ROOT/examples/task_apps/banking77/banking77_task_app.py"
+ENV_FILE="$REPO_ROOT/.env.tunnel"
+
+if [ ! -f "$TASK_APP_PATH" ]; then
+    echo "❌ ERROR: Task app not found: $TASK_APP_PATH"
+    exit 1
+fi
+echo "✅ Task app found: $TASK_APP_PATH"
+echo ""
+
+# Create .env file if it doesn't exist (deploy command requires it to exist)
+touch "$ENV_FILE"
+
+# Deploy with quick tunnel (free, ephemeral) in background mode
+# The deploy command returns immediately, keeping tunnel running headlessly
+echo "🚀 Starting tunnel deployment (background mode)..."
+uv run synth-ai deploy \
+    --task-app "$TASK_APP_PATH" \
+    --runtime tunnel \
+    --tunnel-mode quick \
+    --port 8102 \
+    --env "$ENV_FILE" \
+    --trace > /tmp/tunnel_deploy.log 2>&1 &
+DEPLOY_PID=$!
+
+# Wait for tunnel URL to be written to .env file
+echo "⏳ Waiting for tunnel to be ready..."
+TASK_APP_URL=""
+for i in {1..30}; do
+    if [ -f "$ENV_FILE" ] && grep -q "^TASK_APP_URL=" "$ENV_FILE"; then
+        TASK_APP_URL=$(grep "^TASK_APP_URL=" "$ENV_FILE" | cut -d'=' -f2 | tr -d '"' | tr -d "'")
+        if [ -n "$TASK_APP_URL" ]; then
+            echo "✅ Tunnel URL found: $TASK_APP_URL"
+            # Wait a bit more for DNS propagation and tunnel to be fully ready
+            echo "⏳ Waiting for tunnel to be accessible..."
+            for j in {1..15}; do
+                if curl -s -f -H "X-API-Key: $ENVIRONMENT_API_KEY" "$TASK_APP_URL/health" > /dev/null 2>&1; then
+                    echo "✅ Tunnel is accessible!"
+                    break
+                fi
+                if [ $j -eq 15 ]; then
+                    echo "⚠️  Tunnel not yet accessible, but continuing..."
+                fi
+                sleep 2
+            done
+            break
+        fi
+    fi
+    sleep 1
+done
+
+if [ -z "$TASK_APP_URL" ]; then
+    echo "❌ ERROR: Tunnel deployment failed or timed out"
+    echo "   Check deployment logs: /tmp/tunnel_deploy.log"
+    kill $DEPLOY_PID 2>/dev/null || true
+    exit 1
+fi
+
+echo ""
+echo "✅ Tunnel deployed: $TASK_APP_URL"
+echo "   Credentials saved to: $ENV_FILE"
+echo "   Tunnel process PID: $DEPLOY_PID (running in background)"
+
+# Verify backend is accessible
+echo ""
+echo "🔍 Verifying backend connection..."
+if curl -s -f "$BACKEND_URL/api/v1/health" > /dev/null 2>&1; then
+    echo "✅ Backend is accessible"
+else
+    echo "⚠️  Warning: Cannot connect to backend at $BACKEND_URL"
+    echo "   Continuing anyway..."
+fi
+
+# Create GEPA config with tunnel URL
+CONFIG_DIR="$REPO_ROOT/examples/tunnel_gepa_banking77"
+mkdir -p "$CONFIG_DIR"
+CONFIG_FILE="$CONFIG_DIR/banking77_gepa_tunnel.toml"
+
+echo ""
+echo "📝 Creating GEPA config: $CONFIG_FILE"
+# Copy the base config from existing Banking77 GEPA example and update task_app_url
+BASE_CONFIG="$REPO_ROOT/examples/blog_posts/gepa/configs/banking77_gepa_local.toml"
+if [ -f "$BASE_CONFIG" ]; then
+    # Copy base config and update task_app_url
+    cp "$BASE_CONFIG" "$CONFIG_FILE"
+    # Update task_app_url using sed (works on macOS and Linux)
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        sed -i '' "s|task_app_url = \".*\"|task_app_url = \"$TASK_APP_URL\"|" "$CONFIG_FILE"
+    else
+        sed -i "s|task_app_url = \".*\"|task_app_url = \"$TASK_APP_URL\"|" "$CONFIG_FILE"
+    fi
+    echo "✅ Config created from: $BASE_CONFIG"
+    echo "   Updated task_app_url to: $TASK_APP_URL"
+else
+    echo "❌ ERROR: Base config not found: $BASE_CONFIG"
+    echo "   Please ensure the Banking77 GEPA example config exists"
+    exit 1
+fi
+
+# Run GEPA optimization
+echo "🎯 Starting GEPA prompt optimization..."
+echo "   Config: $CONFIG_FILE"
+echo "   Backend: $BACKEND_URL"
+echo "   Task App: $TASK_APP_URL"
+echo ""
+echo "⚠️  Note: Keep the tunnel process running in another terminal"
+echo "   The tunnel will close when you stop the deployment process"
+echo ""
+
+export BACKEND_BASE_URL="$BACKEND_URL"
+export SYNTH_BASE_URL="$BACKEND_URL"
+
+# Run GEPA optimization
+# The tunnel is already running (uvicorn in background thread, cloudflared process)
+# We'll run GEPA training which will submit the job to the backend
+echo ""
+echo "🚀 Starting GEPA prompt optimization..."
+echo "   Config: $CONFIG_FILE"
+echo "   Backend: $BACKEND_URL"
+echo "   Task App: $TASK_APP_URL"
+echo ""
+echo "⚠️  Note: The tunnel process is running in the background."
+echo "   Keep this terminal open until training completes."
+echo ""
+
+export BACKEND_BASE_URL="$BACKEND_URL"
+export SYNTH_BASE_URL="$BACKEND_URL"
+
+# Run GEPA training
+# Use --env-file to skip the interactive prompt
+uv run synth-ai train \
+    --type prompt_learning \
+    --config "$CONFIG_FILE" \
+    --backend "$BACKEND_URL" \
+    --env-file "$ENV_FILE" \
+    --poll
+
+echo ""
+echo "✅ GEPA optimization complete!"
+echo ""
+
+# Cleanup: stop tunnel processes
+echo "🧹 Cleaning up tunnel processes..."
+kill $DEPLOY_PID 2>/dev/null || true
+pkill -f "cloudflared.*8102" 2>/dev/null || true
+pkill -f "uvicorn.*8102" 2>/dev/null || true
+sleep 1
+
+echo ""
+echo "📊 Results:"
+echo "   - Config: $CONFIG_FILE"
+echo "   - Tunnel URL: $TASK_APP_URL"
+echo "   - Credentials: $ENV_FILE"
+echo ""
+echo "💡 To view results, check the job status in the Synth dashboard:"
+echo "   https://app.usesynth.ai"
+

examples/vlm/PROPOSAL.md

@@ -0,0 +1,53 @@
+# Crafter VLM Fine-Tuning Plan
+
+## Why
+
+Crafter observations already expose 64×64 RGB frames, but until now the stack only
+surfaced text summaries. The new multimodal trace format allows us to:
+
+- Retrieve and persist `observation_image_base64` on every step.
+- Thread data URLs through policy prompts so LLMs see the raw frame.
+- Emit multimodal content parts inside LLM call records (and therefore SFT datasets).
+- Capture the same information inside the session trace (`policy_user_prompt` entries).
+
+This unlocks a supervised dataset for vision‑language models that treat the frame as a
+first-class token alongside the textual state summary.
+
+## What Changed
+
+1. **Environment wrappers** now attach `observation_image_base64`, `..._data_url`,
+   and image metadata to every observation (initialise + step).
+2. **Crafter policy** augments the user prompt with `{"type":"image_url"}` segments
+   while still emitting the textual summary for language-only models.
+3. **Tracing** stores structured prompt content and serialises it to JSON so prompts
+   with images survive the round-trip to SQLite/Turso.
+4. **Dataset exporter** preserves multimodal content, flags rows with images, and
+   carries this metadata through SFT JSONL.
+5. **Utility scripts** under `examples/vlm/` make it easy to sanity check frames,
+   filter datasets, and spin up an image-aware training job.
+
+## Proposed Workflow
+
+1. **Collect rollouts** with tracing enabled (either via the task app or scripted
+   runs) to populate `traces/v3/synth_ai.db`.
+2. **Export** using `export_trace_sft.py` — images are embedded automatically.
+3. **Filter** to rows with user images (see `filter_image_rows.py`) and optionally
+   build validation splits.
+4. **Upload** the JSONL via `run_fft_and_save.py` or the Synth CLI.
+5. **Train** with a VLM-capable base model (e.g. `openai/gpt-4o-mini-2024-07-18`)
+   using `configs/crafter_vlm_gpt4o.toml`.
+6. **Evaluate** the resulting checkpoint on Crafter tasks (reuse the evaluation
+   harness from `examples/warming_up_to_rl` but now with multimodal prompts).
+
+## Open Questions / Future Work
+
+- **Longer context**: investigate packing multiple sequential frames per turn
+  (e.g. last N frames) as either separate image parts or a stitched sprite sheet.
+- **Reward shaping**: extend metadata so SFT rows carry frame-level reward deltas,
+  enabling hybrid BC + value regression objectives.
+- **Assistant images**: currently most assistant messages are textual; we could
+  experiment with returning thumbnails explaining the plan.
+- **Automated filtering**: add CLI helpers to keep only turns whose tool calls led
+  to high-reward outcomes (e.g. achievements).
+- **Evaluation**: define a reference set of human-labelled “vision checkpoints”
+  (e.g. recognise nearby resource, detect threats) to quantify multimodal progress.

examples/vlm/README.md

@@ -0,0 +1,68 @@
+# Crafter VLM Pipeline
+
+This folder captures the reference workflow for fine-tuning Crafter policies with
+multimodal (text + image) prompts. It stitches together the new image-aware tracing
+plumbing with lightweight utilities for dataset curation and training.
+
+## Quick Start
+
+1. **Verify image capture**  
+   ```
+   uv run python examples/vlm/crafter_image_only_agent.py --seed 7 --steps 5
+   ```
+   This writes PNG frames to `examples/vlm/output/frames/` and produces a JSONL preview
+   of OpenAI-style image-only user messages.
+
+2. **Collect traced rollouts**  
+   Use the Crafter task app (or your existing pipeline) with tracing enabled. The new
+   tracing schema automatically records `observation_image_base64` and stores image parts
+   in LM call records.
+
+3. **Export multimodal SFT rows**  
+   ```
+   uv run python examples/warming_up_to_rl/export_trace_sft.py \
+      --db traces/v3/task_app_traces_<timestamp>.db \
+       --output examples/vlm/output/crafter_sft_full.jsonl
+   ```
+   The exporter now emits `metadata.has_image`, `metadata.user_has_image`, and
+   `metadata.assistant_has_image` flags per turn.
+
+4. **Filter to image-rich turns**  
+   ```
+   uv run python examples/vlm/filter_image_rows.py \
+       --input examples/vlm/output/crafter_sft_full.jsonl \
+       --output examples/vlm/output/crafter_vlm_dataset.jsonl
+   ```
+
+5. **(Optional) Split validation or augment**, then upload using the standard CLI:
+   ```
+   uv run python examples/warming_up_to_rl/run_fft_and_save.py \
+       --toml examples/vlm/configs/crafter_vlm_gpt4o.toml \
+       --data examples/vlm/output/crafter_vlm_dataset.jsonl
+   ```
+
+## Config & Utilities
+
+| File | Purpose |
+| --- | --- |
+| `configs/crafter_vlm_gpt4o.toml` | Sample Synth job targeting an image-capable model (`openai/gpt-4o-mini`). Set `job.data` or pass `--data` explicitly. |
+| `crafter_image_only_agent.py` | Captures frames and builds image-only prompts for sanity checks. |
+| `filter_image_rows.py` | Extracts rows with image parts from exported JSONL datasets. |
+
+## Notes & Next Steps
+
+- The training config assumes full-finetuning (`mode = "sft_offline"`). Adjust the
+  model id, hardware, or hyperparameters to match available infrastructure.
+- Dataset rows emitted by `export_trace_sft.py` already contain OpenAI multimodal
+  content parts like:
+  ```json
+  {
+    "role": "user",
+    "content": [
+      {"type": "text", "text": "..."},
+      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..." }}
+    ]
+  }
+  ```
+- See `PROPOSAL.md` for a deeper dive into outstanding work (longer rollouts,
+  richer multimodal augmentations, evaluation ideas).

examples/vlm/configs/crafter_vlm_gpt4o.toml

@@ -0,0 +1,49 @@
+[algorithm]
+type = "offline"
+method = "sft"
+variety = "fft"
+
+[job]
+model = "openai/gpt-4o-mini-2024-07-18"
+modalities = ["text", "image"]
+# data = "examples/vlm/output/crafter_vlm_dataset.jsonl"
+description = "Crafter VLM SFT (text + image prompts)"
+
+[compute]
+gpu_type = "A100"
+gpu_count = 1
+nodes = 1
+
+[data]
+topology = {}
+# validation_path = "examples/vlm/output/crafter_vlm_dataset.val.jsonl"
+
+[training]
+mode = "sft_offline"
+use_qlora = false
+
+[training.validation]
+enabled = true
+evaluation_strategy = "steps"
+eval_steps = 50
+save_best_model_at_end = true
+metric_for_best_model = "val.loss"
+greater_is_better = false
+
+[hyperparameters]
+n_epochs = 1
+train_kind = "fft"
+per_device_batch = 1
+gradient_accumulation_steps = 32
+sequence_length = 4096
+learning_rate = 1e-5
+warmup_ratio = 0.03
+weight_decay = 0.01
+
+[hyperparameters.parallelism]
+use_deepspeed = true
+deepspeed_stage = 2
+fsdp = false
+bf16 = true
+fp16 = false
+activation_checkpointing = true