Metadata-Version: 2.5
Name: failstep
Version: 0.1.0
Summary: A local CLI that diagnoses why one AI agent run failed.
Project-URL: Homepage, https://github.com/AbdelazizBs/failstep
Project-URL: Repository, https://github.com/AbdelazizBs/failstep
Project-URL: Issues, https://github.com/AbdelazizBs/failstep/issues
Project-URL: Changelog, https://github.com/AbdelazizBs/failstep/blob/master/CHANGELOG.md
Author: failstep contributors
License: MIT License
        
        Copyright (c) 2026 failstep contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,cli,debug,llm,trace
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: llm
Requires-Dist: httpx>=0.27; extra == 'llm'
Description-Content-Type: text/markdown

# failstep

A local CLI that diagnoses **why one AI agent run failed**.

Not a dashboard. Not an eval suite. Not a coding-agent linter. Not an LLM wrapper.

```text
pip install failstep
failstep diagnose examples/traces/retry-loop.json
```

No API key. No network. A root cause, quoted evidence, and what to change.

Repo: [github.com/AbdelazizBs/failstep](https://github.com/AbdelazizBs/failstep)

[![CI](https://github.com/AbdelazizBs/failstep/actions/workflows/ci.yml/badge.svg)](https://github.com/AbdelazizBs/failstep/actions/workflows/ci.yml)

`inspect` prints the run. `diagnose` names the failed step. `compare` counts diffs. `fix` prints the recommendation.

## 60 seconds

From a clone (Python 3.11+):

```text
pip install -e ".[dev]"
python -m failstep diagnose examples/traces/retry-loop.json
```

```text
failstep 0.1.0
file         examples/traces/retry-loop.json
run          checkout-agent
status       failed
duration     14820 ms
steps        8

root cause
  FS004  retry loop
  steps  3-5  search_docs

evidence
  identical calls  3
  tool             search_docs
  args             {"query": "refund policy"}
  outputs          unchanged

recommendation
  Cap identical tool retries at 1. Return the first error to the model.

secondary
  none
```

Exit `1` when there is a finding (`--fail-on error`, the default). A clean run exits `0`. Garbage input exits `2`. It never prints healthy.

If `failstep` is not on PATH:

```text
python -m failstep diagnose examples/traces/retry-loop.json
python -m failstep inspect examples/traces/retry-loop.json
python -m failstep version
```

```text
failstep inspect TRACE [--format terminal|json|markdown]
failstep diagnose TRACE [--format terminal|json|markdown] [--fail-on error|warning] [--no-llm] [--no-redact]
failstep compare OLD NEW [--format terminal|json|markdown]
failstep fix TRACE [--format terminal|json|markdown]
failstep version
```

Native JSON and JSONL. Also OpenAI `messages` + `tool_calls`, LangChain `intermediate_steps`, and exported OpenTelemetry GenAI JSON (`resourceSpans` or `{spans: [...]}`). Contract: [docs/TRACE_FORMAT.md](docs/TRACE_FORMAT.md).
How the report must look: [docs/OUTPUT.md](docs/OUTPUT.md).

Detectors: FS001 malformed output, FS002 tool schema, FS003 tool failure, FS004 retry loop, FS005 timeout, FS006 empty retrieval, FS007 duplicate chunks, FS008 conflicting sources. Optional leftover (`FS000`) only if `FAILSTEP_LLM_URL` is set, httpx is installed (`pip install failstep[llm]`), and no error finding exists. `--no-llm` skips it. Secrets are redacted before the request.

## Tests

```text
python -m pytest
python -m ruff check .
```

If you use uv: `uv sync --extra dev` then `uv run pytest` / `uv run ruff check .`.

## Design

| Doc | What it is |
|---|---|
| [docs/PRODUCT.md](docs/PRODUCT.md) | What we ship, the +, quality bar |
| [docs/POSITIONING.md](docs/POSITIONING.md) | Exact difference vs lookalikes |
| [docs/STACK.md](docs/STACK.md) | Free open-source stack |
| [docs/OUTPUT.md](docs/OUTPUT.md) | How the diagnosis looks (terminal / JSON / markdown) |
| [docs/TESTING.md](docs/TESTING.md) | How each phase is proven |
| [docs/PHASES.md](docs/PHASES.md) | Build order. Do not skip. |
| [docs/TRACE_FORMAT.md](docs/TRACE_FORMAT.md) | Native trace contract |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Modules and pipeline |
| [docs/COMPETITORS.md](docs/COMPETITORS.md) | Market scan |
| [docs/DECISIONS.md](docs/DECISIONS.md) | Locked decisions |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup, tests, pull requests |
| [CHANGELOG.md](CHANGELOG.md) | Shipped versions |

## License

MIT. See [LICENSE](LICENSE).
