loopengt 0.1.0__py3-none-any.whl

loopengt/storage/sqlite.py

@@ -0,0 +1,102 @@
+"""SQLite storage backend for traces and checkpoints."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class SQLiteStorage:
+    """General-purpose async SQLite storage.
+
+    Wraps ``aiosqlite`` and provides convenience methods for common
+    operations used by the trace and checkpoint subsystems.
+
+    Usage::
+
+        storage = SQLiteStorage(Path(".loopengt/data.db"))
+        async with storage:
+            await storage.execute("INSERT INTO ...", ...)
+    """
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = db_path
+        self._db: Any = None
+        self._log = logger.bind(component="sqlite", path=str(db_path))
+
+    async def __aenter__(self) -> "SQLiteStorage":
+        await self.open()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def open(self) -> None:
+        """Open the database connection."""
+        import aiosqlite
+
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = await aiosqlite.connect(str(self._db_path))
+        await self._db.execute("PRAGMA journal_mode=WAL")
+        self._log.debug("sqlite.opened")
+
+    async def close(self) -> None:
+        """Close the database connection."""
+        if self._db:
+            await self._db.close()
+            self._db = None
+            self._log.debug("sqlite.closed")
+
+    async def execute(self, sql: str, params: tuple[Any, ...] = ()) -> Any:
+        """Execute a SQL statement."""
+        if self._db is None:
+            raise RuntimeError("Database not open. Call open() first.")
+        cursor = await self._db.execute(sql, params)
+        await self._db.commit()
+        return cursor
+
+    async def executemany(
+        self, sql: str, params_seq: list[tuple[Any, ...]]
+    ) -> None:
+        """Execute a SQL statement with multiple parameter sets."""
+        if self._db is None:
+            raise RuntimeError("Database not open. Call open() first.")
+        await self._db.executemany(sql, params_seq)
+        await self._db.commit()
+
+    async def fetchall(
+        self, sql: str, params: tuple[Any, ...] = ()
+    ) -> list[dict[str, Any]]:
+        """Execute a query and return all rows as dicts."""
+        if self._db is None:
+            raise RuntimeError("Database not open. Call open() first.")
+        cursor = await self._db.execute(sql, params)
+        rows = await cursor.fetchall()
+        columns = [desc[0] for desc in cursor.description]
+        return [dict(zip(columns, row)) for row in rows]
+
+    async def fetchone(
+        self, sql: str, params: tuple[Any, ...] = ()
+    ) -> dict[str, Any] | None:
+        """Execute a query and return the first row as a dict."""
+        if self._db is None:
+            raise RuntimeError("Database not open. Call open() first.")
+        cursor = await self._db.execute(sql, params)
+        row = await cursor.fetchone()
+        if row is None:
+            return None
+        columns = [desc[0] for desc in cursor.description]
+        return dict(zip(columns, row))
+
+    async def table_exists(self, table_name: str) -> bool:
+        """Check whether a table exists."""
+        result = await self.fetchone(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (table_name,),
+        )
+        return result is not None

loopengt/templates/__init__.py

@@ -0,0 +1 @@
+"""Template management package."""

loopengt/templates/builtins/handoff_loop/LOOPENGS.md

@@ -0,0 +1,10 @@
+# Handoff Loop Pattern
+
+## Purpose
+A sequential chain where each agent processes and hands off enriched
+context to the next agent in the pipeline.
+
+## When to Use
+- Multi-stage document processing pipelines
+- Data transformation chains
+- Any workflow where each stage enriches the previous output

loopengt/templates/builtins/planner_executor/LOOPENGS.md

@@ -0,0 +1,29 @@
+# Planner-Executor Pattern
+
+## Purpose
+A sequential two-agent pattern where a **Planner** analyses the goal and
+produces a structured action plan, then an **Executor** carries out each
+step of that plan.
+
+## When to Use
+- Tasks with clear decomposition into planning and execution phases
+- Code generation, refactoring, and migration tasks
+- Document drafting and editing workflows
+
+## Agents
+| Agent    | Role                                    |
+|----------|-----------------------------------------|
+| planner  | Analyses the goal, produces action plan |
+| executor | Executes each step of the plan          |
+
+## Steps
+1. **plan** — Planner analyses the goal and outputs a structured plan
+2. **execute** — Executor follows the plan step-by-step
+
+## Verification
+- Plan must contain at least one actionable step
+- Executor output must address all plan items
+
+## Risks
+- Planner may produce overly complex plans → mitigate with max_steps
+- Executor may deviate from plan → add plan-adherence verification gate

loopengt/templates/builtins/research_architect/LOOPENGS.md

@@ -0,0 +1,17 @@
+# Research-Architect Pattern
+
+## Purpose
+A three-phase workflow: **Research** gathers context, **Synthesiser**
+distils findings, and **Architect** produces a design based on synthesis.
+
+## When to Use
+- System design and architecture tasks
+- Technical specification writing
+- Literature review → analysis → recommendation workflows
+
+## Agents
+| Agent       | Role                                       |
+|-------------|--------------------------------------------|
+| researcher  | Deep research on the topic                 |
+| synthesiser | Distils research into key findings         |
+| architect   | Designs solution based on synthesis        |

loopengt/templates/builtins/reviewer_retry/LOOPENGS.md

@@ -0,0 +1,29 @@
+# Reviewer-Retry Pattern
+
+## Purpose
+An iterative loop where a **Worker** produces output, a **Reviewer**
+evaluates it, and the worker retries with feedback until the review passes.
+
+## When to Use
+- Code review workflows
+- Content quality assurance
+- Any task requiring iterative refinement based on feedback
+
+## Agents
+| Agent    | Role                                      |
+|----------|-------------------------------------------|
+| worker   | Produces initial output and revisions      |
+| reviewer | Evaluates output and provides feedback     |
+
+## Steps
+1. **produce** — Worker creates initial output
+2. **review** — Reviewer evaluates and provides feedback
+3. **revise** — Worker revises based on feedback (loops back to review)
+
+## Verification
+- Reviewer must provide explicit pass/fail verdict
+- Max 3 revision cycles to prevent infinite loops
+
+## Risks
+- Infinite revision loops → enforced by max_turns policy
+- Reviewer may be too strict → add quality_threshold stop condition

loopengt/templates/builtins/supervisor_workers/LOOPENGS.md

@@ -0,0 +1,29 @@
+# Supervisor-Workers Pattern
+
+## Purpose
+A **Supervisor** agent analyses the goal and delegates sub-tasks to
+specialised **Worker** agents, then aggregates results.
+
+## When to Use
+- Complex tasks requiring multiple specialisations
+- Parallel workstreams that need coordination
+- Tasks where different expertise is needed for different parts
+
+## Agents
+| Agent       | Role                                          |
+|-------------|-----------------------------------------------|
+| supervisor  | Decomposes goal, delegates, aggregates results|
+| researcher  | Gathers information and context               |
+| implementer | Writes code or produces artifacts             |
+| tester      | Validates and tests outputs                   |
+
+## Steps
+1. **decompose** — Supervisor analyses goal and creates sub-tasks
+2. **research** — Researcher gathers relevant context
+3. **implement** — Implementer produces the work product
+4. **test** — Tester validates the output
+5. **aggregate** — Supervisor combines and reviews all results
+
+## Verification
+- Each worker output must pass supervisor validation
+- Final aggregate must satisfy the original goal

loopengt/templates/loader.py

@@ -0,0 +1,38 @@
+"""Template loader — YAML to LoopSpec conversion."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from loopengt.core.models.loop_spec import LoopSpec
+
+
+class TemplateLoader:
+    """Loads loop templates from YAML files and converts to LoopSpec.
+
+    Usage::
+
+        loader = TemplateLoader()
+        spec = loader.load(Path("loop.yaml"))
+    """
+
+    def load(self, path: Path) -> LoopSpec:
+        """Load a loop.yaml and validate it as a LoopSpec."""
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        return LoopSpec.model_validate(raw)
+
+    def load_dict(self, data: dict[str, Any]) -> LoopSpec:
+        """Validate a dict as a LoopSpec."""
+        return LoopSpec.model_validate(data)
+
+    def dump(self, spec: LoopSpec, path: Path) -> None:
+        """Serialize a LoopSpec to YAML and write to a file."""
+        data = spec.model_dump(mode="json", exclude_none=True)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            yaml.dump(data, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )

