agentforge-py 0.2.1__py3-none-any.whl

agentforge/cli/module_cmd.py

@@ -0,0 +1,247 @@
+"""`agentforge add/remove/swap module` commands (feat-010b).
+
+These are the destructive CLI commands deferred from feat-010
+PR #16. They edit `agentforge.yaml`, apply per-module manifest
+files, and shell out to `pip install` / `pip uninstall`.
+
+The pip subprocess is injected via the `pip_run` callable so tests
+can mock it without actually installing packages. Production uses
+`python -m pip` in the active venv.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess  # nosec B404
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+import yaml
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.values.manifest import Manifest
+
+from agentforge.cli.manifest_apply import (
+    apply_manifest,
+    read_applied,
+    reverse_manifest,
+)
+
+PipRunner = Callable[[Sequence[str]], int]
+"""Signature: `runner(["install", "agentforge-X"]) -> exit_code`."""
+
+
+def register_module_cmd(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    """Attach `agentforge add/remove/swap module` to the parent
+    subparser action."""
+    # `agentforge add module X` — slot into a nested `add` subparser
+    # so we have room for `agentforge add tool`, etc. later.
+    add = sub.add_parser("add", help="Install + wire a module into this agent.")
+    add_sub = add.add_subparsers(dest="add_target", required=True)
+    add_mod = add_sub.add_parser("module", help="Install + apply a module manifest.")
+    add_mod.add_argument(
+        "distribution", help="Module distribution (e.g. agentforge-memory-postgres)."
+    )
+    add_mod.set_defaults(_handler=_run_add_module)
+
+    remove = sub.add_parser("remove", help="Remove a module from this agent.")
+    remove_sub = remove.add_subparsers(dest="remove_target", required=True)
+    rm_mod = remove_sub.add_parser("module", help="Reverse + uninstall a module.")
+    rm_mod.add_argument("distribution", help="Module distribution to remove.")
+    rm_mod.set_defaults(_handler=_run_remove_module)
+
+    swap = sub.add_parser(
+        "swap",
+        help="Replace one module with another in the same category.",
+    )
+    swap.add_argument("category", help="Module category (memory, providers, etc.).")
+    swap.add_argument("from_dist", metavar="FROM", help="Distribution to remove.")
+    swap.add_argument("to_dist", metavar="TO", help="Distribution to install + apply.")
+    swap.set_defaults(_handler=_run_swap)
+
+
+# ----------------------------------------------------------------------
+# add module
+# ----------------------------------------------------------------------
+
+
+def _run_add_module(
+    args: argparse.Namespace,
+    *,
+    pip_run: PipRunner | None = None,
+    cwd: Path | None = None,
+    package_root: Path | None = None,
+) -> int:
+    """Install a module via pip + apply its manifest.
+
+    Args:
+        pip_run: Injected pip runner; defaults to `python -m pip`.
+        cwd: Working directory; defaults to `Path.cwd()`.
+        package_root: For tests — skip the importlib.resources lookup
+            and read manifest + templates from this directory.
+    """
+    runner = pip_run if pip_run is not None else _default_pip_runner
+    work_dir = cwd if cwd is not None else Path.cwd()
+    distribution = args.distribution
+
+    sys.stdout.write(f"  → installing {distribution}\n")
+    code = runner(["install", distribution])
+    if code != 0:
+        sys.stderr.write(f"pip install {distribution} failed (exit {code})\n")
+        return code
+
+    try:
+        manifest = _load_manifest(distribution, package_root=package_root)
+    except ModuleError as exc:
+        sys.stderr.write(f"manifest load failed: {exc}\n")
+        return 1
+
+    if read_applied(work_dir, distribution) is not None:
+        sys.stdout.write("  → already applied (state file present); skipping\n")
+        _print_next_steps(manifest)
+        return 0
+
+    try:
+        apply_manifest(
+            manifest,
+            distribution=distribution,
+            cwd=work_dir,
+            package_root=package_root,
+        )
+    except ModuleError as exc:
+        sys.stderr.write(f"manifest apply failed: {exc}\n")
+        return 1
+
+    sys.stdout.write(f"  → applied manifest for {distribution}\n")
+    _print_next_steps(manifest)
+    return 0
+
+
+# ----------------------------------------------------------------------
+# remove module
+# ----------------------------------------------------------------------
+
+
+def _run_remove_module(
+    args: argparse.Namespace,
+    *,
+    pip_run: PipRunner | None = None,
+    cwd: Path | None = None,
+    package_root: Path | None = None,
+) -> int:
+    runner = pip_run if pip_run is not None else _default_pip_runner
+    work_dir = cwd if cwd is not None else Path.cwd()
+    distribution = args.distribution
+
+    applied = read_applied(work_dir, distribution)
+    if applied is None:
+        state_dir = work_dir / ".agentforge-state"
+        sys.stderr.write(
+            f"No applied state for {distribution} in {state_dir}; nothing to remove.\n"
+        )
+        return 1
+
+    # The reverse needs the manifest's config_block (state stores only
+    # what landed, not the original block). Try to read the manifest
+    # from the still-installed package; fall back to "skip config-block
+    # reverse" if the package is already gone.
+    config_block: dict[str, Any] = {}
+    try:
+        manifest = _load_manifest(distribution, package_root=package_root)
+        config_block = manifest.config_block
+    except ModuleError:
+        # Module already uninstalled / manifest gone. Reverse what we can.
+        config_block = {}
+
+    reverse_manifest(applied, cwd=work_dir, config_block=config_block)
+    sys.stdout.write(f"  → reversed manifest for {distribution}\n")
+
+    sys.stdout.write(f"  → uninstalling {distribution}\n")
+    code = runner(["uninstall", "-y", distribution])
+    if code != 0:
+        sys.stderr.write(f"pip uninstall {distribution} failed (exit {code})\n")
+        return code
+    sys.stdout.write("  → done.\n")
+    return 0
+
+
+# ----------------------------------------------------------------------
+# swap
+# ----------------------------------------------------------------------
+
+
+def _run_swap(
+    args: argparse.Namespace,
+    *,
+    pip_run: PipRunner | None = None,
+    cwd: Path | None = None,
+    package_root: Path | None = None,
+) -> int:
+    """`agentforge swap <category> <from> <to>` — remove + add atomic-ish.
+
+    Not transactional: if `add` fails after `remove` succeeded, the
+    agent is left without either module. Documented in the runbook.
+    """
+    # Build a fake namespace for the underlying remove + add calls.
+    remove_ns = argparse.Namespace(distribution=args.from_dist)
+    add_ns = argparse.Namespace(distribution=args.to_dist)
+    sys.stdout.write(f"  → swap: removing {args.from_dist}, installing {args.to_dist}\n")
+    code = _run_remove_module(remove_ns, pip_run=pip_run, cwd=cwd, package_root=package_root)
+    if code != 0:
+        return code
+    return _run_add_module(add_ns, pip_run=pip_run, cwd=cwd, package_root=package_root)
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+
+def _load_manifest(distribution: str, *, package_root: Path | None) -> Manifest:
+    """Load `<package>/manifest.yaml` for `distribution`.
+
+    Args:
+        package_root: When set, read `manifest.yaml` from this directory
+            (test injection). Otherwise read via `importlib.resources`.
+    """
+    if package_root is not None:
+        path = package_root / "manifest.yaml"
+        if not path.exists():
+            raise ModuleError(f"manifest.yaml not found in package_root {package_root}.")
+        with path.open() as fh:
+            raw = yaml.safe_load(fh) or {}
+        return Manifest.model_validate(raw)
+
+    from importlib import resources  # noqa: PLC0415 — lazy import
+
+    package_name = distribution.replace("-", "_")
+    try:
+        package_files = resources.files(package_name)
+    except (ModuleNotFoundError, TypeError) as exc:
+        raise ModuleError(f"Cannot locate package files for {package_name!r}: {exc}.") from exc
+    manifest_resource = package_files.joinpath("manifest.yaml")
+    try:
+        text = manifest_resource.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise ModuleError(
+            f"{package_name} does not ship a manifest.yaml — cannot `add` it."
+        ) from exc
+    raw = yaml.safe_load(text) or {}
+    return Manifest.model_validate(raw)
+
+
+def _print_next_steps(manifest: Manifest) -> None:
+    if not manifest.next_steps:
+        return
+    sys.stdout.write("  Next:\n")
+    for step in manifest.next_steps:
+        sys.stdout.write(f"    - {step}\n")
+
+
+def _default_pip_runner(args: Sequence[str]) -> int:
+    """Run `python -m pip <args>` in the active venv."""
+    cmd = [sys.executable, "-m", "pip", *args]
+    # No untrusted input — args is built from CLI arg `distribution`
+    # which is just a distribution name string. shell=False (default).
+    return subprocess.run(cmd, check=False).returncode  # noqa: S603  # nosec B603

agentforge/cli/new_cmd.py

@@ -0,0 +1,171 @@
+"""`agentforge new <name>` — scaffold a new agent from a template.
+
+feat-011 ships six templates inside `agentforge/templates/<name>/`
+(see Implementation status §4.4 — local templates instead of the
+spec's separate-repo design; migration to `agentforge-templates`
+is a 0.4+ follow-up).
+
+Copier handles the render; this module is the CLI wrapper +
+template resolution. The lock file + marker headers are written
+post-render in chunk 3.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from agentforge_core.production.exceptions import ModuleError
+
+from agentforge.cli._scaffold_state import (
+    prepend_markers,
+    write_managed_files_lock,
+)
+from agentforge.cli._shared_scaffold import inject_shared_scaffold
+
+_TEMPLATES = ("minimal", "code-reviewer", "patch-bot", "docs-qa", "triage", "research")
+"""Templates shipped with the framework — discoverable via
+`agentforge new --help`. Each lives at
+`agentforge/templates/<name>/`."""
+
+
+def register_new_cmd(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    """Attach `agentforge new` to the parent subparser action."""
+    new = sub.add_parser(
+        "new",
+        help="Scaffold a new AgentForge project from a template.",
+    )
+    new.add_argument(
+        "project_slug",
+        help="Project name / directory (kebab-case, e.g. 'my-pr-reviewer').",
+    )
+    new.add_argument(
+        "--template",
+        choices=_TEMPLATES,
+        default="minimal",
+        help="Template to scaffold from (default: minimal).",
+    )
+    new.add_argument(
+        "--provider",
+        choices=("bedrock", "anthropic", "openai"),
+        default=None,
+        help="LLM provider (bedrock, anthropic, openai). Prompted when --no-prompts is not set.",
+    )
+    new.add_argument(
+        "--no-prompts",
+        action="store_true",
+        help="Batch mode — use defaults for every Copier question.",
+    )
+    new.add_argument(
+        "--dst",
+        type=Path,
+        default=None,
+        help="Destination directory (default: ./<project_slug>).",
+    )
+    new.set_defaults(_handler=_run_new)
+
+
+def _run_new(args: argparse.Namespace) -> int:
+    """Render the chosen template into `args.dst` (or `./<slug>`)."""
+    template_root = _template_root(args.template)
+    if template_root is None:
+        sys.stderr.write(
+            f"Template {args.template!r} not shipped with this install. "
+            f"Known: {', '.join(_TEMPLATES)}.\n"
+        )
+        return 1
+
+    dst = args.dst if args.dst is not None else Path.cwd() / args.project_slug
+    answers: dict[str, object] = {"project_slug": args.project_slug}
+    if args.provider is not None:
+        answers["llm_provider"] = args.provider
+
+    try:
+        _run_copier(str(template_root), str(dst), answers, defaults=args.no_prompts)
+    except ModuleError as exc:
+        sys.stderr.write(f"scaffolding failed: {exc}\n")
+        return 1
+
+    # feat-011 chunk 3: write the lock + prepend marker headers. Done
+    # post-render so the lock reflects exactly what landed on disk.
+    template_version = _template_version()
+    write_managed_files_lock(
+        dst,
+        template_name=args.template,
+        template_version=template_version,
+    )
+    prepend_markers(dst, template_name=args.template, template_version=template_version)
+
+    # feat-019: inject shared runbooks + AGENTS.md / CLAUDE.md /
+    # .cursorrules / .github/copilot-instructions.md into every
+    # scaffolded agent.
+    shared_count = inject_shared_scaffold(
+        dst,
+        template_name=args.template,
+        template_version=template_version,
+    )
+    if shared_count:
+        sys.stdout.write(f"  → wrote {shared_count} shared scaffold files (runbooks + AI rules)\n")
+
+    sys.stdout.write(f"  → done. Next: cd {args.project_slug} && uv sync\n")
+    return 0
+
+
+def _template_version() -> str:
+    """Resolve the installed `agentforge` version — used as the
+    template's `source_version` in the lock file."""
+    from importlib.metadata import PackageNotFoundError, version  # noqa: PLC0415
+
+    try:
+        return version("agentforge")
+    except PackageNotFoundError:  # pragma: no cover
+        return "0.0.0+unknown"
+
+
+def _template_root(name: str) -> Path | None:
+    """Resolve the template directory under `agentforge/templates/`.
+
+    Uses `importlib.resources` so it works from the installed wheel.
+    """
+    from importlib import resources  # noqa: PLC0415
+
+    try:
+        root_traversable = resources.files("agentforge.templates").joinpath(name)
+    except ModuleNotFoundError:
+        return None
+    # Materialise to a Path — Copier needs a filesystem path, not a
+    # MultiplexedPath. `as_file` returns a context-managed temporary
+    # path for zipped distributions; for editable installs (the
+    # common case) the underlying path is real.
+    with resources.as_file(root_traversable) as path:
+        if not path.exists() or not (path / "copier.yml").exists():
+            return None
+        return Path(path)
+
+
+def _run_copier(
+    src: str,
+    dst: str,
+    data: dict[str, object],
+    *,
+    defaults: bool,
+) -> None:
+    """Run Copier's render. Wrapped so tests can mock the call."""
+    from copier import run_copy  # noqa: PLC0415 — lazy to keep import cost off other CLI paths
+
+    try:
+        run_copy(
+            src_path=src,
+            dst_path=dst,
+            data=data,
+            defaults=defaults,
+            unsafe=False,
+            quiet=False,
+        )
+    except Exception as exc:
+        raise ModuleError(f"copier render failed: {exc}") from exc
+
+
+__all__: Sequence[str] = ["register_new_cmd"]

agentforge/cli/run_cmd.py

@@ -0,0 +1,234 @@
+"""`agentforge run` — invoke an Agent against a task (feat-017 chunk 4).
+
+Configurable from the command line:
+
+    agentforge run "Review this PR"
+    agentforge run --task-file ./task.txt
+    agentforge run --override agent.budget.usd=10 "..."
+    agentforge run --output-format json "..."
+    agentforge run --replay 01HX...  --to-step 5
+    agentforge run --record "..."      # writes step claims to memory
+
+Exit codes (locked in feat-017 §4):
+
+    0  success
+    1  generic error
+    2  config invalid
+    3  budget exceeded
+    4  guardrail tripped
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from agentforge_core.production.exceptions import (
+    BudgetExceeded,
+    GuardrailViolation,
+    ModuleError,
+)
+from pydantic import ValidationError
+
+from agentforge.agent import Agent
+from agentforge.cli._build import build_agent_from_config, build_memory_from_config
+from agentforge.replay import ReplayLLMClient, load_pipeline_result
+
+EXIT_OK = 0
+EXIT_GENERIC = 1
+EXIT_CONFIG_INVALID = 2
+EXIT_BUDGET = 3
+EXIT_GUARDRAIL = 4
+
+
+def register_run_cmd(sub: argparse._SubParsersAction) -> None:  # type: ignore[type-arg]
+    parser = sub.add_parser(
+        "run",
+        help="Run an agent against a task.",
+        description="Run an agent against a task and print its output.",
+    )
+    parser.add_argument("task", nargs="?", default=None, help="Task text to run.")
+    parser.add_argument(
+        "--task-file",
+        type=Path,
+        default=None,
+        help="Read the task body from a file (alternative to positional).",
+    )
+    parser.add_argument(
+        "--path",
+        type=Path,
+        default=None,
+        help="Path to agentforge.yaml (defaults to ./agentforge.yaml or $AGENTFORGE_CONFIG).",
+    )
+    parser.add_argument(
+        "--env",
+        default=None,
+        help="Override AGENTFORGE_ENV for this run (selects agentforge.<env>.yaml).",
+    )
+    parser.add_argument(
+        "--override",
+        action="append",
+        default=[],
+        metavar="KEY=VALUE",
+        help="Dotted-path config override (repeatable), e.g. agent.budget.usd=5.",
+    )
+    parser.add_argument(
+        "--output-format",
+        choices=("rich", "json", "plain"),
+        default=None,
+        help="How to print the result. Default: rich if stdout is a TTY else plain.",
+    )
+    parser.add_argument(
+        "--replay",
+        default=None,
+        metavar="RUN_ID",
+        help="Replay a previously recorded run instead of calling the LLM.",
+    )
+    parser.add_argument(
+        "--to-step",
+        type=int,
+        default=None,
+        help="Stop replay after this many emitted steps (debug aid).",
+    )
+    parser.add_argument(
+        "--record",
+        action="store_true",
+        help="Persist this run's steps + result to the configured memory store.",
+    )
+    parser.set_defaults(_handler=_run_handler)
+
+
+def _run_handler(args: argparse.Namespace) -> int:
+    return asyncio.run(_dispatch(args))
+
+
+async def _dispatch(args: argparse.Namespace) -> int:
+    task = _resolve_task(args)
+    if task is None:
+        sys.stderr.write("agentforge run: must provide a task or --task-file.\n")
+        return EXIT_GENERIC
+
+    config_or_code = _load_config_or_exit(args)
+    if isinstance(config_or_code, int):
+        return config_or_code
+
+    try:
+        agent, replay_pipeline = await _build_for_run(args, config_or_code)
+    except ModuleError as exc:
+        sys.stderr.write(f"agentforge run: failed to construct agent: {exc}\n")
+        return EXIT_GENERIC
+
+    return await _run_and_emit(agent, task, args.output_format, replay_pipeline=replay_pipeline)
+
+
+def _load_config_or_exit(args: argparse.Namespace) -> Any:
+    """Load config; return the config object or an exit code int."""
+    from agentforge_core.config.loader import load_config  # noqa: PLC0415
+
+    try:
+        return load_config(args.path, env=args.env, overrides=list(args.override) or None)
+    except ValidationError as exc:
+        sys.stderr.write(f"agentforge run: config invalid:\n{exc}\n")
+        return EXIT_CONFIG_INVALID
+    except ModuleError as exc:
+        sys.stderr.write(f"agentforge run: {exc}\n")
+        return EXIT_CONFIG_INVALID
+
+
+async def _run_and_emit(
+    agent: Agent,
+    task: str,
+    output_format: str | None,
+    *,
+    replay_pipeline: Any | None = None,
+) -> int:
+    try:
+        result = await agent.run(task, replay_pipeline=replay_pipeline)
+    except BudgetExceeded as exc:
+        sys.stderr.write(f"agentforge run: budget exceeded: {exc}\n")
+        return EXIT_BUDGET
+    except GuardrailViolation as exc:
+        sys.stderr.write(f"agentforge run: guardrail tripped: {exc}\n")
+        return EXIT_GUARDRAIL
+    except ModuleError as exc:
+        sys.stderr.write(f"agentforge run: {exc}\n")
+        return EXIT_GENERIC
+    _emit(result, output_format)
+    return EXIT_OK
+
+
+async def _build_for_run(args: argparse.Namespace, config: Any) -> tuple[Agent, Any | None]:
+    """Wire an Agent, optionally substituting the LLM with a replay client.
+
+    Returns ``(agent, replay_pipeline)`` — the second tuple item is a
+    previously recorded `PipelineResult` (or ``None``) that the run
+    handler threads into `Agent.run(replay_pipeline=...)` so a
+    side-effect-bearing pipeline doesn't re-execute on replay.
+    """
+    if args.replay is not None:
+        memory = build_memory_from_config(config)
+        if memory is None:
+            msg = "--replay requires modules.memory to be configured."
+            raise ModuleError(msg)
+        replay_llm = await ReplayLLMClient.from_recording(memory, args.replay)
+        replay_pipeline = await load_pipeline_result(memory, args.replay)
+        return Agent(model=replay_llm, memory=memory), replay_pipeline
+    return await build_agent_from_config(config, enable_recording=args.record), None
+
+
+def _resolve_task(args: argparse.Namespace) -> str | None:
+    if args.task is not None and args.task_file is not None:
+        msg = "agentforge run: pass either positional task or --task-file, not both.\n"
+        sys.stderr.write(msg)
+        return None
+    if args.task is not None:
+        return str(args.task)
+    if args.task_file is not None:
+        return Path(args.task_file).read_text(encoding="utf-8").strip()
+    return None
+
+
+def _emit(result: Any, output_format: str | None) -> None:
+    fmt = output_format or ("rich" if sys.stdout.isatty() else "plain")
+    if fmt == "json":
+        print(json.dumps(result.model_dump(mode="json"), indent=2))
+        return
+    if fmt == "rich":
+        _print_rich(result)
+        return
+    # Plain — just the output.
+    output = result.output
+    if isinstance(output, dict):
+        print(json.dumps(output))
+    else:
+        print(output)
+
+
+def _print_rich(result: Any) -> None:
+    try:
+        from rich.console import Console  # noqa: PLC0415
+        from rich.table import Table  # noqa: PLC0415
+    except ImportError:
+        # Rich not installed — fall back to plain.
+        _emit(result, "plain")
+        return
+    console = Console()
+    table = Table(title="Run summary", show_header=True)
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("run_id", result.run_id)
+    table.add_row("finish_reason", str(result.finish_reason))
+    table.add_row("steps", str(len(result.steps)))
+    table.add_row("cost_usd", f"{result.cost_usd:.4f}")
+    table.add_row("tokens_in/out", f"{result.tokens_in} / {result.tokens_out}")
+    table.add_row("duration_ms", str(result.duration_ms))
+    console.print(table)
+    console.print()
+    console.print(result.output)
+
+
+__all__ = ["register_run_cmd"]