config

type AuthSpec struct {
	Type string `yaml:"type,omitempty"` // "api_key" | "oauth" | etc.
	Env  string `yaml:"env,omitempty"`  // env var name for api_key auth
}

type CapabilitySpec struct {
	Type     base.ProviderType
	Model    string
	Defaults map[string]any
	Pricing  *base.PricingDescriptor
}

type ConfigType string

type CredentialConfig = credentials.CredentialConfig

type EmbeddingProviderConfig struct {
	// ID is a stable identifier used to reference this provider from
	// other config blocks (e.g. tool_selector via SelectorContext).
	// Empty falls back to the type name.
	ID string `yaml:"id,omitempty" json:"id,omitempty" jsonschema:"title=ID,description=Stable identifier"`
	// Type selects the implementation: openai, gemini, voyageai, ollama.
	//nolint:lll // jsonschema tags require single line
	Type string `` /* 133-byte string literal not displayed */
	// Model overrides the provider's default embedding model.
	Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"title=Model,description=Embedding model name"`
	// BaseURL overrides the provider's default API endpoint. Useful for
	// self-hosted deployments and OpenAI-compatible gateways.
	//nolint:lll // jsonschema tags require single line
	BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty" jsonschema:"title=BaseURL,description=API endpoint override"`
	// Credential names how to obtain the API key. Same shape as the
	// chat-provider credential block.
	//nolint:lll // jsonschema tags require single line
	Credential *CredentialConfig `yaml:"credential,omitempty" json:"credential,omitempty" jsonschema:"title=Credential,description=API key resolution"`
	// Platform identifies hyperscaler hosting (azure/bedrock/vertex) for
	// keyless auth, mirroring the chat Provider.Platform block. Only
	// "azure" (with an OpenAI-wire provider) is functional today.
	//nolint:lll // jsonschema tags require single line
	Platform *PlatformConfig `` /* 160-byte string literal not displayed */
	// AdditionalConfig carries provider-specific extras (e.g. VoyageAI
	// dimensions, input_type). Each provider documents its own keys.
	//nolint:lll // jsonschema tags require single line
	AdditionalConfig map[string]any `` /* 143-byte string literal not displayed */
}

type ExecBinding struct {
	// Command is the path to the executable, resolved relative to the config file.
	Command string `yaml:"command" json:"command" jsonschema:"title=Command,description=Path to the executable"`
	// Runtime selects the execution mode: "exec" (one-shot, default) or "server" (long-running JSON-RPC).
	//nolint:lll // jsonschema tags require single line
	Runtime string `` /* 138-byte string literal not displayed */
	// Env lists environment variable names required by the process. Values come from the host environment.
	//nolint:lll // jsonschema tags require single line
	Env []string `yaml:"env,omitempty" json:"env,omitempty" jsonschema:"title=Env,description=Required environment variable names"`
	// Args are additional arguments passed to the command.
	//nolint:lll // jsonschema tags require single line
	Args []string `yaml:"args,omitempty" json:"args,omitempty" jsonschema:"title=Args,description=Additional command arguments"`
	// TimeoutMs is the per-invocation timeout in milliseconds.
	//nolint:lll // jsonschema tags require single line
	TimeoutMs int `` /* 133-byte string literal not displayed */
	// Sandbox names a sandbox backend declared under spec.sandboxes.
	// When empty the built-in "direct" backend is used. Only applies to
	// exec hooks; ignored for exec tools and exec eval handlers (which
	// reuse this struct via embedding but do not yet support sandboxing).
	//nolint:lll // jsonschema tags require single line
	Sandbox string `` /* 136-byte string literal not displayed */
}

type ExecHook struct {
	ExecBinding `yaml:",inline"`
	// Hook identifies the hook interface: "provider", "tool", "session", or "eval".
	// "eval" hooks are observational and ignore Phases / Mode — they run
	// once per eval result, fire-and-forget.
	//nolint:lll // jsonschema tags require single line
	Hook string `` /* 126-byte string literal not displayed */
	// Phases lists the hook phases to intercept (e.g. before_call, after_call).
	//nolint:lll // jsonschema tags require single line
	Phases []string `yaml:"phases,omitempty" json:"phases,omitempty" jsonschema:"title=Phases,description=Hook phases to intercept"`
	// Mode is the hook execution mode: "filter" (synchronous, can modify/deny) or "observe" (async, fire-and-forget).
	//nolint:lll // jsonschema tags require single line
	Mode string `` /* 139-byte string literal not displayed */
}

type FileStateStoreConfig struct {
	// Root is the directory under which per-conversation directories live.
	// Required. Created if absent.
	Root string `yaml:"root" json:"root"`

	// FSync controls fsync behavior: "off", "on-save" (default), "on-append".
	//nolint:lll // jsonschema tags require single line
	FSync string `yaml:"fsync,omitempty" json:"fsync,omitempty" jsonschema:"title=FSync Policy,enum=,enum=off,enum=on-save,enum=on-append"`

	// TTLDays, if non-zero, removes conversation directories whose state.json
	// mtime is older than now-TTLDays days at startup.
	TTLDays int `yaml:"ttl_days,omitempty" json:"ttl_days,omitempty"`
}

