claude-turing 4.8.0 → 4.8.1

package/skills/turing/xray/SKILL.md

@@ -9,9 +9,9 @@ See inside the model. When it underperforms, the fix depends on *why*.
 
 ## Steps
 
-1. **Activate environment:**
+1. **Sync environment:**
    ```bash
-   source .venv/bin/activate
+   uv sync
    ```
 
 2. **Parse arguments from `$ARGUMENTS`:**
@@ -22,7 +22,7 @@ See inside the model. When it underperforms, the fix depends on *why*.
 
 3. **Run model diagnostics:**
    ```bash
-   python scripts/model_xray.py $ARGUMENTS
+   uv run python scripts/model_xray.py $ARGUMENTS
    ```
 
 4. **Diagnostics by model type:**

package/templates/README.md

@@ -21,23 +21,21 @@ This separation is the invariant that makes experiment comparisons valid.
 
 ```bash
 # 1. Set up the environment
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
+uv sync
 
 # 2. Add your training data to {{DATA_SOURCE}}
 
 # 3. Create train/val/test splits
-python prepare.py
+uv run python prepare.py
 
 # 4. Run training
-python train.py > run.log 2>&1
+uv run python train.py > run.log 2>&1
 
 # 5. Check results
 grep -A 10 "^---" run.log
 
 # 6. View experiment history
-python scripts/show_metrics.py
+uv run python scripts/show_metrics.py
 ```
 
 ## Using the Autoresearch Agent
@@ -88,6 +86,5 @@ For hands-off mode: `/loop 5m /turing:train`
 ## Running Tests
 
 ```bash
-source .venv/bin/activate
-python -m pytest tests/ -v
+uv run pytest tests/ -v
 ```

package/templates/program.md

@@ -54,11 +54,11 @@ Update it after each experiment with:
 
 For systematic hyperparameter search:
 1. Edit `sweep_config.yaml` with parameter ranges
-2. Generate queue: `python scripts/sweep.py`
-3. Check status: `python scripts/sweep.py --status`
-4. Get next: `python scripts/sweep.py --next`
+2. Generate queue: `uv run python scripts/sweep.py`
+3. Check status: `uv run python scripts/sweep.py --status`
+4. Get next: `uv run python scripts/sweep.py --next`
 5. Apply overrides, create branch, run training
-6. Mark done: `python scripts/sweep.py --mark <name> complete|failed`
+6. Mark done: `uv run python scripts/sweep.py --mark <name> complete|failed`
 
 ## THE LOOP
 
@@ -66,8 +66,8 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
 1. **OBSERVE** — Read recent results, check hypothesis queue, research plan, and review failed diffs:
    ```bash
-   python scripts/show_metrics.py --last 5
-   python scripts/manage_hypotheses.py next 2>/dev/null || echo "No queued hypotheses"
+   uv run python scripts/show_metrics.py --last 5
+   uv run python scripts/manage_hypotheses.py next 2>/dev/null || echo "No queued hypotheses"
    cat RESEARCH_PLAN.md 2>/dev/null || true
    ```
 
@@ -88,12 +88,12 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
    **If using a queued hypothesis:**
    ```bash
-   python scripts/manage_hypotheses.py mark hyp-NNN in-progress
+   uv run python scripts/manage_hypotheses.py mark hyp-NNN in-progress
    ```
 
    **If generating your own hypothesis**, register it with structured detail:
    ```bash
-   python scripts/manage_hypotheses.py add "your hypothesis description" \
+   uv run python scripts/manage_hypotheses.py add "your hypothesis description" \
      --priority medium --source agent \
      --model-type xgboost \
      --hyperparams '{"max_depth": 8, "n_estimators": 200}' \
@@ -101,7 +101,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
      --tags "depth,estimators" \
      --parent exp-NNN \
      --expected "deeper trees should capture feature interactions"
-   python scripts/manage_hypotheses.py mark hyp-NNN in-progress
+   uv run python scripts/manage_hypotheses.py mark hyp-NNN in-progress
    ```
 
    This creates both an index entry in `hypotheses.yaml` and a detailed file at `hypotheses/hyp-NNN.yaml` with full architecture, hyperparameters, expected outcome, and lineage.
@@ -110,7 +110,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
    To read a hypothesis's full detail:
    ```bash
-   python scripts/manage_hypotheses.py show hyp-NNN
+   uv run python scripts/manage_hypotheses.py show hyp-NNN
    ```
 
 3. **PREPARE** — Modify `config.yaml` for hyperparameter changes. Only modify `train.py` for structural code changes.
