synth-ai 0.2.9.dev7__tar.gz → 0.2.9.dev9__tar.gz

synth_ai-0.2.9.dev9/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: synth-ai
+Version: 0.2.9.dev9
+Summary: Python SDK and CLI for Synth — RL-as-a-service
+Author-email: Synth AI <josh@usesynth.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://usesynth.ai
+Project-URL: Documentation, https://docs.usesynth.ai/sdk/get-started
+Project-URL: Changelog, https://docs.usesynth.ai/changelog
+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: 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: textual>=1.1.0
+Requires-Dist: openai-harmony>=0.0.1
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: datasets>=4.0.0
+Requires-Dist: transformers>=4.56.1
+Requires-Dist: modal==1.1.4
+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: all
+Requires-Dist: crafter>=1.8.3; extra == "all"
+Requires-Dist: datasets>=4.0.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
+
+```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)
+
+---
+
+## 🧩 About
+
+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.9.dev9/README.md

@@ -0,0 +1,112 @@
+# 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
+
+```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)
+
+---
+
+## 🧩 About
+
+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.9.dev9/examples/__init__.py

@@ -0,0 +1,16 @@
+"""Top-level package for Synth AI example environments and utilities."""
+
+from importlib import resources as _resources
+
+__all__ = ["path_for"]
+
+
+def path_for(package: str, resource: str) -> str:
+    """Return absolute path for a packaged resource inside ``examples``.
+
+    This helper mirrors the one under ``synth_ai`` so hosted apps can access
+    bundled assets without needing to install the repo in editable mode.
+    """
+
+    with _resources.as_file(_resources.files(f"examples.{package}") / resource) as path:
+        return str(path)

{synth_ai-0.2.9.dev7 → synth_ai-0.2.9.dev9}/examples/crafter_debug_render.py

