synth-ai 0.2.9.dev5__py3-none-any.whl → 0.2.10__py3-none-any.whl

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)

examples/crafter_debug_render.py

@@ -10,10 +10,12 @@ Quick local Crafter observation inspector.
 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, Dict, List
+from typing import Any
 
 import httpx
 
@@ -36,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):
@@ -81,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
@@ -117,13 +117,17 @@ def format_semantic_map_view(obs: Dict[str, Any], view_size: int = 7) -> str:
                 row_cells.append("void")
         lines.append(" ".join(row_cells))
 
-    legend = f"Visible items: {', '.join(sorted(visible))}" if visible else "No notable items visible"
+    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(
+        "--base-url", default=os.getenv("CRAFTER_BASE_URL", "http://localhost:8901")
+    )
     parser.add_argument("--seed", type=int, default=1)
     args = parser.parse_args()
 
@@ -145,7 +149,11 @@ async def main():
         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)
+        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)
@@ -166,15 +174,13 @@ async def main():
         print(format_semantic_map_view(sobs, view_size=7))
 
         # Cleanup
-        try:
-            await client.post(f"{args.base_url}/env/CrafterClassic/terminate", json={"env_id": env_id})
-        except Exception:
-            pass
+        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

@@ -0,0 +1,40 @@
+[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/crafter_rl_lora.md

@@ -0,0 +1,29 @@
+# Crafter RL LoRA (10-step runs)
+
+This walkthrough shows how to fine-tune the Crafter task app with our 10-step RL LoRA config.
+
+1. **Start the Crafter task app on Modal (with tracing + text-only prompts)**
+
+   ```bash
+   BACKEND_BASE_URL=https://agent-learning.onrender.com/api \
+   uvx synth-ai modal-serve grpo-crafter \
+     --env-file examples/warming_up_to_rl/.env \
+     --name grpo-crafter-task-app
+   ```
+
+   * Deploys the Modal task app with the tracing/text-only fixes baked in.*
+
+2. **Launch the RL job using the updated LoRA config**
+
+   ```bash
+   uvx synth-ai train --type rl \
+     --config tests/artifacts/configs/rl.lora.small.toml \
+     --backend https://agent-learning.onrender.com/api \
+     --env-file .env \
+     --no-poll
+   ```
+
+   * This config forces 10 agent turns per rollout, reduces batch size to avoid OOMs, and enforces Crafter-specific defaults.*
+
+  INFO - 🎉 Training completed successfully!
+  INFO - All batch rewards: [0.0625, 0.0625, 0.125, 0.0625, 0.0625, 0.3125, 0.375, 0.4375, 0.5, 0.9375]

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.
+
+

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",
+]

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"]
+
+

examples/qwen_coder/configs/coder_lora_4b.toml

@@ -0,0 +1,57 @@
+# Qwen3 Coder 4B LoRA SFT – all-linear adapters
+
+[job]
+model = "Qwen/Qwen3-4B"
+
+[compute]
+gpu_type = "H100"
+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 = "H100", 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 = 2
+gradient_accumulation_steps = 32
+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"]
+
+
+

examples/qwen_coder/configs/coder_lora_small.toml

