jellycell

What It Is#

jellycell is a reproducible-analysis notebook tool. Notebooks are plain .py files in jupytext percent format (# %% tags=[...]); cells are cached by the content hash of their body plus declared deps=; reruns hit the cache in milliseconds. A live HTML viewer serves the rendered site; export tearsheet produces committed markdown summaries.

Why It Matters#

Jupyter notebooks drift. Re-running a 6-month-old notebook rarely works. Outputs depend on kernel state, in-memory variables, and whatever cells ran in whatever order. jellycell enforces plain-text source, explicit cell dependencies, and a content-addressed artifact store so "run again in six months" is a one-command exercise — and the artifacts it emits (JSON, parquet, figures, tables) are designed to be committed to git.

What Ships in 1.4#

• jellycell.tearsheets Python API (new in 1.4) — jt.findings(), jt.methodology(), jt.audit() callable from inside a jc.step cell, so the rendered manuscript lives in the cache graph. Stable template_overrides make regens byte-identical.
• Plain-text notebooks — jupytext percent format (.py), diff-able in git, authored in any editor
• Content-addressed cache — per-cell hash keyed by body + deps= + upstream artifact hashes; stale cells re-run, unchanged cells hit cache in < 100 ms
• Cell tags — jc.load, jc.step, jc.table, jc.figure structure the DAG; results emitted via jc.save(obj, path, caption=...) and jc.table(df, name=..., caption=...)
• HTML viewer — jellycell view serves the rendered site at localhost:5179 with file-watching
• Tearsheet export — jellycell export tearsheet <notebook> produces a committed markdown summary for each notebook
• Polyglot-monorepo docs — jellycell prompt --write --nested drops AGENTS.md + CLAUDE.md scoped to the notebook subtree; plays nice with TS/Next.js repos
• Scaffolders — jellycell init for a project, jellycell new for a notebook

Ecosystem Fit#

factor-factory >= 1.0 ships a factor_factory.jellycell subtree with canonical cell patterns, figure adapters, and tearsheet payload shapes. Every showcase under packages/python-showcase/ in this repo is a jellycell project. subway-access >= 0.5 uses jellycell for its engine-audit appendix. The jellycell prompt --write --nested recipe is how we keep polyglot-monorepo agent docs current across 4+ languages.

When to Reach For It#

• Any data-science analysis where "still works next year" matters
• Research work that ships committed tearsheets + artifacts
• Replacing a .ipynb whose kernel state is the bottleneck
• Polyglot repos where Python notebooks coexist with TS/Node/Rust tooling