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

examples/blog_posts/warming_up_to_rl/SMOKE_TESTING.md

@@ -0,0 +1,164 @@
+# Smoke Testing Your Task App
+
+This guide shows how to quickly test your task app using the `synth-ai smoke` command with auto-start features.
+
+## Quick Start
+
+The easiest way to smoke test is using the `[smoke]` section in your RL config:
+
+```bash
+cd examples/blog_posts/warming_up_to_rl
+uv run synth-ai smoke --config configs/smoke_test.toml
+```
+
+**That's it!** The smoke command will:
+1. ✅ Auto-start sqld server for tracing (if `sqld_auto_start = true`)
+2. ✅ Auto-start your task app on port 8765 (if `task_app_name` is set)
+3. ✅ Run 10 rollout steps with `gpt-5-nano` using synthetic mocking
+4. ✅ Automatically stop all background services when done
+
+**Expected output:**
+```
+[smoke] sqld ready
+[smoke] Task app ready at http://localhost:8765 (status=400)
+[mock-rl] server ready http://127.0.0.1:51798 backend=synthetic
+>> POST /rollout run_id=smoke-... env=crafter policy=crafter-react
+[mock-rl] ← request backend=synthetic model=gpt-5-nano messages=2
+[mock-rl] → response tool_calls=1 backend=synthetic
+  rollout[0:0] episodes=1 steps=10 mean_return=1.0000
+✓ Smoke rollouts complete
+  successes=1/1 total_steps=10 v3_traces=1/1 nonzero_returns=1/1
+[smoke] Background services stopped
+```
+
+## Configuration
+
+Add a `[smoke]` section to your RL config:
+
+```toml
+[smoke]
+# Auto-start task app
+task_app_name = "grpo-crafter"
+task_app_port = 8765
+task_app_env_file = ".env"
+task_app_force = true
+
+# Auto-start sqld
+sqld_auto_start = true
+sqld_db_path = "./traces/local.db"
+sqld_hrana_port = 8080
+sqld_http_port = 8081
+
+# Test parameters
+max_steps = 10
+policy = "gpt-5-nano"
+mock_backend = "synthetic"  # or "openai" (requires valid OpenAI API key)
+return_trace = true
+```
+
+## Testing Methods
+
+### 1. Full Auto (Recommended)
+Everything auto-starts from config:
+```bash
+uv run synth-ai smoke --config configs/smoke_test.toml
+```
+
+### 2. Manual Task App + Auto sqld
+Start task app manually, auto-start sqld:
+```bash
+# Config with sqld_auto_start=true but no task_app_name
+uv run synth-ai smoke --config configs/my_config.toml --url http://localhost:8765
+```
+
+### 3. Override Config Settings
+Override any config value via CLI:
+```bash
+uv run synth-ai smoke --config configs/smoke_test.toml --max-steps 5
+```
+
+### 4. No Config (Manual Everything)
+```bash
+# Start services manually in separate terminals:
+# Terminal 1: sqld --db-path ./traces/local.db --hrana-listen-addr 127.0.0.1:8080 --http-listen-addr 127.0.0.1:8081
+# Terminal 2: uv run synth-ai task-app serve grpo-crafter --port 8765 --env-file .env --force
+
+# Terminal 3: Run smoke test
+uv run synth-ai smoke --url http://localhost:8765 \
+  --env-name crafter \
+  --policy-name crafter-react \
+  --max-steps 10 \
+  --policy mock \
+  --mock-backend openai
+```
+
+## Prerequisites
+
+### Install sqld (for tracing)
+```bash
+brew install sqld
+# or
+curl -fsSL https://get.turso.com/sqld | bash
+```
+
+### Verify Installation
+```bash
+which sqld
+# Should output: /opt/homebrew/bin/sqld or similar
+```
+
+## Common Issues
+
+### sqld not found
+If you see "sqld not found in PATH":
+```bash
+brew install sqld
+```
+
+### Port already in use
+Use `task_app_force = true` in config, or:
+```bash
+# Kill processes on ports 8080, 8081, 8765
+lsof -ti:8080,8081,8765 | xargs kill -9
+```
+
+### Task app not starting
+Check the error output - you may need:
+- Valid `.env` file with required keys
+- Correct task app name registered in your codebase
+
+## Example Output
+
+```
+[smoke] Loaded configuration from configs/smoke_test.toml
+[smoke] Config keys: task_app_name, task_app_port, sqld_auto_start, max_steps, policy
+[smoke] Starting sqld server...
+[smoke] DB path: /Users/you/project/traces/local.db
+[smoke] Hrana port: 8080, HTTP port: 8081
+[smoke] sqld ready
+[smoke] Starting task app 'grpo-crafter' on port 8765...
+[smoke] Task app ready at http://localhost:8765
+[smoke] Task app started, will use URL: http://localhost:8765
+[mock-rl] server ready http://127.0.0.1:52134 backend=openai
+>> POST /rollout run_id=smoke-abc123...
+  rollout[0:0] episodes=1 steps=20 mean_return=1.2500
+✓ Smoke rollouts complete
+  successes=1/1 total_steps=20 v3_traces=1/1 nonzero_returns=1/1
+[smoke] Stopping sqld...
+[smoke] Stopping task_app...
+[smoke] Background services stopped
+```
+
+## Next Steps
+
+Once smoke tests pass:
+1. Train your model: `uv run synth-ai train --type rl --config configs/your_config.toml`
+2. Check traces: Look in `./traces/` directory
+3. Monitor training: Use the Synth dashboard
+
+## Full Config Reference
+
+See [`configs/smoke_test.toml`](configs/smoke_test.toml) for a complete example.
+
+See [CLI Smoke Documentation](https://docs.usesynth.ai/cli/smoke) for all options.
+

examples/blog_posts/warming_up_to_rl/SMOKE_TEST_COMPLETE.md

@@ -0,0 +1,253 @@
+# Smoke Test Implementation - Complete
+
+## Summary
+
+The smoke test now provides **complete visibility into RL training rollouts**, including:
+
+✅ **Auto-start background services** (sqld, task app)  
+✅ **Real OpenAI inference** with gpt-4o-mini  
+✅ **Tool call display** - see every action the policy takes  
+✅ **Trace validation** - verify v3 trace format  
+✅ **Clean output** - all diagnostic noise suppressed  
+
+## Quick Start
+
+```bash
+cd examples/blog_posts/warming_up_to_rl
+uv run synth-ai smoke --config configs/smoke_test.toml
+```
+
+**Output shows:**
+- Service startup (sqld, task app)
+- Real-time inference requests  
+- **All 10 tool calls with arguments** (e.g., `interact_many({"actions":["move_up","move_up"]})`)
+- Rollout metrics (steps, returns, rewards)
+- Success validation
+
+## Documentation
+
+All documentation has been updated for future agents:
+
+### 1. User Documentation
+- **`SMOKE_TESTING.md`** - How to run smoke tests, what to expect
+- **`configs/smoke_test.toml`** - Well-commented example configuration
+- **`monorepo/docs/cli/smoke.mdx`** - Mintlify CLI documentation
+
+### 2. Developer Documentation  
+- **`ARCHITECTURE.md`** - Internal architecture, troubleshooting guide
+- **`synth_ai/cli/commands/smoke/core.py`** - Extensive inline comments explaining tool call extraction
+
+### 3. Code Comments
+
+**Tool Call Extraction (core.py lines 946-997):**
+```python
+# Extract and display tool calls from v3 trace
+# 
+# IMPORTANT: Tool calls are extracted from the structured v3 trace format.
+# The trace must be requested with return_trace=True for this to work.
+# 
+# Trace structure:
+#   trace.event_history[] - list of events (policy calls, env steps)
+#     ├─ event.call_records[] - LLM calls made during this event
+#        ├─ call_record.output_tool_calls[] - tool calls from LLM response
+#           ├─ tool_call.name - function name (e.g., "interact_many")
+#           └─ tool_call.arguments_json - JSON string of arguments
+```
+
+## Key Implementation Details
+
+### Tool Call Display
+
+**Requirements:**
+1. `return_trace = true` in config (CRITICAL - without this, no tool calls)
+2. v3 trace format (`trace_format="structured"`)
+3. Mock proxy or real inference (direct API calls don't populate traces correctly)
+
+**Data Flow:**
+```
+1. Rollout request with return_trace=True
+   ↓
+2. Task app makes LLM calls, captures responses
+   ↓
+3. LLM responses include tool_calls
+   ↓
+4. Task app stores call_records in event_history
+   ↓
+5. Smoke command extracts from trace.event_history[].call_records[].output_tool_calls[]
+   ↓
+6. Display: TOOL_CALL[N]: function_name({...args})
+```
+
+### Diagnostic Suppression
+
+**Permanently disabled (commented out, not deleted):**
+- `synth_ai/tracing_v3/config.py:21` - `[TRACING_V3_CONFIG_LOADED]`
+- `synth_ai/environments/examples/crafter_classic/engine_deterministic_patch.py` - All `[PATCH]` messages
+- `synth_ai/environments/examples/crafter_classic/engine_serialization_patch_v3.py` - All `[PATCH]` messages
+- `synth_ai/environments/examples/crafter_classic/world_config_patch_simple.py` - All `[PATCH]` messages
+
+**Why commented, not deleted?**
+- Preserves context for debugging
+- Shows what messages existed
+- Easy to re-enable if needed
+
+### Background Service Management
+
+**Task App:**
+- Runs from synth-ai root (required for discovery)
+- Uses `nohup` for detachment
+- Output → `nohup_task_app.out`
+- Health check accepts 200 or 400 (400 = server up, auth failing)
+- 120s timeout with progress updates
+
+**sqld:**
+- Dual ports: 8080 (Hrana WebSocket), 8081 (HTTP)
+- Health check: `GET http://127.0.0.1:8081/health`
+- 30s timeout
+- Auto-cleanup of existing processes
+
+## Configuration Reference
+
+### Critical Settings
+
+```toml
+[smoke]
+# Auto-start services
+task_app_name = "grpo-crafter"  # Task app to serve
+task_app_port = 8765
+task_app_env_file = ".env"      # Required for this app
+sqld_auto_start = true
+
+# Inference - REAL OpenAI
+model = "gpt-4o-mini"           # Actual model used
+mock_backend = "openai"         # Route through OpenAI API
+use_mock = true                 # Enable mock proxy
+
+# CRITICAL for tool call display
+return_trace = true             # Must be true!
+```
+
+### Optional Settings
+
+All `[smoke]` parameters are optional - CLI args override TOML values:
+
+```bash
+# Override max steps
+uv run synth-ai smoke --config configs/smoke_test.toml --max-steps 5
+
+# Use different model
+uv run synth-ai smoke --config configs/smoke_test.toml --model gpt-4o
+
+# Disable mock (use direct API - won't show tool calls properly)
+uv run synth-ai smoke --config configs/smoke_test.toml --no-mock
+```
+
+## Troubleshooting
+
+### No tool calls displayed
+
+**Symptom:** `⚠ No tool calls found in trace`
+
+**Solutions:**
+1. Verify `return_trace = true` in config
+2. Check `v3_traces=1/1` in output (should match successes)
+3. Ensure `use_mock = true` or using mock proxy
+4. Check task app logs: `cat /path/to/synth-ai/nohup_task_app.out`
+
+### Task app exits immediately
+
+**Symptom:** `0 steps`, process not running
+
+**Solutions:**
+1. Verify task app name: `synth-ai task-app list`
+2. Check .env file exists at `task_app_env_file` path
+3. Ensure running from correct directory
+4. Manual test: `cd /synth-ai && uvx synth-ai task-app serve grpo-crafter --port 8765 --env-file /path/.env --force`
+
+### Port conflicts
+
+**Symptom:** `Address already in use`
+
+**Solution:** Auto-cleanup should handle this, but manual cleanup:
+```bash
+lsof -ti :8080 | xargs kill -9
+lsof -ti :8081 | xargs kill -9
+lsof -ti :8765 | xargs kill -9
+```
+
+## Testing
+
+### Unit Tests
+
+- `tests/unit/test_train_validation.py::test_rl_config_with_smoke_section` - Validates `[smoke]` section parsing
+- `tests/unit/test_smoke_config.py` - Comprehensive Pydantic validation tests
+
+### Integration Test
+
+```bash
+cd examples/blog_posts/warming_up_to_rl
+uv run synth-ai smoke --config configs/smoke_test.toml
+```
+
+**Expected result:**
+- ✅ Services start successfully
+- ✅ 10 tool calls displayed
+- ✅ `v3_traces=1/1`
+- ✅ `successes=1/1`
+- ✅ `nonzero_returns=1/1`
+
+## Files Modified
+
+### Core Implementation
+- `synth_ai/cli/commands/smoke/core.py` - Tool call extraction, auto-start logic
+- `synth_ai/api/train/configs/rl.py` - `SmokeConfig` Pydantic model
+- `synth_ai/api/train/builders.py` - Remove `[smoke]` before sending to trainer
+
+### Diagnostic Suppression
+- `synth_ai/tracing_v3/config.py` - Commented out `[TRACING_V3_CONFIG_LOADED]`
+- `synth_ai/environments/examples/crafter_classic/engine_deterministic_patch.py` - Commented out `[PATCH]`
+- `synth_ai/environments/examples/crafter_classic/engine_serialization_patch_v3.py` - Commented out `[PATCH]`
+- `synth_ai/environments/examples/crafter_classic/world_config_patch_simple.py` - Commented out `[PATCH]`
+
+### Documentation
+- `examples/blog_posts/warming_up_to_rl/SMOKE_TESTING.md` - User guide
+- `examples/blog_posts/warming_up_to_rl/ARCHITECTURE.md` - Developer guide
+- `examples/blog_posts/warming_up_to_rl/configs/smoke_test.toml` - Example config
+- `examples/blog_posts/warming_up_to_rl/configs/train_rl_from_sft.toml` - Inline docs
+- `monorepo/docs/cli/smoke.mdx` - Mintlify CLI reference
+
+### Tests
+- `tests/unit/test_train_validation.py` - Added smoke section test
+- `tests/unit/test_smoke_config.py` - Comprehensive smoke config tests
+
+## Future Improvements
+
+Ideas for future agents:
+
+1. **Streaming display** - Show tool calls as they happen, not just at end
+2. **Tool call validation** - Verify format matches environment expectations
+3. **Performance metrics** - Track inference latency per call
+4. **Cost tracking** - Display OpenAI API costs
+5. **Parallel rollouts** - Support concurrent execution testing
+6. **Vision support** - Save observations for vision-based tasks
+7. **Interactive mode** - Step through rollout one action at a time
+8. **Replay mode** - Re-run saved traces for debugging
+
+## Success Criteria Met
+
+✅ **Tool calls visible** - All 10 calls displayed with arguments  
+✅ **Real inference** - OpenAI gpt-4o-mini executing actual tool calls  
+✅ **Clean output** - No diagnostic noise  
+✅ **Auto-start** - Background services managed automatically  
+✅ **Well documented** - Comprehensive docs for users and developers  
+✅ **Robust** - Error handling, health checks, timeouts  
+✅ **Tested** - Unit tests and working integration test  
+
+## Contact
+
+For questions or issues, see:
+- Architecture details: `ARCHITECTURE.md`
+- User guide: `SMOKE_TESTING.md`
+- CLI reference: `monorepo/docs/cli/smoke.mdx`
+
+

examples/blog_posts/warming_up_to_rl/configs/eval_baseline_qwen32b_10x20.toml

@@ -0,0 +1,25 @@
+[eval]
+app_id = "grpo-crafter"
+task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
+model = "Qwen/Qwen3-4B"
+seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+max_turns = 20
+concurrency = 1
+env_name = "crafter"
+policy_name = "crafter-react"
+trace_format = "structured"
+return_trace = true
+
+[eval.policy_config]
+provider = "synth"
+model = "Qwen/Qwen3-4B"
+inference_url = "https://synth-laboratories-dev--learning-v2-service-fastapi-app.modal.run"
+temperature = 0.6
+top_p = 0.95
+max_tokens = 2048
+use_vision = false
+image_only_mode = false
+max_llm_calls = 10
+
+[eval.env_config.env_params]
+max_steps_per_episode = 20

examples/blog_posts/warming_up_to_rl/configs/eval_ft_qwen4b.toml

@@ -0,0 +1,25 @@
+# Evaluate the finetuned Qwen3-4B checkpoint on Crafter.
+# Replace model with the fft: job id returned by the SFT run.
+
+[eval]
+app_id = "grpo-crafter"
+task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
+model = "fft:REPLACE-WITH-SFT-JOB-ID"
+seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+max_turns = 10
+concurrency = 4
+env_name = "crafter"
+policy_name = "crafter-react"
+trace_format = "compact"
+return_trace = false
+
+[eval.policy_config]
+provider = "synth"
+model = "fft:REPLACE-WITH-SFT-JOB-ID"
+temperature = 0.2
+top_p = 0.8
+max_tokens = 512
+use_vision = true
+image_only_mode = false
+max_llm_calls = 10
+tool_choice = "auto"

examples/blog_posts/warming_up_to_rl/configs/eval_ft_qwen4b_10x20.toml

@@ -0,0 +1,26 @@
+[eval]
+app_id = "grpo-crafter"
+task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
+model = "peft:Qwen/Qwen3-4B:job_f774218e6c954517"
+seeds = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+max_turns = 20
+concurrency = 2
+env_name = "crafter"
+policy_name = "crafter-react"
+trace_format = "structured"
+return_trace = true
+
+[eval.policy_config]
+provider = "synth"
+model = "peft:Qwen/Qwen3-4B:job_f774218e6c954517"
+inference_url = "https://synth-laboratories-dev--learning-v2-service-fastapi-app.modal.run"
+temperature = 0.2
+top_p = 0.8
+max_tokens = 1024
+use_vision = false
+image_only_mode = false
+max_llm_calls = 10
+tool_choice = "auto"
+
+[eval.env_config.env_params]
+max_steps_per_episode = 20

examples/blog_posts/warming_up_to_rl/configs/eval_groq_qwen32b.toml

@@ -0,0 +1,25 @@
+[eval]
+app_id = "grpo-crafter"
+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.policy_config]
+provider = "groq"
+model = "qwen/qwen3-32b"
+inference_url = "https://api.groq.com/openai"
+temperature = 0.6
+top_p = 0.95
+max_tokens = 8192
+use_vision = false
+image_only_mode = false
+max_llm_calls = 10
+
+[eval.env_config.env_params]
+max_steps_per_episode = 10

examples/blog_posts/warming_up_to_rl/configs/eval_openai_gpt_oss_120b.toml

@@ -0,0 +1,29 @@
+# Crafter rollout config for GPT-OSS-120B served from OpenAI-compatible APIs.
+# Replace the task_app_url with your deployed Crafter task app URL.
+# The run stores full traces so we can keep the LLM reasoning for fine-tuning.
+
+[eval]
+app_id = "grpo-crafter"
+task_app_url = "https://synth-laboratories--grpo-crafter-task-app-fastapi-app-dev.modal.run"
+model = "openai/gpt-oss-120b"
+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 = "openai/gpt-oss-120b"
+inference_url = "https://api.groq.com/openai"
+temperature = 0.6
+top_p = 0.9
+max_tokens = 768
+use_vision = false
+image_only_mode = false
+max_llm_calls = 10

examples/blog_posts/warming_up_to_rl/configs/filter_high_reward_dataset.toml

@@ -0,0 +1,10 @@
+# Filters Crafter traces into an instruction-tuning dataset.
+# Assumes you stored rollouts in traces/v3/crafter_blog.db via `uvx synth-ai eval`.
+
+[filter]
+db = "sqlite+libsql://http://127.0.0.1:8080"
+output = "examples/blog_posts/warming_up_to_rl/ft_data/crafter_blog_high_reward.jsonl"
+min_official_score = 0.1
+models = ["qwen/qwen3-32b", "openai/gpt-oss-120b"]
+shuffle = true
+shuffle_seed = 42

examples/blog_posts/warming_up_to_rl/configs/smoke_test.toml

@@ -0,0 +1,75 @@
+# Example RL config with smoke testing enabled
+# This config demonstrates auto-starting task app and sqld for easy smoke testing
+
+type = "rl"
+
+# Smoke testing configuration - AUTO-STARTS services in background!
+[smoke]
+# Auto-start the task app server
+task_app_name = "grpo-crafter"  # Your task app name (use "synth-ai task-app list" to see available apps)
+task_app_port = 8765
+task_app_env_file = ".env"  # Required for this task app
+task_app_force = true  # Kill any existing process on this port
+
+# Auto-start sqld for tracing
+sqld_auto_start = true
+sqld_db_path = "./traces/local.db"
+sqld_hrana_port = 8080
+sqld_http_port = 8081
+
+# Test parameters
+env_name = "crafter"
+policy_name = "crafter-react"
+max_steps = 10
+policy = "gpt-5-nano"  # Use gpt-5-nano policy with mock backend
+model = "gpt-4o-mini"  # Real model to use via OpenAI
+mock_backend = "openai"  # Use OpenAI backend for real inference and tool calls
+return_trace = true
+use_mock = true  # Use mock proxy that routes to OpenAI
+
+# RL Training Configuration (used by actual training, not smoke tests)
+[algorithm]
+type = "online"
+method = "policy_gradient"
+variety = "gspo"
+
+[policy]
+model_name = "Qwen/Qwen3-4B"
+trainer_mode = "full"
+label = "crafter-rl-demo"
+
+[compute]
+gpu_type = "H100"
+gpu_count = 2
+
+[compute.topology]
+type = "single_node_split"
+gpus_for_vllm = 1
+gpus_for_training = 1
+
+[services]
+task_url = "http://localhost:8765"
+
+[rollout]
+env_name = "crafter"
+policy_name = "crafter-react"
+max_turns = 10
+episodes_per_batch = 16
+max_concurrent_rollouts = 4
+task_app_origin_rewards_only = true
+
+[training]
+num_epochs = 1
+iterations_per_epoch = 10
+max_turns = 10
+batch_size = 4
+group_size = 4
+learning_rate = 5e-5
+weight_sync_interval = 1
+log_interval = 1
+
+[evaluation]
+instances = 2
+every_n_iters = 1
+seeds = [0, 1]
+