Interactive Execution¶

Interactive execution evaluates complete Kedi fragments against one persistent, process-local runtime. It is useful for terminal exploration, notebooks, debuggers, and hosts that need to submit code incrementally without replaying earlier cells.

Kedi exposes the same execution model through two surfaces:

kedi.interactive() creates a session for Python hosts.
kedi --idle starts a terminal REPL backed by that session.

Normal file execution is unchanged. Interactive execution is an additional surface, not a replacement for compile_program(...).run_main().

Python API¶

Create sessions with kedi.interactive() and execute one complete fragment at a time:

import kedi


with kedi.interactive() as session:
    session.execute("[base: int] = `40`")
    session.execute(
        """
@add_two() -> int:
    = `base + 2`
""".strip()
    )
    assert session.execute("= `add_two()`") == 42

The second and third fragments can read declarations and values created by the first fragment. Values, procedures, types, imports, profiles, directives, conversation state, and artifacts remain available until the session closes. Earlier fragments are neither concatenated nor executed again.

Results¶

InteractiveSession.execute() uses the same native-value boundary as KediRuntime.run_main():

a native return such as = `value` returns the underlying Python value;
a rendered return such as = <value> returns rendered text;
a fragment without a top-level return returns None.

This distinction means an int remains an int; interactive execution does not implicitly stringify results.

Source Identity and Imports¶

Every fragment gets a unique source name such as <interactive:1>. That name appears in parse diagnostics and Kedi stack traces. A host can supply a more useful identity:

with kedi.interactive(cwd="examples/cells") as session:
    result = session.execute(
        "> import: helpers\n= `answer`",
        source_name="answer.kedi",
    )

A real source_name becomes the base for relative imports. Synthetic names use the session's cwd, which defaults to the process working directory. Source names must be unique within a session so diagnostics cannot ambiguously refer to two fragments.

Configuration¶

kedi.interactive() accepts the same model, adapter or agent, system prompt, effort, settings, tools, environment, MCP, approval, skills, artifacts, conversation, and parallel-execution inputs as the other high-level Python API surfaces. It also accepts an executor, execution engine, cwd, and subagent limits.

Configuration is resolved when the session is created. The session owns the runtime assembled from that configuration; later calls to kedi.configure() do not rebuild an existing session.

Durable Snapshots¶

kedi.dump_session(session, path) writes a pickle-free snapshot only when the complete logical session can be restored without replaying executable cells. Restore it with kedi.load_session(path). The corresponding InteractiveSession.dump() and InteractiveSession.load() methods expose the same operations:

from pathlib import Path

import kedi


snapshot = Path("work.kedi-state")
with kedi.interactive() as session:
    session.execute("[base: int] = `40`")
    session.execute(
        """
@add_two() -> int:
    = `base + 2`
""".strip()
    )
    kedi.dump_session(session, snapshot)

with kedi.load_session(snapshot) as session:
    assert session.execute("= `add_two()`") == 42

The operation is strict and all-or-nothing. Kedi validates all fragments, environment values, active profile state, conversation state, and artifacts before publishing the file. SessionDumpError reports every unsupported boundary found during preflight. It never silently removes a binding, and an existing destination remains untouched when validation fails. Successful writes use a mode-0600 temporary file, fsync, and atomic replacement.

The snapshot value codec preserves scalar values, bytes, complex and decimal numbers, UUIDs, dates and times, paths, regular expressions, standard containers with typed keys, and source-backed Kedi type instances. Kedi stores fragment sources and digests so procedures, types, profiles, tracebacks, and source identities can be rebuilt before native values are installed. The document integrity hash, format version, and Kedi version are checked on load.

Kedi rejects state that cannot be restored with equivalent semantics:

arbitrary Python callables, generators, open resources, concurrency primitives, tasks/futures, classes, and unknown object instances;
shared or cyclic mutable object graphs;
dynamic approval handlers, non-importable lifecycle hook handlers, process-bound tool/profile bindings, active artifacts, conversation turns, or adapter-native continuation state;
imports, inline Python preludes, executable type defaults, and runtime-scoped declarations that would require old code to run during load.

Lifecycle hooks are stored without pickle. A handler is restorable only when its module and qualified name resolve back to that exact callable. Importable top-level functions are supported; lambdas, local functions, closures, bound methods, and handlers from __main__ make the dump fail during preflight. Load only session snapshots you trust. Restoring an import-addressable hook imports its Python module, so that module's normal import-time code may run; Kedi does not execute the hook handler itself during load.

Adapters and executors are not serialized. Supply them when the restored session needs those infrastructure dependencies:

session = kedi.load_session(
    "work.kedi-state",
    adapter=adapter,
    executor=executor,
)

load_session() accepts a keyword-only session_type= factory and defaults to InteractiveSession. An InteractiveSession subclass can be supplied when the restored object needs application-specific behavior.

Apart from resolving documented import-addressable hook handlers, loading compiles source-backed declarations but never re-executes prior initializations, assignments, templates, tools, LLM requests, filesystem writes, or other top-level side effects.

Lifecycle and Failure Semantics¶

Use the context manager form when possible. close() is idempotent and releases session-owned resources. Executing after close, closing during execution, or starting concurrent or re-entrant execute() calls raises an error.

The execution model is synchronous and non-transactional. If a fragment fails:

it is not retried automatically;
state committed before the failure remains visible;
completed external side effects are not rolled back;
the source-aware exception identifies the failed fragment.

Interactive fragments reject package metadata, export directives, and @test/@eval suites. Those constructs describe complete files, packages, or validation surfaces rather than one incremental cell.

Terminal REPL¶

See Terminal REPL.

Choosing a Surface¶

Use kedi --idle for direct terminal exploration. Use kedi.interactive() when an editor, notebook, debugger, or application owns input, output, source names, and lifecycle. Use ordinary file execution when a complete program should be repeatable from source as one unit.

Interactive Execution¶

Python API¶

Results¶

Source Identity and Imports¶

Configuration¶

Durable Snapshots¶

Lifecycle and Failure Semantics¶

Terminal REPL¶

Explicit Multiline Input¶

Syntax Highlighting¶

Inspecting Values¶

Commands, History, and Exit¶

Choosing a Surface¶