acumen 0.0.1.dev0__py3-none-any.whl

acumen/config.py

@@ -0,0 +1,204 @@
+"""Config schema and loader for ``config.yaml``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .paths import PathError, slugify
+
+
+class ConfigError(ValueError):
+    """Raised when ``config.yaml`` is malformed."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Everything a pass needs that isn't a task: target, models, budgets, concurrency."""
+
+    repo: str
+    skill_name: str
+    ref: str = "main"
+    extras: list[str] = field(default_factory=list)
+    python: str = "3.12"
+    #: Names of environment variables to carry from the operator's shell into isolated
+    #: agents (bench sandboxes and the draft/improve/tasks meta-agents), on top of the
+    #: built-in auth/proxy allowlist. The agent env is otherwise a clean allowlist — every
+    #: other inherited variable is blanked — so a target that needs a runtime variable
+    #: (``OMP_NUM_THREADS``, ``R_HOME``, a service key) must name it here. Values are passed
+    #: through verbatim; only list what the package genuinely needs.
+    env_passthrough: list[str] = field(default_factory=list)
+    models: list[str] = field(default_factory=lambda: ["claude-opus-5"])
+    n_replicates: int = 3
+    max_concurrency: int = 4
+    #: Turn cap for benchmark agents only; draft/improve/ship/tasks are unbounded by default.
+    max_turns: int = 40
+    #: Budget cap (USD) for benchmark agents only; draft/improve/ship/tasks are unbounded by default.
+    max_usd: float = 3.0
+    draft_model: str = "claude-opus-5"
+    improve_model: str = "claude-opus-5"
+    tasks_model: str = "claude-opus-5"
+    ship_model: str = "claude-opus-5"
+
+    @property
+    def is_local(self) -> bool:
+        """Whether ``repo`` points at a local path rather than a remote URL."""
+        return not _looks_remote(self.repo)
+
+
+_REMOTE_PREFIXES = ("http://", "https://", "git@", "ssh://", "git://")
+
+_KNOWN = {
+    "repo",
+    "ref",
+    "extras",
+    "python",
+    "env_passthrough",
+    "models",
+    "n_replicates",
+    "max_concurrency",
+    "max_turns",
+    "max_usd",
+    "draft_model",
+    "improve_model",
+    "tasks_model",
+    "ship_model",
+    "skill_name",
+}
+
+
+def _looks_remote(repo: str) -> bool:
+    return repo.startswith(_REMOTE_PREFIXES)
+
+
+def derive_skill_name(repo: str) -> str:
+    """Derive a default skill name from a ``repo`` URL or local path.
+
+    Takes the last path component (``.../scanpy`` or ``git@…:owner/scanpy.git`` ->
+    ``scanpy``), drops a trailing ``.git``, and slugifies it to a lowercase, filesystem-safe
+    token. This is the fallback when ``config.yaml`` omits ``skill_name``, so the name is one
+    fewer field a user can get wrong.
+    """
+    stem = Path(repo.rstrip("/")).name.removesuffix(".git")
+    try:
+        return slugify(stem).lower()
+    except PathError as err:
+        raise ConfigError(f"cannot derive a skill name from repo {repo!r}; set 'skill_name' explicitly") from err
+
+
+def _require_str(raw: dict[str, Any], key: str) -> str:
+    value = raw[key]
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f"'{key}' must be a non-empty string, got {value!r}")
+    return value
+
+
+def _optional_str(raw: dict[str, Any], key: str, default: str) -> str:
+    if key not in raw:
+        return default
+    return _require_str(raw, key)
+
+
+def _positive_int(raw: dict[str, Any], key: str, default: int) -> int:
+    if key not in raw:
+        return default
+    value = raw[key]
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise ConfigError(f"'{key}' must be a positive integer, got {value!r}")
+    return value
+
+
+def _positive_float(raw: dict[str, Any], key: str, default: float) -> float:
+    if key not in raw:
+        return default
+    value = raw[key]
+    if isinstance(value, bool) or not isinstance(value, int | float) or value <= 0:
+        raise ConfigError(f"'{key}' must be a positive number, got {value!r}")
+    return float(value)
+
+
+def _str_list(raw: dict[str, Any], key: str, default: list[str]) -> list[str]:
+    if key not in raw:
+        return list(default)
+    value = raw[key]
+    if not isinstance(value, list) or not all(isinstance(v, str) and v.strip() for v in value):
+        raise ConfigError(f"'{key}' must be a list of non-empty strings, got {value!r}")
+    return list(value)
+
+
+def parse_config(raw: Any) -> Config:
+    """Validate an already-parsed ``config.yaml`` document.
+
+    Parameters
+    ----------
+    raw
+        The mapping loaded from YAML.
+
+    Returns
+    -------
+    The validated config.
+    """
+    if not isinstance(raw, dict):
+        raise ConfigError(f"config.yaml must be a mapping, got {type(raw).__name__}")
+    unknown = set(raw) - _KNOWN
+    if unknown:
+        raise ConfigError(f"unknown keys: {sorted(unknown)} (known keys: {sorted(_KNOWN)})")
+    if "repo" not in raw:
+        raise ConfigError("missing required key 'repo'")
+
+    repo = _require_str(raw, "repo")
+    skill_name = _require_str(raw, "skill_name") if "skill_name" in raw else derive_skill_name(repo)
+
+    models = _str_list(raw, "models", ["claude-opus-5"])
+    if not models:
+        raise ConfigError("'models' must list at least one model")
+    if len(set(models)) != len(models):
+        raise ConfigError(f"'models' contains duplicates: {models}")
+
+    default_model = models[0]
+    return Config(
+        repo=repo,
+        skill_name=skill_name,
+        ref=_optional_str(raw, "ref", "main"),
+        extras=_str_list(raw, "extras", []),
+        python=_optional_str(raw, "python", "3.12"),
+        env_passthrough=_str_list(raw, "env_passthrough", []),
+        models=models,
+        n_replicates=_positive_int(raw, "n_replicates", 3),
+        max_concurrency=_positive_int(raw, "max_concurrency", 4),
+        max_turns=_positive_int(raw, "max_turns", 40),
+        max_usd=_positive_float(raw, "max_usd", 3.0),
+        draft_model=_optional_str(raw, "draft_model", default_model),
+        improve_model=_optional_str(raw, "improve_model", default_model),
+        tasks_model=_optional_str(raw, "tasks_model", default_model),
+        ship_model=_optional_str(raw, "ship_model", default_model),
+    )
+
+
+def load_config(path: Path) -> Config:
+    """Load and validate ``config.yaml`` from disk.
+
+    A local ``repo`` path is resolved relative to the config file, so a config is
+    portable with the directory that contains it.
+    """
+    try:
+        text = path.read_text()
+    except OSError as err:
+        raise ConfigError(f"cannot read config file {path}: {err}") from err
+    try:
+        raw = yaml.safe_load(text)
+    except yaml.YAMLError as err:
+        raise ConfigError(f"{path} is not valid YAML: {err}") from err
+    try:
+        cfg = parse_config(raw)
+    except ConfigError as err:
+        raise ConfigError(f"{path}: {err}") from err
+    if cfg.is_local:
+        resolved = (path.parent / cfg.repo).expanduser()
+        if not resolved.exists():
+            raise ConfigError(f"{path}: repo {cfg.repo!r} is not a URL and does not exist as a local path ({resolved})")
+        cfg = replace(cfg, repo=str(resolved.resolve()))
+    return cfg

