display_name: Rigor Setup
short_description: Rigor Setup mode for conservative environment and asset assumptions before a reproduction run.
default_prompt: Prepare a conservative conda-first environment plus checkpoint, dataset, and cache assumptions for this README-documented reproduction target before any run.

# Assets Policy

## Goal

Prepare checkpoints, datasets, and caches conservatively and transparently.

## Order of evidence

1. README links and paths
2. config files and default arguments
3. code-level constants or path joins
4. careful inference from filenames

## Behavior

- prefer documented asset sources
- preserve source URLs or identifiers when recording downloads
- avoid mirroring unofficial files unless the project explicitly points to them
- never claim an asset is the canonical one unless the repository or primary paper source supports it

## Common asset groups

- model checkpoints
- tokenizer files
- dataset archives or prepared splits
- cache directories
- output directories

## Reporting

Record:

- requested asset
- source
- target local path
- status: present, missing, downloaded, skipped, unknown

# Environment Policy

## Default preference

Prefer conda or Anaconda-style setup for deep learning research repositories because it is common in research code and helps isolate conflicting dependencies.

## Order of trust

1. README environment instructions
2. repository environment files
3. package metadata files
4. conservative inference from imports or script names

## OS guidance

- Linux is the default reference environment.
- Support Windows and macOS where practical.
- If a repository is clearly Linux-only, record that rather than pretending otherwise.
- When virtualenv activation is needed, emit platform-specific commands instead of a fake one-size-fits-all activation step.
- Prefer Python entrypoints over shell-only helpers when the same setup logic should run on Windows, macOS, and Linux.

## Dependency handling

- prefer existing `environment.yml`
- otherwise translate README requirements into a simple conda-plus-pip setup
- avoid aggressive upgrades unless needed for a verified fix
- record version uncertainty explicitly

## Out of scope by default

- container orchestration
- cluster schedulers
- custom CUDA builds unless clearly required

#!/usr/bin/env python3
"""Bootstrap a conservative research environment on Windows, macOS, or Linux."""

from __future__ import annotations

import argparse
import shutil
import subprocess
import sys
from pathlib import Path
from typing import Iterable, List, Optional

from plan_setup import ENV_FILES, find_first, parse_env_name, venv_activation_commands


CONDA_ENV_FILES = {"environment.yml", "environment.yaml", "conda.yml"}


def format_command(command: Iterable[str]) -> str:
    return " ".join(str(part) for part in command)


def run_command(command: List[str], *, cwd: Path, dry_run: bool) -> None:
    print(f"+ {format_command(command)}")
    if dry_run:
        return
    subprocess.run(command, cwd=cwd, check=True)


def choose_manager(preferred: str) -> Optional[str]:
    if preferred != "auto":
        if shutil.which(preferred):
            return preferred
        raise FileNotFoundError(f"Requested manager `{preferred}` was not found on PATH.")

    for candidate in ["conda", "mamba"]:
        if shutil.which(candidate):
            return candidate
    return None


def venv_python(env_dir: Path) -> Path:
    if sys.platform.startswith("win"):
        return env_dir / "Scripts" / "python.exe"
    return env_dir / "bin" / "python"


def print_activation_instructions(env_name: Optional[str], using_conda: bool) -> None:
    if using_conda:
        target = env_name or "<env-name>"
        print(f"Activate with: conda activate {target}")
        return

    print("Activate the virtualenv with one of:")
    for item in venv_activation_commands():
        platforms = ", ".join(item.get("platforms", []))
        print(f"  [{platforms}] {item['command']}")


def install_with_manager(manager: str, env_name: str, repo_path: Path, rel_env_file: Optional[str], *, dry_run: bool) -> None:
    if rel_env_file == "requirements.txt":
        run_command(
            [manager, "run", "-n", env_name, "python", "-m", "pip", "install", "-r", rel_env_file],
            cwd=repo_path,
            dry_run=dry_run,
        )
    elif rel_env_file in {"pyproject.toml", "setup.py"}:
        run_command(
            [manager, "run", "-n", env_name, "python", "-m", "pip", "install", "-e", "."],
            cwd=repo_path,
            dry_run=dry_run,
        )


