synth-ai 0.2.14__py3-none-any.whl → 0.4.1__py3-none-any.whl

examples/crafter_debug_render.py

@@ -1,186 +0,0 @@
-#!/usr/bin/env python3
-"""
-Quick local Crafter observation inspector.
-
-- Initializes a CrafterClassic env via local service (default http://localhost:8901)
-- Fetches one observation
-- Renders a 7x7 semantic view around the player with best-effort item names
-- Prints status (health/food/energy), inventory, and achievements
-
-Run:
-  uv run python examples/crafter_debug_render.py --base-url http://localhost:8901 --seed 1
-"""
-
-import argparse
-import contextlib
-import math
-import os
-from typing import Any
-
-import httpx
-
-
-def try_import_crafter_mapping():
-    try:
-        import crafter  # type: ignore
-
-        env = crafter.Env()
-        try:
-            max_id = (
-                max(max(env._world._mat_ids.values()), max(env._sem_view._obj_ids.values())) + 1
-            )
-            id_to_item = ["void"] * max_id
-            for name, ind in env._world._mat_ids.items():
-                label = name.__name__ if hasattr(name, "__name__") else str(name)
-                id_to_item[ind] = label.lower()
-            for name, ind in env._sem_view._obj_ids.items():
-                label = name.__name__ if hasattr(name, "__name__") else str(name)
-                id_to_item[ind] = label.lower()
-            return id_to_item
-        finally:
-            with contextlib.suppress(Exception):
-                env.close()
-    except Exception:
-        return None
-
-
-def format_semantic_map_view(obs: dict[str, Any], view_size: int = 7) -> str:
-    sem = obs.get("semantic_map") or obs.get("sem_map") or obs.get("map")
-    if sem is None:
-        return "No semantic map available"
-
-    # Normalize to 2D grid
-    grid: list[list[int]]
-    if isinstance(sem, list) and sem and isinstance(sem[0], list):
-        grid = sem
-    elif isinstance(sem, list):
-        try:
-            n = int(math.sqrt(len(sem)))
-            if n * n != len(sem) or n == 0:
-                return "Semantic map format not recognized"
-            grid = [sem[i * n : (i + 1) * n] for i in range(n)]
-        except Exception:
-            return "Semantic map format not recognized"
-    else:
-        return "Semantic map format not recognized"
-
-    rows = len(grid)
-    cols = len(grid[0]) if rows > 0 else 0
-    if rows == 0 or cols == 0:
-        return "Empty semantic map"
-
-    # Resolve item mapping if available
-    id_to_item = try_import_crafter_mapping()
-
-    # Player position if provided; otherwise center
-    ppos = obs.get("player_position") or [rows // 2, cols // 2]
-    try:
-        px = int(ppos[0])
-        py = int(ppos[1])
-    except Exception:
-        px, py = rows // 2, cols // 2
-
-    half = max(1, view_size // 2)
-    lines: list[str] = []
-    visible: set[str] = set()
-    for dy in range(-half, half + 1):
-        row_cells: list[str] = []
-        for dx in range(-half, half + 1):
-            x = px + dx
-            y = py + dy
-            if dx == 0 and dy == 0:
-                row_cells.append("you")
-            elif 0 <= x < rows and 0 <= y < cols:
-                try:
-                    val = int(grid[x][y])
-                except Exception:
-                    val = -1
-                if id_to_item and 0 <= val < len(id_to_item):
-                    name = id_to_item[val]
-                else:
-                    # Fallback: simple mapping for common ids (best-effort)
-                    name = {
-                        0: "grass",
-                        1: "stone",
-                        2: "stone",
-                        3: "tree",
-                        4: "coal",
-                        5: "iron",
-                        6: "water",
-                        7: "zombie",
-                        14: "wood",
-                    }.get(val, str(val))
-                row_cells.append(name)
-                if name not in {"grass", "you", "0"}:
-                    visible.add(name)
-            else:
-                row_cells.append("void")
-        lines.append(" ".join(row_cells))
-
-    legend = (
-        f"Visible items: {', '.join(sorted(visible))}" if visible else "No notable items visible"
-    )
-    return "\n".join(lines) + "\n" + legend
-
-
-async def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument(
-        "--base-url", default=os.getenv("CRAFTER_BASE_URL", "http://localhost:8901")
-    )
-    parser.add_argument("--seed", type=int, default=1)
-    args = parser.parse_args()
-
-    async with httpx.AsyncClient(timeout=30.0) as client:
-        init = await client.post(
-            f"{args.base_url}/env/CrafterClassic/initialize",
-            json={"config": {"difficulty": "easy", "seed": args.seed}},
-        )
-        init.raise_for_status()
-        data = init.json()
-        env_id = data["env_id"]
-        obs = data["observation"]
-
-        print("=== INITIAL OBSERVATION ===")
-        print(format_semantic_map_view(obs, view_size=7))
-        inv = obs.get("inventory", {})
-        ach = obs.get("achievements_status", {})
-        print("\n=== STATUS ===")
-        print(f"Health: {obs.get('health', 10)}/10")
-        print(f"Hunger: {obs.get('food', 10)}/10")
-        print(f"Energy: {obs.get('energy', 10)}/10")
-        inv_items = (
-            ", ".join([f"{k}: {v}" for k, v in inv.items() if v])
-            if isinstance(inv, dict)
-            else str(inv)
-        )
-        print(f"Inventory: {inv_items if inv_items else 'empty'}")
-        if isinstance(ach, dict):
-            unlocked = sum(1 for v in ach.values() if v)
-            print(f"Achievements: {unlocked}/{len(ach)} unlocked")
-
-        # Take one step right to get a new obs
-        step = await client.post(
-            f"{args.base_url}/env/CrafterClassic/step",
-            json={
-                "env_id": env_id,
-                "action": {"tool_calls": [{"tool": "interact", "args": {"action": 2}}]},
-            },
-        )
-        step.raise_for_status()
-        sdata = step.json()
-        sobs = sdata["observation"]
-        print("\n=== NEXT OBSERVATION (after move_right) ===")
-        print(format_semantic_map_view(sobs, view_size=7))
-
-        # Cleanup
-        with contextlib.suppress(Exception):
-            await client.post(
-                f"{args.base_url}/env/CrafterClassic/terminate", json={"env_id": env_id}
-            )
-
-
-if __name__ == "__main__":
-    import asyncio
-
-    asyncio.run(main())

examples/dev/qwen3_32b_qlora_4xh100.toml

@@ -1,40 +0,0 @@
-[job]
-model = "Qwen/Qwen3-32B"
-# Optionally set here; you can also pass --dataset
-# data = "/abs/path/to/train.jsonl"
-
-[compute]
-gpu_type = "H100"
-gpu_count = 4
-nodes = 1
-
-[data]
-# Optional; forwarded into metadata.effective_config.data.topology
-topology = { container_count = 4 }
-
-[training]
-mode = "sft_offline"
-use_qlora = true
-
-[training.validation]
-enabled = true
-evaluation_strategy = "steps"
-eval_steps = 20
-save_best_model_at_end = true
-metric_for_best_model = "val.loss"
-greater_is_better = false
-
-[hyperparameters]
-n_epochs = 1
-per_device_batch = 1
-gradient_accumulation_steps = 64
-sequence_length = 4096
-learning_rate = 5e-6
-warmup_ratio = 0.03
-
-[hyperparameters.parallelism]
-use_deepspeed = true
-deepspeed_stage = 2
-bf16 = true
-fp16 = false
-fsdp = false

examples/multi_step/configs/README_verilog_rl.md

@@ -1,77 +0,0 @@
-# Verilog RL with LoRA (Qwen3-0.6B)
-
-## Quick Start
-
-1. **Deploy Verilog Task App**:
-```bash
-cd synth-ai
-uvx synth-ai modal-serve grpo-verilog
-```
-Note the Modal URL and update `task_url` in `verilog_rl_lora.toml`.
-
-2. **Run Training**:
-```bash
-uvx synth-ai rl run --config examples/multi_step/configs/verilog_rl_lora.toml
-```
-
-## Configuration Overview
-
-### **Key Adaptations from Crafter**:
-
-- **Model**: `Qwen/Qwen3-0.6B` (✅ proven in SFT configs)
-- **Environment**: `verilog` instead of `crafter`
-- **Steps**: 15 turns (vs Crafter's 10) for compilation workflows
-- **Rewards**: Adjusted for sparser Verilog rewards (0.5 vs 1.0 indicator_lambda)
-- **Rubrics**: Verilog-specific judging criteria
-
-### **Hardware Requirements** (Standard RL setup):
-- ✅ **2x H100 GPUs** (vLLM inference + LoRA training split)
-- ✅ **No tensor parallelism** needed for 0.6B model
-- ✅ **4x faster inference** than 32B model
-- ✅ **Same compute pattern** as Crafter (just smaller model)
-
-### **Expected Workflow**:
-1. Agent writes Verilog code (`write_file`)
-2. Compiles to check syntax (`compile`)
-3. Simulates to verify behavior (`simulate`)
-4. Submits if tests pass (`submit`)
-5. **Rewards**: +1.0 for compilation success, +10.0 for passing tests
-
-## Rubric Design
-
-### **Event Rewards** (per decision):
-- **Compilation Success**: 70% weight (1.0 for success, 0.0 for errors)
-- **Process Efficiency**: 30% weight (penalizes redundant operations)
-
-### **Outcome Rewards** (final score):
-- **Tests Passed**: 80% weight (full credit when all tests pass)
-- **Design Quality**: 20% weight (code clarity, documentation)
-
-## Troubleshooting
-
-### **If training fails**:
-1. Check Modal URL in `task_url` field
-2. Verify `GROQ_API_KEY` for inference
-3. Ensure `OPENAI_API_KEY` for judging
-
-### **Memory issues** (unlikely with 0.6B):
-- Reduce `batch_size` to 2
-- Set `gradient_accumulation_steps = 2`
-- Verify 2x GPU split is working (vLLM on GPU 0, training on GPU 1)
-
-### **Slow training**:
-- Increase `episodes_per_batch` to 6-8
-- Check network latency to Modal task app
-
-## Expected Results
-
-- **Convergence**: Should learn basic compilation workflow in 1-2 hours
-- **Success Rate**: 20-40% initial test pass rate (improves with training)
-- **Learning**: Agent learns to debug compilation errors and write correct Verilog
-
-## Next Steps
-
-1. **Monitor reward progression** in training logs
-2. **Adjust rubrics** if agent struggles with compilation errors
-3. **Scale to 8B model** once 0.6B baseline works
-4. **Add domain-specific fine-tuning** for Verilog syntax

examples/multi_step/configs/VERILOG_REWARDS.md

@@ -1,90 +0,0 @@
-# Verilog Reward Structure (Normalized to 1.0)
-
-## Overview
-All rewards in the Verilog task app are normalized so the maximum possible reward is **1.0**.
-
-## Reward Components
-
-### 1. Step Penalty: **-0.001** per step
-- Applied to every action taken
-- Encourages efficient solutions
-- Normalized from `-0.01` (original)
-
-### 2. Compile Success: **+0.01**
-- Awarded when `iverilog` compilation succeeds (returncode 0)
-- Validates syntax correctness
-- Normalized from `+0.1` (original)
-
-### 3. Simulation Pass: **+0.1**
-- Awarded when `vvp` simulation passes all tests
-- Validates behavioral correctness
-- Normalized from `+1.0` (original)
-
-### 4. Submit Success: **+1.0** (maximum reward)
-- Awarded when final submission passes all verification tests
-- This is the goal state
-- Normalized from `+10.0` (original)
-
-## Typical Reward Trajectories
-
-### ✅ Optimal Path (3 steps)
-```
-Step 1: write_file        → -0.001
-Step 2: compile (success) → +0.01 - 0.001 = +0.009
-Step 3: simulate (pass)   → +0.1 - 0.001 = +0.099
-Total:                      ~0.107
-```
-
-### ✅ Good Path (4 steps with submit)
-```
-Step 1: write_file        → -0.001
-Step 2: compile (success) → +0.009
-Step 3: simulate (pass)   → +0.099
-Step 4: submit (success)  → +1.0 - 0.001 = +0.999
-Total:                      ~1.106
-```
-*Note: Can exceed 1.0 if intermediate rewards stack with final submit*
-
-### ❌ Failure Path (compilation errors)
-```
-Step 1: write_file        → -0.001
-Step 2: compile (fail)    → -0.001
-Step 3: write_file (fix)  → -0.001
-Step 4: compile (success) → +0.009
-Step 5: simulate (pass)   → +0.099
-Total:                      ~0.105
-```
-
-## Implementation Details
-
-### Location
-- **Reward components**: `synth_ai/environments/examples/verilog/engine.py`
-  - `VerilogCompileSuccessComponent`: +0.01
-  - `VerilogSimulationPassComponent`: +0.1
-  - `VerilogSubmitSuccessComponent`: +1.0
-  - `VerilogStepPenaltyComponent`: -0.001
-
-### Normalization Ratio
-All rewards were divided by **10.0** to normalize:
-- Original max: ~10.0
-- Normalized max: ~1.0
-- Ratio: 10.0
-
-## Why Normalize?
-
-1. **Consistency**: Makes it easier to compare rewards across different task types
-2. **RL Training**: Standard reward scales improve learning stability
-3. **Interpretability**: Rewards as percentages (0.0 to 1.0) are intuitive
-4. **Judge Compatibility**: Rubric scores typically range 0-1, making blending easier
-
-## Testing
-```bash
-# Run eval to verify normalized rewards
-uvx synth-ai eval --config examples/multi_step/configs/verilog_eval_groq_qwen32b.toml
-```
-
-Expected output for successful rollout:
-- `mean_return` ≈ 0.1 (if only compile+simulate)
-- `mean_return` ≈ 1.0+ (if full submit success)
-
-

examples/multi_step/configs/VERILOG_RL_CHECKLIST.md

@@ -1,183 +0,0 @@
-# Verilog Task App - RL Training Readiness Checklist
-
-## ✅ Core Requirements
-
-### 1. Reward Normalization
-- ✅ **Max reward = 1.0**: All rewards scaled to `[0, 1]` range
-- ✅ **Step penalty**: `-0.001` (normalized from `-0.01`)
-- ✅ **Compile success**: `+0.01` (normalized from `+0.1`)
-- ✅ **Simulate pass**: `+0.1` (normalized from `+1.0`)
-- ✅ **Submit success**: `+1.0` (normalized from `+10.0`)
-
-### 2. Inference URL Handling (Critical for Trace Correlation)
-- ✅ **Extracts from policy config**: Uses `policy_config.get("inference_url")` as primary source
-- ✅ **Includes in trajectory**: Sets `trajectory.inference_url` with `?cid=...` parameter
-- ✅ **Includes in final.info**: Adds to `final["info"]["inference_url"]`
-- ✅ **Includes in pipeline_metadata**: Top-level `inference_url` field for trainer extraction
-- ✅ **Logs cid presence**: Logs `has_cid` flag for debugging
-- ✅ **Fallback to agent.inference_url**: Uses agent's URL if policy config missing (eval mode)
-
-**Location**: `grpo_verilog.py` lines 829-867, 887-908
-
-### 3. Pipeline Metadata
-- ✅ **Required fields present**:
-  - `reward_score`: Final episode reward
-  - `policy_id`: Policy identifier
-  - `inference_url`: **CRITICAL** - Contains `?cid=trace_xxxxx` for correlation
-  - `env_name`: Environment identifier
-  - `task_id`: Problem identifier
-  - `task_split`: Dataset split (train/val/test)
-- ✅ **Inference details**: Provider, model, URL in nested `inference` dict
-
-**Location**: `grpo_verilog.py` lines 887-908
-
-### 4. Trace Correlation (Required for RL Training)
-- ✅ **Trainer injects cid**: Trainer adds `?cid=trace_xxxxx` to `policy_config["inference_url"]`
-- ✅ **Task app preserves cid**: Uses `policy_config["inference_url"]` directly
-- ✅ **Trainer extracts cid**: Extracts from `trajectory.inference_url` using `inference_url_to_trace_correlation_id()`
-- ✅ **Trace hydration**: Trainer queries trace store with extracted `trace_correlation_id`
-
-**Flow**:
-```
-Trainer → policy_config["inference_url"] = "http://...?cid=trace_xxxxx"
-         ↓
-Task App → trajectory.inference_url = policy_config["inference_url"]
-         ↓
-Trainer → extract_trace_correlation_id(trajectory.inference_url)
-         ↓
-Trainer → trace_store.resolve_correlation(trace_correlation_id)
-         ↓
-Trainer → Hydrate v3 trace with event_history
-         ↓
-Judge   → Score using full trace
-```
-
-### 5. Response Contract Compliance
-- ✅ **RolloutResponse fields**:
-  - `run_id`: Unique identifier
-  - `trajectories`: List of trajectories (with `inference_url`)
-  - `metrics`: Episode metrics
-  - `pipeline_metadata`: **CRITICAL** - Contains `inference_url` and `reward_score`
-  - `trace_correlation_id`: Optional (trainer infers from `inference_url`)
-- ✅ **Optional trace_correlation_id**: Made optional in `contracts.py` (trainer infers from URL)
-
-**Location**: `synth_ai/task/contracts.py` line 156
-
-### 6. Environment Implementation
-- ✅ **Stateful engine**: `VerilogEngine` extends `StatefulEngine`
-- ✅ **Reward stack**: Properly configured with normalized components
-- ✅ **State management**: `VerilogPublicState` and `VerilogPrivateState`
-- ✅ **Tool implementation**: All 4 tools (write_file, compile, simulate, submit)
-
-**Location**: `synth_ai/environments/examples/verilog/engine.py`
-
-### 7. LLM Agent Integration
-- ✅ **Multi-turn support**: Agent maintains conversation history
-- ✅ **Tool parsing**: Extracts tool calls from LLM responses
-- ✅ **Guidance system**: Provides context-aware hints
-- ✅ **Error handling**: Graceful fallback for malformed responses
-
-**Location**: `grpo_verilog.py` lines 200-530
-
-## 🔍 Verification Tests
-
-### Test 1: Eval Mode (No Trace Correlation)
-```bash
-uvx synth-ai eval --config examples/multi_step/configs/verilog_eval_groq_qwen32b.toml
-```
-**Expected**:
-- ✅ `mean_return` ≈ 0.1 (normalized rewards)
-- ✅ `inference_url` = Groq API URL (no `?cid=...`)
-- ✅ `task_completed` = True for correct solutions
-
-### Test 2: RL Training Mode (With Trace Correlation)
-```bash
-uvx synth-ai train \
-  --type rl \
-  --config examples/multi_step/configs/verilog_rl_lora.toml \
-  --task-url https://synth-laboratories--grpo-verilog-task-app-fastapi-app-dev.modal.run \
-  --backend https://synth-backend-dev-docker.onrender.com/api \
-  --env-file /path/to/verilog/.env
-```
-**Expected**:
-- ✅ Trainer logs show `inference_url` with `?cid=trace_xxxxx`
-- ✅ Task app logs show `has_cid=True`
-- ✅ Trace hydration succeeds (no `404 Not Found` errors)
-- ✅ Judge receives full `event_history`
-- ✅ Training updates show non-zero rewards
-
-### Test 3: Trace Correlation ID Extraction
-```python
-from synth_envs_hosted.utils import inference_url_to_trace_correlation_id
-
-# Should extract trace_xxxxx from URL
-url = "http://localhost:8000/v1/chat/completions?cid=trace_abc123"
-cid = inference_url_to_trace_correlation_id(url)
-assert cid == "trace_abc123"
-```
-
-### Test 4: Pipeline Metadata Structure
-```python
-# Verify response has correct structure for RL
-response = await task_app.rollout(request)
-assert "pipeline_metadata" in response
-assert "inference_url" in response.pipeline_metadata
-assert "reward_score" in response.pipeline_metadata
-assert len(response.trajectories) > 0
-assert response.trajectories[0].inference_url is not None
-```
-
-## 📋 Deployment Checklist
-
-### Modal Deployment
-1. ✅ **Environment variables set**:
-   - `GROQ_API_KEY`
-   - `VERILOG_INFERENCE_URL` (optional, uses Groq default)
-2. ✅ **Secrets configured**: Groq API key in Modal secrets
-3. ✅ **Task app URL**: Update in `verilog_rl_lora.toml`
-
-### Training Configuration
-1. ✅ **2x GPUs minimum**: 1 for vLLM, 1 for training
-2. ✅ **Model size**: `Qwen/Qwen3-0.6B` for testing
-3. ✅ **Batch size**: 4 (matches Crafter)
-4. ✅ **Max turns**: 15 (enough for compile chains)
-5. ✅ **Rubric enabled**: `rubric.enabled = true`
-
-## 🚨 Common Issues & Fixes
-
-### Issue 1: `trace_correlation_id` Missing
-**Symptom**: Trainer logs `FATAL: Rollout payload missing 'trace_correlation_id'`
-**Fix**: Verify `trajectory.inference_url` contains `?cid=...` parameter
-
-### Issue 2: Trace Hydration Fails (404)
-**Symptom**: `404 Not Found` when querying `/trace/by-correlation/...`
-**Fix**: 
-- Check inference server is capturing traces
-- Verify `cid` parameter is in inference URL
-- Ensure `vllm_public_url` is set correctly
-
-### Issue 3: Rewards Not Normalized
-**Symptom**: `mean_return` > 1.0 in eval
-**Fix**: Verify all reward components in `engine.py` are scaled by 10x
-
-### Issue 4: Agent Gets Stuck
-**Symptom**: Agent repeats same action (e.g., compile without fixing)
-**Fix**: Check guidance system is providing proper hints
-
-## 🎯 Final Verification
-
-Before starting RL training, verify:
-- [ ] Eval runs successfully with normalized rewards (≈ 0.1)
-- [ ] Modal deployment returns proper `inference_url` structure
-- [ ] Trace correlation ID extraction works
-- [ ] Pipeline metadata includes all required fields
-- [ ] Response contract matches expected schema
-
-**If all checks pass**: ✅ **Ready for RL training!**
-
-## 📚 Related Documentation
-- [VERILOG_REWARDS.md](./VERILOG_REWARDS.md) - Reward structure details
-- [verilog_rl_lora.md](../verilog_rl_lora.md) - RL/LoRA feasibility analysis
-- [verilog_rl_lora.toml](./verilog_rl_lora.toml) - Training configuration
-
-

examples/multi_step/configs/crafter_eval_synth_qwen4b.toml

@@ -1,35 +0,0 @@
-# Crafter eval using Synth backend with Qwen3-4B
-
-[eval]
-app_id = "grpo-crafter-task-app"
-task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
-model = "Qwen/Qwen3-4B"
-seeds = [0, 1, 2]
-max_turns = 10
-concurrency = 1
-env_name = "crafter"
-policy_name = "crafter-react"
-trace_format = "full"
-return_trace = true
-
-[eval.env_config]
-env_params = {max_steps_per_episode = 10}
-
-[eval.policy_config]
-provider = "openai"
-model = "Qwen/Qwen3-4B"
-inference_url = "https://synth-backend-dev-docker.onrender.com/api/v1/chat/completions"
-temperature = 0.6
-top_p = 0.95
-max_tokens = 512
-use_vision = false
-image_only_mode = false
-max_llm_calls = 10
-
-[eval.judge]
-path = "examples/multi_step/judges/crafter_backend_judge.py"
-name = "Backend"
-backend_url = "http://localhost:8000/api"
-model = "openai/gpt-oss-120b"
-timeout_s = 45
-

examples/multi_step/configs/crafter_eval_text_only_groq_qwen32b.toml

@@ -1,36 +0,0 @@
-# Evaluation config for Crafter with text-only input
-# This config uses Groq Qwen with only text observations (no images)
-
-[eval]
-app_id = "grpo-crafter-task-app"
-task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
-model = "qwen/qwen3-32b"
-seeds = [0, 1, 2]
-max_turns = 10
-concurrency = 1
-env_name = "crafter"
-policy_name = "crafter-react"
-trace_format = "full"
-return_trace = true
-
-[eval.env_config]
-env_params = {max_steps_per_episode = 10}
-
-[eval.policy_config]
-provider = "groq"
-model = "qwen/qwen3-32b"
-inference_url = "https://api.groq.com/openai/v1/chat/completions"
-temperature = 0.6
-top_p = 0.95
-max_tokens = 512
-use_vision = false
-image_only_mode = false
-max_llm_calls = 10
-
-[eval.judge]
-path = "examples/multi_step/judges/crafter_backend_judge.py"
-name = "Backend"
-backend_url = "http://localhost:8000/api"
-model = "openai/gpt-oss-120b"
-timeout_s = 45
-