clever

Converts Quarto chapters into single-language Jupyter notebooks.

Installation

To run clever, you need Python 3.10+ and uv installed. Then, clone the repository:

git clone https://github.com/m3nin0-labs/clever.git

Access the repository downloaded:

cd clever

Finally, you can sync the dependencies:

uv sync

Usage

clever uses an Anthropic model for two small steps, so export your key first:

export CLEVER_ANTHROPIC_API_KEY="sk-ant-..."

Then, point it at a book and pick a language:

uv run clever convert path/to/sitsbook --lang r --out dist/r

Or, for Python:

uv run clever convert path/to/sitsbook --lang python --out dist/py

Each chapter becomes a directory with its notebook, a manifest.json listing every path the code refers to, and copies of the book files it reads:

dist/r/ts_basics/
├── ts_basics.ipynb
├── manifest.json
└── data/samples.csv

To see what a book contains without converting anything:

uv run clever inspect path/to/sitsbook

Configuration

Settings are optional and read from a clever.toml file, environment variables (prefix CLEVER_) or a .env file. Command-line options win over all of them.

book_dir = "path/to/sitsbook"
out_dir = "dist"
language = "r"
model = "claude-sonnet-4"
image_base_url = "https://raw.githubusercontent.com/e-sensing/sitsbook/refs/heads/main/"

Development

uv sync --extra dev
uv run pytest          # run the test suite
uv run ruff check .    # lint
uv run mypy clever     # type-check

Contributing

Contributions are welcome. Please open an issue to discuss significant changes, and ensure tests and linting pass before submitting a pull request.

License

clever is distributed under the GPL-v3.0 license. See LICENSE for the full text.