loopengt 0.1.0__py3-none-any.whl

loopengt/cli/commands/doctor.py

@@ -0,0 +1,110 @@
+"""``loopengt doctor`` — diagnose configuration and dependencies."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+import typer
+
+from loopengt.cli.formatters import print_doctor_result, print_header
+
+
+def doctor_cmd() -> None:
+    """Diagnose loopengt configuration, dependencies, and adapters."""
+    from pathlib import Path
+
+    print_header("loopengt doctor", "Checking configuration and dependencies")
+
+    # 1. Python version
+    py_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    py_ok = sys.version_info >= (3, 11)
+    print_doctor_result(
+        "Python version",
+        py_ok,
+        f"{py_version} {'(>= 3.11 required)' if not py_ok else ''}",
+    )
+
+    # 2. Core dependencies
+    core_deps = ["pydantic", "typer", "rich", "structlog", "anyio", "yaml"]
+    for dep in core_deps:
+        try:
+            mod = importlib.import_module(dep)
+            version = getattr(mod, "__version__", "installed")
+            print_doctor_result(f"  {dep}", True, version)
+        except ImportError:
+            print_doctor_result(f"  {dep}", False, "not installed")
+
+    # 3. Optional dependencies
+    optional_deps = {
+        "mcp": ["fastmcp", "mcp"],
+        "llm": ["openai", "httpx"],
+    }
+    for group, deps in optional_deps.items():
+        for dep in deps:
+            try:
+                mod = importlib.import_module(dep)
+                version = getattr(mod, "__version__", "installed")
+                print_doctor_result(f"  {dep} [{group}]", True, version)
+            except ImportError:
+                print_doctor_result(
+                    f"  {dep} [{group}]", False, f"install with: uv pip install \"loopengt[{group}]\""
+                )
+
+    # 4. .loopengt/ directory
+    loopengt_dir = Path(".loopengt")
+    print_doctor_result(
+        ".loopengt/ directory",
+        loopengt_dir.exists(),
+        str(loopengt_dir.resolve()) if loopengt_dir.exists() else "run 'loopengt init'",
+    )
+
+    if loopengt_dir.exists():
+        config_path = loopengt_dir / "config.toml"
+        print_doctor_result(
+            "  config.toml",
+            config_path.exists(),
+        )
+
+        runs_dir = loopengt_dir / "runs"
+        run_count = len(list(runs_dir.glob("*.json"))) if runs_dir.exists() else 0
+        print_doctor_result(
+            "  runs/",
+            runs_dir.exists(),
+            f"{run_count} trace(s)" if runs_dir.exists() else "",
+        )
+
+    # 5. Plugin entry points
+    try:
+        if sys.version_info >= (3, 12):
+            from importlib.metadata import entry_points
+            adapters = entry_points(group="loopengt.adapters")
+        else:
+            from importlib.metadata import entry_points
+            eps = entry_points()
+            adapters = eps.get("loopengt.adapters", [])
+
+        adapter_names = [ep.name for ep in adapters]
+        print_doctor_result(
+            "Registered adapters",
+            len(adapter_names) > 0,
+            ", ".join(adapter_names) if adapter_names else "none found",
+        )
+    except Exception:  # noqa: BLE001
+        print_doctor_result("Registered adapters", False, "discovery failed")
+
+    # 6. Environment variables
+    import os
+
+    env_vars = {
+        "OPENAI_API_KEY": "OpenAI API key",
+        "HF_TOKEN": "Hugging Face API token",
+        "LOOPENGT_LLM_PROVIDER": "LLM provider override (e.g. openai, huggingface)",
+    }
+    for var, desc in env_vars.items():
+        present = os.environ.get(var) is not None
+        print_doctor_result(
+            f"  ${var}",
+            present,
+            desc if not present else "set",
+        )

loopengt/cli/commands/eval.py

@@ -0,0 +1,105 @@
+"""``loopengt eval`` — run evaluations against a completed run."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from loopengt.cli.formatters import console, print_error, print_info, print_success
+
+
+def eval_cmd(
+    run_id: str = typer.Argument(..., help="Run ID to evaluate."),
+    runs_dir: Path = typer.Option(
+        Path(".loopengt/runs"),
+        "--runs-dir",
+        help="Directory containing run traces.",
+    ),
+    metrics: list[str] = typer.Option(
+        [],
+        "--metric",
+        "-m",
+        help="Specific metrics to evaluate (default: all).",
+    ),
+) -> None:
+    """Run evaluations against a completed loop run."""
+    trace_path = runs_dir / f"{run_id}.json"
+
+    if not trace_path.exists():
+        candidates = list(runs_dir.glob(f"{run_id}*"))
+        if candidates:
+            trace_path = candidates[0]
+        else:
+            print_error(f"Trace not found: {trace_path}")
+            raise typer.Exit(code=1)
+
+    try:
+        trace_data = json.loads(trace_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        print_error(f"Failed to read trace: {exc}")
+        raise typer.Exit(code=1) from exc
+
+    print_info(f"Evaluating run {run_id}…")
+
+    # Run built-in metrics
+    results = _evaluate_builtin_metrics(trace_data, metrics or None)
+
+    # Display results
+    from rich.table import Table
+
+    table = Table(title="Evaluation Results", border_style="green")
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="white")
+    table.add_column("Status", style="green")
+
+    for name, value, status in results:
+        status_style = "green" if status == "pass" else "red"
+        table.add_row(name, str(value), f"[{status_style}]{status}[/{status_style}]")
+
+    console.print(table)
+    print_success(f"Evaluation complete for run {run_id}")
+
+
+def _evaluate_builtin_metrics(
+    trace_data: dict, metric_names: list[str] | None = None
+) -> list[tuple[str, object, str]]:
+    """Evaluate built-in metrics against a trace."""
+    results: list[tuple[str, object, str]] = []
+
+    all_metrics = {
+        "total_turns": lambda t: (t.get("turn", 0), "pass"),
+        "total_steps": lambda t: (len(t.get("step_states", {})), "pass"),
+        "completed_steps": lambda t: (
+            sum(
+                1
+                for s in t.get("step_states", {}).values()
+                if s.get("status") == "completed"
+            ),
+            "pass",
+        ),
+        "failed_steps": lambda t: (
+            (
+                n := sum(
+                    1
+                    for s in t.get("step_states", {}).values()
+                    if s.get("status") == "failed"
+                )
+            ),
+            "fail" if n > 0 else "pass",
+        ),
+        "run_status": lambda t: (
+            t.get("status", "unknown"),
+            "pass" if t.get("status") == "completed" else "fail",
+        ),
+    }
+
+    selected = metric_names or list(all_metrics.keys())
+
+    for name in selected:
+        if name in all_metrics:
+            value, status = all_metrics[name](trace_data)
+            results.append((name, value, status))
+
+    return results

