Metadata-Version: 2.4
Name: ghostspan
Version: 0.1.0
Summary: Local, offline scanner that finds silent failures in OTel and Langfuse AI agent trace exports
Project-URL: Homepage, https://meshai.dev
Project-URL: Repository, https://github.com/meshailabs-org/ghostspan
Author-email: MeshAI Labs <hello@meshai.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,langfuse,meshai,observability,opentelemetry,otel,silent-failure
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# ghostspan

Built by [MeshAI Labs](https://meshai.dev), the Agent Control Plane for monitoring and governing AI agents.

`ghostspan` is a local, offline command-line scanner that finds silent failures in AI agent trace exports: OTel (OpenTelemetry) and Langfuse. It looks for the failure modes that never raise an exception and never show up as a 5xx: swallowed errors, empty completions, truncated responses, degraded tool-call success rates, retry loops, cost outliers, and latency outliers.

## The guarantee

`ghostspan` runs entirely on your machine, on files you already have.

- 100% local. No data leaves this machine.
- Zero network calls. There is no HTTP client anywhere in this codebase.
- Zero telemetry. Nothing is phoned home, ever.
- No API keys required. There is nothing to configure and nothing to authenticate.

Detection always runs on tokens and structural facts, never on raw content, unless you explicitly opt in with `--show-content` (terminal only) or `--content-in-file` (markdown report). Redaction is on by default everywhere.

## Install

```bash
pipx install ghostspan
```

`pipx` is recommended because a bare `pip install` fails on modern Debian/Ubuntu (PEP 668, externally managed environments). If you prefer plain pip, use a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install ghostspan
```

## Usage

```bash
ghostspan traces.jsonl
ghostspan ./exports/            # recurses for *.json and *.jsonl
ghostspan traces.jsonl --format langfuse
ghostspan traces.jsonl --since 7d --fail-on high
ghostspan traces.jsonl --show-content --max-content-chars 120
```

By default `ghostspan` writes a markdown report to `silent-failure-report.md` (see `examples/silent-failure-report.md` for a sample) and prints a summary to the terminal.

### Flags

| Flag | Description |
|---|---|
| `--format auto\|otlp\|langfuse` | Force the input format instead of auto-detecting it. |
| `--out PATH` | Markdown report path (default `silent-failure-report.md`). |
| `--no-file` | Do not write the markdown report. |
| `--json [PATH]` | Write structured, already-redacted JSON findings to PATH or stdout. |
| `--since / --until` | Time filter: `7d` or ISO 8601. |
| `--show-content` | Show redacted content snippets in the terminal only. Off by default. |
| `--content-in-file` | Also allow redacted content snippets in the markdown report. Off by default. |
| `--redact PATTERN` | Extra regex to redact from content snippets. Repeatable. |
| `--max-content-chars N` | Max characters per content snippet (default 200). |
| `--min-samples N` | Override the minimum group size used by every statistical detector gate. |
| `--config ghostspan.toml` | Defaults for any option above. |
| `--price-map FILE` | JSON file overriding the bundled pricing table for dollar estimates. |
| `--fail-on high\|medium\|low` | Exit 1 if a finding at or above this tier exists. Off by default. |
| `--quiet` | Compact terminal summary only. |
| `--no-color` | Disable terminal colors. |
| `--version` | Print the version and exit. |

### Exit codes

- `0`: scan completed. Findings never fail the process unless `--fail-on` is set.
- `1`: only with `--fail-on`, when a finding at or above the given tier was found.
- `2`: usage error (bad flags, no input paths).
- `3`: input error, no parseable spans were found in any input.

## What it detects

| ID | Detector | Tier |
|---|---|---|
| D1 | Errors not surfaced to the trace root, and abandoned tool calls | HIGH |
| D2 | Truncation and finish_reason anomalies | HIGH / MEDIUM |
| D3 | Empty completions and structured-error envelopes | HIGH |
| D4 | Degraded tool-call success rate | MEDIUM |
| D5 | Retry loops | MEDIUM |
| D6 | Cost anomalies (token-based; dollars are display-only) | MEDIUM / INFO |
| D7 | Latency anomalies | INFO |

Every rule and its exact threshold is printed in the report's methodology appendix. Detectors degrade gracefully: a missing attribute never becomes an assumed value, and a detector with too little data to run says so explicitly rather than silently skipping or guessing.

## What it does not catch

`ghostspan` runs deterministic and statistical heuristics over trace structure, status codes, token counts, and finish reasons. It cannot catch natural-language refusals, semantically wrong answers, or hallucination and faithfulness failures. A clean report is not proof the agent behaved correctly, only that it did not trip these particular structural heuristics.

## License

MIT. See [LICENSE](LICENSE).

Built by [MeshAI Labs](https://meshai.dev).