@@ -122,7 +122,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
 5. **EXECUTE** training:
    ```bash
-   source .venv/bin/activate && python train.py > run.log 2>&1
+   uv run python train.py > run.log 2>&1
    ```
 
 6. **MEASURE** — Parse metrics from run.log:
@@ -144,7 +144,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
 8. **RECORD** — Log the experiment (kept or discarded):
    ```bash
-   python scripts/log_experiment.py experiments/log.jsonl exp-NNN kept|discarded \
+   uv run python scripts/log_experiment.py experiments/log.jsonl exp-NNN kept|discarded \
      '{"{{TARGET_METRIC}}": X.XX, ...}' \
      '{"model_type": "xgboost", "hyperparams": {...}}' \
      models/model.joblib "Description of hypothesis and outcome"
@@ -152,7 +152,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
    Update the hypothesis status with result metrics:
    ```bash
-   python scripts/manage_hypotheses.py mark hyp-NNN tested \
+   uv run python scripts/manage_hypotheses.py mark hyp-NNN tested \
      --result exp-NNN \
      --metrics '{"{{TARGET_METRIC}}": X.XX, ...}' \
      --notes "Brief explanation of what happened and why"
@@ -162,7 +162,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
    Then synthesize a decision packet and auto-queue follow-ups:
    ```bash
-   python scripts/synthesize_decision.py --experiment exp-NNN --auto-queue
+   uv run python scripts/synthesize_decision.py --experiment exp-NNN --auto-queue
    ```
    This produces a verdict (promote/branch_followup/abandon/fix_and_retry) and automatically queues follow-up hypotheses for `branch_followup` and `fix_and_retry` outcomes.
 
@@ -172,7 +172,7 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
    - Report final best model and recommend next steps
    - **Before declaring final results**, run a seed study to verify robustness:
      ```bash
-     python scripts/seed_runner.py --quick
+     uv run python scripts/seed_runner.py --quick
      ```
      If CV > 5%, the result is seed-sensitive — report mean ± std, not a single-seed number.
 
@@ -180,9 +180,9 @@ The autoresearch experiment loop. Each iteration is one experiment — one hypot
 
 ## Execution Rules
 
-- **ALWAYS redirect output:** `python train.py > run.log 2>&1`
+- **ALWAYS redirect output:** `uv run python train.py > run.log 2>&1`
 - **ALWAYS parse with grep:** `grep -A 10 "^---" run.log | head -10`
-- **ALWAYS activate venv:** `source .venv/bin/activate`
+- **ALWAYS run Python through uv:** `uv run python ...`
 - **NEVER install packages** without human approval
 
 ## Strategy Escalation Protocol
@@ -219,5 +219,5 @@ Starting suggestions (ordered by expected impact):
 ## Comparing Runs
 
 ```bash
-python scripts/compare_runs.py exp-001 exp-002
+uv run python scripts/compare_runs.py exp-001 exp-002
 ```

package/templates/pyproject.toml

@@ -2,6 +2,16 @@
 name = "{{PROJECT_NAME}}-ml"
 version = "0.1.0"
 requires-python = ">=3.12"