def install_with_venv(env_python: Path, repo_path: Path, rel_env_file: Optional[str], *, dry_run: bool) -> None:
    if rel_env_file == "requirements.txt":
        run_command(
            [str(env_python), "-m", "pip", "install", "-r", rel_env_file],
            cwd=repo_path,
            dry_run=dry_run,
        )
    elif rel_env_file in {"pyproject.toml", "setup.py"}:
        run_command(
            [str(env_python), "-m", "pip", "install", "-e", "."],
            cwd=repo_path,
            dry_run=dry_run,
        )


def main() -> int:
    parser = argparse.ArgumentParser(description="Bootstrap a conservative AI research environment.")
    parser.add_argument("repo", nargs="?", default=".", help="Target repository path.")
    parser.add_argument("env_name", nargs="?", default="repro-env", help="Fallback environment name.")
    parser.add_argument("--python-version", default="3.10", help="Python version to use for conda or mamba environments.")
    parser.add_argument(
        "--manager",
        choices=["auto", "conda", "mamba"],
        default="auto",
        help="Conda-compatible manager to use when available.",
    )
    parser.add_argument("--dry-run", action="store_true", help="Print commands without executing them.")
    args = parser.parse_args()

    repo_path = Path(args.repo).resolve()
    env_file = find_first(repo_path, ENV_FILES)
    rel_env_file = env_file.relative_to(repo_path).as_posix() if env_file else None
    declared_env_name = parse_env_name(env_file) if env_file else None
    resolved_env_name = declared_env_name or args.env_name
    manager = choose_manager(args.manager)

    print(f"Target repo: {repo_path}")
    print(f"Detected environment file: {rel_env_file or 'none'}")

    if env_file and env_file.name in CONDA_ENV_FILES:
        if manager is None:
            raise SystemExit("A conda-compatible manager is required for environment.yml-based setup. Install conda or mamba first.")

        create_command = [manager, "env", "create", "-f", rel_env_file]
        if not declared_env_name:
            create_command.extend(["-n", resolved_env_name])
        run_command(create_command, cwd=repo_path, dry_run=args.dry_run)
        print_activation_instructions(declared_env_name or resolved_env_name, using_conda=True)
        return 0

    if manager is not None:
        run_command(
            [manager, "create", "-y", "-n", resolved_env_name, f"python={args.python_version}"],
            cwd=repo_path,
            dry_run=args.dry_run,
        )
        install_with_manager(manager, resolved_env_name, repo_path, rel_env_file, dry_run=args.dry_run)
        print_activation_instructions(resolved_env_name, using_conda=True)
        return 0

    env_dir = repo_path / ".venv"
    run_command([sys.executable, "-m", "venv", str(env_dir)], cwd=repo_path, dry_run=args.dry_run)
    install_with_venv(venv_python(env_dir), repo_path, rel_env_file, dry_run=args.dry_run)
    print_activation_instructions(None, using_conda=False)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PYTHON_BIN="${PYTHON:-python3}"

if ! command -v "${PYTHON_BIN}" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

exec "${PYTHON_BIN}" "${SCRIPT_DIR}/bootstrap_env.py" "$@"

#!/usr/bin/env python3
"""Create a conservative environment setup plan for a research repository."""

from __future__ import annotations

import argparse
import json
import re
from pathlib import Path
from typing import Any, Dict, List, Optional


ENV_FILES = [
    "environment.yml",
    "environment.yaml",
    "conda.yml",
    "requirements.txt",
    "pyproject.toml",
    "setup.py",
]
ALL_PLATFORMS = ["windows", "macos", "linux"]


def find_first(repo: Path, candidates: List[str]) -> Optional[Path]:
    for name in candidates:
        path = repo / name
        if path.exists():
            return path
    return None


