llm

type Annotation struct {
	Type       AnnotationType `json:"type"`                 // Type of annotation
	StartIndex int            `json:"start_index"`          // Start position in message text (0-based, JS UTF-16 code units)
	EndIndex   int            `json:"end_index"`            // End position in message text (0-based, JS UTF-16 code units)
	URL        string         `json:"url,omitempty"`        // Source URL (for url_citation)
	Title      string         `json:"title,omitempty"`      // Source title (for url_citation)
	CitedText  string         `json:"cited_text,omitempty"` // Optional: text being cited (for context)
	Index      int            `json:"index"`                // Display index (1-based for UI)
}

type AnnotationType string

type BenchmarkScenario struct {
	Name      string
	Generator StreamGenerator
}

type BotConfig struct {
	ID                 string `json:"id"`
	Name               string `json:"name"`
	DisplayName        string `json:"displayName"`
	CustomInstructions string `json:"customInstructions"`
	ServiceID          string `json:"serviceID"`

	// Model is the optional model override for this bot.
	// If not specified, the service's DefaultModel will be used.
	Model string `json:"model"`

	// Service is deprecated and kept only for backwards compatibility during migration.
	Service *ServiceConfig `json:"service,omitempty"`

	EnableVision       bool               `json:"enableVision"`
	DisableTools       bool               `json:"disableTools"`
	ChannelAccessLevel ChannelAccessLevel `json:"channelAccessLevel"`
	ChannelIDs         []string           `json:"channelIDs"`
	UserAccessLevel    UserAccessLevel    `json:"userAccessLevel"`
	UserIDs            []string           `json:"userIDs"`
	TeamIDs            []string           `json:"teamIDs"`
	MaxFileSize        int64              `json:"maxFileSize"`

	// EnabledNativeTools contains the list of enabled native tools for this bot
	// (see the NativeTool* constants). Which ids a provider actually supports is
	// defined by bifrost.SupportedNativeToolsForServiceType; unsupported values
	// are filtered out at request time. For OpenAI-compatible and Azure services,
	// native tools additionally require UseResponsesAPI.
	EnabledNativeTools []string `json:"enabledNativeTools"`

	// EnabledMCPTools is the per-agent allowlist of MCP tools:
	// only tools matching these (ServerOrigin, ToolName) pairs are kept.
	// Ignored when AutoEnableNewMCPTools is true.
	EnabledMCPTools []EnabledMCPTool `json:"enabledMCPTools"`

	// AutoEnableNewMCPTools, when true, gives this agent access to every currently
	// configured MCP tool and any MCP tool added later. EnabledMCPTools is ignored
	// in that mode. When false, only tools listed in EnabledMCPTools are available.
	AutoEnableNewMCPTools bool `json:"autoEnableNewMCPTools"`

	// MCPDynamicToolLoading controls whether this bot uses the JIT MCP tool loading flow.
	// It defaults to true for omitted legacy config.
	MCPDynamicToolLoading bool `json:"mcpDynamicToolLoading"`

	// UseServiceAccountAuth switches external MCP access for this agent to
	// admin-configured ServiceAccountHeaders instead of per-user OAuth.
	// Embedded Mattermost and plugin MCP servers still run as the requesting user.
	UseServiceAccountAuth bool `json:"useServiceAccountAuth"`

	// ReasoningEnabled determines whether reasoning/thinking is enabled for this bot.
	// Applicable to OpenAI (with ResponsesAPI), Anthropic, and Gemini / Vertex AI.
	ReasoningEnabled bool `json:"reasoningEnabled"`

	// ReasoningEffort determines the reasoning effort level.
	// Valid values: "minimal", "low", "medium", "high".
	// Applicable to OpenAI (with ResponsesAPI) and Gemini / Vertex AI (maps to
	// Gemini's thinkingLevel on 3.0+, and to a thinkingBudget estimate on 2.5).
	// Default: "medium".
	ReasoningEffort string `json:"reasoningEffort"`

	// ThinkingBudget determines the token budget for reasoning/thinking.
	// - Anthropic: must be at least 1024 and cannot exceed the OutputTokenLimit.
	//   Default: 1/4 of OutputTokenLimit, capped at 8192.
	// - Gemini / Vertex AI: maps to thinkingConfig.thinkingBudget. When set, it
	//   takes priority over ReasoningEffort.
	ThinkingBudget int `json:"thinkingBudget"`

	// StructuredOutputEnabled controls how a requested JSONOutputFormat schema is handled.
	// When enabled, the schema is sent natively to the provider to constrain the model's
	// output. When disabled, the schema is converted into prompt instructions and stripped
	// from the provider request, for models/APIs without native structured output support.
	StructuredOutputEnabled bool `json:"structuredOutputEnabled"`

	// MaxToolTurns is the maximum number of LLM-call → tool-execute iterations
	// the tool runner will perform for this agent before stopping. A non-positive
	// value falls back to DefaultMaxToolTurns. Lower this when using a smaller
	// model that tends to call tools in loops; raise it for agents that rely on
	// long dynamic-tool-discovery chains (e.g. search → load → execute).
	MaxToolTurns int `json:"maxToolTurns"`

	// Admin / lifecycle metadata.
	BotUserID    string   `json:"botUserID,omitempty"`
	CreatorID    string   `json:"creatorID,omitempty"`
	AdminUserIDs []string `json:"adminUserIDs,omitempty"`
	CreateAt     int64    `json:"createAt,omitempty"`
	UpdateAt     int64    `json:"updateAt,omitempty"`
	DeleteAt     int64    `json:"deleteAt,omitempty"`
}

