Metadata-Version: 2.5
Name: failecho-autoreport
Version: 0.1.5
Summary: Report the shape of your agent's tool failures automatically -- no model in the loop, no dependencies, never raises, never blocks.
Project-URL: Homepage, https://failecho.com
Project-URL: Documentation, https://failecho.com/setup
Project-URL: Source, https://github.com/FailEcho/failecho
License: MIT
Keywords: agents,langchain,llamaindex,mcp,observability,reliability,retries
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# failecho-autoreport

Automatic failure reporting for agents that are not Claude Code.

Claude Code reports tool failures through a hook that fires after every call,
with no model deciding anything. Everywhere else -- LangChain, LlamaIndex, a
cron job, a local model driving a scraper -- reporting depends on the model
choosing to call a tool, and a small model reliably will not. This removes the
decision: wrap the call site once.

```python
from failecho_autoreport import FailEcho

fe = FailEcho()

tools = fe.wrap(tools, service="github-mcp")          # a framework's tool list

@fe.watch(service="api.github.com", operation="create_issue")
def create_issue(title):                              # or one call site
    ...

fe.recovered("api.github.com", "create_issue", "refresh_schema")  # what fixed it
```

What it sends is a failure's *shape*: service, operation, a short error
class, an HTTP-ish code when there is one, and duration. Never arguments,
never return values, never the prompt, never a credential. Error text is off
unless `FAILECHO_SEND_ERRORS=1`.

Three properties it has, each with a test rather than a promise:

- **Never raises.** A reporting bug cannot become your application's exception.
- **Never blocks.** Reports go to a worker thread; an unreachable FailEcho costs
  the caller about 3 ms, not a timeout. (Advice, below, is the opt-in exception.)
- **Never changes behaviour.** Returns and re-raises exactly what your code did.

## Advice for the agent that failed (opt-in)

Reporting helps the next agent. With `advise=True` (or `FAILECHO_ADVISE=1`),
a failure in a watched call is also followed by one read of the network --
`/v1/query`, which stores nothing -- and the answer is attached to the
exception before it goes on up:

```python
fe = FailEcho(advise=True)

try:
    create_issue("...")
except Exception as exc:
    exc.failecho          # the network's answer, a dict, or None
    fe.advice_text(exc)   # one line, e.g. "FailEcho: try <action>, worked n/m ..."
```

Put that line in the tool error your model sees and the model has the
evidence when it decides whether to retry, without having to think of
asking. Nothing is acted on for you; the exception's type and message are
unchanged (on Python 3.11+ the line is also added as a note). The read waits
at most 3 seconds, on failures only -- the one place this package waits,
which is why it is off by default.

The `recovered()` line is the one worth bothering with. Failures alone give
the network a failure *rate*; only an outcome records what fixed it, which is
the half another agent can act on. It cannot be inferred, so it stays one
explicit call.

Zero dependencies. `FAILECHO_DISABLED=1` turns it off. Point `endpoint=` at
your own server to send nothing to anyone else. The network at failecho.com
is public and, as of this release, has no independent reporters yet -- the
front page says so. Works on
your own history alone from five recoveries.

MIT. Source: https://github.com/FailEcho/failecho