type HTTPConfig = tools.HTTPConfig

type HTTPTransportConfig struct {
	// MaxConnsPerHost caps the total TCP connections the transport may
	// open to any single upstream host (in-use + idle). Zero means
	// unlimited (the default, matching Go's http.Transport). Set a
	// positive value to cap connections for backends that need it.
	MaxConnsPerHost int `json:"max_conns_per_host,omitempty" yaml:"max_conns_per_host,omitempty"`
	// MaxIdleConnsPerHost caps idle keep-alive connections retained per
	// host for reuse. Zero or negative falls back to
	// providers.DefaultMaxIdleConnsPerHost (100). Usually tracked to
	// MaxConnsPerHost so the whole pool is reusable.
	MaxIdleConnsPerHost int `json:"max_idle_conns_per_host,omitempty" yaml:"max_idle_conns_per_host,omitempty"`
	// IdleConnTimeout is how long an idle keep-alive connection lingers
	// before being closed. Empty falls back to
	// providers.DefaultIdleConnTimeout (90s). Go duration string, e.g.
	// "60s", "5m".
	IdleConnTimeout string `json:"idle_conn_timeout,omitempty" yaml:"idle_conn_timeout,omitempty"`
}

type InferenceDefaults struct {
	AudioClassifier string `yaml:"audio_classifier,omitempty" json:"audio_classifier,omitempty"`
	TextClassifier  string `yaml:"text_classifier,omitempty" json:"text_classifier,omitempty"`
	ImageClassifier string `yaml:"image_classifier,omitempty" json:"image_classifier,omitempty"`
	VideoClassifier string `yaml:"video_classifier,omitempty" json:"video_classifier,omitempty"`
	Embedder        string `yaml:"embedder,omitempty" json:"embedder,omitempty"`
}

type InferenceProviderConfig struct {
	// ID is a stable identifier; defaults to the type when empty.
	ID string `yaml:"id,omitempty" json:"id,omitempty" jsonschema:"title=ID,description=Stable identifier"`
	// Type selects the implementation. Today only "huggingface".
	Type string `yaml:"type" json:"type" jsonschema:"enum=huggingface,title=Type,description=Inference provider type"`
	// Model overrides the provider's default classification model.
	//nolint:lll // jsonschema tags require single line
	Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"title=Model,description=Classification model name"`
	// BaseURL overrides the provider's default API endpoint.
	//nolint:lll // jsonschema tags require single line
	BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty" jsonschema:"title=BaseURL,description=API endpoint override"`
	// Credential names how to obtain the API key.
	//nolint:lll // jsonschema tags require single line
	Credential *CredentialConfig `yaml:"credential,omitempty" json:"credential,omitempty" jsonschema:"title=Credential,description=API key resolution"`
	// AdditionalConfig carries provider-specific extras (e.g. dedicated
	// endpoint flag for HuggingFace).
	//nolint:lll // jsonschema tags require single line
	AdditionalConfig map[string]any `` /* 143-byte string literal not displayed */
}

type K8sManifest interface {
	GetAPIVersion() string
	GetKind() string
	GetName() string
	SetID(id string)
}

type LoggingConfig struct {
	//nolint:lll // jsonschema tags require single line
	APIVersion string `` /* 126-byte string literal not displayed */
	//nolint:lll // jsonschema tags require single line
	Kind     string            `yaml:"kind" jsonschema:"const=LoggingConfig,title=Kind,description=Resource type identifier"`
	Metadata ObjectMeta        `yaml:"metadata,omitempty" jsonschema:"title=Metadata,description=Resource metadata"`
	Spec     LoggingConfigSpec `yaml:"spec" jsonschema:"title=Spec,description=Logging configuration specification"`
}

type LoggingConfigSpec struct {
	// DefaultLevel is the default log level for all modules.
	// Supported values: trace, debug, info, warn, error.
	//nolint:lll // jsonschema tags require single line
	DefaultLevel string `` /* 174-byte string literal not displayed */

	// Format specifies the output format.
	// "json" produces machine-parseable JSON logs.
	// "text" produces human-readable text logs.
	//nolint:lll // jsonschema tags require single line
	Format string `yaml:"format,omitempty" jsonschema:"enum=json,enum=text,default=text,title=Format,description=Log output format"`

	// CommonFields are key-value pairs added to every log entry.
	// Useful for environment, service name, cluster, etc.
	//nolint:lll // jsonschema tags require single line
	CommonFields map[string]string `yaml:"commonFields,omitempty" jsonschema:"title=Common Fields,description=Key-value pairs added to every log entry"`

	// Modules configures logging for specific modules.
	// Module names use dot notation (e.g., runtime.pipeline).
	//nolint:lll // jsonschema tags require single line
	Modules []ModuleLoggingConfig `yaml:"modules,omitempty" jsonschema:"title=Modules,description=Per-module logging configuration"`
}

