types

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

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

type ContentPart struct {
	Type string `json:"type"` // "text", "image", "audio", "video"

	// For text content
	Text *string `json:"text,omitempty"`

	// For media content (image, audio, video)
	Media *MediaContent `json:"media,omitempty"`
}

type CostInfo struct {
	InputTokens   int     `json:"input_tokens"`              // Number of input tokens consumed
	OutputTokens  int     `json:"output_tokens"`             // Number of output tokens generated
	CachedTokens  int     `json:"cached_tokens,omitempty"`   // Number of cached tokens used (reduces cost)
	InputCostUSD  float64 `json:"input_cost_usd"`            // Cost of input tokens in USD
	OutputCostUSD float64 `json:"output_cost_usd"`           // Cost of output tokens in USD
	CachedCostUSD float64 `json:"cached_cost_usd,omitempty"` // Cost savings from cached tokens
	TotalCost     float64 `json:"total_cost_usd"`            // Total cost in USD
}

type MediaChunk struct {
	// Data contains the raw media bytes for this chunk
	Data []byte `json:"data"`

	// SequenceNum is the sequence number for ordering chunks (starts at 0)
	SequenceNum int64 `json:"sequence_num"`

	// Timestamp indicates when this chunk was created
	Timestamp time.Time `json:"timestamp"`

	// IsLast indicates if this is the final chunk in the stream
	IsLast bool `json:"is_last"`

	// Metadata contains chunk-specific metadata (MIME type, encoding, etc.)
	Metadata map[string]string `json:"metadata,omitempty"`
}

type MediaContent struct {
	// Data source - exactly one should be set
	Data     *string `json:"data,omitempty"`      // Base64-encoded media data
	FilePath *string `json:"file_path,omitempty"` // Local file path
	URL      *string `json:"url,omitempty"`       // External URL (http/https)

	// Storage backend reference (used when media is externalized)
	StorageReference *string `json:"storage_reference,omitempty"` // Backend-specific storage reference

	// Media metadata
	MIMEType   string  `json:"mime_type"`             // e.g., "image/jpeg", "audio/mp3", "video/mp4"
	Format     *string `json:"format,omitempty"`      // Optional format hint (e.g., "png", "mp3", "mp4")
	SizeKB     *int64  `json:"size_kb,omitempty"`     // Optional size in kilobytes
	Detail     *string `json:"detail,omitempty"`      // Optional detail level for images: "low", "high", "auto"
	Caption    *string `json:"caption,omitempty"`     // Optional caption/description
	Duration   *int    `json:"duration,omitempty"`    // Optional duration in seconds (for audio/video)
	BitRate    *int    `json:"bit_rate,omitempty"`    // Optional bit rate in kbps (for audio/video)
	Channels   *int    `json:"channels,omitempty"`    // Optional number of channels (for audio)
	Width      *int    `json:"width,omitempty"`       // Optional width in pixels (for image/video)
	Height     *int    `json:"height,omitempty"`      // Optional height in pixels (for image/video)
	FPS        *int    `json:"fps,omitempty"`         // Optional frames per second (for video)
	PolicyName *string `json:"policy_name,omitempty"` // Retention policy name
}

type MediaItemSummary struct {
	Type      string `json:"type"`             // Content type: "image", "audio", "video"
	Source    string `json:"source"`           // Source description (file path, URL, or "inline data")
	MIMEType  string `json:"mime_type"`        // MIME type
	SizeBytes int    `json:"size_bytes"`       // Size in bytes (0 if unknown)
	Detail    string `json:"detail,omitempty"` // Detail level for images
	Loaded    bool   `json:"loaded"`           // Whether media was successfully loaded
	Error     string `json:"error,omitempty"`  // Error message if loading failed
}

type MediaSummary struct {
	TotalParts int                `json:"total_parts"`           // Total number of content parts
	TextParts  int                `json:"text_parts"`            // Number of text parts
	ImageParts int                `json:"image_parts"`           // Number of image parts
	AudioParts int                `json:"audio_parts"`           // Number of audio parts
	VideoParts int                `json:"video_parts"`           // Number of video parts
	MediaItems []MediaItemSummary `json:"media_items,omitempty"` // Details of each media item
}

