explainer

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

type Comparison struct {
	// Play is what we were asked to contrast the best play with.
	Play string `json:"play"`
	// FromHistory is true when it is the move the player actually made, as
	// opposed to one they named.
	FromHistory bool `json:"from_history"`
	// WasBest is true when the play we were asked about *is* the top play. It
	// then has nothing to be contrasted with, so Rival below is the runner-up
	// instead and there is still something to learn.
	WasBest bool `json:"was_best"`

	// Rival is the candidate actually contrasted against.
	Rival          *montecarlo.CandidateStats `json:"rival"`
	RivalPlayStats *stats.PlayStats           `json:"-"`
	RivalFollowups []*FollowupFact            `json:"rival_followups"`
	// RivalChances is RivalFollowups gathered into opportunities.
	RivalChances []*FollowupCluster `json:"rival_chances"`
	// TypicalNextScore is what our next turn averages after the rival, and
	// ChanceBaseline is what it is worth when none of the rival's chances come
	// up. See judgeChances.
	TypicalNextScore float64 `json:"typical_next_score"`
	ChanceBaseline   float64 `json:"chance_baseline"`

	Deltas Deltas `json:"deltas"`

	// OnlyBest and OnlyRival are the worthwhile follow-up plays each side has
	// that the other doesn't - the concrete "what you gave up" list.
	OnlyBest  []*FollowupFact `json:"only_best"`
	OnlyRival []*FollowupFact `json:"only_rival"`
}

type ComparisonRequest struct {
	Move *move.Move
	// FromHistory distinguishes "the move you actually made", which we found
	// ourselves, from one the user named.
	FromHistory bool
}

type Concept struct {
	// ID is the card's name, taken from its frontmatter.
	ID string
	// Priority orders the cards in the prompt, lowest first.
	Priority int
	// When lists flag names. The card ships if any of them is set, so
	// "always" is just a flag that is always true.
	When []string
	Body string
}

type Config struct {
	Provider  string // "gemini", "openai", "openrouter", or "deepseek"
	APIKey    string
	Model     string
	BaseURL   string // optional: override base URL (e.g. for LM Studio at http://127.0.0.1:1234/v1)
	UseQuirky bool
}

type Deltas struct {
	WinPct     float64 `json:"win_pct"`
	Equity     float64 `json:"equity"`
	Score      int     `json:"score"`
	LeaveValue float64 `json:"leave_value"`
	// The opponent's reply, one ply out: a negative OppMeanScore means the
	// best play holds them to less.
	OppMeanScore float64 `json:"opp_mean_score"`
	OppStdev     float64 `json:"opp_stdev"`
	OppBingoPct  float64 `json:"opp_bingo_pct"`
	// Our own next turn, two plies out.
	OurMeanScore float64 `json:"our_mean_score"`
	OurBingoPct  float64 `json:"our_bingo_pct"`
	// BestUpside and RivalUpside are the expected points each play's big
	// follow-up chances add to its next turn, over a next turn without them.
	// The gap between them is often the whole reason one play wins, and it is
	// invisible in every other figure here.
	BestUpside  float64 `json:"best_upside"`
	RivalUpside float64 `json:"rival_upside"`
	// ChancesShare and OrdinaryShare split OurMeanScore into the part that is
	// the two plays' big chances and the part that is their ordinary turns.
	// They add to OurMeanScore, which is the whole point of them: without the
	// split, the mean difference and the upside difference read as two
	// separate arguments for the same play when they are one argument counted
	// twice. SplitKnown is false when a play has no second ply to split.
	ChancesShare  float64 `json:"chances_share"`
	OrdinaryShare float64 `json:"ordinary_share"`
	SplitKnown    bool    `json:"split_known"`
	// Established is true when the two win% confidence intervals don't
	// overlap. When it is false the simulation has not actually shown one
	// play to be better, and saying so would be overclaiming.
	Established bool `json:"established"`
}

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

type Exchange struct {
	Prompt   *Prompt
	Response string
	// BestPlay and Comparison say what the explanation was about, so a dump
	// after the fact is identifiable.
	BestPlay   string
	Comparison string
}

type ExplainInput struct {
	Game     *bot.BotTurnPlayer
	Simmer   *montecarlo.Simmer
	SimStats *stats.SimStats
	// Compare asks for a head-to-head against a particular play, usually the
	// one the player actually made. The simulation must already have
	// evaluated it - see Simmer.AvoidPruningMoves.
	Compare *ComparisonRequest
	// Inference is the read on the opponent's rack that Simmer was run with,
	// plus the same plays simmed without it. Nil when no read was taken.
	Inference *InferenceInput
	// Model overrides the configured model for this one explanation, so that
	// several can be tried on the same position without editing any config.
	// Empty means whatever the provider is configured to use.
	Model string
}

