llmcall

type AssembledResponse struct {
	Text      string
	ToolCalls []AssembledToolCall
}

type AssembledToolCall struct {
	ID        string
	Name      string
	Arguments string
}

type AudioPart struct {
	MIMEType string `json:"mimeType,omitempty" yaml:"mimeType,omitempty"`
	DataB64  string `json:"dataB64,omitempty" yaml:"dataB64,omitempty"`
	URL      string `json:"url,omitempty" yaml:"url,omitempty"`
	Wire     Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Capabilities struct {
	// Operations are the gen_ai.operation.name values the schema
	// serves ("chat", "text_completion", "embeddings", ...).
	Operations []string `json:"operations,omitempty" yaml:"operations,omitempty"`

	Tools             bool `json:"tools,omitempty" yaml:"tools,omitempty"`
	ParallelToolCalls bool `json:"parallelToolCalls,omitempty" yaml:"parallelToolCalls,omitempty"`
	ImageInput        bool `json:"imageInput,omitempty" yaml:"imageInput,omitempty"`
	AudioInput        bool `json:"audioInput,omitempty" yaml:"audioInput,omitempty"`
	FileInput         bool `json:"fileInput,omitempty" yaml:"fileInput,omitempty"`
	Reasoning         bool `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
	StructuredOutput  bool `json:"structuredOutput,omitempty" yaml:"structuredOutput,omitempty"`
	Streaming         bool `json:"streaming,omitempty" yaml:"streaming,omitempty"`
	// SystemRole reports whether the schema carries system content
	// natively (top-level field or system role) rather than requiring
	// it to be folded into the first user message.
	SystemRole bool `json:"systemRole,omitempty" yaml:"systemRole,omitempty"`
}

type Choice struct {
	Message      Message      `json:"message,omitempty" yaml:"message,omitempty"`
	FinishReason FinishReason `json:"finishReason,omitempty" yaml:"finishReason,omitempty"`
	// FinishReasonRaw is the provider's literal finish value when the
	// canonical mapping is lossy; empty when the mapping is bijective.
	FinishReasonRaw string `json:"finishReasonRaw,omitempty" yaml:"finishReasonRaw,omitempty"`
	Wire            Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type CitationPart struct {
	Title   string `json:"title,omitempty" yaml:"title,omitempty"`
	URL     string `json:"url,omitempty" yaml:"url,omitempty"`
	Snippet string `json:"snippet,omitempty" yaml:"snippet,omitempty"`
	Wire    Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Codec interface {
	DecodeRequest(in RequestInput) (*Request, error)
	EncodeRequest(req *Request, opts EncodeOptions) (*EncodedRequest, error)
	DecodeResponse(in ResponseInput, req *Request) (*Response, error)
	EncodeResponse(resp *Response, opts EncodeOptions) (*EncodedResponse, error)
}

type EncodeOptions struct {
	Mode Mode
}

type EncodedRequest struct {
	Body          []byte
	Path          string
	SetHeaders    map[string]string
	RemoveHeaders []string

	// DroppedExtras counts unmodeled fields and unknown parts dropped
	// in strip mode (0 in preserve mode); surfaced as the
	// clrk.translation.dropped_extras telemetry attribute.
	DroppedExtras int

	// Exact reports that Body is the verbatim decode-time capture,
	// emitted via the equality-gated passthrough (EncodeRaw).
	Exact bool
}

type EncodedResponse struct {
	Body          []byte
	SetHeaders    map[string]string
	DroppedExtras int
	Exact         bool
}

type ExtraField struct {
	Key   string          `json:"key,omitempty" yaml:"key,omitempty"`
	Value json.RawMessage `json:"value,omitempty" yaml:"value,omitempty"`
}

type FieldEmitter func(e *ObjectEncoder)

type FilePart struct {
	MIMEType string `json:"mimeType,omitempty" yaml:"mimeType,omitempty"`
	DataB64  string `json:"dataB64,omitempty" yaml:"dataB64,omitempty"`
	URL      string `json:"url,omitempty" yaml:"url,omitempty"`
	Name     string `json:"name,omitempty" yaml:"name,omitempty"`
	Wire     Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type FinishReason string

type GenerationConfig struct {
	MaxTokens     json.Number `json:"maxTokens,omitempty" yaml:"maxTokens,omitempty"`
	Temperature   json.Number `json:"temperature,omitempty" yaml:"temperature,omitempty"`
	TopP          json.Number `json:"topP,omitempty" yaml:"topP,omitempty"`
	TopK          json.Number `json:"topK,omitempty" yaml:"topK,omitempty"`
	StopSequences []string    `json:"stopSequences,omitempty" yaml:"stopSequences,omitempty"`
	Wire          Wire        `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ImagePart struct {
	MIMEType string `json:"mimeType,omitempty" yaml:"mimeType,omitempty"`
	DataB64  string `json:"dataB64,omitempty" yaml:"dataB64,omitempty"`
	URL      string `json:"url,omitempty" yaml:"url,omitempty"`
	Wire     Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Input struct {
	Method        string
	Path          string
	ReqHeaders    map[string]string
	RespHeaders   map[string]string
	ReqBody       []byte
	ReqTruncated  bool
	RespBody      []byte
	RespTruncated bool
}

type MalformedError struct {
	Provider string
	Detail   string
	Err      error
}

type Message struct {
	Role  Role   `json:"role,omitempty" yaml:"role,omitempty"`
	Parts []Part `json:"parts,omitempty" yaml:"parts,omitempty"`
	Wire  Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Mode int

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

type Parser interface {
	Parse(in Input) *ProviderInfo
}

type Part struct {
	Type PartType `json:"type,omitempty" yaml:"type,omitempty"`

	Text             *TextPart             `json:"text,omitempty" yaml:"text,omitempty"`
	Image            *ImagePart            `json:"image,omitempty" yaml:"image,omitempty"`
	Audio            *AudioPart            `json:"audio,omitempty" yaml:"audio,omitempty"`
	File             *FilePart             `json:"file,omitempty" yaml:"file,omitempty"`
	ToolCall         *ToolCallPart         `json:"toolCall,omitempty" yaml:"toolCall,omitempty"`
	ToolCallResponse *ToolCallResponsePart `json:"toolCallResponse,omitempty" yaml:"toolCallResponse,omitempty"`
	Reasoning        *ReasoningPart        `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
	Refusal          *RefusalPart          `json:"refusal,omitempty" yaml:"refusal,omitempty"`
	Citation         *CitationPart         `json:"citation,omitempty" yaml:"citation,omitempty"`

	Wire Wire `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type PartType string

type Provider struct {
	// Name is the canonical gen_ai.system value ("anthropic", "openai",
	// "google_genai"). It is the key the route table, backend schema
	// resolution, and telemetry all share.
	Name string

	// Aliases are CRD short names that resolve to Name via Canonical
	// (e.g. AIProviderRouteMatch.Provider "google" -> "google_genai").
	Aliases []string

	// Hosts are the exact :authority hosts (lowercase, port already
	// stripped by the caller) this provider serves.
	Hosts []string

	// MatchHost, when set, replaces the exact Hosts match — for
	// wildcard surfaces like *.openai.azure.com. It receives a
	// lowercased host.
	MatchHost func(host string) bool

	// Telemetry extracts ProviderInfo from captured transactions.
	// Required for built-in providers.
	Telemetry Parser

	// Codec converts this provider's wire format to and from the IR.
	// May be nil: the provider is then registered (telemetry, routing)
	// but not translatable.
	Codec Codec

	// Capabilities declare what the schema can express; consumed by
	// cross-schema backend selection.
	Capabilities Capabilities

	// StreamCodec converts this provider's streamed response framing
	// to and from StreamEvents. Nil disables streaming translation for
	// any pair that includes this provider.
	StreamCodec StreamCodec

	// EnsureStreamUsage, when set, rewrites a raw request body in this
	// provider's wire schema so streamed responses always report
	// terminal usage (OpenAI's stream_options.include_usage). Returns
	// (newBody, true) only when a rewrite was needed. Nil for schemas
	// whose streams carry usage unconditionally. The hook decodes the
	// body — hot-path callers pre-probe with a cheap byte scan
	// (parsers.BodyAdvertisesStream).
	EnsureStreamUsage func(path string, body []byte) ([]byte, bool)

	// AuthHeaders are the credential-bearing request headers this
	// provider's clients send (lowercase). Translated requests shed
	// the union across all registered providers (AuthHeaderUnion) —
	// an agent-supplied credential belongs to the source schema and
	// must never reach a different upstream.
	AuthHeaders []string

	// ErrorBody shapes a proxy-generated error payload (translation
	// failures, fail-closed 502s) in this provider's error envelope —
	// the client SDK is mid-parse of this schema, and a foreign blob
	// would surface as a second, more confusing error at the call
	// site. Nil falls back to the OpenAI envelope (see ErrorBodyFor).
	ErrorBody func(msg string) []byte
}

type ProviderInfo struct {
	// System is the canonical OTel gen_ai.system value
	// (e.g. "anthropic", "openai", "azure_openai", "google_genai",
	// "aws_bedrock"). Always non-empty when the parser ran.
	System string

	// Operation is the gen_ai.operation.name value
	// ("chat", "text_completion", "embeddings", ...). Empty when the
	// parser couldn't classify the path.
	Operation string

	// RequestModel is the model the caller asked for. From the request
	// body's "model" field. Empty when the request body wasn't decodable
	// (truncation, non-JSON).
	RequestModel string

	// ResponseModel is the model the provider actually served (often
	// equal to RequestModel but can include a version suffix). Some
	// providers don't echo it for non-streaming responses.
	ResponseModel string

	// InputTokens / OutputTokens are the provider-reported usage
	// counts. Zero when not present (truncation, error response with no
	// usage block, streaming response with no usage block).
	InputTokens  int64
	OutputTokens int64

	// StreamResponse is true when the response advertised
	// content-type: text/event-stream. Token accounting is intentionally
	// skipped on streams in MVP — providers report usage inconsistently
	// across SSE chunks.
	StreamResponse bool

	// UsageVisible indicates that the response body contained the usage
	// block we look for. False when truncation hid it; lets the OTLP
	// sink emit clrk.body.usage_visible=false to nudge operators to
	// raise CaptureBody.MaxBytes.
	UsageVisible bool

	// ResponseContent is the assistant message reconstructed from a
	// streamed response: concatenated text plus any tool calls. Unlike
	// the fields above it is NOT filled by the Parser — enrichRecord
	// populates it post-parse via AssembleStreamedResponse, which drives
	// the serving schema's StreamCodec so every provider is reassembled
	// by one path. Empty for non-streamed responses (whose body is
	// already a single readable JSON), when no stream codec exists, and
	// when nothing decoded. Best-effort: partial under a truncated
	// capture (the keep-last-N ring drops the head of long streams).
	ResponseContent string
}

type ReasoningPart struct {
	Text      string `json:"text,omitempty" yaml:"text,omitempty"`
	Signature string `json:"signature,omitempty" yaml:"signature,omitempty"`
	Wire      Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type RefusalPart struct {
	Text string `json:"text,omitempty" yaml:"text,omitempty"`
	Wire Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Request struct {
	// Provider is the canonical gen_ai.system name of the schema the
	// request was decoded from, stamped by DecodeRequest.
	Provider string `json:"provider,omitempty" yaml:"provider,omitempty"`

	// Operation is the gen_ai.operation.name value ("chat", ...).
	Operation string `json:"operation,omitempty" yaml:"operation,omitempty"`

	// Model is the requested model ID. For schemas that carry the model
	// in the URL rather than the body (Gemini), codecs keep Wire.Path
	// authoritative and synthesize the path on encode.
	Model string `json:"model,omitempty" yaml:"model,omitempty"`

	// System is the system/instructions content. Kept separate from
	// Messages because providers disagree on whether it is a message
	// role or a top-level field.
	System []Part `json:"system,omitempty" yaml:"system,omitempty"`

	Messages   []Message        `json:"messages,omitempty" yaml:"messages,omitempty"`
	Tools      []ToolDefinition `json:"tools,omitempty" yaml:"tools,omitempty"`
	ToolChoice *ToolChoice      `json:"toolChoice,omitempty" yaml:"toolChoice,omitempty"`
	Generation GenerationConfig `json:"generation,omitempty" yaml:"generation,omitempty"`
	Stream     bool             `json:"stream,omitempty" yaml:"stream,omitempty"`

	// Wire holds root-level bookkeeping: the full original body in Raw,
	// the original :path, and modeled request headers.
	Wire Wire `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type RequestInput struct {
	Method  string
	Path    string
	Headers map[string]string
	Body    []byte
}

type Response struct {
	// Provider is the canonical gen_ai.system name of the schema the
	// response was decoded from.
	Provider string `json:"provider,omitempty" yaml:"provider,omitempty"`

	ID      string   `json:"id,omitempty" yaml:"id,omitempty"`
	Model   string   `json:"model,omitempty" yaml:"model,omitempty"`
	Choices []Choice `json:"choices,omitempty" yaml:"choices,omitempty"`
	Usage   Usage    `json:"usage,omitempty" yaml:"usage,omitempty"`

	Wire Wire `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ResponseInput struct {
	Status  int
	Headers map[string]string
	Body    []byte
}

type Role string

type SSEEvent struct {
	// Name is the "event:" field; empty for bare data frames.
	Name string
	// Data is the "data:" payload, multi-line continuations joined
	// with '\n' per the SSE spec.
	Data []byte
}

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

type Shadow struct {
	Raw json.RawMessage `json:"raw,omitempty" yaml:"raw,omitempty"`
	Val any             `json:"val,omitempty" yaml:"val,omitempty"`
}

type StreamCodec interface {
	// NewStreamDecoder returns a decoder for a streamed response to
	// req — the request as sent upstream, in this provider's schema.
	NewStreamDecoder(req *Request) StreamDecoder
	// NewStreamEncoder returns an encoder rendering a stream for the
	// client that sent req in this provider's schema. req supplies
	// fallbacks (model) and framing choices.
	NewStreamEncoder(req *Request) StreamEncoder
}

type StreamContentEnd struct {
	Index int `json:"index,omitempty" yaml:"index,omitempty"`
}

type StreamContentStart struct {
	Index int  `json:"index,omitempty" yaml:"index,omitempty"`
	Part  Part `json:"part,omitempty" yaml:"part,omitempty"`
}

type StreamDecoder interface {
	// Decode parses the events completed by chunk. eos marks the final
	// chunk: the decoder flushes its reassembly buffer, closes any
	// still-open blocks, synthesizes a terminal done event when the
	// provider's own terminator never arrived, and reports a dangling
	// partial frame via MalformedError.
	Decode(chunk []byte, eos bool) ([]StreamEvent, error)
}

type StreamEncoder interface {
	// ContentType is the content-type the encoded stream rides on.
	ContentType() string
	// Encode appends the wire rendering of events. Empty output is
	// valid — events may buffer until a block completes, and a
	// mid-frame upstream chunk completes no events at all.
	Encode(events []StreamEvent) ([]byte, error)
}

type StreamError struct {
	Code    string `json:"code,omitempty" yaml:"code,omitempty"`
	Message string `json:"message,omitempty" yaml:"message,omitempty"`
}

type StreamEvent struct {
	Type StreamEventType `json:"type,omitempty" yaml:"type,omitempty"`

	Start          *StreamStart          `json:"start,omitempty" yaml:"start,omitempty"`
	ContentStart   *StreamContentStart   `json:"contentStart,omitempty" yaml:"contentStart,omitempty"`
	TextDelta      *StreamTextDelta      `json:"textDelta,omitempty" yaml:"textDelta,omitempty"`
	ToolCallDelta  *StreamToolCallDelta  `json:"toolCallDelta,omitempty" yaml:"toolCallDelta,omitempty"`
	ReasoningDelta *StreamReasoningDelta `json:"reasoningDelta,omitempty" yaml:"reasoningDelta,omitempty"`
	ContentEnd     *StreamContentEnd     `json:"contentEnd,omitempty" yaml:"contentEnd,omitempty"`
	Usage          *Usage                `json:"usage,omitempty" yaml:"usage,omitempty"`
	Finish         *StreamFinish         `json:"finish,omitempty" yaml:"finish,omitempty"`
	Error          *StreamError          `json:"error,omitempty" yaml:"error,omitempty"`

	Wire Wire `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type StreamEventType string

type StreamFinish struct {
	FinishReason    FinishReason `json:"finishReason,omitempty" yaml:"finishReason,omitempty"`
	FinishReasonRaw string       `json:"finishReasonRaw,omitempty" yaml:"finishReasonRaw,omitempty"`
}

type StreamReasoningDelta struct {
	Index int    `json:"index,omitempty" yaml:"index,omitempty"`
	Text  string `json:"text,omitempty" yaml:"text,omitempty"`
}

type StreamStart struct {
	ID    string `json:"id,omitempty" yaml:"id,omitempty"`
	Model string `json:"model,omitempty" yaml:"model,omitempty"`
}

type StreamTextDelta struct {
	Index int    `json:"index,omitempty" yaml:"index,omitempty"`
	Text  string `json:"text,omitempty" yaml:"text,omitempty"`
}

type StreamToolCallDelta struct {
	Index          int    `json:"index,omitempty" yaml:"index,omitempty"`
	ID             string `json:"id,omitempty" yaml:"id,omitempty"`
	Name           string `json:"name,omitempty" yaml:"name,omitempty"`
	ArgumentsDelta string `json:"argumentsDelta,omitempty" yaml:"argumentsDelta,omitempty"`
}

type TextPart struct {
	Text string `json:"text,omitempty" yaml:"text,omitempty"`
	Wire Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ToolCallPart struct {
	ID        string          `json:"id,omitempty" yaml:"id,omitempty"`
	Name      string          `json:"name,omitempty" yaml:"name,omitempty"`
	Arguments json.RawMessage `json:"arguments,omitempty" yaml:"arguments,omitempty"`
	Wire      Wire            `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ToolCallResponsePart struct {
	ToolCallID string `json:"toolCallID,omitempty" yaml:"toolCallID,omitempty"`
	Parts      []Part `json:"parts,omitempty" yaml:"parts,omitempty"`
	IsError    bool   `json:"isError,omitempty" yaml:"isError,omitempty"`
	Wire       Wire   `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ToolChoice struct {
	Mode ToolChoiceMode `json:"mode,omitempty" yaml:"mode,omitempty"`
	Name string         `json:"name,omitempty" yaml:"name,omitempty"`
	Wire Wire           `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type ToolChoiceMode string

type ToolDefinition struct {
	Name        string          `json:"name,omitempty" yaml:"name,omitempty"`
	Description string          `json:"description,omitempty" yaml:"description,omitempty"`
	Parameters  json.RawMessage `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	Wire        Wire            `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Usage struct {
	InputTokens  int64 `json:"inputTokens,omitempty" yaml:"inputTokens,omitempty"`
	OutputTokens int64 `json:"outputTokens,omitempty" yaml:"outputTokens,omitempty"`
	Wire         Wire  `json:"wire,omitempty" yaml:"wire,omitempty"`
}

type Wire struct {
	// KeyOrder is the node's full original member sequence — modeled
	// and extra keys interleaved. The encoder walks it to reproduce
	// source order; modeled keys absent from it (added after decode)
	// are appended in the codec's canonical order.
	KeyOrder []string `json:"keyOrder,omitempty" yaml:"keyOrder,omitempty"`

	// Extras are the unmodeled members in encounter order.
	Extras []ExtraField `json:"extras,omitempty" yaml:"extras,omitempty"`

	// Shadow maps a modeled key to its source-byte fallback. See Shadow.
	Shadow map[string]Shadow `json:"shadow,omitempty" yaml:"shadow,omitempty"`

	// Hints record wire-shape variants the typed fields can't express,
	// e.g. {"content": "string"} when an OpenAI message carried string
	// content rather than a parts array. Keys and values are
	// codec-private conventions.
	Hints map[string]string `json:"hints,omitempty" yaml:"hints,omitempty"`

	// Raw is the verbatim source subtree. On root nodes (Request,
	// Response) it is the full original body, used by the
	// equality-gated passthrough (EncodeRaw). On unknown Parts it is
	// the whole unmodeled block.
	Raw json.RawMessage `json:"raw,omitempty" yaml:"raw,omitempty"`

	// Path is the original request :path. Root Request only.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Headers are modeled request headers captured at decode time
	// (e.g. anthropic-version), lowercased keys. Root Request only.
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
}