jellycell.run.runner

The :class:Runner — orchestrates per-cell execution, caching, manifests.

Spec §2.5 / §3:

• Parse notebook (format.parse).

• Iterate cells in source order.

• For each cell, compute a cache key from source + declared deps + env_hash.

• Cache hit → load manifest, skip execution.

• Cache miss → execute via :class:~jellycell.run.kernel.Kernel, capture outputs, diff the artifacts dir for new files, build manifest, store.

The runner installs a small setup prelude before each cell so jc.* inside the kernel sees a live :class:~jellycell.run.context.RunContext.

Module Contents

Classes

CellError	Structured error details surfaced on a failed CellResult.
CellResult	Per-cell outcome for the run report.
LargeArtifactWarning	One artifact that exceeded [artifacts] max_committed_size_mb.
RunReport	JSON schema for jellycell run --json. Spec §10.1 contract.
Runner	Executes a jellycell notebook through a subprocess kernel, with caching.

API

class jellycell.run.runner.CellError(/, **data: Any)

Bases: pydantic.BaseModel

Structured error details surfaced on a failed CellResult.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

ename: str

None

evalue: str

None

traceback: list[str]

‘Field(…)’

class jellycell.run.runner.CellResult(/, **data: Any)

Bases: pydantic.BaseModel

Per-cell outcome for the run report.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

cell_id: str

None

cell_name: str | None

None

status: Literal[ok, jellycell.run.runner.CellResult.error, cached, skipped]

None

cache_key: str | None

None

duration_ms: int

None

error: jellycell.run.runner.CellError | None

None

Populated when status == "error". Optional, additive field (§10.1 safe).

class jellycell.run.runner.LargeArtifactWarning(/, **data: Any)

Bases: pydantic.BaseModel

One artifact that exceeded [artifacts] max_committed_size_mb.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

path: str

None

size_mb: float

None

limit_mb: int

None

cell_id: str

None

cell_name: str | None

None

class jellycell.run.runner.RunReport(/, **data: Any)

Bases: pydantic.BaseModel

JSON schema for jellycell run --json. Spec §10.1 contract.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

schema_version: int

1

notebook: str

None

cell_results: list[jellycell.run.runner.CellResult]

‘Field(…)’

total_duration_ms: int

0

status: Literal[ok, error]

‘ok’

large_artifacts: list[jellycell.run.runner.LargeArtifactWarning]

‘Field(…)’

Per-run soft warnings — artifacts above max_committed_size_mb.

Additive, optional field (§10.1 safe). Consumers that ignore it keep working unchanged.

class jellycell.run.runner.Runner(project: jellycell.paths.Project, *, kernel_pool: jellycell.run.pool.KernelPool | None = None)

Executes a jellycell notebook through a subprocess kernel, with caching.

Pass kernel_pool to reuse a kernel across multiple runs (see

Class:

jellycell.run.pool.KernelPool). Default is a fresh kernel per run for isolation.

Initialization

run(notebook_path: pathlib.Path, *, force: bool = False, kernel_name: str | None = None) → jellycell.run.runner.RunReport

Execute all cells in notebook_path. Returns a :class:RunReport.

close() → None

Close underlying resources.