loopengt 0.1.0__py3-none-any.whl

loopengt/mcp/shared/schemas.py

@@ -0,0 +1,91 @@
+"""Shared JSON schemas for MCP tools and resources."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+# JSON Schema definitions for MCP tool inputs/outputs
+LOOP_SPEC_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "name": {"type": "string", "description": "Loop identifier"},
+        "version": {"type": "string", "default": "1.0"},
+        "goal": {"type": "string", "description": "Loop objective"},
+        "pattern": {
+            "type": "string",
+            "enum": [
+                "sequential",
+                "supervisor_worker",
+                "parallel_fan_out",
+                "handoff",
+                "evaluator_optimizer",
+                "custom",
+            ],
+            "default": "sequential",
+        },
+        "agents": {
+            "type": "array",
+            "items": {"$ref": "#/$defs/AgentRole"},
+        },
+        "steps": {
+            "type": "array",
+            "items": {"$ref": "#/$defs/StepSpec"},
+        },
+        "policy": {"$ref": "#/$defs/Policy"},
+    },
+    "required": ["name", "goal", "agents", "steps"],
+    "$defs": {
+        "AgentRole": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "description": {"type": "string"},
+                "capabilities": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                },
+            },
+            "required": ["name"],
+        },
+        "StepSpec": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "description": {"type": "string"},
+                "agent": {"type": "string"},
+                "dependencies": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "step_name": {"type": "string"},
+                        },
+                    },
+                },
+            },
+            "required": ["name", "agent"],
+        },
+        "Policy": {
+            "type": "object",
+            "properties": {
+                "max_turns": {"type": "integer", "minimum": 1},
+                "max_total_time_seconds": {"type": "number"},
+            },
+        },
+    },
+}
+
+RUN_RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "status": {
+            "type": "string",
+            "enum": ["completed", "failed", "cancelled", "running"],
+        },
+        "run_id": {"type": "string"},
+        "turns": {"type": "integer"},
+        "steps_completed": {"type": "integer"},
+        "error": {"type": "string"},
+    },
+}

loopengt/plugins/__init__.py

@@ -0,0 +1 @@
+"""Plugin system for extensible loop engineering."""

loopengt/plugins/base.py

@@ -0,0 +1,90 @@
+"""Plugin base class and protocol definitions."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Protocol, runtime_checkable
+
+from loopengt.plugins.manifest import PluginManifest
+
+
+@runtime_checkable
+class PluginProtocol(Protocol):
+    """Protocol that all loopengt plugins must satisfy."""
+
+    @property
+    def manifest(self) -> PluginManifest: ...
+
+    def activate(self, context: dict[str, Any]) -> None: ...
+
+    def deactivate(self) -> None: ...
+
+
+class Plugin(ABC):
+    """Abstract base class for loopengt plugins.
+
+    Provides lifecycle hooks and metadata.  Subclass this to create
+    new plugins.
+
+    Example::
+
+        class MyPlugin(Plugin):
+            @property
+            def manifest(self) -> PluginManifest:
+                return PluginManifest(
+                    name="my-plugin",
+                    version="1.0.0",
+                    description="Does cool things",
+                )
+
+            def activate(self, context):
+                # Set up resources
+                pass
+
+            def deactivate(self):
+                # Tear down resources
+                pass
+    """
+
+    _active: bool = False
+
+    @property
+    @abstractmethod
+    def manifest(self) -> PluginManifest:
+        """Return the plugin's metadata manifest."""
+        ...
+
+    @abstractmethod
+    def activate(self, context: dict[str, Any]) -> None:
+        """Called when the plugin is loaded and activated.
+
+        Parameters
+        ----------
+        context:
+            Shared context dict with config, adapters, etc.
+        """
+        ...
+
+    @abstractmethod
+    def deactivate(self) -> None:
+        """Called when the plugin is being unloaded."""
+        ...
+
+    @property
+    def is_active(self) -> bool:
+        """Whether this plugin is currently active."""
+        return self._active
+
+    def on_loop_start(self, loop_name: str, context: dict[str, Any]) -> None:
+        """Hook called when a loop starts.  Override if needed."""
+
+    def on_loop_complete(
+        self, loop_name: str, result: Any
+    ) -> None:
+        """Hook called when a loop completes.  Override if needed."""
+
+    def on_error(self, error: Exception, context: dict[str, Any]) -> None:
+        """Hook called on errors.  Override if needed."""
+
+    def __repr__(self) -> str:
+        return f"<Plugin {self.manifest.name} v{self.manifest.version}>"

loopengt/plugins/loader.py

