Jev AI Function Calling: Turn Typed Signatures into Confidence-Scored Dispatcher Calls
TL;DR: Jev AI function calling is not the LLM kind, where a model writes a JSON blob you then validate. TypeSafe’s approach is to read the type hints already on your functions, turn every closed-set argument into a
Choice, every optional argument into aNoul, and every function into an option of one moreChoice— then send all of it as a single request and read back only the branch that was selected. The cookbook measures the result: 10 functions, 28 fillable arguments, 54 questions per command, and 14 test commands whose confidences range from 1.00 down to 0.53. Nothing in the functions changes. This page walks the cookbook’s own printed output, argument by argument.
If you have read that LLM tool-calling is “just a schema”, the interesting part here is what replaces the schema. There is no JSON Schema, no tool_choice, no grammar-constrained decoding. There is a signature whose arguments are Literals, plus a spec.json that says in plain English what each argument means, plus a dispatcher that asks every question at once.
Where these facts come from
Everything below was checked on 2026-11-14 against three TypeSafe pages:
- Function calling cookbook — the ten-function trading dispatcher, its printed tables, and all fourteen command results. The executable example also lives in the public examples repository at
github.com/typesafe-ai/typesafe-public-examples/tree/main/cookbooks/function_calling, which is where the notebook downloadsdispatch.py,trader.py,spec.jsonandbars.parquetfrom. - Choice primitive — option limits, what
probabilitiesandconfidencemean, and why confidence is derived from the shape of the distribution. - Noul primitive — why a yes/no question has no separate
confidence, and the 0.7 / 0.3 starting thresholds. - Models — model ID
jev-1.14.0and the $42 per billion tokens / $0.042 per million tokens price.
One disclosure the cookbook makes about itself, repeated here because it matters if you plan to copy the numbers: the tickers in the example are real, but every price, return and chart is simulated from a fixed random seed. The confidences are real model output; the market data is not market data.
The problem the page is actually solving
A trading assistant exposes ten ordinary functions. A user types a sentence. The sentence never names a function.
"plot rolling correlation between nvda and spy for the past month"
rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo') confidence 0.93
"compare nvda amd and msft over the past three months"
compare_returns(symbols=['NVDA', 'AMD', 'MSFT'], window='3mo') confidence 0.93
"show me apple daily with volume"
plot_price(symbol='AAPL', resolution='1d', include_volume=True) confidence 0.69
"what tickers do you have"
list_symbols() confidence 1.00
The cookbook’s own analogy for this is a barista: when you order a large iced oat latte with no sweetener, they do not write your sentence down, they mark four options on a cup. The equivalent here is that a sentence goes in and a function name plus evaluated arguments comes out, each argument having been chosen from a fixed list.
The reason this fits a judgment model rather than a generative one is that every decision is a closed question. Which function? One out of ten. Which symbol? One out of six. Were candles or a line requested? Yes or no, twice over. There is no point in the pipeline where the model has to produce a value that was not already on a list.
Three shapes hide inside the signatures
The type hints already declare which arguments come from a fixed list. The cookbook’s closed_sets helper reads a signature and sorts those arguments into three shapes:
| Shape | Declared as | Becomes | Example |
|---|---|---|---|
| choice | Literal["a", "b"] | one Choice over exactly those values | symbol: Literal["SPY","NVDA","AMD","AAPL","MSFT","TSLA"] |
| set | list[Literal[...]] | one Noul per member, {} in the text standing for the member | symbols in compare_returns |
| flag | bool | one on/off question | include_volume, log_scale |
The signature the cookbook prints as its sketch is worth reading in full, because it shows how much of the work the type annotation already did:
def plot_price(
symbol: Literal["SPY", "NVDA", "AMD", "AAPL", "MSFT", "TSLA"],
style: Literal["line", "candles"] = "line",
resolution: Literal["1m", "5m", "15m", "1h", "1d"] = "15m",
window: Literal["1d", "1w", "1mo", "3mo"] = "1w",
include_volume: bool = False,
moving_average: Literal["9", "20", "50"] | None = None,
log_scale: bool = False,
): ...
Seven arguments, and the notebook’s measured output classifies all seven: symbol:choice, style:choice, resolution:choice, window:choice, include_volume:flag, moving_average:choice, log_scale:flag.
The measured inventory
This is the notebook’s printed table, not a reconstruction. Ten functions, and a fillable-argument count per function:
list_symbols 0
market_summary 1 window:choice
plot_price 7 symbol:choice, style:choice, resolution:choice, window:choice, include_volume:flag, moving_average:choice, log_scale:flag
intraday_pattern 3 symbol:choice, window:choice, metric:choice
compare_returns 3 symbols:set, window:choice, normalize:flag
rolling_correlation 4 symbol:choice, benchmark:choice, window:choice, resolution:choice
summary_stats 2 symbol:choice, window:choice
volatility 3 symbol:choice, window:choice, annualized:flag
top_movers 2 window:choice, direction:choice
drawdown 3 symbol:choice, window:choice, plot:flag
28 fillable arguments in total
Two details in that table are more useful than the total.
list_symbols has zero. Its output line is the trailing blank after the count, because there is nothing to fill. A function with no closed-set arguments needs no argument questions at all — it can still be selected, it simply contributes nothing else.
top_movers shows what gets skipped. It has three arguments and only two are closed sets. The third, limit, is an int, so it never gets a question and keeps its default of 3. That is the general rule for anything unenumerated: free text, numbers and dates get no question, and the function’s own default stands. It is also the reason this pattern cannot be used to pull a customer name or an invoice amount out of a sentence — those are exactly the arguments that fall through.
The spec is where English lives
The Literal gives you the strings "1mo" and "3mo". It does not tell the model that a user typing this quarter means the second one. That is the spec’s job, and it is the only part of the setup a human has to write. It holds one question per argument, a description per option, a description per function, and one more question that picks between functions.
Two entries from the cookbook’s actual spec.json, printed by the notebook:
{
"style": {
"question": "Does the user want a plain line or candles?",
"stated": "Does the user say how the chart should be drawn, such as a line, candles, or OHLC bars?",
"options": {
"line": "a simple line through the closing prices",
"candles": "a candlestick or OHLC chart, showing each bar's open, high, low and close"
}
}
}
{
"moving_average": {
"question": "How many bars should the moving average cover - nine, twenty, or fifty?",
"stated": "Does the user ask for a moving average or a smoothed line over the candles?",
"options": {
"9": "a nine-bar moving average, a fast one",
"20": "a twenty-bar moving average",
"50": "a fifty-bar moving average, a slow one"
}
}
}
Three mechanics are buried in those few lines.
Option keys are the function’s own strings. "9", not "nine". Nothing has to map a label back to an argument afterwards, which removes an entire class of off-by-one bugs from the dispatcher.
stated is what makes an argument optional. It is a second yes/no question — a Noul — asking whether the command says anything about that argument at all. Answer no, and the call omits the argument so the function’s default applies. Without it, the Choice would be forced to name some window even when the command names none.
A set gets its question once per member. "Does the user want {} in the comparison?" becomes one question per ticker, with {} standing in for the member name.
Two authoring rules the cookbook states
Both of these are about meaning rather than wording, and both are easy to get wrong:
- Write each question about the idea, not the words. The match is on meaning, so “is amd tracking nvidia lately” reaches
rolling_correlationeven though neither tracking nor lately appears anywhere inspec.json. - Do not name a question after its parameter. The cookbook’s counter-example is
"Which resolution?"— it gives the command nothing to match against.
Fifty-four questions, one request
Dispatcher builds the question set from the spec once. After that, each user command is a single request carrying the choice of function and every function’s arguments, with the dispatcher reading only the answers belonging to the function that won.
54 questions per command, among them:
__tool__ choice What is the user asking the trading assistant to do?
plot_price.style choice Does the user want a plain line or candles?
plot_price.style? noul Does the user say how the chart should be drawn, such as a line,
compare_returns.symbols.NVDA noul Does the user want NVDA in the comparison?
Note the naming convention: plot_price.style is the Choice, and plot_price.style? — same path with a question mark — is the stated Noul. The __tool__ id is the routing choice over the ten function descriptions.
Sending all ten functions’ arguments on every command looks wasteful and is in one sense: extra questions still cost tokens, the documentation says so plainly. What it buys you is latency. Questions are evaluated in parallel, so adding questions barely changes response time, and the code simply ignores the answers it does not need. That is the same advice the Choice primitive page gives in general — ask every question you might need in one request rather than one request per question.
Fourteen commands, measured
The cookbook runs fourteen commands and prints the call plus two numbers: the call’s confidence and the tool probability for the function it routed to.
| Command | Call | confidence | tool |
|---|---|---|---|
| “show nvda 1h” | plot_price(symbol='NVDA', resolution='1h') | 0.59 | 0.99 |
| “plot rolling correlation between nvda and spy for the past month” | rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo') | 0.93 | 1.00 |
| “when during the day does nvda trade the most” | intraday_pattern(symbol='NVDA') | 0.53 | 1.00 |
| “what moved today” | top_movers(window='1d', direction='gainers') | 0.90 | 0.94 |
| “what tickers do you have” | list_symbols() | 1.00 | 1.00 |
| “how did the market do this week” | market_summary(window='1w') | 0.94 | 0.98 |
| “candles for tesla with a 20 period moving average” | plot_price(symbol='TSLA', style='candles', moving_average='20') | 0.88 | 1.00 |
| “compare nvda amd and msft over the past three months” | compare_returns(symbols=['NVDA','AMD','MSFT'], window='3mo') | 0.93 | 1.00 |
| “how volatile is tsla” | volatility(symbol='TSLA') | 0.97 | 1.00 |
| “biggest losers today” | top_movers(window='1d', direction='losers') | 0.94 | 1.00 |
| “worst drawdown for nvda this quarter, and chart it please” | drawdown(symbol='NVDA', window='3mo', plot=True) | 0.92 | 0.98 |
| “spy stats for the last month” | summary_stats(symbol='SPY', window='1mo') | 0.97 | 0.98 |
| “show me apple daily with volume” | plot_price(symbol='AAPL', resolution='1d', include_volume=True) | 0.69 | 0.98 |
| “is amd tracking nvidia lately” | rolling_correlation(symbol='AMD', benchmark='NVDA') | 0.69 | 0.85 |
The routing question was almost never the problem. tool sits at 0.98–1.00 for eleven of the fourteen commands, and the two lowest values in the whole table — 0.94 and 0.85 — still selected the right function. The uncertainty lives in the arguments, not in the choice of function. That is the single most useful thing in this table if you are deciding where to put your fallback logic.
Two commands deserve a closer look.
“compare nvda amd and msft over the past three months” put three tickers in the symbols set and left the other three out — a six-way set resolved correctly in one pass. The cookbook’s framing is that the questions respect roles: in the correlation command, symbol and benchmark draw from the same six tickers, and each ticker landed in the right argument because the questions spell out the one being measured, named first against the second one named, the yardstick. Same closed set, two meanings, no cross-wiring.
“is amd tracking nvidia lately” is the one that tests the spec. It produced rolling_correlation(symbol='AMD', benchmark='NVDA') with confidence 0.69 and tool 0.85 — the lowest routing probability in the table — even though the words tracking and lately appear nowhere in spec.json.
Why 0.69, when only one argument was shaky
The cookbook breaks that call down argument by argument, and this is the part worth internalising:
"is amd tracking nvidia lately" -> rolling_correlation(symbol='AMD', benchmark='NVDA') confidence 0.69
symbol 'AMD' p 0.93 AMD 0.93 NVDA 0.07 AAPL 0.00
benchmark 'NVDA' p 0.69 NVDA 1.00 AAPL 0.00 AMD 0.00
window omitted, default stands p 0.88
resolution omitted, default stands p 0.95
weakest argument: benchmark
Two arguments were filled confidently. One was omitted with a high stated probability. One — benchmark — came in at 0.69, and the call’s confidence is 0.69 because confidence is the least certain judgement, not the product.
The justification is stated directly: one wrong argument is enough to spoil the result. A product would answer a different question — is every part right — and it falls as a function takes more arguments whether or not any single judgement is shaky, which would punish plot_price for having seven arguments instead of two. Taking the minimum means the number you compare against a threshold is the number that should actually block the call.
This is the same semantics the standalone Choice primitive uses, where confidence is computed from how spread out the probability distribution is: a single peak means high confidence, a flat shape spread over several options means low confidence. Here it is simply applied per argument and then reduced with min.
The stated probability is not a certainty
An oddity worth flagging, because it trips people up. window and resolution were omitted yet still carry a probability, 0.88 and 0.95. That number belongs to the yes/no stated question — the probability that the command said something about the argument. A high value means the model was confident in its answer to “did the user mention a window?”, and that answer was no. High probability of a negative answer is still a confident answer, so it does not drag the call’s minimum down.
The reason both were omitted is the word lately: it says nothing about how far back to look or on what bars, so rolling_correlation ran on its own defaults of one month and hourly bars. That is exactly the behaviour the stated question exists to produce, and it is what stops a dispatcher from inventing an argument the user never gave.
Putting a threshold on a dispatched call
The confidence value is only useful if something reads it. Following the documented guidance, there are two places to branch:
On the call’s confidence, three ways. Below a floor, do not execute — ask the user a clarifying question naming the weakest argument. Above a ceiling, execute. In between, hand the call to a person or to a confirmation UI. This is the same three-way split the confidence page describes for Choice and Score answers, applied to the whole call rather than to one field.
On the individual argument probabilities. call.weakest() returns the argument that set the minimum. Naming it in the clarification prompt is what turns a 0.69 into a good user question — “did you mean NVDA as the benchmark?” is answerable; “which benchmark?” after the user already typed a sentence is not.
For the yes/no arguments, the documented starting point is 0.7 for yes and 0.3 for no, with the caveat that where you put it depends on the cost of being wrong: raise it when acting on a false yes is expensive, lower it when missing a true yes is expensive. Values between 0.3 and 0.7 can go to a person rather than either code path. Do not fit thresholds closely to a handful of test cases.
Notice what the fourteen-command table implies for a naive threshold of 0.9: five of the fourteen commands would have gone to a person, including the perfectly reasonable "show nvda 1h" at 0.59 and "show me apple daily with volume" at 0.69. Both of those calls look right. A high floor is expensive here, and the reason is that partial sentences genuinely are ambiguous — “show nvda 1h” never said what to plot.
What this pattern does and does not buy you
It buys you a guarantee the LLM pattern does not give. Whatever reaches the function is a value the function accepts, because the option keys are the argument’s own strings. There is no validation layer between the dispatcher and the call, and no malformed-argument branch to write.
It buys you a calibrated per-argument number. The confidence is not a vibe; it is derived from a probability distribution over the options you supplied, and it names the weakest part of the call.
It costs tokens on arguments you throw away. Ten functions’ worth of questions go out on every command. The documentation’s own rule — ask everything once, ignore what you do not need — trades token spend for round trips, and it is the right trade when latency matters more than the marginal cost.
It does not extract values you did not enumerate. The 255-option ceiling on a Choice, and the rule that free text, numbers and dates get no question at all, both point the same way: candidate generation belongs in code or in a generative model, and Jev’s job is to pick among candidates. If your function needs a free-text query argument, that argument arrives at its default and you fill it some other way.
It does not replace the functions. The cookbook’s line is worth keeping: you leave the functions alone. The dispatcher is additive, which is what makes the pattern adoptable in an existing codebase where the selectors already exist.
A translation to the non-trading case
Strip the tickers out and the shape is generic. Any pipeline that routes a message to one of N handlers, each with a small set of enumerated settings, is the same problem:
- Support routing. One
Choiceover N queues, oneChoiceover priority levels, aNoulper attached tag. See support routing scenarios for the routing layer this dispatcher would sit in front of. - Invoice approval. One
Choiceover approve / reject / escalate, aChoiceover a bounded set of reason codes, plusNoulquestions per policy check. The invoice approval gate case shows the response shapes. - Form or ticket triage. One
Choiceover departments, aChoiceover subcategories per department — which is where the hierarchical variant becomes relevant, since the subcategory set can be conditioned on the department answer in a second request.
What makes any of these work is having the enumerations first. The cookbook’s fourteen commands did not succeed because the model understood trading; they succeeded because "1mo" and "3mo" and candles were already on a list and the spec said what each one meant. If your handlers take free strings, there is nothing to ask.
A minimal checklist before you wire this in
- Enumerate the arguments first. Any argument that cannot take a
Literal(or a smalllist[Literal]) will silently keep its default. Decide for each one whether that default is acceptable. - Give every closed-set argument a
statedquestion if the argument is optional. Without it theChoiceis forced to guess. - Write option descriptions that separate the options from each other. Both the option names and their descriptions are sent to the model, and the descriptions are what do the separating work.
- Log the weakest argument, not just the confidence. The number tells you a call is risky; the name tells you what to ask.
- Test with commands that name nothing. Every one of the fourteen worked. The interesting ones were “what moved today” and “is amd tracking nvidia lately”.
- Expect to take the minimum, and set your floor accordingly. Five of fourteen commands land below 0.9 in the cookbook’s own table, and all five look correct.
FAQ
Is this the same as OpenAI-style function calling? No, and the difference is architectural rather than cosmetic. In the LLM pattern the model emits arguments it generated, and your code validates them. Here there is no generation step: every argument is chosen from a list you supplied, and the answer is a distribution over those options plus a probability. The trade is expressiveness for guaranteed-valid arguments.
Can I dispatch to more than ten functions?
The cookbook uses ten, and the documentation’s practical ceiling for a Choice is 255 options, so the function-routing question has the same headroom as any other Choice. What grows with function count is the per-command question total — the dispatcher sends every function’s arguments each time — so a large handler set is a token-cost decision before it is a limit decision.
Does the dispatcher need a separate request per function? No. The cookbook is explicit that each command is one request carrying the choice of function and every function’s arguments, with the dispatcher reading only the chosen function’s answers. That is why 54 questions can be asked for the price of one round trip.
What model does the example use?
jev-1.14.0 is pinned in the notebook, with a note that jev-latest runs the newest model live. Pricing from the models page is $42 per billion tokens and $0.042 per million tokens.
If I set DOWNLOAD_CACHE = True, does it call the API at all?
No. In that mode the notebook fills its cache from the published answers and the run makes no requests. Set it to false and delete the cache file to go live — an existing cache on disk is never overwritten.