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

Optional IPython/Jupyter integration:

python -m pip install "astscribe[ipython]"

Quick start

from astscribe import explain

print(explain("""
model.eval()
with torch.no_grad():
    outputs = model(inputs)
""", style="scientific"))

For notebooks:

from astscribe import NotebookAnalyzer

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

ASTScribe only reports claims supported by the source it can inspect.

CLI

astscribe training.py --style concise
astscribe experiment.ipynb --report methodology --evidence
astscribe experiment.ipynb --report diagnostics
astscribe experiment.ipynb --report impact --cell 3
astscribe experiment.ipynb --report dependencies --dot

# Read Python source from stdin
printf 'model.eval()\n' | astscribe - --style concise

# Fail if a notebook contains a code cell that is not valid Python
astscribe experiment.ipynb --report diagnostics --strict

The same CLI is available as python -m astscribe.

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. The scientific renderer uses directly observed, statically resolved, and known-framework claims by default.

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.