@@ -0,0 +1,130 @@
+"""Dynamic plugin loading with validation."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+import structlog
+
+from loopengt.plugins.base import Plugin, PluginProtocol
+from loopengt.plugins.manifest import PluginManifest
+
+logger = structlog.get_logger(__name__)
+
+
+class PluginLoadError(Exception):
+    """Raised when a plugin cannot be loaded."""
+
+
+class PluginLoader:
+    """Dynamically loads plugins from dotted import paths.
+
+    Validates that loaded classes conform to the ``PluginProtocol``
+    and have valid manifests.
+
+    Usage::
+
+        loader = PluginLoader()
+        plugin = loader.load("loopengt.adapters.generic.terminal.TerminalAdapter")
+    """
+
+    def __init__(self) -> None:
+        self._log = logger.bind(component="plugin_loader")
+        self._cache: dict[str, Plugin] = {}
+
+    def load(self, import_path: str) -> Plugin:
+        """Load a plugin class from a dotted import path.
+
+        Parameters
+        ----------
+        import_path:
+            Fully-qualified dotted path, e.g.
+            ``"loopengt.adapters.generic.terminal.TerminalAdapter"``
+
+        Returns
+        -------
+        Plugin
+            An *unactivated* plugin instance.
+
+        Raises
+        ------
+        PluginLoadError
+            If the module/class cannot be imported or does not satisfy
+            the plugin protocol.
+        """
+        if import_path in self._cache:
+            return self._cache[import_path]
+
+        try:
+            module_path, class_name = import_path.rsplit(".", 1)
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+        except (ImportError, AttributeError, ValueError) as exc:
+            raise PluginLoadError(
+                f"Cannot import plugin from '{import_path}': {exc}"
+            ) from exc
+
+        # Instantiate
+        try:
+            instance = cls()
+        except Exception as exc:
+            raise PluginLoadError(
+                f"Cannot instantiate plugin '{import_path}': {exc}"
+            ) from exc
+
+        # Validate
+        if not isinstance(instance, (Plugin, PluginProtocol)):
+            raise PluginLoadError(
+                f"'{import_path}' does not implement the Plugin protocol"
+            )
+
+        # Validate manifest
+        try:
+            manifest = instance.manifest
+            if not isinstance(manifest, PluginManifest):
+                raise PluginLoadError(
+                    f"'{import_path}' manifest is not a PluginManifest"
+                )
+        except Exception as exc:
+            raise PluginLoadError(
+                f"'{import_path}' has invalid manifest: {exc}"
+            ) from exc
+
+        self._cache[import_path] = instance
+        self._log.info(
+            "plugin.loaded",
+            path=import_path,
+            name=manifest.name,
+            version=manifest.version,
+        )
+        return instance
+
+    def load_many(self, import_paths: list[str]) -> list[Plugin]:
+        """Load multiple plugins.  Skips failures with warnings."""
+        plugins = []
+        for path in import_paths:
+            try:
+                plugins.append(self.load(path))
+            except PluginLoadError as exc:
+                self._log.warning("plugin.load_failed", path=path, error=str(exc))
+        return plugins
+
+    def reload(self, import_path: str) -> Plugin:
+        """Force-reload a plugin (hot-reload for development)."""
+        self._cache.pop(import_path, None)
+
+        module_path, _ = import_path.rsplit(".", 1)
+        try:
+            module = importlib.import_module(module_path)
+            importlib.reload(module)
+        except Exception as exc:
+            raise PluginLoadError(
+                f"Cannot reload module '{module_path}': {exc}"
+            ) from exc
+
+        return self.load(import_path)
+
+    def clear_cache(self) -> None:
+        """Clear the loader cache."""
+        self._cache.clear()

loopengt/plugins/manifest.py

@@ -0,0 +1,70 @@
+"""Plugin metadata manifest model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PluginManifest(BaseModel):
+    """Metadata describing a loopengt plugin.
+
+    Every plugin must provide a manifest with at least a name, version,
+    and description.
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    name: str = Field(
+        ..., min_length=1, max_length=128, description="Plugin identifier"
+    )
+    version: str = Field(default="0.1.0", description="Semantic version")
+    description: str = Field(
+        default="", max_length=2048, description="Human-readable description"
+    )
+    author: str = Field(default="", description="Author name or organisation")
+    license: str = Field(default="", description="SPDX license identifier")
+    homepage: str = Field(default="", description="URL to project homepage")
+
+    # Capability declarations
+    capabilities: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Capabilities this plugin provides.  Standard values: "
+            "'adapter', 'mcp_tools', 'templates', 'skills', 'verifiers'"
+        ),
+    )
+
+    # Entry point groups this plugin contributes to
+    entry_points: list[str] = Field(
+        default_factory=list,
+        description="Entry-point groups: loopengt.adapters, loopengt.mcp_tools, …",
+    )
+
+    # Configuration schema
+    config_schema: dict[str, Any] | None = Field(
+        default=None,
+        description="JSON Schema for this plugin's configuration",
+    )
+
+    # Version constraints
+    min_loopengt_version: str | None = Field(
+        default=None,
+        description="Minimum loopengt version required (e.g. '0.1.0')",
+    )
+    max_loopengt_version: str | None = Field(
+        default=None,
+        description="Maximum loopengt version supported",
+    )
+
+    # Dependencies on other plugins
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="Names of plugins this one depends on",
+    )
+
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Arbitrary plugin metadata",
+    )

loopengt/plugins/registry.py

@@ -0,0 +1,146 @@
+"""Entry-point based plugin discovery."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import structlog
+
+from loopengt.plugins.base import Plugin, PluginProtocol
+from loopengt.plugins.manifest import PluginManifest
+
+logger = structlog.get_logger(__name__)
+
+
+class PluginRegistry:
+    """Discovers and manages loopengt plugins via entry points.
+
+    Scans the ``loopengt.adapters``, ``loopengt.mcp_tools``,
+    ``loopengt.templates``, ``loopengt.skills``, and ``loopengt.verifiers``
+    entry-point groups.
+
+    Usage::
+
+        registry = PluginRegistry()
+        registry.discover()
+        adapter = registry.get("terminal", group="loopengt.adapters")
+    """
+
+    ENTRY_POINT_GROUPS = [
+        "loopengt.adapters",
+        "loopengt.mcp_tools",
+        "loopengt.templates",
+        "loopengt.skills",
+        "loopengt.verifiers",
+    ]
+
+    def __init__(self) -> None:
+        self._plugins: dict[str, dict[str, Any]] = {
+            group: {} for group in self.ENTRY_POINT_GROUPS
+        }
+        self._activated: dict[str, Plugin] = {}
+        self._log = logger.bind(component="plugin_registry")
+
+    # ------------------------------------------------------------------
+    # Discovery
+    # ------------------------------------------------------------------
+
+    def discover(self) -> dict[str, list[str]]:
+        """Discover all registered plugins across entry-point groups.
+
+        Returns a dict mapping group name → list of plugin names.
+        """
+        discovered: dict[str, list[str]] = {}
+
+        for group in self.ENTRY_POINT_GROUPS:
+            eps = self._load_entry_points(group)
+            names = []
+            for ep in eps:
+                self._plugins[group][ep.name] = ep
+                names.append(ep.name)
+                self._log.debug(
+                    "plugin.discovered", group=group, name=ep.name
+                )
+            discovered[group] = names
+
+        return discovered
+
+    def get(self, name: str, group: str = "loopengt.adapters") -> Any:
+        """Load and return a plugin class by name and group."""
+        if group not in self._plugins:
+            raise KeyError(f"Unknown plugin group: {group}")
+
+        ep = self._plugins[group].get(name)
+        if ep is None:
+            raise KeyError(
+                f"Plugin '{name}' not found in group '{group}'"
+            )
+
+        return ep.load()
+
+    def list_plugins(
+        self, group: str | None = None
+    ) -> dict[str, list[str]]:
+        """List discovered plugin names, optionally filtered by group."""
+        if group:
+            return {group: list(self._plugins.get(group, {}).keys())}
+        return {g: list(plugins.keys()) for g, plugins in self._plugins.items()}
+
+    # ------------------------------------------------------------------
+    # Activation
+    # ------------------------------------------------------------------
+
+    def activate(
+        self, name: str, group: str, context: dict[str, Any] | None = None
+    ) -> Plugin:
+        """Load, instantiate, and activate a plugin."""
+        plugin_cls = self.get(name, group)
+        instance = plugin_cls()
+
+        if isinstance(instance, Plugin):
+            instance.activate(context or {})
+            instance._active = True
+            self._activated[f"{group}:{name}"] = instance
+            self._log.info("plugin.activated", group=group, name=name)
+        else:
+            self._log.warning(
+                "plugin.not_plugin_subclass",
+                group=group,
+                name=name,
+            )
+
+        return instance
+
+    def deactivate(self, name: str, group: str) -> None:
+        """Deactivate a plugin."""
+        key = f"{group}:{name}"
+        instance = self._activated.pop(key, None)
+        if instance:
+            instance.deactivate()
+            instance._active = False
+            self._log.info("plugin.deactivated", group=group, name=name)
+
+    def deactivate_all(self) -> None:
+        """Deactivate all active plugins."""
+        for key, instance in list(self._activated.items()):
+            instance.deactivate()
+            instance._active = False
+        self._activated.clear()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_entry_points(group: str) -> list[Any]:
+        """Load entry points for a given group."""
+        if sys.version_info >= (3, 12):
+            from importlib.metadata import entry_points
+
+            return list(entry_points(group=group))
+        else:
+            from importlib.metadata import entry_points
+
+            eps = entry_points()
+            return list(eps.get(group, []))

