narrowing

type Attempt struct {
	Provider  string `json:"provider"`
	Outcome   string `json:"outcome"`
	Detail    string `json:"detail,omitempty"`
	LatencyMs int64  `json:"latencyMs"`
}

type Config struct {
	// Relations are the healthy tables and views of the active source, in the
	// order the full schema context lists them.
	Relations []api.CatalogRelation
	// Rules are the project's deterministic knowledge, tried before the engine.
	Rules []Rule
	// Links, when set, returns the schema's foreign keys, read each turn. They let
	// the decision keep the tables on the path between selected tables.
	Links func() []Link
	// Engine scores candidate tables. Nil means no engine: only rules narrow.
	Engine decision.ScoredProvider
	// Policy turns the engine's probabilities into a verdict. It must be valid
	// (decision.NarrowingPolicy is the intended one).
	Policy decision.SelectionPolicy
	// Format renders relations as the model's schema context (the chat's
	// FormatSchemaContext), so the byte counts compare like with like.
	Format func(*api.CatalogSchema) string
	// Product is sent to the engine; default "datatug".
	Product string
	// Timeout bounds the engine call; default 1.5s.
	Timeout time.Duration
	// CoolDown is how long the engine is left alone after a failure or a stop;
	// default 5 minutes.
	CoolDown time.Duration
	// Now is the clock; default time.Now.
	Now func() time.Time
}

type History struct {
	// Questions are the user's earlier questions in this session, oldest first.
	// Only the last few are used.
	Questions []string
	// Kept are the tables the previous narrowed turn put in the model's context.
	// Empty when the previous turn did not narrow.
	Kept []string
}

type Link struct {
	FromSchema, From string
	ToSchema, To     string
}

type Mechanism string

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

type Outcome struct {
	Context string
	Record  Record
}

type Record struct {
	DecidedAt time.Time `json:"decidedAt"`
	// Mechanism is the rung that decided; Engine and Model name the answering
	// engine and its model id when one was asked.
	Mechanism Mechanism `json:"mechanism,omitempty"`
	Engine    string    `json:"engine,omitempty"`
	Model     string    `json:"model,omitempty"`
	// Provenance is the decision.Provenance class of the answer that stood:
	// deterministic, calibrated or self_reported.
	Provenance string `json:"provenance,omitempty"`
	Policy     string `json:"policy,omitempty"`
	// DeciderEnabled is true when a decision engine was configured when the
	// question was asked. The question of a turn is only reused as history for a
	// later question if it was (a question typed before the user opted in must
	// never be sent after).
	DeciderEnabled bool `json:"deciderEnabled,omitempty"`
	// Verdict is the selection policy's judgement, for example "several" or
	// "uncertain: only_potential".
	Verdict string `json:"verdict,omitempty"`
	// Narrowed is true only when the model was given fewer tables than the
	// full schema. FallbackReason says why not, when the answer is false.
	Narrowed       bool   `json:"narrowed"`
	FallbackReason string `json:"fallbackReason,omitempty"`
	// StoppedBy is set when the engine refused for a reason that must not be
	// answered by asking a bigger, paid model: an exhausted allowance (quota), a
	// spent budget (budget) or a misconfigured endpoint (misconfigured).
	StoppedBy string `json:"stoppedBy,omitempty"`

	CandidatesBefore int `json:"candidatesBefore"`
	CandidatesAfter  int `json:"candidatesAfter"`
	// Selected are the tables the engine or rule selected; Strong is the subset
	// it was most sure of; Potential are tables it judged possibly relevant, kept
	// in the model's context so that ambiguity is preserved, not hidden.
	// Proposed holds the picks of an uncalibrated answer, which are never a
	// selection and are recorded only.
	Selected  []string `json:"selected,omitempty"`
	Strong    []string `json:"strong,omitempty"`
	Potential []string `json:"potential,omitempty"`
	Proposed  []string `json:"proposed,omitempty"`
	// Carried are tables kept because the previous turn kept them (a follow-up is
	// about the same data); Closure are tables kept because they lie on the
	// foreign-key path between selected tables.
	Carried []string `json:"carried,omitempty"`
	Closure []string `json:"closure,omitempty"`
	// Kept are the tables whose definitions reached the model, in schema order.
	Kept   []string `json:"kept,omitempty"`
	Scores []Score  `json:"scores,omitempty"`

	ContextBytesBefore int `json:"contextBytesBefore"`
	ContextBytesAfter  int `json:"contextBytesAfter"`

	Attempts     []Attempt `json:"attempts,omitempty"`
	LatencyMs    int64     `json:"latencyMs"`
	InputTokens  int       `json:"inputTokens,omitempty"`
	OutputTokens int       `json:"outputTokens,omitempty"`
}

type Rule struct {
	Phrase string   `yaml:"phrase"`
	Tables []string `yaml:"tables"`
}

type Score struct {
	ID          string  `json:"id"`
	Probability float64 `json:"probability"`
}

type Settings struct {
	// Decision is the project's choice of decision provider ("" when unset).
	Decision string
	Rules    []Rule
	Warnings []string
}