DocsAI

AI

An optional language model, Claude or one on your own machine, for chat, drafting and agents.

AI is a plugin, off until a superuser sets up a model. Every feature that uses it works without one, and a model’s output is always a suggestion that a person accepts or rejects. To add it:

sluurp plugin add ai

Or install it from the admin’s Marketplace. Without the plugin, Sluurp has no model: ai() answers null, and search by meaning compares the words themselves.

Features include:

  • Claude, OpenAI, Mistral, Gemini, Groq, OpenRouter, or any OpenAI-compatible server on your own machine
  • Chat and streaming in the browser, with a daily limit per person
  • The app’s own server functions as the model’s tools, run as the person asking
  • Answers as JSON, shaped by a type or checked by a schema
  • Your own model, from any plugin with a model.ts

Set up a model

In the admin, under AI, pick where the model runs:

TabWhat you fill in
ClaudeA key. By default, the model is claude-opus-5
OpenAI, Mistral, Google Gemini, Groq, OpenRouterA key, and the model as the service names it (each tab starts with a sensible one)
Your own serverThe address of any OpenAI-compatible server, such as http://localhost:11434/v1 for Ollama, LM Studio or llama.cpp, and the model’s name

You can also set:

  • Effort: how hard Claude thinks, low, medium (the default) or high.
  • Questions per person per day: a limit for the chat assistant. 0 means no limit, and administrators aren’t counted.

The key is stored on the server and never sent back by the API.

With a local model, no data leaves your machine. The plugin is allowed to reach localhost: its plugin.json names that host, and installing the plugin allows it. Other plugins can name the private hosts they need the same way.

Chat in the browser

Import the plugin where you use it:

app.ts
import "plugin:ai";

const { text } = await sluurp.ai.chat([{ role: "user", text: "Summarise this week's orders" }]);

// Streaming:
await sluurp.ai.stream(turns, { onText: (piece, all) => (out.textContent = all) });

Both take { system, signal }; aborting through the signal keeps what arrived so far. When a person reaches their daily limit, the answer says so instead of throwing.

Tools: the app’s server functions

An assistant can be given the app’s own "use server" functions as its tools. Pass the functions themselves:

app.tsx
import { assistant } from "plugin:ai";

/** Books a room for a day, if it is free. */
export async function bookRoom(room: string, day: Date) {
  "use server";
  // …
}

const ai = assistant({ client: sluurp, system, load, save, words, tools: [bookRoom] });
ai.ask("Book the small room for Friday");
  • The model learns what each function does from its doc comment, and what it takes from its parameters’ types.
  • The server runs the calls the model makes, as the person asking, so every collection rule still applies. The browser only says which functions may be used.
  • When the model sends an argument that doesn’t fit, the function’s type check answers with what’s wrong, and the model can try again.
  • With tools, the answer arrives whole once the model is done, not as it’s written.

In server code

ai(system, prompt, schema) returns JSON matching the schema, or null when no model is set up:

functions/tag-post.ts
const tags = await ai(
  "You tag blog posts.",
  post.body,
  { type: "object", properties: { tags: { type: "array", items: { type: "string" } } } },
);
if (tags) await collection("posts").update(post.id, tags);

Answers shaped by a type

To shape the answer, give ai a type instead of a schema. The schema is made from the type when the file is served:

functions/tag-post.ts
interface Tags { tags: string[]; urgent: boolean }

const got = await ai<Tags>("You tag blog posts.", post.body);

The model’s answer is read leniently: JSON in a code fence, with words around it, or with a trailing comma is still read. It’s then fitted to the type where the meaning is plain, so "3" becomes a number and "true" a boolean. If it still doesn’t fit, the model is told what’s wrong and asked once more.

Answers checked by a schema

You can also give ai a Standard Schema, such as one from zod, Valibot, ArkType or schemaOf<T>(). The model is given the schema’s JSON Schema, and its answer is checked by the schema itself, refinements included. An answer that doesn’t fit is sent back once with what’s wrong. If the second answer doesn’t fit either, ai throws an error.

functions/tag-post.ts
import { z } from "zod";

const Tags = z.object({ tags: z.array(z.string()).max(5), urgent: z.boolean() });

const got = await ai("You tag posts.", post.body, Tags);

The schema has to be able to give its JSON Schema, as the Standard JSON Schema interface describes. Zod 4.2 or later and schemaOf<T>() can do this.

For tool use over several turns, see Agents.

Where Sluurp uses it

Pages shows its AI tools, and plugin:ai provides an assistant for any app, only when a model is set up. The admin’s agent, a button in every screen’s header, comes with the plugin too.

Bring your own model

Sluurp asks the installed plugin that has a model.ts file. The AI plugin is one, and you can write your own:

plugins/my-model/model.ts
export default async (ctx) => {
  switch (ctx.method) {
    case "READY": return true;                        // whether a model is set up
    case "JSON": return askForJson(ctx.body);          // { system, prompt, schema } → JSON
    case "STEP": return oneTurn(ctx.body);             // an agent's turn: { messages, text, calls }
    case "EMBED": return null;                         // { texts, query } → { kind, vectors }, or null
  }
};

View as Markdown