sciworld 0.1.0__py3-none-any.whl

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/__main__.py

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

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/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()