Jupyter Notebook Stamping¶

PrimeStamp can stamp Jupyter notebooks (.ipynb files) to create cryptographic proof of computational research at a specific point in time. This is valuable for reproducible science, intellectual property protection, and audit trails of data analysis.

Quick Start¶

From Python¶

from primestamp.integrations.jupyter import NotebookStamper

stamper = NotebookStamper()

result = stamper.stamp_notebook("analysis.ipynb")
print(f"Notebook hash: {result.content_hash}")
print(f"Cells stamped: {result.cell_count}")
print(f"Executed cells: {result.executed_count}")

From Inside a Notebook¶

# Load the PrimeStamp extension
%load_ext primestamp.integrations.jupyter

# Stamp the current cell
%stamp

# Verify the notebook
%verify

Dependencies¶

pip install ipython jupyter nbformat
# or install with the integrations extra:
pip install "primestamp[integrations]"

Features¶

Notebook-level timestamping (entire .ipynb file)
Cell-level timestamping with execution tracking
Output hashing for reproducibility verification
IPython magic commands (%stamp, %verify)
Metadata integration via notebook and cell metadata
Export stamps alongside notebooks
Support for code, markdown, and raw cells

Cell-Level Stamping¶

Each cell receives an independent stamp:

Field	Description
`cell_index`	Position in the notebook
`cell_id`	Unique cell identifier
`cell_type`	`code`, `markdown`, or `raw`
`content_hash`	SHA-256 hash of the cell source
`output_hash`	SHA-256 hash of cell outputs (code cells only)
`execution_count`	Jupyter execution counter
`status`	`not_executed`, `executed`, `error`, or `modified`

result = stamper.stamp_notebook("analysis.ipynb")

for cell_stamp in result.cell_stamps:
    print(f"Cell {cell_stamp.cell_index} ({cell_stamp.cell_type}):")
    print(f"  Content hash: {cell_stamp.content_hash}")
    if cell_stamp.output_hash:
        print(f"  Output hash: {cell_stamp.output_hash}")
    print(f"  Status: {cell_stamp.status}")

Execution Tracking¶

PrimeStamp detects whether cells have been executed and whether source was modified since last execution:

Status	Meaning
`not_executed`	Cell has no outputs (never run or outputs cleared)
`executed`	Cell has outputs and source is unchanged
`error`	Cell execution produced an error
`modified`	Cell source changed after last execution

Output Hashing¶

For code cells, outputs (text, images, data frames) are hashed separately from source. This enables proving that specific code produced specific results.

cell = result.cell_stamps[3]
print(f"Source hash: {cell.content_hash}")
print(f"Output hash: {cell.output_hash}")

Notebook Metadata¶

Stamp information is stored in the notebook's metadata under the primestamp key:

{
  "metadata": {
    "primestamp": {
      "stamp_id": "ps_abc123...",
      "content_hash": "sha256:...",
      "timestamp": "2025-06-15T10:30:00Z"
    }
  }
}

IPython Magic Commands¶

`%stamp`¶

%stamp          # Stamp the current cell
%stamp notebook # Stamp the entire notebook
%stamp --preset archival

`%verify`¶

%verify         # Verify the entire notebook
%verify cell    # Verify the current cell only

`%stamp_status`¶

%stamp_status
# Cell 0 [code]   : stamped (executed)
# Cell 1 [md]     : stamped
# Cell 2 [code]   : MODIFIED since stamp
# Cell 3 [code]   : not stamped

Stamp Scopes¶

Scope	Description
`notebook`	Hash all cells together into one stamp
`cell`	Stamp individual cells independently
`output`	Stamp only execution outputs
`selection`	Stamp a selected range of cells

# Stamp only cells 5-10
result = stamper.stamp_cells("analysis.ipynb", cell_range=(5, 10))

# Stamp only outputs
result = stamper.stamp_outputs("analysis.ipynb")

CLI Usage¶

# Stamp a notebook
primestamp stamp analysis.ipynb --preset standard

# Verify a notebook
primestamp verify analysis.ipynb

# Show cell-level details
primestamp fingerprint analysis.ipynb --show-cells

# Compare two notebook versions
primestamp fingerprint --compare v1.ipynb v2.ipynb

Reproducibility Workflow¶

Develop -- Write and run your notebook normally
Stamp -- Run %stamp notebook to create a stamp
Share -- Share the notebook (stamp metadata travels with it)
Reproduce -- The recipient runs the notebook
Verify -- The recipient runs %verify to check output hashes match

If output hashes match, there is cryptographic proof of identical results.

JupyterHub Integration¶

For JupyterHub deployments, PrimeStamp provides a server extension that automatically stamps notebooks on save. See primestamp.integrations.jupyterhub for configuration details.

Google Colab Integration¶

PrimeStamp also supports notebooks running in Google Colab. See primestamp.integrations.colab for details.