type MCPServerConfig struct {
	Name       string            `yaml:"name" json:"name"`
	Command    string            `yaml:"command,omitempty" json:"command,omitempty"`
	Args       []string          `yaml:"args,omitempty" json:"args,omitempty"`
	Env        map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	WorkingDir string            `yaml:"working_dir,omitempty" json:"working_dir,omitempty"`
	URL        string            `yaml:"url,omitempty" json:"url,omitempty"`
	Headers    map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	//nolint:lll // jsonschema tags require single line
	Transport string `` /* 310-byte string literal not displayed */
	//nolint:lll // jsonschema tags require single line
	Source string `` /* 226-byte string literal not displayed */
	//nolint:lll // jsonschema tags require single line
	Scope string `` /* 211-byte string literal not displayed */
	//nolint:lll // jsonschema tags require single line
	SourceArgs map[string]any `` /* 223-byte string literal not displayed */
	TimeoutMs  int            `yaml:"timeout_ms,omitempty" json:"timeout_ms,omitempty"`
	ToolFilter *MCPToolFilter `yaml:"tool_filter,omitempty" json:"tool_filter,omitempty"`
}

type MCPToolFilter struct {
	Allowlist []string `yaml:"allowlist,omitempty" json:"allowlist,omitempty"`
	Blocklist []string `yaml:"blocklist,omitempty" json:"blocklist,omitempty"`
}

type MockMediaSpec struct {
	FilePath string `json:"file_path,omitempty" yaml:"file_path,omitempty"` // Local file path (resolved at execution)
	URL      string `json:"url,omitempty" yaml:"url,omitempty"`             // External URL
	MIMEType string `json:"mime_type" yaml:"mime_type"`
	Width    *int   `json:"width,omitempty" yaml:"width,omitempty"`
	Height   *int   `json:"height,omitempty" yaml:"height,omitempty"`
	Caption  string `json:"caption,omitempty" yaml:"caption,omitempty"`
}

type MockPartSpec struct {
	Type  string         `json:"type" yaml:"type"`                     // "text", "image", "audio", "video", "document"
	Text  string         `json:"text,omitempty" yaml:"text,omitempty"` // For type=text
	Media *MockMediaSpec `json:"media,omitempty" yaml:"media,omitempty"`
}

type ModuleLoggingConfig struct {
	// Name is the module name pattern using dot notation.
	// Examples: "runtime", "runtime.pipeline", "providers.openai".
	// More specific names take precedence over less specific ones.
	//nolint:lll // jsonschema tags require single line
	Name string `yaml:"name" jsonschema:"title=Name,description=Module name pattern using dot notation (e.g. runtime.pipeline)"`

	// Level is the log level for this module.
	// Overrides the default level for matching loggers.
	//nolint:lll // jsonschema tags require single line
	Level string `` /* 128-byte string literal not displayed */

	// Fields are additional key-value pairs added to logs from this module.
	//nolint:lll // jsonschema tags require single line
	Fields map[string]string `yaml:"fields,omitempty" jsonschema:"title=Fields,description=Additional fields added to logs from this module"`
}

type MultimodalConfig = tools.MultimodalConfig

type ObjectMeta struct {
	Name      string            `yaml:"name,omitempty" json:"name,omitempty" jsonschema:"title=Name,description=Name of the resource"`                      //nolint:lll
	Namespace string            `yaml:"namespace,omitempty" json:"namespace,omitempty" jsonschema:"title=Namespace,description=Namespace for the resource"` //nolint:lll
	Labels    map[string]string ``                                                                                                                          //nolint:lll
	/* 126-byte string literal not displayed */
	Annotations map[string]string `yaml:"annotations,omitempty" json:"annotations,omitempty" jsonschema:"title=Annotations,description=Additional metadata"` //nolint:lll
}

type PlatformConfig = credentials.PlatformConfig

type Pricing struct {
	InputCostPer1K  float64 `json:"input_cost_per_1k" yaml:"input_cost_per_1k"`
	OutputCostPer1K float64 `json:"output_cost_per_1k" yaml:"output_cost_per_1k"`
}

