Metadata-Version: 2.4
Name: reloop-ai
Version: 0.3.2
Summary: Failure memory for AI agents — self-healing retry with structured learning
Project-URL: Homepage, https://github.com/nihalnihalani/wordware-hackathon-apr11
Project-URL: Documentation, https://github.com/nihalnihalani/wordware-hackathon-apr11#readme
Project-URL: Repository, https://github.com/nihalnihalani/wordware-hackathon-apr11
Project-URL: Issues, https://github.com/nihalnihalani/wordware-hackathon-apr11/issues
Author: Nihal Nihalani
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,failure-memory,mcp,retry,self-healing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: redis>=5.2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sse-starlette>=2.2.0
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.34.0
Provides-Extra: agents
Requires-Dist: openai-agents>=0.7.0; extra == 'agents'
Provides-Extra: all
Requires-Dist: reloop[agents,blaxel,context-surfaces,dev,local-embeddings,mcp,redis-extra]; extra == 'all'
Provides-Extra: blaxel
Requires-Dist: blaxel>=0.2.0; extra == 'blaxel'
Requires-Dist: websockets<16,>=13.0; extra == 'blaxel'
Provides-Extra: context-surfaces
Requires-Dist: context-surfaces>=0.0.2; extra == 'context-surfaces'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: local-embeddings
Requires-Dist: scikit-learn>=1.4; extra == 'local-embeddings'
Requires-Dist: sentence-transformers>=2.0; extra == 'local-embeddings'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: redis-extra
Requires-Dist: redisvl>=0.4.0; extra == 'redis-extra'
Description-Content-Type: text/markdown

# ReLoop

**Failure memory for AI agents.**