type Message struct {
	Role    string `json:"role"`    // "system", "user", "assistant", "tool"
	Content string `json:"content"` // Message content (legacy text-only, maintained for backward compatibility)

	// Multimodal content parts (text, images, audio, video)
	// If Parts is non-empty, it takes precedence over Content.
	// For backward compatibility, if Parts is empty, Content will be used.
	Parts []ContentPart `json:"parts,omitempty"`

	// Tool invocations (for assistant messages that call tools)
	ToolCalls []MessageToolCall `json:"tool_calls,omitempty"`

	// Tool result (for tool role messages)
	// When Role="tool", this contains the tool execution result
	ToolResult *MessageToolResult `json:"tool_result,omitempty"`

	// Source indicates where this message originated (runtime-only, not persisted in JSON)
	// Values: "statestore" (loaded from StateStore), "pipeline" (created during execution), "" (user input)
	Source string `json:"-"`

	// Metadata for observability and tracking
	Timestamp time.Time              `json:"timestamp,omitempty"`  // When the message was created
	LatencyMs int64                  `json:"latency_ms,omitempty"` // Time taken to generate (for assistant messages)
	CostInfo  *CostInfo              `json:"cost_info,omitempty"`  // Token usage and cost tracking
	Meta      map[string]interface{} `json:"meta,omitempty"`       // Custom metadata

	// Validation results (for assistant messages)
	Validations []ValidationResult `json:"validations,omitempty"`
}

type MessageToolCall struct {
	ID   string          `json:"id"`   // Unique identifier for this tool call
	Name string          `json:"name"` // Name of the tool to invoke
	Args json.RawMessage `json:"args"` // JSON-encoded tool arguments
}

type MessageToolResult struct {
	ID        string `json:"id"`              // References the MessageToolCall.ID that triggered this result
	Name      string `json:"name"`            // Tool name that was executed
	Content   string `json:"content"`         // Result content or error message
	Error     string `json:"error,omitempty"` // Error message if tool execution failed
	LatencyMs int64  `json:"latency_ms"`      // Tool execution latency in milliseconds
}

type StreamingMediaConfig struct {
	// Type specifies the media type being streamed
	// Values: ContentTypeAudio, ContentTypeVideo
	Type string `json:"type"`

	// ChunkSize is the target size in bytes for each chunk
	// Typical values: 4096-8192 for audio, 32768-65536 for video
	ChunkSize int `json:"chunk_size"`

	// SampleRate is the audio sample rate in Hz
	// Common values: 8000 (phone quality), 16000 (wideband), 44100 (CD quality), 48000 (pro audio)
	SampleRate int `json:"sample_rate,omitempty"`

	// Encoding specifies the audio encoding format
	// Values: "pcm" (raw), "opus", "mp3", "aac"
	Encoding string `json:"encoding,omitempty"`

	// Channels is the number of audio channels
	// Values: 1 (mono), 2 (stereo)
	Channels int `json:"channels,omitempty"`

	// BitDepth is the audio bit depth in bits
	// Common values: 16, 24, 32
	BitDepth int `json:"bit_depth,omitempty"`

	// Width is the video width in pixels
	Width int `json:"width,omitempty"`

	// Height is the video height in pixels
	Height int `json:"height,omitempty"`

	// FrameRate is the video frame rate (FPS)
	// Common values: 24, 30, 60
	FrameRate int `json:"frame_rate,omitempty"`

	// BufferSize is the maximum number of chunks to buffer
	// Larger values increase latency but provide more stability
	// Typical values: 5-20
	BufferSize int `json:"buffer_size,omitempty"`

	// FlushInterval is how often to flush buffered data (if applicable)
	FlushInterval time.Duration `json:"flush_interval,omitempty"`

	// Metadata contains additional provider-specific configuration
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type ToolDef struct {
	Name         string          `json:"name"`                    // Unique tool name
	Description  string          `json:"description"`             // Human-readable description of what the tool does
	InputSchema  json.RawMessage `json:"input_schema"`            // JSON Schema for input validation
	OutputSchema json.RawMessage `json:"output_schema,omitempty"` // Optional JSON Schema for output validation
}

type ToolStats struct {
	TotalCalls int            `json:"total_calls"` // Total number of tool calls
	ByTool     map[string]int `json:"by_tool"`     // Count of calls per tool name
}

type ValidationError struct {
	Type   string `json:"type"`   // Error type: "args_invalid" | "result_invalid" | "policy_violation"
	Tool   string `json:"tool"`   // Name of the tool that failed validation
	Detail string `json:"detail"` // Human-readable error details
}

type ValidationResult struct {
	ValidatorType string                 `json:"validator_type"`      // Type of validator
	Passed        bool                   `json:"passed"`              // Whether the validation passed
	Details       map[string]interface{} `json:"details,omitempty"`   // Validator-specific details
	Timestamp     time.Time              `json:"timestamp,omitempty"` // When validation was performed
}