Hunch (TypeScript)

Hunch is a library that adds probabilistic control flow to TypeScript: you ask questions about text or application data in plain English and use the answers directly in code, such as branching on whether an order almost certainly looks fraudulent.

It asks a System One model, such as TypeSafe's Jev, which answers with calibrated probabilities rather than generated text. You configure a backend such as SystemOne with a URL, API key and model, and Hunch parses the typed answers for you.

Install with npm install @carldaws/hunch, then create a Hunch with a backend: new Hunch({ backend: new SystemOne({ url, apiKey, model }) }). The README's example points at https://openrouter.ai/api/alpha/decisions with model typesafe/jev-1.13 and an OPENROUTER_API_KEY.

chance returns a probability between 0 and 1. The named levels convert it to booleans: possibly is at least 0.25, likely 0.5, probably 0.75 and almostCertainly 0.93. Built-in thresholds can be overridden, for example new Hunch({ backend, levels: { probably: 0.8 } }).

Use pick for unordered categories such as billing, support and sales, and rate for ordered levels such as low, medium and high. rate returns a level plus a numeric position and supports comparisons like atLeast('livid'); pick just returns one of your named options.

Yes. hunch.decide takes the given data and a set of questions, sending them in one API call. The result carries each answer, a probabilities object and confidence values, for example result.team, result.probabilities.team and result.confidence.team.

No, this repository is a TypeScript port of carldaws/hunch, published as @carldaws/hunch on npm. The Ruby gem is a separate package with its own backend configuration, and the README documents no shared benchmarks between the two.