Narrate Lean
A Python CLI tool that converts Lean 4 proof files into human-readable Markdown documents with natural language explanations.
Features
- Parse Lean 4 proofs: Extracts theorem statements, definitions, hypotheses, and proof steps
- Natural language narration: Uses LLMs to generate clear explanations of mathematical proofs
- LaTeX support: Preserves mathematical notation using LaTeX syntax
- Flexible output: Output to file or stdout
- Customizable: Skip definitions or proof details as needed
Installation
# Install dependencies
uv sync
# Or with pip
pip install -e .
Configuration
Create a .env file with your LLM API configuration:
# For LiteLLM proxy
LITELLM_API_KEY=your-api-key
LITELLM_BASE_URL=http://your-litellm-server:4000
LLM_MODEL=gpt-4.1
# Or for direct OpenAI API
OPENAI_API_KEY=your-openai-key
LLM_MODEL=gpt-4.1
Usage
Basic Usage
Convert a Lean proof file to Markdown:
narratelean narrate input.lean -o output.md
Output to stdout:
narratelean narrate example.lean
Options
-o, --output PATH: Specify output file (default: stdout)--no-definitions: Skip narrating definitions--no-proofs: Skip detailed proof narration (only include theorem statements)--explain-lean: Include explanations of Lean tactics and syntax in the proof (default: pure math only)
Examples
# Narrate the example proof (pure math, no Lean explanations)
uv run narratelean narrate example.lean -o example_output.md
# Include Lean tactics explanations
uv run narratelean narrate example.lean --explain-lean -o example_with_lean.md
# Skip definitions, only narrate theorems
uv run narratelean narrate example.lean --no-definitions -o output.md
# Just theorem statements, no detailed proofs
uv run narratelean narrate example.lean --no-proofs -o statements_only.md
Example Files
This repository includes a complete example demonstrating the tool's capabilities:
- example.lean - A Lean 4 proof of the Sequence Squeeze Theorem using Mathlib
- example_output.md - The generated human-readable mathematical proof in Markdown format
The example showcases:
- Custom definition (
seq_converges_to) with natural language explanation - Formal theorem statement with hypotheses and conclusion
- Step-by-step proof narrative in mathematical paper style
- Proper LaTeX notation compatible with KaTeX rendering
Development
Running Tests
make test
Code Quality
# Format code
make format
# Lint code
make lint
# Type check
make type
# Run all checks
make all
Project Structure
src/narratelean/parser.py- Lean 4 file parsersrc/narratelean/narrator.py- LLM-based proof narration enginesrc/narratelean/markdown.py- Markdown document generatorsrc/narratelean/cli.py- Command-line interface
License
MIT
Metadata
Release files for narratelean 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| narratelean-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for narratelean-0.1.1-py3-none-any.whl |
Release files / narratelean-0.1.1-py3-none-any.whl
| Download URL | narratelean-0.1.1-py3-none-any.whl |
|---|---|
| Size | 11.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6ef37402b312320ac4786446b55b910786362647b82a1902b22402e17ff4e3b4
|
|
BLAKE2b-256 checksum How to use checksums |
fbbd41569a84fa933d59464eba0b6f2708ef8a51f574a0ba0b39b43e6b015fba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.17 {"installer":{"name":"uv","version":"0.9.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for narratelean 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.