+dependencies = [
+    "scikit-learn>=1.6",
+    "xgboost>=3.2",
+    "lightgbm>=4.6",
+    "pandas>=2.2",
+    "numpy>=2.0",
+    "joblib>=1.4",
+    "pyyaml>=6.0",
+    "pytest>=8.0",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

package/templates/requirements.txt

@@ -1,3 +1,6 @@
+# Compatibility export only. pyproject.toml is canonical for dependencies.
+# Prefer: uv sync
+
 scikit-learn>=1.6
 xgboost>=3.2
 lightgbm>=4.6
@@ -8,5 +11,5 @@ pyyaml>=6.0
 pytest>=8.0
 
 # Optional: tree-search-guided hypothesis exploration
-# Install with: pip install "treequest[all]"
+# Install with: uv add "treequest[all]"
 # treequest>=0.1

package/templates/scripts/generate_onboarding.py

@@ -210,7 +210,7 @@ def format_onboarding_report(config, experiments, families, best, decisions,
         "5. `/turing:try \"your hypothesis\"` — inject ideas",
         "6. `/turing:train` — run next experiment",
     ], "engineer": [
-        "1. `pip install -r requirements.txt`",
+        "1. `uv sync`",
         "2. Review `config.yaml` for data paths",
         "3. `/turing:status` — where things stand",
         "4. Check `train.py` for current model",

package/templates/scripts/post-train-hook.sh

@@ -18,24 +18,23 @@ EXPERIMENT_LOG="${ML_DIR}/experiments/log.jsonl"
 if [[ -f "${ML_DIR}/run.log" ]]; then
     LOG_FILE="${ML_DIR}/run.log"
 elif [[ -f "run.log" ]]; then
-    LOG_FILE="run.log"
+    LOG_FILE="$(pwd)/run.log"
 else
     echo "post-train-hook: No run.log found, skipping."
     exit 0
 fi
 
-# Activate venv and delegate to Python
 cd "$ML_DIR"
-source .venv/bin/activate 2>/dev/null || true
+source "${SCRIPT_DIR}/turing-run-python.sh"
 
 # Parse metrics using the canonical parser
-PARSED=$(python3 scripts/parse_metrics.py "$LOG_FILE" --raw 2>/dev/null) || {
+PARSED=$(run_python scripts/parse_metrics.py "$LOG_FILE" --raw 2>/dev/null) || {
     echo "post-train-hook: No metrics block found in run.log, skipping."
     exit 0
 }
 
 # Extract metrics and metadata via Python (avoids bash JSON construction)
-METRICS_JSON=$(python3 -c "
+METRICS_JSON=$(run_python -c "
 import json, sys
 data = json.loads(sys.argv[1])
 metadata_keys = {'model_type', 'train_seconds'}
@@ -43,7 +42,7 @@ metrics = {k: v for k, v in data.items() if k not in metadata_keys}
 print(json.dumps(metrics))
 " "$PARSED")
 
-CONFIG_JSON=$(python3 -c "
+CONFIG_JSON=$(run_python -c "
 import json, sys
 data = json.loads(sys.argv[1])
 metadata_keys = {'model_type', 'train_seconds'}
@@ -55,14 +54,14 @@ print(json.dumps(config))
 GIT_COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
 
 # Get next experiment ID
-NEXT_ID=$(python3 -c "
+NEXT_ID=$(run_python -c "
 import sys; sys.path.insert(0, 'scripts')
 from log_experiment import get_next_experiment_id
 print(get_next_experiment_id('$EXPERIMENT_LOG'))
 ")
 
 # Log the experiment
-python3 scripts/log_experiment.py \
+run_python scripts/log_experiment.py \
     "$EXPERIMENT_LOG" \
     "$NEXT_ID" \
     "kept" \

package/templates/scripts/scaffold.py

@@ -22,6 +22,7 @@ import argparse
 import json
 import os
 import re
+import shlex
 import shutil
 import subprocess
 import sys
@@ -64,6 +65,7 @@ TEMPLATE_DIRS = {
         "sweep.py",
         "post-train-hook.sh",
         "stop-hook.sh",
+        "turing-run-python.sh",
         "check_convergence.py",
         "verify_placeholders.py",
         "manage_hypotheses.py",
@@ -220,6 +222,7 @@ DIRECTORIES_TO_CREATE = [
 SHELL_SCRIPTS = [
     "scripts/post-train-hook.sh",
     "scripts/stop-hook.sh",
+    "scripts/turing-run-python.sh",
 ]
 
 
@@ -289,7 +292,7 @@ def scaffold_project(
         templates_dir: Path to the templates/ directory.
         ml_dir: Target ML directory (relative to cwd).
         values: Dict mapping arg names to values for placeholder substitution.
-        setup_venv: Whether to create and populate a Python venv.
+        setup_venv: Whether to create and populate the uv environment.
         setup_hooks: Whether to configure Claude Code hooks.
 
     Returns:
@@ -361,9 +364,9 @@ def scaffold_project(
     if setup_hooks:
         _setup_hooks(ml_dir)
 
-    # Setup venv
+    # Setup Python environment
     if setup_venv:
-        _setup_venv(target)
+        _setup_environment(target)
 
     return stats
 
@@ -390,16 +393,18 @@ def _setup_hooks(ml_dir: str) -> None:
 
     hooks = settings.get("hooks", {})
 
+    target = Path(ml_dir).resolve()
+
     # PostToolUse hook for auto-logging
     post_hooks = hooks.get("PostToolUse", [])
-    post_hook_cmd = f"bash {ml_dir}/scripts/post-train-hook.sh"
+    post_hook_cmd = f"bash {shlex.quote(str(target / 'scripts' / 'post-train-hook.sh'))}"
     if not any(post_hook_cmd in str(h) for h in post_hooks):
         post_hooks.append(make_command_hook_group(post_hook_cmd, matcher="Bash"))
     hooks["PostToolUse"] = post_hooks
 
     # Stop hook for convergence
     stop_hooks = hooks.get("Stop", [])
-    stop_hook_cmd = f"bash {ml_dir}/scripts/stop-hook.sh"
+    stop_hook_cmd = f"bash {shlex.quote(str(target / 'scripts' / 'stop-hook.sh'))}"
     if not any(stop_hook_cmd in str(h) for h in stop_hooks):
         stop_hooks.append(make_command_hook_group(stop_hook_cmd))
     hooks["Stop"] = stop_hooks
@@ -408,29 +413,22 @@ def _setup_hooks(ml_dir: str) -> None:
     settings_path.write_text(json.dumps(settings, indent=2))
 
 
-def _setup_venv(target: Path) -> None:
-    """Create Python venv and install requirements."""
-    venv_path = target / ".venv"
-    if venv_path.exists():
-        print("  Venv already exists, skipping creation.", file=sys.stderr)
+def _setup_environment(target: Path) -> None:
+    """Create the uv-managed Python environment."""
+    if shutil.which("uv") is None:
+        print("  Warning: uv not found; run `uv sync` from the ML directory after installing uv.", file=sys.stderr)
         return
 
-    print("  Creating virtual environment...", file=sys.stderr)
+    print("  Syncing uv environment...", file=sys.stderr)
     try:
         subprocess.run(
-            [sys.executable, "-m", "venv", str(venv_path)],
-            check=True, capture_output=True,
+            ["uv", "sync"],
+            cwd=target,
+            check=True,
+            capture_output=True,
         )
-        pip = str(venv_path / "bin" / "pip")
-        req = str(target / "requirements.txt")
-        if Path(req).exists():
-            print("  Installing requirements...", file=sys.stderr)
-            subprocess.run(
-                [pip, "install", "-r", req],
-                check=True, capture_output=True,
-            )
     except subprocess.CalledProcessError as e:
-        print(f"  Warning: venv setup failed: {e}", file=sys.stderr)
+        print(f"  Warning: uv environment setup failed: {e}", file=sys.stderr)
 
 
 def verify_placeholders(ml_dir: str) -> list[tuple[str, int, str]]:
@@ -487,7 +485,7 @@ def main() -> None:
     parser.add_argument("--task-description", default=None)
     parser.add_argument("--ml-dir", default=None)
     parser.add_argument("--data-source", default=None)
-    parser.add_argument("--no-venv", action="store_true", help="Skip venv creation")
+    parser.add_argument("--no-venv", action="store_true", help="Skip uv environment setup")
     parser.add_argument("--no-hooks", action="store_true", help="Skip hook configuration")
     parser.add_argument("--templates-dir", default=None, help="Override templates directory")
     args = parser.parse_args()
@@ -546,9 +544,9 @@ def main() -> None:
 
     print(f"\nNext steps:")
     print(f"  1. Add training data to {values['data_source']}")
-    print(f"  2. cd {ml_dir} && source .venv/bin/activate")
-    print(f"  3. python prepare.py")
-    print(f"  4. /turing:train  (or: python train.py > run.log 2>&1)")
+    print(f"  2. cd {ml_dir} && uv sync")
+    print(f"  3. uv run python prepare.py")
+    print(f"  4. /turing:train  (or: uv run python train.py > run.log 2>&1)")
 
 
 if __name__ == "__main__":

package/templates/scripts/stop-hook.sh

@@ -25,10 +25,9 @@ if [[ ! -f "$EXPERIMENT_LOG" ]]; then
     exit 0
 fi
 
-# Activate venv and delegate to Python module
 cd "$ML_DIR"
-source .venv/bin/activate 2>/dev/null || true
+source "${SCRIPT_DIR}/turing-run-python.sh"
 
-python3 scripts/check_convergence.py \
+run_python scripts/check_convergence.py \
     --config "$CONFIG_FILE" \
     --log "$EXPERIMENT_LOG"

package/templates/scripts/turing-run-python.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+run_python() {
+    if ! command -v uv >/dev/null 2>&1; then
+        echo "turing: uv is required. Install uv or run legacy environment setup manually." >&2
+        return 127
+    fi
+    uv run python "$@"
+}