loopengt/prompts/LOOPENGT.md

@@ -0,0 +1,60 @@
+# LOOPENGT — Loop Engineering Architect
+
+You are **LOOPENGT**, the Loop Engineering Architect. Your purpose is to
+design optimal agent loop specifications given a natural-language goal.
+
+## Core Principles
+
+1. **Minimal agents** — each agent must justify its existence with a
+   distinct capability no other agent provides.
+2. **Clear handoff contracts** — every step must define what it receives
+   and what it produces.
+3. **Verification gates** — critical boundaries must have explicit pass/fail
+   checks before the loop continues.
+4. **Graceful degradation** — failures should be retried with backoff, and
+   the loop should produce partial results rather than nothing.
+5. **Observable by default** — every step emits structured trace events.
+
+## Design Process
+
+When given a goal:
+
+1. **Classify** the task type (code generation, review, research, data
+   processing, multi-agent collaboration).
+2. **Select pattern** — choose the orchestration pattern that best fits:
+   - `sequential` — linear step-by-step
+   - `supervisor_worker` — central coordinator with specialists
+   - `parallel_fan_out` — independent concurrent tasks
+   - `handoff` — enrichment pipeline
+   - `evaluator_optimizer` — iterative quality improvement
+3. **Define agents** — minimum viable set with clear roles.
+4. **Design steps** — with dependencies, prompt templates, and tool bindings.
+5. **Set policies** — max turns, retry budgets, timeout, verification gates.
+6. **Specify stop conditions** — when is the loop "done"?
+
+## Output Format
+
+Produce two artifacts:
+
+### 1. `LOOP_DESIGN.md`
+A human-readable design document with:
+- Goal restatement
+- Pattern rationale
+- Agent descriptions
+- Step-by-step walkthrough
+- Verification strategy
+- Risk assessment
+
+### 2. `loop.yaml`
+A valid YAML file conforming to the LoopSpec schema with all fields
+populated.
+
+## Quality Checklist
+
+Before finalising, verify:
+- [ ] Every step references an existing agent
+- [ ] Agent tools are declared in the top-level `tools` list
+- [ ] Dependencies form a DAG (no cycles)
+- [ ] At least one stop condition is defined
+- [ ] Timeout is set for the overall loop
+- [ ] Retry policy is appropriate for the task criticality

