# Jupyter Notebook versus K2F

The **K2F format** operates on a dual-state architecture: an editable, declarative semantic JSON tree (State A) and a compiled, **pixel stable lock** (`document.K2F.lock` / State C) packaged inside a self-contained ZIP archive. While Jupyter Notebook delegates layout, typography, and visual styling dynamically to host application stylesheets and client browser rendering engines—producing fluid, viewport-dependent reflow without native concepts of physical pages, margins, running headers, or print-ready bounding boxes—K2F compiles semantic intent into deterministic geometry using a dedicated Rust reference layout engine (`k2f_layout`), strictly isolating content meaning from visual theme primitives and mandating embedded fonts.

K2F is not a lossless superset of Jupyter Notebook. K2F v0.1 strictly prohibits executable scripts, computational kernels, and dynamic programming runtimes: it cannot execute Python, R, or Julia code, evaluate live expressions, cache in-memory data states, or run interactive client-side JavaScript widgets (`ipywidgets`, Plotly). In addition, K2F v0.1 ships with a fixed `"paged"` canvas mode (slide presentations and infinite canvas modes are roadmap design targets), does not natively import or parse `.ipynb` files, does not import PDF or Word documents (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`), and forbids arbitrary programmatic vector path drawing in State A JSON (external graphics must be stored as pre-rendered SVGs or images in `/assets/`). Bringing notebook content into K2F requires an external extraction step to convert code and figures into Markdown, which is then ingested via K2F's Markdown bridge (`k2f markdown`) with an author template shell. All export formats derived from K2F are unidirectional, read-only deliverables rendered from the compiled render lock rather than round-trip sources of truth (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`).

## At a glance

