hunch

Plain functions on Jev. Lists in, lists out.

Jev is TypeSafe's System One model: you send state and typed questions, and you get labels, scores, and yes/no probabilities back. hunch turns that into six verbs you call like any other function. Code owns the workflow. Jev judges. An optional LLM may propose candidates; it never decides.

import hunch

hunch.classify("This product is amazing!", ["positive", "negative", "neutral"])
# 'positive'

hunch.classify(df["JOB_TITLE"], ["Sales", "Engineering", "Marketing"])
# Series of labels, same index

hunch.score("Critical system failure", ["cosmetic", "degraded, workaround exists", "down for everyone"])
# 1.87  (position on the scale, 0 .. n-1)

hunch.check("BUY NOW!!!", "is unsolicited advertising")
# True

Install

pip install hunch-jev

Python 3.10+. Set TYPESAFE_API_KEY, or call hunch.configure(api_key=...). Never put keys in source.

Verbs

Every verb takes a single item or a list / tuple / pandas Series and returns the same shape. Repeated values are asked once. Items run in parallel across max_workers threads. Every verb accepts context= (extra state alongside the input) and client=. Every verb has an _async twin.

labels may be a list, an Enum class (you get members back), or a mapping of label to description. instructions on score and check may be a mapping of name to question; the dimensions go in one request and you get a dict per item.

detail=True

The bare return is the answer. detail=True returns the whole distribution:

.shape is your policy on the distribution, not a Jev field:

level = hunch.classify(title, ["IC", "Manager", "Director"], detail=True)
seniority = level.on(
    sure=level.label,
    split=lambda: hunch.classify(title, level.top2),  # rematch the top two
    unsure="review",
)

Cutoffs live on ShapePolicy. Confidence is how peaked the distribution is, not whether the label is true. Changing the policy never re-runs inference.

Generate, rank, pick

An LLM drafts. Jev scores and chooses. Code keeps the weights.

import hunch

hunch.configure(llm=hunch.openrouter(), cache="~/.cache/hunch")

tweets = hunch.generate(str, n=20, instructions="Tweets introducing hunch to Python developers", context=README)

ranked = hunch.rank(
    tweets,
    {"hook": "How strong is the first line?", "clarity": "How clearly does it say what hunch does?", "specific": "How concrete, not generic, is it?"},
    levels=["weak", "okay", "strong", "excellent"],
    weights={"hook": 2, "clarity": 1, "specific": 1},
)
finalists = [row.item for row in ranked[:5]]

winner = hunch.pick(finalists, "the tweet most likely to make a Python developer install hunch")

generate accepts str, int, dataclasses, TypedDicts, pydantic models, list[str], and any other type pydantic can validate. hunch.openai, hunch.cerebras, and hunch.openrouter are OpenAI-compatible adapters; pass llm= on configure() or on generate().

Client

jev = hunch.Client(api_key=..., model="jev-latest", cache="~/.cache/hunch", max_workers=8, policy=ShapePolicy(...))
hunch.classify(x, labels, client=jev)
jev.usage   # calls, cache hits, tokens, model

hunch.configure(...) takes the same arguments and sets the default used when client= is omitted. cache= persists raw Jev answers on disk keyed by state and question.

Examples

Each one is a single file with the data inline. The first three need only TYPESAFE_API_KEY.

What this is not

Jev does not invent labels. labels is the whole set of allowed answers. generate invents candidates; it has no tools and takes no actions. Open-ended writing and multi-step agents are out of scope.

License

MIT. Jev and TypeSafe are typesafe.ai; this library is not affiliated.