responses

type APIError = wire.APIError

type Accumulator struct {
	// contains filtered or unexported fields
}

type Client struct {
	// contains filtered or unexported fields
}

type ClientConfig struct {
	// BaseURL is the OpenAI-compat root, e.g. "https://api.openai.com/v1".
	// If ResponsesURL is set, it takes precedence.
	BaseURL string

	// HTTPClient is the transport. Callers should use
	// model.NewHTTPClient to construct one with the framework's
	// connection-hygiene defaults.
	HTTPClient *http.Client

	// AuthHeader, if non-empty, is set as the Authorization header
	// on every request. Typically "Bearer <key>".
	AuthHeader string

	// ExtraHeaders are added to every request before send. Useful for
	// provider-specific headers.
	ExtraHeaders http.Header

	// ResponsesURL overrides BaseURL+/responses. Empty means derive
	// from BaseURL.
	ResponsesURL string

	// MaxFrameSize caps the per-SSE-frame buffer in streaming mode.
	// Phase 1 client is non-streaming; the field is carried for the
	// Phase 2 streaming addition.
	MaxFrameSize int
}

type ContentPart struct {
	// Type is one of "input_text", "output_text", "refusal".
	Type string `json:"type"`

	// Text carries the body for text-class parts.
	Text string `json:"text,omitempty"`

	// Refusal carries the refusal body when Type == "refusal".
	Refusal string `json:"refusal,omitempty"`

	// Annotations are inline citations/URL refs the model may attach
	// to output_text. Carried as RawMessage; this package does not
	// model the shape, which has evolved across SDK versions.
	Annotations json.RawMessage `json:"annotations,omitempty"`
}

type Event struct {
	// Type is the SSE event name (e.g. "response.output_text.delta").
	// Mirrors the `event:` SSE line and the data payload's `type`
	// field, which the API contract holds equal.
	Type string `json:"type"`

	// SequenceNumber is the monotonically increasing event sequence
	// the API ships on every event. Useful for de-duplication on
	// reconnect; we don't reconnect (stateless one-shot stream) but
	// the field is carried for trace correlation.
	SequenceNumber int `json:"sequence_number,omitempty"`

	// Response carries the full Response on lifecycle events
	// (response.created, response.completed, response.failed, etc.).
	Response *Response `json:"response,omitempty"`

	// OutputIndex addresses the OutputItem inside Response.Output
	// that this event targets. Populated on item/content/text/refusal/
	// arguments/summary events.
	OutputIndex *int `json:"output_index,omitempty"`

	// ContentIndex addresses the ContentPart inside an OutputItem's
	// Content array. Populated on content_part.*, output_text.*,
	// refusal.* events.
	ContentIndex *int `json:"content_index,omitempty"`

	// SummaryIndex addresses the SummaryPart inside a reasoning
	// OutputItem's Summary array. Populated on reasoning_summary_*
	// events.
	SummaryIndex *int `json:"summary_index,omitempty"`

	// ItemID echoes the OutputItem.ID this event targets. Populated
	// on content/text/refusal/arguments/summary events.
	ItemID string `json:"item_id,omitempty"`

	// Item carries the OutputItem on output_item.added /
	// output_item.done.
	Item *OutputItem `json:"item,omitempty"`

	// Part carries the polymorphic part payload on content_part.* and
	// reasoning_summary_part.* events. Decode via ContentPart() or
	// SummaryPart() helpers based on Type.
	Part json.RawMessage `json:"part,omitempty"`

	// Delta accumulates partial text on output_text.delta,
	// refusal.delta, function_call_arguments.delta, and
	// reasoning_summary_text.delta events.
	Delta string `json:"delta,omitempty"`

	// Text snapshots final text on output_text.done and
	// reasoning_summary_text.done events.
	Text string `json:"text,omitempty"`

	// Arguments snapshots final JSON-encoded arguments on
	// function_call_arguments.done.
	Arguments string `json:"arguments,omitempty"`

	// Refusal snapshots final refusal body on refusal.done.
	Refusal string `json:"refusal,omitempty"`

	// Error carries the APIError on error events.
	Error json.RawMessage `json:"error,omitempty"`
}

