core

type AgentConfig struct {
	// Instruction, when non-empty, is a per-agent system instruction that is
	// prepended to every prompt sent to this agent.
	Instruction string
	// Weight is the influence weight used by weighted aggregation functions.
	// Zero means the default weight of 1.0.
	Weight float64
	// SkipPhases lists the phases this agent is excluded from.
	SkipPhases map[Phase]bool
}

type AggregationFn func(after map[string]*Answer, labels []string, weights map[string]float64) string

type Answer struct {
	Answer      string             `json:"answer"`
	Confidences map[string]float64 `json:"confidences,omitempty"`
	Reasoning   string             `json:"reasoning"`
	Challenge   *challengeRequest  `json:"challenge,omitempty"`
}

type AnswerSchema interface {
	// Instruction is the output-contract text appended to prompts.
	Instruction() string
	// Parse extracts an Answer from raw model output. It must tolerate leading
	// prose, markdown fences, and trailing chatter.
	Parse(raw string) (*Answer, error)
}

type AttributionFn func(res *PromptResult, labels []string, verdict *DriftVerdict)

type BudgetError struct {
	MaxCalls  int
	Calls     int64
	MaxTokens int
	Tokens    int64
}

type CallOption func(*CallOptions)

type CallOptions struct {
	Verbose           bool
	MaxRounds         int
	OptionLabels      []string
	Thresholds        Thresholds
	GrillStrategy     GrillStrategy
	GrillCount        int
	Protocol          Protocol
	Metadata          map[string]any
	Confidence        *float64
	Claim             string
	Hooks             *Hooks
	Budget            CostBudget
	ConsistencyScorer ConsistencyScorer
}

type Classifier func(confScore, consistencyScore float64) (QuadrantState, string)

type Config struct {
	// SupervisorModel is the model that powers the moderator (and, when
	// ConsistencyModel is unset, the default LLM consistency scorer). Required.
	SupervisorModel model.BaseModel[*schema.Message]
	// ConsistencyModel powers the default LLM consistency scorer. When nil it
	// falls back to SupervisorModel. Use a cheap model here and reserve
	// SupervisorModel for the moderator.
	ConsistencyModel model.BaseModel[*schema.Message]
	// Agents is the panel of debaters. At least one is required. Agent names
	// (from Agent.Name) must be unique.
	Agents []adk.Agent
	// Logger receives all verbose/progress output. Default slog.Default().
	Logger *slog.Logger

	// PacingDelay throttles each model invocation by sleeping before the call.
	// Zero disables pacing. Default 0.
	PacingDelay time.Duration
	// RequestTimeout bounds a single model invocation. Zero disables. Default 0.
	RequestTimeout time.Duration
	// MaxRetries is how many corrective re-prompts to attempt when an agent
	// returns unparseable output. Default 2.
	MaxRetries int
	// Concurrency is the number of agents queried in parallel during the
	// baseline and evaluation phases. Default 1 (sequential).
	Concurrency int
	// MaxRounds is the number of (cross-examine → evaluate) rounds run by
	// Debate. Default 1.
	MaxRounds int

	// Thresholds drives drift detection and quadrant classification. Zero
	// Thresholds resolves to the defaults.
	Thresholds Thresholds
	// OptionLabels overrides the auto-generated A, B, C... labels used for
	// multiple-choice questions. Leave nil to auto-generate.
	OptionLabels []string
	// AnswerSchema defines the JSON output contract agents must follow. Default
	// is the MCQ schema. Open-ended questions (no options) always use the
	// open-ended schema regardless of this field.
	AnswerSchema AnswerSchema
	// Protocol selects the cross-examination orchestration strategy.
	Protocol Protocol
	// GrillStrategy selects which agents get grilling diagnostics.
	GrillStrategy GrillStrategy
	// GrillCount is the number of agents grilled by GrillTopN. Default 1.
	GrillCount int
	// AggregationFn derives the winning option from the final positions.
	AggregationFn AggregationFn
	// DriftMetric computes the distribution shift between an agent's before and
	// after positions. Only used for multiple-choice questions.
	DriftMetric DriftMetric
	// AttributionFn determines who drove the primary shift.
	AttributionFn AttributionFn
	// Classifier maps confidence/consistency onto the quadrant grid.
	Classifier Classifier
	// ConsistencyScorer evaluates whether two arguments from the same agent
	// contradict each other. Defaults to an LLM scorer over ConsistencyModel.
	ConsistencyScorer ConsistencyScorer
	// PromptTemplates overrides any or all of the built-in prompts.
	PromptTemplates PromptTemplates

	// AgentOverrides holds per-agent customization keyed by agent name.
	AgentOverrides map[string]AgentConfig
	// ExtraTools are additional tools given to the moderator alongside the
	// built-in cross_examine_agent tool.
	ExtraTools []tool.BaseTool
	// Hooks are observability callbacks fired at pipeline milestones.
	Hooks Hooks
	// Recorder receives a JSON-serializable Event stream for persistence.
	Recorder Recorder
	// Redact, when non-nil, is applied to every outgoing prompt before it is
	// sent to any model.
	Redact func(string) string
	// Budget caps total work per debate.
	Budget CostBudget
	// Verbose enables default progress logging when a call does not override it.
	Verbose bool
}

type ConsistencyScorer interface {
	Score(ctx context.Context, question, r1, r2 string) (float64, error)
}