loopengt/templates/registry.py

@@ -0,0 +1,85 @@
+"""Template discovery from built-ins and plugins."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+class BuiltinTemplateProvider:
+    """Provides built-in loop templates bundled with loopengt."""
+
+    TEMPLATE_NAMES = [
+        "planner_executor",
+        "reviewer_retry",
+        "supervisor_workers",
+        "research_architect",
+        "handoff_loop",
+    ]
+
+    def list_templates(self) -> list[dict[str, str]]:
+        """List available built-in templates."""
+        return [{"name": name, "source": "builtin"} for name in self.TEMPLATE_NAMES]
+
+    def get_template_path(self, name: str) -> Path | None:
+        """Get the path to a built-in template directory."""
+        try:
+            from importlib.resources import files
+
+            pkg = files("loopengt.templates.builtins").joinpath(name)  # type: ignore[union-attr]
+            return Path(str(pkg))
+        except Exception:
+            return None
+
+
+class TemplateRegistry:
+    """Registry that discovers templates from multiple sources.
+
+    Sources:
+    1. Built-in templates (loopengt.templates.builtins)
+    2. Project-local templates (.loopengt/templates/)
+    3. Plugin-provided templates (loopengt.templates entry point)
+    """
+
+    def __init__(self, local_dir: Path | None = None) -> None:
+        self._local_dir = local_dir or Path(".loopengt/templates")
+        self._builtin = BuiltinTemplateProvider()
+        self._log = logger.bind(component="template_registry")
+
+    def list_all(self) -> list[dict[str, str]]:
+        """List all available templates from all sources."""
+        templates = self._builtin.list_templates()
+
+        # Local templates
+        if self._local_dir.exists():
+            for entry in sorted(self._local_dir.iterdir()):
+                if entry.is_dir() and (entry / "loop.yaml").exists():
+                    if entry.name not in BuiltinTemplateProvider.TEMPLATE_NAMES:
+                        templates.append({
+                            "name": entry.name,
+                            "source": "local",
+                        })
+
+        return templates
+
+    def get_template(self, name: str) -> dict[str, Any] | None:
+        """Load a template's loop.yaml as a dict."""
+        import yaml
+
+        # Check local first
+        local_path = self._local_dir / name / "loop.yaml"
+        if local_path.exists():
+            return yaml.safe_load(local_path.read_text(encoding="utf-8"))  # type: ignore[no-any-return]
+
+        # Check built-ins
+        builtin_path = self._builtin.get_template_path(name)
+        if builtin_path:
+            yaml_path = builtin_path / "loop.yaml"
+            if yaml_path.exists():
+                return yaml.safe_load(yaml_path.read_text(encoding="utf-8"))  # type: ignore[no-any-return]
+
+        return None

