open_responses 0.4.0

Dart client for the OpenResponses API. Provides a unified, type-safe interface for interacting with multiple LLM providers through the OpenResponses specification.

0.4.0

Caution

This release has breaking changes. See the Migration Guide for upgrade instructions.

Tracks OpenResponses spec v2.3.0 (openresponses#68) by adding response compaction, the assistant message phase, and broader output-item coverage. Adds POST /responses/compact via ResponsesResource.compact() along with new CompactResource, CompactResponseRequest, CompactionItem (input variant), and CompactionOutputItem (output variant) models. Adds MessagePhase (commentary/final_answer) with a new optional phase field on AssistantMessageItem and MessageOutputItem — required for follow-up requests on gpt-5.3-codex and similar models. Also adds FunctionCallOutputResponseItem so OutputItem covers all members of the spec's ItemField union, and supports input_* content parts in MessageOutputItem.content so echoed-back user messages in stored or compacted history parse correctly. Breaking: MessageOutputItem.content is retyped from List<OutputContent> to List<MessageContentPart> — type guards on leaf classes still narrow correctly, but callers that declare the intermediate list type must migrate.

• BREAKING FEAT: Add response compaction and assistant phase (#214). (af4bd2fe)

0.3.2

Adds support for WebSocket mode in the Responses API via new WebSocketResponseCreateEvent and WebSocketErrorEvent types. The request wrapper composes an existing CreateResponseRequest with the required response.create discriminator and automatically strips the three HTTP-only fields (background, stream, stream_options) that must not be sent over WebSocket. Promotes the bundled OpenResponses spec to v2.3.0 (openresponses#71).

• FEAT: Add WebSocket mode support (#199). (cb10f1d0)

0.3.1

Annotates llms.txt with per-link token counts and per-package totals so coding agents can budget context before fetching documentation, examples, or changelogs — inspired by Addy Osmani's Agentic Engine Optimization article.

• FEAT: Annotate llms.txt with token counts and tighten agent-facing docs (#181). (a1e82aca)

0.3.0

Caution

This release has breaking changes. See the Migration Guide for upgrade instructions.

The InputFileContent.data() factory now requires a mediaType parameter and constructs proper data URL format instead of passing raw base64 (which was rejected by the API). Also adds the missing ReasoningItemParam manifest entry and copyWith method to ReasoningInputItem.

• BREAKING FEAT: Require mediaType in InputFileContent.data() for data URL construction (#152). (821eea60)
• FIX: Add missing ReasoningItemParam manifest entry and copyWith (#160). (0752275b)
• DOCS: Overhaul root README and add semver bullet to all packages (#151). (e6af33dd)

0.2.0

Caution

This release has breaking changes. See the Migration Guide for upgrade instructions.

Replaces the ServiceTier enum with an extensible class to preserve provider-specific tier values on round-trip serialization, aligning with the provider-agnostic OpenResponses specification. Also standardizes equality helper locations, overhauls README documentation with llms.txt ecosystem files, and aligns compliance tests with the official OpenResponses CLI test runner.

• BREAKING FEAT: Improve spec compliance for ServiceTier and ResponseError (#133). (487231d2)
• REFACTOR: Standardize equality helpers location across packages (#123). (34086102)
• DOCS: Overhaul READMEs and add llms.txt ecosystem (#149). (98f11483)
• TEST: Align compliance tests with official CLI test runner (#134). (f7919790)

0.1.5

Added StreamingEventAccumulator for assembling streamed response events into a complete response, convenience factories on Item for creating common message types (userMessage, assistantMessage, functionCall, etc.), and type-safe ResponseInput for building request input with compile-time safety. Also added copyWith methods to streaming events and several model classes.

• FEAT: Add streaming accumulator, convenience factories, and type-safe input (#109). (61ffa87c)

0.1.4

This release adds inline streaming error detection for improved reliability when handling streamed responses.

• FEAT: Detect inline streaming errors (#91). (9f0eaf37)
• DOCS: Improve READMEs with badges, sponsor section, and vertex_ai deprecation (#90). (5741f2f3)

0.1.3

Internal improvements to build tooling and package publishing configuration.

• REFACTOR: Migrate API skills to the shared api-toolkit CLI (#74). (923cc83e)
• CHORE: Add .pubignore to exclude .agents/ and specs/ from publishing (#78). (0ff199bf)

0.1.2

Added baseUrl and defaultHeaders parameters to withApiKey constructors and unified equality helpers across packages.

• FEAT: Add baseUrl and defaultHeaders to withApiKey constructors (#57). (f0dd0caa)
• REFACTOR: Unify equality_helpers.dart across packages (#67). (ec2897f8)

0.1.1

Added withApiKey convenience constructor for simplified client initialization.

• FEAT: Add withApiKey convenience constructors (#56). (b06e3df3)
• CHORE: Bump googleapis from 15.0.0 to 16.0.0 and Dart SDK to 3.9.0 (#52). (eae130b7)

0.1.0

Initial release of the OpenResponses Dart client.

Features

• Core Client: OpenResponsesClient with configurable base URL and authentication
• Response Creation: responses.create() for non-streaming requests
• Streaming: responses.createStream() and responses.stream() with builder pattern
• Multi-provider Support: Works with OpenAI, Ollama, Hugging Face, OpenRouter, and LM Studio

Request Features

• String or message item list input
• System instructions via instructions parameter
• Multi-turn conversations with previousResponseId
• Temperature and max output tokens control
• Service tier selection

Tools

• FunctionTool: Define custom functions with JSON Schema parameters
• McpTool: Remote Model Context Protocol server tools
• Tool choice configuration (auto, required, specific function)

Structured Output

• TextConfig with format options
• JsonSchemaFormat for structured JSON responses with strict mode
• TextResponseFormat and JsonObjectFormat

Reasoning Models

• ReasoningConfig with effort levels (low, medium, high)
• Reasoning summary modes (concise, detailed, auto)
• Access to reasoning items via response.reasoningItems

Streaming Events

• Full SSE event parsing with 25+ event types
• Response lifecycle events (created, queued, in_progress, completed, failed)
• Output item and content part events
• Text delta and done events
• Function call argument streaming
• Reasoning delta and summary events
• Error events

Content Types

• InputTextContent: Text input
• InputImageContent: Image URLs with detail level
• InputFileContent: File references
• OutputTextContent: Text output with annotations
• RefusalContent: Model refusal messages

Message Items

• MessageItem with role (user, assistant, system, developer)
• Convenience factories: userText(), systemText(), assistantText()
• FunctionCallItem and FunctionCallOutputItem
• ItemReference for referencing previous items

DX Extensions

• response.outputText: Concatenated text from output
• response.functionCalls: All function call items
• response.reasoningItems: All reasoning items
• response.hasToolCalls, response.isCompleted, response.isFailed
• event.textDelta, event.isFinal
• stream.text, stream.finalResponse

Error Handling

• OpenResponsesException sealed class hierarchy
• ApiException with error code and details
• AuthenticationException for auth failures
• RateLimitException with retry-after duration
• ValidationException for invalid requests
• TimeoutException and AbortedException

Authentication

• BearerTokenProvider for API key authentication
• NoAuthProvider for local providers (Ollama, LM Studio)
• Extensible AuthProvider interface

Configuration

• OpenResponsesConfig with base URL, auth, headers, timeout
• RetryPolicy with exponential backoff and jitter
• Custom HTTP client support

Commits

• FEAT: Initial implementation of OpenResponses Dart client (#10). (4fac8fa6)
• FEAT: Comprehensive model improvements with new features (#16). (6b6450a7)
• FEAT: Add SummaryTextContent for reasoning models (#23). (93ce0a00)
• FEAT: Add ReasoningInputItem, UnknownEvent, and provider aliases (#28). (e1fa0afe)
• REFACTOR: Align client package architecture across SDK packages (#37). (cf741ee1)
• REFACTOR: Align API surface across all SDK packages (#36). (ed969cc7)