decide

type Answer struct {
	Key           string
	Type          string
	Probability   *float64
	Choice        string
	Score         *float64
	Probabilities map[string]float64
	Confidence    *float64
}

type Backend interface {
	// Name returns the registered name (must match the Register key).
	Name() string

	// DefaultModel is the model used when a request omits WITH model.
	DefaultModel() string

	// RequiredSecrets are the standardized secret names this backend needs.
	RequiredSecrets() []string

	// Decide asks every question in req against req.State in one call. It
	// translates the provider's answers into Response and returns them as
	// reported; Normalize (called by the handler) enforces the contract —
	// every question answered, choices from the offered set, probabilities
	// in range. The bag carries cleartext for every name in
	// RequiredSecrets(); implementations keep it in local variables only.
	Decide(ctx context.Context, req Request, bag *secrets.SecretBag) (Response, error)
}

type CodedError interface {
	error
	Code() string
}

type Config struct {
	// HTTPClient is the chassis-owned http.Client (egress-guarded). Every
	// outbound call from a backend MUST use it.
	HTTPClient *http.Client

	// ZeroDataRetention asks the provider not to retain request data, where
	// the backend can express that (chassis config
	// decide-zero-data-retention).
	ZeroDataRetention bool
}

type Constructor func(Config) (Backend, error)

type InvalidAnswerError struct {
	Question string
	Reason   string
}

type InvalidWithError struct {
	Reason string
}

type MissingSecretError struct {
	Backend string
	Secret  string
}

type NoBackendError struct {
	ProviderHint string
	Registered   []string
}

type Option struct {
	Name        string
	Description string
}

type ProviderHTTPError struct {
	StatusCode int
	Body       string
}

type ProviderNetError struct {
	Reason string
}

type ProviderParseError struct {
	Reason  string
	BodyLen int
}

type Question struct {
	// Key is the caller's id for the question; the answer comes back under
	// the same key.
	Key string

	// Type is TypeNoul, TypeChoice, or TypeScore.
	Type string

	// Instructions is the question itself.
	Instructions string

	// Choices are the offered options for a choice question, in author
	// order.
	Choices []Option

	// Levels are a score question's rubric, lowest to highest.
	Levels []string

	// True and False optionally describe what each answer to a noul
	// question means. Empty = not supplied.
	True  string
	False string
}

type Request struct {
	// State is the evidence every question is asked against: a JSON string,
	// object, or array, passed to the provider as data.
	State json.RawMessage

	// Questions in author order. Keys are unique.
	Questions []Question

	// Model is the resolved model identifier.
	Model string

	// Intent is a trace-only label (e.g. "pony_ingest_place").
	Intent string
}

type Response struct {
	// Answers, one per question. After Normalize they are in question order.
	Answers []Answer

	// Provider is the backend name; Model is the model requested.
	Provider string
	Model    string

	// ResolvedModel is the model the provider reports having run, verbatim
	// ("" when it reports none). It may be an alias rather than a version;
	// the chassis records it and invents nothing.
	ResolvedModel string

	// Provider-reported token usage (0 if unreported). Recorded in trace and
	// the envelope; never charged to fuel.
	InputTokens  int64
	OutputTokens int64

	// Cost is the provider-reported cost in USD; nil when unreported.
	Cost *float64

	// GenerationID is the provider's id for this call, for reconciliation.
	GenerationID string

	// LatencyMS is wall-clock from request build to response parse.
	LatencyMS int64

	// Retries is the count of provider retries performed.
	Retries int
}

type TimeoutError struct {
	Reason string
}