Jidoka (Jidoka v0.9.0)

Copy Markdown View Source

Public facade for Jidoka.

This module exposes the stable application-facing surface for Jidoka:

  • an immutable Jidoka.Agent.Spec;
  • a compiled Jidoka.Turn.Plan;
  • a Runic-backed pure planning workflow;
  • an Effect.Intent / Effect.Result interpreter boundary;
  • explicit turn, session, and review use cases;
  • hibernate/resume from a phase-boundary snapshot.

The facade intentionally uses short, stable verbs for the main workflow:

Summary

Build

agent(attrs)

Builds a validated agent definition.

agent!(attrs)

Builds a validated agent definition and raises when validation fails.

export(agent_or_spec, opts \\ [])

Exports an agent definition to a portable JSON or YAML document string.

import(contents, opts \\ [])

Imports a JSON or YAML agent document string into Jidoka.Agent.Spec.

plan(plan)

Compiles an agent definition into executable turn data.

plan!(plan)

Compiles an agent definition into executable turn data and raises on failure.

Run

chat(spec_or_server, input, opts \\ [])

Runs one turn and returns final assistant text.

resume(snapshot_input, opts \\ [])

Resumes from a durable agent snapshot.

turn(spec_or_server, request_input, opts \\ [])

Runs one agent turn through the Jidoka Runic spine.

Async

await(request_or_stream, opts \\ [])

Waits for a chat request or stream to finish.

cancel(request, opts \\ [])

Cancels an active asynchronous chat request and returns typed evidence.

chat_async(target, input, opts \\ [])

Starts one chat request asynchronously and returns a request handle.

stream(request, opts \\ [])

Builds a request-scoped event stream for an async chat request.

Sessions

fork_session(session_or_id, opts \\ [])

Creates a new session from a safe snapshot in an existing session.

recover_session(session_id, opts \\ [])

Recovers a stored session after its durable worker lease expires.

session(agent_or_plan, opts \\ [])

Starts a durable Jidoka session for an agent, spec, or plan.

session(agent_or_plan, session_id, opts)

Starts a durable Jidoka session with an explicit session id.

Review

approve(snapshot_or_session, review_or_id, opts \\ [])

Approves a pending review and resumes the target.

deny(snapshot_or_session, review_or_id, opts \\ [])

Denies a pending review and resumes the target.

pending_reviews(target)

Lists pending human-review requests from a snapshot, session, or session store.

Process Host

await_agent(server, opts \\ [])

Awaits terminal Jido status for a process-hosted Jidoka agent.

start_agent(agent, opts \\ [])

Starts a Jidoka DSL agent under the default Jidoka.Jido process tree.

stop_agent(pid_or_id, opts \\ [])

Stops a process-hosted Jidoka agent by pid or registered Jido agent id.

whereis(id, opts \\ [])

Looks up a running Jidoka agent process by registered Jido agent id.

Inspect

inspect(value, opts \\ [])

Returns a stable inspection view for an agent, plan, turn, snapshot, journal, or other Jidoka data value.

preflight(spec_or_plan, request_input, opts \\ [])

Assembles the prompt for a turn without calling an LLM or tools.

project(value)

Projects a Jidoka data contract into a stable inspection map.

Handoff

handoff(conversation_id)

Returns the current handoff owner for a conversation, if one has been recorded.

reset_handoff(conversation_id)

Clears the current handoff owner for a conversation.

Errors

error_to_map(error)

Converts a Jidoka error or arbitrary error term into a display-oriented map.

format_error(error)

Formats a Jidoka error or arbitrary error term for display.

normalize_error(reason, context \\ %{})

Normalizes any error term into a Splode-backed Jidoka.Error exception.

Types

agent_input()
chat_input()
plan_input()
request_input()
run_result()
runnable_input()
runtime_opts()
server_ref()

Build

agent(attrs)

@spec agent(keyword() | map()) :: {:ok, Jidoka.Agent.Spec.t()} | {:error, term()}

Builds a validated agent definition.

