Documentation
¶
Overview ¶
Package chatwire is the OpenRouter-dialect chat-completions wire format: the standard OpenAI shape plus the routed-gateway extensions (the reasoning request object, the reasoning_details echo, cost-bearing usage) that OpenRouter's API defines and gateways that speak its dialect share.
openrouter and aperture are both thin adapters over this package; the dialect is the shared part, the endpoint, auth and attribution headers are the adapter's.
Index ¶
- func ConvertResponse(cr *ChatResponse) ac.Message
- func EmitSSE(ctx context.Context, r io.Reader, out chan<- ac.StreamEvent, provider string, ...)
- func ReasoningEffort(level ac.ThinkingLevel) string
- func ToAgentUsage(u *WireUsage) *ac.Usage
- func ToLLMUsage(provider, model string, u *WireUsage, latency time.Duration) llm.Usage
- type ChatRequest
- type ChatResponse
- type GenParams
- type WireError
- type WireMessage
- type WireUsage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ConvertResponse ¶
func ConvertResponse(cr *ChatResponse) ac.Message
ConvertResponse maps a non-stream chat response choice to an agentcore message: reasoning first (a thinking block), then text, then every tool call, then the reasoning_details echo in metadata when the response carried one.
func EmitSSE ¶
func EmitSSE(ctx context.Context, r io.Reader, out chan<- ac.StreamEvent, provider string, onUsage func(*WireUsage))
EmitSSE reads the SSE body to completion, emitting agentcore stream events via a shared openaiwire.Emitter and reporting usage once through onUsage. A read error (other than clean EOF) or an error chunk becomes a terminal error event, and skips the terminal done event (there is nothing complete to report).
A body that just ends, with no "[DONE]" frame and no finish_reason, is a truncated response: the done event and the tool-call-end events are skipped so the agent loop raises its own PartialStreamError and retries the turn, instead of persisting a half message with cut-off tool-call arguments.
ctx is the request context. Every send is guarded by it, so a consumer that stops reading releases this goroutine and the HTTP body rather than pinning both for the life of the process.
func ReasoningEffort ¶
func ReasoningEffort(level ac.ThinkingLevel) string
ReasoningEffort maps an agentcore thinking level to the dialect's effort enum. Off maps to "none", which actually turns reasoning off on a reasoning model; only an unspecified level returns "" so the reasoning object is omitted and the model keeps its own default.
func ToAgentUsage ¶
ToAgentUsage maps wire usage to agentcore Usage (Input keeps the OpenAI convention of including cached tokens). nil when nothing was reported. Cost only carries a Total: the dialect reports one call-level cost, not a per-token-class breakdown, so Input/Output/CacheRead/CacheWrite on ac.Cost stay zero rather than claim a precision the wire data doesn't have.
Types ¶
type ChatRequest ¶
type ChatRequest struct {
openaiwire.Request[WireMessage]
MaxTokens int `json:"max_tokens,omitempty"`
Reasoning *reasoningParam `json:"reasoning,omitempty"`
}
ChatRequest embeds the shared request shape and adds the dialect's own max_tokens and reasoning object. openaiwire.Request tags its own max-tokens field max_completion_tokens for kimi; redeclaring MaxTokens here shadows that promoted field for Go access, so it is never assigned and its omitempty keeps it off the wire, leaving only "max_tokens".
func BuildRequest ¶
func BuildRequest(model string, msgs []ac.Message, tools []ac.ToolSpec, cfg ac.CallConfig, gen GenParams, stream bool) ChatRequest
BuildRequest assembles a ChatRequest from agentcore inputs and the resolved per-call config. The reasoning object is set only when the call carries a thinking level. The dialect always returns usage, in the last chunk when streaming, so no stream_options are sent.
type ChatResponse ¶
type ChatResponse struct {
Choices []struct {
Message struct {
Role string `json:"role"`
Content string `json:"content"`
Reasoning string `json:"reasoning"`
ReasoningDetails json.RawMessage `json:"reasoning_details"`
ToolCalls []openaiwire.ToolCall `json:"tool_calls"`
} `json:"message"`
FinishReason string `json:"finish_reason"`
} `json:"choices"`
Usage *WireUsage `json:"usage"`
Error *WireError `json:"error"`
}
ChatResponse is a non-stream chat completion in the dialect.
type GenParams ¶
GenParams carries the adapter-level sampler settings into a request. Pointer fields mean "unset, do not send".
type WireError ¶
WireError is the error block. Gateways differ in whether a numeric code is present; Code stays 0 when it is not and the message stands alone.
type WireMessage ¶
type WireMessage struct {
openaiwire.Message
Reasoning string `json:"reasoning,omitempty"`
ReasoningDetails json.RawMessage `json:"reasoning_details,omitempty"`
}
WireMessage is one OpenAI-format chat message. On assistant messages, ReasoningDetails echoes the provider's structured reasoning back unmodified so a model resumes its chain of thought across tool calls; Reasoning is the plaintext fallback when no details were returned.
func AssistantMessage ¶
func AssistantMessage(m ac.Message) WireMessage
AssistantMessage builds the wire assistant message: text, tool calls, and the reasoning echo. reasoning_details from metadata wins; otherwise the thinking block text is sent as plaintext reasoning.
func ConvertMessages ¶
func ConvertMessages(msgs []ac.Message) []WireMessage
ConvertMessages maps agentcore messages to OpenAI-format wire messages. The system prompt stays inline as a system-role message and tool results are their own "tool" role.
type WireUsage ¶
type WireUsage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
Cost float64 `json:"cost"`
PromptTokensDetails struct {
CachedTokens int `json:"cached_tokens"`
} `json:"prompt_tokens_details"`
CompletionTokensDetails struct {
ReasoningTokens int `json:"reasoning_tokens"`
} `json:"completion_tokens_details"`
}
WireUsage is the dialect's usage block. prompt_tokens INCLUDES cached tokens (OpenAI convention), so ToLLMUsage subtracts to keep llm.Usage additive. Cost is in USD credits and is reported by routes that price; a route that does not price leaves it zero.