@@ -0,0 +1,58 @@
+# Qwen3 Coder LoRA SFT – all-linear adapters
+
+[algorithm]
+type = "offline"
+method = "sft"
+variety = "fft"
+
+[job]
+# Smallest supported Qwen3 base; replace with the smallest Coder variant when available
+model = "Qwen/Qwen3-1.7B"
+
+[compute]
+gpu_type = "H100"
+gpu_count = 1
+nodes = 1
+
+[data]
+topology = {}
+# Optional validation set
+# validation_path = "examples/sft/ft_data/coder_traces.val.jsonl"
+
+[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 = 2
+gradient_accumulation_steps = 32
+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"]
+
+

examples/qwen_coder/generate_dataset.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Generate a small, synthetic SFT JSONL dataset for coder-style prompts.
+
+Each line uses the minimal schema consumed by the SFT CLI:
+  {"messages": [{"role": "user", "content": "..."}], "response": "..."}
+
+Example:
+  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
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import random
+from collections.abc import Iterable
+from pathlib import Path
+
+PROMPT_TEMPLATES: dict[str, list[str]] = {
+    "python": [
+        "Write a Python function `add(a, b)` that returns the sum of two numbers.",
+        "Write a Python function `reverse_string(s)` that returns the reversed string.",
+        "Implement a Python function `is_palindrome(s)` that returns True if s is a palindrome.",
+        "Write a Python function `fibonacci(n)` that returns a list of the first n Fibonacci numbers.",
+        "Write a Python function `count_words(text)` that returns a dict of word -> count.",
+    ],
+    "javascript": [
+        "Write a JavaScript function `add(a, b)` that returns the sum of two numbers.",
+        "Write a JavaScript function `reverseString(s)` that returns the reversed string.",
+        "Implement a JavaScript function `isPalindrome(s)` that returns true if s is a palindrome.",
+        "Write a JavaScript function `fibonacci(n)` that returns an array of the first n Fibonacci numbers.",
+        "Write a JavaScript function `countWords(text)` that returns an object mapping word -> count.",
+    ],
+}
+
+
+SOLUTIONS: dict[str, list[str]] = {
+    "python": [
+        """def add(a, b):\n    return a + b\n""",
+        """def reverse_string(s: str) -> str:\n    return s[::-1]\n""",
+        """def is_palindrome(s: str) -> bool:\n    t = ''.join(ch.lower() for ch in s if ch.isalnum())\n    return t == t[::-1]\n""",
+        """def fibonacci(n: int) -> list[int]:\n    a, b = 0, 1\n    out: list[int] = []\n    for _ in range(max(0, n)):\n        out.append(a)\n        a, b = b, a + b\n    return out\n""",
+        """from collections import Counter\n\n"""
+        """def count_words(text: str) -> dict[str, int]:\n    words = [w for w in text.split() if w]\n    return dict(Counter(words))\n""",
+    ],
+    "javascript": [
+        """function add(a, b) {\n  return a + b;\n}\n""",
+        """function reverseString(s) {\n  return s.split('').reverse().join('');\n}\n""",
+        """function isPalindrome(s) {\n  const t = (s.match(/[a-z0-9]/gi) || []).join('').toLowerCase();\n  return t === t.split('').reverse().join('');\n}\n""",
+        """function fibonacci(n) {\n  const out = [];\n  let a = 0, b = 1;\n  for (let i = 0; i < Math.max(0, n); i++) {\n    out.push(a);\n    [a, b] = [b, a + b];\n  }\n  return out;\n}\n""",
+        """function countWords(text) {\n  const words = text.split(/\s+/).filter(Boolean);\n  return words.reduce((acc, w) => { acc[w] = (acc[w] || 0) + 1; return acc; }, {});\n}\n""",
+    ],
+}
+
+
+def _iter_examples(n: int, lang: str) -> Iterable[dict]:
+    prompts = PROMPT_TEMPLATES.get(lang, PROMPT_TEMPLATES["python"]).copy()
+    answers = SOLUTIONS.get(lang, SOLUTIONS["python"]).copy()
+    for _ in range(n):
+        i = random.randrange(0, len(prompts))
+        j = random.randrange(0, len(answers))
+        user = prompts[i]
+        assistant = answers[j]
+        yield {
+            "messages": [
+                {"role": "user", "content": user},
+            ],
+            "response": assistant,
+        }
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Generate synthetic coder SFT JSONL dataset")
+    ap.add_argument("--output", required=True, help="Path to write JSONL (will create parent dir)")
+    ap.add_argument("--n", type=int, default=50, help="Number of examples to generate")
+    ap.add_argument("--seed", type=int, default=42, help="Random seed")
+    ap.add_argument("--lang", choices=["python", "javascript"], default="python")
+    args = ap.parse_args()
+
+    random.seed(args.seed)
+    out_path = Path(args.output).expanduser().resolve()
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write JSONL
+    with out_path.open("w", encoding="utf-8") as fh:
+        for rec in _iter_examples(max(1, int(args.n)), lang=args.lang):
+            fh.write(json.dumps(rec, ensure_ascii=False))
+            fh.write("\n")
+
+    print(f"Wrote {args.n} examples to {out_path}")
+
+
+if __name__ == "__main__":
+    main()
+
+