type InputItem struct {
	// Type is the variant discriminator. Required.
	Type string `json:"type"`

	// ID echoes the provider-assigned identifier for items echoed
	// from a prior response (reasoning, function_call). Optional on
	// items the caller constructs locally.
	ID string `json:"id,omitempty"`

	// Role is set when Type == "message". Values: "user", "system",
	// "developer", "assistant". The translator should emit "developer"
	// for system-prompt-class messages on Responses (system → developer)
	// per ADR-051 open question 2.
	Role string `json:"role,omitempty"`

	// Content is the typed content-parts array on message items.
	Content []ContentPart `json:"content,omitempty"`

	// CallID is the function-call correlation token shared between
	// function_call (echo) and function_call_output items. Set on
	// both types.
	CallID string `json:"call_id,omitempty"`

	// Name is the function name on function_call items.
	Name string `json:"name,omitempty"`

	// Arguments is the JSON-encoded arguments string on function_call
	// items. Wire-shape mirrors ChatCompletion's
	// tool_calls[].function.arguments — opaque string holding a JSON
	// object.
	Arguments string `json:"arguments,omitempty"`

	// Output is the tool-result body on function_call_output items.
	// Opaque string — typically a JSON-encoded object, but the API
	// accepts any string the caller wants the model to consume.
	Output string `json:"output,omitempty"`

	// Summary is the reasoning summary on reasoning items. Carried
	// as typed parts (mirror of the response shape).
	Summary []SummaryPart `json:"summary,omitempty"`

	// EncryptedContent is the opaque blob echoed on reasoning items
	// in stateless mode. Treated as bytes; do not parse.
	EncryptedContent string `json:"encrypted_content,omitempty"`

	// Status is optionally present on items echoed from a prior
	// response. Possible values include "completed", "in_progress",
	// "incomplete". Producers leave empty on items they construct.
	Status string `json:"status,omitempty"`
}

type InputTokensDetails struct {
	CachedTokens int `json:"cached_tokens,omitempty"`
}

type OutputItem struct {
	// Type is the variant discriminator. Required.
	Type string `json:"type"`

	// ID is the provider-assigned identifier. Required on all output
	// items.
	ID string `json:"id"`

	// Status reports the item's lifecycle state. Common values:
	// "completed", "in_progress", "incomplete".
	Status string `json:"status,omitempty"`

	// Role applies to message items. "assistant" in practice.
	Role string `json:"role,omitempty"`

	// Content is the typed content-parts array on message items.
	Content []ContentPart `json:"content,omitempty"`

	// CallID is the function-call correlation token. Set on
	// function_call items.
	CallID string `json:"call_id,omitempty"`

	// Name is the function name on function_call items.
	Name string `json:"name,omitempty"`

	// Arguments is the JSON-encoded arguments string on function_call
	// items.
	Arguments string `json:"arguments,omitempty"`

	// Summary is the reasoning summary on reasoning items.
	Summary []SummaryPart `json:"summary,omitempty"`

	// EncryptedContent is the opaque reasoning blob the API emits in
	// stateless mode. The caller must echo it back verbatim on the
	// next turn's InputItem to maintain reasoning continuity.
	EncryptedContent string `json:"encrypted_content,omitempty"`
}

type OutputTokensDetails struct {
	ReasoningTokens int `json:"reasoning_tokens,omitempty"`
}

type ReasoningParams struct {
	// Effort is "minimal", "low", "medium", or "high". Empty falls
	// through to the model default.
	Effort string `json:"effort,omitempty"`

	// Summary controls reasoning summary emission. "auto", "concise",
	// "detailed", or empty for none.
	Summary string `json:"summary,omitempty"`
}

type Request struct {
	// Model is the OpenAI model identifier, e.g. "gpt-5.5", "o4-mini",
	// "codex-mini-latest".
	Model string `json:"model"`

	// Input is the heterogeneous input items array. Each element is a
	// typed item (message, function_call echo, function_call_output,
	// reasoning echo). See InputItem.
	Input []InputItem `json:"input"`

	// Instructions optionally pins a system-prompt-class instruction.
	// Equivalent in role to ChatCompletion's "system" message but
	// passed as a top-level field. Recommended for stable persona
	// prose that doesn't belong inline with conversational input.
	Instructions string `json:"instructions,omitempty"`

	// Tools enumerates the function tools available to the model.
	// Hosted tools (file_search, web_search_preview, etc.) are out of
	// scope for Phase 1; future addition extends the Tool type with a
	// discriminator.
	Tools []Tool `json:"tools,omitempty"`

	// ToolChoice controls tool-selection behavior. Accepts the same
	// string values as ChatCompletion ("auto", "required", "none")
	// or an object {"type":"function","name":"..."} forcing a
	// specific tool. json.RawMessage carries the variant.
	ToolChoice json.RawMessage `json:"tool_choice,omitempty"`

	// Reasoning controls reasoning-effort and summary-emission for
	// the o-series and GPT-5.5-class models. The Responses endpoint
	// is the only endpoint where reasoning_effort combines with
	// tool_choice on these model classes.
	Reasoning *ReasoningParams `json:"reasoning,omitempty"`

	// Text controls the output text format. The Responses API uses
	// text.format here rather than the ChatCompletion top-level
	// response_format. The two shapes are not 1:1; the adapter layer
	// translates.
	Text *TextParams `json:"text,omitempty"`

	// Temperature, TopP, MaxOutputTokens carry the standard sampling
	// controls. Names match the Responses API ("max_output_tokens",
	// not "max_tokens" — the two endpoints differ).
	Temperature     *float64 `json:"temperature,omitempty"`
	TopP            *float64 `json:"top_p,omitempty"`
	MaxOutputTokens int      `json:"max_output_tokens,omitempty"`

	// Store enables OpenAI-side conversation state persistence.
	// Stateless mode (store=false) is what this client uses per
	// ADR-051 D2 — caller owns full history and echoes reasoning
	// items per turn. The field is a pointer so the zero value is
	// distinguishable from explicit-false (the API default is true).
	Store *bool `json:"store,omitempty"`

	// PreviousResponseID threads server-side state when Store=true.
	// Unused in stateless mode; carried here for completeness.
	PreviousResponseID string `json:"previous_response_id,omitempty"`

	// Stream selects SSE streaming mode. Phase 1 client only supports
	// false; streaming lands in Phase 2.
	Stream bool `json:"stream,omitempty"`

	// User is the optional end-user identifier for abuse monitoring,
	// per OpenAI's documented usage.
	User string `json:"user,omitempty"`

	// Metadata is the optional operator-provided key/value pairs the
	// API echoes back on the response. Capped at 16 keys, 64-char
	// keys, 512-char values per OpenAI's docs.
	Metadata map[string]string `json:"metadata,omitempty"`

	// Include opts into response fields the API otherwise omits.
	// Most consequential for our path: "reasoning.encrypted_content"
	// — without this opt-in, the API does NOT emit encrypted_content
	// on reasoning output items in stateless mode, breaking
	// cross-turn echo silently. The translator sets this
	// automatically when reasoning is configured (ADR-051 D2).
	//
	// Other documented values (out of scope for Phase 1):
	// "message.input_image.image_url", "file_search_call.results",
	// "code_interpreter_call.outputs".
	Include []string `json:"include,omitempty"`
}