acumen/draft.py

@@ -0,0 +1,202 @@
+"""The drafting agent: write ``skills/v1/`` from the target package's source.
+
+Unlike a benchmark agent, the drafter reads the target's source — it is documenting
+the package, so it needs to see it. It is otherwise held to the same isolation: scrubbed
+env, throwaway config dir, no user settings or memories.
+
+The agent writes into a staging directory, not into ``skills/`` directly. Only a skill
+that loads and validates is promoted to a version, so a failed or half-finished draft
+never leaves a broken ``skills/vN/`` behind — versions are immutable, which means
+they must be right the moment they appear.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
+
+from acumen.config import Config
+from acumen.env import AuthMode, Target, build_agent_env
+from acumen.logs import LiveLog
+from acumen.procs import label_env, reap
+from acumen.prompts import draft_prompt
+from acumen.skills import (
+    SKILL_FILE,
+    Skill,
+    SkillError,
+    load_skill,
+    next_version,
+    skill_dir,
+    write_meta,
+)
+
+
+class DraftError(RuntimeError):
+    """Raised when a skill could not be drafted."""
+
+
+@dataclass(frozen=True)
+class DraftResult:
+    """A drafted skill version and what it cost to produce."""
+
+    skill: Skill
+    cost_usd: float
+    turns: int
+    #: Live log paths for this run, when a :class:`LiveLog` was attached.
+    log_jsonl: Path | None = None
+    log_html: Path | None = None
+
+
+def _validate_staged(staging: Path, skill_name: str) -> None:
+    """Fail loudly if the agent's output isn't a usable skill, before it becomes a version."""
+    if not (staging / SKILL_FILE).is_file():
+        raise DraftError(
+            f"the drafting agent did not write {SKILL_FILE} — nothing to promote. Inspect the run log or the prompt."
+        )
+    # load_skill enforces the frontmatter contract (name matches, description present).
+    try:
+        load_skill(staging.parent, staging.name, expect_name=skill_name)
+    except SkillError as err:
+        raise DraftError(f"the drafted skill is not valid: {err}") from err
+
+
+async def draft_skill(
+    *,
+    cfg: Config,
+    target: Target,
+    skills_root: Path,
+    auth_mode: AuthMode = "session",
+    model: str | None = None,
+    max_turns: int | None = None,
+    max_usd: float | None = None,
+    rationale: str = "initial draft",
+    feedback: str | None = None,
+    log: LiveLog | None = None,
+) -> DraftResult:
+    """Draft a new skill version from the target package's source.
+
+    Parameters
+    ----------
+    cfg
+        The pass config; supplies ``skill_name`` and ``draft_model``.
+    target
+        The prepared target, supplying the source checkout and interpreter.
+    skills_root
+        The ``skills/`` root. The new version is the next unused one.
+    auth_mode
+        Which credential the drafting agent authenticates with — ``"session"`` (the Claude
+        subscription) or ``"api"`` (see :func:`acumen.env.build_agent_env`).
+    model
+        Override for the drafting model; defaults to the config's.
+    max_turns, max_usd
+        Turn and budget caps for the drafting agent. **Unbounded by default** — the config's
+        ``max_turns``/``max_usd`` cap benchmark agents only; pass explicit caps to bound the
+        drafter.
+    rationale
+        Recorded in ``meta.json`` as why this version exists.
+    feedback
+        Optional maintainer guidance, injected into the draft prompt as a subordinated block
+        and recorded in ``meta.json`` as provenance.
+    log
+        A :class:`LiveLog` to stream the agent's messages to and render an HTML log from.
+
+    Returns
+    -------
+    The drafted skill, loaded and validated.
+    """
+    version = next_version(skills_root)
+    dest = skill_dir(skills_root, version)
+    if dest.exists():
+        raise DraftError(f"{dest} already exists — skill versions are immutable and never overwritten")
+
+    holder = Path(tempfile.mkdtemp(prefix="acumen-draft-"))
+    try:
+        # The staging dir is named for the version so load_skill can validate it in place.
+        work = holder / "work"
+        staging = work / version
+        home = holder / "home"
+        config_dir = home / ".claude"
+        for path in (staging, home, config_dir, home / "tmp"):
+            path.mkdir(parents=True, exist_ok=True)
+
+        # Marks the agent's processes so the teardown below can find what it leaves running.
+        env = label_env(
+            build_agent_env(
+                config_dir=config_dir,
+                home=home,
+                extra_path=[target.bin_dir],
+                auth_mode=auth_mode,
+                extra_allow=cfg.env_passthrough,
+            ),
+            holder,
+        )
+
+        prompt = draft_prompt(
+            package=target.pkg_name,
+            version=target.pkg_version,
+            src=target.src_dir,
+            python=target.python,
+            out=staging,
+            skill_name=cfg.skill_name,
+            feedback=feedback,
+        )
+        options = ClaudeAgentOptions(
+            cwd=str(work),
+            env=env,
+            model=model or cfg.draft_model,
+            # No default turn or budget cap: only bound the agent if the caller asked. The
+            # config's ``max_turns``/``max_usd`` cap benchmark agents only.
+            max_turns=max_turns,
+            max_budget_usd=max_usd,
+            # The drafter reads the target source; benchmark agents never do.
+            add_dirs=[str(target.src_dir)],
+            setting_sources=["project"],
+            permission_mode="bypassPermissions",
+            system_prompt={"type": "preset", "preset": "claude_code"},
+        )
+
+        result: ResultMessage | None = None
+        agent_error: Exception | None = None
+        try:
+            async for message in query(prompt=prompt, options=options):
+                if log is not None:
+                    log.append(message)
+                if isinstance(message, ResultMessage):
+                    result = message
+        except Exception as err:  # noqa: BLE001 - a failed draft is an error to report, re-raised below
+            agent_error = err
+        finally:
+            # Render the HTML log while the throwaway config dir still holds the native
+            # transcript — in a finally so an aborted run (the SDK raises on a cap breach,
+            # after yielding the result) is still inspectable.
+            if log is not None:
+                log.finalize(config_dir=config_dir, work_dir=work, result=result)
+
+        if agent_error is not None:
+            raise DraftError(f"the drafting agent failed: {type(agent_error).__name__}: {agent_error}") from agent_error
+        if result is None:
+            raise DraftError("the drafting agent produced no result message")
+        if result.is_error:
+            raise DraftError(f"the drafting agent errored: {result.subtype} {result.errors or ''}".strip())
+
+        _validate_staged(staging, cfg.skill_name)
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(staging, dest)
+        write_meta(dest, parent=None, rationale=rationale, feedback=feedback)
+        skill = load_skill(skills_root, version, expect_name=cfg.skill_name)
+        return DraftResult(
+            skill=skill,
+            cost_usd=result.total_cost_usd or 0.0,
+            turns=result.num_turns,
+            log_jsonl=log.jsonl_path if log is not None else None,
+            log_html=log.html_path if log is not None and log.html_rendered else None,
+        )
+    finally:
+        # Kill anything the agent left running before removing the directory it runs in.
+        reap(holder)
+        shutil.rmtree(holder, ignore_errors=True)