agentnb 0.1.0__tar.gz

agentnb-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Bytecode / caches
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Build / packaging artifacts
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+
+# AgentNB runtime state
+.agentnb/
+*.ipynb_checkpoints

agentnb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oege Dijk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentnb-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: agentnb
+Version: 0.1.0
+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.
+
+## 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 "u = User(name='test'); print(u)" --json
+agentnb vars --json
+agentnb stop --json
+```
+
+## Recommended Workflow
+
+The normal agent loop is:
+
+1. `agentnb start --json`
+2. `agentnb exec "..." --json`
+3. `agentnb vars --json`
+4. `agentnb inspect NAME --json`
+5. `agentnb reload MODULE --json` after source edits
+6. `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]`
+- `agentnb status [--project PATH]`
+- `agentnb exec [CODE] [-f FILE] [--timeout SECONDS] [--project PATH] [--json]`
+- `agentnb vars [--project PATH] [--json] [--types]`
+- `agentnb inspect NAME [--project PATH] [--json]`
+- `agentnb reload MODULE [--project PATH] [--json]`
+- `agentnb history [--project PATH] [--errors] [--json]`
+- `agentnb interrupt [--project PATH] [--json]`
+- `agentnb reset [--project PATH] [--json]`
+- `agentnb stop [--project PATH] [--json]`
+- `agentnb doctor [--project PATH] [--python PATH] [--fix] [--json]`
+
+## 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.
+
+```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, stale cleanup, 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
+```
+
+## License
+
+MIT

agentnb-0.1.0/README.md

@@ -0,0 +1,143 @@
+# 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.
+
+## 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 "u = User(name='test'); print(u)" --json
+agentnb vars --json
+agentnb stop --json
+```
+
+## Recommended Workflow
+
+The normal agent loop is:
+
+1. `agentnb start --json`
+2. `agentnb exec "..." --json`
+3. `agentnb vars --json`
+4. `agentnb inspect NAME --json`
+5. `agentnb reload MODULE --json` after source edits
+6. `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]`
+- `agentnb status [--project PATH]`
+- `agentnb exec [CODE] [-f FILE] [--timeout SECONDS] [--project PATH] [--json]`
+- `agentnb vars [--project PATH] [--json] [--types]`
+- `agentnb inspect NAME [--project PATH] [--json]`
+- `agentnb reload MODULE [--project PATH] [--json]`
+- `agentnb history [--project PATH] [--errors] [--json]`
+- `agentnb interrupt [--project PATH] [--json]`
+- `agentnb reset [--project PATH] [--json]`
+- `agentnb stop [--project PATH] [--json]`
+- `agentnb doctor [--project PATH] [--python PATH] [--fix] [--json]`
+
+## 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.
+
+```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, stale cleanup, 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
+```
+
+## License
+
+MIT

agentnb-0.1.0/pyproject.toml

@@ -0,0 +1,110 @@
+[project]
+name = "agentnb"
+version = "0.1.0"
+description = "A persistent Python notebook for AI agents, driven from the CLI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [
+    { name = "Oege Dijk", email = "oegedijk@gmail.com" },
+]
+keywords = ["agent", "repl", "notebook", "ipython", "jupyter", "cli", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+dependencies = [
+    "click>=8.1",
+    "ipykernel>=6.0",
+    "jupyter-client>=8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=4.0",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-mock>=3.14",
+    "ruff>=0.11",
+    "ty>=0.0.1a6",
+]
+
+[project.scripts]
+agentnb = "agentnb.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/oegedijk/agentnb"
+Repository = "https://github.com/oegedijk/agentnb"
+Issues = "https://github.com/oegedijk/agentnb/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+ignore-vcs = true
+exclude = [
+    ".agentnb",
+    ".github",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "dist",
+    "tests",
+    "ROADMAP.md",
+    ".gitignore",
+    "**/.gitignore",
+    "uv.lock",
+    "**/__pycache__",
+    "*.py[cod]",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentnb"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/agentnb",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+exclude = [
+    ".gitignore",
+    "**/.gitignore",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["agentnb"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

agentnb-0.1.0/src/agentnb/__init__.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from .contracts import CommandResponse, ExecutionResult, KernelStatus
+from .provisioner import DoctorReport, KernelProvisioner, ProvisionResult
+from .runtime import KernelRuntime
+from .session import DEFAULT_SESSION_ID, resolve_project_root
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CommandResponse",
+    "DoctorReport",
+    "ExecutionResult",
+    "KernelProvisioner",
+    "KernelRuntime",
+    "KernelStatus",
+    "ProvisionResult",
+    "__version__",
+    "doctor_environment",
+    "execute_code",
+    "start_kernel",
+    "status_kernel",
+    "stop_kernel",
+]
+
+
+def start_kernel(
+    project: str | Path = ".",
+    session_id: str = DEFAULT_SESSION_ID,
+    *,
+    auto_install: bool = False,
+) -> tuple[KernelStatus, bool]:
+    runtime = KernelRuntime()
+    project_root = resolve_project_root(override=Path(project))
+    return runtime.start(
+        project_root=project_root,
+        session_id=session_id,
+        auto_install=auto_install,
+    )
+
+
+def status_kernel(project: str | Path = ".", session_id: str = DEFAULT_SESSION_ID) -> KernelStatus:
+    runtime = KernelRuntime()
+    project_root = resolve_project_root(override=Path(project))
+    return runtime.status(project_root=project_root, session_id=session_id)
+
+
+def execute_code(
+    code: str,
+    project: str | Path = ".",
+    timeout_s: float = 30.0,
+    session_id: str = DEFAULT_SESSION_ID,
+) -> ExecutionResult:
+    runtime = KernelRuntime()
+    project_root = resolve_project_root(override=Path(project))
+    return runtime.execute(
+        project_root=project_root, session_id=session_id, code=code, timeout_s=timeout_s
+    )
+
+
+def stop_kernel(project: str | Path = ".", session_id: str = DEFAULT_SESSION_ID) -> None:
+    runtime = KernelRuntime()
+    project_root = resolve_project_root(override=Path(project))
+    runtime.stop(project_root=project_root, session_id=session_id)
+
+
+def doctor_environment(
+    project: str | Path = ".",
+    *,
+    python_executable: str | Path | None = None,
+    auto_fix: bool = False,
+    session_id: str = DEFAULT_SESSION_ID,
+) -> dict[str, object]:
+    runtime = KernelRuntime()
+    project_root = resolve_project_root(override=Path(project))
+    python_path = Path(python_executable) if python_executable is not None else None
+    return runtime.doctor(
+        project_root=project_root,
+        session_id=session_id,
+        python_executable=python_path,
+        auto_fix=auto_fix,
+    )

agentnb-0.1.0/src/agentnb/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()