@softr/sdk 0.0.78-alpha.2 → 0.0.78

package/skills/softr-sdk/ai/SKILL.md

@@ -1,161 +0,0 @@
----
-name: ai
-description: >-
-  Run an AI model from the app on Softr's own keys, billed to the workspace's
-  AI credits, with nothing to connect: defineAiAction from @softr/sdk declares
-  the action with the catalog model it runs on and its permissions;
-  ai.generate from @softr/sdk/server runs it with a system text, a prompt, an
-  optional JSON schema for an answer that is data, and optional files;
-  ai.stream runs it for an answer the user watches being written. Load this
-  for a summary, an extraction, a classification, a draft, or a chat the app
-  asks a model for.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.78-alpha.2
----
-
-**Boundary.** `ai` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineAiAction` and every type come from `@softr/sdk` and can be imported anywhere.
-
-# AI
-
-An app asks a model through an AI action. Softr runs the call on its own provider keys and bills the workspace's AI credits, so there is no key to ask the user for and nothing to connect. This is the path for every AI feature of the app's own — a summary of a record, fields extracted from a document, a classification, a draft, a chat — unless the user explicitly asked to use their own provider account, which is the `integrations` sub-skill's path.
-
-## Choose the model first
-
-The model is chosen when the app is built and frozen in its code. Before you declare an action, read Softr's catalog with the `ai_list_models` tool. Each entry carries the `id` the action names, the `provider`, and `bestFor`, what to pick it for:
-
-- a summary, a briefing, a draft, reasoning over many facts: the strongest model listed;
-- an extraction or a classification over one document: the cheapest model that reads that document's kind — a PDF needs a model whose `bestFor` says so.
-
-Copy the `id` exactly. An id outside the catalog is refused when the action is saved, and a model spelled from memory never is in it.
-
-## Declare the action
-
-```ts
-const summarizeDeal = defineAiAction({
-  id: 'summarizeDeal',
-  model: 'anthropic-claude-sonnet-4-6',
-  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
-})
-```
-
-Write the object inline in `defineAiAction`. Passing it through a variable widens the types.
-
-**Every call spends the workspace's credits.** Keep the audience to `['LOGGED_IN_USERS']`, narrowed with `customGroups` where the feature is for some users only. Open an AI action to visitors only when a public page really needs it, and say so to the user: anyone on the internet can then bill the workspace.
-
-Declare one action per feature — the summary and the extraction are two actions, each with its own `id`, its own model and its own audience.
-
-## Core pattern: an answer the server reads
-
-`ai.generate(action, init)` runs the action and answers when the model is done. `init` takes:
-
-- `prompt` — what the model is asked, with the facts it is given. Required.
-- `system` — what the model is and the rules it answers under.
-- `schema` — a JSON schema the answer has to match. With it the model is asked for JSON only, and the answer comes back parsed in `json` as well as written in `text`.
-- `files` — documents and images the model reads, each as `{ url, mimeType? }`: an `https` URL Softr may fetch, one of the app's own uploads as a rule.
-- `maxOutputTokens` — a cap on the answer's length. Softr caps it further.
-- `messages` — the earlier turns of a conversation, oldest first, each `{ role: 'user' | 'assistant', content }`. The prompt is the newest turn. Leave out for a one-shot call.
-- `reasoning` — `'low'`, `'medium'` or `'high'`: how hard a reasoning model thinks before it answers. The catalog says which models reason; the others ignore it. Leave out for the provider's default.
-- `temperature` — 0 to 1: how varied the answer is. `0` for an extraction or a classification, around `0.7` for a draft. A low default when left out.
-
-The answer is `{ text, json, usage, model }`: `text` as the model wrote it, `json` parsed when a schema was given and the model kept to it, `null` otherwise.
-
-```ts
-const summarize = createServerFn({ method: 'POST' })
-  .validator(z.object({ recordId: z.string() }))
-  .handler(async ({ data }) => {
-    const deal = await ds.get(dealQuery, { id: data.recordId })
-    if (deal === null) throw new Error('This deal no longer exists')
-    const facts = [`Name: ${fieldText(deal.fields.name)}`, `Stage: ${fieldText(deal.fields.stage)}`].join('\n')
-    const answer = await ai.generate(summarizeDeal, {
-      system: 'You brief a sales team. Use only the facts given; say what is missing rather than invent it.',
-      prompt: facts,
-      maxOutputTokens: 800,
-    })
-    return answer.text
-  })
-```
-
-## Extraction: an answer that is data
-
-A document dropped on the app, fields pulled out of it, a record created — the model reads the file and answers in the shape the record needs. Give it the schema and the file; validate the parsed answer before writing it, since a model may stray from the shape.
-
-```ts
-const InvoiceFields = z.object({ vendor: z.string(), total: z.number(), issuedOn: z.string() })
-
-const extractInvoice = createServerFn({ method: 'POST' })
-  .validator(z.object({ fileUrl: z.string().url() }))
-  .handler(async ({ data }) => {
-    const answer = await ai.generate(readInvoice, {
-      system: 'Read the invoice and answer with its fields. Dates as YYYY-MM-DD, amounts as numbers.',
-      prompt: 'Extract the vendor, the total and the issue date.',
-      schema: {
-        type: 'object',
-        properties: { vendor: { type: 'string' }, total: { type: 'number' }, issuedOn: { type: 'string' } },
-        required: ['vendor', 'total', 'issuedOn'],
-      },
-      files: [{ url: data.fileUrl, mimeType: 'application/pdf' }],
-    })
-    const parsed = InvoiceFields.safeParse(answer.json)
-    if (!parsed.success) throw new Error('The invoice could not be read. Try a clearer scan.')
-    return ds.create(createInvoice, { data: parsed.data })
-  })
-```
-
-The file's URL comes from the app's own upload: load the Softr SDK `file-uploads` guidance for that half. `readInvoice` names a model whose `bestFor` reads PDF documents.
-
-## A conversation
-
-A chat sends its earlier turns in `messages` and the new one as `prompt`. The app keeps the turns; the model holds nothing between calls.
-
-```ts
-const reply = createServerFn({ method: 'POST' })
-  .validator(z.object({ turns: z.array(z.object({ role: z.enum(['user', 'assistant']), content: z.string() })), prompt: z.string() }))
-  .handler(async ({ data }) => {
-    const answer = await ai.generate(supportChat, {
-      system: 'You answer questions about the order the user is looking at.',
-      messages: data.turns,
-      prompt: data.prompt,
-      temperature: 0.5,
-    })
-    return answer.text
-  })
-```
-
-A chat the user watches being written streams instead, with the same `messages`: see the next section.
-
-## Streaming: an answer the user watches being written
-
-A chat, an assistant, a long draft shown as it is typed — never buffer these: the user would watch a blank panel until the last token. `ai.stream(action, init)` takes the same `init` and answers with a `Response` whose body is a stream of Server-Sent Events. Hand it to the browser from the server function, unchanged:
-
-```ts
-const draftReply = createServerFn({ method: 'POST' })
-  .validator(z.object({ prompt: z.string() }))
-  .handler(async ({ data }) => {
-    const res = await ai.stream(draftAction, { system: 'You write replies for a support team.', prompt: data.prompt })
-    return new Response(res.body, { headers: { 'Content-Type': 'text/event-stream' } })
-  })
-```
-
-Each event is one JSON object on a `data:` line:
-
-- `{ "text": "..." }` — the next piece of the answer; append it.
-- `{ "done": true, "usage": { "inputTokens", "outputTokens" }, "model": "..." }` — the answer is complete.
-- `{ "error": "..." }` — in place of `done`, when the call ended before its answer: show the message.
-
-On the client, call the server function's URL with `fetch`, read `response.body` with a stream reader, split on blank lines, and parse the JSON after `data:`.
-
-## Failure modes
-
-**Calling from client code.** `ai` is server-only. Importing it into a component or calling it outside a `createServerFn` handler fails the build or has no request context to act on.
-
-**Spelling a model id.** `model` is copied from `ai_list_models`, never written from memory. An id outside the catalog fails the save of the action, so the app cannot be published with it.
-
-**No credits left.** `ai.generate` and `ai.stream` throw an `AiError` whose `status` is `402` when the workspace has no AI credits. Show its message to the user; the workspace owner tops the credits up in Softr. Any other refusal carries its status and reason the same way.
-
-**Trusting `json` without checking it.** A model may stray from the schema; `json` is then `null`, or a shape close to the one asked. Validate it with `zod` before writing it to a record, and keep `text` as the fallback the user can read.
-
-**Reading a streamed body with `res.json()`.** The body of `ai.stream` is an event stream, not one JSON document. Return `res.body` in a `Response` or read it with a stream reader.
-
-**Asking for the user's API key.** An AI feature of the app's own needs none. Only when the user asks to run the app on their own provider account does the call go through a connected integration — load the `integrations` sub-skill then.