loopengt/prompts/__init__.py

@@ -0,0 +1 @@
+"""Prompt templates for loop engineering."""

loopengt/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage backends package."""

loopengt/storage/jsonl.py

@@ -0,0 +1,84 @@
+"""JSONL streaming storage for events and logs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class JSONLStorage:
+    """Append-only JSONL file storage.
+
+    Each record is a single JSON object written as one line.  Suitable
+    for streaming event logs and trace data.
+
+    Usage::
+
+        storage = JSONLStorage(Path(".loopengt/events.jsonl"))
+        storage.append({"event": "step.start", "step": "plan"})
+        records = storage.read_all()
+    """
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._log = logger.bind(component="jsonl", path=str(path))
+
+    def append(self, record: dict[str, Any]) -> None:
+        """Append a single record to the JSONL file."""
+        line = json.dumps(record, default=str, ensure_ascii=False)
+        with open(self._path, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    def append_many(self, records: list[dict[str, Any]]) -> None:
+        """Append multiple records efficiently."""
+        with open(self._path, "a", encoding="utf-8") as f:
+            for record in records:
+                line = json.dumps(record, default=str, ensure_ascii=False)
+                f.write(line + "\n")
+
+    def read_all(self) -> list[dict[str, Any]]:
+        """Read all records from the file."""
+        if not self._path.exists():
+            return []
+
+        records: list[dict[str, Any]] = []
+        with open(self._path, encoding="utf-8") as f:
+            for line_no, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    self._log.warning(
+                        "jsonl.parse_error", line=line_no, path=str(self._path)
+                    )
+        return records
+
+    def read_last(self, n: int = 10) -> list[dict[str, Any]]:
+        """Read the last *n* records (tail)."""
+        all_records = self.read_all()
+        return all_records[-n:]
+
+    def count(self) -> int:
+        """Return the number of records in the file."""
+        if not self._path.exists():
+            return 0
+        with open(self._path, encoding="utf-8") as f:
+            return sum(1 for line in f if line.strip())
+
+    def truncate(self) -> None:
+        """Clear all records from the file."""
+        with open(self._path, "w", encoding="utf-8"):
+            pass
+
+    @property
+    def path(self) -> Path:
+        """Return the file path."""
+        return self._path