sciworld 0.1.0__tar.gz

sciworld-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taiming Lu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sciworld-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: sciworld
+Version: 0.1.0
+Summary: Turn published papers into research environments an AI agent can work in
+Author: Taiming Lu
+License: MIT
+Project-URL: Homepage, https://github.com/TaiMingLu/sciworld
+Project-URL: Repository, https://github.com/TaiMingLu/sciworld
+Project-URL: Issues, https://github.com/TaiMingLu/sciworld/issues
+Keywords: ai,agents,research,reproducibility,benchmark,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt_toolkit>=3.0
+Dynamic: license-file
+
+# sciworld
+
+Turn published papers into research environments an AI agent can actually work in.
+
+Every paper with public code is a frozen research trajectory — problem, method,
+baseline, metric, result. `sciworld` packages one of those into an isolated
+workspace, hands the keys to an agent (Claude Code or Codex), and lets it try
+to **reproduce**, **improve**, or **solve from scratch** — then scores the result.
+
+```bash
+pip install sciworld
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/TaiMingLu/sciworld.git
+cd sciworld
+pip install -e .
+```
+
+## CLI
+
+```bash
+sw init                                         # one-time setup wizard
+sw config [section]                             # view/edit (paths, compute, prompt, test-prompt, …)
+sw select [--id ID]                             # browse papers; clones <data_dir>/envs/<id>/source/
+sw info --id <arxiv_id> [--full]                # show paper overview/problem/experiments
+sw research --id <arxiv_id> [flags]             # build + launch a research env
+sw evaluate --id <arxiv_id> [--run NAME]        # compare run scores to paper scores
+```
+
+### `sw research` flags
+
+| Flag | What it does |
+|---|---|
+| `--id ARXIV_ID` | paper to work on (required for non-interactive use) |
+| `--mode improve \| scratch` | agent gets the method + results (`improve`) vs problem-only (`scratch`) |
+| `--agent claude-code \| codex` | which CLI runs inside the container |
+| `--tag TAG` | suffix for the run folder (e.g. `v2`, `ablation`) |
+| `--path DIR` | override workspace destination |
+| `--loop` | keep resuming the agent's session until `status.json.done=true` |
+| `--max-loops N` | safety cap for `--loop` (default 10) |
+| `--setup-only` | build the env + write `launch.sh` but **don't launch the agent** |
+| `--refresh` | bypass paper cache |
+
+`sw research` always writes a standalone `launch_<run_name>.sh` as a sibling
+of the workspace. Normal runs execute it inside tmux/screen/nohup. With
+`--setup-only`, nothing starts — the env is prepared and you can run
+`bash <path>/launch_<run_name>.sh` yourself (inside your own job scheduler,
+cron, or another session manager). Re-running the script is safe.
+
+### Train / test split (anti-shortcut)
+
+After the agent sets `status.json.done=true`, sciworld silently enters a
+test phase: copies the hidden `source/eval/test/` + `scripts/evaluate_test.sh`
+into the workspace, resumes the agent with a strict "be honest, do not
+cheat, do not modify your method" prompt, and records the test-side scores
+to `scoring/scores_test.json`. The test phase locks `method/` read-only.
+Nothing test-related is present in the workspace during main-phase operation.
+
+### Trajectory and token capture
+
+Each CLI invocation writes raw JSONL events to
+`<env_dir>/trajectory/turn_NNNN_raw.jsonl` and merges a unified summary
+into `<env_dir>/trajectory/stats.json` with `{input_tokens, output_tokens,
+num_turns, duration_s, cost_usd, tool_uses}` — identical shape for Claude
+Code and Codex.
+
+## Python API
+
+Every CLI command is also a Python function with the same name and matching
+kwargs. Required args missing → `TypeError`; non-zero exit → `RuntimeError`
+(no interactive prompts — notebook/script-safe).
+
+```python
+import sciworld
+from pathlib import Path
+
+info = sciworld.research(
+    id="2505.19252", agent="claude-code", mode="scratch",
+    loop=True, max_loops=5,
+    system_prompt=Path("~/my_prompts/strict.md").expanduser(),
+    test_prompt="Run evaluate_test.sh, write reflection.md, stop.",
+    setup_only=False,       # True → write launch.sh, don't launch
+)
+# → {"arxiv_id", "run_name", "env_dir", "source_dir", "launch_script"}
+
+sciworld.evaluate(id="2505.19252", run=info["run_name"])
+sciworld.info(id="2505.19252")
+sciworld.select(id="2505.19252")
+sciworld.config()                               # returns current config dict
+sciworld.config(section="compute")              # opens the interactive editor
+sciworld.init(force=False)                      # first-time setup wizard
+```
+
+Prompt kwargs (`system_prompt`, `mode_prompt`, `continue_prompt`,
+`test_prompt`, `compute`) accept either a literal `str` or a
+`pathlib.Path` — paths are read at call time. Use `import sciworld as sw`
+if you prefer the two-letter alias.
+
+## Where things live
+
+| Path | What's there |
+|---|---|
+| `~/.sciworld/config.json` | your config (paths, container, session, env bindings) |
+| `~/.sciworld/instructions/*.md` | your customized prompts (system, research_scratch, continue, test, compute) |
+| `<data_dir>/envs/<id>/source/` | cloned paper repo |
+| `<data_dir>/envs/<id>/<run_name>/` | per-run agent workspace (bind-mounted into container) |
+| `<data_dir>/envs/<id>/launch_<run_name>.sh` | launcher — **outside** the workspace, not visible to the agent |
+| `<run_workspace>/agent.log` | full pretty-printed session log |
+| `<run_workspace>/trajectory/` | raw per-turn JSONL + merged stats.json |
+| `<run_workspace>/scoring/scores_train.json` | agent's train-side scores |
+| `<run_workspace>/scoring/scores_test.json` | agent's test-side scores (written during test phase) |
+| `<run_workspace>/idea.md`, `reflection.md` | agent's end-of-run notes |
+
+## Default prompts
+
+All bundled prompts live as markdown under `sciworld/prompts/` — nothing
+prompt-related is hardcoded in Python. Per-user overrides go into
+`~/.sciworld/instructions/` via `sw config …`.
+
+| File | When it's used |
+|---|---|
+| `system_prompt.md` | base role description, prepended to every launch |
+| `improve.md`, `scratch.md` | mode-specific task instructions |
+| `environment.md` | container housekeeping note (appended to every launch) |
+| `continue.md` | follow-up message for each `--loop` iteration |
+| `test.md` | strict test-phase prompt (sent only at test-phase transition) |
+
+Run any command with `--help` for details.

