session

type BaseSession interface {
	// Identity
	ID() string

	// Variable management for template substitution
	Variables() map[string]string
	SetVar(name, value string)
	GetVar(name string) (string, bool)

	// State management - encapsulates StateStore access
	Messages(ctx context.Context) ([]types.Message, error)
	Clear(ctx context.Context) error
}

type DuplexSession interface {
	BaseSession

	// SendChunk sends a chunk to the session (populate MediaDelta for media, Content for text).
	// This method is thread-safe and can be called from multiple goroutines.
	SendChunk(ctx context.Context, chunk *providers.StreamChunk) error

	// SendText is a convenience method for sending text directly.
	SendText(ctx context.Context, text string) error

	// SendFrame sends an image frame to the session for realtime video scenarios.
	// This is a convenience method that wraps SendChunk with proper image formatting.
	SendFrame(ctx context.Context, frame *ImageFrame) error

	// SendVideoChunk sends a video chunk to the session for encoded video streaming.
	// This is a convenience method that wraps SendChunk with proper video formatting.
	SendVideoChunk(ctx context.Context, chunk *VideoChunk) error

	// Response returns a receive-only channel for streaming responses.
	// The channel emits StreamChunks containing LLM responses (text, media, tool calls, etc).
	Response() <-chan providers.StreamChunk

	// Close ends the streaming session and releases resources.
	Close() error

	// Done returns a channel that's closed when the session ends.
	Done() <-chan struct{}

	// Error returns any error that occurred during the session.
	Error() error

	// ForkSession creates a new session that is a fork of this one.
	// The new session will have an independent copy of the conversation state.
	ForkSession(
		ctx context.Context,
		forkID string,
		pipelineBuilder PipelineBuilder,
	) (DuplexSession, error)
}

type DuplexSessionConfig struct {
	ConversationID  string
	UserID          string
	StateStore      statestore.Store                // StateStore for conversation history
	PipelineBuilder PipelineBuilder                 // Function to build pipeline (required, typically a closure from SDK)
	Provider        providers.Provider              // Provider for LLM calls (required)
	Config          *providers.StreamingInputConfig // For ASM mode: base streaming config. For VAD mode: nil
	Metadata        map[string]interface{}
	Variables       map[string]string // Initial variables for template substitution
}

type ImageFrame struct {
	// Data is the raw image data (JPEG, PNG, etc.)
	Data []byte

	// MIMEType is the MIME type of the image (e.g., "image/jpeg")
	MIMEType string

	// Width is the image width in pixels (optional, for metadata)
	Width int

	// Height is the image height in pixels (optional, for metadata)
	Height int

	// FrameNum is the sequence number for ordering frames
	FrameNum int64

	// Timestamp is when the frame was captured
	Timestamp time.Time
}

type PipelineBuilder func(
	ctx context.Context,
	provider providers.Provider,
	streamProvider providers.StreamInputSupport,
	streamConfig *providers.StreamingInputConfig,
	conversationID string,
	store statestore.Store,
) (*stage.StreamPipeline, error)

type UnarySession interface {
	BaseSession

	// Execution methods
	Execute(ctx context.Context, role, content string) (*pipeline.ExecutionResult, error)
	ExecuteWithMessage(ctx context.Context, message types.Message) (*pipeline.ExecutionResult, error)
	ExecuteStream(ctx context.Context, role, content string) (<-chan providers.StreamChunk, error)
	ExecuteStreamWithMessage(ctx context.Context, message types.Message) (<-chan providers.StreamChunk, error)

	// ForkSession creates a new session that is a fork of this one.
	// The new session will have an independent copy of the conversation state.
	ForkSession(ctx context.Context, forkID string, pipeline *stage.StreamPipeline) (UnarySession, error)
}

type UnarySessionConfig struct {
	ConversationID string
	UserID         string
	StateStore     statestore.Store // Must match Pipeline's StateStore stages
	Pipeline       *stage.StreamPipeline
	Metadata       map[string]interface{}
	Variables      map[string]string // Initial variables for template substitution
}

type VideoChunk struct {
	// Data is the encoded video data (H.264, VP8, etc.)
	Data []byte

	// MIMEType is the MIME type of the video (e.g., "video/h264")
	MIMEType string

	// Width is the video width in pixels (optional, for metadata)
	Width int

	// Height is the video height in pixels (optional, for metadata)
	Height int

	// ChunkIndex is the sequence number for ordering chunks
	ChunkIndex int

	// IsKeyFrame indicates if this chunk contains a keyframe
	IsKeyFrame bool

	// Timestamp is when the chunk was created/captured
	Timestamp time.Time

	// Duration is the duration of this video chunk
	Duration time.Duration
}