type ExplainResult struct {
	Explanation  string
	InputTokens  int
	OutputTokens int
	// Provider and Model say who actually answered. Worth reporting because
	// both can now change between one explanation and the next.
	Provider string
	Model    string
	// Concepts names the concept cards this position pulled into the prompt.
	Concepts []string
	// Prompt is exactly what was sent. Also kept on the service, so it can be
	// read back after the fact.
	Prompt *Prompt
}

type Flags map[string]bool

type FollowupCluster struct {
	// Anchor is where the opportunity is: the tiles it runs through and the
	// lane they are in, like "(QUAD) in row 2", or a bare square when there is
	// nothing on the board to name it by.
	Anchor string `json:"anchor"`
	// Through is the letters already on the board that every play here runs
	// through, empty when the opportunity is an open square rather than a hook.
	Through string `json:"through"`
	// Plays are the ways of taking it, most likely first.
	Plays []*FollowupFact `json:"plays"`
	// Pct, MinScore and MaxScore cover the cluster as a whole.
	Pct      float64 `json:"pct"`
	AvgScore float64 `json:"avg_score"`
	MinScore int     `json:"min_score"`
	MaxScore int     `json:"max_score"`

	IsSetup     bool    `json:"is_setup"`
	IsBigChance bool    `json:"is_big_chance"`
	Upside      float64 `json:"upside"`
	// Baseline is what our next turn is worth when this chance does not come
	// up, which is what Upside is measured over. It is not the play's mean
	// next turn: a chance that comes up often is a large part of that mean,
	// and measuring it against a number it dominates hides it. See
	// chanceBaseline.
	Baseline float64 `json:"baseline"`
}

type FollowupFact struct {
	*stats.FollowupFamily
	// WayRequirements runs parallel to Ways. Each entry is "none", "requires
	// opponent play", or "requires us to play <best play> first". The last is
	// what actually makes a setup a setup: the follow-up doesn't exist unless
	// we make this play.
	WayRequirements []string `json:"way_requirements"`
	// IsSetup means our best play creates this opportunity.
	IsSetup bool `json:"is_setup"`
	// IsBigChance means the play is far bigger than an ordinary next turn and
	// comes up often enough for that to be worth playing for, whether or not
	// our play is what created it.
	IsBigChance bool `json:"is_big_chance"`
	// Upside is expected points above a next turn without this chance in it:
	// how often the play comes up times how much bigger it is than the turns
	// where it doesn't. See judgeChances for why the comparison is against
	// those turns rather than against the mean of all of them.
	Upside float64 `json:"upside"`
	// Baseline is what those turns are worth.
	Baseline float64 `json:"baseline"`
}

type FuturePlayFamily struct {
	Play              string   `json:"play"`
	CombinedPercent   float64  `json:"combined_probability_percent"`
	ScoreRange        string   `json:"score_range"`
	NeededDrawOptions []string `json:"needed_draw_options"` // any one of these unlocks the play
	IsSetup           bool     `json:"is_setup"`
}

type FuturePlayLookup struct {
	Asked  string // the specific way the model named, if it named one
	Family *FuturePlayFamily
	Ways   []*FuturePlayMetadata
}

type FuturePlayMetadata struct {
	Play               string   `json:"play"`
	Score              int      `json:"score"`
	IsBingo            bool     `json:"is_bingo"`
	NeededDraw         []string `json:"needed_draw"`         // tiles needed from bag
	RequiresOtherPlay  string   `json:"requires_opp_play"`   // opponent play needed first
	ProbabilityPercent float64  `json:"probability_percent"` // likelihood of this play
	IsSetup            bool     `json:"is_setup"`
}

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

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

