Metadata-Version: 2.4
Name: myles-ai
Version: 0.1.0
Summary: The circuit breaker for AI agents — stop runaway loops and budget blowouts before they burn money.
Author: Myles
License: Apache-2.0
Project-URL: Homepage, https://github.com/ElamOlame31/myles
Project-URL: Issues, https://github.com/ElamOlame31/myles/issues
Keywords: ai,agents,llm,cost,budget,circuit-breaker,proxy,openai,anthropic
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Myles — the circuit breaker for AI agents

**Stop your agent bankrupting you overnight.** A zero-config local proxy that catches runaway
loops and budget blowouts *before* they burn money — any agent, any language, any provider, no
code changes.

```bash
pip install myles-ai
myles demo            # see it work in 15s (no API key)
myles run             # start watching your agents (observe-only, safe)
```

![Myles catching a runaway loop and saving money](https://raw.githubusercontent.com/ElamOlame31/Myles/main/assets/demo.gif)
<!-- generate this GIF with `vhs assets/demo.tape` — see assets/RECORDING.md -->

---

## The problem

Autonomous agents get stuck — a broken tool retried thousands of times, a reflection loop that
never converges, dozens of parallel sessions grinding the same impossible lookup. Developers wake
up to **$2k-in-4-hours** and **$8k-overnight** bills. Platform daily caps kick in *after* the
runway is gone. ([real](https://news.ycombinator.com/item?id=48491670)
[stories](https://news.ycombinator.com/item?id=45914307).)

Myles sits in the request path and **stops the bleed in real time.**

## See the value in 15 seconds

```bash
myles demo
```
```
  call  5  forwarded  $0.0153   <-- MYLES: runaway loop detected!
  call  6  BLOCKED    $0.0000   (Myles refused — would have cost $0.0153)
  ...
  SAVED : $0.1530 on this ONE loop
```

## Try it on your own agent (safe — observe-only)

```bash
myles run                                   # observe mode: logs, never blocks
export ANTHROPIC_BASE_URL=http://localhost:8788   # Claude Code
# ...use your agent normally...
myles report                                # what it WOULD have stopped + saved
```

When you trust it, flip on enforcement:
```bash
myles run --enforce --budget 5.00           # now it actually blocks
```

## What it stops

| Problem | How Myles catches it |
|---|---|
| **Runaway loop** | Semantic novelty detection — flags calls that stop carrying new information, even when the agent *rephrases* the same failing request or spreads it across tools. |
| **Budget blowout** | Real-dollar metering from actual token usage + a hard cap. Blocked calls never reach the provider — they cost **$0**. |
| **Fan-out** | Cross-run detection: the same doomed intent across many concurrent sessions, contained fleet-wide — something per-process tools can't do. |

Not a compressor. Not a router. Not a dashboard. A **wire-level kill switch** that refuses the bad
call mid-flight and shows you what it saved.

## Why it works (30s)

The detector measures **information novelty** per step: a healthy loop keeps exploring new state; a
runaway collapses to near-zero novelty while still spending. Similarity is **IDF-weighted** (learns
your boilerplate, so `read file src` is ignored and the real intent decides) and **response-aware**
(only a proxy sees responses — that's what separates a *refining* loop from a *stuck* one). Built
and validated with an open probe — see [`probe/FINDINGS.md`](probe/FINDINGS.md).

## Install

```bash
pip install myles-ai   # zero dependencies, stdlib only, Python 3.9+ · provides the `myles` command
```
Or run from source: `python -m myles run`.

## Status

**v0.1 — early MVP, seeking feedback.** Enforcement validated end-to-end. Honest limits:
- **Observe-only by default** on purpose — try it with zero risk, then `--enforce`.
- **Cross-run** uses a coarse intent key; can be sensitive on common short intents (tuning next).
- **Streaming** is buffered (fine for coding-agent sizes); true pass-through is a later optimization.

Issues and PRs welcome. Apache-2.0.

## Let's connect

I'm building Myles in the open and I'd genuinely love to hear from you — whether it's
feedback on the idea, a bug, a horror story of your own agent going rogue, or you just
want to talk about the project. Reach out:

- **LinkedIn:** https://www.linkedin.com/in/elam-olame-mugabo/
- **Website:** https://elamolamemugabo.com/

— Elam Olame Mugabo

---
*Built for people who ship agents and hate surprise bills.*