type ChannelAccessLevel int

type CompletionRequest struct {
	Posts            []Post
	Context          *Context
	Operation        string
	OperationSubType string
}

type Composition struct {
	Components      []CompositionComponent `json:"components"`
	Total           int                    `json:"total"`
	TotalSource     string                 `json:"total_source"`
	InputTokenLimit int                    `json:"input_token_limit,omitempty"`
	Model           string                 `json:"model,omitempty"`
}

type CompositionComponent struct {
	Source     CompositionSource `json:"source"`
	Proportion float64           `json:"proportion"`
	Tokens     int               `json:"tokens"`
}

type CompositionInput struct {
	Source CompositionSource
	Text   string
}

type CompositionSource string

type Context struct {
	// Server
	Time        string
	ServerName  string
	CompanyName string
	SiteURL     string

	// Location
	Team    *model.Team
	Channel *model.Channel
	Thread  []Post // Normalized posts that already have been formatted. nil if not in a thread or a root post

	// User that is making the request
	RequestingUser *model.User

	// Bot Specific
	BotName            string
	BotUsername        string
	BotUserID          string
	BotModel           string
	BotServiceType     string
	CustomInstructions string

	// ToolAuthMode records the identity mode the tool catalog was built with
	// (ToolAuthModeUser or ToolAuthModeServiceAccount); consumed by token usage attribution.
	ToolAuthMode string

	Tools             *ToolStore
	DisabledToolsInfo []ToolInfo // Info about tools that are unavailable in the current context (e.g., DM-only tools in a channel)
	Parameters        map[string]interface{}

	// ToolCatalog holds request-scoped inputs used while building the tool store.
	ToolCatalog ToolCatalogContext
	// ToolRuntime holds non-prompt tool execution state for this turn.
	ToolRuntime ToolRuntimeContext
}

type ContextOption func(*Context)

type CreatedFile struct {
	ID   string
	Name string
}

type CustomAuthTransport struct {
	// Base is the underlying RoundTripper. If nil, http.DefaultTransport is used.
	Base http.RoundTripper

	// RemoveHeaders is a list of header names to remove from the request.
	RemoveHeaders []string

	// SetHeaders is a map of header names to values to set on the request.
	SetHeaders map[string]string
}

type EnabledMCPTool struct {
	ServerOrigin string `json:"server_origin"`
	ToolName     string `json:"tool_name"`
}

type EnrichToolCallOptions struct {
	// OverwriteDescription replaces an existing Description with the store's
	// value. Rehydration trusts the store; approval preserves the model's text.
	OverwriteDescription bool
	// BareNameFallback retries the lookup by MCPBareName when the primary
	// (name, origin) lookup misses (needed when rehydrating persisted blocks).
	BareNameFallback bool
}

type EventType int

type File struct {
	MimeType string
	Size     int64
	Data     []byte
	Reader   io.Reader
}

type LanguageModel interface {
	ChatCompletion(ctx context.Context, conversation CompletionRequest, opts ...LanguageModelOption) (*TextStreamResult, error)
	ChatCompletionNoStream(ctx context.Context, conversation CompletionRequest, opts ...LanguageModelOption) (string, error)

	// CountTokens returns the exact input-token count. Implementations that
	// can't reach a provider counting endpoint return ErrUnsupportedTokenCount
	// so callers can fall back to EstimateTokens.
	CountTokens(ctx context.Context, request CompletionRequest, opts ...LanguageModelOption) (int, error)

	InputTokenLimit() int
	OutputTokenLimit() int
}

