@spec agent_diagram(
  term(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}

Renders a Mermaid diagram for an agent definition or inspection map.

@spec call_graph(
  term(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}

Renders a Mermaid call graph from a Jidoka timeline.

@spec chat(String.t(), (-> term()), keyword()) :: term()

Runs a notebook chat cell and renders a concise result summary.

By default this does not require provider credentials; deterministic notebooks can pass injected LLM functions. Pass require_provider?: true when the cell should fail fast if provider credentials are missing.

@spec context(String.t(), map(), keyword()) :: :ok

Renders a runtime context map with public and internal keys separated.

@spec debug_agent(
  term(),
  keyword()
) :: {:ok, map()} | {:error, String.t()}

Renders Jidoka.inspect/1 for an agent definition, plan, session, or result.

@spec format_chat_result(term()) :: term()

Formats common Jidoka turn/session results for notebook display.

@spec load_provider_env([String.t()]) :: {:ok, String.t()} | {:error, String.t()}

Mirrors a Livebook provider secret into the normal provider environment.

@spec preflight(Jidoka.plan_input() | module(), Jidoka.request_input(), keyword()) ::
  {:ok, Jidoka.Inspection.Preflight.t()} | {:error, String.t()}

Runs Jidoka.preflight/3 and renders prompt/timeline tables.

@spec setup(keyword()) :: :ok

Configures optional notebook conveniences.

This is opt-in and intended for Livebook/examples. It can mirror Livebook secrets such as LB_OPENAI_API_KEY into the provider environment expected by ReqLLM.

@spec setup_notebook(keyword()) :: map()

Configures a notebook and renders a compact setup status table.

@spec start_or_reuse(String.t(), (-> DynamicSupervisor.on_start_child()), keyword()) ::
  DynamicSupervisor.on_start_child()

Starts a process-hosted Jidoka agent unless an agent with id is already running.

This keeps Livebook cells repeatable when a notebook is re-evaluated.

@spec table(String.t(), [map()], keyword()) :: :ok

Renders a small Markdown table in Livebook.

@spec timeline(
  term(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Renders a compact Jidoka event timeline from a result, snapshot, session, replay, or raw events.

@spec trace(String.t(), (-> result), keyword()) :: result when result: term()

Runs fun, renders a Jidoka timeline when the result contains one, and returns the original result.

@spec trace_table(
  term(),
  keyword()
) :: {:ok, [map()]} | {:error, String.t()}

Renders the raw compact timeline table.