type Provider struct {
	ID    string `json:"id,omitempty" yaml:"id,omitempty"`
	Type  string `json:"type" yaml:"type"`
	Model string `json:"model,omitempty" yaml:"model,omitempty"`
	// Voice is the vendor-specific voice identifier used when Capability is
	// "tts". For Cartesia it's the voice UUID; for ElevenLabs the voice ID;
	// for OpenAI the voice name (alloy, nova, etc.). Ignored for LLM/STT
	// providers.
	Voice string `json:"voice,omitempty" yaml:"voice,omitempty"`
	// SampleRate is the audio sample rate in Hz for TTS providers. Common
	// values: 16000 (telephony), 24000 (default for most TTS vendors),
	// 48000 (high quality). Ignored for non-TTS providers.
	SampleRate int `json:"sample_rate,omitempty" yaml:"sample_rate,omitempty"`
	// AudioFiles is the list of PCM fixtures used by the mock TTS provider
	// (capability=tts, type=mock). The mock service rotates through these
	// files on each Synthesize() call. Paths are relative to the arena
	// config directory. Ignored when type != "mock" or capability != "tts".
	AudioFiles []string `json:"audio_files,omitempty" yaml:"audio_files,omitempty"`
	// Role tags what this provider does. One of "llm" (default), "tts", or
	// "stt". The arena uses this to route the provider to the correct
	// registry and to skip non-llm providers when building the
	// agent-under-test matrix. Distinct from the Capabilities field which
	// lists per-model feature flags (vision, tools, etc.).
	//
	// Renamed from "capability" 2026-05-18 to avoid singular/plural
	// collision with Capabilities. The field is required for tts/stt
	// providers; defaults to "llm" when empty.
	Role string `` //nolint:lll // enum list can't be split inside a struct tag
	/* 135-byte string literal not displayed */
	BaseURL string `json:"base_url,omitempty" yaml:"base_url,omitempty"`
	// Headers specifies custom HTTP headers to include in every request to
	// this provider. Useful for OpenAI-compatible gateways (OpenRouter,
	// LiteLLM, etc.) that require app attribution or custom auth headers.
	// Values are plain strings — use the credentials field for secrets.
	// Collisions with built-in provider headers (Authorization, Content-Type,
	// etc.) are rejected at request time.
	Headers          map[string]string      `json:"headers,omitempty" yaml:"headers,omitempty"`
	RateLimit        RateLimit              `json:"rate_limit,omitempty" yaml:"rate_limit,omitempty"`
	Defaults         ProviderDefaults       `json:"defaults,omitempty" yaml:"defaults,omitempty"`
	Pricing          Pricing                `json:"pricing,omitempty" yaml:"pricing,omitempty"`
	PricingCorrectAt string                 `json:"pricing_correct_at,omitempty" yaml:"pricing_correct_at,omitempty"`
	IncludeRawOutput bool                   `json:"include_raw_output,omitempty" yaml:"include_raw_output,omitempty"` // Include raw API requests in output for debugging
	AdditionalConfig map[string]interface{} `json:"additional_config,omitempty" yaml:"additional_config,omitempty"`   // Additional provider-specific configuration
	Credential       *CredentialConfig      `json:"credential,omitempty" yaml:"credential,omitempty"`
	Platform         *PlatformConfig        `json:"platform,omitempty" yaml:"platform,omitempty"`
	// Capabilities lists what this provider supports: text, streaming, vision, tools, json, audio, video, documents
	Capabilities []string `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`
	// UnsupportedParams lists model parameters not supported by this provider model
	// (e.g. "temperature", "top_p", "max_tokens").
	UnsupportedParams []string `json:"unsupported_params,omitempty" yaml:"unsupported_params,omitempty"`
	// RequestTimeout caps the wall-clock duration of request/response HTTP
	// calls (Predict, embeddings, etc.) via http.Client.Timeout. Does NOT
	// apply to SSE streaming calls, which are unbounded by wall-clock and
	// governed only by StreamIdleTimeout and context cancellation. Empty
	// falls back to the provider's default (typically 60s). Go duration
	// string, e.g. "2m", "90s".
	RequestTimeout string `json:"request_timeout,omitempty" yaml:"request_timeout,omitempty"`
	// StreamIdleTimeout bounds how long an SSE streaming body may remain
	// silent (no bytes) between reads before the stream is aborted. The
	// timer resets on every byte received, so legitimately long-running
	// streams (e.g. hours-long sessions delivering sparse output) are not
	// affected. Empty falls back to providers.DefaultStreamIdleTimeout
	// (30s). Go duration string, e.g. "60s", "2m".
	StreamIdleTimeout string `json:"stream_idle_timeout,omitempty" yaml:"stream_idle_timeout,omitempty"`
	// StreamRetry configures bounded retry for streaming requests that fail
	// before any content chunk has been forwarded downstream (the
	// "pre-first-chunk window"). Targets transient HTTP/2 stream resets and
	// initial-connection errors without risking duplicate content emission.
	// Disabled by default. See docs/local-backlog/STREAMING_RETRY_AT_SCALE.md.
	StreamRetry *StreamRetryConfig `json:"stream_retry,omitempty" yaml:"stream_retry,omitempty"`
	// StreamMaxConcurrent caps the number of concurrent streaming requests
	// the provider will have in flight at any time. Requests beyond the
	// limit block on the caller's context — a short deadline acts as
	// fail-fast, a long one queues. Zero or negative means unlimited
	// (current default). Reduces goroutine/timer explosion under load.
	StreamMaxConcurrent int `json:"stream_max_concurrent,omitempty" yaml:"stream_max_concurrent,omitempty"`
	// HTTPTransport configures the per-provider HTTP connection pool.
	// Lets operators raise MaxConnsPerHost and related limits above the
	// single-process defaults when scaling up concurrent streams per
	// upstream. Note that raising MaxConnsPerHost alone is not sufficient
	// if the upstream advertises a low SETTINGS_MAX_CONCURRENT_STREAMS
	// (RFC 7540 §6.5.2) — the effective ceiling is
	// MaxConnsPerHost × SETTINGS_MAX_CONCURRENT_STREAMS per upstream.
	// See AltairaLabs/PromptKit#873.
	HTTPTransport *HTTPTransportConfig `json:"http_transport,omitempty" yaml:"http_transport,omitempty"`
}

