loopengt 0.1.0__py3-none-any.whl

loopengt/__init__.py

@@ -0,0 +1,31 @@
+"""Loop Engineering Agent — design, orchestrate, and evaluate agent loops."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__all__ = [
+    "__version__",
+    "LoopSpec",
+    "LoopState",
+    "AgentRole",
+    "ToolSpec",
+    "Policy",
+]
+
+# Lazy imports to keep startup fast
+def __getattr__(name: str) -> object:
+    """Lazy-load public API symbols."""
+    _imports: dict[str, tuple[str, str]] = {
+        "LoopSpec": ("loopengt.core.models.loop_spec", "LoopSpec"),
+        "LoopState": ("loopengt.core.models.state", "LoopState"),
+        "AgentRole": ("loopengt.core.models.agent", "AgentRole"),
+        "ToolSpec": ("loopengt.core.models.tool", "ToolSpec"),
+        "Policy": ("loopengt.core.models.policy", "Policy"),
+    }
+    if name in _imports:
+        module_path, attr_name = _imports[name]
+        import importlib
+
+        module = importlib.import_module(module_path)
+        return getattr(module, attr_name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

loopengt/adapters/__init__.py

@@ -0,0 +1 @@
+"""IDE adapters for loop engineering."""

loopengt/adapters/antigravity/__init__.py

@@ -0,0 +1 @@
+"""Antigravity IDE adapter."""

loopengt/adapters/antigravity/adapter.py

@@ -0,0 +1,55 @@
+"""Antigravity IDE adapter — skeleton implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loopengt.plugins.base import Plugin
+from loopengt.plugins.manifest import PluginManifest
+
+
+class AntigravityAdapter(Plugin):
+    """Adapter for Google Antigravity IDE.
+
+    Integrates loopengt with Antigravity's MCP tool system and
+    skill framework.
+
+    .. note:: Skeleton — requires Antigravity MCP integration.
+    """
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="antigravity",
+            version="0.1.0",
+            description="Antigravity IDE adapter for loopengt",
+            capabilities=["adapter", "commands", "mcp"],
+            entry_points=["loopengt.adapters"],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        self._active = True
+
+    def deactivate(self) -> None:
+        self._active = False
+
+    def capabilities(self) -> set[str]:
+        return {"commands", "mcp", "file_access", "terminal"}
+
+    def register_commands(self, registry: Any) -> None:
+        raise NotImplementedError("Antigravity command registration not yet implemented")
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        pass
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        pass
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        pass
+
+    def on_loop_complete(self, result: Any) -> None:
+        pass
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        pass

loopengt/adapters/antigravity/commands.py

@@ -0,0 +1,21 @@
+"""Antigravity command definitions — placeholder."""
+
+from __future__ import annotations
+
+ANTIGRAVITY_COMMANDS = [
+    {
+        "id": "loopengt.design",
+        "title": "Design Loop",
+        "description": "Design a new agent loop from a goal",
+    },
+    {
+        "id": "loopengt.run",
+        "title": "Run Loop",
+        "description": "Execute a loop.yaml spec",
+    },
+    {
+        "id": "loopengt.trace",
+        "title": "View Trace",
+        "description": "Inspect execution trace",
+    },
+]

loopengt/adapters/base.py

@@ -0,0 +1,51 @@
+"""Adapter protocol — the contract all IDE adapters must implement."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Protocol for IDE/environment adapters.
+
+    Each adapter bridges loopengt's runtime with a specific IDE or
+    execution environment (terminal, Cursor, Claude Code, etc.).
+    """
+
+    def capabilities(self) -> set[str]:
+        """Return the set of capabilities this adapter provides.
+
+        Standard capabilities include:
+        - ``"commands"`` — can register user-facing commands
+        - ``"notifications"`` — can show notifications
+        - ``"progress"`` — can show progress indicators
+        - ``"file_access"`` — can read/write files
+        - ``"terminal"`` — has terminal access
+        - ``"mcp"`` — supports MCP protocol
+        """
+        ...
+
+    def register_commands(self, registry: Any) -> None:
+        """Register adapter-specific commands with the given registry."""
+        ...
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        """Called when a loop begins execution."""
+        ...
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        """Called when a step begins execution."""
+        ...
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        """Called when a step completes."""
+        ...
+
+    def on_loop_complete(self, result: Any) -> None:
+        """Called when the loop finishes."""
+        ...
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        """Called when an error occurs during execution."""
+        ...

loopengt/adapters/claude_code/__init__.py

@@ -0,0 +1 @@
+"""Claude Code adapter."""

loopengt/adapters/claude_code/adapter.py

