aichat

aichat

Shared AI provider layer and Bubble Tea chat kit for Sneat, DataTug and future products. Apache-2.0.

Using the decision chain safely

Four things a product must know before it acts on ai/decision answers:

• Only a judged decision is actionable. Decision.Actionable() is true only when the package's own judges (Chain, compose.WithPolicy, decision.Deterministic) stamped a positive verdict in an unexported field. The exported Outcome is informational and is never believed from a provider, a remote engine or storage. A side-effectful interaction (confirmation, rejection, correction, cancellation, undo) needs, with or without a policy, an InteractionConfidence above 0 and at least the durable bar (0.90); a calibrated claim also needs InteractionScores, because a remote engine's calibrated flag is only a claim.
• A stored or replayed decision is NOT actionable and has lost its provenance class (a replayed rule decision reads self_reported). Re-judge it with Chain.Rejudge(d, taxonomy) (it is then an ordinary decision under your policy or floor, never deterministic), or re-run your rules.
• A stopped chain is not "nobody decided". At an exhausted allowance (ErrQuota), a spent budget (ErrBudget) or a misconfigured engine the chain returns ok=false with Trace.StoppedBy and Trace.Err() set, so a paid backup is never billed silently. Check Trace.StoppedBy BEFORE escalating to your paid main LLM. Put rules (deterministic providers) before the engines: a stop skips everything after it.
• A verdict belongs to the content it judged. Editing a judged decision's module, intent, interaction, confidences or Calibrated makes it not actionable again, json.Unmarshal into a judged value discards its verdict, and Chain.Rejudge never upgrades a refusal recorded in Outcome (a policy-less chain knows only its floor: rejudge with the chain that carries your policy). Fields outside that list (Scores, Slots, Reference, ...) are not bound: re-judge after changing them.
• A paid backup needs a cap. TypeSafe documents one 429 (a rate limit) and no way to tell a spent Jev account from it, so every 429 stays transient and a Fallback(Breaker(jev), Breaker(llm)) sends all traffic to the LLM once the account is spent (a probe: 5 Jev calls and 50 paid LLM calls in 50 turns). Wrap the backup in compose.NewBudget (inside its Breaker), or set decision.backupBudget: {maxCalls, per} in aiconfig. For anonymous or public traffic run the calibrated engine alone (no paid backup) or with a budgeted backup. The cap counts admissions, not billed requests (a hedge-started backup that loses still consumed one), its window is fixed (a burst across a boundary can admit twice the cap), a spent budget is never failed over from (OnQuota does not apply) and always beats an abstention or an uncertain answer, so the chain stops; a spent budget in a race halts the race.

Upgrade notes

• Usage is reported on every attempt. Trace.Attempts[i].Usage (and Report.Attempts) now carries what the engine billed for EVERY upstream call, not only an abstained or scored one: a decided answer, an answer the policy judged uncertain, and a call that failed after a response that carried a usage object. typesafe.Client reports one attempt per call from DecideTraced and the new ScoreTraced (outcome decided, abstained or error, with latency), and compose (Single, Fallback, Hedged, Race, Breaker, Budget) and decision.Chain keep it. A call whose response reported no usage, a network error or a leg still running when it was cancelled, has Usage == nil (cost unknown), never zero. A host that meters or caps spend can sum Attempts[].Usage from the trace; typesafe.CallEvent.Usage is likewise set on a failed call whose body carried usage. A report that used to carry no attempts for a decided answer or an error now carries one, so code that counted len(Attempts) as "abstentions" should filter on Outcome.

Products own scopes, intents, prompts, actions and controls. This module owns only what every product needs to talk to models and render chat the same way — including how it looks: github.com/tuigoff/tuigoff/pkg/theme is the single place colour, padding and border decisions live, and every tui/* package (and every product built on tui/chatshell) gets that look as the default, with zero styling code of its own. A product supplies content only — message text, hint labels ([]theme.Hint), top-bar title/context/menu items ([]theme.MenuItem) — never a colour literal. See spec/features/tui-kit for the full contract.

See docs/tui.md for the tui/* keyboard map and sidebar reference.