type ProviderConfig struct {
	APIVersion string     `yaml:"apiVersion" json:"apiVersion"`
	Kind       string     `yaml:"kind" json:"kind"`
	Metadata   ObjectMeta `yaml:"metadata,omitempty" json:"metadata,omitempty"`
	Spec       Provider   `yaml:"spec" json:"spec"`
}

type ProviderConfigK8s struct {
	APIVersion string            `yaml:"apiVersion" json:"apiVersion"`
	Kind       string            `yaml:"kind" json:"kind"`
	Metadata   metav1.ObjectMeta `yaml:"metadata,omitempty" json:"metadata,omitempty"`
	Spec       Provider          `yaml:"spec" json:"spec"`
}

type ProviderDefaults struct {
	Temperature float32 `json:"temperature" yaml:"temperature"`
	TopP        float32 `json:"top_p" yaml:"top_p"`
	MaxTokens   int     `json:"max_tokens" yaml:"max_tokens"`
	// PromptCaching controls Anthropic prompt caching. Omit or set true to enable
	// (the default); set false to disable. Only affects Claude providers.
	PromptCaching *bool `json:"prompt_caching,omitempty" yaml:"prompt_caching,omitempty"`
}

type ProviderSpec struct {
	Name         string // from metadata.name
	Impl         string // implementation discriminator (e.g. "openai", "imagen")
	Endpoint     string // base URL
	Auth         AuthSpec
	Timeouts     TimeoutsSpec
	Retry        RetrySpec
	Capabilities []CapabilitySpec
}

type RateLimit struct {
	RPS   int `json:"rps" yaml:"rps"`
	Burst int `json:"burst" yaml:"burst"`
}

type RedisConfig struct {
	// Address of the Redis server (e.g., "localhost:6379")
	Address string `yaml:"address" json:"address"`

	// Password for Redis authentication (optional)
	Password string `yaml:"password,omitempty" json:"password,omitempty"`

	// Database number (0-15, default is 0)
	Database int `yaml:"database,omitempty" json:"database,omitempty"`

	// TTL for conversation state (e.g., "24h", "7d"). Default is "24h"
	TTL string `yaml:"ttl,omitempty" json:"ttl,omitempty"`

	// Prefix for Redis keys (default is "promptkit")
	Prefix string `yaml:"prefix,omitempty" json:"prefix,omitempty"`
}

type RequestMapping = tools.RequestMapping

type ResponseMapping = tools.ResponseMapping

type RetrySpec struct {
	MaxAttempts int    `yaml:"max_attempts,omitempty"`
	Backoff     string `yaml:"backoff,omitempty"`
}

type RuntimeConfig struct {
	//nolint:lll // jsonschema tags require single line
	APIVersion string `` /* 144-byte string literal not displayed */
	Kind       string `yaml:"kind" json:"kind" jsonschema:"const=RuntimeConfig,title=Kind,description=Resource type"`
	//nolint:lll // jsonschema tags require single line
	Metadata ObjectMeta `yaml:"metadata,omitempty" json:"metadata,omitempty" jsonschema:"title=Metadata,description=Resource metadata"`
	//nolint:lll // jsonschema tags require single line
	Spec RuntimeConfigSpec `yaml:"spec" json:"spec" jsonschema:"title=Spec,description=Runtime configuration specification"`
}