type InferenceFacts struct {
	Summary *rangefinder.InferenceSummary `json:"summary"`
	// Outliers are the tiles the read actually says something about, ordered
	// by how far it moved them.
	Outliers []rangefinder.TileDeviation `json:"outliers"`
	// ShapeRead is set when the read is about the makeup of the rack rather
	// than about any one tile. It is a separate finding because it can be the
	// only one: a read can leave every letter within a tenth of a tile of
	// chance and still say, unmistakably, that they kept consonants.
	ShapeRead *rangefinder.RackShape `json:"shape_read,omitempty"`

	// Baseline is the same plays simmed without the read, so we can say what
	// the read changed rather than only what it concluded.
	Baseline []montecarlo.CandidateStats `json:"-"`
	// BaselineBest is the play we would have recommended knowing nothing.
	BaselineBest *montecarlo.CandidateStats `json:"baseline_best"`
	// BaselineOfBest is the recommended play's own showing in that sim, which
	// is what WinPctShift is measured against. Nil if it wasn't simmed there.
	BaselineOfBest *montecarlo.CandidateStats `json:"baseline_of_best"`

	// ChangedTopPlay is the strongest thing a read can do: recommend a
	// different play than we would have made without it.
	ChangedTopPlay bool `json:"changed_top_play"`
	// WinPctShift is the recommended play's win% with the read minus without.
	WinPctShift float64 `json:"win_pct_shift"`
	// Established is true when that shift is outside both sims' confidence
	// intervals. The two runs stop independently, so they aren't equally
	// sampled - non-overlapping intervals still means a real difference, but
	// the size of it shouldn't be read too precisely.
	Established bool `json:"established"`
	// Decisive is Established plus a practical significance test. A shift can
	// be statistically real and mean nothing: in a position already won, win
	// probabilities saturate, their intervals shrink to almost nothing, and a
	// swing from 97.9% to 97.0% clears the statistical bar while changing
	// nothing about how to play. Decisive is what gates the subject.
	Decisive bool `json:"decisive"`

	// Informative is true when the posterior deviates from chance enough to
	// be worth a sentence.
	Informative bool `json:"informative"`
	// Matters gates the whole subject. An uninformative read, or one that
	// moves nothing, is not mentioned at all.
	Matters bool `json:"matters"`
}

type InferenceInput struct {
	Summary *rangefinder.InferenceSummary
	// Baseline is CandidateStats from a sim run with inference off, best
	// win% first.
	Baseline []montecarlo.CandidateStats
}

type LaneComparison struct {
	Play  string
	Best  bool
	Stats *stats.LaneStats
}

type Phase string

type PlayMetadata struct {
	Play           string `json:"play"`
	Score          int    `json:"score"`
	TilesUsed      int    `json:"tiles_used"`
	IsBingo        bool   `json:"is_bingo"`
	VowelsInLeave  int    `json:"vowels_in_leave"`
	ConsonantsLeft int    `json:"consonants_in_leave"`
	LeaveBalance   string `json:"leave_balance"` // "balanced", "vowel-heavy", "consonant-heavy"
}

type PlayNotFoundError struct {
	Play      string
	Available []string
}

type PositionFacts struct {
	Rack        string
	Lexicon     string
	BagCount    int
	UnseenCount int
	OppRackSize int
	Spread      int
	Phase       Phase

	UnseenVowels     int
	UnseenConsonants int
	UnseenBlanks     int
	UnseenPowerTiles []string

	Iterations int
	Candidates []montecarlo.CandidateStats
	Best       *montecarlo.CandidateStats

	PlayStats *stats.PlayStats
	Followups []*FollowupFact
	// Chances is Followups gathered into opportunities: the plays that take the
	// same hook are one chance, and are judged and reported as one. Ordered by
	// upside, biggest first.
	Chances []*FollowupCluster
	Lanes   []*LaneComparison
	// TypicalNextScore is what our next turn averages after the best play,
	// chances and all.
	TypicalNextScore float64
	// ChanceBaseline is what that turn is worth when none of the chances come
	// up, which is what every chance is measured against - see judgeChances.
	// The gap between the two is what the chances are worth.
	ChanceBaseline float64

	// BestByEquity is the candidate with the highest equity, which is not
	// always the one with the highest win%.
	BestByEquity *montecarlo.CandidateStats

	// Comparison is set when we were asked why the best play beats some other
	// play - usually the one the player actually made.
	Comparison *Comparison

	// Inference is set when the position was analyzed with a read on the
	// opponent's rack. It is nil unless `explain -infer` asked for one.
	Inference *InferenceFacts

	Flags Flags
}

type Prompt struct {
	System string
	User   string
	// Concepts names the cards this position pulled in. Useful for logging
	// and for tests that assert a position asks for the right knowledge.
	Concepts []string
	// Tools are the function definitions sent alongside the messages. They
	// appear in neither message's text - the API carries them in a field of
	// their own - so a dump showing only the messages would be missing
	// instructions the model really does receive, and some of them are
	// substantive: get_our_future_play_metadata's description is what tells
	// the model it may only look up plays from the follow-up table.
	Tools []interfaces.Tool
}

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