type LanguageModelConfig struct {
	Model                  string
	MaxGeneratedTokens     int
	EnableVision           bool
	JSONOutputFormat       *jsonschema.Schema
	ToolsDisabled          bool
	NativeWebSearchAllowed bool // Allows native web search even when ToolsDisabled is true
	ReasoningDisabled      bool
}

type LanguageModelOption func(*LanguageModelConfig)

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

type LanguageModelWrapper func(LanguageModel) LanguageModel

type MCPDynamicToolTelemetry interface {
	ObserveMCPDynamicToolEvent(botName, event, result string)
}

type MetricsObserver interface {
	ObserveTokenUsage(botName, teamID, userID string, inputTokens, outputTokens int)
}

type ModelInfo struct {
	ID               string `json:"id"`
	DisplayName      string `json:"displayName"`
	InputTokenLimit  *int   `json:"inputTokenLimit,omitempty"`
	OutputTokenLimit *int   `json:"outputTokenLimit,omitempty"`
	ContextLength    *int   `json:"contextLength,omitempty"`
}

type OpenAICompatibleProvider struct {
	// DefaultModel used when none is configured.
	DefaultModel string

	// CreateTransport returns a custom RoundTripper for non-standard auth.
	// If nil, the default HTTP client is used (standard Bearer token auth).
	CreateTransport func(cfg ServiceConfig, base http.RoundTripper) http.RoundTripper

	// DisableStreamOptions disables the stream_options parameter.
	DisableStreamOptions bool

	// UseMaxTokens uses max_tokens instead of max_completion_tokens.
	UseMaxTokens bool
}

type Post struct {
	Role               PostRole
	Message            string
	Files              []File
	ToolUse            []ToolCall
	Reasoning          string // Extended thinking/reasoning content from models that support it
	ReasoningSignature string // Signature for thinking blocks (opaque verification field)

	// ServerTools is provider-executed activity from this turn. The provider
	// drops those results from later requests, so we replay a labeled summary
	// (not reconstructed blocks: fields are truncated and the sandbox is gone).
	ServerTools []ServerToolUse

	// AssistantSegments is arrival order of text vs server-tool activity.
	// ServerTools holds payloads; segments reference them by ID.
	AssistantSegments []TurnSegment
}

type PostRole int

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

type ProviderFile struct {
	// Name is model-influenced for sandbox output; sanitize before use.
	Name        string
	ContentType string
	Content     []byte
}

type ProviderFileDownloader interface {
	DownloadProviderFile(ctx context.Context, ref ProviderFileReference, maxBytes int64) (ProviderFile, error)
}

type ProviderFileReference struct {
	ID            string
	ProviderRoute string
}

type ProviderServices struct {
	FileDownloader ProviderFileDownloader
}

type ReasoningData struct {
	Text      string // The reasoning/thinking text content
	Signature string // Opaque verification signature from the model
}

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

type ServerToolUse struct {
	ID     string `json:"id"`
	Tool   string `json:"tool"`
	Status string `json:"status"`

	// Query is the web_search query.
	Query string `json:"query,omitempty"`
	// URL is the web_fetch target (request URL, replaced by the resolved
	// result URL when the fetch completes).
	URL string `json:"url,omitempty"`
	// Title is the fetched document title (web_fetch).
	Title string `json:"title,omitempty"`
	// SubTool is the code-execution sub-tool: "bash", "text_editor" or
	// "python" (Anthropic), empty for providers without sub-tools.
	SubTool string `json:"sub_tool,omitempty"`
	// Command is the code or shell command executed in the sandbox.
	Command string `json:"command,omitempty"`
	// Output is the execution output (stdout/logs, with stderr appended when
	// present) or other human-readable result summary.
	Output string `json:"output,omitempty"`
	// ErrorCode is the provider error code when the invocation failed.
	ErrorCode string `json:"error_code,omitempty"`
	// FileIDs are provider-side ids of files left in the sandbox output directory.
	FileIDs []string `json:"file_ids,omitempty"`

	// ProviderRoute is the Bifrost route that produced FileIDs. Runtime-only:
	// needed for fallback downloads, never broadcast or persisted for display.
	ProviderRoute string `json:"-"`
}

