AI: the language model (LLM) in server code (ai)
ai is the project's language model. In server code (*.server.ts, Server functions)
it asks for an answer, an object of a type, a look at pictures, calls of your server's functions, a
decision about a text, and keeps chats; in the app it has one member, ai.messagesResource(id): a chat's messages, live while the
answer is written. The code names no API key and no model: the model is the project's setting on
le.codes, paid from its owner's AI credits. Another provider's API is a fetch from server code, its
key in env.
- call an LLM from the server and show its answer in the app (
ai.send) - get structured output, JSON of a type, instead of text (
ai.send<T>) - describe a photo the user took, read a receipt or a menu (
images) - build a chat with an AI assistant that remembers the conversation (
ai.createChat,chat.send) - show the assistant's answer as it is being written, with a "typing…" line (
ai.messagesResource) - let the model look up an order or run my server code: function calling, tools (
ai.tool) - let the AI ask the user a question with answer buttons
- let the AI search the web, or read a page by its link, and show the sources under its answer (
ai.webSearch,ai.webFetch) - classify, moderate, route or rate a text cheaply — spam or not, which category, a score (
ai.decide) - show why the AI did not answer: no credits, too many requests, the daily limit (
AiError,RpcError.ai) - test an app that uses AI on my machine
Platforms: iOS, Android, the web and the web player, against a backend le.codes deployed — the
editor's preview and the published app; not on desktop: desktop run reaches only a backend on
your machine, a packaged desktop build none. A backend on your machine (lecodes dev, lecodes test, lecodes render, desktop run)
has no model: every ai.send, ai.decide and chat.send there throws AiError("unavailable") — see
Testing AI on your machine.
At a glance
// ask.server.ts — runs on the app backend
export async function ask(question: string) {
if (!question.trim()) throw new ApiError(400, "Ask something first")
const reply = await ai.send({
system: "You are a cooking assistant. Answer in two or three short sentences, plain text.",
text: question,
maxTokens: 400,
})
return reply.text
}// main.ts — the app
import { ask } from "./ask.server"
const asking = action((question: string) => ask(question))
const question = UIInput().style({ placeholder: "How long do I boil an egg?" }).named("question")
const answer = UIText("").named("answer")
UIScreen(
question,
UIButton(UIText(() => (asking.busy.value ? "Thinking…" : "Ask")))
.named("ask")
.onClick(async () => {
const text = await asking(question.value)
if (text !== null) answer.text = text
}),
answer,
UIText(() => asking.error.value?.message ?? "").named("error"), // why it did not answer — see Errors
).style({ gap: 12, padding: 24 }).open()In the le.codes preview and the published app the answer appears under the button. Under
lecodes dev the error line shows the refusal instead: ai.send works on a deployed backend only — the model runs on le.codes, paid by the project's owner: deploy the server to use it.
Testing AI on your machine: unavailable under lecodes dev, the answers on le.codes
Under lecodes dev and lecodes test the model does not answer: it answers only on a backend
le.codes deployed — the development backend (the editor's preview, the project link on a phone) and
the production one (the published app). A backend on your machine has no road to it:
- under
lecodes dev,lecodes test,lecodes renderanddesktop run,ai.sendthrowsAiError("unavailable"), so doesai.decide(ai.decide works on a deployed backend only — …), and so doeschat.send(A chat's answer is written on a deployed backend only — …), which leaves the chat as it was. Uncaught, the app's call fails with status 503 andai: "unavailable". The terminal says so at the first request, and each call it refuses in one line:[server:warn] ask.server.ts#ask: AiError("unavailable") — the call is refused with 503: …; - everything around the model works there:
ai.createChat,ai.getChat,ai.deleteChat,chat.messages()and, in the app,ai.messagesResource(id).
So test on your machine what the app does around the model — opening a chat, the error states, the retry — and the answers themselves in the le.codes preview. A flow can check the refusal:
{ "steps": [
{ "call": "ask.server.ts#ask", "args": ["hi"], "expect": { "error": { "status": 503 } } },
{ "type": "question", "text": "hi" },
{ "tap": "ask" },
{ "expect": { "node": "error", "text": "deployed backend only" } }
] }Which model answers and who pays: Data → AI
The model is the project's setting, not the code's: Data → AI in the le.codes editor. A request names
no model — ai.send({ model: … }) is refused as invalid.
- On the Free plan the model is Haiku; a paid plan may choose Sonnet or Opus. A setting the owner's plan does not allow runs on Haiku.
- Every request is paid from the project owner's AI credits (a team project's: the team's). With none
left, a request throws
AiError("credits"). - What the project's requests may cost a day (a UTC day) is capped; Data → AI shows today's spend
against that limit. Past it, a request throws
AiError("budget")until the next day.
Call the LLM from the server: ai.send
To ask the language model one thing from server code — answer a question, rewrite a text, summarize
a note — await ai.send in an endpoint and return what the app needs. To classify a text — yes or
no, a category, a tag from a list, a rating — ask ai.decide instead: about a second,
and a small fraction of a send's price.
await ai.send({
system?: string, // who the model is and how to answer
text?: string, // what it answers — and/or
images?: AiImage[], // pictures it looks at (see Pictures) — or
messages?: AiMessage[], // a conversation, in place of text and images (see A whole conversation)
tools?: AiTools, // functions it may call first (see Tools)
maxTokens?: number, // the most tokens the answer may take: 1024 when absent, 4096 at most
}): Promise<AiReply>
type AiReply = {
text: string // the answer
stop: "end" | "length" | "refusal" // done · cut off at maxTokens · the model would not answer
usage: { input: number, output: number } // tokens of the request (system and pictures in it) and of the answer
calls?: AiToolCall[] // the tools it called, in order; absent when none
}- A request is a
text,images, or both — ormessages, never beside them (invalid). An empty text, a key the request does not have, amaxTokensthat is no whole number above 0:invalid. - A token is a word or a piece of one. Past
maxTokensthe answer stops where it is:stopis"length"andtextis what was written. AmaxTokensabove 4096 is lowered to 4096. stop: "refusal": the model would not answer;textholds what it said, maybe"".- Each
ai.sendis one paid request, counted against the caller's rate and the project's limits (The limits). The time an endpoint waits for the model does not count toward its 30 s cap. ai.sendstreams nothing: it resolves with the whole answer. An answer the app shows as it is written is a chat.
Get an object instead of text: ai.send<T> (structured output)
To get data the model has to write — a recipe, a list of tasks, the fields of a receipt — give
ai.send a type: the model answers JSON of it, the answer is checked against it, and data is a
value of that type.
Classifying a text is not this. A verdict is ai.decide: yes or no (ai.yesNo), one
category of a few or one tag of a list (ai.choice), several tags (an ai.yesNo each), a rating
(ai.score). It answers with probabilities in about a second, for a small fraction of a typed send's
price, and its options may be built at run time — the person's own tags — which a type cannot say.
// recipes.server.ts
export type Recipe = {
title: string
minutes: number
vegetarian: boolean
difficulty: "easy" | "medium" | "hard"
ingredients: { name: string, amount: string }[]
tip?: string // optional: the model may leave it out
}
export async function recipeFor(dish: string): Promise<Recipe> {
const { data } = await ai.send<Recipe>({
system: "You write home recipes. Amounts in metric units; minutes = the whole time, preparation included.",
text: dish,
maxTokens: 1500,
})
return data // a whole Recipe: the answer was checked against the type
}await ai.send<T>(request): Promise<AiDataReply<T>>
type AiDataReply<T> = { data: T, stop: "end", usage: { input: number, output: number }, calls?: AiToolCall[] }What T may hold — the JSON a model can be told to write:
- an object at the top (wrap a list or a string in one:
{ items: … }); string,number,boolean,null, arrays, objects, literal unions ("easy" | "hard"),T | null, unions of objects; a property with?is one the model may leave out.
What fails the compile, with the file, the line and the place in the type: Date (use a string,
an ISO date), Map / Set, a class, a function, a File, any / unknown, an index signature
(Record<string, …>: name the keys, or use a list of { key, value }), a tuple, a recursive type, a
template-literal type, a type parameter, a property typed undefined (make it optional), a type
whose schema is over 64 KB:
the type of a typed ai.send and of an ai.tool's arguments is the JSON the model writes — this one cannot be told to it:
recipes.server.ts:12: ai.send<{ when: Date }>: data.when: Date is not JSON — use a string (an ISO date)- The type is the model's instructions: name each property for what it holds. Doc comments do not
reach the model — say the rest in
system. - It has no ranges or lengths:
minutes: numbermay come back 0 or 900, a list empty. Check what matters (data.minutes > 0) before you store it. datais always a wholeT. An answer that is not throwsAiError("incomplete"), its message saying why: it was cut off atmaxTokens(raise maxTokens), the model would not answer, or what it wrote did not match the type.- Write the call as it is —
ai.send<T>({ … })on the globalai, the type argument and the request its one argument: the compile writes the type's schema into that call. Called through another name (const send = ai.send) it is an untyped call, and its reply has nodata. - Tools may come with a typed call if each has a function; one the person answers is
invalidthere (Ask the person).
Send a photo to the AI: what is on it, read a receipt — images
To ask what is on a photo the user took, read a receipt or check a picture, send it in images: a
File the endpoint received from the app, or a stored file read from the database.
// photos.server.ts
const Dish = model({ name: t.string(), photo: t.image() })
const db = defineDb({ Dish })
export async function whatIsThis(photo: File) { // a picture the app uploads with the call
const reply = await ai.send({ text: "What dish is this? One short sentence.", images: [photo], maxTokens: 200 })
return reply.text
}
export async function caloriesOf(id: number) { // a picture stored in the database
const dish = await db.dish.where({ id }).first()
if (!dish) throw new ApiError(404, "No such dish")
const { data } = await ai.send<{ kcal: number }>({ text: `About how many kcal is this portion of ${dish.name}?`, images: [dish.photo] })
return Math.round(data.kcal)
}// main.ts — the app picks a photo and sends it with the call
import { whatIsThis } from "./photos.server"
UIScreen(
UIButton(UIText("What is this dish?")).named("pick").onClick(async () => {
const photo = await openFilePicker({ accept: "image/*" })
if (photo) toast(await whatIsThis(photo))
}),
).open()- An image is a parameter of type
File(an upload — Stored files) or the value of at.file()/t.image()field. Anything else, or a file that is no picture:invalid. - At most 5 pictures a request — with
messages, 5 across all of them. - Each is shown to the model as a JPEG turned the way the camera meant (HEIC photos are read), at most
1568 px on its longer side. Together, as shown, they take at most 6 MB: more is
invalid, send fewer. - With pictures,
textmay be left out. - Pictures are input: they count in
usage.input.
Give the model a whole conversation: messages
To give the model a conversation instead of one text — one your server keeps, or a chat's history
read for a summary — pass messages; the answer is the model's next message.
type AiMessage =
| { role: "user", text?: string, images?: AiImage[] } // a text, pictures, or both
| { role: "assistant", text: string, calls?: AiToolCall[] } // what the model said before, the calls it made// summary.server.ts — one sentence about a chat
export async function summarize(id: string) {
const history = await (await ai.getChat(id)).messages()
const reply = await ai.send({
system: "You say what a conversation was about in one sentence.",
messages: [...history.slice(-30), { role: "user", text: "What was this conversation about?" }],
maxTokens: 200,
})
return reply.text
}- The last message is the user's. At most 60 messages, and 5 pictures among them: a chat's history with more pictures than that needs the older ones taken out first.
- A chat's history fits as it is: a
ChatMessage's other keys (id,createdAt,writing) are not given to the model. A conversation that opens with the assistant's message (it greeted first) is fine.
Chat with an AI assistant that remembers the conversation: ai.createChat, chat.send
To build a chat with an AI assistant in the app — it remembers the conversation, the platform keeps its
messages, the answer shows while it is written — open a chat on the server and write to it with
chat.send. The chat stays on the server: an endpoint returns its id, and the app follows its messages
with ai.messagesResource(id).
// help.server.ts — the chat's server
defineDb({}) // a chat keeps its messages in the project's database
const ASSISTANT = { // who the assistant is: a chat keeps none of it, so every send says it
system: "You are the cafe's assistant. Answer briefly, in plain text.",
maxTokens: 800,
}
/** The id of the chat `id` names, or of a new one when there is none (no id yet, or the chat is gone). */
export async function openHelp(id: string | null): Promise<string> {
if (id) {
try {
return (await ai.getChat(id)).id
} catch (e) {
if (!(e instanceof ApiError)) throw e // 404: gone, 400: no chat's id — open a new one
}
}
return (await ai.createChat()).id
}
/** The person's message: resolves once the answer is stored. Refused, the chat is as it was. */
export async function say(id: string, text: string): Promise<ChatMessage> {
const chat = await ai.getChat(id)
return chat.send({ ...ASSISTANT, text })
}// main.ts — the app
import { openHelp, say } from "./help.server"
type Opened = { id: string, messages: Resource<ChatMessage[]> }
const savedId = signal<string | null>(null).stored("help-chat") // the device keeps the chat's id
const chat = signal<Opened | null>(null)
const list = computed((): ChatMessage[] => {
const loaded = chat.value?.messages.value
return loaded?.state === "ready" ? loaded.data : []
})
const last = computed(() => list.value[list.value.length - 1])
const sending = action((text: string) => say(chat.peek()!.id, text))
const Bubble = (m: ChatMessage) =>
UIText(m.text || "…").style({
alignSelf: m.role === "user" ? "flex-end" : "flex-start", maxWidth: "80%",
px: 12, py: 8, borderRadius: 14, color: "white", bgColor: m.role === "user" ? "#4f7cff" : "#2a3142",
})
const field = UIInput().style({ flexGrow: 1, placeholder: "Message" }).named("message")
const send = async () => {
const text = field.value.trim()
if (!text || !chat.peek() || sending.busy.peek()) return
field.value = ""
if ((await sending(text)) === null) field.value = text // refused: nothing changed — the text back
}
UIScreen(
UIScrollable(UIColumn(() => list.value.map(Bubble)).style({ gap: 8, padding: 16 })).style({ flexGrow: 1 }),
// the assistant is answering while the last message is the one being written; no word of it yet: "typing…"
UIText(() => (last.value?.writing && !last.value.text ? "typing…" : sending.error.value?.message ?? "")).named("status"),
UIRow(field, UIButton(UIText("Send")).named("send").onClick(send)).style({ gap: 8, padding: 16 }),
).style({ bgColor: "#1e2230" })
.onClose(() => chat.peek()?.messages.close()) // stop following it
.open()
const main = async () => {
const id = await openHelp(savedId.peek())
savedId.value = id
chat.value = { id, messages: ai.messagesResource(id) } // the chat's messages, live
}
main()The person's message appears once the server stored it, the answer under it as the model writes it, and it stays as one stored message. The server's side:
await ai.createChat(): AiChat // a new chat, its row written: chat.id is safe to store
await ai.getChat(id): AiChat // the chat id names — ApiError 400: no chat's id, 404 "No such chat"
await ai.deleteChat(id): boolean // true: gone, its messages and pictures with it; false: there was none
await chat.send({ system?, tools?, text?, images?, maxTokens? }): ChatMessage // the answer, once stored
await chat.messages(): ChatMessage[] // every stored message, in order
chat.id: string // a UUID — what an endpoint returns to the app
type ChatMessage = {
id: number | string // rises with the conversation; "writing" for the answer being written
role: "user" | "assistant"
text: string // "" for pictures alone, for an answer that only called tools, and at a turn's start
images: StoredImage[] // the user's pictures, as stored; an answer has none
calls?: AiToolCall[] // an answer's calls of tools; absent when none
createdAt: number // when it was stored, ms since 1970
writing: boolean // the answer being written (in the app's list only); false for every stored message
}-
A chat keeps its messages in the project's database, in two models of the platform that the compile adds (
AiChat,AiChatMessage: notdb.<model>, and no model of yours may take their names). A project that opens chats needs adefineDb(…)in a server file —defineDb({})when it has no models. Without one its backend does not start:a chat (ai.createChat, ai.getChat, ai.deleteChat) keeps its conversation in the project's database, and this project defines none — …. -
The three verbs answer a promise and are awaited where they are called.
ai.getChat(id).id, a call as a statement or a promise kept for later fails the compile:a chat's verb is awaited — ai.createChat, ai.getChat and ai.deleteChat answer a promise: help.server.ts:4: ai.getChat(…) — write `await` before it -
They take no options (
ai.createChat({ system })throws): who the assistant is goes with each send.
Who the assistant is: said at every send
A chat stores only its messages. system, tools and maxTokens belong to each chat.send: keep
them in one module constant and spread it into every send — chat.send({ ...ASSISTANT, text }). A
change of the constant reaches every chat at its next answer. One send may add to it:
chat.send({ ...ASSISTANT, system: ASSISTANT.system + "\nThis is the last question.", tools: { ...ASSISTANT.tools, finish }, text })
— finish a tool made in the endpoint, which sees that call's values.
One turn: chat.send waits, all or nothing
chat.send is ai.send that remembers the conversation: it stores the user's message (text,
images, or both), asks the model with the chat's history and the send's tools, stores the answer
and resolves with it.
- All or nothing. When
sendresolves, both messages are in the chat. When it throws — anAiError, orApiError(404)because the chat was deleted meanwhile — nothing of the turn is: the user's message and its pictures were taken back. What a tool did meanwhile stays done. To ask again, callsendagain. - No
textand noimages: the assistant speaks by itself — a greeting on a new chat, going on mid-chat. Only its answer is stored, and it counts as one of the day's messages.text: ""is not that: it is an empty message, refused with 400. - An answer cut off at
maxTokensis stored as it is. A turn whose answer has neither text nor calls throwsAiError("incomplete"). - One turn per chat at a time: a
sendwhile one runs is refused withApiError(409),An answer is being written in this chat — wait for it to end. - A message is at most 8000 characters and 5 pictures, else
ApiError(400). A chat's pictures areFiles the call received (a stored file belongs to its row and is refused); they are stored as at.image()field's are (Pictures). - The model is given the chat's last 30 stored messages — the answers' calls with their results among
them — and the 5 newest pictures. What is older it does not see: keep lasting facts in
systemor behind a tool. - The endpoint's call waits as long as the answer takes; that wait does not count toward its 30 s cap. An app that goes away meanwhile stops nothing: the answer is stored.
- A deploy or a restart of the backend under a running turn takes the turn back: the call is refused
(502
incomplete,The answer was not written — ask again, or 503) and the chat is as it was.
Show the AI's answer while it is being written: the chat's messages, ai.messagesResource(id)
To show a chat on a screen — its messages, and the answer as the model writes it — an endpoint returns
the chat's id (chat.id, a string) and the app opens ai.messagesResource(id): a resource of the
chat's messages, live, the same kind of thing a computed's .resource() is.
const messages = ai.messagesResource(chatId) // Resource<ChatMessage[]> — chatId: what an endpoint returned
messages.value: Loaded<ChatMessage[]> // loading → ready: the last 200 stored, the answer being written last · failed
messages.peek(): Loaded<ChatMessage[]> // the same, read without following it
messages.reload() // follow it again: after close() (a screen's onOpen), or when it failed
messages.close() // stop following it (a screen's onClose)- The list is the server's. The user's message appears once it is stored. From the start of a turn to
its end the LAST message is the answer being written —
id: "writing",writing: true, itstext""at first and then growing, itscallsas the tools run — and the stored answer takes its place when the turn ends. A turn that gets no answer takes the message and the answer being written out of the list again. - "Is the assistant answering" is the last message's
writing: show "typing…" while it is true and itstextis still"". failedwhen the server refuses it: 404No such chat(no chat has that id, or it was deleted withai.deleteChat), 400 when the id is no UUID. Opening it never throws.- Each call is a subscription of its own: open it where the screen that shows the chat is built and
close()it when the screen closes;reload()follows it again. - It only reads: there is no
send. The app writes through your endpoints, and whether a message went through is that call's answer — anaction'serror, not the list. - It rides the channels' socket: after a reconnect or a deploy it shows the chat as the server has it.
- The chat object itself never leaves the server. An endpoint that returns it, a computed whose value
holds it, a channel message carrying it are refused with a 500, in words that say what to do:
the answer of help.server.ts#openHelp holds a chat (result) — a chat stays on the server: return its id, chat.id, and the app follows it with ai.messagesResource(id). aiis one name on both sides with each side's members:ai.messagesResourceis the app's, andai.send,ai.tooland the chat verbs are the server's. The compile refuses a member on the wrong side, with the file and the line:ai.messagesResource is the app's — on the server read a chat with ai.getChat(id),ai.send runs on the server — call an endpoint.
Keep, protect and delete a chat: its id
chat.id is what you keep to open the chat again: a t.uuid() field of the row the chat belongs to,
or the device's storage (signal(null).stored(key)), handed back to an endpoint that calls
ai.getChat(id).
- The id is the right to read the chat: whoever has it may follow it (
ai.messagesResource(id)). An endpoint returns it only to who may read the chat, and writes only after checking the caller — find the chat through a row of theirs instead of taking any id:
// chats.server.ts — each user's conversations, nobody else's
const User = model({ name: t.string().default("") })
const Conversation = model({ owner: t.one("User").onDelete("cascade"), chat: t.uuid().unique() })
const db = defineDb({ User, Conversation }).withAuth({ model: "User" })
const ASSISTANT = { system: "You are a helpful, concise assistant.", maxTokens: 1024 }
/** The caller's conversation `id` — someone else's is "not found", like one that never was. */
const mine = async (id: number) => {
const me = await db.auth.requireUser().select({ id: true })
const row = await db.conversation.where({ id, owner: { id: me.id } }).first()
if (!row) throw new ApiError(404, "No such conversation")
return row
}
/** A new conversation of the caller: our row's id, and the chat's — to its owner only. */
export async function newConversation(): Promise<{ id: number, chat: string }> {
const me = await db.auth.requireUser().select({ id: true })
const chat = await ai.createChat()
const { id } = await db.conversation.insert({ owner: me, chat: chat.id })
return { id, chat: chat.id }
}
export async function sendMessage(id: number, text: string): Promise<ChatMessage> {
const row = await mine(id)
return (await ai.getChat(row.chat)).send({ ...ASSISTANT, text })
}
export async function deleteConversation(id: number) {
const row = await mine(id)
await ai.deleteChat(row.chat) // false when it was gone already: no error
await db.conversation.delete(row.id)
}- A chat lives until
ai.deleteChat(id). One that has no message is removed by the platform a day after it was made — a chat whose only message was taken back among them. A kept id may therefore be gone:getChatrejects with 404; catch it andcreateChat. ai.deleteChat(id)removes the chat, its messages and their pictures. It resolvesfalsefor an id that names no chat, so calling it twice is safe; an id that is no UUID isApiError(400). Asendof that chat waiting for its answer rejects with 404, and an app'sai.messagesResource(id)of it turnsfailed, 404No such chat.
Let the model call your code: tools, ai.tool (function calling)
To let the model look something up or do something while it answers — find an order, check the stock, save a result — give it tools: functions of your server, each with a description and a typed parameter. The model calls them, reads what they return, and answers once it has what it needs.
// orders.server.ts
const Order = model({ number: t.string().unique(), status: t.string(), total: t.float() })
const db = defineDb({ Order })
const findOrder = ai.tool(
"Find one of the cafe's orders by its number: its status and its total",
async ({ number }: { number: string }) => {
const order = await db.order.where({ number }).select({ status: true, total: true }).first()
if (!order) throw new ApiError(404, `There is no order ${number}`) // the model reads this message
return order
},
)
export async function askAboutOrders(question: string) {
const reply = await ai.send({
system: "You answer questions about the cafe's orders. Look an order up before you say anything about it.",
text: question,
tools: { findOrder }, // the key is the name the model calls it by
maxTokens: 500,
})
return { text: reply.text, lookedUp: reply.calls?.length ?? 0 }
}ai.tool(description: string, fn: (args: A) => unknown): AiTool // the code answers the call
ai.tool<A>(description: string): AiTool // the person answers it — see Ask the person
tools: { findOrder, ask } // in ai.send and chat.send: the key is the tool's name
type AiToolCall = { tool: string, args: unknown, result?: unknown, error?: string }- The description is what the model reads to decide when to call it (10 000 characters at most).
- The function takes ONE object of arguments, typed — or none (
() => Date.now()). The model is told that type's JSON, with the rules ofai.send<T>; a parameter with no type, two parameters or a non-object fail the compile:ai.tool: a tool's function takes ONE object of arguments — …. - What it returns, sync or async, goes back to the model as JSON: any value, at most 16 KB as JSON (a larger result is an error the model is told).
- A throw is the model's to hear, and it goes on: an
ApiError's message as it is, any other error asThe tool failed(the error itself in the server console). Arguments that do not match the type are not run; the model is told why. - It runs where the send was made, in the endpoint's call:
requestanddb.authare the caller's. A tool made inside an endpoint sees that call's values. - The calls of one answer run one after another. One send may ask the model 8 times and run 24 calls
— past either it throws
AiError("incomplete").textis all the model wrote between its calls,usagethe sum,maxTokenseach model call's; the send counts once against the caller's rate. reply.callslists the calls in the order they ran, each with itsresultor itserror.- What a tool did stays done when the send fails after it — in a chat too.
- The name is the key in
tools: letters, digits,_and-, 64 at most; 16 tools a request. - Make a tool with
ai.tool(…)on the global, in a server file: the compile writes its schema into that call. One it did not see throwsai.tool: this tool has no schema of its arguments — ….
A chat's tool calls are part of the chat
In a chat, the answer is stored with its calls — their arguments and results — and whoever follows
the chat sees them; ai.messagesResource(id) shows each call while it runs (no result yet), then with
its result. The model is given them again at the next turns. Return what the conversation may hold: the
fields the answer needs, not a whole row.
Ask the person a question with answer buttons: a tool without a function
To let the model ask the user — a quiz, an onboarding interview, "which of these did you mean?" with
buttons — give it a tool with no function: ai.tool<T>(description). Its call ends the assistant's
turn, the app shows its arguments, and the person's next message is its answer.
// quiz.server.ts — the model asks, the person answers with a button (or types)
export type Ask = { question: string, options: string[] }
const ask = ai.tool<Ask>("Ask the user one question, with 2 to 4 short answers they can tap") // no function: the person answers
const QUIZ = {
system: "You run a five-question quiz about the solar system. Ask every question with the ask tool, never in your text. " +
"After each answer say in a few words whether it was right. After the fifth, give the score and ask nothing more.",
tools: { ask },
maxTokens: 400,
}
export async function startQuiz(): Promise<string> {
const chat = await ai.createChat()
await chat.send({ ...QUIZ }) // no text: the assistant speaks first — and asks
return chat.id // the app follows it: ai.messagesResource(id)
}
export async function answerQuiz(id: string, text: string) {
const chat = await ai.getChat(id)
await chat.send({ ...QUIZ, text }) // the answer to the waiting question: its result for the model
}// main.ts — the app
import { answerQuiz, startQuiz, type Ask } from "./quiz.server"
type Opened = { id: string, messages: Resource<ChatMessage[]> }
const chat = signal<Opened | null>(null)
const messages = computed((): ChatMessage[] => {
const loaded = chat.value?.messages.value
return loaded?.state === "ready" ? loaded.data : []
})
const replying = action((text: string) => answerQuiz(chat.peek()!.id, text))
/** The question waiting for the person: a call of `ask` with neither result nor error in the last stored message. */
const waiting = computed((): Ask | null => {
const last = messages.value[messages.value.length - 1]
if (last?.role !== "assistant" || last.writing) return null // while an answer is written, a call is still running
const call = last.calls?.find((c) => c.tool === "ask" && c.result === undefined && c.error === undefined)
return call ? (call.args as Ask) : null
})
UIScreen(
UIColumn(() => messages.value.filter((m) => m.text).map((m) => UIText(`${m.role === "user" ? "You" : "Quiz"}: ${m.text}`))),
UIText(() => waiting.value?.question ?? "").style({ fontSize: 20 }).named("question"),
UIRow(() => (waiting.value && !replying.busy.value ? waiting.value.options : []).map((option, i) =>
UIButton(UIText(option)).named(`option-${i + 1}`).onClick(() => replying(option)),
)).style({ gap: 8, flexWrap: "wrap" }),
UIText(() => replying.error.value?.message ?? ""),
).style({ gap: 12, padding: 24 })
.onClose(() => chat.peek()?.messages.close())
.open()
startQuiz().then((id) => { chat.value = { id, messages: ai.messagesResource(id) } })- A tool with a function: the code answers. A tool without one: the person answers.
Tis its arguments — an object type, with the rules ofai.send<T>: what the model fills in and the app shows.ai.tool("…")with neither a function nor a type argument, and a type argument beside a function, fail the compile. - When the model's answer calls it, the tools with a function called in that same answer still run,
in order, and then the turn ends — the model is not asked again.
chat.sendresolves with the stored answer: its text (what the model wrote before the call, maybe"") and itscalls, where this call has neitherresultnorerror. - The next
chat.send({ ...QUIZ, text })is its answer — a tapped option and a typed one alike. The model is given that message as the call's result; in the chat it is an ordinary user message. Pictures sent with it go along; a send with no text answers it with "no message". Several such calls in one answer are all answered by that one message. - The send that answers carries the same tool (spread the same constant). Without it the model gets the person's message as an ordinary one, after a call with no answer.
- In the app, the waiting question is a call with neither
resultnorerrorin the chat's LAST message, once it is stored (!writing): while an answer is being written, a call without a result is a tool still running. - Arguments that do not match
Tare an error result like any tool's, and the model goes on. - With
ai.sendthe reply ends the same way (stop: "end", the call waiting incalls). Give the conversation back with the person's answer after it, and the tool again:
export type Pick = { question: string, options: string[] }
const pick = ai.tool<Pick>("Ask the user to choose one option")
export async function nextTurn(first: string, said: AiReply, answer: string) {
return ai.send({
tools: { pick },
messages: [
{ role: "user", text: first },
{ role: "assistant", text: said.text, calls: said.calls },
{ role: "user", text: answer }, // the waiting call's result for the model
],
})
}- A typed
ai.send<T>takes no tool without a function: its answer is data, and this call would end it with none (invalid).
Search the web and read a page: ai.webSearch(), ai.webFetch()
For what the model does not know — today's news, a price, a product page, an article the user links — give it the web tools. Anthropic runs them on its servers: no function, no description, just the tool under the name your app calls it.
// support.server.ts
const SUPPORT = {
system: "You help the cafe's customers. Search the web for anything about the area; read a page when the customer sends a link.",
tools: { findOrder, search: ai.webSearch(), page: ai.webFetch() }, // findOrder: a tool of your own, beside them
maxTokens: 800,
}
export async function ask(id: string, text: string) {
await (await ai.getChat(id)).send({ ...SUPPORT, text })
}
export async function quick(question: string) {
const reply = await ai.send({ ...SUPPORT, text: question })
return { text: reply.text, sources: reply.sources ?? [] } // show the sources with the answer
}ai.webSearch(options?: AiWebOptions): AiWebTool
ai.webFetch(options?: AiWebOptions): AiWebTool
type AiWebOptions = { maxUses?: number, allowedDomains?: string[], blockedDomains?: string[] }
type AiSource = { url: string, title: string }- They go in the same
toolsobject, inai.sendandchat.sendalike, beside your own tools — one of each a send. The key is your name for it;web_searchandweb_fetchare the model's own names for them, so a tool of yours may not use those keys. - Their calls are in
callslike any, under your key — never a page itself:- a search:
{ tool: "search", args: { query }, result: { sources: [{ url, title }] } }— the pages it found (an empty list when nothing matched); - a page:
{ tool: "page", args: { url }, result: { url, title? } }; - either with
errorinstead ofresultwhen it failed — Anthropic's code:max_uses_exceeded,too_many_requests,url_not_accessible,url_not_in_prior_context,unsupported_content_type,unavailable, … The model hears it and goes on.
- a search:
sources— onreply.sourcesand on a chat's stored answer — are the pages the answer's text cites, each once, in the order it first cites them; absent when it cites none (the model may search and still cite nothing: the search'sresult.sourcessays what it found). Anthropic's terms: when you show the answer to people, show its sources with it.- While a chat's answer is written, a web call with no
resultyet is the search running — show "Searching the web…". A stored answer's web calls always have aresultor anerror. - A page is read only from a link already in the conversation: the user's message, a tool's
result, an earlier search's pages — never a link the model wrote itself, nor one only in
system. A link you want it to read goes in the user's message:text: `${question}\n\n${url}`. Pages that need JavaScript to render are not read. maxUses: how many searches (or pages) one send may make — 3 unless given, at most 5.allowedDomainsorblockedDomains(not both): bare domains with an optional path, no scheme —"docs.example.com","example.com/blog"— 20 at most. A wrong option throws at theai.webSearch(…)/ai.webFetch(…)call:ai.webSearch: maxUses is at most 5 uses in one send, got 6.- What it costs the owner: a search costs about $0.01 on top of the tokens its results take; a page read costs its tokens — up to about 20 000 of a page. Both count against the project's daily limit.
- A chat stores the answer's text, its calls and its sources — not the pages: the next turns are not given them again (and are not paid for them again). The model sees its earlier answer's text.
- A typed
ai.send<T>takes no web tool (invalid): the API cannot cite pages in a typed answer. Search in one send, then ask for the typed answer in another, the first answer's text in itstext.
// main.ts — the answer, "Searching the web…" while a search runs, and the sources under it
const messages = ai.messagesResource(chatId)
const list = computed((): ChatMessage[] => (messages.value.state === "ready" ? messages.value.data : []))
const bubble = (m: ChatMessage) => {
const searching = m.writing && (m.calls ?? []).some((c) => c.tool === "search" && c.result === undefined && c.error === undefined)
return UIColumn(
UIText(m.text),
...(searching ? [UIText("Searching the web…").style({ color: "#888" })] : []),
...(m.sources ?? []).map((s, i) => UIText(`[${i + 1}] ${s.title}`).style({ color: "#2563eb" }).onClick(() => openURL(s.url))),
).style({ gap: 4 })
}
UIScreen(UIColumn(() => list.value.map(bubble)).style({ gap: 12 })).style({ padding: 16 }).open()Classify, moderate, route or rate a text with AI: ai.decide (spam, a category, sentiment, a score)
To classify a text with AI — content moderation (is this comment spam, toxic or offensive), the
category or tag of a message, which team a support request is routed to, sentiment analysis, a rating
on a scale — ask the platform's decision model with ai.decide. It writes no text: it answers a
question of a kind with how likely each answer is, in about a second, for a small fraction of what an
ai.send costs.
// reviews.server.ts
const Review = model({ text: t.string(), topic: t.string().default(""), hidden: t.boolean().default(false) })
const db = defineDb({ Review })
export async function addReview(text: string) {
if (!text.trim()) throw new ApiError(400, "Write something first")
const { spam, topic } = await ai.decide(text, {
spam: ai.yesNo("Is this review spam or an advertisement?", {
yes: "Advertising, links, the same text repeated",
no: "An opinion about the cafe, even a rude one",
}),
topic: ai.choice("What is the review mostly about?", {
food: null, // the name says it
service: "Staff, waiting time, delivery",
price: null,
}),
})
return db.review.insert({
text,
hidden: spam.probability > 0.8, // a threshold of your own
topic: topic.confidence > 0.5 ? topic.choice : "", // topic.choice: "food" | "service" | "price"
})
}// text classification: a verdict with probabilities, ~1 s, far cheaper than ai.send or a typed ai.send<T>
await ai.decide(text: string, question: AiQuestion): the question's answer
await ai.decide(text: string, questions: { name: AiQuestion, … }): { name: that question's answer, … }
ai.yesNo(question: string, criteria?: { yes?: string, no?: string }) → { probability: number }
ai.choice(question: string, options: { name: string | null, … }) → { choice: name, confidence: number, probabilities: { name: number, … } }
ai.score(question: string, levels: string[]) → { score: number, confidence: number, probabilities: number[] }- Several tags of a list are a yes / no question each, in one decide —
ai.decide(note, Object.fromEntries(tags.map((tag) => [tag, ai.yesNo(`Does the note fit the tag "${tag}"?`)])))— and the tags past your threshold are the note's; one tag is anai.choiceover them. - One question answers its answer:
const spam = await ai.decide(text, ai.yesNo("Is it spam?")), thenspam.probability. Several go by name and answer under the same names — one request, one payment of the text, each question asked of the text by itself (one says nothing to another). ai.yesNo→probability: how likely the answer is yes, 0 … 1. The criteria say what counts as yes and as no, where the question leaves room — either, both or none. It is how SURE the model is, not how much: "Is the customer angry?" at 0.9 is "almost certainly angry", not "very angry". A degree is anai.score.ai.choice→choice: the likeliest option's name;probabilities: each option's, by name (together about 1);confidence: how far ahead the choice is, 0 (all alike) … 1. An option is its name and a description, ornullwhen the name says it; 1 to 255 of them.ai.score→score: where the text sits on the levels — 0 is the first, fractional (1.7: between the second and the third;Math.round(score)is a level's index);probabilities: each level's, in order;confidence: how narrowly they sit around one level. The levels are described lowest first, 2 to 10 of them. One thing a score: "useful" and "polite" are two questions.- The answer's type comes from the call:
choiceis the union of the option names written there,probabilitieshas exactly those keys, and the answers have the names of the questions. Options built at run time (aRecord<string, string | null>made from a table's rows) work the same;choiceis then astring. - The model always answers — it has no "I do not know", and a choice always picks one of the
options. Act past a threshold of your own (
probability > 0.8,confidence > 0.5) and treat the rest as undecided; for "none of these", ask anai.yesNobeside the choice ("Does it name any of these topics?"). - Ask narrow questions: one thing each, answerable from the text alone. A judgment of several
factors is several questions put together in code. What needs reasoning over steps, or words —
an explanation, a summary, a reply — is an
ai.send. textis a string, at most 200 000 characters — an object goes asJSON.stringify(value). The model itself takes about 64 000 tokens a request and 32 000 with any one question; past that the call throwsAiError("invalid"). At most 32 questions a decide; a question 10 000 characters, a criterion (what counts as yes, an option's description, a level) 2 000.- A wrong argument of
ai.yesNo/ai.choice/ai.scorethrows where the question is made (ai.score: a score has 2 to 10 levels, got 1); a question may be made once, at the module's top, and asked many times. - Which model decides is the platform's — one for every project and plan, not the Data → AI
setting: TypeSafe's Jev, and the text and the questions are sent to TypeSafe. The owner pays for the tokens of the text and the questions (the answers cost nothing), from
the same AI credits and against the same daily limit as
ai.send. - It throws the same
AiErrorasai.send—credits,budget,busy,unavailable(a backend on your machine among them:ai.decide works on a deployed backend only — …),invalid— and an uncaught one refuses the app's call the same way (Errors). One decide is one request of the caller's rate, however many questions it asks. - It takes no pictures, no
system, no tools, and it is no part of a chat: decide in the endpoint, before or after thechat.send. - Where the decision is optional, catch the refusal and go on without it — the review is saved
unsorted, the message goes to the default team. The app then works on a backend with no model too
(
lecodes dev, a check), where every decide isunavailable:
const decided = async <Q extends AiQuestion | Record<string, AiQuestion>>(text: string, question: Q): Promise<AiAnswers<Q> | null> => {
try {
return await ai.decide(text, question)
} catch (e) {
if (e instanceof AiError && e.code !== "invalid") return null // no decision this time
throw e
}
}
const spam = await decided(text, ai.yesNo("Is this review spam?"))
const hidden = spam !== null && spam.probability > 0.8 // undecided: shown, as before// support.server.ts — route a message before answering it
const DEPARTMENT = ai.choice("Which team handles this message?", {
billing: "Payments, refunds, invoices",
delivery: "Where the order is, a late or damaged order",
other: "Anything else",
})
export async function route(message: string) {
const team = await ai.decide(message, DEPARTMENT) // one question: its answer
return team.confidence > 0.6 ? team.choice : "other"
}When the AI does not answer: out of credits, the daily limit, busy — AiError, RpcError.ai
When the model gives no answer — the owner is out of credits, the day's limit is spent, too many
requests — ai.send, ai.decide and chat.send throw an AiError: its code is the reason the code can act on,
its message the words. An endpoint that does not catch it refuses the app's
call with the status of the code, and the app reads the code as ai.
class AiError extends Error { readonly code: AiErrorCode } // server: what ai.send and chat.send throw
err.ai?: AiErrorCode // app: on RpcError — and on the Failure of an action / resourcecode |
why | the app's call, uncaught |
|---|---|---|
credits |
the project's owner has no AI credits left | 402 |
budget |
the project's daily AI limit is spent (Data → AI) | 402 |
busy |
too many requests: this caller's, the project's (8 at once) or the platform's — the same request can go a little later | 429 |
unavailable |
no model answered: a backend on your machine, or the platform did not answer (or its web tools are turned off: a send with ai.webSearch() / ai.webFetch()) |
503 |
incomplete |
no whole answer: a typed answer that is not a whole T; a chat's answer that was not written; the model still calling tools after 8 rounds or 24 calls |
502 |
limit |
chat.send only: the person sent the most messages a day allows (100) |
429 |
invalid |
the request is wrong — your code's mistake, the message says what | 500 Internal error, no ai |
- An uncaught
AiErroris no crash: the call is refused in theAiError's words, its code on the app'sRpcError.ai, and the server console says it in one line.invalidis a 500 like any throw, its message in the server console only. - A channel's hook and a computed's run that let one escape carry
aithe same way (the subscription'serror, a resource'sfailed). - A 429 without
aiis the transport'sToo many calls(The limits). - A chat's other refusals are
ApiErrors with noai: 400 (an empty or too long message, no chat's id), 404 (No such chat), 409 (a turn is running).
In the app, branch on ai and say it in the person's words:
// main.ts
import { ask } from "./ask.server"
const asking = action((question: string) => ask(question))
const said = (f: Failure): string => {
if (f.offline) return "No connection"
switch (f.ai) {
case "limit": return "That's all for today — come back tomorrow"
case "busy": return "Too many questions at once — try again in a few seconds"
case "credits": case "budget": return "The assistant is resting until tomorrow"
case "unavailable": case "incomplete": return "The assistant could not answer — try again"
}
return f.message // the endpoint's ApiError
}
UIScreen(
UIButton(UIText("Ask")).named("ask").onClick(() => asking("What is on the menu today?")),
UIText(() => (asking.error.value ? said(asking.error.value) : "")).named("error"),
).open()On the server, catch it where the answer is optional:
export async function suggestTitle(text: string): Promise<string | null> {
try {
const { data } = await ai.send<{ title: string }>({ system: "Name the note in 2 to 6 words.", text, maxTokens: 60 })
return data.title
} catch (e) {
if (e instanceof AiError && e.code !== "invalid") return null // no title this time: the note saves all the same
throw e
}
}The limits
What a project's AI may do, and what each limit produces past it:
| what | limit | past it |
|---|---|---|
| requests of one caller — a device: its session, its address before it has one | one every 5 s, a burst of 5 | busy |
| requests of server code with no call behind it (a timer, the module's load) | one bucket for all of them, the same rate | busy |
| the project's requests at once (a chat's turn among them) | 8 | busy |
| what the project's requests cost a day (UTC) | the daily limit Data → AI shows | budget |
| the owner's AI credits | what is left | credits |
| an answer's tokens, each model call's | maxTokens: 1024 when absent, 4096 at most |
stop: "length"; typed: incomplete |
text / system of a request |
400 000 / 200 000 characters | invalid |
messages of ai.send({ messages }) |
60 | invalid |
| pictures of a request | 5; each shown at 1568 px at most; 6 MB together | invalid |
| a typed answer's schema | 64 KB as JSON | a compile error |
| tools of a request | 16, the web tools among them; a description 10 000 characters | invalid |
| one send with tools | 8 model calls (a paused long turn's going on among them), 24 calls of your tools | incomplete |
| web tools of a request | one ai.webSearch(), one ai.webFetch() |
invalid |
| a web tool's uses in one send | maxUses: 3 when absent, 5 at most; a domain list 20 at most, one list |
thrown at ai.webSearch(…) / ai.webFetch(…); past maxUses the call's error is max_uses_exceeded |
| a page the model reads | about 20 000 tokens of it | the rest is cut off |
a typed ai.send<T> with a web tool |
not allowed | invalid |
| a tool's result | 16 KB as JSON | the model is told the call failed |
the text of an ai.decide |
200 000 characters; about 64 000 tokens with its questions, 32 000 with any one | invalid |
the questions of an ai.decide |
32; a choice's options 255; a score's levels 2 to 10 | invalid; a maker's own limits throw where the question is made |
| a chat's message | 8000 characters, 5 pictures | ApiError 400 |
| a chat's turns | one at a time | ApiError 409 |
| messages one person sends to the project's chats | 100 in 24 h | limit (429), nothing stored |
| what the model sees of a chat | the last 30 stored messages, the 5 newest pictures | older ones are not given to it |
what ai.messagesResource(id) lists |
the last 200 stored messages | await chat.messages() on the server has every one |
| a chat with no message | removed a day after it was made | getChat rejects with 404 |
- One send is one request of the caller however many tool rounds it takes; a chat's turn is one too,
and so is an
ai.decide, however many questions it asks. - The daily messages count the user's messages and the answers of sends with no text (the assistant
speaking by itself), against the device whose call made the send. A turn that got no answer leaves
nothing and is not counted; a
chat.sendwith no call behind it (a timer) is not counted.
Inside a computed: what is a read, what is refused
A server computed runs again whenever its data changes, so it only
reads. A chat inside one:
await ai.getChat(id)is allowed: it reads nothing the computed follows.await chat.messages()is followed: a message stored later runs the computed again.ai.createChat(),ai.deleteChat(id)andchat.send(…)are writes: the run fails with status 500,computed help.server.ts#helpView: AiChat.insert is a write — a computed only reads (…); write in an endpoint.ai.sendis no write and runs — but each run of the computed is another paid request, at every change of its data. Ask in an endpoint and store the answer in a row the computed reads.- A computed's value carries the chat's id, never the chat: a value that holds the chat object is
refused like an endpoint's answer (a 500 saying to return
chat.id).
export const conversationView = computed(async (id: number): Promise<{ chat: string, messages: number }> => {
const row = await mine(id) // the caller's row: `mine` of chats.server.ts above
const chat = await ai.getChat(row.chat) // a read: allowed, not followed
return { chat: chat.id, messages: (await chat.messages()).length } // followed: a new message runs it again
})Pitfalls
await ai.send({ model: "claude-…", text }) // ✗ invalid: which model answers is the project's setting (Data → AI)
await ai.send({ text }) // ✓
const chat = ai.getChat(id) // ✗ compile error: a chat's verb is awaited
const chat = await ai.getChat(id) // ✓
await ai.createChat({ system: "You help." }) // ✗ throws: a chat keeps no options
await chat.send({ ...ASSISTANT, text }) // ✓ who the assistant is, at every send
await chat.send({ text: "" }) // ✗ 400: an empty message
await chat.send({ ...ASSISTANT }) // ✓ no text: the assistant speaks by itself
return await ai.getChat(id) // ✗ endpoint: 500 — a chat stays on the server
return (await ai.getChat(id)).id // ✓ its id; the app opens ai.messagesResource(id)
const messages = ai.messagesResource(id) // ✗ in a *.server.ts file: compile error — the app's member
const history = await (await ai.getChat(id)).messages() // ✓ the server reads a chat so
const reply = await ai.send({ text }) // ✗ in the app: compile error — ai.send runs on the server
const reply = await ask(text) // ✓ an endpoint that calls ai.send
ai.send<{ when: Date }>({ text }) // ✗ compile error: Date is not JSON
ai.send<{ when: string }>({ text }) // ✓ an ISO date
ai.send<Report>({ text, tools: { search: ai.webSearch() } }) // ✗ invalid: a typed answer takes no web tool
const found = await ai.send({ text, tools: { search: ai.webSearch() } })
ai.send<Report>({ text: `${text}\n\nWhat was found:\n${found.text}` }) // ✓ search first, then ask typed
ai.send({ system: `Summarize ${url}`, tools: { page: ai.webFetch() } }) // ✗ the link is only in system: url_not_in_prior_context
ai.send({ system: "Summarize the page the user links.", text: url, tools: { page: ai.webFetch() } }) // ✓ in the user's message
await ai.decide(text, "Is this spam?") // ✗ invalid: a question is made by ai.yesNo / ai.choice / ai.score
await ai.decide(text, ai.yesNo("Is this spam?")) // ✓
if ((await ai.decide(text, ai.yesNo("Spam?"))).probability) hide() // ✗ 0.02 is truthy: a probability, not a yes
if ((await ai.decide(text, ai.yesNo("Spam?"))).probability > 0.8) hide() // ✓ a threshold of your own
await ai.decide(order, ai.yesNo("Is it late?")) // ✗ invalid: the text is a string
await ai.decide(JSON.stringify(order), ai.yesNo("Is it late?")) // ✓
ai.webSearch({ maxUses: 10 }) // ✗ throws: at most 5 uses in one send
tools: { web_search: myTool } // ✗ invalid: web_search / web_fetch are the web tools' names
UIText(reply.text) // ✗ an answer with sources shown without them
UIColumn(UIText(reply.text), ...(reply.sources ?? []).map((s) => UIText(s.title).onClick(() => openURL(s.url)))) // ✓See also
- Server functions — endpoints,
action/resource,RpcError, computeds - Database — the rows a chat's id belongs to
- Stored files —
Fileparameters andt.image()fields, the pictures a request carries - Sign-in —
db.auth, whose chats are whose - Keys (env) — another provider's API, its key kept out of the code