llmclient

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

type Config struct {
	// ProviderName is the identifier used in logs and metrics (e.g., "openai", "anthropic").
	ProviderName string
	// BaseURL is the base URL for the provider's API (e.g., "https://api.openai.com/v1").
	BaseURL string
	// Retry specifies retry behaviour for failed requests, including backoff and jitter settings.
	Retry config.RetryConfig
	// CircuitBreaker configures the circuit breaker that prevents cascading failures by
	// stopping requests to an unhealthy provider until it recovers.
	CircuitBreaker config.CircuitBreakerConfig
	// Hooks provides optional observability callbacks invoked on request start and end.
	Hooks Hooks
}

type EmptyResponseInfo struct {
	Provider     string // Configured provider name
	ProviderType string // Provider implementation type
	Model        string // Upstream model name, as sent to the provider
	Operation    string // Semantic GenAI operation
	Reason       string // One of the EmptyReason* values
}

type HeaderSetter func(req *http.Request)

type Hooks struct {
	// OnRequestStart is called before a request is sent.
	// The returned context can be used to propagate trace spans or request IDs.
	OnRequestStart func(ctx context.Context, info RequestInfo) context.Context

	// OnRequestEnd is called after a request completes (success or failure).
	// For streaming requests, this is called when the stream starts, not when it closes.
	OnRequestEnd func(ctx context.Context, info ResponseInfo)

	// OnStreamFirstChunk is called once when a successful streaming response
	// body first returns bytes. It is not called for empty or unread streams.
	OnStreamFirstChunk func(ctx context.Context, info ResponseInfo)

	// OnStreamEmpty is called once when a successful streaming response body
	// ends (EOF or read error) before returning any bytes: the stream was
	// established but never delivered. OnStreamFirstChunk is not called for
	// it. Error carries the read error, io.EOF for a clean empty stream.
	OnStreamEmpty func(ctx context.Context, info ResponseInfo)

	// OnEmptyResponse is called when a buffered inference call succeeded at
	// the HTTP level but its normalized response carries no choices, output,
	// or usage. The provider router fires it after decoding, so it follows
	// the OnRequestEnd call that recorded the same attempt as a success.
	OnEmptyResponse func(ctx context.Context, info EmptyResponseInfo)
}

type Request struct {
	Method   string
	Endpoint string
	Model    string
	// Operation explicitly identifies model inference semantics for
	// observability. Leave empty for control-plane and other non-inference calls.
	Operation       string
	Stream          bool   // explicit stream intent; Accept: text/event-stream remains a fallback
	StreamUncertain bool   // bounded opaque-body inspection could not determine stream intent
	Body            any    // Will be JSON marshaled if not nil
	RawBody         []byte // Used as-is (e.g., multipart form bodies). Mutually exclusive with Body and RawBodyReader.
	// RawBodyReader streams the request body without buffering it in memory.
	// It is intended for one-shot passthrough requests and is not replayable for retries.
	RawBodyReader io.Reader
	Headers       http.Header
}

type RequestInfo struct {
	Provider     string // Configured provider name
	ProviderType string // Provider implementation type (e.g., "openai", "anthropic")
	Model        string // Model name (e.g., "gpt-4", "claude-3-opus")
	Operation    string // Semantic GenAI operation; empty for non-inference calls
	Endpoint     string // API endpoint (e.g., "/chat/completions", "/models")
	Method       string // HTTP method (e.g., "POST", "GET")
	Stream       bool   // Whether this is a streaming request
	// StreamUncertain means a bounded opaque-body inspection could not
	// determine intent before the upstream call began.
	StreamUncertain bool
}

type Response struct {
	StatusCode int
	// ContentType is the upstream response Content-Type header, preserved so
	// callers can describe the bytes actually returned (e.g. audio formats).
	ContentType string
	// Header carries the upstream response headers. It is used to audit failed
	// provider attempts; it is not relayed to API clients.
	Header http.Header
	Body   []byte
	// Stream is the live upstream body of a streaming response (DoStreamResponse),
	// where Body stays nil. The caller owns closing it.
	Stream io.ReadCloser
}

type ResponseInfo struct {
	Provider        string        // Configured provider name
	ProviderType    string        // Provider implementation type
	Model           string        // Model name
	Operation       string        // Semantic GenAI operation
	Endpoint        string        // API endpoint
	Method          string        // HTTP method
	StatusCode      int           // HTTP status code (0 if network error)
	Duration        time.Duration // Request duration
	Stream          bool          // Whether this was a streaming request
	StreamUncertain bool          // Whether request stream intent was unknown at dispatch
	Error           error         // Error if request failed (nil on success)
	// CircuitState is the selected provider or model breaker state after this request
	// completed ("closed", "half-open", "open"); empty when the breaker is
	// disabled. It reflects the moment of completion, so metrics built from it
	// update as traffic flows.
	CircuitState string
}