Documentation
¶
Overview ¶
Package utils provides utility functions for token estimation, tool call validation, and embedded error detection. These primitives enable consumers to make routing decisions and validate API interactions without imposing specific patterns.
Package utils provides utility functions for the application.
Index ¶
- Constants
- Variables
- func ByteThresholdForTokens(tokens int) int
- func ContainsAnyPattern(body string, patterns []string) bool
- func ContainsCommonErrors(body string) bool
- func EstimateTokensFromBytes(byteCount int) int
- func EstimateTokensFromMessages(messages []types.ChatMessage) int
- func EstimateTokensFromString(s string) int
- func FixMissingToolResponses(messages []types.ChatMessage, defaultResponse string) []types.ChatMessage
- func GetPendingToolCalls(messages []types.ChatMessage) []types.ToolCall
- func HasPendingToolCalls(messages []types.ChatMessage) bool
- type EmbeddedError
- type ToolCallValidationError
Constants ¶
const ( TokenThreshold4K = 4096 TokenThreshold8K = 8192 TokenThreshold16K = 16384 TokenThreshold32K = 32768 TokenThreshold128K = 131072 )
TokenThreshold represents common context window sizes in tokens.
const BytesPerToken = 4.7
BytesPerToken is the empirically-derived average bytes per token. Can be used by consumers for custom calculations.
Variables ¶
var CommonErrorPatterns = []string{
"token quota is not enough",
"rate limit exceeded",
"context length exceeded",
"insufficient_quota",
"model_not_found",
"invalid_api_key",
"quota exceeded",
"capacity exceeded",
"overloaded",
}
CommonErrorPatterns provides default patterns for known provider errors. Consumers can use these or define their own.
Functions ¶
func ByteThresholdForTokens ¶
ByteThresholdForTokens converts token thresholds to approximate byte sizes. Useful for quick content-length based routing decisions.
func ContainsAnyPattern ¶
ContainsAnyPattern returns true if body contains any of the patterns. Case-insensitive matching.
func ContainsCommonErrors ¶
ContainsCommonErrors returns true if body contains any common error patterns.
func EstimateTokensFromBytes ¶
EstimateTokensFromBytes estimates token count from byte length. Based on empirical observation: ~4.7 bytes per token on average. This is a rough estimate, not exact tokenization.
func EstimateTokensFromMessages ¶
func EstimateTokensFromMessages(messages []types.ChatMessage) int
EstimateTokensFromMessages estimates total tokens across all messages. Uses GetTextContent() to extract text from both simple and multimodal messages.
func EstimateTokensFromString ¶
EstimateTokensFromString estimates token count from string content.
func FixMissingToolResponses ¶
func FixMissingToolResponses(messages []types.ChatMessage, defaultResponse string) []types.ChatMessage
FixMissingToolResponses returns a new message slice with injected responses for any tool calls that don't have corresponding tool responses. Tool responses are inserted immediately after the assistant message containing the tool_calls, not at the end of the message array.
func GetPendingToolCalls ¶
func GetPendingToolCalls(messages []types.ChatMessage) []types.ToolCall
GetPendingToolCalls returns tool calls that don't have responses yet.
func HasPendingToolCalls ¶
func HasPendingToolCalls(messages []types.ChatMessage) bool
HasPendingToolCalls returns true if there are tool calls without responses.
Types ¶
type EmbeddedError ¶
type EmbeddedError struct {
Pattern string // The pattern that matched
Context string // Surrounding text for debugging (up to 100 chars)
}
EmbeddedError represents an error found in a successful response body
func CheckCommonErrors ¶
func CheckCommonErrors(body string) *EmbeddedError
CheckCommonErrors is a convenience function using CommonErrorPatterns.
func CheckEmbeddedErrors ¶
func CheckEmbeddedErrors(body string, patterns []string) *EmbeddedError
CheckEmbeddedErrors scans response body for error patterns. Returns nil if no errors found, or the first matching error. Matching is case-insensitive.
func (*EmbeddedError) Error ¶
func (e *EmbeddedError) Error() string
Error implements the error interface
type ToolCallValidationError ¶
type ToolCallValidationError struct {
ToolCallID string
ToolName string
MessageIndex int
Issue string // "missing_response", "orphan_response", etc.
}
ToolCallValidationError represents a missing or invalid tool response
func ValidateToolCallSequence ¶
func ValidateToolCallSequence(messages []types.ChatMessage) []ToolCallValidationError
ValidateToolCallSequence checks if all tool calls have matching responses. Returns nil if valid, or a slice of validation errors.
Source Files