sciworld-0.1.0/README.md

@@ -0,0 +1,131 @@
+# sciworld
+
+Turn published papers into research environments an AI agent can actually work in.
+
+Every paper with public code is a frozen research trajectory — problem, method,
+baseline, metric, result. `sciworld` packages one of those into an isolated
+workspace, hands the keys to an agent (Claude Code or Codex), and lets it try
+to **reproduce**, **improve**, or **solve from scratch** — then scores the result.
+
+```bash
+pip install sciworld
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/TaiMingLu/sciworld.git
+cd sciworld
+pip install -e .
+```
+
+## CLI
+
+```bash
+sw init                                         # one-time setup wizard
+sw config [section]                             # view/edit (paths, compute, prompt, test-prompt, …)
+sw select [--id ID]                             # browse papers; clones <data_dir>/envs/<id>/source/
+sw info --id <arxiv_id> [--full]                # show paper overview/problem/experiments
+sw research --id <arxiv_id> [flags]             # build + launch a research env
+sw evaluate --id <arxiv_id> [--run NAME]        # compare run scores to paper scores
+```
+
+### `sw research` flags
+
+| Flag | What it does |
+|---|---|
+| `--id ARXIV_ID` | paper to work on (required for non-interactive use) |
+| `--mode improve \| scratch` | agent gets the method + results (`improve`) vs problem-only (`scratch`) |
+| `--agent claude-code \| codex` | which CLI runs inside the container |
+| `--tag TAG` | suffix for the run folder (e.g. `v2`, `ablation`) |
+| `--path DIR` | override workspace destination |
+| `--loop` | keep resuming the agent's session until `status.json.done=true` |
+| `--max-loops N` | safety cap for `--loop` (default 10) |
+| `--setup-only` | build the env + write `launch.sh` but **don't launch the agent** |
+| `--refresh` | bypass paper cache |
+
+`sw research` always writes a standalone `launch_<run_name>.sh` as a sibling
+of the workspace. Normal runs execute it inside tmux/screen/nohup. With
+`--setup-only`, nothing starts — the env is prepared and you can run
+`bash <path>/launch_<run_name>.sh` yourself (inside your own job scheduler,
+cron, or another session manager). Re-running the script is safe.
+
+### Train / test split (anti-shortcut)
+
+After the agent sets `status.json.done=true`, sciworld silently enters a
+test phase: copies the hidden `source/eval/test/` + `scripts/evaluate_test.sh`
+into the workspace, resumes the agent with a strict "be honest, do not
+cheat, do not modify your method" prompt, and records the test-side scores
+to `scoring/scores_test.json`. The test phase locks `method/` read-only.
+Nothing test-related is present in the workspace during main-phase operation.
+
+### Trajectory and token capture
+
+Each CLI invocation writes raw JSONL events to
+`<env_dir>/trajectory/turn_NNNN_raw.jsonl` and merges a unified summary
+into `<env_dir>/trajectory/stats.json` with `{input_tokens, output_tokens,
+num_turns, duration_s, cost_usd, tool_uses}` — identical shape for Claude
+Code and Codex.
+
+## Python API
+
+Every CLI command is also a Python function with the same name and matching
+kwargs. Required args missing → `TypeError`; non-zero exit → `RuntimeError`
+(no interactive prompts — notebook/script-safe).
+
+```python
+import sciworld
+from pathlib import Path
+
+info = sciworld.research(
+    id="2505.19252", agent="claude-code", mode="scratch",
+    loop=True, max_loops=5,
+    system_prompt=Path("~/my_prompts/strict.md").expanduser(),
+    test_prompt="Run evaluate_test.sh, write reflection.md, stop.",
+    setup_only=False,       # True → write launch.sh, don't launch
+)
+# → {"arxiv_id", "run_name", "env_dir", "source_dir", "launch_script"}
+
+sciworld.evaluate(id="2505.19252", run=info["run_name"])
+sciworld.info(id="2505.19252")
+sciworld.select(id="2505.19252")
+sciworld.config()                               # returns current config dict
+sciworld.config(section="compute")              # opens the interactive editor
+sciworld.init(force=False)                      # first-time setup wizard
+```
+
+Prompt kwargs (`system_prompt`, `mode_prompt`, `continue_prompt`,
+`test_prompt`, `compute`) accept either a literal `str` or a
+`pathlib.Path` — paths are read at call time. Use `import sciworld as sw`
+if you prefer the two-letter alias.
+
+## Where things live
+
+| Path | What's there |
+|---|---|
+| `~/.sciworld/config.json` | your config (paths, container, session, env bindings) |
+| `~/.sciworld/instructions/*.md` | your customized prompts (system, research_scratch, continue, test, compute) |
+| `<data_dir>/envs/<id>/source/` | cloned paper repo |
+| `<data_dir>/envs/<id>/<run_name>/` | per-run agent workspace (bind-mounted into container) |
+| `<data_dir>/envs/<id>/launch_<run_name>.sh` | launcher — **outside** the workspace, not visible to the agent |
+| `<run_workspace>/agent.log` | full pretty-printed session log |
+| `<run_workspace>/trajectory/` | raw per-turn JSONL + merged stats.json |
+| `<run_workspace>/scoring/scores_train.json` | agent's train-side scores |
+| `<run_workspace>/scoring/scores_test.json` | agent's test-side scores (written during test phase) |
+| `<run_workspace>/idea.md`, `reflection.md` | agent's end-of-run notes |
+
+## Default prompts
+
+All bundled prompts live as markdown under `sciworld/prompts/` — nothing
+prompt-related is hardcoded in Python. Per-user overrides go into
+`~/.sciworld/instructions/` via `sw config …`.
+
+| File | When it's used |
+|---|---|
+| `system_prompt.md` | base role description, prepended to every launch |
+| `improve.md`, `scratch.md` | mode-specific task instructions |
+| `environment.md` | container housekeeping note (appended to every launch) |
+| `continue.md` | follow-up message for each `--loop` iteration |
+| `test.md` | strict test-phase prompt (sent only at test-phase transition) |
+
+Run any command with `--help` for details.