@@ -0,0 +1,55 @@
+"""Claude Code adapter — skeleton implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loopengt.plugins.base import Plugin
+from loopengt.plugins.manifest import PluginManifest
+
+
+class ClaudeCodeAdapter(Plugin):
+    """Adapter for Claude Code (Anthropic's CLI-based coding agent).
+
+    Integrates loopengt with Claude Code's MCP tool capabilities
+    and permission model.
+
+    .. note:: Skeleton — requires Claude Code's MCP integration.
+    """
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="claude-code",
+            version="0.1.0",
+            description="Claude Code adapter for loopengt",
+            capabilities=["adapter", "commands", "mcp"],
+            entry_points=["loopengt.adapters"],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        self._active = True
+
+    def deactivate(self) -> None:
+        self._active = False
+
+    def capabilities(self) -> set[str]:
+        return {"commands", "mcp", "file_access", "terminal"}
+
+    def register_commands(self, registry: Any) -> None:
+        raise NotImplementedError("Claude Code command registration not yet implemented")
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        pass
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        pass
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        pass
+
+    def on_loop_complete(self, result: Any) -> None:
+        pass
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        pass

loopengt/adapters/claude_code/commands.py

@@ -0,0 +1,16 @@
+"""Claude Code command definitions — placeholder."""
+
+from __future__ import annotations
+
+CLAUDE_CODE_COMMANDS = [
+    {
+        "id": "loopengt.design",
+        "title": "Design Loop",
+        "description": "Design a new agent loop from a goal",
+    },
+    {
+        "id": "loopengt.run",
+        "title": "Run Loop",
+        "description": "Execute a loop.yaml spec",
+    },
+]

loopengt/adapters/codex/__init__.py

@@ -0,0 +1 @@
+"""Codex adapter."""

loopengt/adapters/codex/adapter.py

@@ -0,0 +1,52 @@
+"""Codex (OpenAI) adapter — skeleton implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loopengt.plugins.base import Plugin
+from loopengt.plugins.manifest import PluginManifest
+
+
+class CodexAdapter(Plugin):
+    """Adapter for OpenAI Codex agent environment.
+
+    .. note:: Skeleton — requires Codex CLI integration.
+    """
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="codex",
+            version="0.1.0",
+            description="Codex adapter for loopengt",
+            capabilities=["adapter", "commands"],
+            entry_points=["loopengt.adapters"],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        self._active = True
+
+    def deactivate(self) -> None:
+        self._active = False
+
+    def capabilities(self) -> set[str]:
+        return {"commands", "file_access"}
+
+    def register_commands(self, registry: Any) -> None:
+        raise NotImplementedError("Codex command registration not yet implemented")
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        pass
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        pass
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        pass
+
+    def on_loop_complete(self, result: Any) -> None:
+        pass
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        pass

loopengt/adapters/codex/commands.py

@@ -0,0 +1,16 @@
+"""Codex command definitions — placeholder."""
+
+from __future__ import annotations
+
+CODEX_COMMANDS = [
+    {
+        "id": "loopengt.design",
+        "title": "Design Loop",
+        "description": "Design a new agent loop",
+    },
+    {
+        "id": "loopengt.run",
+        "title": "Run Loop",
+        "description": "Execute a loop spec",
+    },
+]

loopengt/adapters/cursor/__init__.py

@@ -0,0 +1 @@
+"""Cursor IDE adapter."""

loopengt/adapters/cursor/adapter.py

@@ -0,0 +1,56 @@
+"""Cursor IDE adapter — skeleton implementation."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loopengt.plugins.base import Plugin
+from loopengt.plugins.manifest import PluginManifest
+
+
+class CursorAdapter(Plugin):
+    """Adapter for the Cursor IDE.
+
+    Registers loopengt commands accessible via Cursor's command palette
+    and integrates with Cursor's agent capabilities.
+
+    .. note:: This is a skeleton implementation.  Full integration
+       requires the Cursor extension API.
+    """
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="cursor",
+            version="0.1.0",
+            description="Cursor IDE adapter for loopengt",
+            capabilities=["adapter", "commands", "mcp"],
+            entry_points=["loopengt.adapters"],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        self._active = True
+
+    def deactivate(self) -> None:
+        self._active = False
+
+    def capabilities(self) -> set[str]:
+        return {"commands", "mcp", "file_access"}
+
+    def register_commands(self, registry: Any) -> None:
+        raise NotImplementedError("Cursor command registration not yet implemented")
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        pass  # Will integrate with Cursor notifications
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        pass
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        pass
+
+    def on_loop_complete(self, result: Any) -> None:
+        pass
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        pass

loopengt/adapters/cursor/commands.py

@@ -0,0 +1,29 @@
+"""Cursor-specific command definitions — placeholder."""
+
+from __future__ import annotations
+
+# Cursor commands will be registered via the Cursor extension API.
+# This module defines the command metadata for Cursor integration.
+
+CURSOR_COMMANDS = [
+    {
+        "id": "loopengt.design",
+        "title": "LOOPENGT: Design Loop",
+        "description": "Design a new agent loop from a goal",
+    },
+    {
+        "id": "loopengt.run",
+        "title": "LOOPENGT: Run Loop",
+        "description": "Execute a loop.yaml spec",
+    },
+    {
+        "id": "loopengt.trace",
+        "title": "LOOPENGT: View Trace",
+        "description": "Inspect execution trace of a run",
+    },
+    {
+        "id": "loopengt.template",
+        "title": "LOOPENGT: Use Template",
+        "description": "Create a loop from a template",
+    },
+]

loopengt/adapters/generic/__init__.py

@@ -0,0 +1 @@
+"""Generic (non-IDE-specific) adapters."""

loopengt/adapters/generic/terminal.py

@@ -0,0 +1,82 @@
+"""Terminal/CLI adapter — the default adapter for command-line usage."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+
+from loopengt.adapters.base import Adapter
+from loopengt.plugins.base import Plugin
+from loopengt.plugins.manifest import PluginManifest
+
+console = Console()
+
+
+class TerminalAdapter(Plugin):
+    """Full terminal/CLI adapter for loopengt.
+
+    This is the default adapter used when running ``loopengt`` from the
+    command line.  It outputs step progress to the terminal using Rich.
+    """
+
+    @property
+    def manifest(self) -> PluginManifest:
+        return PluginManifest(
+            name="terminal",
+            version="0.1.0",
+            description="Terminal/CLI adapter for loopengt",
+            capabilities=["adapter", "commands", "notifications", "progress", "terminal"],
+            entry_points=["loopengt.adapters"],
+        )
+
+    def activate(self, context: dict[str, Any]) -> None:
+        """Activate the terminal adapter."""
+        self._active = True
+
+    def deactivate(self) -> None:
+        """Deactivate the terminal adapter."""
+        self._active = False
+
+    # ------------------------------------------------------------------
+    # Adapter protocol
+    # ------------------------------------------------------------------
+
+    def capabilities(self) -> set[str]:
+        return {"commands", "notifications", "progress", "terminal"}
+
+    def register_commands(self, registry: Any) -> None:
+        """Terminal adapter commands are registered via CLI; no-op here."""
+
+    def on_loop_start(self, loop_spec: dict[str, Any]) -> None:
+        name = loop_spec.get("name", "unknown")
+        console.print(f"\n[bold blue]▶ Loop starting:[/bold blue] {name}")
+        console.print(f"  Pattern: {loop_spec.get('pattern', 'sequential')}")
+        agents = loop_spec.get("agents", [])
+        if agents:
+            names = [
+                a["name"] if isinstance(a, dict) else str(a) for a in agents
+            ]
+            console.print(f"  Agents:  {', '.join(names)}")
+        console.print()
+
+    def on_step_start(self, step: str, agent: str) -> None:
+        console.print(f"  [yellow]● Step:[/yellow] {step}  [dim]agent={agent}[/dim]")
+
+    def on_step_complete(self, step: str, result: Any) -> None:
+        status = "✓" if result else "●"
+        color = "green" if result else "dim"
+        console.print(f"  [{color}]{status} Completed:[/{color}] {step}")
+
+    def on_loop_complete(self, result: Any) -> None:
+        console.print(f"\n[bold green]✓ Loop completed[/bold green]")
+        if isinstance(result, dict):
+            run_id = result.get("run_id", "")
+            if run_id:
+                console.print(f"  Run ID: {run_id}")
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        console.print(f"\n[bold red]✗ Error:[/bold red] {error}")
+        step = context.get("step")
+        if step:
+            console.print(f"  Step: {step}")

loopengt/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for loopengt."""

loopengt/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command subpackage."""

loopengt/cli/commands/design.py

@@ -0,0 +1,171 @@
+"""``loopengt design`` — invoke LOOPENGT to generate a loop spec from a goal."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+
+from loopengt.cli.formatters import print_error, print_info, print_success
+
+
+def design_cmd(
+    goal: str = typer.Argument(
+        ..., help="Natural-language goal for the loop to achieve."
+    ),
+    output: Path = typer.Option(
+        Path("loop.yaml"),
+        "--output",
+        "-o",
+        help="Output path for the generated loop.yaml.",
+    ),
+    template: str | None = typer.Option(
+        None,
+        "--template",
+        "-t",
+        help="Start from a named template instead of blank.",
+    ),
+    design_doc: Path = typer.Option(
+        Path("loopengt.md"),
+        "--design-doc",
+        "-d",
+        help="Output path for the design document.",
+    ),
+) -> None:
+    """Design a loop spec from a natural-language goal.
+
+    Invokes the LOOPENGT architect prompt (or an LLM if configured) to
+    produce a ``loop.yaml`` and ``LOOP_DESIGN.md``.
+    """
+    print_info(f"Designing loop for goal: {goal}")
+
+    # Try LLM-based design first
+    try:
+        from loopengt.core.designer import design_loop
+
+        spec_dict, design_markdown = design_loop(goal, template_name=template)
+    except ImportError:
+        # Fall back to template-based stub generation
+        spec_dict = _generate_stub_spec(goal, template)
+        design_markdown = _generate_stub_design(goal, spec_dict)
+
+    # Write loop.yaml
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(
+        yaml.dump(spec_dict, default_flow_style=False, sort_keys=False),
+        encoding="utf-8",
+    )
+    print_success(f"Loop spec written to {output}")
+
+    # Write design doc
+    design_doc.parent.mkdir(parents=True, exist_ok=True)
+    design_doc.write_text(design_markdown, encoding="utf-8")
+    print_success(f"Design document written to {design_doc}")
+
+    print_info("Next: loopengt run loop.yaml")
+
+
+def _generate_stub_spec(goal: str, template: str | None) -> dict:
+    """Generate a minimal loop spec dict without an LLM."""
+    import re
+
+    # Derive a slug name from the goal
+    slug = re.sub(r"[^a-z0-9]+", "-", goal.lower()).strip("-")[:64]
+
+    spec: dict = {
+        "name": slug,
+        "version": "1.0",
+        "goal": goal,
+        "pattern": "sequential",
+        "agents": [
+            {
+                "name": "planner",
+                "description": f"Plans the approach for: {goal}",
+                "capabilities": ["planning"],
+            },
+            {
+                "name": "executor",
+                "description": "Executes the plan produced by the planner",
+                "capabilities": ["code_generation", "tool_use"],
+            },
+        ],
+        "steps": [
+            {
+                "name": "plan",
+                "description": "Analyse the goal and produce an action plan",
+                "agent": "planner",
+            },
+            {
+                "name": "execute",
+                "description": "Execute the plan",
+                "agent": "executor",
+                "dependencies": [{"step_name": "plan"}],
+            },
+        ],
+        "policy": {
+            "max_turns": 20,
+            "max_total_time_seconds": 600,
+        },
+        "stop_conditions": [
+            {"condition_type": "max_turns", "value": 20},
+            {"condition_type": "goal_met", "value": "true"},
+        ],
+    }
+
+    if template:
+        spec["metadata"] = {"based_on_template": template}
+
+    return spec
+
+
+def _generate_stub_design(goal: str, spec: dict) -> str:
+    """Generate a stub loopengt.md without an LLM."""
+    agents_section = ""
+    for agent in spec.get("agents", []):
+        agents_section += (
+            f"### {agent['name']}\n"
+            f"- **Description**: {agent.get('description', 'N/A')}\n"
+            f"- **Capabilities**: {', '.join(agent.get('capabilities', []))}\n\n"
+        )
+
+    steps_section = ""
+    for i, step in enumerate(spec.get("steps", []), 1):
+        steps_section += (
+            f"{i}. **{step['name']}** — {step.get('description', 'N/A')}\n"
+            f"   - Agent: `{step['agent']}`\n"
+        )
+        if step.get("dependencies"):
+            deps = ", ".join(d["step_name"] for d in step["dependencies"])
+            steps_section += f"   - Depends on: {deps}\n"
+        steps_section += "\n"
+
+    return (
+        f"# Loop Design: {spec.get('name', 'untitled')}\n"
+        f"\n"
+        f"## Goal\n"
+        f"{goal}\n"
+        f"\n"
+        f"## Pattern\n"
+        f"`{spec.get('pattern', 'sequential')}`\n"
+        f"\n"
+        f"## Agents\n"
+        f"{agents_section}"
+        f"## Steps\n"
+        f"{steps_section}"
+        f"## Policy\n"
+        f"- Max turns: {spec.get('policy', {}).get('max_turns', 50)}\n"
+        f"- Max time: {spec.get('policy', {}).get('max_total_time_seconds', 3600)}s\n"
+        f"\n"
+        f"## Risks & Mitigations\n"
+        f"- *To be refined with LLM-assisted design.*\n"
+        f"\n"
+        f"## Execution Instructions\n"
+        f"If you are reading this as an Agentic IDE (Cursor, Claude Code, Antigravity, etc.), "
+        f"**you are the Orchestrator**.\n\n"
+        f"Please execute this loop by fulfilling the roles of each agent described above in sequence, "
+        f"writing code and performing tasks as specified in the Steps section.\n"
+        f"\n"
+        f"---\n"
+        f"*Generated by loopengt design (stub mode)*\n"
+    )