# nbskill


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

`nbskill` is notebook-aware tooling for agents and maintainers working
in nbdev projects. It provides focused context, structured edits, safe
execution, and review through a Python Pyskill.

## Why it exists

In nbdev, the notebook is the source of truth. It holds the
implementation, its explanation, examples, outputs, and metadata. Raw
JSON edits are easy to misplace, and changes to generated Python are
overwritten. `nbskill` makes notebook work deliberate and reviewable.

## What it does

Use `nbskill` to find the relevant project, notebook, chapter, cell, or
symbol; edit the right cells; run focused checks in project context; and
review the resulting diff and style.

## What it offers

<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>Need</th>
<th>Tooling</th>
</tr>
</thead>
<tbody>
<tr>
<td>Find the right context</td>
<td><a
href="https://MorsCerta-crypto.github.io/nbskill/read.html#context"><code>context</code></a>
reads a project, notebook, chapter, cell id, or symbol without raw JSON
noise.</td>
</tr>
<tr>
<td>Make focused edits</td>
<td><a
href="https://MorsCerta-crypto.github.io/nbskill/edit.html#edit_notebook"><code>edit_notebook</code></a>
preserves cell structure, validates source, and returns a structured
diff.</td>
</tr>
<tr>
<td>Verify behavior</td>
<td><a
href="https://MorsCerta-crypto.github.io/nbskill/execute.html#exec_nb"><code>exec_nb</code></a>
runs the notebook in project context, with a check-only mode for review
loops.</td>
</tr>
<tr>
<td>Verify a change</td>
<td><a
href="https://MorsCerta-crypto.github.io/nbskill/review.html#diff_nb"><code>diff_nb</code></a>,
<a
href="https://MorsCerta-crypto.github.io/nbskill/execute.html#exec_nb"><code>exec_nb</code></a>,
and <code>doctor</code> show the source change, executed checks, and
diagnostics.</td>
</tr>
<tr>
<td>Review changes</td>
<td><a
href="https://MorsCerta-crypto.github.io/nbskill/review.html#diff_nb"><code>diff_nb</code></a>
and <code>doctor</code> focus on behavior changes and notebook
hygiene.</td>
</tr>
<tr>
<td>Use the library directly</td>
<td>The <code>nbskill.skill</code> Pyskill exposes the curated Python
workflow for an installed project environment.</td>
</tr>
</tbody>
</table>

## Parse notebook cells

Notebook text uses `%%markdown`, `%%code`, and `---` as a compact cell
format.
[`parse_cells`](https://MorsCerta-crypto.github.io/nbskill/foundation.html#parse_cells)
turns that text into notebook cells while preserving each cell’s type
and source.

``` python
cell_text = "\n".join(["%%markdown", "## Demo", "---", "%%code", "value = 42"])
parsed_cells = parse_cells(cell_text)
[(cell.cell_type, cell_source(cell).splitlines()[0]) for cell in parsed_cells]
```

    [('markdown', '## Demo'), ('code', 'value = 42')]

## Read a notebook

Start with the smallest useful view.
[`context`](https://MorsCerta-crypto.github.io/nbskill/read.html#context)
resolves a project, notebook, chapter, cell, or symbol without exposing
notebook JSON. In Python, the first call explains the notebook and the
second follows the public
[`write_nb`](https://MorsCerta-crypto.github.io/nbskill/write.html#write_nb)
symbol to its owning cell and related uses.

``` python
with redirect_stdout(StringIO()): notebook_context = context("02_write.ipynb", mode="overview")
print("\n".join([x['source'] for x in notebook_context["selection"]["markdown"]]))
```

## Python workflow

Load the curated Python workflow through Pyskills:

``` python
from nbskill.skill import *

context("nbs/02_write.ipynb#write_nb", mode="overview")
```

## Use with aai-coding

`aai-coding` owns the persistent Python session, hooks, ordinary Python
files, configuration, and prose. `nbskill.skill` owns notebook source,
generated modules, focused execution, and notebook review.

`install_nbskill --target codex` installs the local `jupyter-notebooks`
skill. It never rewrites an aai-coding checkout or a README.

In an nbdev project, do not use `exhash` or a general editor to mutate a
source notebook or its generated module. Import `nbskill.skill`, call
[`generated_owner`](https://MorsCerta-crypto.github.io/nbskill/foundation.html#generated_owner)
to route a Python file, read with
[`context`](https://MorsCerta-crypto.github.io/nbskill/read.html#context),
query
[`reference_query`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_query)
for nontrivial prior art, make one
[`edit_notebook`](https://MorsCerta-crypto.github.io/nbskill/edit.html#edit_notebook)
change, then prove it with
[`exec_nb`](https://MorsCerta-crypto.github.io/nbskill/execute.html#exec_nb),
[`diff_nb`](https://MorsCerta-crypto.github.io/nbskill/review.html#diff_nb),
and
[`style_check`](https://MorsCerta-crypto.github.io/nbskill/review.html#style_check).

## References

References are a local implementation knowledgebase, not code to copy.
Discover or register repositories with
[`reference_discover`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_discover)
or
[`reference_add`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_add),
ingest them with
[`reference_ingest`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_ingest),
then query them with
[`reference_query`](https://MorsCerta-crypto.github.io/nbskill/knowledge.html#reference_query)
before adding a nontrivial helper. Results combine structured filters,
hybrid BM25/vector search, dependency status, and optional branch
context.

``` python
reference_query(
    query="AST definition helper",
    top_k=5,
    include_branch=True,
)
```

## Graph structure

The local graph records notebooks, cells, headings, symbols, and
imports. Its edges record containment, definitions, calls, imports,
documentation order, and related symbols. Call and import edges carry
evidence separately from heuristic similarity edges.

This gives `nbskill` a fast, project-wide map of the notebook source.
Agents can assess the impact of a change, follow a symbol to its
callers, and spot cross-notebook private-helper use without reading
every notebook. It is a navigation and maintenance aid, not a runtime
dependency analyzer.

Ask for project context with the graph attached when you need to trace a
symbol through the notebook structure:

``` python
context(target="project", scope="nbs", include_graph=True)
```

## Problem-solution memory

Before choosing an approach, query `problem_memory` for similar verified
lessons from this and other projects. After verification, add a reusable
problem-solution pair with short evidence and at least four normalized
tags, such as topic, sub-topic, library, problem category, and solution
category.

Tags make lessons precise enough to reuse: a query with tags applies an
exact all-of filter, while the natural-language problem ranks the
remaining matches. This keeps a broadly similar memory from being
mistaken for a directly applicable solution.

``` python
graph = notebook_knowledge_graph_data("nbs")
dict(nodes=len(graph["nodes"]), edges=len(graph["edges"]), node_types=sorted({node["type"] for node in graph["nodes"]}), edge_types=sorted({edge["type"] for edge in graph["edges"]}))
```

    {'nodes': 3588,
     'edges': 13426,
     'node_types': ['cell', 'heading', 'import', 'notebook', 'symbol'],
     'edge_types': ['calls',
      'contains',
      'defines',
      'documents',
      'imports',
      'precedes',
      'similar_to']}