Metadata-Version: 2.5
Name: errd
Version: 0.1.0
Summary: Debug with less context. Analyze Python tracebacks and generate minimal AI-ready debugging packages.
Project-URL: Homepage, https://github.com/reyan/errd
Project-URL: Repository, https://github.com/reyan/errd
Project-URL: Issues, https://github.com/reyan/errd/issues
Author-email: Reyan <reyan@errd.dev>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,cli,context,debugging,llm,traceback
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Requires-Dist: rich>=13.7.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# errd

**Debug with less context.**

`errd` is a local-first Python CLI that analyzes tracebacks, finds the code most relevant to a failure, and generates a focused debugging context for AI coding assistants.

Instead of giving an AI your entire repository, `errd` extracts the code most relevant to the error.

```bash
pip install errd
errd analyze error.log
```

> **No LLM. No API key. No cloud. Your code stays local during analysis.**

---
## Installation

Requires **Python 3.11+**.

```bash
pip install errd
```

Verify:

```bash
errd --version
```

---
## The Problem

When an error occurs in a large codebase, developers often give an AI coding assistant a large portion of the repository to provide enough context.

This creates two problems:

- **Unnecessary context** — most of the repository is unrelated to the failure.
- **Context cost** — larger prompts consume more tokens and can make debugging harder by introducing irrelevant information.

The challenge isn't simply giving an AI **more code**.

It's giving it **the right code**.

---

## What errd Does

```text
Python traceback
       │
       ▼
     errd
       │
       ├── Parse traceback
       ├── Find repository
       ├── Locate failing source
       ├── Analyze Python code
       ├── Follow import dependencies
       ├── Rank relevant symbols
       ├── Apply token budget
       └── Redact obvious secrets
       │
       ▼
errd-context.md
       │
       ▼
Claude / GPT / Gemini / Cursor
```

`errd` does not try to fix the bug itself.

It prepares the **smallest useful debugging context** for the AI tool you already use.

---

## Example

Suppose your repository contains roughly 48,000 tokens of Python source.

A traceback points to:

```text
app/database/repository.py:63
```

Instead of manually finding the relevant files, `errd` can produce a focused context such as:

```text
errd analysis complete

Error              UniqueViolationError
Crash site         app/database/repository.py:63

Relevant symbols   7
Selected context   3,184 tokens
Repository source  47,821 tokens
Reduction           93.3%

Output             errd-context.md
```

**The numbers above are illustrative output from the included example fixture, not benchmark results.**

The generated `errd-context.md` can then be provided to Claude, GPT, Gemini, Cursor, or another coding assistant.

---

## How It Works

### Stage 1 — Local Analysis

No AI or API key is required.

#### 1. Parse the traceback

Extracts:

- exception type
- exception message
- traceback frames
- source paths
- line numbers
- function names when available

Supports chained exceptions and noisy log output.

#### 2. Discover the repository

`errd` attempts to locate the project automatically.

You can also explicitly specify it:

```bash
errd analyze error.log --repo /path/to/project
```

#### 3. Analyze Python source

`errd` uses Tree-sitter to locate:

- functions
- methods
- classes
- imports
- relevant source ranges

Tree-sitter is fault-tolerant, allowing analysis of files that may contain syntax errors.

#### 4. Build an import dependency graph

`errd` follows Python module-level import relationships to find code connected to the failing location.

V0.1 does **not** attempt complete dynamic or inter-procedural call-graph analysis.

#### 5. Rank relevant code

Symbols are scored using deterministic signals including:

- traceback proximity
- dependency distance
- source location
- user-code relevance
- Git modification signals

Recently modified files can receive an additional relevance boost.

#### 6. Apply a token budget

```bash
errd analyze error.log --budget 4000
```

`errd` selects the highest-value context that fits the requested budget.

Large symbols can be structurally reduced when necessary.

#### 7. Redact obvious secrets

Before generating the final context, `errd` attempts to redact common secrets such as:

- API keys
- AWS credentials
- JWTs
- Bearer tokens
- database credentials
- passwords
- private keys

---

### Stage 2 — AI Debugging

The output is a Markdown file:

```text
errd-context.md
```

Give that context to your preferred AI coding assistant:

```text
Claude
GPT
Gemini
Cursor
```

The AI performs the actual debugging.

`errd` simply makes sure it receives focused context first.

---


## Usage

### Analyze a traceback

```bash
errd analyze error.log
```

### Set a custom token budget

```bash
errd analyze error.log --budget 8000
```

### Specify an output file

```bash
errd analyze error.log --output debug-context.md
```

### Specify the repository explicitly

```bash
errd analyze error.log --repo /path/to/my-project
```

### Show help

```bash
errd --help
```

---

## Output

The generated Markdown contains:

```text
Error
Traceback
Repository information
Relevant source files
Relevant code snippets
Relevance information
Debugging task
```