type ServiceConfig struct {
	ID           string `json:"id"`
	Name         string `json:"name"`
	Type         string `json:"type"`
	APIKey       string `json:"apiKey"`
	OrgID        string `json:"orgId"`
	DefaultModel string `json:"defaultModel"`
	APIURL       string `json:"apiURL"`
	Region       string `json:"region"` // For AWS Bedrock region

	// AWS IAM credentials for Bedrock (optional, takes precedence over APIKey)
	AWSAccessKeyID     string `json:"awsAccessKeyID"`
	AWSSecretAccessKey string `json:"awsSecretAccessKey"`

	// Vertex AI (GCP) configuration. Region is reused from the shared Region field.
	// VertexAuthCredentials holds the service-account JSON; when empty, Bifrost
	// falls back to Application Default Credentials / attached IAM role.
	VertexProjectID       string `json:"vertexProjectID"`
	VertexProjectNumber   string `json:"vertexProjectNumber"`
	VertexAuthCredentials string `json:"vertexAuthCredentials"`

	// Renaming the JSON field to inputTokenLimit would require a migration, leaving as is for now.
	InputTokenLimit         int `json:"tokenLimit"`
	StreamingTimeoutSeconds int `json:"streamingTimeoutSeconds"`

	// Otherwise known as maxTokens
	OutputTokenLimit int `json:"outputTokenLimit"`

	// UseResponsesAPI determines whether to use the new OpenAI Responses API
	// Only applicable to OpenAI and OpenAI-compatible services
	UseResponsesAPI bool `json:"useResponsesAPI"`

	// FallbackServiceID is the ID of another service to fall back to when this
	// service's provider/model fails (e.g. network error, rate limit, model
	// unavailable). The fallback service's DefaultModel is used. Chains are
	// followed (A→B→C) with cycle detection.
	FallbackServiceID string `json:"fallbackServiceID,omitempty"`

	// LoadTestMockConfig is raw JSON merged by loadtest.ParseProfile for ServiceTypeLoadTestMock.
	// Nil, empty, or whitespace-only means the default read/search-heavy profile.
	LoadTestMockConfig json.RawMessage `json:"loadTestMockConfig,omitempty"`
}

type StreamGenerator struct {
	// TotalTextSize is the total bytes of text to generate
	TotalTextSize int
	// ChunkSize is the size of each text chunk
	ChunkSize int
	// IncludeReasoning adds reasoning events before text events
	IncludeReasoning bool
	// IncludeToolCalls ends with tool calls instead of normal end event
	IncludeToolCalls bool
	// IncludeUsage adds a usage event before end
	IncludeUsage bool
	// IncludeAnnotations adds annotation events
	IncludeAnnotations bool
}

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

type TextRange struct {
	Start int
	End   int
}

type TextStreamEvent struct {
	Type  EventType
	Value any
}

type TextStreamResult struct {
	Stream <-chan TextStreamEvent
}

type TokenUsage struct {
	InputTokens       int64   `json:"input_tokens"`
	OutputTokens      int64   `json:"output_tokens"`
	CachedReadTokens  int64   `json:"cached_read_tokens,omitempty"`
	CachedWriteTokens int64   `json:"cached_write_tokens,omitempty"`
	ReasoningTokens   int64   `json:"reasoning_tokens,omitempty"`
	Cost              float64 `json:"cost,omitempty"`
}

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

type TokenUsagePluginLogger interface {
	Info(message string, keyValuePairs ...any)
}

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

type Tool struct {
	Name        string
	Description string
	Schema      any
	Resolver    ToolResolver

	// Title is an optional human-readable display name resolved from MCP
	// metadata (title > annotations.title) and Unicode-sanitized at capture
	// (mcp.UserClients.GetTools). Empty for built-in tools and MCP tools that
	// do not declare one.
	Title string

	// ServerOrigin identifies the MCP server this tool came from (the BaseURL).
	// Empty for built-in (non-MCP) tools. Used for auto-approval decisions.
	ServerOrigin string

	// UserInteraction marks a tool whose pending call is answered by the
	// requesting user in the Mattermost UI instead of executed by the server;
	// the Resolver is only an error backstop. Empty for normal tools.
	UserInteraction string

	// AutoExecute marks a built-in tool that runs without user approval, like
	// the MCP dynamic-loading meta-tools. Reserve it for tools whose only side
	// effect is scoped to the assistant's own response (e.g. CreateFile
	// attaching a file to the reply post). Only honored for tools with an
	// empty ServerOrigin — MCP tools must never auto-execute through this flag.
	AutoExecute bool

	// CallMetadata is forwarded to the tool implementation as MCP CallToolParams.Meta.
	// It is invisible to the LLM, not part of the input schema, and not parsed from the
	// model's arguments. Set it at scope-time via WithCallMetadata when callers need to
	// plumb runtime/protocol info (e.g. before-hook keys) that the underlying server
	// needs but the model shouldn't see or be able to manipulate.
	CallMetadata map[string]any
}