type CostBudget struct {
	// MaxCalls limits the total number of model invocations.
	MaxCalls int
	// MaxTokens is an approximate token budget (characters / 4) consumed by
	// all outgoing prompt content.
	MaxTokens int
	// Deadline bounds the total wall-clock time of a debate.
	Deadline time.Duration
}

type DiagnosticResult struct {
	AgentName        string        `json:"agent_name"`
	ConfidenceScore  float64       `json:"confidence_score"`  // X-axis (0.0 -> 1.0)
	ConsistencyScore float64       `json:"consistency_score"` // Y-axis (0.0 -> 1.0)
	Quadrant         QuadrantState `json:"quadrant"`
	InitialReasonR1  string        `json:"r1_initial_reasoning"`
	CounterReasonR2  string        `json:"r2_counter_reasoning"`
	Recommendation   string        `json:"recommendation"`
}

type DriftMetric func(labels []string, before, after *Answer) float64

type DriftVerdict struct {
	// HasDrift reports whether any agent flipped or significantly eroded.
	HasDrift bool `json:"has_drift"`
	// DriftedAgents lists the names of agents that drifted.
	DriftedAgents []string `json:"drifted_agents"`
	// PrimaryDriver is the agent (or the supervisor) responsible for the shift.
	PrimaryDriver string `json:"primary_driver"`
	// DriverImpact is a human-readable description of who swayed whom.
	DriverImpact string `json:"driver_impact"`
	// AgentShifts maps each agent name to its measured shift.
	AgentShifts map[string]float64 `json:"agent_shifts"`
}

type Event struct {
	Time  time.Time       `json:"time"`
	Type  EventType       `json:"type"`
	Agent string          `json:"agent,omitempty"`
	Data  json.RawMessage `json:"data,omitempty"`
}

type EventType string

type FullDebateSummary struct {
	Question       string                       `json:"question"`
	Options        []string                     `json:"options"`
	OptionLabels   []string                     `json:"option_labels"`
	PromptResult   *PromptResult                `json:"prompt_result"`
	DriftVerdict   DriftVerdict                 `json:"drift_verdict"`
	Diagnostics    map[string]*DiagnosticResult `json:"diagnostics,omitempty"` // Targeted grilling results
	Winner         string                       `json:"winner"`                // Aggregated winning option ("" if none)
	OverallOutcome string                       `json:"overall_outcome"`
	Metadata       map[string]any               `json:"metadata,omitempty"`
}

type GrillStrategy int

type Hooks struct {
	OnPhaseStart func(ctx context.Context, phase Phase)
	OnPhaseEnd   func(ctx context.Context, phase Phase)
	OnBaseline   func(ctx context.Context, agent string, ans *Answer)
	OnCrossExam  func(ctx context.Context, target, prompt string)
	OnEval       func(ctx context.Context, agent string, ans *Answer)
	OnDrift      func(ctx context.Context, verdict *DriftVerdict)
	OnDiagnostic func(ctx context.Context, diag *DiagnosticResult)
}

type InstrumentationStats struct {
	TotalCalls    int64
	Tokens        int64
	AgentCalls    map[string]int64
	PhaseDuration map[string][]time.Duration
}

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

type MCQSchema struct{}

type OpenEndedSchema struct{}

type Option func(*Config)

type Phase int

type PromptResult struct {
	Before map[string]*Answer
	After  map[string]*Answer
}

type PromptTemplates struct {
	// SupervisorSystem is the moderator system prompt. %s is replaced with the
	// comma-joined panelist names.
	SupervisorSystem string
	// CrossExamineLead is formatted with (challenge prompt, schema
	// instruction) when the moderator or a protocol challenges an agent.
	CrossExamineLead string
	// FinalEvalPrompt precedes the schema instruction when re-collecting final
	// positions.
	FinalEvalPrompt string
	// InitialPrompt builds the baseline question prompt.
	InitialPrompt func(question string, options []string, labels []string, instr string) string
	// DebateTrigger builds the moderator's cross-examination briefing.
	DebateTrigger func(question string, names []string, before map[string]*Answer) string
	// GrillProbe builds the adversarial inversion probe.
	GrillProbe func(question, claim string) string
	// NLIProbe builds the consistency-evaluation prompt.
	NLIProbe func(question, r1, r2 string) string
	// ChallengePrompt builds a direct peer challenge used by the non-supervised
	// protocols.
	ChallengePrompt func(from, claim, reasoning string) string
	// ConfidenceProbe asks an agent to self-report confidence in a claim.
	ConfidenceProbe func(claim string) string
}

type Protocol int

type QuadrantState string

type Recorder interface {
	Record(ctx context.Context, ev Event) error
}

type StreamEvent struct {
	Type       EventType         `json:"type"`
	Phase      Phase             `json:"phase,omitempty"`
	Agent      string            `json:"agent,omitempty"`
	Prompt     string            `json:"prompt,omitempty"`
	Answer     *Answer           `json:"answer,omitempty"`
	Verdict    *DriftVerdict     `json:"verdict,omitempty"`
	Diagnostic *DiagnosticResult `json:"diagnostic,omitempty"`
	Metadata   map[string]any    `json:"metadata,omitempty"`
	Error      error             `json:"-"`
}

type Thresholds struct {
	// DriftSignificance is the minimum shift (TVD or lexical distance) or
	// confidence erosion required to flag an agent as drifted. Default 0.15.
	DriftSignificance float64
	// Confidence is the x-axis (confidence) threshold for quadrant
	// classification. Default 0.55.
	Confidence float64
	// Consistency is the y-axis (consistency) threshold for quadrant
	// classification. Default 0.60.
	Consistency float64
}