Documentation
¶
Overview ¶
Package openaiwire holds the OpenAI-shaped chat-completions wire format shared by every native adapter whose provider speaks that dialect (kimi, openrouter): the request and response structs, message and tool conversion, stop-reason mapping, the SSE emitter and the authenticated HTTP client. Provider-specific extensions (kimi's partial/name and reasoning_effort, openrouter's reasoning object and reasoning_details) stay in the adapter that needs them; this package only knows the shape every OpenAI-compatible provider shares.
Index ¶
- Constants
- func ArgsString(args json.RawMessage) string
- func AssembleMessage(reasoning, content string, calls []ToolCall, finish string) ac.Message
- func ConvertMessages[M any](msgs []ac.Message, assistant func(ac.Message) M, ...) []M
- func MapStopReason(reason string) ac.StopReason
- func RawArgs(s string) json.RawMessage
- func ReadSSE(r io.Reader, onData func(data string) (stop bool, err error)) (done bool, err error)
- func Sanitize(s string, max int) string
- func Send(ctx context.Context, out chan<- ac.StreamEvent, ev ac.StreamEvent) bool
- type Client
- func (c *Client) NewRequest(ctx context.Context, path string, body []byte, apiKeyOverride string) (*http.Request, error)
- func (c *Client) Post(ctx context.Context, path string, body any, apiKeyOverride string) ([]byte, error)
- func (c *Client) Stream(ctx context.Context, path string, body []byte, apiKeyOverride string) (io.ReadCloser, error)
- type Delta
- type Emitter
- type Func
- type Message
- type Request
- type StreamToolCall
- type Tool
- type ToolCall
- type ToolFunc
Constants ¶
const ( // MaxErrorText bounds endpoint-chosen text echoed into an error, which // may reach logs or clients. MaxErrorText = 512 )
Limits on what an endpoint can make this process hold or echo. A user-supplied endpoint can send anything, and one tenant must not be able to exhaust a host shared with others.
Variables ¶
This section is empty.
Functions ¶
func ArgsString ¶
func ArgsString(args json.RawMessage) string
ArgsString renders tool-call args (json.RawMessage) as the OpenAI arguments string. Empty args become "{}" so the wire message stays valid.
func AssembleMessage ¶
AssembleMessage builds an assistant message from its parts, in the order the agent loop expects (thinking, text, tool calls). Shared by the non-stream path and the stream's terminal message so both produce identical structure. The adapter adds any extra metadata (such as openrouter's reasoning_details echo) to the returned message afterwards.
func ConvertMessages ¶
func ConvertMessages[M any](msgs []ac.Message, assistant func(ac.Message) M, plain func(role, content, toolCallID string) M) []M
ConvertMessages maps agentcore messages to the provider's wire message type M, delegating construction to two adapter-supplied constructors: assistant builds the (provider-specific) assistant message, and plain builds every other role from a role, its text content and, for a tool result, the tool_call_id it answers. The system prompt stays inline as a system-role message and tool results are their own "tool" role (not a user message), matching the OpenAI shape every such provider speaks.
func MapStopReason ¶
func MapStopReason(reason string) ac.StopReason
MapStopReason maps an OpenAI finish_reason to an agentcore StopReason.
func RawArgs ¶
func RawArgs(s string) json.RawMessage
RawArgs is the inverse: a wire arguments string to json.RawMessage, defaulting empty to "{}" so the enclosing message stays JSON-serializable.
func ReadSSE ¶
ReadSSE reads r line by line to completion, extracting each "data:" frame's payload and invoking onData with it. It stops at a data frame of "[DONE]" or when onData reports stop=true, and returns any error onData reports or any read error other than a clean EOF (an SSE body ends without a trailing frame, so that is not itself an error).
done reports whether the stream terminated on an explicit "[DONE]" frame. A false done with a nil error means the body simply ended: the response may be truncated mid message, so the caller must not treat what it accumulated as a complete turn unless a finish_reason arrived.
A line longer than maxSSELine fails the stream: no real chunk is that big, and buffering one without limit lets an endpoint exhaust memory.
func Sanitize ¶ added in v0.6.0
Sanitize makes endpoint-chosen text safe to put in an error: newlines and tabs become spaces, other control characters (terminal escapes) are dropped, and the result is cut to max bytes on a rune boundary.
func Send ¶
func Send(ctx context.Context, out chan<- ac.StreamEvent, ev ac.StreamEvent) bool
Send delivers ev on out unless ctx is already done, reporting whether the send happened. Every producer send goes through this: a consumer that stops reading must not pin the producer goroutine or the HTTP body it holds for the life of the process.
Types ¶
type Client ¶
type Client struct {
HTTP *http.Client
BaseURL string
APIKey string
Provider string
Headers map[string]string
// StreamHTTP sends streaming requests. It carries no overall timeout: a
// long generation is legitimate, and a stalled one is caught by StreamIdle
// instead. Falls back to HTTP when nil.
StreamHTTP *http.Client
// StreamIdle aborts a stream whose body has produced nothing for this
// long. Zero disables the watchdog.
StreamIdle time.Duration
}
Client is the shared authenticated JSON-over-HTTP client both adapters use to talk to their OpenAI-shaped chat-completions endpoint. Provider names the source in every error message; Headers carries any extra headers a provider always sends (OpenRouter's HTTP-Referer/X-Title attribution), applied to every request alongside the bearer token.
Every request retries the transient statuses (429 and 5xx) so a coding agent's long run is not ended by one throttled call, and every failure is classified: a provider message about the context window comes back as agentcore's ContextOverflowError so the agent loop compacts rather than aborts.
func (*Client) NewRequest ¶
func (c *Client) NewRequest(ctx context.Context, path string, body []byte, apiKeyOverride string) (*http.Request, error)
NewRequest builds an authenticated JSON POST, with any configured extra headers set. apiKeyOverride overrides the client's APIKey when non-empty.
func (*Client) Post ¶
func (c *Client) Post(ctx context.Context, path string, body any, apiKeyOverride string) ([]byte, error)
Post marshals body, sends it to path and returns the response bytes, failing on a non-200 with the response text. apiKeyOverride overrides the client's APIKey when non-empty (per-call key rotation).
func (*Client) Stream ¶
func (c *Client) Stream(ctx context.Context, path string, body []byte, apiKeyOverride string) (io.ReadCloser, error)
Stream sends body to path as an SSE request and returns the live body for the caller to read to completion and close. Retries apply to the initial status only: once a byte of the body has been consumed the turn is under way, and resending it would duplicate whatever the model already emitted. The returned reader enforces StreamIdle, so a body that goes quiet fails with an error wrapping agentcore.ErrProviderStreamIdle.
type Delta ¶
type Delta struct {
Content string
Reasoning string
ToolCalls []StreamToolCall
}
Delta is one incremental update extracted from a provider's own SSE chunk type. The adapter decodes its chunk (with its own quirks: kimi's reasoning_content, openrouter's reasoning/reasoning_details) and hands Emitter.Handle a Delta so accumulation and event framing stay in one place.
type Emitter ¶
type Emitter struct {
Out chan<- ac.StreamEvent
// contains filtered or unexported fields
}
Emitter accumulates streamed content and frames it as agentcore StreamEvents. It tracks whether the thinking/text blocks are open and builds tool calls by provider index, assigning each block a stable agentcore content index. The adapter decodes its own chunk type and feeds this Emitter one Delta per choice via Handle.
func NewEmitter ¶
func NewEmitter(ctx context.Context, out chan<- ac.StreamEvent) *Emitter
NewEmitter builds an Emitter that sends its framed StreamEvents on out. ctx is the request context: once it is done the Emitter stops sending and reports Aborted, so the adapter can drop the rest of the stream.
func (*Emitter) Aborted ¶
Aborted reports whether a send was abandoned because the request context ended. The adapter checks it before sending its own terminal events.
func (*Emitter) Finish ¶
Finish returns the finish_reason seen so far, empty when the provider has not reported one. An empty Finish once the body has ended means the stream was cut short, not that the model stopped.
func (*Emitter) Flush ¶
func (e *Emitter) Flush(final func(reasoning, content string, calls []ToolCall, finish string) ac.Message) ac.Message
Flush closes any open blocks, emits a tool-call-end (with the completed call) for each streamed tool call and returns the terminal message built by final from the accumulated reasoning, text, tool calls and finish reason. The caller decorates the result (Usage, provider-specific metadata) and sends it as the terminal Done event; usage and mid-stream errors are the adapter's concern, not this package's. Only a stream that actually finished may be flushed: a truncated one has no complete tool call or message to report.
func (*Emitter) Handle ¶
Handle processes one delta: reasoning first (thinking), then text, then tool calls, recording the finish reason when present. The adapter calls Handle once per choice in its chunk (and, when a provider can attach more than one reasoning fragment to a single chunk, once more per fragment).
type Func ¶
Func is a tool call's function name and arguments (a JSON-encoded string, not a raw object, per the OpenAI wire format).
type Message ¶
type Message struct {
Role string `json:"role"`
Content string `json:"content,omitempty"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
}
Message is the OpenAI-format chat message shape common to every adapter: a role, its content, any tool calls an assistant message carries and an optional tool_call_id for tool-role messages. Provider extensions (kimi's partial/name, openrouter's reasoning/reasoning_details) live in the adapter's own message type, which embeds this one.
type Request ¶
type Request[M any] struct { Model string `json:"model"` Messages []M `json:"messages"` Tools []Tool `json:"tools,omitempty"` ToolChoice any `json:"tool_choice,omitempty"` // ResponseFormat carries agentcore's per-call response format through as // is: *agentcore.ResponseFormat already marshals to the OpenAI shape. // Leave it nil to keep it off the wire; a typed nil pointer would encode // as a JSON null and some providers reject that. ResponseFormat any `json:"response_format,omitempty"` Stream bool `json:"stream"` MaxTokens int `json:"max_completion_tokens,omitempty"` Temperature *float64 `json:"temperature,omitempty"` TopP *float64 `json:"top_p,omitempty"` }
Request is the shared OpenAI-format chat-completions request body. M is the provider's own message type, which embeds Message and adds its own fields, so Messages can carry provider extensions without this package knowing them. An adapter that needs a different wire name for a shared field (kimi sends max_completion_tokens, openrouter sends max_tokens) redeclares that field in its own request struct. The redeclaration shadows the promoted one for Go field access only: encoding/json keys on the JSON name, so a differently tagged promoted field is still a candidate. It works because nothing ever assigns the promoted field, and its omitempty keeps the zero value off the wire, leaving only the adapter's own tag.
type StreamToolCall ¶
type StreamToolCall struct {
Index int `json:"index"`
ID string `json:"id"`
Type string `json:"type"`
Function Func `json:"function"`
}
StreamToolCall is one tool_call delta fragment from an SSE chunk. Index identifies which call the fragment belongs to: id and name arrive on the first fragment for that index, arguments stream across later ones.
type Tool ¶
Tool is an OpenAI-format function tool declaration.
func ConvertTools ¶
ConvertTools maps agentcore tool specs to OpenAI-format function tools, skipping any tool with an empty name.
type ToolCall ¶
type ToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function Func `json:"function"`
}
ToolCall is a completed OpenAI-format tool call, on an assistant message or a non-stream response.
func ToolCallsFrom ¶
ToolCallsFrom renders an agentcore message's tool calls as wire tool calls, so every agentcore tool call round-trips to a wire tool_call and a replayed transcript keeps an exact tool-call set. Both adapters call this from their own assistant-message constructor.