scitex-notebook 0.1.1

Jupyter notebook verification, compilation, and DAG-based conversion for the SciTeX ecosystem

SciTeX Notebook (scitex-notebook)

Jupyter notebook verification, compilation, and DAG-based conversion

---

Interfaces: Python ⭐⭐⭐ · CLI ⭐⭐ · MCP ⭐⭐ · Skills ⭐⭐ · Hook — · HTTP —

Problem and Solution

#	Problem	Solution
1	Cell order lies — on-disk .ipynb cell sequence has no relationship to execution order, so naive jupyter nbconvert produces scripts that don't run	DAG from timestamps — reconstructs the true execution dependency graph from scitex-clew session timestamps, then emits a topologically-ordered .py or a Mermaid diagram
2	Silent untracked I/O — scitex.io.save/load calls outside @stx.session leave no reproducibility trail, but nothing warns you	check_notebook() — scans for untracked I/O and flags cells that bypass session tracking
3	Exploration vs. production gap — notebooks let you iterate freely, but shipping means rewriting by hand into a clean script	"Do what you want, organize later" — execute cells in any order while exploring; compile_notebook(...).to_script() emits the production-ready DAG-ordered script

Problem

Jupyter notebooks can be executed in any cell order. The on-disk cell sequence often has no relationship to the actual execution dependency graph. Traditional notebook-to-script converters assume linear order and produce broken scripts.

Solution

scitex-notebook records actual execution order via scitex-clew timestamps, then reconstructs the dependency DAG afterward. "Do what you want, organize later."

• Verify clew sessions for a notebook (reproducibility check)
• Check for scitex.io calls missing @scitex.session decoration
• Compile execution history into a Mermaid DAG or topologically-sorted .py
• Convert .ipynb to a SciTeX Python script (per-cell or unified main())

Installation

Requires Python >= 3.10.

pip install scitex-notebook

Optional extras:

pip install "scitex-notebook[mcp]"     # MCP server for AI agents
pip install "scitex-notebook[linter]"  # IO-call conversion via scitex-linter
pip install "scitex-notebook[all]"     # everything

Quickstart

Python API

import scitex_notebook as notebook

cells    = notebook.parse_notebook("experiment.ipynb")
issues   = notebook.check_notebook("experiment.ipynb")     # untracked IO
results  = notebook.verify_notebook("experiment.ipynb")    # via clew DB
compiled = notebook.compile_notebook("experiment.ipynb")

print(compiled.to_mermaid())   # Mermaid DAG diagram
print(compiled.to_script())    # DAG-ordered Python script

notebook.convert_notebook(
    "experiment.ipynb",
    output="experiment.py",
    mode="unified",            # or "per_cell"
)

CLI

scitex-notebook verify experiment.ipynb
scitex-notebook check experiment.ipynb
scitex-notebook compile experiment.ipynb --format mermaid
scitex-notebook compile experiment.ipynb --format script -o experiment.py
scitex-notebook convert experiment.ipynb --mode unified -o experiment.py

MCP Server — for AI Agents

Tool	Description
notebook_verify	Verify clew sessions for a notebook
notebook_check	Flag untracked scitex.io calls
notebook_compile	Return Mermaid DAG / script / JSON
notebook_convert	Convert .ipynb to .py

python -m scitex_notebook.mcp_server

Dependencies

• Required: scitex-clew — execution-order reconstruction via timestamped sessions.
• Optional: scitex-linter — advanced IO-call rewriting during conversion.

Part of SciTeX

SciTeX Notebook is part of SciTeX.

The SciTeX system follows the Four Freedoms for Research below, inspired by the Free Software Definition:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.