v0.18.0

v0.18.0 Release Summary

What Changed

This release adds comprehensive support for Google's ADK (AI Development Kit) response format. The implementation includes full Rust type definitions, PyO3 bindings, and unified response handling via the ResponseAdapter trait.

---

Breaking Changes

None. No schema changes, no migration required.

---

Changes

ADK Response Types

Added full support for Google's ADK wire format:

• AdkLlmResponse — Top-level response struct. Discriminated by presence of "partial" key (ADK-specific).
• AdkContent — Content container with role and parts list.
• AdkPart — Individual response parts. Uses individual Option<T> fields (not an enum) to handle Pydantic's null-serialization requirement.
• AdkUsageMetadata — Token counts with support for cached content, thoughts tokens, and per-modality breakdowns (prompt_tokens_details, candidates_tokens_details, etc.).
• AdkTranscription — Input and output transcription with text and finished flag.
• AdkCacheMetadata — Cache metadata including name, expiry, fingerprint, and invocation count.
• AdkLiveSessionResumptionUpdate — Session resumption data (new handle, resumable flag, last consumed message index).
• AdkToolCallInfo — Python-accessible tool call information extracted from AdkPart.function_call.

All types implement Serialize/Deserialize for wire format compatibility and #[pyclass] for Python exposure.

AdkLlmResponse Methods

AdkLlmResponse implements the ResponseAdapter trait for unified handling:

Method	Returns	Purpose
response_text()	String	Last text part in content, empty if none
model_name()	Option<&str>	Model version from response
finish_reason()	Option<&str>	Finish reason (STOP, MAX_TOKENS, etc.)
input_tokens()	Option<i64>	Prompt token count
output_tokens()	Option<i64>	Candidates token count
total_tokens()	Option<i64>	Sum of input and output
get_tool_calls()	Vec<ToolCallInfo>	Extracted function calls from parts
get_log_probs()	Vec<TokenLogProbs>	Token probabilities (digit tokens only)
structured_output_value()	Option<Value>	Parsed JSON from response text

Wire Format Compatibility

AdkPart uses flat Option<T> fields instead of an enum variant to handle Pydantic's serialization behavior. This allows deserialization of wire formats where all part fields are present, including explicit null values:

{
  "text": "hello",
  "function_call": null,
  "function_response": null,
  "inline_data": null,
  ...
}

Python Bindings

All ADK types are now exposed in potato_head.google:

from potato_head.google import (
    AdkLlmResponse,
    AdkContent,
    AdkPart,
    AdkUsageMetadata,
    AdkTranscription,
    AdkCacheMetadata,
    AdkLiveSessionResumptionUpdate,
    AdkToolCallInfo,
)

Each type supports:

• .model_validate_json(json_string) — deserialize from JSON string
• .model_dump_json() — serialize to JSON string
• Attribute access via @pyo3(get) / @pyo3(get_all) annotations

Anthropic Response Updates

Added missing field accessors to Anthropic citation types (CitationCharLocation, CitationPageLocation).

Testing

Comprehensive test suite for AdkLlmResponse:

• Text response deserialization
• Pydantic wire format (explicit nulls)
• Function call extraction and priority
• Token count handling
• Log probabilities with digit-only filtering
• Structured output (JSON) parsing
• Empty response handling
• Session resumption and caching metadata

---

Upgrading from v0.17.0

No action required. The ADK types are purely additive and don't affect existing Anthropic or Gemini support.

If you integrate with Google's ADK API (currently preview/beta), you can now deserialize responses directly:

response_json = "{...}"  # From Google ADK API
response = AdkLlmResponse.model_validate_json(response_json)
print(response.response_text())
print(response.get_tool_calls())