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)