loopengt/cli/commands/init.py

@@ -0,0 +1,131 @@
+"""``loopengt init`` — scaffold a new .loopengt/ project directory."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import typer
+
+from loopengt.cli.formatters import print_error, print_info, print_success
+
+
+def init_cmd(
+    directory: Path = typer.Argument(
+        Path("."),
+        help="Directory to initialise (defaults to current directory).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing .loopengt/ directory.",
+    ),
+) -> None:
+    """Scaffold a new .loopengt/ project directory with default config."""
+    target = directory.resolve() / ".loopengt"
+
+    if target.exists() and not force:
+        print_error(
+            f"{target} already exists. Use --force to overwrite."
+        )
+        raise typer.Exit(code=1)
+
+    if target.exists() and force:
+        shutil.rmtree(target)
+
+    # Create directory structure
+    dirs = [
+        target,
+        target / "templates",
+        target / "runs",
+        target / "prompts",
+    ]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+
+    # Write default config
+    config_path = target / "config.toml"
+    config_path.write_text(
+        '# Loop Engineering configuration\n'
+        '\n'
+        '[general]\n'
+        'default_pattern = "sequential"\n'
+        'trace_format = "jsonl"\n'
+        '\n'
+        '[llm]\n'
+        'provider = "openai"\n'
+        'model = "gpt-4o"\n'
+        'temperature = 0.7\n'
+        '# api_key_env = "OPENAI_API_KEY"\n'
+        '\n'
+        '[mcp]\n'
+        'transport = "stdio"\n'
+        'host = "localhost"\n'
+        'port = 8765\n'
+        '\n'
+        '[tracing]\n'
+        'backend = "jsonl"\n'
+        'directory = "runs"\n',
+        encoding="utf-8",
+    )
+
+    # Write LOOPENGT prompt
+    loopengt_path = target / "prompts" / "LOOPENGT.md"
+    loopengt_path.write_text(
+        "# LOOPENGT — Loop Engineering Architect\n"
+        "\n"
+        "You are the Loop Engineering Architect.  Given a goal, you design\n"
+        "the optimal agent loop by selecting the right pattern, defining\n"
+        "agents, steps, tools, and policies.\n"
+        "\n"
+        "## Principles\n"
+        "1. Minimal agents — each must justify its existence\n"
+        "2. Clear handoff contracts between steps\n"
+        "3. Verification gates at critical boundaries\n"
+        "4. Graceful degradation on failure\n"
+        "5. Observable by default (structured traces)\n",
+        encoding="utf-8",
+    )
+
+    # Copy built-in templates
+    _copy_builtin_templates(target / "templates")
+
+    print_success(f"Initialised .loopengt/ at {target}")
+    print_info("  config.toml     — edit LLM & tracing settings")
+    print_info("  prompts/        — architect & design prompts")
+    print_info("  templates/      — loop templates")
+    print_info("  runs/           — execution traces")
+    print_info("")
+    print_info("Next: loopengt design \"your goal here\"")
+
+
+def _copy_builtin_templates(templates_dir: Path) -> None:
+    """Copy built-in templates into the project templates directory."""
+    try:
+        from importlib.resources import files
+
+        builtins_root = files("loopengt.templates.builtins")
+        # Iterate known template directories
+        for template_name in (
+            "planner_executor",
+            "reviewer_retry",
+            "supervisor_workers",
+            "research_architect",
+            "handoff_loop",
+        ):
+            try:
+                template_pkg = builtins_root.joinpath(template_name)  # type: ignore[union-attr]
+                dest = templates_dir / template_name
+                dest.mkdir(parents=True, exist_ok=True)
+
+                for filename in ("LOOPENGTS.md", "loop.yaml"):
+                    resource = template_pkg.joinpath(filename)  # type: ignore[union-attr]
+                    resource_text = resource.read_text(encoding="utf-8")  # type: ignore[union-attr]
+                    (dest / filename).write_text(resource_text, encoding="utf-8")
+            except Exception:  # noqa: BLE001
+                # Template not found — skip silently during init
+                continue
+    except Exception:  # noqa: BLE001
+        # importlib.resources not available or templates not packaged yet
+        pass

loopengt/cli/commands/mcp_serve.py

@@ -0,0 +1,57 @@
+"""``loopengt mcp`` — start the MCP server."""
+
+from __future__ import annotations
+
+import typer
+
+from loopengt.cli.formatters import print_error, print_info
+
+
+def mcp_cmd(
+    transport: str = typer.Option(
+        "stdio",
+        "--transport",
+        "-t",
+        help="Transport protocol: stdio or sse.",
+    ),
+    host: str = typer.Option(
+        "localhost",
+        "--host",
+        help="Host for SSE transport.",
+    ),
+    port: int = typer.Option(
+        8765,
+        "--port",
+        "-p",
+        help="Port for SSE transport.",
+    ),
+) -> None:
+    """Start the loopengt MCP server."""
+    print_info(f"Starting MCP server (transport={transport})…")
+
+    try:
+        from loopengt.mcp.server.server import create_server
+
+        server = create_server()
+
+        if transport == "stdio":
+            import asyncio
+
+            asyncio.run(server.run_stdio())
+        elif transport == "sse":
+            import asyncio
+
+            asyncio.run(server.run_sse(host=host, port=port))
+        else:
+            print_error(f"Unknown transport: {transport}")
+            raise typer.Exit(code=1)
+
+    except ImportError:
+        print_error(
+            "MCP dependencies not installed. "
+            "Install with: uv pip install \"loopengt[mcp]\""
+        )
+        raise typer.Exit(code=1)
+    except Exception as exc:  # noqa: BLE001
+        print_error(f"MCP server failed: {exc}")
+        raise typer.Exit(code=1) from exc

loopengt/cli/commands/run.py

@@ -0,0 +1,99 @@
+"""``loopengt run`` — execute a loop from a YAML spec."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import typer
+import yaml
+
+from loopengt.cli.formatters import print_error, print_info, print_success
+
+
+def run_cmd(
+    spec_path: Path = typer.Argument(
+        ..., help="Path to loop.yaml spec file."
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Validate the spec and show the execution plan without running.",
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-V", help="Enable verbose output."
+    ),
+) -> None:
+    """Execute a loop from a YAML specification file."""
+    if not spec_path.exists():
+        print_error(f"Spec file not found: {spec_path}")
+        raise typer.Exit(code=1)
+
+    print_info(f"Loading spec from {spec_path}")
+
+    try:
+        raw = yaml.safe_load(spec_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        print_error(f"Invalid YAML: {exc}")
+        raise typer.Exit(code=1) from exc
+
+    # Validate with Pydantic
+    try:
+        from loopengt.core.models.loop_spec import LoopSpec
+
+        spec = LoopSpec.model_validate(raw)
+    except Exception as exc:  # noqa: BLE001
+        print_error(f"Spec validation failed: {exc}")
+        raise typer.Exit(code=1) from exc
+
+    print_success(f"Spec validated: {spec.name} v{spec.version}")
+    print_info(f"  Pattern : {spec.pattern}")
+    print_info(f"  Agents  : {', '.join(spec.agent_names())}")
+    print_info(f"  Steps   : {', '.join(spec.step_names())}")
+
+    if dry_run:
+        print_info("Dry run — skipping execution.")
+        return
+
+    # Execute the loop
+    print_info("Starting loop execution…")
+    try:
+        from loopengt.core.runtime.executor import LoopExecutor
+
+        executor = LoopExecutor(spec)
+        result = asyncio.run(executor.execute())
+
+        if result.status.value == "completed":
+            print_success(f"Loop completed — run ID: {result.run_id}")
+        else:
+            print_error(f"Loop finished with status: {result.status}")
+            if result.error:
+                print_error(f"  Error: {result.error}")
+
+        # Save trace
+        _save_trace(result, spec_path)
+
+    except Exception as exc:  # noqa: BLE001
+        print_error(f"Execution failed: {exc}")
+        raise typer.Exit(code=1) from exc
+
+
+def _save_trace(state: object, spec_path: Path) -> None:
+    """Persist the run trace to .loopengt/runs/."""
+    import json
+
+    loopengt_dir = spec_path.parent / ".loopengt" / "runs"
+    loopengt_dir.mkdir(parents=True, exist_ok=True)
+
+    # state is a LoopState; serialise via Pydantic
+    try:
+        state_dict = state.model_dump(mode="json")  # type: ignore[union-attr]
+        run_id = state_dict.get("run_id", "unknown")
+        trace_path = loopengt_dir / f"{run_id}.json"
+        trace_path.write_text(
+            json.dumps(state_dict, indent=2, default=str),
+            encoding="utf-8",
+        )
+        print_info(f"Trace saved to {trace_path}")
+    except Exception:  # noqa: BLE001
+        pass

loopengt/cli/commands/template.py

@@ -0,0 +1,145 @@
+"""``loopengt template`` — manage loop templates."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from loopengt.cli.formatters import console, print_error, print_info, print_success
+
+template_app = typer.Typer(
+    name="template",
+    help="Manage loop templates.",
+    no_args_is_help=True,
+)
+
+
+@template_app.command("list")
+def template_list(
+    include_builtins: bool = typer.Option(
+        True, "--builtins/--no-builtins", help="Include built-in templates."
+    ),
+) -> None:
+    """List available loop templates."""
+    from rich.table import Table
+
+    table = Table(title="Available Templates", border_style="blue")
+    table.add_column("Name", style="cyan")
+    table.add_column("Source", style="dim")
+    table.add_column("Description", style="white")
+
+    # Built-in templates
+    if include_builtins:
+        builtins = {
+            "planner_executor": "Sequential plan-then-execute pattern",
+            "reviewer_retry": "Code review with iterative retry on failure",
+            "supervisor_workers": "Supervisor delegates to specialised workers",
+            "research_architect": "Research → synthesise → architect workflow",
+            "handoff_loop": "Sequential agent-to-agent handoff pattern",
+        }
+        for name, desc in builtins.items():
+            table.add_row(name, "builtin", desc)
+
+    # Project-local templates
+    local_dir = Path(".loopengt/templates")
+    if local_dir.exists():
+        for entry in sorted(local_dir.iterdir()):
+            if entry.is_dir() and (entry / "loop.yaml").exists():
+                if entry.name not in (
+                    "planner_executor",
+                    "reviewer_retry",
+                    "supervisor_workers",
+                    "research_architect",
+                    "handoff_loop",
+                ):
+                    table.add_row(entry.name, "local", "")
+
+    console.print(table)
+
+
+@template_app.command("use")
+def template_use(
+    name: str = typer.Argument(..., help="Template name to use."),
+    output: Path = typer.Option(
+        Path("loop.yaml"),
+        "--output",
+        "-o",
+        help="Output path for the loop.yaml.",
+    ),
+) -> None:
+    """Create a loop.yaml from a named template."""
+    import shutil
+
+    # Search in project-local templates first, then built-ins
+    search_paths = [
+        Path(".loopengt/templates") / name,
+    ]
+
+    # Add built-in template paths
+    try:
+        from importlib.resources import files
+
+        builtin_path = files("loopengt.templates.builtins").joinpath(name)  # type: ignore[union-attr]
+        search_paths.append(Path(str(builtin_path)))
+    except Exception:  # noqa: BLE001
+        pass
+
+    for template_dir in search_paths:
+        src = template_dir / "loop.yaml"  # type: ignore[operator]
+        if hasattr(src, "exists") and src.exists():  # type: ignore[union-attr]
+            try:
+                if isinstance(src, Path):
+                    shutil.copy2(src, output)
+                else:
+                    # importlib resource
+                    output.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")  # type: ignore[union-attr]
+                print_success(f"Template '{name}' written to {output}")
+                return
+            except Exception as exc:  # noqa: BLE001
+                print_error(f"Failed to copy template: {exc}")
+                raise typer.Exit(code=1) from exc
+
+    print_error(f"Template not found: {name}")
+    print_info("Use 'loopengt template list' to see available templates.")
+    raise typer.Exit(code=1)
+
+
+@template_app.command("create")
+def template_create(
+    name: str = typer.Argument(..., help="Name for the new template."),
+    source: Path = typer.Option(
+        Path("loop.yaml"),
+        "--source",
+        "-s",
+        help="Source loop.yaml to create template from.",
+    ),
+) -> None:
+    """Create a new template from an existing loop.yaml."""
+    if not source.exists():
+        print_error(f"Source file not found: {source}")
+        raise typer.Exit(code=1)
+
+    template_dir = Path(".loopengt/templates") / name
+    template_dir.mkdir(parents=True, exist_ok=True)
+
+    import shutil
+
+    shutil.copy2(source, template_dir / "loop.yaml")
+
+    # Create a stub LOOPENGTS.md
+    (template_dir / "LOOPENGTS.md").write_text(
+        f"# {name}\n\n"
+        f"## Purpose\n"
+        f"TODO: Describe the purpose of this template.\n\n"
+        f"## Agents\n"
+        f"TODO: Document the agents and their roles.\n\n"
+        f"## Steps\n"
+        f"TODO: Document the execution steps.\n\n"
+        f"## Verification\n"
+        f"TODO: Describe verification criteria.\n",
+        encoding="utf-8",
+    )
+
+    print_success(f"Template '{name}' created at {template_dir}")
+    print_info(f"Edit {template_dir / 'LOOPENGTS.md'} to add documentation.")