# slmn


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

## What’s inside

slmn is a small collection of independent tools, each in its own
notebook/module:

<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>module</th>
<th>what it does</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="nbtools.html"><code>nbtools</code></a></td>
<td>read, grep, and edit Jupyter notebook cells by id – no hand-rolled
JSON surgery</td>
</tr>
<tr>
<td><a href="misc.html"><code>misc</code></a></td>
<td>read a PDF’s text; check whether a local GPU is free</td>
</tr>
<tr>
<td><a href="remote.html"><code>remote</code></a></td>
<td>launch and monitor background jobs on a remote host over ssh; fetch
a URL; check a repo’s GitHub CI</td>
</tr>
<tr>
<td><a
href="publish.html">[<code>publish</code>](https://drscotthawley.github.io/slmn/publish.html#publish)</a></td>
<td>automate the nbdev edit-&gt;ship loop: clean/export, a reviewed
commit, push, wait for CI, and (on a feature branch) merge a PR to
main</td>
</tr>
<tr>
<td><a href="dead_drop.html"><code>dead_drop</code></a></td>
<td>file-based async IPC – one side drops a message file, another picks
it up (with a streaming variant)</td>
</tr>
<tr>
<td><a href="cli.html"><code>cli</code></a></td>
<td>the <code>slmn &lt;tool&gt; [args...]</code> dispatcher that exposes
all of the above from the shell</td>
</tr>
<tr>
<td><a href="mcp.html"><code>mcp</code></a></td>
<td>an <em>optional</em> server exposing the same tools to any MCP
client (<code>slmn-mcp</code>)</td>
</tr>
</tbody>
</table>

Every tool is a plain, type-hinted function. That single definition is
what the CLI turns into command-line flags and what the MCP server turns
into a tool schema – so the three ways to call a tool (below) never
drift apart.

## Installation

slmn isn’t on PyPI or conda yet, so install it from GitHub. The default
install is “lite” – just the tools and the `slmn` CLI:

``` sh
pip install git+https://github.com/drscotthawley/slmn.git
```

The MCP server is optional; add the `mcp` extra if you want it (it pulls
in `fastmcp` and friends):

``` sh
pip install "slmn[mcp] @ git+https://github.com/drscotthawley/slmn.git"
```

## How to use

The same tools are reachable three ways.

**Import them directly:**

``` python
from slmn.nbtools import grep_nb
print(grep_nb('nbs/01_nbtools.ipynb', 'def read_nb'))
```

**From the shell**, via the `slmn` dispatcher (run `slmn` with no
arguments for the tool list):

``` sh
slmn grep_nb nbs/01_nbtools.ipynb 'def read_nb'
slmn gpu_free
```

**Over MCP** (with the `mcp` extra installed), registered with any
MCP-speaking client:

``` sh
claude mcp add slmn -- slmn-mcp
```

## Documentation

Full documentation is hosted on the project’s GitHub
[pages](https://drscotthawley.github.io/slmn/); the source for each page
is the correspondingly-named notebook under `nbs/`.

## For developers

slmn is built with [nbdev](https://nbdev.fast.ai/): the notebooks under
`nbs/` are the source of truth, and the `slmn/` package is generated
from them. To hack on it, install in editable mode:

``` sh
git clone https://github.com/drscotthawley/slmn.git
cd slmn
pip install -e ".[mcp]"
```

Edit the notebooks, then regenerate the package, run the tests, and ship
– all via slmn’s own
[`publish`](https://drscotthawley.github.io/slmn/publish.html#publish)
tool (nbdev-clean/export -\> reviewed commit -\> push -\> wait for CI
-\> merge a PR to main):

``` sh
slmn publish "your commit message"
```

``` python
from slmn.misc import gpu_free
gpu_free()
```

    2