substrate-setup 0.1.0__py3-none-any.whl

substrate_setup/agents/hermes.py

@@ -0,0 +1,259 @@
+"""Hermes Agent (NousResearch/hermes-agent) integration.
+
+Config:
+  ~/.hermes/config.yaml   — providers + model defaults
+  ~/.hermes/.env          — secrets (SUBSTRATE_API_KEY)
+
+Schema verified against upstream docs during plan-writing.
+"""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+from substrate_setup.agents.base import (
+    Agent,
+    AgentResult,
+    ConfigureContext,
+    ResultStatus,
+)
+from substrate_setup.backup import backup_once
+from substrate_setup.markers import MARKER_KEY, MARKER_VALUE, is_substrate_managed
+
+PROVIDER_NAME = "substrate"
+ENV_VAR = "SUBSTRATE_API_KEY"
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".hermes"
+
+
+def _config_yaml() -> Path:
+    return _config_dir() / "config.yaml"
+
+
+def _env_file() -> Path:
+    return _config_dir() / ".env"
+
+
+def _yaml() -> YAML:
+    y = YAML()
+    y.preserve_quotes = True
+    y.indent(mapping=2, sequence=4, offset=2)
+    return y
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    result: dict[str, Any] = _yaml().load(text) or {}
+    return result
+
+
+def _dump_yaml(path: Path, data: dict[str, Any]) -> None:
+    buf = io.StringIO()
+    _yaml().dump(data, buf)
+    path.write_text(buf.getvalue(), encoding="utf-8")
+
+
+def _build_substrate_provider(ctx: ConfigureContext) -> dict[str, Any]:
+    models = {
+        entry.id: {"context_length": 200000}
+        for entry in ctx.catalog
+    }
+    return {
+        "name": PROVIDER_NAME,
+        "base_url": ctx.base_url,
+        "key_env": ENV_VAR,
+        "api_mode": "chat_completions",
+        "models": models,
+        MARKER_KEY: MARKER_VALUE,
+    }
+
+
+def _merge_provider_models(
+    existing: dict[str, Any],
+    fresh: dict[str, Any],
+    *,
+    additive_only: bool,
+) -> dict[str, Any]:
+    """Merge the substrate provider entry, respecting additive-only on fallback."""
+    if additive_only:
+        merged_models = {**existing.get("models", {}), **fresh["models"]}
+        return {**fresh, "models": merged_models}
+    return fresh
+
+
+def _read_env_lines(path: Path) -> list[str]:
+    if not path.exists():
+        return []
+    return path.read_text(encoding="utf-8").splitlines()
+
+
+def _write_env_lines(path: Path, lines: list[str]) -> None:
+    path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+class HermesAgent(Agent):
+    name = "hermes"
+    pretty_name = "Hermes"
+
+    def detect(self) -> Path | None:
+        cfg = _config_yaml()
+        return cfg if cfg.exists() else None
+
+    def configure(self, ctx: ConfigureContext) -> AgentResult:
+        _config_dir().mkdir(parents=True, exist_ok=True)
+        backups: list[Path] = []
+        notes: list[str] = []
+
+        # ── config.yaml ──────────────────────────────────────────────
+        cfg_path = _config_yaml()
+        if cfg_path.exists():
+            backup = backup_once(cfg_path)
+            if backup is not None:
+                backups.append(backup)
+
+        payload = _load_yaml(cfg_path)
+        providers: list[dict[str, Any]] = payload.get("custom_providers") or []
+        new_provider = _build_substrate_provider(ctx)
+
+        existing_substrate = next(
+            (p for p in providers if p.get("name") == PROVIDER_NAME), None
+        )
+        if existing_substrate is not None:
+            merged = _merge_provider_models(
+                existing_substrate, new_provider, additive_only=(ctx.catalog_source == "fallback")
+            )
+            providers = [
+                merged if p.get("name") == PROVIDER_NAME else p for p in providers
+            ]
+        else:
+            providers.append(new_provider)
+
+        payload["custom_providers"] = providers
+
+        if not ctx.dry_run:
+            _dump_yaml(cfg_path, payload)
+
+        # ── .env ─────────────────────────────────────────────────────
+        env_path = _env_file()
+        lines = _read_env_lines(env_path)
+        existing_value = None
+        for line in lines:
+            if line.startswith(f"{ENV_VAR}="):
+                existing_value = line.split("=", 1)[1]
+                break
+
+        should_write_env = False
+        new_lines = list(lines)
+        if existing_value is None:
+            new_lines.append(f"{ENV_VAR}={ctx.api_key}")
+            should_write_env = True
+        elif existing_value.startswith("sk-substrate-"):
+            if existing_value != ctx.api_key:
+                new_lines = [
+                    f"{ENV_VAR}={ctx.api_key}" if line.startswith(f"{ENV_VAR}=") else line
+                    for line in lines
+                ]
+                should_write_env = True
+        else:
+            notes.append(
+                f"Hermes already has {ENV_VAR} set to a non-Substrate-shaped value; "
+                "please update manually."
+            )
+
+        if should_write_env:
+            if env_path.exists():
+                env_backup = backup_once(env_path)
+                if env_backup is not None:
+                    backups.append(env_backup)
+            if not ctx.dry_run:
+                _write_env_lines(env_path, new_lines)
+
+        msg = f"{len(ctx.catalog)} models written to ~/.hermes/config.yaml"
+        if notes:
+            msg += "\n" + "\n".join(notes)
+        return AgentResult(ResultStatus.SUCCESS, msg, tuple(backups))
+
+    def verify(self, ctx: ConfigureContext) -> AgentResult:
+        cfg_path = _config_yaml()
+        if not cfg_path.exists():
+            return AgentResult(
+                ResultStatus.ERROR, "Hermes config.yaml does not exist"
+            )
+        payload = _load_yaml(cfg_path)
+        providers = payload.get("custom_providers") or []
+        substrate = next(
+            (p for p in providers if p.get("name") == PROVIDER_NAME), None
+        )
+        if substrate is None:
+            return AgentResult(
+                ResultStatus.ERROR, "No substrate provider entry found"
+            )
+        if not is_substrate_managed(substrate):
+            return AgentResult(
+                ResultStatus.ERROR,
+                "Substrate provider entry exists but is not managed by "
+                "substrate-setup (run configure to re-take ownership)",
+            )
+        catalog_ids = {e.id for e in ctx.catalog}
+        config_ids = set(substrate.get("models", {}).keys())
+        missing = catalog_ids - config_ids
+        stale = config_ids - catalog_ids
+        if missing or stale:
+            parts = []
+            if missing:
+                parts.append(f"missing: {sorted(missing)}")
+            if stale:
+                parts.append(f"stale: {sorted(stale)}")
+            return AgentResult(ResultStatus.ERROR, "; ".join(parts))
+        return AgentResult(ResultStatus.SUCCESS, "in sync")
+
+    def remove(self, ctx: ConfigureContext) -> AgentResult:
+        cfg_path = _config_yaml()
+        if not cfg_path.exists():
+            return AgentResult(ResultStatus.SKIPPED, "Hermes not configured")
+        backups: list[Path] = []
+        cfg_backup = backup_once(cfg_path)
+        if cfg_backup is not None:
+            backups.append(cfg_backup)
+        payload = _load_yaml(cfg_path)
+        providers = payload.get("custom_providers") or []
+        kept = [
+            p for p in providers
+            if not (p.get("name") == PROVIDER_NAME and is_substrate_managed(p))
+        ]
+        payload["custom_providers"] = kept
+        if not ctx.dry_run:
+            _dump_yaml(cfg_path, payload)
+
+        # Strip SUBSTRATE_API_KEY from .env only if it's currently a Substrate-shaped value.
+        env_path = _env_file()
+        if env_path.exists():
+            lines = _read_env_lines(env_path)
+            new_lines = []
+            stripped = False
+            for line in lines:
+                if line.startswith(f"{ENV_VAR}="):
+                    value = line.split("=", 1)[1]
+                    if value.startswith("sk-substrate-"):
+                        stripped = True
+                        continue
+                new_lines.append(line)
+            if stripped:
+                env_backup = backup_once(env_path)
+                if env_backup is not None:
+                    backups.append(env_backup)
+                if not ctx.dry_run:
+                    _write_env_lines(env_path, new_lines)
+
+        return AgentResult(
+            ResultStatus.SUCCESS,
+            "Removed substrate provider entry from Hermes",
+            tuple(backups),
+        )