Every agent fails. ReLoop is the first framework that gets smarter from failure.

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/reloop-ai.svg)](https://pypi.org/project/reloop-ai/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)

---

## The Problem

AI agents retry blindly -- same mistake, same failure, burning tokens and money.
No framework treats failure as data. They either retry with no memory, or give up.

## The Solution

ReLoop captures every failure into a structured memory graph -- error type, root cause,
suggested fix, confidence score, semantic embedding -- so the next retry starts smarter.
Your agents don't just recover. They get permanently smarter.

---

## Quick Start

The `reloop-ai` package is officially published and ready for production use.

```bash
pip install reloop-ai
reloop init
reloop demo
```

## Minimal Setup (No Redis Required)

ReLoop works out of the box with SQLite -- no Redis or Blaxel needed:

```bash
pip install reloop-ai
export OPENAI_API_KEY=sk-...
reloop serve
```

Redis and Blaxel are optional -- add them when you need production performance.
For local development, ReLoop uses Docker or runs commands directly as the sandbox.

---

## Three Ways to Use ReLoop

### 1. As a Library (any agent, 3 lines)

```python
from reloop import FailureMemory

memory = FailureMemory(redis_url="redis://localhost:6379")
similar = await memory.search("ImportError sharp")  # Returns past failures + fixes
```

### 2. As a Framework (full self-healing loop)

```bash
reloop run "Fix and deploy the Next.js project at ./my-broken-app"
```

### 3. As an MCP Server (Cursor & Claude Code)

Integrate ReLoop directly into your AI IDEs so they become self-healing. When the MCP server is connected, Claude can:

- **Search Memory:** Semantically search past errors across your team's history.
- **Fetch Checkpoints:** Restore exact state from past Blaxel Firecracker VM checkpoints.
- **Execute Safely:** Run isolated code tests within Blaxel sandboxes directly from the editor.

Add to your `claude_desktop_config.json` or Cursor settings:

```json
{
  "mcpServers": {
    "reloop": {
      "command": "python",
      "args": ["-m", "reloop.mcp_server"]
    }
  }
}
```

---

## Architecture

```
┌─────────────────────┐   MCP Protocol    ┌──────────────────────┐
│  Cursor / Claude    │ ───────────────►  │  ReLoop MCP Server   │
└─────────────────────┘                   └──────────┬───────────┘
                                                     │
                               ┌─────────────────────┴──────────────────────┐
                               │                                             │
                               ▼  Vector Search                              ▼  Isolated Execution
                    ┌──────────────────────┐                    ┌──────────────────────┐
                    │  Redis Agent Memory  │                    │  Blaxel Firecracker  │
                    └──────────┬───────────┘                    └──────────┬───────────┘
                               │ stores                                    │ 25ms resume
                               ▼                                           ▼
                    ┌──────────────────────┐                    ┌──────────────────────┐
                    │  Failure Embeddings  │                    │   State Checkpoints  │
                    └──────────────────────┘                    └──────────────────────┘
```

### Redis: The Memory Backbone

ReLoop utilizes Redis as the core of its Agent Memory Server. The architecture consists of a 3-tier memory system:

1. **Working Memory:** Stores the current task's session state and immediate context.
2. **Long-term Memory:** A persistent failure graph using Redis Vector Search to semantically match current errors with past distilled solutions.
3. **Episodic Memory:** Full execution traces and timeline records for auditing and the dashboard UI.

### Blaxel: Perpetual Execution Sandboxes

For safe, deterministic task execution, ReLoop integrates Blaxel's Firecracker microVMs.

- **Perpetual State:** The sandbox is never lost. You can pause and resume the exact environment.
- **25ms Checkpoint/Restore:** ReLoop creates instantaneous checkpoints after every step.
- **Time-Travel Rewinds:** Hit a roadblock? Rewind the agent to a previous checkpoint in 25ms and try a different fix strategy.

### The REJD Loop

The core algorithm: **Retrieve -> Execute -> Judge -> Distill**

```
                           ┌─────────────┐
                           │  New Task   │
                           └──────┬──────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │           Retrieve           │
                    │  Query Redis for similar     │
                    │      past failures           │
                    └──────────────┬──────────────┘
                                   │
                                   ▼
                    ┌─────────────────────────────┐
                    │           Execute            │
                    │    Run in Blaxel sandbox     │
                    └──────────────┬──────────────┘
                                   │
                                   ▼
                    ┌─────────────────────────────┐
                    │            Judge             │
                    │     Success or failure?      │
                    └──────┬──────────────┬────────┘
                           │              │
                        Success        Failure
                           │              │
                           ▼              ▼
              ┌────────────────┐  ┌───────────────────────┐
              │ Distill        │  │ Distill Failure        │
              │ Success        │  │ root cause, fix,       │
              │ Store solution │  │ confidence score       │
              └───────┬────────┘  └──────────┬────────────┘
                      │                       │
                      ▼                       ▼
              ┌────────────────┐  ┌───────────────────────┐
              │ Task Complete  │  │  Circuit breaker or    │
              └────────────────┘  │   budget exceeded?    │
                                  └──────┬──────────┬──────┘
                                         │          │
                                        Yes         No
                                         │          │
                                         ▼          └──► Retrieve ↑
                                ┌─────────────────┐
                                │ Task Abandoned  │
                                └─────────────────┘
```

Powered by:

- **OpenAI Agents SDK** -- orchestrates the REJD loop with handoffs between specialist agents
- **Redis** -- 3-tier failure memory (working, long-term, episodic) via Agent Memory Server
- **Blaxel** -- Firecracker sandbox with 25ms checkpoint/restore (optional; Docker or direct execution for local dev)

---

## Timeline UI

The non-chat interface that makes failure learning visible.

A horizontal timeline of colored nodes tells the full story at a glance:

**RED** (failed) -> **RED** (failed) -> **RED** (failed) -> **GREEN** (succeeded)

Click any node to inspect the full failure record -- root cause, suggested fix,
confidence score, cost, and the exact code diff that resolved it.

---

## Integrations

Works with any agent framework:

- OpenAI Agents SDK
- LangGraph
- CrewAI
- Claude Agent SDK
- Raw Python

ReLoop is the memory layer -- bring your own orchestration.

---

## A/B: Memory vs No Memory

| Metric                 | Without Memory | With Memory |
| ---------------------- | -------------- | ----------- |
| Attempts to fix 4 bugs | 12+            | 4           |
| Total cost             | $0.47          | $0.18       |
| Same mistake repeated  | 3x             | 0x          |

---

## API Reference

Full API reference: [`docs/api-reference.md`](docs/api-reference.md)

| Method | Path                                       | Description                                 |
| ------ | ------------------------------------------ | ------------------------------------------- |
| `POST` | `/v1/tasks`                                | Create and run a task                       |
| `GET`  | `/v1/tasks/{id}`                           | Get task status and result                  |
| `GET`  | `/v1/tasks/{id}/timeline`                  | Full execution timeline                     |
| `GET`  | `/v1/tasks/{id}/sse`                       | Server-Sent Events stream                   |
| `POST` | `/v1/memories/search`                      | Semantic search over failure memory         |
| `GET`  | `/v1/memories/stats`                       | Aggregated memory statistics                |
| `GET`  | `/v1/tasks/{id}/checkpoints`               | List sandbox checkpoints                    |
| `POST` | `/v1/tasks/{id}/checkpoints/{cid}/restore` | Rewind to checkpoint                        |
| `POST` | `/v1/tasks/ab-comparison`                  | Run A/B comparison (with vs without memory) |
| `GET`  | `/v1/tasks/{id}/circuit-breaker`           | Get circuit breaker state for a task        |
| `POST` | `/v1/memories/predict`                     | Predict failure likelihood for new code     |
| `GET`  | `/v1/memories/export`                      | Export failure memory as JSON               |

---

## Configuration

ReLoop is configured via environment variables. Only `OPENAI_API_KEY` is required -- everything else has sensible defaults.

| Variable                    | Required | Default                  | Description                                      |
| --------------------------- | -------- | ------------------------ | ------------------------------------------------ |
| `OPENAI_API_KEY`            | **Yes**  | --                       | OpenAI API key for code generation and reasoning |
| `REDIS_URL`                 | No       | `redis://localhost:6379` | Redis connection URL (falls back to SQLite)      |
| `REDIS_MEMORY_INDEX`        | No       | `reloop-failures`        | Vector index name for failure embeddings         |
| `BLAXEL_API_KEY`            | No       | --                       | Blaxel API key for Firecracker sandboxes         |
| `BLAXEL_WORKSPACE`          | No       | --                       | Blaxel workspace name                            |
| `CODEX_MODEL`               | No       | `gpt-4o`                 | Chat model for planner/distiller                 |
| `REASONING_MODEL`           | No       | `o1`                     | Deep reasoning model for root cause analysis     |
| `FAST_MODEL`                | No       | `gpt-4o-mini`            | Fast/cheap model for classification              |
| `EMBEDDING_MODEL`           | No       | `text-embedding-3-small` | Model for failure memory embeddings              |
| `API_PORT`                  | No       | `8000`                   | FastAPI server port                              |
| `API_HOST`                  | No       | `0.0.0.0`                | API host                                         |
| `NEXT_PUBLIC_API_URL`       | No       | `http://localhost:8000`  | Backend API URL for frontend                     |
| `MAX_RETRIES`               | No       | `5`                      | Maximum retry attempts per task                  |
| `MAX_BUDGET_USD`            | No       | `1.00`                   | Maximum cost budget per task                     |
| `CIRCUIT_BREAKER_THRESHOLD` | No       | `3`                      | Consecutive failures before circuit break        |

See [`.env.example`](.env.example) for a copy-paste template.

---

| Layer             | Technology                     | Role                                                             |
| ----------------- | ------------------------------ | ---------------------------------------------------------------- |
| Orchestration     | OpenAI Agents SDK              | REJD loop with specialist agent handoffs                         |
| Failure Memory    | Redis Agent Memory Server      | 3-tier: working memory, long-term failure graph, episodic traces |
| Execution Sandbox | Blaxel Firecracker microVMs    | Perpetual state, 25ms resume, checkpoint/restore                 |
| API               | FastAPI + SSE                  | Task management, memory search, real-time streaming              |
| Dashboard         | Next.js + Tailwind + shadcn/ui | Timeline, failure sidebar, cost tracker                          |

---

## Contributing

We welcome contributions. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for:

- Development environment setup
- Code style requirements (ruff, mypy)
- PR process and review checklist
- Architecture overview for new contributors

---

## License

Apache 2.0 -- see [`LICENSE`](LICENSE) for the full text.