loopengt-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: loopengt
+Version: 0.1.0
+Summary: Loop Engineering Agent — design, orchestrate, and evaluate agent loops
+Project-URL: Homepage, https://github.com/Sriramdayal/LOOPENGT
+Project-URL: Documentation, https://github.com/Sriramdayal/LOOPENGT/tree/main/docs
+Project-URL: Repository, https://github.com/Sriramdayal/LOOPENGT
+Project-URL: Issues, https://github.com/Sriramdayal/LOOPENGT/issues
+Author: Loop Engineering Contributors
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: agent,ai,loop,mcp,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: anyio>=4.0
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: structlog>=23.0
+Requires-Dist: typer>=0.9
+Provides-Extra: all
+Requires-Dist: fastmcp>=0.1; extra == 'all'
+Requires-Dist: httpx>=0.25; extra == 'all'
+Requires-Dist: mcp>=1.0; extra == 'all'
+Requires-Dist: mypy>=1.8; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
+Requires-Dist: pytest-cov>=4.0; extra == 'all'
+Requires-Dist: pytest>=7.0; extra == 'all'
+Requires-Dist: ruff>=0.4; extra == 'all'
+Requires-Dist: types-aiofiles>=23.0; extra == 'all'
+Requires-Dist: types-pyyaml>=6.0; extra == 'all'
+Provides-Extra: antigravity
+Provides-Extra: claude-code
+Provides-Extra: codex
+Provides-Extra: cursor
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-aiofiles>=23.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: httpx>=0.25; extra == 'llm'
+Requires-Dist: openai>=1.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1; extra == 'mcp'
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# LOOPENGT — Loop Engineering Agent
+
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+**Design, orchestrate, and evaluate agent loops** — a framework for building
+production-grade multi-agent workflows with MCP integration and IDE-agnostic
+plugin architecture.
+
+## Features
+
+- 🔄 **5 orchestration patterns** — sequential, supervisor-worker, parallel
+  fan-out, handoff, evaluator-optimizer
+- 🧩 **Plugin architecture** — extend with custom adapters, tools, templates. Includes built-in plugins for **Cursor, Claude Code, Antigravity, and Codex**.
+- 🧠 **Native LLM Integration** — Built-in support for OpenAI and Hugging Face Inference Endpoints for autonomous loop orchestration.
+- 🔌 **MCP server** — expose loop tools to Cursor, Claude Code, Antigravity
+- 📊 **Built-in tracing** — SQLite + JSONL traces with OpenTelemetry export
+- 🧪 **Evaluation framework** — built-in metrics + LLM-as-judge
+- 📝 **5 built-in templates** — planner-executor, reviewer-retry,
+  supervisor-workers, research-architect, handoff loop
+- ⚡ **Async-first** — built on anyio for concurrent execution
+
+## Quick Start
+
+```bash
+# Create and activate a virtual environment
+uv venv
+.venv\Scripts\activate  # On Windows
+# source .venv/bin/activate  # On macOS/Linux
+
+# Install the base package
+uv pip install loopengt
+
+# With MCP support
+uv pip install "loopengt[mcp]"
+
+# With everything
+uv pip install "loopengt[all]"
+```
+
+### Initialize
+
+```bash
+loopengt init
+```
+
+Creates a `.loopengt/` directory with configuration, templates, and prompts.
+
+### Design a Loop
+
+```bash
+loopengt design "code review loop with automated testing"
+```
+
+Generates `loop.yaml` and `LOOP_DESIGN.md`.
+
+### Execute
+
+```bash
+loopengt run loop.yaml
+```
+
+### Inspect Traces
+
+```bash
+loopengt trace <run_id>
+```
+
+### Evaluate
+
+```bash
+loopengt eval <run_id>
+```
+
+## How to Engineer a Loop (Step-by-Step Guide)
+
+Building an autonomous agent loop with LOOPENGT involves designing the architecture, defining the agents, and orchestrating their workflow. Here is the recommended workflow for engineering a new loop from scratch:
+
+### Step 1: Initialize Your Workspace
+First, set up the necessary project configurations by running:
+```bash
+loopengt init
+```
+This scaffolds a `.loopengt/` directory in your project containing configuration files, built-in templates, and prompts.
+
+### Step 2: Set Your LLM Provider
+Ensure your environment is configured for the LLM that will both design and run your agents. For example, to use OpenAI:
+```bash
+export OPENAI_API_KEY="your-api-key"
+export LOOPENGT_LLM_PROVIDER="openai"
+```
+
+### Step 3: Design the Loop
+Instead of writing the YAML specification manually, use the built-in AI Architect to design the loop for you. Provide a clear goal:
+```bash
+loopengt design "create a content generation loop where a Researcher finds facts, a Writer drafts an article, and an Editor reviews it for quality."
+```
+The architect will generate two files:
+- **`LOOP_DESIGN.md`**: A human-readable breakdown of the agents, their roles, and the orchestration strategy.
+- **`loop.yaml`**: The executable Pydantic-serializable configuration file.
+
+### Step 4: Refine the Configuration (Optional)
+Open `loop.yaml` in your editor. You can manually tweak:
+- **Agents**: Adjust system prompts, input/output schemas, or LLM settings.
+- **Tools**: Add native functions or MCP integrations.
+- **Policies**: Set retry limits, turn budgets, or verification gates.
+
+### Step 5: Execute the Loop
+Run the orchestrator using your generated specification:
+```bash
+loopengt run loop.yaml
+```
+Watch the terminal as the Executor coordinates the agents (Researcher -> Writer -> Editor) based on the chosen pattern (e.g., sequential or supervisor-worker).
+
+### Step 6: Trace and Evaluate
+Once the run completes, inspect the detailed execution trace to debug or review agent interactions:
+```bash
+# List recent runs to find the ID
+ls .loopengt/runs/
+
+# Inspect the trace
+loopengt trace <run_id>
+```
+If you want to score the quality of the final output, run the evaluator:
+```bash
+loopengt eval <run_id>
+```
+
+## Architecture
+
+```
+CLI / IDE Adapters → MCP Server → Plugin System → Core Runtime → Models
+                                                        ↓
+                                              Tracing & Memory → Storage
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
+
+## Orchestration Patterns
+
+| Pattern | Description | Use Case |
+|---------|-------------|----------|
+| `sequential` | Steps execute in order | Simple workflows |
+| `supervisor_worker` | Supervisor delegates to workers | Complex tasks |
+| `parallel_fan_out` | Independent steps run concurrently | Batch processing |
+| `handoff` | Agents pass enriched context along | Pipelines |
+| `evaluator_optimizer` | Iterative quality improvement | Code review |
+
+## MCP Integration
+
+Start the MCP server:
+
+```bash
+loopengt mcp --transport stdio
+```
+
+Add to Cursor (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "loopengt": {
+      "command": "loopengt",
+      "args": ["mcp", "--transport", "stdio"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `loopengt init` | Scaffold .loopengt/ project directory |
+| `loopengt design "goal"` | Design a loop from a goal |
+| `loopengt run <spec>` | Execute a loop spec |
+| `loopengt trace <id>` | Inspect execution trace |
+| `loopengt eval <id>` | Run evaluations |
+| `loopengt template list` | List available templates |
+| `loopengt doctor` | Diagnose configuration |
+| `loopengt mcp` | Start MCP server |
+
+## Development
+
+```bash
+git clone https://github.com/Sriramdayal/LOOPENGT.git
+cd LOOPENGT
+uv pip install -e ".[dev]"
+
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/loopengt/
+
+# Test
+pytest tests/ -v
+```
+
+## Plugin Development
+
+See [docs/plugin_dev.md](docs/plugin_dev.md) for the plugin development guide.
+
+## Examples
+
+Check out the `examples/` directory for programmatic usage:
+- `examples/basic_loop.py` — A simple sequential loop setup.
+- `examples/multi_agent_loop.py` — A complex Supervisor-Worker multi-agent orchestration.
+
+## License
+
+[GPL-3.0](LICENSE)