The goal is to produce something you can directly give to an AI coding assistant.

---

## Tech Stack

| Component | Technology |
|---|---|
| Language | Python 3.11+ |
| CLI | Typer + Rich |
| Python parsing | Tree-sitter + tree-sitter-python |
| Dependency analysis | Python standard library + BFS |
| Token counting | tiktoken |
| Git signals | Git CLI |
| Secret redaction | Regex-based patterns |
| Testing | pytest |
| Linting | Ruff |
| Type checking | mypy |

No LLM is required.

No API key is required.

The analysis runs locally.

---

## Why Tree-sitter?

Why not Python's built-in `ast` module?

Debugging often involves code that is incomplete or syntactically broken.

`ast.parse()` raises a `SyntaxError` when it cannot parse the file.

Tree-sitter is fault-tolerant and can produce a partial syntax tree, allowing `errd` to extract useful structural information even from imperfect source files.

---

## Security

`errd` includes a lightweight, best-effort secret redaction layer.

It detects common patterns such as:

- AWS access keys
- API keys
- Bearer tokens
- JWTs
- database URLs containing credentials
- password configuration values
- private key blocks

Detected values are replaced with:

```text
[REDACTED]
```

### Important

This is **not a complete secret scanner**.

It uses pattern-based detection and cannot guarantee that every secret will be detected.

Always review generated context before sharing it with an external AI service.

---

## Privacy

`errd` performs its analysis locally.

V0.1 does not send your source code, traceback, or repository to an `errd` server.

There is no required cloud service or LLM API.

You choose if and where the generated context is subsequently shared.

---

## Limitations — V0.1

`errd` is intentionally narrow.

### Python only

V0.1 supports Python projects.

JavaScript, TypeScript, Go, Rust, Java, and other languages are not currently supported.

### Import-level dependencies

V0.1 analyzes module-level import relationships.

It does not provide complete inter-procedural call-graph analysis and cannot perfectly understand dynamic Python behavior such as:

- dynamic imports
- monkey patching
- runtime-generated attributes
- complex dependency injection
- dynamic dispatch

### Heuristic relevance

The relevance scorer is deterministic and heuristic-based.

It does not use embeddings or machine learning.

### Token estimates

V0.1 uses `tiktoken` for token estimation.

Token counts can differ from the tokenizer used by Claude, Gemini, or other models.

### Best-effort redaction

Secret detection is pattern-based and is not a security guarantee.

### Git is optional

Git information can improve relevance scoring, but `errd` can operate without Git.

---

## Development

Clone the repository:

```bash
git clone https://github.com/Das-R10/errd.git
cd errd
```

Install in development mode:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

Run linting:

```bash
ruff check .
```

Run formatting check:

```bash
ruff format --check .
```

Run type checking:

```bash
mypy --strict
```

---

## Architecture

The V0.1 pipeline is:

```text
Traceback
    ↓
Traceback Parser
    ↓
Repository Discovery
    ↓
Tree-sitter Analysis
    ↓
Dependency Analysis
    ↓
Relevance Scoring
    ↓
Token Budgeting
    ↓
Secret Redaction
    ↓
Markdown Context
```

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for details.

---

## Testing

The current V0.1 implementation includes:

- **143 tests**
- **91% code coverage**
- Ruff linting
- strict mypy type checking
- CLI smoke tests
- end-to-end fixtures

Run the full suite with:

```bash
pytest
```

---

## Benchmarking

A benchmark framework is included for evaluating `errd` on real-world debugging tasks.

The planned evaluation measures:

- repository source baseline
- selected context size
- token reduction
- selected file count
- fix-file recall
- fix-function recall
- relevant-line/context recall
- runtime

The full SWE-bench evaluation has **not yet been completed**.

Benchmark results will be added once the evaluation has been run.

---

## Roadmap

### V0.1 — Current

- Python traceback analysis
- Repository discovery
- Tree-sitter source analysis
- Import-level dependency analysis
- Deterministic relevance scoring
- Token-aware context selection
- Git relevance signals
- Secret redaction
- Markdown debugging context
- CLI
- Benchmark framework

### V0.2 — Planned

Potential improvements based on V0.1 benchmark results:

- improved graph-based relevance ranking
- Personalized PageRank evaluation
- better context selection
- `--explain` scoring output
- additional input formats
- improved Git intelligence

V0.2 features will be driven by benchmark results rather than added solely for feature breadth.

### Later

- additional language support
- editor integrations
- deeper debugging workflows

---

## Contributing

Contributions are welcome.

If you find a bug, have an idea, or want to improve the analysis pipeline, open an issue or pull request.

Please keep contributions focused on `errd`'s core goal:

> **Find the smallest useful debugging context for an error.**

---

## License

Apache License 2.0.
