Back to releases

v0.12.0 - May 27, 2026

Release v0.12.0 - 2026-05-27

Highlights

  • Added a clarification protocol to the interactive Akuma query endpoint: when a prompt is ambiguous, the endpoint can now return a needs_clarification envelope with a discrete option list, and the caller resolves it by re-calling the endpoint with the chosen option plus an Idempotency-Key header.
  • Updated the public SDKs and MCP server with typed consume methods, request/response schemas, and tool definitions for the new clarification flow.
  • Clarification consumes return an error and do not produce SQL if the source schema changes between when the clarification was issued and when the caller resolves it, so the answer is always against the schema the API used at issuance.

Product Changes

Akuma

  • Added a needs_clarification status to the /v1/akuma/queries/interactive envelope. When a prompt has materially different valid interpretations, the endpoint returns a server-issued clarificationToken, a short question, and 2-4 discrete options instead of guessing.
  • Added the consume side of the protocol on the same /v1/akuma/queries/interactive endpoint: re-call it with clarificationToken, optionId, and an Idempotency-Key header to get a completed envelope with the resolved SQL. The original interactive endpoint continues to serve fresh queries with the same request shape and is not deprecated.
  • Same token plus same Idempotency-Key plus same optionId replays the persisted result for 24 hours after the consume. Replays of large sql-and-results responses (over 1 MiB) return a placeholder envelope that preserves the generated SQL with a warning explaining that the rows were not retained; re-execute the SQL directly to recover the rows.
  • Same token plus same Idempotency-Key but a different optionId, or a different Idempotency-Key, returns 409. Replays after the 24-hour window have been pruned return 404. Unconsumed clarifications whose 30-minute issuance window has elapsed return 410. Source schema changes between issuance and consume return 409 (restart the query flow).
  • Each clarification token can be resolved by only one consume request; clients must serialize retries for a given clarification rather than fanning consume calls out across keys.

API Changes

  • Added:
    • needs_clarification status on POST /v1/akuma/queries/interactive responses.
    • clarificationToken, optionId request body fields and the Idempotency-Key request header on POST /v1/akuma/queries/interactive for the consume flow.
    • clarification response field (token, question, options, expiry) on needs_clarification envelopes.
    • 404 response on POST /v1/akuma/queries/interactive when a clarification token cannot be found or its replay window has elapsed.
    • 409 response on POST /v1/akuma/queries/interactive for idempotency-key mismatch, option-id mismatch on an already-consumed token, source schema changes since issuance, and unavailable routing model.
    • 410 response on POST /v1/akuma/queries/interactive when an unconsumed clarification token has expired.

SDK + MCP Changes

TypeScript SDK

  • Added a typed consumeClarification method that takes clarificationToken, optionId, and idempotencyKey. The method forwards the idempotency key as the Idempotency-Key header.
  • Extended the interactive query response type with the clarification object so callers can pattern-match on status === "needs_clarification".

Python SDK

  • Added a consume_clarification service method that takes clarification_token, option_id, and idempotency_key and surfaces the resolved envelope or a typed KaizenError on contract violations.
  • Extended AkumaInteractiveQueryResponse with clarification plus AkumaClarification and AkumaClarificationOption models for the new envelope shape.

Go SDK

  • Added a ConsumeClarification client method that takes AkumaInteractiveConsumeRequest (ClarificationToken, OptionID, IdempotencyKey) and returns the typed envelope. The full raw HTTP 200 envelope is still exposed for forward compatibility.
  • Extended AkumaInteractiveQueryResponse with Clarification plus AkumaClarification and AkumaClarificationOption types.

MCP Server

  • Extended the akuma.query_interactive tool with optional clarificationToken, optionId, and idempotencyKey arguments. The same tool entry serves both fresh queries and consume calls; the tool description enumerates which fields each call shape requires. idempotencyKey is forwarded to the API as the Idempotency-Key header.
  • needs_clarification envelopes are returned with the tool result error flag set, and the full envelope (including the clarification token and option list) is mirrored into structured content so host LLMs can present the choices to the user.

Migration Notes

  • Existing callers of POST /v1/akuma/queries/interactive are not required to change. The fresh-query request shape and the completed / rejected envelope statuses are unchanged; needs_clarification is only returned when the engine sees real ambiguity.
  • Customers parsing the envelope by status should treat unknown future values as non-completed: SDK clients still surface the raw envelope so a future status passes through without an SDK upgrade.

Documentation Updates

  • Updated the public API docs, SDK docs, and MCP docs for the new clarification protocol, consume request shape, and the Idempotency-Key header semantics.