Actions

Actions are curated AI operations you run over a bucket’s data. Highlight an object, a set of objects, a table, or a vector collection, pick an action — summarize, classify, extract entities, translate, answer a question — and K3 runs it and hands back a structured result. Under the hood each action is a Scriptum template, filtered to the ones that fit what you selected and dispatched with the bucket, service account, org, and user context injected for you.

Actions are a control-plane surface: they live on k3-api, under the dodil.data.actions.v1 package and the ActionsService, reached over the same HTTP/JSON (api.data.dodil.io) and gRPC (rpc.data.dodil.io:443) doors as every other control op. K3 owns the selection model, context injection, and the run lifecycle; Scriptum stays the generic execution substrate underneath.

This is the action menu, not a chat agent. The proto once also declared a conversational ChatTurn agent — it was never built and has been removed. The shipping surface is the curated-action menu: ListAvailableActions + RunAction, plus the queued dispatch and run-history calls below. Nothing on the site should point you at a chat RPC.

Where actions sit

An action’s inputs are resolved from two sources: the fields K3 fills from your selection (bucket, key(s), collection, table) and the per-action form params you supply (question, target_language, llm_model, …). K3 merges the form params on top of the selection-derived inputs before dispatch — you never assemble presigned URLs or fetch schemas yourself.

Selection — what you run an action over

Every action runs against a selection. The selection’s shape decides which actions are even offered (ListAvailableActions filters the catalog to actions whose (pillar, unit, cardinality) and content-type accept-lists match), and it maps to the action’s K3-filled inputs:

The set of actions is server-driven — it comes from the Scriptum catalog filtered per selection, not a fixed list baked into the client. Enumerate it live rather than hard-coding ids; see Catalog.

Sync vs async, and the queued path

Every action carries an invoke hint:

• sync — completes inline (default ~30s K3 deadline). The extraction/classification family runs this way.
• async — long-running (default ~10min); the caller streams progress and gets a terminal event when it finishes. Q&A, synthesis, and the agentic plan_and_run run this way.

There are two dispatch styles for the same action:

1. Streaming — RunAction (POST /actions/run) keeps the dispatch on the HTTP connection and emits an NDJSON event stream (started → progress… → completed|failed). Good for one click.
2. Queued — EnqueueAction / EnqueueBulkActions publish the dispatch onto a work queue and return run_id(s) immediately. Built for fan-out — “100 files × 1 translation” is one bulk call returning 100 run_ids. Watch a queued run with WatchActionRun, or poll ListActiveRuns for the in-flight snapshot.

Run history

Every dispatch — streamed or queued — writes a run manifest into the bucket under _actions/runs/{reverse_ts}_{run_id}/manifest.json. Small outputs land inline in the manifest; larger ones as a sibling output.{ext}; self-routing templates point at a warehouse table or an S3 key instead. A reverse-timestamp prefix makes “most recent N” a single ordered listing.

• ListRecentActions / GetActionRun read the history (newest first).
• SaveActionOutput promotes an ephemeral run’s output to a permanent S3 key or a warehouse table — the temp copy has a TTL, the promoted copy does not.

See API Reference for the full manifest and lifecycle.

In this section

• API Reference — every ActionsService RPC + HTTP route, with proto/json pairs and the NDJSON stream shape
• CLI Guide — dodil data actions list · run
• Catalog — the 13 shipping actions: id, purpose, selection kind, invoke mode

See also

• Pipelines — the automatic side of the same intelligence: rules that run templates on every upload, rather than on demand
• Object Storage — where object-selection actions read from
• Vector — collections and chunks that collection_topic_map / chunks_synthesize_answer run over
• Conventions — auth headers, error envelope, using gRPC
• CLI Basics — install + common flags