Metadata-Version: 2.4
Name: sniptrace
Version: 1.2.0
Summary: Trim noisy terminal output before it reaches your AI coding agent
Author-email: SnipTrace <hello@sniptrace.com>
License-Expression: MIT
Project-URL: Homepage, https://sniptrace.com
Project-URL: Documentation, https://sniptrace.com/docs
Project-URL: Bug Tracker, https://github.com/sniptrace/sniptrace/issues
Keywords: llm,ai,agents,terminal,output,filter,tokens,context-window
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sniptrace

Trim noisy terminal output before it reaches your AI coding agent. Save tokens, reduce LLM costs, and keep context windows focused on what matters.

```python
pip install sniptrace
```

## Quick start

### Filter a string you already have

```python
from sniptrace import filter_text

raw_output = captured_stderr  # string from your agent's code execution
clean = filter_text(raw_output)
llm.complete(f"Fix this error:\n{clean}")
```

### Run a command and get filtered output

```python
from sniptrace import run

result = run(["pytest", "tests/"])

if not result.ok:
    llm.complete(f"Fix this error:\n{result.output}")
    # result.output has no progress bars, no site-packages frames, no noise
```

## What gets filtered

SnipTrace removes known low-signal output patterns from:

- **Python** — stdlib/venv traceback frames, pip install chatter
- **Node / JS** — npm/pnpm/yarn deprecation warnings, progress lines
- **Docker** — BuildKit step lines, layer pull progress
- **pytest / Jest / Vitest** — session headers, progress dots, PASSED lines
- **Cargo / Gradle / Maven** — compile progress, `[INFO]` lines
- **Generic** — ANSI escape codes, progress bars, spinner frames, update banners

Lines containing error signals (`error`, `traceback`, `exception`, `failed`, `cannot`, etc.) are **always preserved**, even if they match a strip pattern.

## API

### `filter_text(text: str) -> str`

Filter an already-captured string. No CLI required — all filtering is pure Python.

```python
from sniptrace import filter_text

clean = filter_text(raw_stderr)
```

### `run(command, *, cwd=None, env=None, timeout=None) -> SnipResult`

Run a command and return filtered output. Uses the `sniptrace` CLI if installed (preserves telemetry), otherwise filters natively in Python.

```python
from sniptrace import run

result = run(["pytest", "-q", "tests/"])
print(result.output)        # filtered output
print(result.ok)            # True if exit code was 0
print(result.reduction_pct) # e.g. 87.3
print(result.bytes_saved)   # original_bytes - filtered_bytes
```

### `SnipResult`

```python
@dataclass
class SnipResult:
    exit_code: int
    output: str
    original_bytes: int
    filtered_bytes: int
    reduction_pct: float
    filtered: bool      # False if filtering was skipped

    @property
    def ok(self) -> bool: ...         # exit_code == 0
    @property
    def bytes_saved(self) -> int: ... # original_bytes - filtered_bytes
```

### `is_available() -> bool`

Returns `True` if the `sniptrace` CLI is installed on PATH.

## Typical agent loop

```python
from sniptrace import run

def agent_loop(task: str, llm, max_rounds: int = 5):
    code = llm.complete(f"Write Python code to: {task}")
    
    for _ in range(max_rounds):
        write_to_disk(code)
        result = run(["python", "solution.py"])
        
        if result.ok:
            return code  # done
        
        code = llm.complete(
            f"The code produced this error:\n{result.output}\n\nFix it."
        )
    
    return code
```

## Zero dependencies

The package uses only the Python standard library. No external packages required.

## Install the CLI (optional)

The CLI is optional — `filter_text()` and `run()` both work without it. The CLI adds telemetry (token savings counter) and shell wrappers for automatic filtering in your terminal.

```bash
curl -fsSL https://sniptrace.com/install.sh | sh
```

## Links

- [Website](https://sniptrace.com)
- [Documentation](https://sniptrace.com/docs)
- [Live token savings counter](https://sniptrace.com/counter)