sciworld-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "sciworld"
+version = "0.1.0"
+description = "Turn published papers into research environments an AI agent can work in"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Taiming Lu" },
+]
+keywords = ["ai", "agents", "research", "reproducibility", "benchmark", "llm"]
+dependencies = [
+    "prompt_toolkit>=3.0",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/TaiMingLu/sciworld"
+Repository = "https://github.com/TaiMingLu/sciworld"
+Issues = "https://github.com/TaiMingLu/sciworld/issues"
+
+[project.scripts]
+sciworld = "sciworld.cli:main"
+sw = "sciworld.cli:main"
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sciworld*"]
+
+[tool.setuptools.package-data]
+sciworld = ["containers/*", "prompts/*.md", "format_stream.py"]

sciworld-0.1.0/sciworld/__init__.py

@@ -0,0 +1,32 @@
+"""sciworld — research environments for paper reproduction.
+
+This package exposes the same commands the ``sw`` CLI provides as Python
+functions. Typical usage from a script or notebook:
+
+    import sciworld
+
+    sciworld.research(id="2505.19252", agent="claude-code", mode="scratch",
+                      loop=True, max_loops=5)
+    sciworld.evaluate(id="2505.19252", run="claude-code-scratch")
+
+Prompt kwargs accept either a literal string or a ``pathlib.Path`` — the
+file is read at call time.
+"""
+
+from sciworld._api import (
+    research,
+    evaluate,
+    select,
+    info,
+    init,
+    config,
+)
+
+__all__ = [
+    "research",
+    "evaluate",
+    "select",
+    "info",
+    "init",
+    "config",
+]

sciworld-0.1.0/sciworld/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m sciworld``."""
+from sciworld.cli import main
+import sys
+
+sys.exit(main())

sciworld-0.1.0/sciworld/_api.py

@@ -0,0 +1,242 @@
+"""Python API mirror of the ``sw`` CLI.
+
+Every top-level CLI command has a sibling Python function here. The
+function signature reuses the CLI's kwargs; interactive prompts are
+replaced with ``TypeError`` on missing required args so calling the
+API from a notebook or script never blocks on stdin.
+
+Typical usage:
+
+    import sciworld
+    result = sciworld.research(
+        id="2505.19252", agent="claude-code", mode="scratch",
+        loop=True, max_loops=5,
+        system_prompt=Path("~/my_prompts/strict.md"),
+    )
+    # result = {"arxiv_id": ..., "run_name": ..., "env_dir": Path(...),
+    #           "launch_script": Path(...), "source_dir": Path(...)}
+
+    sciworld.evaluate(id="2505.19252", run=result["run_name"])
+
+Prompt kwargs (``system_prompt``, ``mode_prompt``, ``continue_prompt``,
+``test_prompt``, ``compute``) accept either a literal string or a
+``pathlib.Path``. Paths are read at call time — the resolved content
+is used for that call; later file edits do not affect the running
+session (for live per-iteration binding, see the `live_prompts`
+roadmap item).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from sciworld import config as _config
+
+
+# ── Helpers ────────────────────────────────────────────────
+
+
+def _resolve_prompt(value: Any) -> str | None:
+    """Normalize a prompt kwarg: Path → file content; str → as-is; None → None."""
+    if value is None:
+        return None
+    if isinstance(value, Path):
+        return value.expanduser().read_text()
+    return str(value)
+
+
+def _require(**kwargs) -> None:
+    """Raise TypeError for any kwarg that's None (required but missing)."""
+    missing = [k for k, v in kwargs.items() if v is None]
+    if missing:
+        raise TypeError(
+            f"Missing required argument(s): {', '.join(missing)}"
+        )
+
+
+def _run_with_overrides(callable_, args_ns, overrides: dict) -> int:
+    """Run a cmd_* function with prompt overrides active for this call."""
+    if not overrides:
+        return callable_(args_ns)
+    token = _config._instruction_overrides.set(overrides)
+    try:
+        return callable_(args_ns)
+    finally:
+        _config._instruction_overrides.reset(token)
+
+
+# ── research ──────────────────────────────────────────────
+
+
+def research(
+    *,
+    id: str,
+    agent: str,
+    mode: str,
+    tag: str | None = None,
+    path: str | Path | None = None,
+    loop: bool = False,
+    max_loops: int = 10,
+    setup_only: bool = False,
+    refresh: bool = False,
+    org: str | None = None,
+    system_prompt: str | Path | None = None,
+    mode_prompt: str | Path | None = None,
+    continue_prompt: str | Path | None = None,
+    test_prompt: str | Path | None = None,
+    compute: str | Path | None = None,
+) -> dict:
+    """Build (and optionally launch) a research environment.
+
+    Mirrors ``sw research``. Returns a dict with ``arxiv_id``, ``run_name``,
+    ``env_dir``, ``source_dir``, ``launch_script`` — all the paths you need
+    to inspect the workspace or tail the agent log.
+
+    Raises ``TypeError`` if any of the three required kwargs (``id``,
+    ``agent``, ``mode``) is missing, and ``RuntimeError`` if the command
+    itself exits with a non-zero return code.
+    """
+    _require(id=id, agent=agent, mode=mode)
+
+    from sciworld.research_cmd import cmd_research  # lazy import
+
+    args_ns = SimpleNamespace(
+        paper_id=id,
+        agent=agent,
+        mode=mode,
+        tag=tag,
+        dest_path=str(path) if path else None,
+        loop=loop,
+        max_loops=max_loops,
+        setup_only=setup_only,
+        refresh=refresh,
+        org=org,
+    )
+
+    overrides: dict[str, str] = {}
+    if system_prompt is not None:
+        overrides["system_prompt"] = _resolve_prompt(system_prompt)
+    if mode_prompt is not None:
+        overrides[f"research_{mode}"] = _resolve_prompt(mode_prompt)
+    if continue_prompt is not None:
+        overrides["continue"] = _resolve_prompt(continue_prompt)
+    if test_prompt is not None:
+        overrides["test"] = _resolve_prompt(test_prompt)
+    if compute is not None:
+        overrides["compute"] = _resolve_prompt(compute)
+
+    rc = _run_with_overrides(cmd_research, args_ns, overrides)
+    if rc != 0:
+        raise RuntimeError(f"sciworld.research exited with code {rc}")
+
+    result = getattr(args_ns, "_sw_result", None)
+    if result is None:
+        raise RuntimeError(
+            "sciworld.research completed but produced no result metadata"
+        )
+    return result
+
+
+# ── evaluate ──────────────────────────────────────────────
+
+
+def evaluate(*, id: str, run: str | None = None) -> int:
+    """Compare a run's scores to the paper's scores.
+
+    Mirrors ``sw evaluate``. Returns the command's exit code (0 = success).
+    Raises ``TypeError`` if ``id`` is missing.
+    """
+    _require(id=id)
+    from sciworld.evaluate_cmd import cmd_evaluate  # lazy import
+
+    args_ns = SimpleNamespace(arxiv_id=id, run=run)
+    return cmd_evaluate(args_ns)
+
+
+# ── select ────────────────────────────────────────────────
+
+
+def select(
+    *,
+    id: str | None = None,
+    path: str | Path | None = None,
+    refresh: bool = False,
+) -> int:
+    """Select a paper and clone its repo.
+
+    Mirrors ``sw select``. When ``id`` is given, fetches that paper
+    directly; when missing, raises ``TypeError`` (no interactive fallback
+    in the Python API).
+    """
+    _require(id=id)
+    from sciworld.select_cmd import cmd_select  # lazy import
+
+    args_ns = SimpleNamespace(
+        paper_id=id,
+        dest_path=str(path) if path else None,
+        refresh=refresh,
+    )
+    return cmd_select(args_ns)
+
+
+# ── info ──────────────────────────────────────────────────
+
+
+def info(*, id: str, full: bool = False) -> int:
+    """Show a paper's metadata (overview, problem, experiments, …).
+
+    Mirrors ``sw info``. Raises ``TypeError`` if ``id`` is missing.
+    """
+    _require(id=id)
+    from sciworld.info_cmd import cmd_info  # lazy import
+
+    args_ns = SimpleNamespace(arxiv_id=id, full=full)
+    return cmd_info(args_ns)
+
+
+# ── config ────────────────────────────────────────────────
+
+
+def config(section: str | None = None, **overrides) -> dict:
+    """View or update configuration.
+
+    ``sciworld.config()`` → returns the current config as a dict.
+    ``sciworld.config(section="...")`` → runs the interactive editor for
+    that section; raises ``ValueError`` if the section is unknown.
+    """
+    if section is None and not overrides:
+        return dict(_config.load_config())
+
+    if section is not None:
+        from sciworld.cli import _CONFIG_SECTIONS, cmd_config
+        if section not in _CONFIG_SECTIONS:
+            valid = ", ".join(_CONFIG_SECTIONS)
+            raise ValueError(f"Unknown config section {section!r}. Valid: {valid}")
+        args_ns = SimpleNamespace(section=section)
+        cmd_config(args_ns)
+        return dict(_config.load_config())
+
+    # If we got here, someone passed raw kwargs with no section. Write them
+    # straight into config.json. (Low-level escape hatch.)
+    cfg = dict(_config.load_config())
+    cfg.update(overrides)
+    _config.save_config(cfg)
+    return cfg
+
+
+# ── init ──────────────────────────────────────────────────
+
+
+def init(*, force: bool = False) -> int:
+    """Run the first-time setup wizard (builds the agent SIF, etc.).
+
+    Mirrors ``sw init``. The underlying command is interactive; calling
+    it from a script typically only makes sense with the setup already
+    partially complete. ``force=True`` rebuilds the agent container.
+    """
+    from sciworld.cli import cmd_init  # lazy import
+
+    args_ns = SimpleNamespace(force=force)
+    return cmd_init(args_ns)

sciworld-0.1.0/sciworld/cache.py

@@ -0,0 +1,42 @@
+"""TTL-based cache for GitHub repo data."""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+from sciworld.config import config_dir
+
+CACHE_DIR = config_dir() / "cache"
+
+
+def cache_path(org: str) -> Path:
+    return CACHE_DIR / f"{org}_repos.json"
+
+
+def load_cached(org: str, ttl: int = 600) -> list[dict] | None:
+    """Load cached repo data. Returns None if stale or missing."""
+    path = cache_path(org)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        if time.time() - data.get("timestamp", 0) > ttl:
+            return None
+        return data.get("repos", [])
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def save_cached(org: str, repos: list[dict]) -> None:
+    """Write repos to cache with current timestamp."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    data = {"timestamp": time.time(), "repos": repos}
+    cache_path(org).write_text(json.dumps(data))
+
+
+def invalidate(org: str) -> None:
+    """Delete cache for an org."""
+    path = cache_path(org)
+    if path.exists():
+        path.unlink()