Metadata-Version: 2.4
Name: reloop-ai
Version: 0.1.0
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: all
Requires-Dist: reloop[blaxel,context-surfaces,dev]; extra == 'all'
Provides-Extra: blaxel
Requires-Dist: blaxel>=0.2.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'
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)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
[![GitHub stars](https://img.shields.io/github/stars/nihalnihalani/wordware-hackathon-apr11?style=social)](https://github.com/nihalnihalani/wordware-hackathon-apr11)

---

## 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

```bash
pip install reloop
reloop init
reloop demo
```

---

## 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 (Claude Code / Cursor)

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

---

## How It Works

The REJD Loop: **Retrieve -> Execute -> Judge -> Distill**

```mermaid
flowchart TD
    A([New Task]) --> R[Retrieve\nQuery Redis for similar past failures]
    R --> E[Execute\nRun in Blaxel sandbox]
    E --> J{Judge\nSuccess or failure?}

    J -- Success --> D_OK[Distill Success\nStore solution + learnings]
    D_OK --> DONE([Task Complete])

    J -- Failure --> D_FAIL[Distill Failure\nCapture root cause, fix, confidence]
    D_FAIL --> CB{Circuit breaker\nor budget exceeded?}
    CB -- Yes --> ABANDON([Task Abandoned])
    CB -- No --> R
```

Powered by:
- **OpenAI Agents SDK** -- orchestrates the REJD loop with handoffs between specialist agents
- **Redis** -- 3-tier failure memory (working, long-term, episodic)
- **Blaxel** -- Firecracker sandbox with 25ms checkpoint/restore

---

## 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 |

---

## Architecture

```text
+-------------------+     +-------------------+     +-------------------+
|  OpenAI Agents    |     |  Redis Agent      |     |  Blaxel           |
|  SDK              |     |  Memory Server    |     |  Firecracker VMs  |
|                   |     |                   |     |                   |
|  Orchestrates the |     |  3-tier memory:   |     |  Perpetual state  |
|  REJD loop with   |<--->|  - Working        |     |  25ms resume      |
|  specialist agent |     |  - Long-term      |<--->|  Checkpoint/       |
|  handoffs         |     |  - Episodic       |     |  restore          |
+-------------------+     +-------------------+     +-------------------+
         |                         |                         |
         v                         v                         v
+---------------------------------------------------------------+
|                     FastAPI + SSE                              |
|  Task management, memory search, checkpoints, streaming       |
+---------------------------------------------------------------+
         |
         v
+---------------------------------------------------------------+
|               Next.js Dashboard                               |
|  Timeline UI, failure sidebar, live output, cost tracker      |
+---------------------------------------------------------------+
```

| 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.
