package llm

// StreamEvent is one increment of a streaming response.
//
// Exactly one field group is meaningful per event: a text delta, a completed
// tool call, or the final response. Tool-call arguments are buffered by the
// provider until complete — consumers never see partial JSON.
type StreamEvent struct {
	// TextDelta is a fragment of assistant text.
	TextDelta string

	// ToolCall, when non-nil, is a fully-assembled tool call.
	ToolCall *ToolCall

	// Response, when non-nil, is the final accumulated response (content,
	// tool calls, finish reason, usage). It is always the last event.
	Response *Response
}

// Stream delivers a response incrementally.
//
// Next returns io.EOF after the final event (the one carrying Response).
// Close releases the underlying connection and is safe to call at any time,
// including after io.EOF or concurrently with Next returning.
type Stream interface {
	Next() (StreamEvent, error)
	Close() error
}