Metadata-Version: 2.4
Name: tracelens-ai
Version: 0.3.0
Summary: AI-powered Python error assistant. `import tracelens` and uncaught exceptions get an instant explanation of the cause and a suggested fix.
Author: TraceLens contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,assistant,debugging,errors,exception,onnx,traceback,tracelens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Requires-Dist: onnxruntime>=1.17
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.17; extra == 'onnx'
Description-Content-Type: text/markdown

# TraceLens

> AI-powered Python error assistant. `import tracelens` and uncaught
> exceptions get an instant explanation of the cause and a suggested fix.

```python
import tracelens  # that's it

age = input("Age: ")  # user types "30"
result = age + 1      # uncaught TypeError -> TraceLens explains it
```

## Usage

```bash
pip install tracelens-ai
```

> Note: this project is distributed on PyPI as **`tracelens-ai`** because the
> `tracelens` name is taken by an unrelated project. You still
> `import tracelens`.

Then in any script:

```python
import tracelens
```

On an uncaught exception TraceLens:

1. always prints the original stock traceback first (it never hides errors),
2. runs an analysis (on a background thread with a timeout), and
3. renders a panel with the error, the failing line, a cause, a fix and a
   confidence score.

Try it without writing any code:

```bash
tracelens demo
```

## How it works

1. `import tracelens` registers `sys.excepthook` (and
   `threading.excepthook`) — nothing else changes in your program.
2. On an uncaught exception, TraceLens collects the error type, message,
   traceback frames, surrounding source code, and Python version.
3. A local ONNX model (`Qwen2.5-0.5B-Instruct`, 4-bit, ~780 MB) is
   downloaded automatically on first use and cached in
   `%LOCALAPPDATA%\tracelens` (Windows) or `~/.cache/tracelens`. It runs
   entirely on the CPU via onnxruntime — no API key, no network calls
   during analysis.
4. The explanation is rendered with [Rich](https://github.com/Textualize/rich).

A deterministic heuristic rule engine ships as the guaranteed offline
fallback: if the model is not cached, the download fails, analysis times
out, or the model output does not parse, you still get useful, rule-based
advice. When the fallback replaces part of the output the panel says so
(`Engine: local+heuristic`).

### Backends

Select one with the `TRACELENS_BACKEND` environment variable:

| Backend    | Description                                          |
| ---------- | ---------------------------------------------------- |
| `local`    | built-in ONNX model (default)                        |
| `heuristic`| offline rule engine, instant, no downloads           |
| `ollama`   | your local Ollama server (opt-in, `OLLAMA_*` env)    |
| `openai`   | OpenAI-compatible API (opt-in, `OPENAI_*` env)       |
| `anthropic`| Claude API (opt-in, `ANTHROPIC_*` env)               |

## Configuration

| Variable                | Meaning                                             |
| ----------------------- | --------------------------------------------------- |
| `TRACELENS_DISABLE`     | `1` = hooks print only the stock traceback          |
| `TRACELENS_BACKEND`     | backend name (default `local`)                      |
| `TRACELENS_TIMEOUT`     | analysis timeout in seconds (default `120`)         |
| `TRACELENS_MODEL_DIR`   | override the model cache directory                  |
| `TRACELENS_OFFLINE`     | `1` = never touch the network, heuristic only       |
| `TRACELENS_ALLOW_CLOUD` | `1` = allow cloud backends (default off)            |
| `OLLAMA_*`, `OPENAI_*`, `ANTHROPIC_*` | cloud backend settings (key, base URL, model) |

## Command line

```bash
tracelens info    # configuration + model cache status
tracelens model   # cache files and sizes
tracelens purge   # delete the downloaded model files
tracelens demo    # crash a snippet to preview TraceLens output
```

## Privacy

Local and heuristic backends never send code, source, or error data
anywhere. Cloud backends are strictly opt-in.

## Development status

All phases implemented:

- [x] Phase 1: package structure + import system
- [x] Phase 2: exception interception
- [x] Phase 3: traceback parsing + source context
- [x] Phase 4: AI backend abstraction
- [x] Phase 5: local model loading
- [x] Phase 6: UI with Rich
- [x] Phase 7: PyPI publishing prep

## Development

```bash
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -e ".[dev]"
pytest
```

The test suite covers the import system, the hooks, the traceback parser,
source context, the heuristic rules, the tokenizer and inference helpers
(no model download required).

## License

MIT