| Topic | Jupyter Notebook | K2F |
| :--- | :--- | :--- |
| What the file *is* | Uncompressed JSON computational document (`.ipynb`, nbformat v4.5+) interleaving code, markdown, metadata, and execution output bundles | Declarative semantic JSON tree (State A) + compiled render lock (State C) in a ZIP archive |
| Primary authoring model | Interactive REPL computing, step-by-step data analysis, and exploratory prototyping across web and desktop notebook environments | Programmatic authoring, inspection, and patching by AI agents and automated code pipelines |
| Computational execution | Native execution of live code (Python, R, Julia) via background kernels communicating over ZeroMQ sockets | Prohibited: no runtime kernel, script execution, or dynamic evaluation; stores finalized semantic content only |
| Physical page geometry | Zero concept of physical pages, paper sizes (A4, Letter), margins, columns, running headers/footers, or spatial bounding boxes | Explicit paged canvas geometry, margin definitions, multi-column stacks, page budgets, card containers, and running headers/footers |
| Rendering architecture | Runtime layout computed by client web browsers (DOM/CSS) or export toolchains (`nbconvert` delegating to LaTeX or Chromium) | Dual-state model: reference engine compiles deterministic geometry; viewers paint `document.K2F.lock` directly without reflowing text |
| Pixel-stable pages & fonts | Non-pixel-stable; reflows per viewport; relies on system fonts; client themes override styling; PDF export cleaves code and tables arbitrarily | Yes — viewers paint the lock directly; mandatory embedded fonts guarantee cross-device pixel stability |
| Node addressing for AI | Random hex/UUID cell IDs (nbformat 4.5+); opaque, coarse container-level; no IDs for paragraphs, code lines, or table cells | Mandatory, hierarchical dotted IDs (`parent_id.child_type_semantic_name`) on every semantic node in State A |
| Execution state & synchronization | Prone to "hidden state" and stale outputs: modifying code without execution leaves conflicting visual outputs; stripping outputs loses deliverables | Guaranteed synchronization: State A compiles deterministically into State C geometry lock; verified via `pack_verify.py` |
| Separation of concerns & styling | Zero format-level styling abstraction or design tokens; visual appearance is dictated by host CSS or injected inline HTML/CSS | Strict separation: zero styling on State A nodes; visual primitives live exclusively in `styles/theme.json` |
| Theming & global restyling | Overridden by host viewer themes (JupyterLab, VS Code, Colab, GitHub); no centralized theme schema for whole-document restyling | Single token change in `styles/theme.json` restyles entire document deterministically upon recompilation |
| Version control & Git diffs | Noisy Git diffs: inline Base64 plot binaries, execution counters, metadata timestamps, and string/array source splits cause merge conflicts | Git-native Canonical JSON (sorted keys, 2-space indentation); clean semantic diffs; images stored externally in `assets/images/` |
| Interactive widgets & media | Rich interactive JavaScript widgets (Plotly, Bokeh, ipywidgets); plots stored as inline Base64 PNGs or vector SVGs | Interactive JS prohibited; static vector/raster images in `/assets/`; native `form_field` compiles to AcroForms |
| Vector graphics & art | Dynamic programmatic plot generation (Matplotlib, Seaborn) embedded as Base64 raster or inline SVG in output MIME bundles | Forbidden in State A JSON; external vector graphics stored as pre-rendered SVGs or images in `/assets/` |
| Multi-format publishing | Relies on `nbconvert` to generate static HTML, LaTeX, PDF, or slides; frequent formatting breakage and orphan code blocks | Single-source lock-drawn exports to PDF (with AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and InDesign (`.idml`) |
| Integrity & signatures | Local HMAC-SHA256 signature database for untrusted HTML/JS mitigation; zero portable cryptographic signatures or tamper evidence in `.ipynb` | Dual-hash architecture (`content_hash`, `appearance_hash`), Ed25519 signatures, mandatory viewer banner (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, `UNLOCKED`) |
| Verification tooling | nbformat schema validators (`jsonschema`); verifies JSON structure, not visual layout or output synchronization | Automated schema validation via `pack_verify.py` (validating embedded `/schema/`) and visual defect detection (`PAGE_UNDERFILL`) |
| Headless / Automation API | Papermill CLI, `nbclient`, and `jupyter_client` Python API for headless batch execution and parameter injection | Native offline CLI (`pip install k2f`), Python SDK, Rust crates, and stdio MCP; remote HTTP MCP is Not publicly specified |
| Import / Source of truth | De facto editable source in data science; Jupytext sync; K2F does not import `.ipynb` (requires Markdown bridge) | `.K2F` is sole source of truth; K2F does not import Jupyter or PDF (`*_IS_NOT_A_SOURCE`); exports are unidirectional lock renderings |

## Jupyter Notebook vs K2F: What Jupyter Notebook is good at

Jupyter Notebook is the undisputed global standard for interactive computing, exploratory data science, and computational research. Its core strengths include:

- **Interactive exploratory data science and rapid prototyping:** Jupyter Notebook provides an unparalleled environment for step-by-step data analysis, feature engineering, and statistical modeling with libraries like Pandas, Polars, NumPy, and SciPy. Authors can run an expensive data loading or model evaluation step once, cache the resulting DataFrame or tensors in kernel memory, and iteratively refine downstream visualizations without re-executing the entire script.
- **Stateful REPL execution and runtime debugging:** Code is executed against an active background kernel (IPython for Python, IRkernel for R, IJulia for Julia, or over 100 community kernels) over ZeroMQ sockets using the Jupyter Messaging Protocol. Users inspect stdout, stderr, and variable states interactively, diagnosing and resolving runtime errors immediately beneath the code cell that produced them.
- **Computational research and scientific reproducibility:** Jupyter Notebook is the foundational medium for reproducible research, machine learning benchmarks, academic coursework, and open-source tutorials (e.g., PyTorch, TensorFlow, Scikit-Learn, Hugging Face model demonstrations, and Kaggle competitions). Readers can inspect the exact code that generated a scientific figure and re-execute the notebook to verify computational results.
- **Rich interactive visualizations and dynamic widgets:** The format natively accommodates dynamic client-side web visualizations: interactive 3D molecular structures (NGLview), interactive geographic maps (Folium, Leaflet), dynamic drill-down dashboards (Plotly, Bokeh, Altair), and interactive GUI sliders and controls (`ipywidgets`).
- **Seamless cloud compute and hardware acceleration:** Notebook environments integrate directly with managed cloud runtimes and remote GPU/TPU clusters across Google Colaboratory, Kaggle Kernels, Amazon SageMaker Studio, Databricks, and Azure ML. Document authoring is directly fused with heavy computational infrastructure.
- **Parameterized batch execution pipelines (Papermill):** Through tools like Papermill, notebooks serve as executable production jobs. Automated systems inject runtime arguments (e.g., dates, customer IDs, model hyperparameters), run the notebook headlessly in CI/CD pipelines, and preserve the executed outputs as immutable audit artifacts.
- **Premier execution sandbox for AI coding agents:** Modern AI coding assistants (ChatGPT Advanced Data Analysis / Code Interpreter, Claude Code, Cursor) use Jupyter execution containers as their primary computational workbench. Agents solve complex data tasks by writing code, executing it in a live REPL, inspecting stdout, stderr, and visual plots, and iteratively debugging errors in real time.

## What K2F adds

K2F is designed for workflows where automated systems and AI agents require deterministic structure, verifiable rendering, and multi-format delivery:

- **Declarative semantic tree & stable dotted IDs:** Every node in State A (`content/root.json`) carries a mandatory, hierarchical dotted ID (format: `parent_id.child_type_semantic_name`, e.g., `financials.q3_results.table_revenue`, `contract.clauses.clause_4_indemnity`). AI agents target, read, patch, diff, and revert specific content nodes deterministically without scraping visual coordinates, parsing arbitrary text blocks, or relying on fragile regex matching within multi-line strings. Long documents can be modularized via explicit `{ "include": "content/sub_section.json" }` fragments in container `children`.
- **Deterministic layout compilation & pixel-stable lock (`document.K2F.lock`):** K2F pairs an editable semantic tree with a compiled render lock (State C). The Rust reference layout engine (`k2f_layout`) calculates exact physical coordinates using HarfBuzz text shaping (`rustybuzz`), Unicode line breaking (UAX #14), and IEEE-754 math layout. Official viewers (`<k2f-viewer>`, Desktop Reader, Playground) paint the published lock directly without running layout or reflowing body text in the browser, guaranteeing PDF-grade visual consistency.
- **Mandatory embedded fonts & elimination of visual drift:** Jupyter Notebook relies entirely on local system fonts or host web fonts, causing typography, glyph advances, and line breaks to drift across operating systems. K2F mandates complete embedded fonts in `assets/fonts/` and strictly prohibits system font fallbacks, ensuring identical rendering on every machine.
- **Strict intent-presentation separation & global restyling:** Jupyter Notebook lacks any format-level styling abstraction, forcing authors to inject non-standard inline HTML/CSS or rely on host application themes. K2F strictly forbids inline styling on State A nodes; appearance is governed entirely by named design primitives in `styles/theme.json`. Content nodes reference appearance via semantic roles, variants, and closed-enum modifiers with UTF-8 byte ranges (`emphasis`, `link`, `math`). A single prompt or theme token edit restyles an entire document deterministically upon recompilation without layout drift.
- **Paged document architecture & graphic design primitives:** K2F natively handles multi-column layouts, page sheet fills (`box_decoration.background`), page budgets, card containers, elevation/shadow atoms, rounded corners, glassmorphism, running headers, and running footers without leaking presentation into content. In contrast, Jupyter Notebook is restricted to a single vertical scroll stream that breaks chaotically across pages when converted to PDF.
- **Git-native Canonical JSON & clean version control:** Jupyter Notebooks produce noisy Git diffs due to embedded Base64 image strings, shifting execution counters, and metadata timestamps. K2F source trees are maintained as Canonical JSON (alphabetically sorted keys, 2-space indentation) with images stored as standalone files in `assets/images/`, enabling AI agents and human engineers to review clean semantic diffs, resolve merge conflicts, and audit changes node by node.
- **Guaranteed state synchronization (No "hidden state" or stale outputs):** In Jupyter Notebook, editing code without running it leaves existing outputs frozen, producing discrepancies where displayed charts contradict the updated code. In K2F, State A always compiles deterministically into the State C geometry lock, eliminating out-of-order execution states and stale outputs entirely.
- **Automated package verification (`pack_verify.py`):** K2F packages embed formal JSON schemas in `/schema/`. The stdlib-only `pack_verify.py` script and CLI `k2f pack` validate structural rules, font coverage, and modifier constraints. When run with `--render`, the compiler rasterizes pages to preview PNGs and detects visual defects such as `PAGE_UNDERFILL` (flagging when content fails to fill the lower third of a designed page), enabling agents to self-correct layout issues before delivery.
- **Dual-hash cryptographic integrity & mandatory viewer banner:** Jupyter's trust model is confined to a local HMAC database on the author's machine, providing zero portable tamper evidence. K2F implements a built-in cryptographic integrity architecture: `content_hash` hashes the canonical semantic tree, while `appearance_hash` binds content, theme primitives, embedded fonts, canvas setup, and the pinned reference engine identity (`engine_commit_sha`). Official readers enforce a mandatory integrity banner reporting five canonical states (`SIGNED`, `UNSIGNED`, `SIGNED_BUT_BROKEN`, `BROKEN_INTEGRITY`, `UNLOCKED`), while reporting layout engine discrepancies (`ENGINE_MISMATCH`). Ed25519 digital signatures can be attached via `signatures/v1.json`.
- **Native fillable PDF forms (AcroForm):** K2F's `form_field` semantic nodes compile directly into interactive AcroForm PDF fields upon export, bridging agent-generated form logic with universal PDF distribution without drawing non-functional visual underscores (`____`).
- **Single-source multi-format publishing:** A single `.K2F` document compiles once to produce lock-drawn deliverables for PDF (with interactive AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and Adobe InDesign (`.idml`). In contrast, Jupyter's `nbconvert` pipelines frequently produce broken LaTeX or unstyled HTML that requires heavy manual post-processing. Under K2F's architectural rules, exports are unidirectional drawings of the render lock, not editable sources (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`).
- **Agent tooling and template ecosystem:** K2F provides an official agent skill implementing the `agent_v0` authoring dialect, native CLI (`pip install k2f`), and a public [Gallery](/gallery) of 469+ templates on [k2f.dev](https://k2f.dev) with multi-format downloads (`.K2F`, `.docx`, `.pptx`, `.idml`) without requiring accounts, logins, or subscriptions.

## When to pick which

- **Pick Jupyter Notebook when:**
  - Conducting interactive data science, exploratory data analysis, statistical modeling, or machine learning engineering with live code.
  - Workflows require active kernel execution, in-memory state caching, interactive debugging, or remote GPU/TPU acceleration (Colaboratory, SageMaker, Databricks).
  - Authoring computational research papers, tutorials, or educational assignments where code transparency and direct execution by readers are paramount.
  - Building interactive visual dashboards with dynamic client-side JavaScript widgets (Plotly, Bokeh, ipywidgets).
  - Executing parameterized automated pipelines using Papermill.
  - Providing an execution sandbox for AI coding assistants that iteratively generate, execute, and debug code via terminal outputs and stack traces.

- **Pick K2F when:**
  - Producing formal, boardroom-ready, paged deliverables (executive summaries, financial analyses, contracts, proposals, invoices, whitepapers, certificates, planners) that demand exact typography, page budgets, and print-ready presentation.
  - Autonomous AI agents and automated code pipelines must programmatically inspect, target, patch, and validate document content using stable dotted node IDs without fragile regex string scraping or array index drift.
  - Documents demand cross-device, cross-platform pixel stability via embedded fonts and a compiled geometry lock (`document.K2F.lock`), avoiding viewport-dependent reflow and chaotic PDF export page breaks.
  - Publishing from a single source of truth to PDF (with interactive AcroForms), Microsoft Word (`.docx`), PowerPoint (`.pptx`), and Adobe InDesign (`.idml`) simultaneously.
  - Documents require Git-native semantic version control without Base64 binary noise, theme-driven restyling without layout shifts, and tamper-evident cryptographic integrity banners.

- **Bridging Jupyter Notebook and K2F (The Complementary Pipeline):**
  - Jupyter Notebook and K2F are not mutually exclusive; they form a natural end-to-end data pipeline. Data scientists and AI agents perform computational analysis, model training, and visualization generation inside Jupyter; an automated script or agent exports the narrative and generated figures to Markdown (`nbconvert --to markdown` or Jupytext); and K2F's Markdown bridge (`k2f markdown`) attaches an author directory and embedded fonts to compile a pixel-stable, branded, boardroom-ready report. Deliverables exported from K2F are unidirectional drawings of the compiled render lock, not editable sources of truth (`PDF_IS_NOT_A_SOURCE`, `DOCX_IS_NOT_A_SOURCE`, `PPTX_IS_NOT_A_SOURCE`, `IDML_IS_NOT_A_SOURCE`). All authoritative structural edits occur in K2F State A.

## Bottom line

Jupyter Notebook and K2F serve distinct, non-overlapping stages in data science and technical publishing. Jupyter Notebook is the global benchmark for interactive computation, REPL-driven analysis, and executable research. However, computational notebooks lack the paged geometry, embedded typography, and layout constraint solvers required for publication-ready documents.

K2F provides the missing publication master for automated and agent-driven document workflows. By separating semantic intent from deterministic geometry through a dual-state architecture, K2F allows teams to transform raw analysis and extracted figures into pixel-stable, boardroom-ready deliverables across PDF, Word, PowerPoint, and InDesign. Rather than choosing between them, data teams can pair Jupyter Notebook as the computational engine with K2F as the final publishing compiler.

For additional details on K2F architecture, explore the technical [documentation](/docs), review pre-built templates in the [Gallery](/gallery), read [why K2F exists](/why), or view the full matrix on [Compare](/compare).

This comparison is based on publicly available information at the time of writing. Capabilities, pricing, and policies may change; verify details with the relevant provider.