def parse_env_name(path: Path) -> Optional[str]:
    if path.suffix not in {".yml", ".yaml"}:
        return None
    text = path.read_text(encoding="utf-8", errors="replace")
    match = re.search(r"^\s*name:\s*([A-Za-z0-9._-]+)\s*$", text, flags=re.MULTILINE)
    return match.group(1) if match else None


def command_entry(label: str, command: str, platforms: Optional[List[str]] = None) -> Dict[str, Any]:
    return {
        "label": label,
        "command": command,
        "platforms": list(platforms or ALL_PLATFORMS),
    }


def venv_activation_commands() -> List[Dict[str, Any]]:
    return [
        command_entry("adapted", ".\\.venv\\Scripts\\Activate.ps1", ["windows"]),
        command_entry("adapted", "source .venv/bin/activate", ["macos", "linux"]),
    ]


def append_venv_flow(setup_commands: List[Dict[str, Any]], install_command: Optional[str] = None) -> None:
    setup_commands.append(command_entry("adapted", "python -m venv .venv"))
    setup_commands.extend(venv_activation_commands())
    if install_command:
        setup_commands.append(command_entry("documented", install_command))


def build_setup_commands(repo: Path) -> Dict[str, object]:
    setup_commands: List[Dict[str, Any]] = []
    notes: List[str] = []
    unresolved: List[str] = []

    env_file = find_first(repo, ENV_FILES)
    env_name = parse_env_name(env_file) if env_file else None

    if env_file is None:
        unresolved.append("No top-level environment specification file was found.")
        setup_commands.append(command_entry("inferred", "python -m venv .venv"))
        setup_commands.extend(
            [
                command_entry("inferred", ".\\.venv\\Scripts\\Activate.ps1", ["windows"]),
                command_entry("inferred", "source .venv/bin/activate", ["macos", "linux"]),
            ]
        )
        notes.append("Defaulted to a virtualenv fallback because no environment file was detected.")
        return {
            "environment_file": None,
            "environment_name": None,
            "setup_commands": setup_commands,
            "setup_notes": notes,
            "unresolved_setup_risks": unresolved,
        }

    rel_env_file = env_file.relative_to(repo).as_posix()
    notes.append(f"Detected environment file `{rel_env_file}`.")
    if env_name:
        notes.append(f"Detected conda environment name `{env_name}`.")

    if env_file.name in {"environment.yml", "environment.yaml", "conda.yml"}:
        setup_commands.append(command_entry("documented", f"conda env create -f {rel_env_file}"))
        setup_commands.append(command_entry("adapted", f"conda activate {env_name}" if env_name else "conda activate <env-name>"))
        if not env_name:
            unresolved.append("The conda environment name was not declared and still needs confirmation.")
    elif env_file.name == "requirements.txt":
        append_venv_flow(setup_commands, f"python -m pip install -r {rel_env_file}")
        notes.append("Fell back to a virtualenv plus requirements installation plan.")
    elif env_file.name == "pyproject.toml":
        append_venv_flow(setup_commands, "python -m pip install -e .")
        notes.append("Detected a pyproject-based installation flow.")
    elif env_file.name == "setup.py":
        append_venv_flow(setup_commands, "python -m pip install -e .")
        notes.append("Detected a setup.py-based editable install flow.")

    return {
        "environment_file": rel_env_file,
        "environment_name": env_name,
        "setup_commands": setup_commands,
        "setup_notes": notes,
        "unresolved_setup_risks": unresolved,
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Create a conservative environment setup plan.")
    parser.add_argument("--repo", required=True, help="Path to the target repository.")
    parser.add_argument("--json", action="store_true", help="Emit JSON output.")
    args = parser.parse_args()

    repo = Path(args.repo).resolve()
    payload = build_setup_commands(repo)
    text = json.dumps(payload, indent=2, ensure_ascii=False)
    print(text)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

#!/usr/bin/env python3
"""Prepare a conservative asset manifest for reproduction work."""

from __future__ import annotations

import argparse
import json
import re
from pathlib import Path
from typing import Dict, List


COMMON_ASSET_DIRS = ["datasets", "data", "checkpoints", "weights", "cache", ".cache"]
KEYWORDS = ("checkpoint", "weight", "dataset", "cache", "model", "download")
URL_RE = re.compile(r"https?://\S+")
PATH_RE = re.compile(r"[\w./-]+\.(?:ckpt|pth|pt|bin|safetensors|zip|tar|gz|json|yaml)")


def first_existing(root: Path, names: List[str]) -> Path | None:
    for name in names:
        candidate = root / name
        if candidate.exists():
            return candidate
    return None


def collect_text_hints(repo: Path) -> List[Dict[str, str]]:
    hints: List[Dict[str, str]] = []
    readme = first_existing(repo, ["README.md", "README"])
    if readme:
        text = readme.read_text(encoding="utf-8", errors="replace")
        for line in text.splitlines():
            lowered = line.lower()
            if not any(keyword in lowered for keyword in KEYWORDS):
                continue
            urls = URL_RE.findall(line)
            paths = PATH_RE.findall(line)
            if not urls and not paths:
                continue
            hints.append(
                {
                    "source": str(readme.resolve()),
                    "line": line.strip(),
                    "urls": ", ".join(urls) if urls else "",
                    "paths": ", ".join(paths) if paths else "",
                }
            )

    for directory in ["configs", "config"]:
        config_root = repo / directory
        if not config_root.exists():
            continue
        for path in config_root.rglob("*"):
            if not path.is_file() or path.suffix.lower() not in {".py", ".yaml", ".yml", ".json", ".toml"}:
                continue
            text = path.read_text(encoding="utf-8", errors="replace")
            if not any(keyword in text.lower() for keyword in KEYWORDS):
                continue
            matches = PATH_RE.findall(text)
            urls = URL_RE.findall(text)
            if not matches and not urls:
                continue
            hints.append(
                {
                    "source": str(path.resolve()),
                    "line": "config hint",
                    "urls": ", ".join(urls[:3]) if urls else "",
                    "paths": ", ".join(matches[:5]) if matches else "",
                }
            )
    return hints


def prepare_assets(repo: Path, assets_root: Path) -> Dict[str, object]:
    assets_root.mkdir(parents=True, exist_ok=True)
    manifest: List[Dict[str, str]] = []

    for name in COMMON_ASSET_DIRS:
        repo_candidate = repo / name
        manifest.append(
            {
                "asset_group": name,
                "source_hint": str(repo_candidate.resolve()) if repo_candidate.exists() else "not found in repo",
                "target_path": str((assets_root / name).resolve()),
                "status": "present" if repo_candidate.exists() else "missing",
            }
        )

    return {
        "repo_path": str(repo.resolve()),
        "assets_root": str(assets_root.resolve()),
        "manifest": manifest,
        "text_hints": collect_text_hints(repo),
    }


def main() -> int:
    parser = argparse.ArgumentParser(description="Create a conservative asset manifest.")
    parser.add_argument("--repo", required=True, help="Path to the target repository.")
    parser.add_argument("--assets-root", default="artifacts/assets", help="Directory where prepared assets should live.")
    parser.add_argument(
        "--output-json",
        default="artifacts/assets/asset_manifest.json",
        help="Path to write the manifest JSON.",
    )
    args = parser.parse_args()

    repo = Path(args.repo).resolve()
    assets_root = Path(args.assets_root).resolve()
    output_json = Path(args.output_json).resolve()
    output_json.parent.mkdir(parents=True, exist_ok=True)

    data = prepare_assets(repo, assets_root)
    output_json.write_text(json.dumps(data, indent=2, ensure_ascii=False), encoding="utf-8")
    print(json.dumps(data, indent=2, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())