@fugood/buttress-server 2.25.1-beta.1 → 2.25.1-beta.3

package/README.md

@@ -33,6 +33,11 @@ variant packages plus onnxruntime, sharp, and oxc-transform prebuilds — into a
 both). Override detection with
 `--ggml-variant=default|cuda|vulkan|snapdragon|all`.
 
+Installs and upgrades are transactional: the executable, the loose assets and
+every native package are downloaded into a staging directory and validated
+before any live path is replaced, and a failure part-way (or during the
+replacement itself) leaves the previously installed version runnable.
+
 Build the distribution locally from this package:
 
 ```bash
@@ -278,6 +283,8 @@ Loads a GGUF LLM. Runtime keys above can be overridden per-generator under `[gen
 | `n_ctx`                                                                       | number           | Context window. Auto-capped at the model's training context.         |
 | `n_gpu_layers`                                                                | number\|`"auto"` | Layers offloaded to GPU (default `"auto"`)                           |
 | `n_batch`                                                                     | number           | Prompt batch size (default `512`)                                    |
+| `embedding`                                                                   | boolean          | Enable llama.cpp embedding mode for a dedicated embedding model (default `false`) |
+| `pooling_type`                                                                | string           | Optional embedding pooling override such as `mean`                   |
 | `n_ubatch`, `n_threads`, `n_parallel`, `n_cpu_moe`                            | number           | Same semantics as the `[runtime]` defaults                           |
 | `flash_attn_type`, `cache_type_k`, `cache_type_v`, `kv_unified`, `swa_full`, `ctx_shift`, `state_cache_budget_mb`, `state_cache_max_checkpoints`, `use_mmap`, `use_mlock`, `no_extra_bufts`, `cpu_mask`, `cpu_strict`, `devices` | various | Per-model overrides for the `[runtime]` defaults |
 
@@ -572,7 +579,7 @@ dir = "./functions"           # relative paths resolve against this config file
 
 On startup the server creates the directory if needed and writes `buttress-functions.d.ts` (ambient types, refreshed every start), plus a `tsconfig.json` and a commented `_example.ts` when the directory holds no functions yet.
 
-Ready-to-copy examples — a no-prerequisite starter, LLM summarization, ffmpeg + STT transcription, TTS with a downloadable result, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
+Ready-to-copy examples — a no-prerequisite starter, LLM summarization, sqlite-vec RAG, ffmpeg + STT transcription, TTS with a downloadable result, and a custom auth gate — live in [`config/function-samples/`](config/function-samples/).
 
 ### Writing a function
 
@@ -605,6 +612,9 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | -------------- | ------------ |
 | `spawn(cmd, args?, opts?)` | Run a child process; resolves `{ code, signal, stdout, stderr, truncated }`. A non-zero exit resolves — check `code`. Every child is killed when the call ends. |
 | `buttress.completion({ model?, messages, max_tokens?, onToken?, … })` | Run a chat completion on this server's LLM generator. `messages` go through the model's chat template; thinking is off unless you pass `enable_thinking: true` (which fills `reasoning_content`). Other keys reach the backend verbatim. |
+| `buttress.embedding({ model?, text, embd_normalize? })` | Embed text with a configured `ggml-llm` generator whose model has `embedding = true`; returns `{ embedding: number[] }`. |
+| `buttress.tokenize({ model?, text, params? })` | Tokenize with a configured GGML or MLX LLM → `{ tokens: number[], … }`. |
+| `buttress.detokenize({ model?, tokens })` | Convert token ids back into text with the same model. |
 | `buttress.transcribe({ model?, filePath \| audioData, options? })` | Transcribe audio with this server's STT generator. |
 | `buttress.synthesize({ model?, text, options? })` | Synthesize speech with this server's TTS generator (`onnx-tts`); the WAV lands in `tempDir` → `{ path, sampling_rate, channels }`. |
 | `emit(event, data)` | Progress event; delivered to SSE callers, ignored otherwise. |
@@ -614,7 +624,7 @@ export default async function ({ path }: { path: string }, context: ButtressFunc
 | `log`, `fetch`, `env`, `config`, `dir` | Prefixed logging, host `fetch`, `process.env`, the `[functions.config]` table, the functions directory. |
 | `libs` | `_`/`lodash`, `moment`, `math`/`mathjs`, `voca`, `chroma`, `json5`, `qs`, `bytes`, `ms`, `nanoid`, `md5`. |
 
-Functions may `import` Node builtins (`node:fs/promises`, …) and sibling files inside the functions directory. Package imports are not supported.
+Functions may `import` Node builtins (`node:fs/promises`, …), sibling files inside the functions directory, and the two provided database packages `sqlite3` and `sqlite-vec`. Other package imports are rejected. `sqlite-vec` supports macOS and Linux on x64/arm64, plus Windows x64; its upstream package does not ship a Windows arm64 extension, so the standalone Windows arm64 build does not provide either SQLite import.
 
 Edits are picked up on the next call — the server re-transpiles when a file in the function's module graph changes, so no restart is needed. A file that fails to load is logged and skipped; the rest keep working.
 

package/config/function-samples/README.md

@@ -11,6 +11,7 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 |------|-------|-------|
 | `host-info.ts` | The simplest possible function: a node builtin + `context.libs` | nothing |
 | `summarize-text.ts` | Calling this server's own LLM (`context.buttress.completion`) | an LLM `[[generators]]` entry |
+| `simple-rag.ts` | Token chunking, embeddings, `sqlite3` + `sqlite-vec` retrieval, then completion | a chat LLM + a GGML embedding `[[generators]]` entry (below) |
 | `transcribe-media.ts` | `context.spawn` (ffmpeg), the scratch dir, SSE progress, STT | `ffmpeg` on PATH + an STT `[[generators]]` entry |
 | `text-to-speech.ts` | TTS (`context.buttress.synthesize`) + downloadable output (`context.fileUrl`) | an `onnx-tts` `[[generators]]` entry |
 | `_auth.ts` | Custom auth: keep workspace tokens working, add static API keys | see the file header |
@@ -18,6 +19,38 @@ needed. On first start the server scaffolds `buttress-functions.d.ts` and a
 `_auth.ts` is not a function: copying it changes how every `/functions` endpoint
 authenticates callers. Read its header before copying it.
 
+`simple-rag.ts` needs a dedicated embedding model. Keep your chat generator as
+the first LLM (or pass its `repo_id` as `chatModel`) and add, for example:
+
+```toml
+[[generators]]
+type = "ggml-llm"
+[generators.model]
+repo_id = "nomic-ai/nomic-embed-text-v1.5-GGUF"
+filename = "nomic-embed-text-v1.5.Q8_0.gguf"
+embedding = true
+pooling_type = "mean"
+n_ctx = 2048
+```
+
+Then call it with `question`, `documents`, and
+`embeddingModel: "nomic-ai/nomic-embed-text-v1.5-GGUF"`. SQLite defaults to an
+in-memory index:
+
+```json
+{ "databasePath": ":memory:" }
+```
+
+For a file-backed database, pass an absolute path or one relative to the
+configured functions directory (missing parent directories are created):
+
+```json
+{ "databasePath": "./data/simple-rag.sqlite" }
+```
+
+The sample rebuilds `chunks` on each call so both modes behave identically; a
+file retains the latest index after the database closes.
+
 Quick test after copying (on a bound server pass a workspace token, or run
 unbound with `allow_unauthenticated = true`):
 

package/config/function-samples/simple-rag.ts

@@ -0,0 +1,231 @@
+import { mkdir } from 'node:fs/promises'
+import path from 'node:path'
+
+import sqlite3 from 'sqlite3'
+import * as sqliteVec from 'sqlite-vec'
+
+type Input = {
+  question: string
+  documents: string[]
+  embeddingModel: string
+  chatModel?: string
+  databasePath?: string
+  chunkTokens?: number
+  topK?: number
+}
+
+type Database = InstanceType<typeof sqlite3.Database>
+type Match = { text: string; distance: number }
+
+export const meta: ButtressFunctionMeta = {
+  description: 'Answer a question from supplied documents with sqlite-vec retrieval',
+  parameters: {
+    type: 'object',
+    properties: {
+      question: { type: 'string', description: 'Question to answer' },
+      documents: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Source texts to chunk and search',
+      },
+      embeddingModel: {
+        type: 'string',
+        description: 'repo_id of a configured GGML generator with embedding = true',
+      },
+      chatModel: {
+        type: 'string',
+        description: 'Optional repo_id of the generator that writes the answer',
+      },
+      databasePath: {
+        type: 'string',
+        default: ':memory:',
+        description:
+          'Use :memory: for an ephemeral index or a SQLite file path; relative paths resolve from the functions directory',
+      },
+      chunkTokens: { type: 'integer', default: 256, minimum: 32, maximum: 1024 },
+      topK: { type: 'integer', default: 3, minimum: 1, maximum: 10 },
+    },
+    required: ['question', 'documents', 'embeddingModel'],
+  },
+  timeout: '10m',
+}
+
+const resolveDatabasePath = async (
+  requestedPath: string | undefined,
+  functionsDirectory: string,
+): Promise<string> => {
+  const databasePath = requestedPath?.trim() || ':memory:'
+  if (databasePath === ':memory:') return databasePath
+
+  const resolvedPath = path.isAbsolute(databasePath)
+    ? databasePath
+    : path.resolve(functionsDirectory, databasePath)
+  await mkdir(path.dirname(resolvedPath), { recursive: true })
+  return resolvedPath
+}
+
+const openDatabase = (databasePath: string): Promise<Database> =>
+  new Promise((resolve, reject) => {
+    const database = new sqlite3.Database(databasePath, (error) => {
+      if (error) reject(error)
+      else resolve(database)
+    })
+  })
+
+const loadExtension = (database: Database, extension: string): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.loadExtension(extension, (error) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const run = (database: Database, sql: string, ...params: unknown[]): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.run(sql, ...params, (error: Error | null) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const all = <T>(database: Database, sql: string, ...params: unknown[]): Promise<T[]> =>
+  new Promise((resolve, reject) => {
+    database.all<T>(sql, ...params, (error: Error | null, rows: T[]) => {
+      if (error) reject(error)
+      else resolve(rows)
+    })
+  })
+
+const close = (database: Database): Promise<void> =>
+  new Promise((resolve, reject) => {
+    database.close((error) => {
+      if (error) reject(error)
+      else resolve()
+    })
+  })
+
+const vectorBlob = (values: number[]): Buffer => {
+  const vector = Float32Array.from(values)
+  return Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength)
+}
+
+const clampInteger = (value: unknown, fallback: number, min: number, max: number): number => {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? Math.min(max, Math.max(min, Math.floor(parsed))) : fallback
+}
+
+export default async function (
+  {
+    question,
+    documents,
+    embeddingModel,
+    chatModel,
+    databasePath,
+    chunkTokens = 256,
+    topK = 3,
+  }: Input,
+  context: ButtressFunctionContext,
+) {
+  if (!question?.trim()) throw new Error('question is required')
+  if (!Array.isArray(documents) || documents.length === 0) {
+    throw new Error('documents must contain at least one source text')
+  }
+
+  const chunkSize = clampInteger(chunkTokens, 256, 32, 1024)
+  const limit = clampInteger(topK, 3, 1, 10)
+  const chunks: string[] = []
+
+  context.emit('progress', { stage: 'chunking', documents: documents.length })
+  for (const document of documents) {
+    const { tokens } = await context.buttress.tokenize({
+      model: embeddingModel,
+      text: String(document),
+    })
+    for (let offset = 0; offset < tokens.length; offset += chunkSize) {
+      const text = await context.buttress.detokenize({
+        model: embeddingModel,
+        tokens: tokens.slice(offset, offset + chunkSize),
+      })
+      if (text.trim()) chunks.push(text)
+    }
+  }
+  if (chunks.length === 0) throw new Error('documents produced no searchable text')
+
+  context.emit('progress', { stage: 'embedding', chunks: chunks.length })
+  const embedded: { text: string; embedding: number[] }[] = []
+  for (const text of chunks) {
+    const { embedding } = await context.buttress.embedding({ model: embeddingModel, text })
+    if (embedding.length === 0) throw new Error('embedding model returned an empty vector')
+    if (embedded.length > 0 && embedding.length !== embedded[0].embedding.length) {
+      throw new Error('embedding model returned vectors with inconsistent dimensions')
+    }
+    embedded.push({ text, embedding })
+  }
+
+  const { embedding: questionEmbedding } = await context.buttress.embedding({
+    model: embeddingModel,
+    text: question,
+  })
+  const dimensions = embedded[0].embedding.length
+  if (questionEmbedding.length !== dimensions) {
+    throw new Error('question embedding dimension does not match the document vectors')
+  }
+
+  const resolvedDatabasePath = await resolveDatabasePath(databasePath, context.dir)
+  const database = await openDatabase(resolvedDatabasePath)
+  let matches: Match[]
+  try {
+    // sqlite-vec's convenience `load()` is synchronous, while node-sqlite3's
+    // loadExtension is callback-based. Awaiting the path explicitly avoids a
+    // race with the first vec0 statement.
+    await loadExtension(database, sqliteVec.getLoadablePath())
+    // Rebuild on every call so memory and file-backed usage have identical,
+    // deterministic behavior. The file retains the latest index after close.
+    await run(database, 'DROP TABLE IF EXISTS chunks')
+    await run(
+      database,
+      `CREATE VIRTUAL TABLE chunks USING vec0(embedding float[${dimensions}], text TEXT)`,
+    )
+    for (const chunk of embedded) {
+      await run(
+        database,
+        'INSERT INTO chunks(embedding, text) VALUES (?, ?)',
+        vectorBlob(chunk.embedding),
+        chunk.text,
+      )
+    }
+    matches = await all<Match>(
+      database,
+      `SELECT text, distance
+         FROM chunks
+        WHERE embedding MATCH ?
+        ORDER BY distance
+        LIMIT ${limit}`,
+      vectorBlob(questionEmbedding),
+    )
+  } finally {
+    await close(database)
+  }
+
+  context.emit('progress', { stage: 'answering', matches: matches.length })
+  const sources = matches.map((match, index) => `[${index + 1}] ${match.text}`).join('\n\n')
+  const answer = await context.buttress.completion({
+    model: chatModel,
+    messages: [
+      {
+        role: 'system',
+        content:
+          'Answer only from the supplied sources. If they do not contain the answer, say so.',
+      },
+      { role: 'user', content: `Sources:\n${sources}\n\nQuestion: ${question}` },
+    ],
+    max_tokens: 512,
+  })
+
+  return {
+    answer: answer.content,
+    matches,
+    chunks: chunks.length,
+    usage: answer.usage,
+  }
+}

package/lib/functions/loader.d.ts

@@ -12,6 +12,8 @@
  * and `JSON.stringify` work, but `instanceof` against host constructors does
  * not. Never `instanceof`-check a function's return value.
  */
+/** The deliberately small package surface local functions may import. */
+export declare const SUPPORTED_PACKAGE_IMPORTS: readonly ['sqlite3', 'sqlite-vec'];
 export declare class FunctionImportError extends Error {
     constructor(message: string);
 }
@@ -23,6 +25,9 @@ export declare const createSandboxGlobals: (extra?: Record<string, any>) => Reco
 export type ResolvedSpecifier = {
     kind: 'builtin';
     id: string;
+} | {
+    kind: 'package';
+    id: string;
 } | {
     kind: 'file';
     path: string;

package/lib/functions/templates.d.ts

@@ -9,6 +9,6 @@
 export declare const TYPES_FILE_NAME = "buttress-functions.d.ts";
 export declare const TSCONFIG_FILE_NAME = "tsconfig.json";
 export declare const EXAMPLE_FILE_NAME = "_example.ts";
-export declare const TYPES_TEMPLATE = "// Generated by @fugood/buttress-server \u2014 do not edit.\n// Rewritten on every server start to match the running version.\n//\n// Local functions are EXPERIMENTAL: this contract may change between\n// releases \u2014 after a server upgrade, re-read this file for the current shape.\n\n/** Result of `context.spawn(...)`. */\ntype ButtressSpawnResult = {\n  /** Exit code, or null when the process was killed by a signal. */\n  code: number | null\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n  /** True when output hit `maxBuffer` and capture stopped early. */\n  truncated: boolean\n}\n\ntype ButtressSpawnOptions = {\n  cwd?: string\n  /** Merged over the server's own environment. */\n  env?: Record<string, string | undefined>\n  /** Written to stdin, which is then closed. */\n  input?: string | Uint8Array\n  /** 'utf8' (default) yields strings; 'buffer' yields Buffers. */\n  encoding?: 'utf8' | 'buffer'\n  /** Per-stream capture cap in bytes (default 8MB). */\n  maxBuffer?: number\n  onStdout?: (chunk: Buffer) => void\n  onStderr?: (chunk: Buffer) => void\n}\n\ntype ButtressCompletionResult = {\n  content: string\n  reasoning_content?: string\n  tool_calls?: any[]\n  interrupted?: boolean\n  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }\n}\n\ntype ButtressFunctionContext = {\n  /**\n   * Run a child process. Resolves once it exits \u2014 a non-zero `code` is a\n   * normal resolution, so check it yourself. Rejects only when the process\n   * cannot be started. Every process a call spawns is killed when the call\n   * ends or times out.\n   */\n  spawn: (\n    command: string,\n    args?: string[],\n    options?: ButtressSpawnOptions,\n  ) => Promise<ButtressSpawnResult>\n\n  buttress: {\n    /**\n     * Run a chat completion on this server's LLM generator. `messages` are\n     * rendered with the model's own chat template, and thinking is off unless\n     * you pass `enable_thinking: true` (which fills `reasoning_content`).\n     */\n    completion: (options: {\n      /** Configured `[[generators]]` model; defaults to the first one. */\n      model?: string\n      messages?: { role: string; content: any }[]\n      prompt?: string\n      /** Cap on generated tokens. Unbounded when omitted. */\n      max_tokens?: number\n      temperature?: number\n      /** Emit the model's reasoning into `reasoning_content` (default false). */\n      enable_thinking?: boolean\n      /** Called for every streamed token event. */\n      onToken?: (event: { token?: string; content?: string; [key: string]: any }) => void\n      /** Any other backend sampling option (`top_p`, `stop`, `tools`, \u2026). */\n      [param: string]: any\n    }) => Promise<ButtressCompletionResult>\n\n    /** Transcribe audio with this server's STT generator. */\n    transcribe: (options: {\n      /** Must match a configured STT model (`repo_id` or `repo_id:filename`). */\n      model?: string\n      filePath?: string\n      audioData?: Uint8Array | Buffer\n      options?: Record<string, any>\n    }) => Promise<any>\n\n    /**\n     * Synthesize speech with this server's TTS generator (onnx-tts). The WAV\n     * is written into `tempDir`; return `fileUrl(path)` to let callers\n     * download it.\n     */\n    synthesize: (options: {\n      /** Must match a configured TTS model when given. */\n      model?: string\n      text: string\n      /** Backend options; `options.speaker` picks a registered voice. */\n      options?: Record<string, any>\n    }) => Promise<{ path: string; sampling_rate: number; channels: number }>\n  }\n\n  fetch: typeof fetch\n  /** Server-side log, prefixed with the function name. */\n  log: (...args: unknown[]) => void\n  /** Emit a progress event. Delivered only to SSE callers; a no-op otherwise. */\n  emit: (event: string, data?: unknown) => void\n  /** Aborted when the call times out or the caller disconnects. */\n  signal: AbortSignal\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table from the server config. */\n  config: Record<string, any>\n  /** Per-call scratch directory, created on first access. */\n  tempDir: string\n  /**\n   * Download URL path (`/functions/files/...`) for a file inside `tempDir`;\n   * relative input resolves against it. Callers fetch the URL with the same\n   * auth as any function call. Scratch dirs are swept after ~24h.\n   */\n  fileUrl: (target: string) => string\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Helper libraries: _, lodash, moment, math, mathjs, voca, chroma, json5, qs, bytes, ms, nanoid, md5. */\n  libs: Record<string, any>\n}\n\ntype ButtressFunctionMeta = {\n  /** Shown to MCP clients in `tools/list`. */\n  description?: string\n  /** JSON Schema for the input object, passed to MCP verbatim. */\n  parameters?: Record<string, any>\n  /** Deadline for this function: ms, or a duration string like \"10m\". */\n  timeout?: number | string\n}\n\n// --- Custom auth ------------------------------------------------------------\n// Drop an `_auth.ts` into this directory to gate the /functions endpoints\n// with your own logic. It exports the same shape as a function file:\n//\n//   export const meta: ButtressAuthMeta = { mode: 'both' }\n//   export default async function (\n//     request: ButtressAuthRequest,\n//     context: ButtressAuthContext,\n//   ): Promise<ButtressAuthResult> { ... }\n//\n// While an `_auth` file exists but fails to load, every call is rejected.\n\ntype ButtressAuthMeta = {\n  /**\n   * 'both' (default): runs after the built-in workspace auth passes, as an\n   * extra gate. 'override': replaces workspace auth \u2014 this function is the\n   * only authority (a presented workspace token is still verified into\n   * `request.workspaceAuth` so you can choose to honor it).\n   */\n  mode?: 'override' | 'both'\n}\n\ntype ButtressAuthRequest = {\n  method: string\n  path: string\n  /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */\n  name?: string\n  headers: Record<string, string | undefined>\n  query: Record<string, string | undefined>\n  /** Raw bearer token (Authorization header or `?token=`), if any. */\n  token: string | null\n  workspaceAuth: {\n    /** Whether this server is bound to a workspace. */\n    bound: boolean\n    /** Whether the caller presented a valid workspace access token. */\n    authenticated: boolean\n    identity: {\n      workspaceId: string\n      subjectType: 'ws' | 'dev'\n      subjectId: string\n      jti?: string\n      exp: number\n    } | null\n  }\n}\n\ntype ButtressAuthContext = {\n  /** Server-side log, prefixed with \"_auth\". */\n  log: (...args: unknown[]) => void\n  fetch: typeof fetch\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table, same as `context.config` in functions. */\n  config: Record<string, any>\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Same helper libraries functions get. */\n  libs: Record<string, any>\n}\n\n/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */\ntype ButtressAuthResult =\n  | boolean\n  | {\n      ok: boolean\n      /** Response status for a denial, 400-499 (default 403). */\n      status?: number\n      /** Message returned to the caller on denial. */\n      error?: string\n    }\n";
+export declare const TYPES_TEMPLATE = "// Generated by @fugood/buttress-server \u2014 do not edit.\n// Rewritten on every server start to match the running version.\n//\n// Local functions are EXPERIMENTAL: this contract may change between\n// releases \u2014 after a server upgrade, re-read this file for the current shape.\n\n/** Result of `context.spawn(...)`. */\ntype ButtressSpawnResult = {\n  /** Exit code, or null when the process was killed by a signal. */\n  code: number | null\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n  /** True when output hit `maxBuffer` and capture stopped early. */\n  truncated: boolean\n}\n\ntype ButtressSpawnOptions = {\n  cwd?: string\n  /** Merged over the server's own environment. */\n  env?: Record<string, string | undefined>\n  /** Written to stdin, which is then closed. */\n  input?: string | Uint8Array\n  /** 'utf8' (default) yields strings; 'buffer' yields Buffers. */\n  encoding?: 'utf8' | 'buffer'\n  /** Per-stream capture cap in bytes (default 8MB). */\n  maxBuffer?: number\n  onStdout?: (chunk: Buffer) => void\n  onStderr?: (chunk: Buffer) => void\n}\n\ntype ButtressCompletionResult = {\n  content: string\n  reasoning_content?: string\n  tool_calls?: any[]\n  interrupted?: boolean\n  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }\n}\n\ntype ButtressEmbeddingResult = {\n  /** Plain numbers, ready for JSON or conversion into a sqlite-vec float32 BLOB. */\n  embedding: number[]\n}\n\ntype ButtressFunctionContext = {\n  /**\n   * Run a child process. Resolves once it exits \u2014 a non-zero `code` is a\n   * normal resolution, so check it yourself. Rejects only when the process\n   * cannot be started. Every process a call spawns is killed when the call\n   * ends or times out.\n   */\n  spawn: (\n    command: string,\n    args?: string[],\n    options?: ButtressSpawnOptions,\n  ) => Promise<ButtressSpawnResult>\n\n  buttress: {\n    /**\n     * Run a chat completion on this server's LLM generator. `messages` are\n     * rendered with the model's own chat template, and thinking is off unless\n     * you pass `enable_thinking: true` (which fills `reasoning_content`).\n     */\n    completion: (options: {\n      /** Configured `[[generators]]` model; defaults to the first one. */\n      model?: string\n      messages?: { role: string; content: any }[]\n      prompt?: string\n      /** Cap on generated tokens. Unbounded when omitted. */\n      max_tokens?: number\n      temperature?: number\n      /** Emit the model's reasoning into `reasoning_content` (default false). */\n      enable_thinking?: boolean\n      /** Called for every streamed token event. */\n      onToken?: (event: { token?: string; content?: string; [key: string]: any }) => void\n      /** Any other backend sampling option (`top_p`, `stop`, `tools`, \u2026). */\n      [param: string]: any\n    }) => Promise<ButtressCompletionResult>\n\n    /**\n     * Embed text with a GGML generator whose `[generators.model]` table sets\n     * `embedding = true`. The vector is returned as plain numbers.\n     */\n    embedding: (options: {\n      model?: string\n      text: string\n      /** llama.cpp normalization mode; 2 (L2) is the native default. */\n      embd_normalize?: number\n    }) => Promise<ButtressEmbeddingResult>\n\n    /** Tokenize text with a configured GGML or MLX generator. */\n    tokenize: (options: {\n      model?: string\n      text: string\n      params?: Record<string, any>\n    }) => Promise<Record<string, any> & { tokens: number[] }>\n\n    /** Turn model token ids back into text. */\n    detokenize: (options: { model?: string; tokens: number[] }) => Promise<string>\n\n    /** Transcribe audio with this server's STT generator. */\n    transcribe: (options: {\n      /** Must match a configured STT model (`repo_id` or `repo_id:filename`). */\n      model?: string\n      filePath?: string\n      audioData?: Uint8Array | Buffer\n      options?: Record<string, any>\n    }) => Promise<any>\n\n    /**\n     * Synthesize speech with this server's TTS generator (onnx-tts). The WAV\n     * is written into `tempDir`; return `fileUrl(path)` to let callers\n     * download it.\n     */\n    synthesize: (options: {\n      /** Must match a configured TTS model when given. */\n      model?: string\n      text: string\n      /** Backend options; `options.speaker` picks a registered voice. */\n      options?: Record<string, any>\n    }) => Promise<{ path: string; sampling_rate: number; channels: number }>\n  }\n\n  fetch: typeof fetch\n  /** Server-side log, prefixed with the function name. */\n  log: (...args: unknown[]) => void\n  /** Emit a progress event. Delivered only to SSE callers; a no-op otherwise. */\n  emit: (event: string, data?: unknown) => void\n  /** Aborted when the call times out or the caller disconnects. */\n  signal: AbortSignal\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table from the server config. */\n  config: Record<string, any>\n  /** Per-call scratch directory, created on first access. */\n  tempDir: string\n  /**\n   * Download URL path (`/functions/files/...`) for a file inside `tempDir`;\n   * relative input resolves against it. Callers fetch the URL with the same\n   * auth as any function call. Scratch dirs are swept after ~24h.\n   */\n  fileUrl: (target: string) => string\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Helper libraries: _, lodash, moment, math, mathjs, voca, chroma, json5, qs, bytes, ms, nanoid, md5. */\n  libs: Record<string, any>\n}\n\ntype ButtressFunctionMeta = {\n  /** Shown to MCP clients in `tools/list`. */\n  description?: string\n  /** JSON Schema for the input object, passed to MCP verbatim. */\n  parameters?: Record<string, any>\n  /** Deadline for this function: ms, or a duration string like \"10m\". */\n  timeout?: number | string\n}\n\n// --- Custom auth ------------------------------------------------------------\n// Drop an `_auth.ts` into this directory to gate the /functions endpoints\n// with your own logic. It exports the same shape as a function file:\n//\n//   export const meta: ButtressAuthMeta = { mode: 'both' }\n//   export default async function (\n//     request: ButtressAuthRequest,\n//     context: ButtressAuthContext,\n//   ): Promise<ButtressAuthResult> { ... }\n//\n// While an `_auth` file exists but fails to load, every call is rejected.\n\ntype ButtressAuthMeta = {\n  /**\n   * 'both' (default): runs after the built-in workspace auth passes, as an\n   * extra gate. 'override': replaces workspace auth \u2014 this function is the\n   * only authority (a presented workspace token is still verified into\n   * `request.workspaceAuth` so you can choose to honor it).\n   */\n  mode?: 'override' | 'both'\n}\n\ntype ButtressAuthRequest = {\n  method: string\n  path: string\n  /** Function name for `GET`/`POST /functions/<name>`; undefined for list and MCP. */\n  name?: string\n  headers: Record<string, string | undefined>\n  query: Record<string, string | undefined>\n  /** Raw bearer token (Authorization header or `?token=`), if any. */\n  token: string | null\n  workspaceAuth: {\n    /** Whether this server is bound to a workspace. */\n    bound: boolean\n    /** Whether the caller presented a valid workspace access token. */\n    authenticated: boolean\n    identity: {\n      workspaceId: string\n      subjectType: 'ws' | 'dev'\n      subjectId: string\n      jti?: string\n      exp: number\n    } | null\n  }\n}\n\ntype ButtressAuthContext = {\n  /** Server-side log, prefixed with \"_auth\". */\n  log: (...args: unknown[]) => void\n  fetch: typeof fetch\n  env: Record<string, string | undefined>\n  /** The `[functions.config]` table, same as `context.config` in functions. */\n  config: Record<string, any>\n  /** Absolute path of this functions directory. */\n  dir: string\n  /** Same helper libraries functions get. */\n  libs: Record<string, any>\n}\n\n/** Only `true` (or `{ ok: true }`) allows the request; anything else denies. */\ntype ButtressAuthResult =\n  | boolean\n  | {\n      ok: boolean\n      /** Response status for a denial, 400-499 (default 403). */\n      status?: number\n      /** Message returned to the caller on denial. */\n      error?: string\n    }\n\n// The only non-builtin packages the local-function loader accepts. These\n// declarations keep editor support working when this directory is outside the\n// server package's own node_modules resolution tree.\ndeclare module 'sqlite3' {\n  type SqliteCallback = (error: Error | null) => void\n\n  class Database {\n    constructor(filename: string, callback?: SqliteCallback)\n    run(sql: string, ...params: any[]): this\n    all<T = Record<string, any>>(\n      sql: string,\n      ...params: [...any[], (error: Error | null, rows: T[]) => void]\n    ): this\n    exec(sql: string, callback?: SqliteCallback): this\n    loadExtension(filename: string, callback?: SqliteCallback): this\n    close(callback?: SqliteCallback): void\n  }\n\n  const sqlite3: { Database: typeof Database }\n  export { Database }\n  export default sqlite3\n}\n\ndeclare module 'sqlite-vec' {\n  export function getLoadablePath(): string\n  export function load(database: { loadExtension(path: string): unknown }): void\n}\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  // Editor support for Buttress local functions.\n  // Install @types/node here for typings on \"node:*\" imports.\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"Bundler\",\n    \"lib\": [\"ES2023\"],\n    \"strict\": true,\n    \"noEmit\": true,\n    \"allowJs\": true,\n    \"skipLibCheck\": true\n  },\n  \"include\": [\"**/*.ts\", \"**/*.js\"]\n}\n";
 export declare const EXAMPLE_TEMPLATE = "// Example Buttress local function.\n//\n// Rename (or copy) this file to expose it: files starting with \"_\" are\n// ignored. The tool name is the file name \u2014 \"video-duration.ts\" becomes the\n// tool \"video-duration\", callable over MCP, at POST /functions/video-duration\n// with a JSON body, and at GET /functions/video-duration?path=... with the\n// input in the query string.\n\nexport const meta: ButtressFunctionMeta = {\n  description: 'Report the duration of a video file using ffprobe',\n  parameters: {\n    type: 'object',\n    properties: {\n      path: { type: 'string', description: 'Absolute path to a video file' },\n    },\n    required: ['path'],\n  },\n  timeout: '2m',\n}\n\nexport default async function (\n  { path }: { path: string },\n  context: ButtressFunctionContext,\n): Promise<{ seconds: number }> {\n  const { code, stdout, stderr } = await context.spawn('ffprobe', [\n    '-v',\n    'error',\n    '-show_entries',\n    'format=duration',\n    '-of',\n    'default=noprint_wrappers=1:nokey=1',\n    path,\n  ])\n\n  if (code !== 0) throw new Error(`ffprobe failed (${code}): ${stderr}`)\n\n  return { seconds: Number(String(stdout).trim()) }\n}\n";

package/lib/functions/types.d.ts

@@ -60,6 +60,28 @@ export type CompletionResult = {
         total_tokens: number;
     };
 };
+export type EmbeddingOptions = {
+    model?: string;
+    text: string;
+    /** llama.cpp normalization mode; 2 (L2) is the native default. */
+    embd_normalize?: number;
+};
+export type EmbeddingResult = {
+    /** Plain numbers (not a cross-realm Float32Array), ready for JSON or sqlite-vec. */
+    embedding: number[];
+};
+export type TokenizeOptions = {
+    model?: string;
+    text: string;
+    params?: Record<string, any>;
+};
+export type TokenizeResult = Record<string, any> & {
+    tokens: number[];
+};
+export type DetokenizeOptions = {
+    model?: string;
+    tokens: number[];
+};
 export type TranscribeOptions = {
     model?: string;
     /** Absolute (or functions-dir relative) path to an audio file. */
@@ -85,6 +107,10 @@ export type FunctionContext = {
     spawn: (command: string, args?: string[], options?: SpawnOptions) => Promise<SpawnResult>;
     buttress: {
         completion: (options: CompletionOptions) => Promise<CompletionResult>;
+        /** GGML only; the selected generator must set `model.embedding = true`. */
+        embedding: (options: EmbeddingOptions) => Promise<EmbeddingResult>;
+        tokenize: (options: TokenizeOptions) => Promise<TokenizeResult>;
+        detokenize: (options: DetokenizeOptions) => Promise<string>;
         transcribe: (options: TranscribeOptions) => Promise<any>;
         synthesize: (options: SynthesizeOptions) => Promise<SynthesizeResult>;
     };