Metadata-Version: 2.4
Name: nberror
Version: 0.1.0
Summary: Collects Jupyter cell errors with the context a traceback leaves out - variable shapes, missing names, execution history - ready to hand to an AI agent.
Author: Erika Lorents
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/nberror/
Keywords: jupyter,ipython,notebook,traceback,debugging,error
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: IPython
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: ipython>=7.0

# nberror

Collects Jupyter cell errors together with the context a traceback leaves out —
DataFrame shapes, which names are missing from the namespace, and what you ran
before — into one text you can hand to an AI agent, or just read yourself.

A traceback tells you *where* execution stopped. It rarely tells you *why*: that
your DataFrame has 17 columns and `duration` is one of them while you asked for
`durations`, or that the cell defining the variable was never run in this kernel.

```
pip install nberror
```

```python
%load_ext nberror
```

That's it. Run cells as usual. When one fails you see the normal traceback plus:

```
[viga logitud - küsi AI-agendilt "viga" või jooksuta: nberror]
```

Then, from the terminal:

```bash
nberror
```

## What the report contains

```markdown
- **Erind:** `KeyError: "['durations'] not found in axis"`
- **Lahter:** In[5], kestus 2.02s

## Lahtri kood            the whole cell, not just the failing line
## Traceback
## Muutujad, mis lahtris esinevad ja on olemas
- `df`: DataFrame kuju=(45211, 17), 17 veergu: age, job, ..., duration ...
## Nimed, mida namespace'is EI OLE
- `train_balanced`
## Mis selles sessioonis enne käivitati
| In[] | tulemus | lahtri esimene rida |
| 4    | **VIGA** KeyError ... | df = df.drop(columns=['durations']) |
| 5    | ok                    | df = df.drop(columns=['duration'])  |
```

The last two sections solve most notebook errors. Missing names usually name the
cause directly. The history shows the *path* — a skipped cell, a wrong order, or a
kernel restart is as common a cause as wrong code.

Report text is in Estonian; the API and CLI flags are in English.

## Commands

```bash
nberror                  # last error, formatted
nberror --all            # every error in the log
nberror --history        # last 25 executed cells

nberror-nb check  nb.ipynb          # static check, does not run the notebook
nberror-nb run    nb.ipynb [--upto 14]
nberror-nb map    nb.ipynb          # cell index, line ranges, stored errors
nberror-nb line   nb.ipynb 148      # which cell is line 148 in

nberror-install          # auto-load in every kernel (optional)
nberror-install --check
nberror-install --uninstall
```

`nberror-nb check` finds undefined names and out-of-order cells in about a second,
without executing anything:

```
[DEFINEERIMATA] lahter 14, rida 4: 'train_balanced' - ei ole kusagil defineeritud
    X_train_bal = train_balanced
```

## Use with an AI agent

Put an `AGENTS.md` in your project telling the agent that "viga" means run
`nberror` and interpret the output. `AGENTS.md` is read without configuration by
Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf and Zed; Claude Code reads
`CLAUDE.md`, which can be a single line: `@AGENTS.md`.

Without an agent, read it yourself or pipe it anywhere:

```bash
nberror | clip          # Windows
nberror | pbcopy        # macOS
```

There is also an inline mode that calls the `claude` CLI and prints the
explanation straight under the cell:

```python
import nberror; nberror.activate(inline=True)
```

Change `MODEL`, or the command in `_kysi_claude`, to use a different model.

## Where data is kept

| | |
|---|---|
| `.nberror/ajalugu.jsonl` | error log, last 200 errors, in your project root |
| `~/.ipython/profile_default/history.sqlite` | IPython's own input history — **read only** |

Only failing cells are logged, so a successful cell costs nothing. "What ran
before" comes from IPython's existing history database, which is opened read-only
and never written to.

The log contains your code. Add `.nberror/` to `.gitignore`.

## Python API

```python
import nberror

nberror.activate(inline=False, quiet=False)
nberror.deactivate()
nberror.last_error()            # dict, or None
nberror.format_error(entry)     # markdown string
nberror.log_path()
nberror.inputs(session, upto_line, count)
```

## License

MIT
