model

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

type Capabilities struct {
	// Streaming indicates if the model supports streaming responses.
	// When true, Generate() will yield incremental chunks with Partial=true.
	Streaming bool

	// Tools indicates if the model supports tool/function calling.
	// When true, you can include tools in Request.Tools.
	Tools bool

	// StructuredOutput indicates if the model supports JSON schema-constrained output.
	// When true, you can provide a schema in Request.Metadata["schema"].
	StructuredOutput bool

	// NativeReasoning indicates if the model exposes its internal reasoning process.
	// When true, Response.Reasoning will be populated with the model's thinking.
	// Examples: OpenAI o1/o3, Gemini 2.0 thinking mode, Claude extended thinking.
	NativeReasoning bool

	// Logprobs indicates if the model can provide token-level log probabilities.
	// When true, Response.Logprobs may be populated (if explicitly requested).
	Logprobs bool

	// Vision indicates if the model can process image inputs.
	// When true, you can include message.ImagePart in your messages.
	Vision bool

	// Audio indicates if the model can process audio inputs.
	Audio bool

	// MaxContextTokens is the maximum context window size in tokens.
	// This is the total budget for input + output tokens.
	// Zero means unknown or unlimited.
	MaxContextTokens int

	// MaxOutputTokens is the maximum number of tokens the model can generate.
	// This may be constrained by configuration or model architecture.
	// Zero means unknown or uses default limits.
	MaxOutputTokens int

	// SupportedModalities lists the input types the model accepts.
	// Common values: "text", "image", "audio", "video"
	SupportedModalities []string
}

type CapabilityDetector interface {
	// Detect returns the capabilities required to handle the request.
	Detect(ctx context.Context, req *Request) (Capabilities, error)
}

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

type CapabilityRouterOption func(*CapabilityRouter)

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

type CircuitState int

type ComplexityEstimator interface {
	// Estimate returns a complexity score between 0.0 (simple) and 1.0 (complex).
	Estimate(ctx context.Context, req *Request) (float64, error)
}

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

type CompositeRouterOption func(*CompositeRouter)

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

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

type CostRouterOption func(*CostBasedRouter)

type DefaultCapabilityDetector struct {
	// ReasoningKeywords are words that indicate reasoning capability is needed.
	ReasoningKeywords []string

	// TokensPerWord is used to estimate token count (default: 1.3)
	TokensPerWord float64
}

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

type Executor interface {
	// Generate executes a model generation with full lifecycle management.
	// It handles observability and error recovery automatically.
	// Returns an iterator that yields responses. For non-streaming requests,
	// a single response is yielded. For streaming requests, incremental
	// responses are yielded as they become available.
	//
	// The iterator pattern (iter.Seq2) provides a unified interface for both
	// streaming and non-streaming execution, allowing consumers to use the
	// same code path regardless of Request.Stream setting.
	//
	// Example (non-streaming):
	//   resp, err := model.Last(executor.Generate(ctx, req))
	//
	// Example (streaming):
	//   for resp, err := range executor.Generate(ctx, req) {
	//       if err != nil { return err }
	//       // Process incremental response
	//   }
	Generate(ctx context.Context, req *Request) iter.Seq2[*Response, error]
}

type ExecutorOption func(*DefaultExecutor)

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

type FallbackRoutedModel struct {
	*RoutedModel
	// contains filtered or unexported fields
}

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

type FallbackRouterOption func(*FallbackRouter)

type HeuristicEstimator struct {
	// ComplexKeywords are words that indicate higher complexity.
	// Default set includes common analytical and technical terms.
	ComplexKeywords []string

	// WordCountWeight is the weight given to word count in complexity.
	// Higher values mean longer messages increase complexity more.
	WordCountWeight float64

	// ContextWeight is the weight given to conversation length.
	ContextWeight float64

	// ToolWeight is the additional complexity when tools are involved.
	ToolWeight float64

	// SchemaWeight is the additional complexity for structured output.
	SchemaWeight float64
}

type Logprobs struct {
	// Content contains log probabilities for each generated token
	Content []TokenLogprob
}

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

type Middleware interface {
	Wrap(next Executor) Executor
}

type MiddlewareFunc func(next Executor) Executor

type Model interface {
	// Generate performs a request that yields Response chunks as an iterator.
	// For streaming, iterate over all chunks to get incremental updates.
	// For blocking, consume only the final response using Last() or similar helpers.
	//
	// ERROR HANDLING:
	//   - Fatal errors (API failures, context canceled, invalid input) are returned
	//     in the second return value (err) as per Go iterator convention
	//   - When err != nil, iteration stops and no more responses are yielded
	//   - Response content is always valid when err == nil
	//
	// Streaming usage:
	//   req := &model.Request{
	//       Messages: messages,
	//       Tools:    myTools,
	//   }
	//   for resp, err := range model.Generate(ctx, req) {
	//       if err != nil {
	//           return fmt.Errorf("generation failed: %w", err)
	//       }
	//       fmt.Print(resp.Message.String()) // Process each chunk
	//   }
	//
	// Blocking usage (helper required):
	//   req := &model.Request{Messages: messages}
	//   resp, err := Last(model.Generate(ctx, req))
	//   if err != nil {
	//       return fmt.Errorf("generation failed: %w", err)
	//   }
	//   fmt.Println(resp.Message.String()) // Process final message
	//   fmt.Println("Reasoning:", resp.Reasoning) // Access native reasoning
	//   fmt.Println("Finish reason:", resp.FinishReason) // Why generation stopped
	//   fmt.Printf("Tokens used: %d\n", resp.Usage.TotalTokens)
	//   if resp.Logprobs != nil {
	//       // Access token probabilities for confidence analysis
	//   }
	//
	// The iterator will yield:
	// - Multiple responses with incremental content (streaming mode)
	// - A single final response (blocking mode)
	//
	// Context cancellation is respected and will stop iteration.
	Generate(ctx context.Context, req *Request) iter.Seq2[*Response, error]

	// Capabilities returns the features and limitations of this model.
	// Use this to discover what the model supports before attempting to use
	// optional features like tools, structured output, or native reasoning.
	//
	// Example:
	//   caps := model.Capabilities()
	//   if caps.Tools {
	//       req.Tools = myTools
	//   }
	//   if caps.NativeReasoning {
	//       // Model will populate Response.Reasoning automatically
	//   }
	Capabilities() Capabilities
}

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

