Metadata-Version: 2.4
Name: agentnb
Version: 0.1.1
Summary: A persistent Python notebook for AI agents, driven from the CLI
Project-URL: Homepage, https://github.com/oegedijk/agentnb
Project-URL: Repository, https://github.com/oegedijk/agentnb
Project-URL: Issues, https://github.com/oegedijk/agentnb/issues
Author-email: Oege Dijk <oegedijk@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,ipython,jupyter,notebook,repl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: ipykernel>=6.0
Requires-Dist: jupyter-client>=8.0
Provides-Extra: dev
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: ty>=0.0.1a6; extra == 'dev'
Description-Content-Type: text/markdown

# agentnb

A persistent project-scoped Python REPL for coding agents, exposed through a simple CLI.

> Status: alpha. Expect rough edges and breaking changes. Use in local
> development workflows at your own risk.

## Why

Agents can run shell commands, but they lose state when using one-off `python -c` and script invocations. `agentnb` gives agents a long-running IPython kernel they can drive with CLI commands, so they can explore incrementally, keep expensive setup in memory, inspect live variables, and recover without restarting from scratch on every step.

The right mental model is a persistent REPL for agents, or an append-only notebook without a notebook UI. `agentnb` keeps execution state and history, but it does not edit notebook cells or manage `.ipynb` files.

Module reloading is explicit. `agentnb` does not auto-reload edited modules on
every execution; use `agentnb reload` after changing project-local code.

`exec` follows normal IPython/Notebook semantics for output: if the final line
of a snippet is an expression, its value is returned as the execution result.

## Install

```bash
uv add agentnb
# or
pip install agentnb
```

## Quick Start

```bash
agentnb start --project /path/to/project --json
agentnb exec "from myapp.models import User" --json
agentnb exec --file analysis.py --json
agentnb vars --json
agentnb inspect User --json
agentnb stop --json
```

For multiline code, prefer `--file` or stdin/heredoc:

```bash
agentnb exec --json <<'PY'
import pandas as pd
df = pd.read_csv("tips.csv")
df.head()
PY
```

For lower-noise agent integrations, you can set defaults once per shell:

```bash
export AGENTNB_FORMAT=agent
```

That enables JSON output and suppresses suggestions across commands. You can also use
top-level flags such as `agentnb --agent ...`, `agentnb --json ...`,
`agentnb --no-suggestions ...`, and `agentnb --quiet ...`.

In `--agent` mode, default payloads are compacted to reduce token usage:
trimmed error tracebacks, compact history entries, compact dataframe previews,
and structural summaries for common containers such as `list` and `dict`.

## Recommended Workflow

The normal agent loop is:

1. `agentnb start --json`
2. `agentnb exec "..." --json` for short snippets
3. `agentnb exec --file analysis.py --json` or pipe code through stdin for multiline work
4. `agentnb vars --json`
5. `agentnb inspect NAME --json`
6. `agentnb reload --json` after editing project-local modules
7. `agentnb reload myapp.module --json` to target one imported module
8. `agentnb history --json`

Use `agentnb doctor --json` if startup fails, `agentnb interrupt --json` if execution hangs, and `agentnb reset --json` if the namespace needs a clean slate.

If startup reports that `ipykernel` is missing, rerun `agentnb start` with
`--auto-install` or use `agentnb doctor --fix --json`.

Running `agentnb` with no arguments, or `agentnb --help`, prints an agent-oriented command guide and workflow summary.

## Positioning

`agentnb` is optimized for stateful agent iteration inside a project:
- a persistent REPL the agent can keep using across steps
- a lightweight append-only notebook model backed by execution history
- module reload and variable inspection without a notebook editor

It is not a notebook editing tool:
- it does not edit cells
- it does not write `.ipynb` files
- it does not synchronize with JupyterLab

## Commands

- `agentnb start [--project PATH] [--python PATH] [--auto-install]`
- top-level flags: `agentnb [--json] [--agent] [--quiet] [--no-suggestions] <command>`
- `agentnb status [--project PATH]`
- `agentnb exec [CODE] [-f FILE] [--timeout SECONDS] [--stdout-only|--stderr-only|--result-only] [--project PATH] [--json]`
- `agentnb vars [--project PATH] [--json] [--types|--no-types]`
- `agentnb inspect NAME [--project PATH] [--json]`
- `agentnb reload [MODULE] [--project PATH] [--json]`
- `agentnb history [--project PATH] [--errors] [--latest|--last N] [--all] [--json]`
- `agentnb interrupt [--project PATH] [--json]`
- `agentnb reset [--project PATH] [--json]`
- `agentnb stop [--project PATH] [--json]`
- `agentnb doctor [--project PATH] [--python PATH] [--fix] [--json]`

