Jev AI Function Calling: Turn Typed Signatures into Confidence-Scored Dispatcher Calls

Updated Applies to Jev 1.14

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 a Noul, and every function into an option of one more Choice — 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:

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:

ShapeDeclared asBecomesExample
choiceLiteral["a", "b"]one Choice over exactly those valuessymbol: Literal["SPY","NVDA","AMD","AAPL","MSFT","TSLA"]
setlist[Literal[...]]one Noul per member, {} in the text standing for the membersymbols in compare_returns
flagboolone on/off questioninclude_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:

  1. Write each question about the idea, not the words. The match is on meaning, so “is amd tracking nvidia lately” reaches rolling_correlation even though neither tracking nor lately appears anywhere in spec.json.
  2. 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.

CommandCallconfidencetool
“show nvda 1h”plot_price(symbol='NVDA', resolution='1h')0.590.99
“plot rolling correlation between nvda and spy for the past month”rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo')0.931.00
“when during the day does nvda trade the most”intraday_pattern(symbol='NVDA')0.531.00
“what moved today”top_movers(window='1d', direction='gainers')0.900.94
“what tickers do you have”list_symbols()1.001.00
“how did the market do this week”market_summary(window='1w')0.940.98
“candles for tesla with a 20 period moving average”plot_price(symbol='TSLA', style='candles', moving_average='20')0.881.00
“compare nvda amd and msft over the past three months”compare_returns(symbols=['NVDA','AMD','MSFT'], window='3mo')0.931.00
“how volatile is tsla”volatility(symbol='TSLA')0.971.00
“biggest losers today”top_movers(window='1d', direction='losers')0.941.00
“worst drawdown for nvda this quarter, and chart it please”drawdown(symbol='NVDA', window='3mo', plot=True)0.920.98
“spy stats for the last month”summary_stats(symbol='SPY', window='1mo')0.970.98
“show me apple daily with volume”plot_price(symbol='AAPL', resolution='1d', include_volume=True)0.690.98
“is amd tracking nvidia lately”rolling_correlation(symbol='AMD', benchmark='NVDA')0.690.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:

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

  1. Enumerate the arguments first. Any argument that cannot take a Literal (or a small list[Literal]) will silently keep its default. Decide for each one whether that default is acceptable.
  2. Give every closed-set argument a stated question if the argument is optional. Without it the Choice is forced to guess.
  3. 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.
  4. Log the weakest argument, not just the confidence. The number tells you a call is risky; the name tells you what to ask.
  5. 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”.
  6. 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.

Frequently asked questions

+ What is function calling in Jev AI?

It is the pattern of taking an ordinary typed function whose arguments come from fixed lists, and generating one System One question per argument plus one question that picks the function. The answer is a function name with its arguments already filled from the enum values the function accepts, each carrying a probability, and the call as a whole carrying a confidence equal to its least certain argument. TypeSafe documents it in a cookbook titled Function calling at docs.typesafe.ai/cookbooks/function_calling.

+ Does Jev AI need the function's source code to be modified?

No. The cookbook states the point directly: you leave the functions alone, and what you add is a specification that says in plain words what each argument means. The closed sets are read from the existing type hints, so a signature already annotated with Literal values is enough to derive the questions.

+ How many questions does one command generate?

In the cookbook's own trading example, 54 questions per command. That figure is printed by the notebook itself, and it covers one Choice over the ten function descriptions plus the argument questions for all ten functions, because the dispatcher sends every function's arguments in the same request and then reads only the answers belonging to the function it picked. Questions are evaluated in parallel, so adding them barely changes response time, but extra questions still cost tokens.

+ What confidence does a dispatched call report?

The confidence is the least certain judgement behind the call, not the product of all the argument probabilities. The cookbook gives the reason: one wrong argument is enough to spoil the result, whereas a product answers a different question — whether every part is right — and it falls as a function takes more arguments whether or not any single judgement is shaky. In the worked example, a call reported confidence 0.69 because one argument scored 0.69 while the others scored higher.

+ What happens to arguments that are not free-form strings or enums?

They get no question at all and the function's own default stands. The cookbook shows top_movers, whose limit argument is an int: of its three arguments two are closed sets and the third never gets a question, so it keeps its default of 3. Free text, numbers and dates work the same way — no question, default kept.

+ Can Jev AI extract free-form values like names or amounts?

Not by asking for the value. The documentation's guidance for data extraction is to pull candidate options out with regex or a generative model first and let Jev pick the correct one, and the option count ceiling on a Choice is 255. A function calling setup therefore fills arguments from closed sets, and leaves unenumerated values to the ordinary code that called it.

+ What does the stated question do?

It makes an argument optional. It is a second yes/no question asking whether the command mentions that argument at all; when the answer is no, the call omits the argument and the function's own default applies. The cookbook's example is a command ending in lately, which says nothing about how far back to look, so both the window and the resolution arguments were omitted and the function ran on its defaults.

Keep reading