type PriorityRouterOption func(*PriorityRouter)

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

type RandomRouterOption func(*RandomRouter)

type Request struct {
	// Messages is the conversation history to send to the model
	Messages []message.Message

	// Tools is an optional list of tools the model can call during generation.
	// Only relevant if Capabilities().Tools is true.
	Tools []tool.Tool

	// Instructions is an optional instruction text sent with this request.
	// When provided, it will be prepended to the messages (or sent via provider-specific
	// system parameter). This is sent per-request and not stored in conversation history,
	// making it more token-efficient than adding a system message to the state.
	//
	// Instructions supports dynamic resolution from graph state via template placeholders,
	// but by the time it reaches the model, it's already resolved to a plain string.
	//
	// If empty, only the messages from the Messages field are used.
	Instructions string

	// OutputSchema is an optional structured output schema with metadata.
	// When provided (and Capabilities().StructuredOutput is true), the model will
	// be constrained to generate valid JSON matching this schema.
	//
	// This field provides additional metadata compared to Schema:
	//  - Name: Schema identifier for logging/debugging
	//  - Strict: Whether to enforce strict schema validation (provider-specific)
	//  - Description: Human-readable schema description
	//  - Schema: The actual JSON Schema definition
	//
	// If both Schema and OutputSchema are provided, OutputSchema takes precedence.
	//
	// Example:
	//  type Result struct {
	//      Answer     string  `json:"answer" jsonschema:"required"`
	//      Confidence float64 `json:"confidence" jsonschema:"required"`
	//  }
	//  outputSchema, _ := schema.NewOutputSchema("result", Result{})
	//  req.OutputSchema = &outputSchema
	OutputSchema *schema.OutputSchema

	// Stream indicates whether to use streaming mode.
	// When true, Generate() will yield incremental chunks with Partial=true.
	// When false, Generate() will yield only the final complete response.
	Stream bool

	// Metadata contains additional request-specific parameters.
	// Use this for provider-specific options not covered by standard fields.
	Metadata map[string]any
}

type Response struct {
	// Message is the actual message content generated by the model
	Message message.Message

	// Reasoning contains the model's internal reasoning/thinking process.
	// This is populated by reasoning-capable models like:
	// - OpenAI o1/o3 (reasoning_content)
	// - Google Gemini 2.0 Flash (thinking mode)
	// - Anthropic Claude 3.5+ (extended thinking)
	// Empty for models without native reasoning support.
	Reasoning string

	// FinishReason indicates why the model stopped generating tokens.
	// Common values: "stop" (natural completion), "length" (max tokens),
	// "tool_calls" (model wants to call a tool), "content_filter" (content policy).
	// Empty string if not provided by the model.
	FinishReason string

	// Logprobs contains the log probabilities of generated tokens.
	// Useful for understanding model confidence and alternative token choices.
	// Nil if log probabilities were not requested or not supported.
	Logprobs *Logprobs

	// Usage provides token consumption information for cost tracking and observability
	Usage *UsageInfo

	// Metadata contains additional model-specific information
	Metadata map[string]any

	// Partial indicates whether this is an incremental streaming chunk (true)
	// or the final complete response (false).
	// For streaming mode: true for all chunks except the last one.
	// For blocking mode: always false (single complete response).
	// Useful for UI state management (e.g., showing spinners until !Partial).
	Partial bool
}

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

type RoutedModelOption func(*RoutedModel)

type Router interface {
	// Route returns the model to use for the given request.
	// Returns ErrNoModelAvailable if no suitable model can be found.
	Route(ctx context.Context, req *Request) (Model, error)
}

type RouterFunc func(ctx context.Context, req *Request) (Model, error)

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

type TokenLogprob struct {
	// Token is the actual token string
	Token string

	// Logprob is the log probability of this token
	Logprob float64

	// Bytes is the byte representation of the token (optional)
	Bytes []byte

	// TopLogprobs contains alternative tokens and their log probabilities.
	// Useful for understanding what other tokens the model considered.
	TopLogprobs []TopLogprob
}

type TopLogprob struct {
	Token   string
	Logprob float64
	Bytes   []byte
}

type UsageInfo struct {
	// PromptTokens is the number of tokens in the input prompt
	PromptTokens int

	// CompletionTokens is the number of tokens in the generated completion
	CompletionTokens int

	// ReasoningTokens is the number of tokens used for internal reasoning.
	// Only applicable for reasoning-capable models (e.g., OpenAI o1/o3).
	// Zero for models without separate reasoning token tracking.
	ReasoningTokens int

	// TotalTokens is the sum of prompt, completion, and reasoning tokens
	TotalTokens int
}

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

type WeightedRouterOption func(*WeightedRouter)