type RuntimeConfigSpec struct {
	// Providers configures LLM providers (credentials, models, rate limits).
	//nolint:lll // jsonschema tags require single line
	Providers []Provider `yaml:"providers,omitempty" json:"providers,omitempty" jsonschema:"title=Providers,description=LLM provider configurations"`

	// EmbeddingProviders configures embedding providers (OpenAI, Gemini,
	// VoyageAI, Ollama). Used for RAG retrieval and as the shared
	// provider supplied to selectors via SelectorContext.Embeddings.
	// First entry becomes the default RAG provider unless one is set
	// programmatically via WithContextRetrieval.
	//nolint:lll // jsonschema tags require single line
	EmbeddingProviders []EmbeddingProviderConfig `` /* 158-byte string literal not displayed */

	// TTSProviders configures text-to-speech providers (OpenAI,
	// ElevenLabs, Cartesia). First entry becomes the default TTS
	// service unless one is set programmatically via WithTTS or
	// WithVADMode.
	//nolint:lll // jsonschema tags require single line
	TTSProviders []TTSProviderConfig `` /* 145-byte string literal not displayed */

	// STTProviders configures speech-to-text providers (OpenAI). First
	// entry becomes the default STT service unless one is set
	// programmatically via WithVADMode.
	//nolint:lll // jsonschema tags require single line
	STTProviders []STTProviderConfig `` /* 145-byte string literal not displayed */

	// InferenceProviders configures inference (classify) providers
	// (HuggingFace). Used by classify-backed eval handlers
	// (audio_emotion, text_toxicity, …). First declared provider
	// implementing a task becomes that task's default.
	//nolint:lll // jsonschema tags require single line
	InferenceProviders []InferenceProviderConfig `` /* 169-byte string literal not displayed */

	// Tools binds pack tool names to implementations (HTTP, mock, or exec).
	//nolint:lll // jsonschema tags require single line
	Tools map[string]*ToolSpec `` /* 130-byte string literal not displayed */

	// MCPServers configures MCP tool servers.
	//nolint:lll // jsonschema tags require single line
	MCPServers []MCPServerConfig `` /* 126-byte string literal not displayed */

	// StateStore configures conversation state persistence.
	//nolint:lll // jsonschema tags require single line
	StateStore *StateStoreConfig `` /* 145-byte string literal not displayed */

	// Logging configures log levels, format, and per-module settings.
	//nolint:lll // jsonschema tags require single line
	Logging *LoggingConfigSpec `yaml:"logging,omitempty" json:"logging,omitempty" jsonschema:"title=Logging,description=Logging configuration"`

	// Evals binds pack eval type names to external process implementations.
	// Eval types not bound here resolve to built-in Go handlers.
	//nolint:lll // jsonschema tags require single line
	Evals map[string]*ExecBinding `` /* 137-byte string literal not displayed */

	// Hooks configures external process hooks for pipeline lifecycle events.
	//nolint:lll // jsonschema tags require single line
	Hooks map[string]*ExecHook `yaml:"hooks,omitempty" json:"hooks,omitempty" jsonschema:"title=Hooks,description=External hook process configurations"`

	// Sandboxes declares named sandbox backends that exec hooks can
	// reference via their "sandbox:" field. Each entry's "mode" selects
	// a factory registered via runtime/hooks/sandbox.RegisterFactory;
	// the remaining fields are passed verbatim to that factory as the
	// config map. The built-in "direct" mode resolves without any
	// consumer opt-in; other modes (docker_run, docker_exec, kubectl_exec,
	// or custom) require that their factory has been registered before
	// RuntimeConfig is loaded.
	//nolint:lll // jsonschema tags require single line
	Sandboxes map[string]*SandboxConfig `` /* 149-byte string literal not displayed */

	// Selectors declares named selectors that narrow the skill or tool
	// set surfaced to the LLM. Each entry spawns an external process
	// that reads a JSON query on stdin and writes selected IDs on
	// stdout. Referenced from spec.skills.selector / spec.tools.selector
	// by name.
	//nolint:lll // jsonschema tags require single line
	Selectors map[string]*SelectorConfig `` /* 162-byte string literal not displayed */

	// Skills carries skill-specific runtime configuration, most notably
	// the selector binding. Pack-level skill definitions live in the
	// pack itself; this block only covers runtime wiring.
	//nolint:lll // jsonschema tags require single line
	Skills *SkillsConfig `yaml:"skills,omitempty" json:"skills,omitempty" jsonschema:"title=Skills,description=Runtime skill configuration"`

	// ToolSelector names a selector declared under spec.selectors that
	// narrows the pack-declared tool set surfaced to the LLM each turn.
	// System tools (skill__, a2a__, workflow__, mcp__, memory__) are
	// always preserved regardless of selection. When empty, the prompt's
	// full allowedTools list is offered to the provider.
	//
	// This is a flat field (not nested under tools:) because the existing
	// spec.tools map binds exec tool implementations.
	//nolint:lll // jsonschema tags require single line
	ToolSelector string `` /* 203-byte string literal not displayed */
}