@@ -12,9 +12,10 @@ Run:
 """
 
 import argparse
+import contextlib
 import math
 import os
-from typing import Any, Dict, List
+from typing import Any
 
 import httpx
 
@@ -37,21 +38,19 @@ def try_import_crafter_mapping():
                 id_to_item[ind] = label.lower()
             return id_to_item
         finally:
-            try:
+            with contextlib.suppress(Exception):
                 env.close()
-            except Exception:
-                pass
     except Exception:
         return None
 
 
-def format_semantic_map_view(obs: Dict[str, Any], view_size: int = 7) -> str:
+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]]
+    grid: list[list[int]]
     if isinstance(sem, list) and sem and isinstance(sem[0], list):
         grid = sem
     elif isinstance(sem, list):
@@ -82,10 +81,10 @@ def format_semantic_map_view(obs: Dict[str, Any], view_size: int = 7) -> str:
         px, py = rows // 2, cols // 2
 
     half = max(1, view_size // 2)
-    lines: List[str] = []
+    lines: list[str] = []
     visible: set[str] = set()
     for dy in range(-half, half + 1):
-        row_cells: List[str] = []
+        row_cells: list[str] = []
         for dx in range(-half, half + 1):
             x = px + dx
             y = py + dy
@@ -175,12 +174,10 @@ async def main():
         print(format_semantic_map_view(sobs, view_size=7))
 
         # Cleanup
-        try:
+        with contextlib.suppress(Exception):
             await client.post(
                 f"{args.base_url}/env/CrafterClassic/terminate", json={"env_id": env_id}
             )
-        except Exception:
-            pass
 
 
 if __name__ == "__main__":

synth_ai-0.2.9.dev9/examples/qwen_coder/README.md

@@ -0,0 +1,102 @@
+Qwen3 Coder – SFT with LoRA (all linear)
+
+This example mirrors the SFT LoRA flow under `examples/sft/` but targets the smallest Qwen3 Coder family model supported downstream. It configures LoRA on all linear projections ("all-linear") to match our RL LoRA recipes.
+
+Quick start
+
+1) Generate a tiny synthetic dataset (or export your own)
+
+```
+uv run python examples/qwen_coder/generate_dataset.py \
+  --output examples/qwen_coder/ft_data/coder_sft.small.jsonl \
+  --n 50 --seed 42 --lang python
+```
+
+2) Run training via the CLI:
+
+```
+uvx synth-ai train \
+  --type sft \
+  --config examples/qwen_coder/configs/coder_lora_small.toml \
+  --dataset examples/qwen_coder/ft_data/coder_sft.small.jsonl \
+  --env-file /path/to/.env
+```
+
+3) Inference via Synth API (pre/post SFT)
+
+Use the SDK’s OpenAI-compatible chat client routed through Synth. Export your env with SYNTH_API_KEY (and optional BACKEND_BASE_URL) or pass an env file to CLI helpers.
+
+Minimal one-shot inference:
+
+```bash
+python - <<'PY'
+import os, asyncio
+from synth_ai.v0.lm.core import main_v3 as lm
+
+async def run():
+    model = os.getenv("MODEL", "Qwen/Qwen3-Coder-30B-A3B-Instruct")
+    resp = await lm.chat_async(
+        model,
+        messages=[{"role":"user","content":"Write a Python function to reverse a string."}],
+        max_tokens=128,
+        temperature=0.2,
+    )
+    print(resp["choices"][0]["message"]["content"]) 
+asyncio.run(run())
+PY
+```
+
+After training, set `MODEL=ft:...` to query the finetuned adapter.
+
+4) 30B LoRA variant
+
+```bash
+uvx synth-ai train \
+  --type sft \
+  --config examples/qwen_coder/configs/coder_lora_30b.toml \
+  --dataset examples/qwen_coder/ft_data/coder_sft.small.jsonl \
+  --env-file /path/to/.env
+```
+
+5) Faster iteration: 4B LoRA config
+
+```bash
+uvx synth-ai train \
+  --type sft \
+  --config examples/qwen_coder/configs/coder_lora_4b.toml \
+  --dataset examples/qwen_coder/ft_data/coder_sft.small.jsonl \
+  --env-file /path/to/.env
+```
+
+Environment variables
+
+- `SYNTH_API_KEY`: required for training/inference through the hosted backend
+- `BACKEND_BASE_URL`: defaults to `https://agent-learning.onrender.com/api`
+
+Post‑SFT smoke
+
+- The training helper `sft_lora_30b.py` writes the resulting `ft:<id>` to `examples/qwen_coder/ft_data/ft_model_id.txt`.
+- Validate inference with your finetuned adapter:
+
+```bash
+uv run python examples/qwen_coder/infer_ft_smoke.py
+```
+
+Dataset utilities
+
+- `examples/qwen_coder/validate_jsonl.py`: sanity‑check first N lines for chat structure
+- `examples/qwen_coder/subset_jsonl.py`: create a capped subset for quick tests
+
+Optional CLI wrappers
+
+- `examples/qwen_coder/scripts/train_coder_30b.sh [/path/to/.env]`
+- `examples/qwen_coder/scripts/infer_coder.sh [/path/to/.env]`
+
+Notes
+
+- LoRA is enabled with `training.mode = "lora"` and `hyperparameters.train_kind = "peft"`.
+- The config sets an `all-linear` target to apply adapters broadly across attention and MLP projections.
+- Adjust `gradient_accumulation_steps`, `per_device_batch`, and `sequence_length` based on available GPU memory.
+- Use the Synth API client (above) for inference to ensure requests route via the hosted backend.
+
+

synth_ai-0.2.9.dev9/examples/qwen_coder/_shared.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Shared helpers for Qwen coder SFT examples."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+TRAIN_DATA_PATH = Path("examples/qwen_coder/ft_data/coder_sft.small.jsonl")
+VAL_DATA_PATH = Path("examples/qwen_coder/ft_data/coder_sft.small.val.jsonl")
+DATA_DIR = TRAIN_DATA_PATH.parent
+
+_FALLBACK_RECORDS: list[dict[str, object]] = [
+    {
+        "messages": [
+            {"role": "user", "content": "Write a Python function `add(a, b)` that returns the sum of two numbers."}
+        ],
+        "response": "def add(a, b):\n    return a + b\n",
+    },
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "Implement a Python function `reverse_string(s)` that returns the reversed string.",
+            }
+        ],
+        "response": "def reverse_string(s: str) -> str:\n    return s[::-1]\n",
+    },
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "Write a Python function `count_words(text)` returning a dict mapping words to counts.",
+            }
+        ],
+        "response": "from collections import Counter\n\ndef count_words(text: str) -> dict[str, int]:\n    words = [w for w in text.split() if w]\n    return dict(Counter(words))\n",
+    },
+]
+
+
+def ensure_tiny_dataset() -> Path:
+    """Ensure the tiny coder dataset exists, generating or writing a fallback if needed."""
+    if TRAIN_DATA_PATH.exists():
+        return TRAIN_DATA_PATH
+
+    try:
+        from examples.qwen_coder.generate_dataset import main as gen_main  # type: ignore
+
+        gen_main()
+        if TRAIN_DATA_PATH.exists():
+            return TRAIN_DATA_PATH
+    except Exception:
+        # Fall back to inline dataset below.
+        pass
+
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    with TRAIN_DATA_PATH.open("w", encoding="utf-8") as fh:
+        for record in _FALLBACK_RECORDS:
+            fh.write(json.dumps(record, separators=(",", ":")))
+            fh.write("\n")
+    return TRAIN_DATA_PATH
+
+
+def optional_validation_dataset() -> Path | None:
+    """Return validation dataset path if present."""
+    if VAL_DATA_PATH.exists():
+        return VAL_DATA_PATH
+    return None
+
+
+def _ensure_parent(path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def resolve_output_path(default_filename: str) -> Path:
+    """Resolve output path for storing fine-tuned model ids."""
+    override = os.getenv("QWEN_CODER_FT_OUTPUT")
+    if override:
+        return _ensure_parent(Path(override).expanduser())
+    return _ensure_parent(DATA_DIR / default_filename)
+
+
+def resolve_model_id_path(default_filename: str) -> Path:
+    """Resolve path to read a stored fine-tuned model id."""
+    override = os.getenv("QWEN_CODER_FT_MODEL_PATH")
+    if override:
+        candidate = Path(override).expanduser()
+        if candidate.is_dir():
+            return candidate / default_filename
+        return candidate
+    return DATA_DIR / default_filename
+
+
+def resolve_infer_output_path(default_filename: str) -> Path:
+    """Resolve path for writing inference outputs."""
+    override = os.getenv("QWEN_CODER_FT_INFER_OUTPUT")
+    if override:
+        return _ensure_parent(Path(override).expanduser())
+    return _ensure_parent(DATA_DIR / default_filename)
+
+
+__all__ = [
+    "DATA_DIR",
+    "TRAIN_DATA_PATH",
+    "VAL_DATA_PATH",
+    "ensure_tiny_dataset",
+    "optional_validation_dataset",
+    "resolve_output_path",
+    "resolve_model_id_path",
+    "resolve_infer_output_path",
+]

synth_ai-0.2.9.dev9/examples/qwen_coder/configs/coder_lora_30b.toml

@@ -0,0 +1,61 @@
+# Qwen3 Coder 30B LoRA SFT – all-linear adapters
+
+[algorithm]
+type = "offline"
+method = "sft"
+variety = "fft"
+
+[job]
+model = "Qwen/Qwen3-Coder-30B-A3B-Instruct"
+
+[compute]
+gpu_type = "H200"
+gpu_count = 1
+nodes = 1
+
+[data]
+topology = {}
+# Optional validation set
+# validation_path = "examples/qwen_coder/ft_data/coder_sft.small.val.jsonl"
+
+[metadata]
+# Effective config hints consumed by the backend
+effective_config = { compute = { gpu_type = "H200", gpu_count = 1, nodes = 1 } }
+
+[training]
+mode = "lora"
+use_qlora = true
+
+[training.validation]
+enabled = true
+evaluation_strategy = "steps"
+eval_steps = 100
+save_best_model_at_end = true
+metric_for_best_model = "val.loss"
+greater_is_better = false
+
+[hyperparameters]
+n_epochs = 1
+train_kind = "peft"
+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
+fsdp = false
+bf16 = true
+fp16 = false
+activation_checkpointing = true
+
+# LoRA target selection for coder models: apply to all linear projections
+[lora]
+r = 16
+alpha = 32
+dropout = 0.05
+target_modules = ["all-linear"]
+
+