substrate_setup/backup.py

@@ -0,0 +1,32 @@
+"""Backup-on-write helper.
+
+One backup per (file, run). The first call backs up; subsequent calls
+for the same path in the same Python process are no-ops returning the
+first backup's path.
+"""
+from __future__ import annotations
+
+import shutil
+import time
+from pathlib import Path
+
+_backups_this_run: dict[Path, Path] = {}
+
+
+def backup_once(target: Path) -> Path | None:
+    """Backup ``target`` to ``<target>.substrate-bak-<unix-ts>``.
+
+    Returns the backup path. If the target doesn't exist, returns None.
+    Within a single process, repeated calls for the same target return
+    the first backup's path without touching anything.
+    """
+    target = target.resolve()
+    if target in _backups_this_run:
+        return _backups_this_run[target]
+    if not target.exists():
+        return None
+    ts = int(time.time())
+    backup_path = target.parent / f"{target.name}.substrate-bak-{ts}"
+    shutil.copy2(target, backup_path)
+    _backups_this_run[target] = backup_path
+    return backup_path

substrate_setup/catalog.py

@@ -0,0 +1,109 @@
+"""Catalog fetch — live /v1/models with bundled-snapshot fallback."""
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+import httpx
+
+CONNECT_TIMEOUT_SEC = 5.0
+READ_TIMEOUT_SEC = 10.0
+
+_FALLBACK_PATH = Path(__file__).parent / "data" / "fallback_catalog.json"
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    id: str
+    provider: str
+    display_name: str
+    description: str
+
+
+class AuthError(Exception):
+    """The gateway rejected the API key (HTTP 401)."""
+
+
+class CatalogUnavailableError(Exception):
+    """Live fetch failed AND the bundled snapshot is missing/corrupt."""
+
+
+def _parse_payload(payload: dict[str, Any]) -> list[CatalogEntry]:
+    return [
+        CatalogEntry(
+            id=item["id"],
+            provider=item.get("owned_by", "unknown"),
+            display_name=item.get("display_name", item["id"]),
+            description=item.get("description", ""),
+        )
+        for item in payload.get("data", [])
+    ]
+
+
+def _load_fallback() -> list[CatalogEntry]:
+    if not _FALLBACK_PATH.exists():
+        raise CatalogUnavailableError(
+            f"Bundled fallback catalog missing at {_FALLBACK_PATH}. "
+            "Reinstall substrate-setup."
+        )
+    try:
+        payload = json.loads(_FALLBACK_PATH.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise CatalogUnavailableError(
+            f"Bundled fallback catalog at {_FALLBACK_PATH} is corrupt: {exc}"
+        ) from exc
+    return _parse_payload(payload)
+
+
+def fetch_catalog(
+    *,
+    base_url: str,
+    api_key: str,
+) -> tuple[list[CatalogEntry], Literal["live", "fallback"]]:
+    """Fetch the model catalog. Returns (entries, source-tag).
+
+    Resolution order:
+      1. live GET <base_url>/v1/models with Bearer <api_key>
+      2. bundled fallback snapshot (with warning printed to stderr)
+
+    Raises:
+      AuthError: live fetch returned 401. Caller should exit 1.
+      CatalogUnavailableError: live fetch failed AND fallback is missing/corrupt.
+        Caller should exit 2.
+    """
+    # Tolerate users passing base URLs with or without a trailing /v1
+    normalized = base_url.rstrip("/")
+    if normalized.endswith("/v1"):
+        normalized = normalized[:-3]
+    url = f"{normalized}/v1/models"
+    timeout = httpx.Timeout(READ_TIMEOUT_SEC, connect=CONNECT_TIMEOUT_SEC)
+    try:
+        resp = httpx.get(
+            url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+    except httpx.TransportError as exc:
+        print(
+            f"WARNING: could not reach {url} ({type(exc).__name__}); "
+            "using bundled catalog snapshot. Models may be out of date.",
+            file=sys.stderr,
+        )
+        return _load_fallback(), "fallback"
+
+    if resp.status_code == 401:
+        raise AuthError(
+            f"That key was rejected by {base_url}. Did you copy the full string?"
+        )
+    if resp.status_code >= 500:
+        print(
+            f"WARNING: gateway at {url} returned HTTP {resp.status_code}; "
+            "using bundled catalog snapshot. Models may be out of date.",
+            file=sys.stderr,
+        )
+        return _load_fallback(), "fallback"
+    resp.raise_for_status()
+    return _parse_payload(resp.json()), "live"

substrate_setup/cli.py

@@ -0,0 +1,211 @@
+"""CLI orchestration for substrate-setup.
+
+Subcommands:
+  configure   (default) detect agents and write Substrate config
+  verify      report whether each detected agent is in sync with the catalog
+  remove      strip substrate-managed entries from each detected agent
+  version     print version
+
+Common flags: --base-url, --agents-only, --dry-run, --quiet.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+
+from substrate_setup import __version__
+from substrate_setup.agents import AGENT_NAMES, ALL_AGENTS
+from substrate_setup.agents.base import Agent, AgentResult, ConfigureContext, ResultStatus
+from substrate_setup.catalog import (
+    AuthError,
+    CatalogEntry,
+    CatalogUnavailableError,
+    fetch_catalog,
+)
+from substrate_setup.credentials import (
+    CredentialResolutionError,
+    InvalidKeyFormatError,
+    resolve_api_key,
+)
+
+EXIT_OK = 0
+EXIT_AUTH = 1
+EXIT_CATALOG = 2
+EXIT_PARTIAL = 3
+EXIT_BAD_FLAGS = 4
+
+DEFAULT_BASE_URL = "https://substrate-solutions-api.fly.dev/v1"
+
+
+def _common_flags_parser() -> argparse.ArgumentParser:
+    """Return a parser holding the flags shared by configure/verify/remove."""
+    p = argparse.ArgumentParser(add_help=False)
+    p.add_argument("--base-url", default=None, help="Override gateway base URL")
+    p.add_argument(
+        "--agents-only",
+        default=None,
+        help=f"Comma-separated subset of: {','.join(AGENT_NAMES)}",
+    )
+    p.add_argument("--dry-run", action="store_true", help="Mutate nothing")
+    p.add_argument("--quiet", action="store_true", help="Summary only")
+    return p
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = _common_flags_parser()
+    parser = argparse.ArgumentParser(
+        prog="substrate-setup",
+        description="Configure local coding agents against a Substrate gateway.",
+        parents=[common],
+    )
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("configure", parents=[common],
+                   help="Default: detect agents and configure")
+    sub.add_parser("verify", parents=[common],
+                   help="Read-only: check whether each agent is in sync")
+    sub.add_parser("remove", parents=[common],
+                   help="Strip substrate-managed entries")
+    sub.add_parser("version", help="Print version and exit")
+    return parser
+
+
+def _select_agents(filter_str: str | None) -> list[Agent]:
+    if filter_str is None:
+        return list(ALL_AGENTS)
+    wanted = {name.strip() for name in filter_str.split(",") if name.strip()}
+    unknown = wanted - set(AGENT_NAMES)
+    if unknown:
+        print(
+            f"Unknown agent(s) in --agents-only: {sorted(unknown)}. "
+            f"Valid: {AGENT_NAMES}",
+            file=sys.stderr,
+        )
+        sys.exit(EXIT_BAD_FLAGS)
+    return [a for a in ALL_AGENTS if a.name in wanted]
+
+
+def _resolve_base_url(arg: str | None) -> str:
+    import os
+
+    if arg is not None:
+        return arg
+    return os.environ.get("SUBSTRATE_BASE_URL") or DEFAULT_BASE_URL
+
+
+def _run_per_agent(
+    agents: list[Agent],
+    ctx: ConfigureContext,
+    method: Callable[[Agent], AgentResult],
+    *,
+    label: str,
+    quiet: bool,
+) -> int:
+    """Execute ``method`` on each detected agent. Print results. Return exit code."""
+    if not quiet:
+        print(f"{label} agents …")
+        print("Detected agents:")
+        for a in agents:
+            detected = a.detect()
+            tag = "[print-only handler]" if a.name == "cursor" else ""
+            mark = "✓" if detected else "·"
+            note = f"({detected})" if detected else "not installed"
+            print(f"  {mark} {a.pretty_name:<12} {note} {tag}")
+        print()
+
+    error_count = 0
+    handled = 0
+    for a in agents:
+        detected = a.detect()
+        if not detected:
+            continue
+        handled += 1
+        try:
+            result = method(a)
+        except Exception as exc:  # noqa: BLE001
+            result = AgentResult(ResultStatus.ERROR, f"unhandled error: {exc}")
+        if not quiet:
+            prefix = f"{label} {a.pretty_name:<10}"
+            if result.status == ResultStatus.ERROR:
+                print(f"{prefix} … ERROR: {result.message}")
+            elif result.status == ResultStatus.PRINT_ONLY:
+                print(f"{prefix} … printed walkthrough above.")
+            else:
+                print(f"{prefix} … {result.message}")
+            for backup in result.backup_paths:
+                print(f"             Backup: {backup}")
+        if result.status == ResultStatus.ERROR:
+            error_count += 1
+
+    if not quiet:
+        total = sum(1 for a in agents if a.detect())
+        print()
+        print(
+            f"Done. {handled} of {total} detected agents handled. "
+            f"{error_count} error{'s' if error_count != 1 else ''}."
+        )
+    return EXIT_PARTIAL if error_count > 0 else EXIT_OK
+
+
+def _build_ctx(
+    args: argparse.Namespace,
+    base_url: str,
+    api_key: str,
+    catalog: list[CatalogEntry],
+    source: str,
+) -> ConfigureContext:
+    return ConfigureContext(
+        base_url=base_url,
+        api_key=api_key,
+        catalog=catalog,
+        catalog_source=source,
+        dry_run=args.dry_run,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        print(f"substrate-setup {__version__}")
+        return EXIT_OK
+
+    command = args.command or "configure"
+    base_url = _resolve_base_url(args.base_url)
+
+    try:
+        api_key = resolve_api_key()
+    except (CredentialResolutionError, InvalidKeyFormatError) as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_AUTH
+
+    try:
+        catalog, source = fetch_catalog(base_url=base_url, api_key=api_key)
+    except AuthError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_AUTH
+    except CatalogUnavailableError as exc:
+        print(str(exc), file=sys.stderr)
+        return EXIT_CATALOG
+
+    if not args.quiet:
+        print(f"substrate-setup {__version__}")
+        print(f"Fetched catalog ({source}): {len(catalog)} models.")
+        print(f"API key resolved (length {len(api_key)} chars).")
+        print()
+
+    agents = _select_agents(args.agents_only)
+    ctx = _build_ctx(args, base_url, api_key, catalog, source)
+
+    if command == "configure":
+        return _run_per_agent(agents, ctx, lambda a: a.configure(ctx),
+                              label="Configuring", quiet=args.quiet)
+    if command == "verify":
+        return _run_per_agent(agents, ctx, lambda a: a.verify(ctx),
+                              label="Verifying", quiet=args.quiet)
+    if command == "remove":
+        return _run_per_agent(agents, ctx, lambda a: a.remove(ctx),
+                              label="Removing", quiet=args.quiet)
+    parser.print_help()
+    return EXIT_BAD_FLAGS

substrate_setup/credentials.py

@@ -0,0 +1,82 @@
+"""Credential resolution: env > config file > interactive prompt."""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections.abc import Callable
+from getpass import getpass
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover - Python <3.11 fallback
+    import tomli as tomllib  # type: ignore[no-redef]
+
+KEY_REGEX = re.compile(r"^sk-substrate-[A-Za-z0-9_-]{20,}$")
+ENV_VAR = "SUBSTRATE_API_KEY"
+
+
+def _default_config_path() -> Path:
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA") or None
+        base = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
+        return base / "substrate-setup" / "credentials.toml"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else Path.home() / ".config"
+    return base / "substrate-setup" / "credentials.toml"
+
+
+class CredentialResolutionError(Exception):
+    """No API key found in env, config file, or prompt."""
+
+
+class InvalidKeyFormatError(Exception):
+    """The resolved value is not the shape of a Substrate API key."""
+
+
+def _prompt(question: str) -> str:
+    return getpass(question)
+
+
+def resolve_api_key(
+    *,
+    config_path: Path | None = None,
+    prompt_fn: Callable[[str], str] = _prompt,
+) -> str:
+    """Resolve a Substrate API key. Validate format. Return it.
+
+    Resolution order: env var → config file → interactive prompt.
+    Raises:
+      InvalidKeyFormatError: a candidate was found but its shape is wrong.
+      CredentialResolutionError: no candidate found at any layer.
+    """
+    config_path = config_path if config_path is not None else _default_config_path()
+
+    candidate: str | None = os.environ.get(ENV_VAR)
+    if not candidate and config_path.exists():
+        try:
+            payload = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        except tomllib.TOMLDecodeError as exc:
+            raise CredentialResolutionError(
+                f"{config_path} is not valid TOML: {exc}"
+            ) from exc
+        candidate = payload.get("api_key")
+        if candidate is not None and not isinstance(candidate, str):
+            raise CredentialResolutionError(
+                f"{config_path}: 'api_key' must be a string, "
+                f"got {type(candidate).__name__}."
+            )
+    if not candidate:
+        candidate = prompt_fn("Substrate API key (sk-substrate-...): ").strip()
+    if not candidate:
+        raise CredentialResolutionError(
+            "No API key found. Set SUBSTRATE_API_KEY, write "
+            f"{config_path}, or paste when prompted."
+        )
+    if not KEY_REGEX.match(candidate):
+        raise InvalidKeyFormatError(
+            "That doesn't look like a Substrate API key — expected "
+            "sk-substrate-... followed by at least 20 characters."
+        )
+    return candidate