type STTProviderConfig struct {
	// ID is a stable identifier; defaults to the type when empty.
	ID string `yaml:"id,omitempty" json:"id,omitempty" jsonschema:"title=ID,description=Stable identifier"`
	// Type selects the implementation. Today only "openai".
	Type string `yaml:"type" json:"type" jsonschema:"enum=openai,title=Type,description=STT provider type"`
	// Model overrides the provider's default transcription model.
	//nolint:lll // jsonschema tags require single line
	Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"title=Model,description=Transcription model name"`
	// BaseURL overrides the provider's default API endpoint.
	//nolint:lll // jsonschema tags require single line
	BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty" jsonschema:"title=BaseURL,description=API endpoint override"`
	// Credential names how to obtain the API key.
	//nolint:lll // jsonschema tags require single line
	Credential *CredentialConfig `yaml:"credential,omitempty" json:"credential,omitempty" jsonschema:"title=Credential,description=API key resolution"`
	// AdditionalConfig carries provider-specific extras.
	//nolint:lll // jsonschema tags require single line
	AdditionalConfig map[string]any `` /* 143-byte string literal not displayed */
}

type SandboxConfig struct {
	// Mode names a registered sandbox factory. "direct" ships in-tree
	// and needs no extra registration.
	//nolint:lll // jsonschema tags require single line
	Mode string `` /* 164-byte string literal not displayed */

	// Config carries mode-specific configuration. Each factory
	// documents its own keys. For example, the docker_run example
	// expects "image", "network", and "mounts".
	Config map[string]any `yaml:",inline" json:"-" jsonschema:"-"`
}

type SchemaValidationError struct {
	Field       string
	Description string
	Value       interface{}

	// Keyword mirrors runtime/prompt/schema.ValidationError.Keyword
	// (e.g. "enum", "additional_property_not_allowed").
	Keyword string
	// ValidValues lists valid alternatives when computable — enum allowed
	// values, or sibling property names for additionalProperties.
	ValidValues []string
	// Suggestions are nearest-match candidates from ValidValues.
	Suggestions []string
}

type SchemaValidationResult struct {
	Valid  bool
	Errors []SchemaValidationError
}

type SelectorConfig struct {
	// Command is the path to the selector executable, resolved relative
	// to the config file by the loader.
	Command string `yaml:"command" json:"command" jsonschema:"title=Command,description=Path to the selector executable"`
	// Args are additional arguments passed to the command.
	//nolint:lll // jsonschema tags require single line
	Args []string `yaml:"args,omitempty" json:"args,omitempty" jsonschema:"title=Args,description=Additional command arguments"`
	// Env lists environment variable names required by the process.
	// Values come from the host environment.
	//nolint:lll // jsonschema tags require single line
	Env []string `yaml:"env,omitempty" json:"env,omitempty" jsonschema:"title=Env,description=Required environment variable names"`
	// TimeoutMs is the per-invocation timeout in milliseconds.
	//nolint:lll // jsonschema tags require single line
	TimeoutMs int `` /* 133-byte string literal not displayed */
	// Sandbox names a sandbox backend declared under spec.sandboxes.
	// When empty the built-in "direct" backend is used.
	//nolint:lll // jsonschema tags require single line
	Sandbox string `` /* 136-byte string literal not displayed */
}

type SkillsConfig struct {
	// Selector names a selector declared under spec.selectors.
	// When empty, all eligible skills are surfaced (current behavior).
	//nolint:lll // jsonschema tags require single line
	Selector string `` /* 140-byte string literal not displayed */
}

type StateStoreConfig struct {
	// Type specifies the state store implementation: "memory", "redis", or "file"
	Type string `yaml:"type" json:"type"`

	// Redis configuration (only used when Type is "redis")
	Redis *RedisConfig `yaml:"redis,omitempty" json:"redis,omitempty"`

	// File configuration (only used when Type is "file")
	File *FileStateStoreConfig `yaml:"file,omitempty" json:"file,omitempty"`
}

type StreamRetryBudgetConfig struct {
	// RatePerSec is the sustained token refill rate. Empty or non-positive
	// disables the budget (unbounded retries).
	RatePerSec float64 `json:"rate_per_sec,omitempty" yaml:"rate_per_sec,omitempty"`
	// Burst is the maximum number of tokens that can accumulate. Empty
	// or non-positive disables the budget.
	Burst int `json:"burst,omitempty" yaml:"burst,omitempty"`
}