Use this when constructing an agent from data at runtime, in tests, or from tooling that does not use the Spark DSL. The returned Agent.Spec is immutable definition data: it contains the agent id, model, instructions, controls, operations, context schema, result schema, and memory policy. It is not a process, session, provider client, or live capability bundle.

agent!(attrs)

@spec agent!(keyword() | map()) :: Jidoka.Agent.Spec.t()

Builds a validated agent definition and raises when validation fails.

This is useful for compile-time examples, tests, and boot-time application setup where invalid agent data should fail fast.

export(agent_or_spec, opts \\ [])

@spec export(
  module() | Jidoka.Agent.Spec.t() | Jidoka.Turn.Plan.t() | keyword() | map(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Exports an agent definition to a portable JSON or YAML document string.

Export writes data that can be passed back into import/2. Runtime-only values are not serialized. If a context or result schema is present, provide a registry ref with context_schema_ref: or result_schema_ref: so the exported document can be resolved by the importing application.

import(contents, opts \\ [])

@spec import(
  String.t(),
  keyword()
) :: {:ok, Jidoka.Agent.Spec.t()} | {:error, term()}

Imports a JSON or YAML agent document string into Jidoka.Agent.Spec.

Import is intentionally string-only at the facade. File loading, registries, and trust boundaries belong to the caller; Jidoka owns parsing, normalization, schema validation, and data-safe conversion into Agent.Spec.

plan(plan)

@spec plan(plan_input()) :: {:ok, Jidoka.Turn.Plan.t()} | {:error, term()}

Compiles an agent definition into executable turn data.

Turn.Plan is still pure data. It contains no live capabilities, processes, provider clients, or credentials. Use it when you want to inspect or cache the normalized runtime contract before executing a turn.

plan!(plan)

@spec plan!(plan_input()) :: Jidoka.Turn.Plan.t()

Compiles an agent definition into executable turn data and raises on failure.

This mirrors plan/1, but is intended for setup paths where invalid agent data should stop execution immediately.

Run

chat(spec_or_server, input, opts \\ [])

@spec chat(chat_input(), String.t(), runtime_opts()) ::
  {:ok, String.t()}
  | {:ok, Jidoka.Session.t(), String.t()}
  | {:hibernate, Jidoka.Snapshot.t()}
  | {:hibernate, Jidoka.Session.t(), Jidoka.Snapshot.t()}
  | {:error, term()}

Runs one turn and returns final assistant text.

chat/3 is the ergonomic path for product code that only needs the final assistant answer. For caller-managed sessions, the updated session is returned alongside the text so durable state is not lost.

Use turn/3 when callers need the full Turn.Result, event journal, agent state, operation results, stream events, or hibernation snapshot.

resume(snapshot_input, opts \\ [])

@spec resume(Jidoka.Snapshot.t() | String.t(), runtime_opts()) :: run_result()

Resumes from a durable agent snapshot.

The snapshot may be an Snapshot struct or the authenticated opaque string returned by Jidoka.Snapshot.serialize/1. Resume continues through the same turn execution boundary as turn/3, so callers provide the same runtime capabilities plus any required approval response.

turn(spec_or_server, request_input, opts \\ [])

@spec turn(runnable_input(), request_input(), runtime_opts()) :: run_result()

Runs one agent turn through the Jidoka Runic spine.

This is the stable core runtime entrypoint. It accepts a DSL agent module, Agent.Spec, or Turn.Plan, normalizes the request, runs pure workflow planning, interprets external effects through explicit runtime capabilities, and returns a typed result or snapshot.

Use turn/3 for deterministic tests with injected capabilities, live ReqLLM calls, process-hosted agents, controls, tools, hibernation, streaming, and trace/event inspection. If the model returns multiple independent operation calls in one decision, the runtime executes them as a bounded Runic-backed batch while preserving observation order.

Async

await(request_or_stream, opts \\ [])

@spec await(
  Jidoka.Chat.Request.t() | Jidoka.Stream.t(),
  keyword()
) :: term()

Waits for a chat request or stream to finish.

This returns the same normalized result shape as chat/3, including session results when the request target is a Jidoka.Session. A cancelled request returns {:cancelled, %Jidoka.Cancellation{}}.

cancel(request, opts \\ [])

@spec cancel(
  Jidoka.Chat.Request.t(),
  keyword()
) :: {:ok, Jidoka.Cancellation.t()} | {:error, term()}

Cancels an active asynchronous chat request and returns typed evidence.

chat_async(target, input, opts \\ [])

@spec chat_async(chat_input(), String.t(), runtime_opts()) ::
  {:ok, Jidoka.Chat.Request.t()} | {:error, term()}

Starts one chat request asynchronously and returns a request handle.

This is the UI-friendly companion to chat/3. Pass stream: true to stream request-scoped Jidoka.Event values to the caller mailbox while the task is running. Use stream/2 to enumerate those events and await/2 to collect the final normalized chat result.

stream(request, opts \\ [])

@spec stream(
  Jidoka.Chat.Request.t(),
  keyword()
) :: Jidoka.Stream.t()

Builds a request-scoped event stream for an async chat request.

The stream consumes events already emitted to the caller mailbox and stops at :turn_finished, :turn_failed, or :turn_hibernated.

Sessions

fork_session(session_or_id, opts \\ [])

@spec fork_session(
  Jidoka.Session.session_input(),
  keyword()
) :: {:ok, Jidoka.Session.t()} | {:error, term()}

Creates a new session from a safe snapshot in an existing session.

The source session is not changed. Use Jidoka.Session.resume/2 to run the returned fork from its copied snapshot.

recover_session(session_id, opts \\ [])

@spec recover_session(
  String.t(),
  keyword()
) :: Jidoka.Session.run_result()

Recovers a stored session after its durable worker lease expires.

session(agent_or_plan, opts \\ [])

@spec session(Jidoka.Session.agent_input(), keyword() | String.t()) ::
  {:ok, Jidoka.Session.t()} | {:error, term()}

Starts a durable Jidoka session for an agent, spec, or plan.

A session stores semantic conversation state, the latest turn result, hibernation snapshots, and replay data. Use it when a caller needs durable multi-turn behavior instead of a one-off turn/3.

session(agent_or_plan, session_id, opts)

@spec session(Jidoka.Session.agent_input(), String.t(), keyword()) ::
  {:ok, Jidoka.Session.t()} | {:error, term()}

Starts a durable Jidoka session with an explicit session id.

Prefer this arity when the caller already has an application-level conversation id and wants Jidoka session state to be addressable by that id.

Review

approve(snapshot_or_session, review_or_id, opts \\ [])

@spec approve(
  Jidoka.Snapshot.t() | Jidoka.Session.Data.t() | String.t(),
  Jidoka.Review.Request.t() | String.t(),
  runtime_opts()
) ::
  run_result()
  | {:ok, Jidoka.Session.Data.t(), Jidoka.Turn.Result.t()}
  | {:hibernate, Jidoka.Session.Data.t(), Jidoka.Snapshot.t()}

Approves a pending review and resumes the target.

The target may be a hibernated snapshot or a caller-managed session. This is a convenience wrapper around Jidoka.Review.Response.approve/2 plus resume/2.

deny(snapshot_or_session, review_or_id, opts \\ [])

@spec deny(
  Jidoka.Snapshot.t() | Jidoka.Session.Data.t() | String.t(),
  Jidoka.Review.Request.t() | String.t(),
  runtime_opts()
) ::
  run_result()
  | {:ok, Jidoka.Session.Data.t(), Jidoka.Turn.Result.t()}
  | {:hibernate, Jidoka.Session.Data.t(), Jidoka.Snapshot.t()}

Denies a pending review and resumes the target.

Denial returns the normal resume error shape for denied approvals. Use this when the application wants a single facade call instead of manually building a Jidoka.Review.Response.

pending_reviews(target)

@spec pending_reviews(
  Jidoka.Snapshot.t()
  | Jidoka.Session.Data.t()
  | Jidoka.Session.Store.store()
  | String.t()
) :: {:ok, [Jidoka.Review.Request.t()]} | {:error, term()}

Lists pending human-review requests from a snapshot, session, or session store.

For snapshots, this reads the review request embedded in snapshot metadata. For sessions and stores, it uses the session store port.

Process Host

await_agent(server, opts \\ [])

@spec await_agent(
  server_ref(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Awaits terminal Jido status for a process-hosted Jidoka agent.

This helper is only for process-hosted agents started through Jido. It is not needed for direct turn/3 or chat/3 calls.

start_agent(agent, opts \\ [])

@spec start_agent(
  module() | Jido.Agent.t(),
  keyword()
) :: DynamicSupervisor.on_start_child()

Starts a Jidoka DSL agent under the default Jidoka.Jido process tree.

The started process is a Jido.AgentServer; incoming Jidoka turn signals are routed to turn execution and the result is written back to Jido agent state.

stop_agent(pid_or_id, opts \\ [])

@spec stop_agent(
  pid() | String.t(),
  keyword()
) :: :ok | {:error, :not_found}

Stops a process-hosted Jidoka agent by pid or registered Jido agent id.

whereis(id, opts \\ [])

@spec whereis(
  String.t(),
  keyword()
) :: pid() | nil

Looks up a running Jidoka agent process by registered Jido agent id.

This is intentionally a process-hosting helper. It does not build specs, create sessions, or run turns.

Inspect

inspect(value, opts \\ [])

@spec inspect(
  term(),
  keyword()
) :: term()

Returns a stable inspection view for an agent, plan, turn, snapshot, journal, or other Jidoka data value.

inspect/2 is the human-facing debug surface. It favors grouped, readable maps over raw structs.

preflight(spec_or_plan, request_input, opts \\ [])

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

Assembles the prompt for a turn without calling an LLM or tools.

Use preflight to debug prompt assembly, tool metadata, memory injection, and request normalization before running live effects.

project(value)

@spec project(term()) :: term()

Projects a Jidoka data contract into a stable inspection map.

project/1 is the data-facing companion to inspect/2. It returns compact, deterministic maps that are useful for tests, golden files, traces, and UI rendering.

Handoff

handoff(conversation_id)

@spec handoff(String.t()) :: Jidoka.Handoff.OwnerStore.owner() | nil

Returns the current handoff owner for a conversation, if one has been recorded.

Handoffs are durable routing data. They indicate which agent should own future turns for a conversation after a handoff operation succeeds.

reset_handoff(conversation_id)

@spec reset_handoff(String.t()) :: :ok

Clears the current handoff owner for a conversation.

Use this when an application wants to return routing control to its default agent selection logic.

Errors

error_to_map(error)

@spec error_to_map(term()) :: map()

Converts a Jidoka error or arbitrary error term into a display-oriented map.

Values likely to contain credentials are sanitized before being returned.

format_error(error)

@spec format_error(term()) :: String.t()

Formats a Jidoka error or arbitrary error term for display.

This is intended for UI/logging boundaries that need a concise message rather than a full Splode error struct.

normalize_error(reason, context \\ %{})

@spec normalize_error(term(), keyword() | map()) :: Exception.t()

Normalizes any error term into a Splode-backed Jidoka.Error exception.

Prefer returning normalized errors from facade boundaries so callers see a consistent error shape even when the underlying cause came from a provider, store, control, or runtime capability.

Types

agent_input()

@type agent_input() :: module() | Jidoka.Agent.Spec.t() | keyword() | map()

chat_input()

@type chat_input() :: runnable_input() | Jidoka.Session.Data.t()

plan_input()

@type plan_input() ::
  module() | Jidoka.Agent.Spec.t() | Jidoka.Turn.Plan.t() | keyword() | map()

request_input()

@type request_input() ::
  Jidoka.Turn.Request.t()
  | String.t()
  | [Jidoka.ContentPart.input()]
  | keyword()
  | map()

run_result()

@type run_result() ::
  {:ok, Jidoka.Turn.Result.t()}
  | {:hibernate, Jidoka.Snapshot.t()}
  | {:error, term()}

runnable_input()

@type runnable_input() :: plan_input() | server_ref()

runtime_opts()

@type runtime_opts() :: keyword()

server_ref()

@type server_ref() :: Jido.AgentServer.server()