Back to releases

v0.13.0 - June 11, 2026

Release v0.13.0 - 2026-06-11

Highlights

  • Completed Akuma interactive query responses now include a structured provenance object explaining how the answer was produced: the tables, joins, filters, projections, and aggregations recovered from the executed SQL, plus enumerated warnings.
  • Every provenance payload carries a provenanceFidelity field — full when the facts were deterministically extracted from the executed SQL (Postgres and MySQL), limited when they come from generation metadata (Snowflake, BigQuery, or when extraction was not possible). Clients should always distinguish the two.
  • Provenance is derived server-side from the SQL itself, never from model-generated explanation text, so the facts shown to users match the query that actually ran.

Product Changes

Akuma

  • completed envelopes from POST /v1/akuma/queries/interactive that carry executed SQL now include a provenance object alongside result. For Postgres and MySQL sources the joins, filters (WHERE/HAVING), projections, and aggregation shape (GROUP BY expressions and aggregate functions) are extracted deterministically from the final SQL; the table list reflects the FROM/JOIN positions of the executed statement, flattened across subqueries and CTEs (so CTE and derived-table alias names may appear alongside base tables).
  • Snowflake and BigQuery sources receive limited provenance: the table list from generation metadata plus enumerated warnings, with empty parsed-fact arrays. The dialect_provenance_limited warning category names the reason.
  • Provenance never affects query execution. If the executed SQL cannot be extracted (an unsupported statement shape, or a query the extractor cannot parse), the query still succeeds and provenance degrades to limited with a parser_extraction_failed or statement_shape_unsupported warning — there is no error path introduced by this feature.
  • Warning categories inside provenance.warnings are a fixed, server-defined set and are additive over releases; clients should tolerate new categories.
  • Replayed clarification consumes return the provenance captured when the consume ran. Oversized-replay placeholder responses (see v0.12.0) omit provenance along with the row data.

API Changes

  • Added:
    • provenance response field on POST /v1/akuma/queries/interactive completed envelopes with executed SQL, containing provenanceFidelity, dialect, tables, joins, filters, projections, aggregations, and warnings.
    • provenanceFidelity values full and limited (extensible enum — treat unknown values as limited).
    • Provenance warning categories parser_extraction_failed, dialect_provenance_limited, and statement_shape_unsupported (extensible enum).
  • POST /v1/akuma/query (the legacy endpoint) is unchanged and does not return provenance.

SDK + MCP Changes

TypeScript SDK

  • Extended the interactive query response type with an optional provenance field and the AkumaProvenance, AkumaProvenanceJoin, AkumaProvenanceFilter, AkumaProvenanceProjection, AkumaProvenanceAggregations, and AkumaProvenanceWarning types.
  • provenance is strictly validated only on completed envelopes; on future statuses an off-shape value is preserved on the raw response rather than raising, matching the clarification field's forward-compatibility behavior.

Python SDK

  • Extended AkumaInteractiveQueryResponse with an optional provenance attribute and the corresponding AkumaProvenance* dataclasses (snake_case attributes, e.g. provenance_fidelity, aggregations.group_by).
  • Parsing is strict about the object shape only on completed envelopes; future statuses pass the raw payload through on raw_response.

Go SDK

  • Extended AkumaInteractiveQueryResponse with an optional Provenance field and the AkumaProvenance family of types, including AkumaProvenanceFidelity constants (AkumaProvenanceFidelityFull, AkumaProvenanceFidelityLimited).
  • Provenance is strictly decoded only on completed envelopes; the raw envelope continues to carry the field for inspection on any status.

MCP Server

  • akuma.query_interactive mirrors the provenance object into structured tool content on completed results, so host LLMs can present how the answer was produced alongside the SQL and rows.
  • The MCP server validates that provenance, when present on a completed envelope, is an object; envelope handling is otherwise unchanged.

Migration Notes

  • This release is fully additive. Existing callers of POST /v1/akuma/queries/interactive are not required to change; envelopes simply gain the provenance field on completed results with executed SQL.
  • Clients that render provenance must surface provenanceFidelity and must not present limited provenance as equivalent to full — limited payloads describe what is known from generation metadata, not verified facts of the executed SQL.

Documentation Updates

  • Updated the public API reference, SDK docs, and MCP docs for the provenance payload, fidelity semantics, and warning categories.