Notes:
- `vars` includes type information by default.
- `vars` hides imported helper routines and classes, and summarizes common containers compactly.
- `history` shows semantic user-visible steps by default such as `exec`, `vars`, `inspect`, `reload`, and `reset`.
- Use `history --all` to include internal helper executions sent to the kernel.
- Module reloading is explicit. `reload MODULE` reloads one imported project-local module.
- Bare `reload` reloads all currently imported project-local modules and reports rebound names and possible stale objects.
- If reload reports stale objects, recreate them or run `agentnb reset` when stale state is widespread.
- `inspect` gives compact previews for pandas-like dataframes and for common `list`/`dict` API payloads.

## Out-of-the-box startup

On `agentnb start`, the runtime selects an interpreter in this order:

1. `--python` interpreter
2. `<project>/.venv` interpreter
3. active `VIRTUAL_ENV` interpreter
4. current Python executable

If `ipykernel` is missing for the selected interpreter, `agentnb start` fails
with the exact install command. Pass `--auto-install` to let `agentnb` install
it for you, or use `agentnb doctor --fix --json`.

## JSON Mode

Pass `--json` to emit a stable machine-readable envelope. This is the preferred mode for agent integrations.

Command-level success and execution success now align: if `exec` or `reset`
fails in the kernel, the top-level response has `"status": "error"` and the
command exits non-zero. The execution payload is still included in `data`.
Default JSON is intentionally compact for agent use: large event lists are
omitted, tracebacks are trimmed, and inspection/history payloads prefer short
previews over raw internal detail.

If you want that behavior by default, set `AGENTNB_FORMAT=json` or `AGENTNB_FORMAT=agent`.
`agent` also suppresses suggestions and enables quiet mode.

```json
{
  "schema_version": "1.0",
  "status": "ok",
  "command": "exec",
  "project": "/path/to/project",
  "session_id": "default",
  "timestamp": "2026-03-08T21:00:00+00:00",
  "data": {
    "status": "ok",
    "stdout": "",
    "stderr": "",
    "result": "42",
    "execution_count": 1,
    "duration_ms": 12
  },
  "suggestions": [
    "Run `agentnb vars --json` to inspect the updated namespace.",
    "Run `agentnb inspect NAME --json` to inspect a specific variable.",
    "Run `agentnb history --json` to review prior executions."
  ],
  "error": null
}
```

## How It Works

`agentnb` starts an IPython kernel process and stores connection/session metadata under `.agentnb/` in the target project. CLI commands connect via Jupyter messaging protocol.

## Architecture

- `SessionStore`: project/session metadata and stale cleanup
- `HistoryStore`: typed JSONL history records for semantic and internal execution history
- `KernelRuntime`: lifecycle + execution API
- `RuntimeBackend`: backend interface, with local IPython backend for v0.1
- `NotebookOps`: vars/inspect/reload semantic operations
- `OutputContract`: human + JSON output from one response envelope
- `Hooks`: no-op extension points for future policy/plugins/telemetry

## Development

```bash
uv sync --extra dev
uv run ruff check src tests
uv run ruff format --check src tests
uv run ty check src
uv run pytest
```

## 0.1.1 Ergonomics

- top-level `--agent`, `--json`, `--quiet`, and `--no-suggestions` flags
- `AGENTNB_FORMAT`, `AGENTNB_NO_SUGGESTIONS`, and `AGENTNB_QUIET` environment defaults
- `exec --stdout-only`, `--stderr-only`, and `--result-only` for script-friendly capture
- `history --latest` and `history --last N` shortcuts

## Current Ergonomics

- `exec` accepts short inline code, `--file`, or stdin/heredoc for multiline snippets
- `vars` includes type information by default
- `vars` hides imported helper routines and classes and summarizes common containers compactly
- `inspect` gives compact previews for pandas-like objects and common `list`/`dict` payloads
- `history` defaults to semantic user-visible steps, with `--all` for internal kernel executions
- `--agent` returns compact JSON by default to reduce token usage during iterative workflows

## License

MIT