type ToolArgumentGetter func(args any) error

type ToolAuthError struct {
	ServerName   string `json:"server_name"`
	ServerOrigin string `json:"server_origin"`
	AuthURL      string `json:"auth_url"`
	Error        error  `json:"error"`
}

type ToolCall struct {
	ID          string          `json:"id"`
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Arguments   json.RawMessage `json:"arguments"`
	Result      string          `json:"result"`
	Status      ToolCallStatus  `json:"status"`
	MCPBareName string          `json:"mcp_bare_name,omitempty"`

	// Title is the resolved display name for MCP tools that declare one
	// (title > annotations.title, resolved at capture). When empty the webapp
	// prettifies the bare name. Visible to non-requesters like Name.
	Title string `json:"title,omitempty"`

	// UserInteraction mirrors Tool.UserInteraction so the webapp can render
	// the matching interaction UI (e.g. a question card) for pending calls.
	UserInteraction string `json:"user_interaction,omitempty"`

	// WouldAutoExecute marks any pending call that passed the auto-execution
	// policy. The webapp must not show approval controls for it; the server
	// re-checks the policy before executing it on resume.
	WouldAutoExecute bool `json:"would_auto_execute,omitempty"`

	// ServerOrigin identifies the MCP server this tool came from (the BaseURL).
	// Empty for built-in tools. Used for auto-approval decisions.
	ServerOrigin string `json:"server_origin,omitempty"`
}

type ToolCallStatus int

type ToolCatalogContext struct {
	// MCPDynamicToolLoading indicates this context uses strict MCP dynamic loading.
	MCPDynamicToolLoading bool

	// DisabledMCPServerOrigins contains per-user disabled MCP server origins that
	// must be removed before strict registry construction.
	DisabledMCPServerOrigins []string

	// KeepMCPTool, when non-nil, is applied to MCP tools before strict registry
	// construction and before flag-off visible MCP insertion.
	KeepMCPTool func(Tool) bool

	// PreloadedMCPTools contains exact-or-bare MCP tool selectors for internal
	// predefined flows. They are selected only from the already-authorized MCP
	// catalog and are request scoped.
	PreloadedMCPTools []EnabledMCPTool

	// InteractiveUserPresent indicates the requesting user is interactively
	// present in Mattermost (DM or human channel mention) and can answer
	// pending tool approvals. Tools that require a user response (see
	// Tool.UserInteraction) are only cataloged when this is set.
	InteractiveUserPresent bool

	// ResponseFilesSupported indicates the current flow attaches
	// ToolRuntime.CreatedFiles to the bot's streamed response post, so
	// file-creating response tools (CreateFile) may be cataloged. Only
	// conversation entry points that stream a response post set this.
	ResponseFilesSupported bool

	// SandboxFilesAttached is true when this turn's sandbox output will be
	// attached automatically. The model cannot see provider file ids, so the
	// prompt must tell it to copy shareable files into $OUTPUT_DIR.
	SandboxFilesAttached bool
}

type ToolInfo struct {
	Name         string
	Description  string
	ServerOrigin string
}

type ToolLookup struct {
	Tool         Tool
	RuntimeName  string
	BareName     string
	ServerOrigin string
}

type ToolResolver func(ctx context.Context, llmCtx *Context, argsGetter ToolArgumentGetter) (string, error)

type ToolRuntimeContext struct {
	// MCPDynamicToolTelemetry receives low-cardinality dynamic MCP tool events.
	MCPDynamicToolTelemetry                 MCPDynamicToolTelemetry
	MCPDynamicToolSearchUsed                bool
	MCPDynamicLoadedToolNames               map[string]bool
	MCPDynamicSearchLoadCallSuccessRecorded map[string]bool

	// CreatedFiles collects files created by tools during this turn for
	// attachment to the response post.
	CreatedFiles []CreatedFile

	// SandboxFiles are provider files observed this request, in order, with
	// the route that produced them. Populated only from server-tool activity,
	// never from model input.
	SandboxFiles []ProviderFileReference

	// ResponseAttachmentBudget caps how many files response tools may create
	// this turn. 0 means unset (full MaxPostAttachments budget); -1 means the
	// response post has no room left. Set via SetResponseAttachmentBudget.
	ResponseAttachmentBudget int
}

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

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

type TurnSegment struct {
	Kind      string
	Text      string
	Signature string

	// ServerToolID looks up the payload in the latest activity snapshot.
	// The provider updates invocations in place, so the segment only stores the id.
	ServerToolID string
	// contains filtered or unexported fields
}

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

type UserAccessLevel int