type Response struct {
	// ID is the provider-assigned response identifier ("resp_..."),
	// usable for previous_response_id threading when Store=true (not
	// used in stateless mode but echoed for trace correlation).
	ID string `json:"id"`

	// Object is the response object type, always "response" on
	// success. Carried for parity with OpenAI's documented shape.
	Object string `json:"object,omitempty"`

	// CreatedAt is the response creation Unix timestamp.
	CreatedAt int64 `json:"created_at,omitempty"`

	// Status is "completed", "failed", "in_progress", "cancelled",
	// or "incomplete".
	Status string `json:"status,omitempty"`

	// Error is populated when Status == "failed". The shape mirrors
	// APIError but is embedded in the response body rather than
	// raised as an HTTP error.
	Error json.RawMessage `json:"error,omitempty"`

	// IncompleteDetails is populated when Status == "incomplete".
	IncompleteDetails json.RawMessage `json:"incomplete_details,omitempty"`

	// Instructions echoes back the request's Instructions field.
	Instructions string `json:"instructions,omitempty"`

	// MaxOutputTokens echoes back the request's MaxOutputTokens.
	MaxOutputTokens int `json:"max_output_tokens,omitempty"`

	// Model is the served model identifier (may differ from requested
	// when the provider routes through a model alias).
	Model string `json:"model"`

	// Output is the heterogeneous emitted items array.
	Output []OutputItem `json:"output"`

	// PreviousResponseID is set when this response continued from a
	// prior response. Empty in stateless mode.
	PreviousResponseID string `json:"previous_response_id,omitempty"`

	// Reasoning echoes back the request's Reasoning settings.
	Reasoning *ReasoningParams `json:"reasoning,omitempty"`

	// Store reports whether server-side persistence is active.
	Store *bool `json:"store,omitempty"`

	// Temperature, TopP echo back the sampling controls.
	Temperature *float64 `json:"temperature,omitempty"`
	TopP        *float64 `json:"top_p,omitempty"`

	// Text echoes back the request's Text settings.
	Text *TextParams `json:"text,omitempty"`

	// ToolChoice and Tools echo back the request configuration.
	ToolChoice json.RawMessage `json:"tool_choice,omitempty"`
	Tools      []Tool          `json:"tools,omitempty"`

	// Truncation reports the truncation policy applied. Values
	// include "auto", "disabled". Carried as string for forward
	// compat.
	Truncation string `json:"truncation,omitempty"`

	// Usage reports token consumption.
	Usage *Usage `json:"usage,omitempty"`

	// User echoes back the request's User identifier.
	User string `json:"user,omitempty"`

	// Metadata echoes back the request's Metadata map.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Stream struct {
	// contains filtered or unexported fields
}

type SummaryPart struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

type TextParams struct {
	// Format is the JSON-schema or json_object envelope. Carried as
	// RawMessage so callers can pass through the shape OpenAI
	// documents without this package taking a hard dependency on
	// the schema layout (which has evolved across SDK versions).
	Format json.RawMessage `json:"format,omitempty"`
}

type Tool struct {
	Type        string          `json:"type"`
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty"`
	Strict      bool            `json:"strict,omitempty"`
}

type Usage struct {
	InputTokens        int                 `json:"input_tokens"`
	InputTokensDetails *InputTokensDetails `json:"input_tokens_details,omitempty"`

	OutputTokens        int                  `json:"output_tokens"`
	OutputTokensDetails *OutputTokensDetails `json:"output_tokens_details,omitempty"`

	TotalTokens int `json:"total_tokens"`
}