# 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:

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

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