Question 1

Is this just a thin wrapper over the TypeSafe SDK?

Accepted Answer

It is a small client, but the value is in the question helpers. ask.if, ask.chance, ask.choice, ask.switch, and ask.score are tagged templates, and ask(state, questions) packs many questions about the same data into one request instead of one await per question. Answers come back under the same keys you asked with.

Question 2

Can it type arbitrary text, or only answer from fixed options?

Accepted Answer

Only fixed options. ask.choice takes 2-255 named options and ask.score takes 2-10 ordered levels; the model picks or rates, it does not write. You can still interpolate long text into a question by wrapping it as an object so it travels as state rather than as question text.

Question 3

What happens if the request fails or times out?

Accepted Answer

Requests are not retried, so a failure surfaces as a rejection rather than a silent duplicate charge. You can pass an AbortSignal (the docs show AbortSignal.timeout) plus a custom fetch and extra headers. Explicit options take priority over environment values.

Question 4

Will it work if my key only lives in a Vercel env var?

Accepted Answer

Yes. The client falls back from an explicit apiKey to TYPESAFE_API_KEY, then AI_GATEWAY_API_KEY, then VERCEL_OIDC_TOKEN. When the key comes from a Vercel variable the provider switches to the AI Gateway, and baseURL and model default to the gateway values instead of api.typesafe.ai and jev-latest.

Question 5

What does each question type actually return?

Accepted Answer

A string or ask.chance gives a chance object with the probability of yes from 0 to 1, and ask.if reduces that to a boolean above 0.5, with the threshold configurable. ask.choice returns the selected label typed against your keys, a probability for every label, and confidence that is high when one label stands out; ask.switch returns just the label. ask.score returns the expected zero-based score, which can be fractional, a ratio scaled to 0 to 1, and a legend plus probabilities keyed by level.

Question 6

How does interpolated data actually reach the model?

Accepted Answer

Text and numbers go straight into the question text. Objects and arrays become the request state instead: one is sent under input and its slot reads as `input`, several become `input[0]`, `input[1]` and so on. Inside ask, the objects from all tags in the request are sent once each in the same input, added to the state object, and passing both a state and tag objects that collide is an error. Wrap longer text as an object to keep it out of the question string.

Question 7

How do I install it, and does it ship anything for agents?

Accepted Answer

Install with npx nypm i advocaat and export TYPESAFE_API_KEY. It ships an agent skill at skills/advocaat/SKILL.md, installed with npx skills add pithings/advocaat, which teaches coding agents how to design questions and build with ask. The client itself is TypeScript and type-safe, with answers typed against the question keys you wrote.

Advocaat

About this project

Highlights

Questions about this entry

From the Jev guides

From the Jev AI model community