synth-ai 0.2.16__tar.gz → 0.2.17__tar.gz

synth_ai-0.2.17/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: synth-ai
+Version: 0.2.17
+Summary: RL as a service SDK - Core AI functionality and tracing
+Author-email: Synth AI <josh@usesynth.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/synth-laboratories/synth-ai
+Project-URL: Repository, https://github.com/synth-laboratories/synth-ai
+Project-URL: Issues, https://github.com/synth-laboratories/synth-ai/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: urllib3>=2.3.0
+Requires-Dist: certifi>=2024.8.30
+Requires-Dist: tqdm>=4.66.4
+Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: backoff>=2.0.0
+Requires-Dist: typing_extensions>=4.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: openai>=1.99.0
+Requires-Dist: anthropic>=0.42.0
+Requires-Dist: langfuse<3.0.0,>=2.53.9
+Requires-Dist: opentelemetry-api<1.27.0,>=1.26.0
+Requires-Dist: opentelemetry-sdk<1.27.0,>=1.26.0
+Requires-Dist: diskcache>=5.6.3
+Requires-Dist: groq>=0.30.0
+Requires-Dist: google-genai>=1.26.0
+Requires-Dist: together>=1.5.21
+Requires-Dist: mistralai>=1.9.2
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: uvicorn>=0.34.2
+Requires-Dist: numpy>=2.2.3
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: redis>=6.2.0
+Requires-Dist: duckdb>=1.0.0
+Requires-Dist: ty>=0.0.1a5
+Requires-Dist: toml>=0.10.2
+Requires-Dist: sqlalchemy>=2.0.42
+Requires-Dist: aiosqlite>=0.21.0
+Requires-Dist: greenlet>=3.2.3
+Requires-Dist: libsql>=0.1.8
+Requires-Dist: pynacl>=1.5.0
+Requires-Dist: google-api-core>=2.25.1
+Requires-Dist: google-generativeai>=0.8.5
+Requires-Dist: crafter>=1.8.3
+Requires-Dist: click<8.2,>=8.1.7
+Requires-Dist: openai-harmony>=0.0.1
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: datasets>=4.0.0
+Requires-Dist: transformers>=4.56.1
+Requires-Dist: modal==1.1.4
+Requires-Dist: pyboy>=2.6.0
+Requires-Dist: setuptools>=80.9.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2.post1; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: keyring>=24.0.0; extra == "dev"
+Requires-Dist: pytest>=8.3.3; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6.1; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pyright>=1.1.350; extra == "dev"
+Requires-Dist: coverage[toml]>=7.3.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: research
+Requires-Dist: crafter>=1.8.3; extra == "research"
+Requires-Dist: datasets>=4.0.0; extra == "research"
+Provides-Extra: swe
+Requires-Dist: morphcloud>=0.1.3; extra == "swe"
+Requires-Dist: swebench>=2.3.0; extra == "swe"
+Provides-Extra: all
+Requires-Dist: crafter>=1.8.3; extra == "all"
+Requires-Dist: datasets>=4.0.0; extra == "all"
+Requires-Dist: morphcloud>=0.1.3; extra == "all"
+Requires-Dist: swebench>=2.3.0; extra == "all"
+Provides-Extra: analytics
+Requires-Dist: pandas>=2.2.3; extra == "analytics"
+Dynamic: license-file
+
+# Synth-AI SDK
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![PyPI](https://img.shields.io/badge/PyPI-0.2.10-orange)](https://pypi.org/project/synth-ai/)
+![Coverage](https://img.shields.io/badge/coverage-9.09%25-red)
+![Tests](https://img.shields.io/badge/tests-37%2F38%20passing-brightgreen)
+![Blacksmith CI](https://img.shields.io/badge/CI-Blacksmith%20Worker-blue)
+
+> **Synth-AI** — Reinforcement Learning-as-a-Service for agents.  
+> **Docs:** [Get Started →](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+## 🚀 Install version 0.2.16
+
+```bash
+pip install synth-ai
+# or
+uv add synth-ai
+```
+
+**Import:**
+
+```python
+import synth_ai
+```
+
+**CLI (with uvx):**
+
+```bash
+uvx synth-ai setup
+uvx synth-ai demo
+uvx synth-ai deploy
+uvx synth-ai run
+```
+
+> Full quickstart: [https://docs.usesynth.ai/sdk/get-started](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+When you run `uvx synth-ai setup`, the SDK opens your browser to the Synth dashboard for a one‑time pairing (handshake) with your signed‑in session. The SDK will automatically:
+
+
+Fast and effective reinforcement learning for agents, via an API.  
+Easily scale GPU topologies, train multi-node, and integrate with existing agent software.
+
+### Highlights
+
+- Scale GPU topologies (A10Gs, H100s, multi-node available on request)
+- Thin FastAPI wrapper integration
+- Supports OSS models like **Qwen3** (GPT-OSS GA soon)
+- Own your trained models
+
+---
+
+## ⚙️ Getting Started
+
+Synth-AI ships with a built-in RL example: training **Qwen3-0.6B** on math reasoning.
+
+1. Create accounts at [Synth](https://usesynth.ai) and [Modal](https://modal.com)
+2. Then run:
+
+   ```bash
+   uvx synth-ai demo
+   uvx synth-ai setup
+   uvx synth-ai deploy
+   uvx synth-ai run
+   ```
+
+3. To walk through your first RL run, see  
+   👉 [Synth-AI SDK Docs](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+## 🔐 SDK → Dashboard Pairing
+
+When you run `uvx synth-ai setup` (or legacy `uvx synth-ai rl_demo setup`):
+
+- The SDK opens your browser to the Synth dashboard to pair your SDK with your signed-in session.
+- Automatically detects your **user + organization**
+- Ensures both **API keys** exist
+- Writes them to your project’s `.env` as:
+
+  ```
+  SYNTH_API_KEY=
+  ENVIRONMENT_API_KEY=
+  ```
+
+✅ No keys printed or requested interactively — all handled via browser pairing.
+
+### Environment overrides
+
+- `SYNTH_CANONICAL_ORIGIN` → override dashboard base URL (default: https://www.usesynth.ai/dashboard)
+- `SYNTH_CANONICAL_DEV` → `1|true|on` to use local dashboard (http://localhost:3000)
+
+---
+
+## 📚 Documentation
+
+- **SDK Docs:** [https://docs.usesynth.ai/sdk/get-started](https://docs.usesynth.ai/sdk/get-started)
+- **CLI Reference:** [https://docs.usesynth.ai/cli](https://docs.usesynth.ai/cli)
+- **API Reference:** [https://docs.usesynth.ai/api](https://docs.usesynth.ai/api)
+- **Changelog:** [https://docs.usesynth.ai/changelog](https://docs.usesynth.ai/changelog)
+
+---
+
+## 🧠 Meta
+
+- Package: [`synth-ai`](https://pypi.org/project/synth-ai)
+- Import: `synth_ai`
+- Source: [github.com/synth-laboratories/synth-ai](https://github.com/synth-laboratories/synth-ai)
+- License: MIT

synth_ai-0.2.17/README.md

@@ -0,0 +1,113 @@
+# Synth-AI SDK
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![PyPI](https://img.shields.io/badge/PyPI-0.2.10-orange)](https://pypi.org/project/synth-ai/)
+![Coverage](https://img.shields.io/badge/coverage-9.09%25-red)
+![Tests](https://img.shields.io/badge/tests-37%2F38%20passing-brightgreen)
+![Blacksmith CI](https://img.shields.io/badge/CI-Blacksmith%20Worker-blue)
+
+> **Synth-AI** — Reinforcement Learning-as-a-Service for agents.  
+> **Docs:** [Get Started →](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+## 🚀 Install version 0.2.16
+
+```bash
+pip install synth-ai
+# or
+uv add synth-ai
+```
+
+**Import:**
+
+```python
+import synth_ai
+```
+
+**CLI (with uvx):**
+
+```bash
+uvx synth-ai setup
+uvx synth-ai demo
+uvx synth-ai deploy
+uvx synth-ai run
+```
+
+> Full quickstart: [https://docs.usesynth.ai/sdk/get-started](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+When you run `uvx synth-ai setup`, the SDK opens your browser to the Synth dashboard for a one‑time pairing (handshake) with your signed‑in session. The SDK will automatically:
+
+
+Fast and effective reinforcement learning for agents, via an API.  
+Easily scale GPU topologies, train multi-node, and integrate with existing agent software.
+
+### Highlights
+
+- Scale GPU topologies (A10Gs, H100s, multi-node available on request)
+- Thin FastAPI wrapper integration
+- Supports OSS models like **Qwen3** (GPT-OSS GA soon)
+- Own your trained models
+
+---
+
+## ⚙️ Getting Started
+
+Synth-AI ships with a built-in RL example: training **Qwen3-0.6B** on math reasoning.
+
+1. Create accounts at [Synth](https://usesynth.ai) and [Modal](https://modal.com)
+2. Then run:
+
+   ```bash
+   uvx synth-ai demo
+   uvx synth-ai setup
+   uvx synth-ai deploy
+   uvx synth-ai run
+   ```
+
+3. To walk through your first RL run, see  
+   👉 [Synth-AI SDK Docs](https://docs.usesynth.ai/sdk/get-started)
+
+---
+
+## 🔐 SDK → Dashboard Pairing
+
+When you run `uvx synth-ai setup` (or legacy `uvx synth-ai rl_demo setup`):
+
+- The SDK opens your browser to the Synth dashboard to pair your SDK with your signed-in session.
+- Automatically detects your **user + organization**
+- Ensures both **API keys** exist
+- Writes them to your project’s `.env` as:
+
+  ```
+  SYNTH_API_KEY=
+  ENVIRONMENT_API_KEY=
+  ```
+
+✅ No keys printed or requested interactively — all handled via browser pairing.
+
+### Environment overrides
+
+- `SYNTH_CANONICAL_ORIGIN` → override dashboard base URL (default: https://www.usesynth.ai/dashboard)
+- `SYNTH_CANONICAL_DEV` → `1|true|on` to use local dashboard (http://localhost:3000)
+
+---
+
+## 📚 Documentation
+
+- **SDK Docs:** [https://docs.usesynth.ai/sdk/get-started](https://docs.usesynth.ai/sdk/get-started)
+- **CLI Reference:** [https://docs.usesynth.ai/cli](https://docs.usesynth.ai/cli)
+- **API Reference:** [https://docs.usesynth.ai/api](https://docs.usesynth.ai/api)
+- **Changelog:** [https://docs.usesynth.ai/changelog](https://docs.usesynth.ai/changelog)
+
+---
+
+## 🧠 Meta
+
+- Package: [`synth-ai`](https://pypi.org/project/synth-ai)
+- Import: `synth_ai`
+- Source: [github.com/synth-laboratories/synth-ai](https://github.com/synth-laboratories/synth-ai)
+- License: MIT

synth_ai-0.2.17/examples/analyze_semantic_words.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Run Crafter agent and analyze semantic map word distribution
+# This script demonstrates semantic analysis of agent observations
+# Output: Markdown tables and JSON data (no plotting dependencies)
+
+echo "🔍 Analyzing semantic map words from Crafter agent..."
+echo "Make sure the synth-ai service is running: uvx synth-ai deploy --runtime uvicorn"
+echo ""
+
+cd synth_ai/environments/examples/crafter_classic/agent_demos/
+
+# Run the semantic analysis (markdown output only)
+python analyze_semantic_words_markdown.py --model gemini-1.5-flash --episodes 3 --max-turns 30
+
+echo ""
+echo "✅ Analysis complete! Check the generated markdown report and JSON files."

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/README.md

@@ -0,0 +1,98 @@
+# Pokémon VL: Vision-Language RL Pipeline
+
+This playbook demonstrates end-to-end vision-language reinforcement learning on Pokémon Red using Synth AI's CLI tools. We follow the eval → collect data → SFT → RL → eval pipeline, but with vision models throughout.
+
+## Overview
+
+**Model**: Qwen3-VL-4B-Instruct (4B parameter vision-language model via Synth API)
+**Environment**: Pokémon Red (Game Boy emulation with vision support)
+**Benchmark**: Pallet Town progression task (leave bedroom → get starter → win first battle)
+
+## Pipeline Steps
+
+1. **Deploy Task App** - Host the Pokémon Red environment
+2. **Collect Vision Rollouts** - Generate high-quality demonstrations using Qwen3-VL
+3. **Filter Dataset** - Extract successful trajectories for supervised fine-tuning
+4. **Fine-Tune Qwen3-4B VL** - Train vision-language model on filtered data
+5. **Vision-Language RL** - Bootstrap RL training from SFT checkpoint
+6. **Final Evaluation** - Compare SFT and RL performance
+
+## Prerequisites
+
+```bash
+# Install dependencies
+uv pip install -e .
+
+# Setup authentication
+uvx synth-ai setup
+
+# Copy environment template
+cp examples/blog_posts/pokemon_vl/.env.example .env
+```
+
+## Quick Start
+
+```bash
+# Export trace database path
+export POKEMON_VL_TRACE_DB=traces/v3/pokemon_vl_blog.db
+
+# 1. Deploy task app
+uvx synth-ai deploy pokemon_red --runtime modal --name pokemon-vl-blog --env-file .env
+
+# 2. Collect vision rollouts with Qwen3-VL
+uvx synth-ai eval pokemon_red --config examples/blog_posts/pokemon_vl/configs/eval_qwen3_vl.toml --trace-db "${POKEMON_VL_TRACE_DB}"
+
+# 3. Filter high-reward trajectories
+uvx synth-ai filter --config examples/blog_posts/pokemon_vl/configs/filter_high_reward.toml
+
+# 4. Fine-tune Qwen3-4B VL
+uvx synth-ai train --type sft --config examples/blog_posts/pokemon_vl/configs/train_sft_qwen4b_vl.toml --env-file .env --poll
+
+# 5. RL from SFT checkpoint (replace JOB_ID)
+uvx synth-ai train --type rl --config examples/blog_posts/pokemon_vl/configs/train_rl_from_sft.toml --env-file .env --poll
+
+# 6. Evaluate final RL model
+uvx synth-ai eval pokemon_red --config examples/blog_posts/pokemon_vl/configs/eval_rl_final.toml --trace-db "${POKEMON_VL_TRACE_DB}"
+```
+
+## Vision Features
+
+- **Full Game Boy Frames**: Base64-encoded PNG screenshots (160x144 resolution)
+- **Vision-Only Mode**: Pure image understanding without text state
+- **Vision + Text Mode**: Combined visual and structured state information
+- **Efficient Action Batching**: `execute_sequence` tool for 5-10 actions per inference call
+
+## Expected Results
+
+| Stage | Model | Mean Reward | Success Rate | Best Achievement |
+|-------|-------|-------------|--------------|------------------|
+| Initial | Qwen3-VL (vision) | ~150 | 60% | Win first battle |
+| SFT | Qwen3-4B VL | ~200 | 75% | Win first battle + explore |
+| RL | Qwen3-4B VL + RL | ~350 | 85% | Complete Pallet Town |
+
+## Files
+
+- `configs/` - All TOML configuration files
+- `ft_data/` - Filtered datasets for fine-tuning
+- `.env.example` - Environment variables template
+
+## Vision Model Configuration
+
+The vision models receive:
+- **Input**: Game Boy screenshot + optional structured state (position, HP, party, etc.)
+- **Output**: Sequence of button presses via `execute_sequence` tool
+- **Action Space**: UP, DOWN, LEFT, RIGHT, A, B, START, SELECT with frame counts
+
+## Reward Function
+
+Dense rewards for Pallet Town progression:
+- Leave bedroom (+20)
+- Exit house (+30)
+- Find Oak's lab (+40)
+- Talk to Oak (+50)
+- Get starter Pokémon (+100)
+- Enter battle (+75)
+- Deal damage (+50 per 10HP)
+- Win battle (+150)
+
+Total possible: ~700 points

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/configs/eval_qwen3_vl.toml

@@ -0,0 +1,25 @@
+[eval]
+app_id = "pokemon_red"
+task_app_url = "https://synth-laboratories--pokemon-vl-qwen-xml-fastapi-app.modal.run"
+model = "Qwen/Qwen3-VL-8B-Instruct"  # Vision-capable Qwen3-VL model
+seeds = [10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
+max_turns = 10
+concurrency = 2
+env_name = "pokemon_red"
+policy_name = "pokemon_vl_qwen3_vl"
+trace_format = "full"
+return_trace = true
+
+[eval.policy_config]
+provider = "synth"  # Use Synth internal API for vision models
+model = "Qwen/Qwen3-VL-8B-Instruct"  # Vision-capable Qwen3-VL model
+inference_url = "http://localhost:8000/api/inference/v1/chat/completions"
+temperature = 1.0  # Higher temperature to encourage tool calling
+top_p = 0.95
+max_tokens = 4096
+use_vision = true
+image_only_mode = false
+max_llm_calls = 10
+
+[eval.env_config.env_params]
+max_steps_per_episode = 10

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/configs/eval_rl_final.toml

@@ -0,0 +1,24 @@
+[eval]
+app_id = "pokemon_red"
+task_app_url = "http://127.0.0.1:8914"
+model = "fft:REPLACE-WITH-RL-JOB-ID"  # Update with final RL job ID
+seeds = [100, 101, 102, 103, 104, 105, 106, 107, 108, 109]
+max_turns = 15  # Allow more steps for trained model
+concurrency = 3
+env_name = "pokemon_red"
+policy_name = "pokemon_vl_rl_final"
+trace_format = "full"
+return_trace = true
+
+[eval.policy_config]
+provider = "synth"
+model = "fft:REPLACE-WITH-RL-JOB-ID"  # Update with final RL job ID
+temperature = 0.1  # Lower temperature for evaluation
+top_p = 0.9
+max_tokens = 4096
+use_vision = true
+image_only_mode = false
+max_llm_calls = 15
+
+[eval.env_config.env_params]
+max_steps_per_episode = 15

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/configs/filter_high_reward.toml

@@ -0,0 +1,10 @@
+# Filter high-quality vision-language rollouts for SFT training
+# Assumes traces stored in pokemon_vl_blog.db via eval commands
+
+[filter]
+db = "traces/v3/pokemon_vl_blog.db"
+output = "examples/blog_posts/pokemon_vl/ft_data/pokemon_vl_high_reward.jsonl"
+min_official_score = 0.3  # Require at least 30% completion (Pallet Town progression)
+models = ["Qwen/Qwen3-VL-4B-Instruct"]  # Vision models used for rollouts
+shuffle = true
+shuffle_seed = 42

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/configs/train_rl_from_sft.toml

@@ -0,0 +1,42 @@
+# Vision-Language RL: Continue training Qwen3-4B VL from SFT checkpoint
+# Update task_url with deployed Modal task app URL
+# Set model.source to the SFT job id from `uvx synth-ai train --type sft`
+
+type = "rl"
+
+[services]
+task_url = "http://127.0.0.1:8914"
+
+[compute]
+gpu_type = "H100"
+gpu_count = 8
+
+[topology]
+gpus_for_vllm = 4
+gpus_for_training = 3
+gpus_for_ref = 1
+
+[vllm]
+tensor_parallel_size = 4
+
+[model]
+source = "fft:REPLACE-WITH-SFT-JOB-ID"  # Update with actual SFT job ID
+label = "pokemon_vl_rl_blog"
+supports_vision = true
+
+[rollout]
+max_turns = 10
+episodes_per_batch = 64
+
+[evaluation]
+instances = 100
+every_n_iters = 20
+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, 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, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99]
+
+[training]
+log_interval = 1
+
+[training.weight_sync]
+enable = true
+targets = ["policy"]
+weight_sync_interval = 1

synth_ai-0.2.17/examples/blog_posts/pokemon_vl/configs/train_sft_qwen4b_vl.toml

@@ -0,0 +1,40 @@
+# Vision-Language Supervised Fine-Tuning: Qwen3-4B VL on filtered Pokémon rollouts
+# Update the `data` path once `uvx synth-ai filter` produces your JSONL
+
+[algorithm]
+type = "offline"
+method = "sft"
+variety = "fft"
+
+[job]
+model = "Qwen/Qwen3-VL-4B-Instruct"  # Vision-enabled Qwen3-VL model
+data = "../ft_data/pokemon_vl_high_reward.jsonl"
+poll_seconds = 1800
+
+[compute]
+gpu_type = "H100"
+gpu_count = 4
+nodes = 1
+
+[data.topology]
+container_count = 4
+
+[training]
+mode = "full_finetune"
+use_qlora = false
+
+[hyperparameters]
+n_epochs = 2
+world_size = 4
+sequence_length = 4096  # Longer for vision tokens + text
+per_device_batch = 2
+gradient_accumulation_steps = 64
+learning_rate = 8e-6
+warmup_ratio = 0.03
+
+[hyperparameters.parallelism]
+use_deepspeed = true
+deepspeed_stage = 3
+fsdp = false
+bf16 = true
+fp16 = false