failstep 0.1.0__tar.gz

failstep-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+* text=auto
+
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.jsonl text eol=lf
+*.txt text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+.gitignore text eol=lf
+LICENSE text eol=lf

failstep-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,48 @@
+name: Bug
+description: A command printed the wrong finding, crashed, or accepted garbage.
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: failstep version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command
+      description: Exact command, including flags.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual
+      description: Paste stdout. Redact secrets.
+    validations:
+      required: true
+  - type: textarea
+    id: fixture
+    attributes:
+      label: Trace
+      description: Minimal JSON, or a path under examples/traces or tests/traces. Redact secrets. Do not paste API keys.
+      render: json
+  - type: input
+    id: python
+    attributes:
+      label: Python
+      placeholder: "3.12.0"
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: Windows 11 / Ubuntu 24.04

failstep-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

failstep-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## Change
+
+## Proof
+
+- [ ] `python -m pytest`
+- [ ] `python -m ruff check .`
+- [ ] Detector changes stay silent on `examples/traces/success.json`
+- [ ] Goldens updated in this PR if output changed
+- [ ] No `confidence`, no invented `$`

failstep-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Ruff
+        run: python -m ruff check .
+      - name: Pytest
+        run: python -m pytest
+
+  package:
+    name: sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build

failstep-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

failstep-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python
+.venv/
+venv/
+env/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+dist/
+build/
+wheels/
+pip-wheel-metadata/
+
+# Test / lint / type / coverage
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.hypothesis/
+.cache/
+
+# uv (lock is optional for a library CLI; pyproject is the source of truth)
+.uv/
+uv.lock
+
+# Env / secrets — never publish
+.env
+
+.env.*
+!.env.example
+*.pem
+*.key
+
+# OS
+.DS_Store
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+*.orig
+
+# Local leftovers — never publish
+MOVED.md
+_chatgpt_share*
+*.tmp
+*.temp
+~$*
+
+# Jupyter
+.ipynb_checkpoints/

failstep-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- `inspect`, `diagnose`, `compare`, `fix`, `version`
+- Detectors FS001–FS008 (malformed, schema, tool failure, retry, timeout, empty retrieval, duplicate chunks, conflicting sources)
+- Native JSON/JSONL, OpenAI messages, LangChain `intermediate_steps`, exported OpenTelemetry GenAI JSON
+- Optional leftover LLM (`FS000`) only when `FAILSTEP_LLM_URL` is set and no error finding exists
+- `compare` counts finding-id and run-field diffs
+- `fix` prints the recommendation as a patch and does not write files
+- Exit codes 0/1/2/3

failstep-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Setup
+
+Python 3.11 or newer.
+
+```text
+pip install -e ".[dev]"
+```
+
+`uv sync --extra dev` is optional.
+
+## Checks
+
+```text
+python -m pytest
+python -m ruff check .
+```
+
+Run those before every pull request.
+
+## Pull requests
+
+- One change. Update goldens in the same PR if output changed.
+- A detector must fire on a fixture, stay silent on `examples/traces/success.json`, and copy evidence from the file.
+- Do not add `confidence`, cost, or health scores.
+- Do not call a real LLM in tests.
+- Unknown trace shape is exit 2, never a silent empty run.
+
+Trace contract: `docs/TRACE_FORMAT.md`.
+Report contract: `docs/OUTPUT.md`.
+Test contract: `docs/TESTING.md`.
+
+## Release
+
+Version lives in `pyproject.toml` and `src/failstep/__init__.py`. Keep them equal. Add a `CHANGELOG.md` entry.
+
+GitHub Actions publishes to PyPI on a GitHub Release. That needs a `pypi` environment on the repo and a trusted publisher on PyPI. Do not put a PyPI token in the repository.

failstep-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

failstep-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+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).

failstep-0.1.0/README.md

@@ -0,0 +1,105 @@
+# 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).

failstep-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,117 @@
+# Architecture
+
+V1 is a local CLI. No server. No database. No UI.
+
+Package and command: **failstep**. Python 3.11+, pip-installable, `python -m failstep` as backup.
+
+## Pipeline
+
+```text
+trace.json / trace.jsonl / otel.json
+        |
+        v
+     parser          sniff format, reject garbage (exit 2)
+        |
+        v
+    normalize        Run + Step (Pydantic)
+        |
+        v
+    detectors        FS001-FS008, evidence only
+        |
+        +-- findings --> report (one root cause + secondary)
+        |
+        +-- compare      two reports, counted diffs only
+        +-- fix          print the recommendation; never writes files
+        |
+        +-- no error finding
+                 |
+                 v
+           optional LLM (Phase 4, if configured)
+                 |
+                 v
+              report or "Insufficient evidence."
+```
+
+## Layout
+
+Phase 8 (shipped). CI, sdist/wheel, changelog, contributing, issue templates.
+
+```text
+src/failstep/
+    __init__.py
+    __main__.py
+    cli.py
+    errors.py
+    models.py
+    parser.py
+    adapters.py
+    normalize.py
+    evidence.py
+    diagnose.py
+    compare.py
+    report.py
+    redact.py
+    llm.py
+    detectors/
+        __init__.py
+        malformed.py
+        schema.py
+        tool_error.py
+        retry.py
+        timeout.py
+        retrieval.py
+
+tests/
+examples/traces/
+docs/
+.github/
+pyproject.toml
+README.md
+CONTRIBUTING.md
+CHANGELOG.md
+LICENSE
+```
+
+No providers package. No FastAPI.
+
+## Internal model
+
+```text
+Run    id, name, status, duration_ms, error, tokens_in/out, steps[]
+Step   index, id, type, name, input, output, error, latency_ms, tokens, metadata
+Finding  id (FS00x), detector, category, title, severity, step_ids,
+         evidence[], recommendation,
+         source (deterministic | heuristic | llm)
+Report   run, root_cause, secondary[], findings[]
+```
+
+No confidence field on Finding.
+
+Nested OTEL spans flatten to ordered steps. Optional `parent_id` in metadata.
+
+## Detector order
+
+1. FS001 MalformedOutput
+2. FS002 ToolSchema
+3. FS003 ToolFailure
+4. FS004 RetryLoop
+5. FS005 Timeout
+6. FS006 EmptyRetrieval
+7. FS007 DuplicateChunks
+8. FS008 ConflictingSources
+
+Root cause = highest severity (`error` then `warning`), then this order, then first step index.
+
+FS005 thresholds: step `latency_ms >= 15000` (error), run `duration_ms >= 30000` (error), one step `>= 80%` of run and `>= 5000ms` (warning).
+
+## Output
+
+Contract: `docs/OUTPUT.md`. Tests freeze it (`docs/TESTING.md`).
+
+Terminal is the product. JSON is CI. Markdown is for GitHub comments.
+
+ASCII-safe. No required emoji. No confidence field. One root cause, then secondary.
+
+## Security
+
+Traces are untrusted. Redact secrets before any LLM call. Default path never uploads. `--no-redact` warns.