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

ASTScribe analyzes source code without executing it:

from astscribe import explain

source = """
import torch

model.eval()
with torch.no_grad():
    outputs = model(inputs)
"""

print(explain(source, style="scientific"))

Output:

Inference procedure

Gradient tracking is disabled for the enclosed operations, so no autograd graph is constructed for computations executed within this context.

The model is explicitly configured in evaluation mode.

A forward pass is performed by invoking the model on the supplied inputs.

For notebook-level structure:

from astscribe import NotebookAnalyzer

notebook = NotebookAnalyzer.from_cells(
    [
        "dataset = load_data()",
        "features = preprocess(dataset)",
        "result = evaluate(features)",
    ]
)

print(notebook.render_dependency_graph())

Output:

# Cell dependency graph

Cell 0 -> Cell 1 [dataset]
Cell 1 -> Cell 2 [features]

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 ranking
astscribe experiment.ipynb --report dependencies --dot

# Structured output for scripts, CI, and jq
astscribe training.py --json
astscribe experiment.ipynb --report diagnostics --json
astscribe experiment.ipynb --report impact --cell 3 --json

# 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

# Return exit status 1 when dependency diagnostics contain warnings
astscribe experiment.ipynb --report diagnostics --fail-on-warning

The same CLI is available as python -m astscribe. Use --json with Python source or any notebook report to emit the underlying structured analysis instead of rendered text. JSON output is deterministic and uses only the Python standard library. For CI validation, --fail-on-warning preserves the selected notebook output while returning 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. 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.