ASTScribe

Evidence-backed scientific explanations for ML notebooks, without LLMs.

ASTScribe statically analyzes Python and Jupyter notebooks and turns supported ML operations into deterministic, traceable explanations.

No LLMs. No API keys. No code execution. No telemetry.

Install

python -m pip install astscribe

For Jupyter/IPython:

python -m pip install "astscribe[ipython]"

Python

from astscribe import explain

print(explain("import torch\nwith torch.no_grad():\n    output = model(inputs)"))

ASTScribe analyzes the source without executing it.

Jupyter / IPython

Load the extension once, then explain any executed input by its In[n] number:

%load_ext astscribe.ipython
%scribe 4
%scribe 7 concise

%scribe N rebuilds forward-only static context from earlier Python inputs and explains In[N]. IPython-only syntax acts as a conservative context boundary because ASTScribe does not execute or infer its runtime side effects.

To explain the cell you are writing:

%%scribe concise
with torch.no_grad():
    output = model(inputs)

The %%scribe body is analyzed, not executed.

Notebook files

from astscribe import NotebookAnalyzer

notebook = NotebookAnalyzer.from_ipynb("experiment.ipynb")
print(notebook.render_methodology())

Other notebook reports include dependencies, diagnostics, impact, impact ranking, experiment pipelines, and composite techniques.

CLI

astscribe training.py --style concise
astscribe experiment.ipynb --report methodology
astscribe experiment.ipynb --report diagnostics --json
astscribe experiment.ipynb --report impact --cell 3

The same CLI is available as python -m astscribe. Use --strict to reject notebook code cells that are not valid Python and --fail-on-warning to return status 1 when dependency diagnostics contain warnings.

Supported semantics

ASTScribe has first-class static semantics for PyTorch, Hugging Face Transformers, Hugging Face Datasets, and PEFT. It can reconstruct notebook methodology, experiment pipelines, cross-cell dependencies, diagnostics, impact, and conservative composite techniques such as QLoRA.

Generated claims retain source provenance and an evidence level. Detailed contracts and limitations live in docs.

Development

python -m pip install -e ".[dev]"
pytest
ruff check .
mypy src/astscribe

See CONTRIBUTING.md and docs/releasing.md.

License

Apache License 2.0. See LICENSE.