type StreamRetryConfig struct {
	// Enabled turns the retry loop on. Defaults to false — streaming retry
	// changes latency/billing semantics and must be opt-in per provider.
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	// MaxAttempts is the total number of attempts including the initial
	// request. A value of 2 means "initial request plus at most one retry".
	// Values <1 are treated as 1 (no retry). Empty falls back to 2.
	MaxAttempts int `json:"max_attempts,omitempty" yaml:"max_attempts,omitempty"`
	// InitialDelay is the base delay before the first retry. Subsequent
	// retries use exponential backoff with full jitter up to MaxDelay. Go
	// duration string. Empty falls back to "250ms".
	InitialDelay string `json:"initial_delay,omitempty" yaml:"initial_delay,omitempty"`
	// MaxDelay caps the per-attempt backoff delay. Go duration string.
	// Empty falls back to "2s".
	MaxDelay string `json:"max_delay,omitempty" yaml:"max_delay,omitempty"`
	// RetryWindow controls which point in the stream lifecycle is still
	// eligible for retry. "pre_first_chunk" (the only currently supported
	// value) retries only if no content chunk has been forwarded yet.
	// Future values may be gated on deduplication support.
	RetryWindow string `json:"retry_window,omitempty" yaml:"retry_window,omitempty"`
	// Budget configures a token bucket that rate-limits retry attempts
	// across all in-flight requests on this provider. Protects against
	// thundering-herd reconnects when a single upstream connection reset
	// kills many streams simultaneously. When nil, retries are unbounded
	// (Phase 1 behavior).
	Budget *StreamRetryBudgetConfig `json:"budget,omitempty" yaml:"budget,omitempty"`
}

type TTSProviderConfig struct {
	// ID is a stable identifier; defaults to the type when empty.
	ID string `yaml:"id,omitempty" json:"id,omitempty" jsonschema:"title=ID,description=Stable identifier"`
	// Type selects the implementation: openai, elevenlabs, cartesia.
	//nolint:lll // jsonschema tags require single line
	Type string `yaml:"type" json:"type" jsonschema:"enum=openai,enum=elevenlabs,enum=cartesia,title=Type,description=TTS provider type"`
	// Model overrides the provider's default voice/model.
	Model string `yaml:"model,omitempty" json:"model,omitempty" jsonschema:"title=Model,description=Voice or model name"`
	// BaseURL overrides the provider's default API endpoint.
	//nolint:lll // jsonschema tags require single line
	BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty" jsonschema:"title=BaseURL,description=API endpoint override"`
	// Credential names how to obtain the API key.
	//nolint:lll // jsonschema tags require single line
	Credential *CredentialConfig `yaml:"credential,omitempty" json:"credential,omitempty" jsonschema:"title=Credential,description=API key resolution"`
	// AdditionalConfig carries provider-specific extras (Cartesia
	// `ws_url`, etc.).
	//nolint:lll // jsonschema tags require single line
	AdditionalConfig map[string]any `` /* 143-byte string literal not displayed */
}

type TimeoutsSpec struct {
	Request time.Duration `yaml:"request,omitempty"`
}

type ToolClientConfig struct {
	Consent        *ToolConsentConfig `json:"consent,omitempty" yaml:"consent,omitempty"`
	TimeoutMs      int                `json:"timeout_ms,omitempty" yaml:"timeout_ms,omitempty"`
	Categories     []string           `json:"categories,omitempty" yaml:"categories,omitempty"`
	ValidateOutput bool               `json:"validate_output,omitempty" yaml:"validate_output,omitempty"`
}

type ToolConsentConfig struct {
	Required        bool   `json:"required" yaml:"required"`
	Message         string `json:"message,omitempty" yaml:"message,omitempty"`
	DeclineStrategy string `json:"decline_strategy,omitempty" yaml:"decline_strategy,omitempty"`
}

type ToolData struct {
	FilePath string `json:"file_path,omitempty"`
	Data     []byte `json:"data,omitempty"`
}

type ToolSpec struct {
	Name        string `json:"name,omitempty" yaml:"name,omitempty"`
	Description string `json:"description" yaml:"description"`
	// InputSchema is a JSON Schema Draft-07 document for the tool's arguments.
	InputSchema interface{} `json:"input_schema" yaml:"input_schema"`
	// OutputSchema is a JSON Schema Draft-07 document for the tool's return value.
	OutputSchema interface{} `json:"output_schema" yaml:"output_schema"`
	Mode         string      `` //nolint:lll
	/* 218-byte string literal not displayed */
	TimeoutMs  int         `json:"timeout_ms,omitempty" yaml:"timeout_ms,omitempty"`
	MockResult interface{} `` //nolint:lll
	/* 230-byte string literal not displayed */
	MockTemplate string `` //nolint:lll
	/* 385-byte string literal not displayed */
	MockParts  []MockPartSpec `json:"mock_parts,omitempty" yaml:"mock_parts,omitempty"`
	HTTPConfig *HTTPConfig    `json:"http,omitempty" yaml:"http,omitempty"`
	// Exec subprocess configuration (mode: exec)
	ExecConfig *ExecBinding `json:"exec,omitempty" yaml:"exec,omitempty"`
	// Client-side execution configuration
	ClientConfig *ToolClientConfig `json:"client,omitempty" yaml:"client,omitempty"`
}

type ValidationError struct {
	Field   string
	Message string
	Value   string
}

type VoiceBinding struct {
	ID       string `yaml:"id" json:"id"`             // Voice id used by personas
	Provider string `yaml:"provider" json:"provider"` // TTS provider id (must exist in spec.tts_providers)
}