@shoalrun/cli 0.1.0-alpha.16 → 0.1.0-alpha.17

package/agent-docs/start.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.
 
@@ -36,7 +36,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.14
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.16
 npx --no-install shoalrun init .
 ```
 

package/agent-docs/start.sections/add-the-page-to-navigation.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/build-and-check-both-outputs.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/build-this-site.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/check-writing-style.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/create-a-page.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/make-it-yours.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/migrating-from-github-packages.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/prerequisites.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/related-reading.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 

package/agent-docs/start.sections/start-your-own-project.md

@@ -16,7 +16,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Get started > Getting started
 
-**Updated: 2026-10-30.**
+**Updated: 2026-11-04.**
 
 Parent page: [Full Markdown page](/start.md)
 
@@ -38,7 +38,7 @@ Install an exact version of the alpha and initialize the minimal starter:
 mkdir my-docs
 cd my-docs
 npm init -y
-npm install --save-exact @shoalrun/cli@0.1.0-alpha.14
+npm install --save-exact @shoalrun/cli@0.1.0-alpha.16
 npx --no-install shoalrun init .
 ```
 

package/dist/ai-directory.d.ts

@@ -0,0 +1 @@
+export declare function aiDirectory(directory: string): Promise<string>;

package/dist/ai-directory.js

@@ -0,0 +1,12 @@
+import { mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+export async function aiDirectory(directory) {
+    const root = path.resolve(directory);
+    const target = path.join(root, 'ai');
+    await mkdir(target, { recursive: true });
+    const real = await realpath(root);
+    const inside = await realpath(target);
+    if (inside !== real && !inside.startsWith(real + path.sep))
+        throw new Error('The ai directory leaves the site directory');
+    return target;
+}

package/dist/answer-cards.js

@@ -2,7 +2,7 @@ import { readFile, realpath, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { parse } from 'yaml';
 import { cacheable, normalizeQuestion } from './answer-cache.js';
-import { aiDirectory } from './index-build.js';
+import { aiDirectory } from './ai-directory.js';
 export const encodeVector = (vector) => Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength).toString('base64');
 export function decodeVector(value) {
     const bytes = Buffer.from(value, 'base64');

package/dist/ask-function.d.ts

@@ -1,19 +1,5 @@
-import type { IncomingMessage, ServerResponse } from 'node:http';
-export type FunctionRuntime = {
-    schemaVersion: 1;
-    settings: Record<string, unknown>;
-    variant?: {
-        channel: string;
-        version: string;
-        language: string;
-    };
-    hosts?: string[];
-    callerHeader?: string;
-    maxRequestsPerMinute?: number;
-};
-export type AskFunction = (request: Request) => Promise<Response>;
-export declare function createHostedSearchFunction(directory: string, env?: NodeJS.ProcessEnv): Promise<AskFunction>;
+import { type AskFunction } from './function-runtime.js';
+export { nodeAdapter } from './function-runtime.js';
+export type { FunctionRuntime, AskFunction } from './function-runtime.js';
+export { createHostedSearchFunction } from './search-function.js';
 export declare function createAskFunction(directory: string, env?: NodeJS.ProcessEnv, send?: typeof fetch): Promise<AskFunction>;
-export declare function nodeAdapter(load: () => Promise<AskFunction>, limits?: {
-    bodyBytes: number;
-}): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/ask-function.js

@@ -1,40 +1,23 @@
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
-import { DailyBudget, SharedRateLimit, adaptiveChallenge } from './budget.js';
+import { SharedRateLimit, adaptiveChallenge } from './budget.js';
 import { askQuestion } from './ask.js';
 import { clientKeyFromHeader, createAskHandler } from './ask-handler.js';
-import { prepareAsk } from './ask-setup.js';
+import { prepareAskRuntime } from './ask-runtime.js';
+import { allowedHosts } from './function-runtime.js';
+export { nodeAdapter } from './function-runtime.js';
+// Keep the previous deep import available without making Search import Ask.
+export { createHostedSearchFunction } from './search-function.js';
 import { validateChat } from './chat-config.js';
 import { validateReaderFilters } from './reader-filters.js';
 import { createSession, turnstileVerifier } from './turnstile.js';
-import { envBudgetStore, envRedis } from './budget-store.js';
-import { createSearchHandler } from './search-handler.js';
-import { validateSearch } from './search-config.js';
+import { envRedis } from './budget-store.js';
 import { pausedKey } from './chat-pause.js';
 import { deleteKvLogRecord, kvLogSink } from './ask-log-kv.js';
-function allowedHosts(runtime, env) {
-    return [...new Set([...(runtime.hosts ?? []), env.VERCEL_URL, env.VERCEL_BRANCH_URL, env.VERCEL_PROJECT_PRODUCTION_URL, ...(env.SHOALRUN_ASK_HOSTS?.split(',') ?? [])].map(host => host?.trim().toLowerCase()).filter((host) => Boolean(host)))];
-}
-// Hosted search uses the same private index as chat, with separate limits for embedding spend.
-export async function createHostedSearchFunction(directory, env = process.env) {
-    const runtime = JSON.parse(await readFile(path.join(directory, 'runtime.json'), 'utf8'));
-    if (runtime?.schemaVersion !== 1 || !runtime.settings)
-        throw new Error('runtime.json is not a Shoalrun search function file');
-    const filters = validateReaderFilters(runtime.settings.readerFilters);
-    const chat = validateChat(runtime.settings.chat, filters);
-    if (!chat?.budget?.store)
-        throw new Error('Hosted semantic search needs a shared budget store');
-    const setup = await prepareAsk({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, sharedStore: true, ...(runtime.variant ?? {}) });
-    const store = envBudgetStore(chat.budget.store, env);
-    const { limits } = validateSearch(runtime.settings.search);
-    return createSearchHandler({
-        retriever: setup.options.retriever, embedQuery: setup.options.embedQuery, readerFilters: filters, hosts: allowedHosts(runtime, env),
-        onFallback: reason => console.warn(`Search fallback: ${reason}`),
-        rateLimiter: new SharedRateLimit(store, limits.perCallerPerMinute, Date.now, error => console.error(`Search rate limit: ${error.message}`), 'search-rate'),
-        budget: new DailyBudget(store, { perCaller: limits.perCallerPerDay, perDay: limits.perDay }, Date.now, error => console.error(`Search budget: ${error.message}`), 'search-budget'),
-        clientKey: clientKeyFromHeader(runtime.callerHeader ?? 'x-vercel-forwarded-for')
-    });
-}
+// The answer function for a hosted site. The build writes a directory holding `runtime.json` (the chat and retrieval settings, with no
+// keys) and `site/ai` (the passages and vectors), and this module turns that directory into a Web `Request` to `Response` function. Keys come
+// only from the environment variables the settings name. It refuses to start without a shared budget store, because per-instance counters
+// on a serverless host would not limit anything.
 export async function createAskFunction(directory, env = process.env, send) {
     const runtime = JSON.parse(await readFile(path.join(directory, 'runtime.json'), 'utf8'));
     if (runtime?.schemaVersion !== 1 || !runtime.settings)
@@ -44,7 +27,7 @@ export async function createAskFunction(directory, env = process.env, send) {
         throw new Error('The site config has no chat section');
     if (!chat.budget?.store)
         throw new Error('A hosted chat needs chat.budget with a shared store, so its daily caps hold across server instances');
-    const setup = await prepareAsk({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, cache: true, sharedStore: true, ...(runtime.variant ?? {}) });
+    const setup = await prepareAskRuntime({ siteDirectory: path.join(directory, 'site'), settings: runtime.settings, cache: true, sharedStore: true, ...(runtime.variant ?? {}) });
     for (const note of setup.notes)
         console.error(note);
     if (!setup.budget)
@@ -95,45 +78,3 @@ export async function createAskFunction(directory, env = process.env, send) {
         answer: (question, history, context) => askQuestion({ question, history, ...setup.options, modelAllowed: context.modelAllowed, signal: context.signal, requireCitations: true })
     });
 }
-const failure = (status, message) => new Response(JSON.stringify({ error: message }), { status, headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' } });
-// Vercel's Node runtime calls `(req, res)`. This turns that into a Web request and back. Starting up happens on the first request, and a
-// failed start is tried again on the next one. The reader never sees why it failed; the reason goes to the function log.
-export function nodeAdapter(load, limits = { bodyBytes: 32_768 }) {
-    let ready;
-    const write = async (res, response) => {
-        res.statusCode = response.status;
-        response.headers.forEach((value, name) => { if (name !== 'set-cookie')
-            res.setHeader(name, value); });
-        const cookies = response.headers.getSetCookie();
-        if (cookies.length)
-            res.setHeader('set-cookie', cookies);
-        res.end(Buffer.from(await response.arrayBuffer()));
-    };
-    return async (req, res) => {
-        try {
-            const handler = await (ready ??= load().catch(error => { ready = undefined; throw error; }));
-            const chunks = [];
-            let size = 0;
-            for await (const chunk of req) {
-                size += chunk.length;
-                if (size > limits.bodyBytes) {
-                    await write(res, failure(413, 'The request is too large.'));
-                    return;
-                }
-                chunks.push(chunk);
-            }
-            const headers = new Headers();
-            for (const [name, value] of Object.entries(req.headers))
-                for (const item of Array.isArray(value) ? value : value === undefined ? [] : [value])
-                    headers.append(name, item);
-            const method = req.method ?? 'GET';
-            const request = new Request(`https://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { method, headers, ...(method === 'GET' || method === 'HEAD' ? {} : { body: Buffer.concat(chunks) }) });
-            await write(res, await handler(request));
-        }
-        catch (error) {
-            console.error(`The answer function failed: ${error.message}`);
-            if (!res.headersSent)
-                await write(res, failure(503, 'The chat is unavailable right now.'));
-        }
-    };
-}

package/dist/ask-runtime.d.ts

@@ -0,0 +1,45 @@
+import type { AskOptions } from './ask.js';
+import { type ChatProvider } from './chat.js';
+import { type ReaderSelection } from './reader-filters.js';
+import { DailyBudget, type BudgetStore } from './budget.js';
+export declare function parseReaderView(specs: string[]): ReaderSelection | undefined;
+export type AskSetupInput = {
+    sharedStore?: boolean;
+    siteDirectory: string;
+    configFile?: string;
+    settings?: Record<string, unknown>;
+    model?: string;
+    passages?: number;
+    channel?: string;
+    version?: string;
+    language?: string;
+    noRerank?: boolean;
+    noDirect?: boolean;
+    noEscalate?: boolean;
+    noCards?: boolean;
+    cache?: boolean;
+    direct?: {
+        threshold: number;
+        maxChars?: number;
+    };
+    jevCacheDir?: string;
+    readerView?: ReaderSelection;
+    maxTokens?: number;
+};
+export type AskSetup = {
+    budget?: DailyBudget;
+    budgetStore?: BudgetStore;
+    chat: ChatProvider;
+    options: Omit<AskOptions, 'question'>;
+    notes: string[];
+    embedTexts?: (texts: string[]) => Promise<Float32Array[]>;
+    embedding?: {
+        provider: string;
+        model: string;
+        space: string;
+        dimension: number;
+    };
+};
+export declare function prepareAskRuntime(input: AskSetupInput & {
+    settings: Record<string, unknown>;
+}): Promise<AskSetup>;

package/dist/ask-runtime.js

@@ -0,0 +1,96 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AnswerCache } from './answer-cache.js';
+import { CardIndex, readCards } from './answer-cards.js';
+import { chatProviderConfig, chatRoutes, validateChat } from './chat-config.js';
+import { createChatProvider, fallbackChat } from './chat.js';
+import { validateReaderFilters, validateReaderSelection } from './reader-filters.js';
+import { createProvider, readEmbeddings } from './embeddings.js';
+import { DailyBudget, memoryBudgetStore } from './budget.js';
+import { envBudgetStore } from './budget-store.js';
+import { jevAvailable, jevEndpoint } from './jev.js';
+import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
+import { Retriever } from './retrieval.js';
+// `--reader-view audience=authors,maintainers`, repeatable for more than one filter.
+export function parseReaderView(specs) {
+    if (!specs.length)
+        return undefined;
+    const selection = {};
+    for (const spec of specs) {
+        const match = /^([a-z][a-z0-9-]*)=(.+)$/.exec(spec);
+        if (!match)
+            throw new Error(`--reader-view needs facet=choice[,choice], such as audience=authors; got ${JSON.stringify(spec)}`);
+        if (selection[match[1]])
+            throw new Error(`--reader-view names ${match[1]} twice`);
+        selection[match[1]] = match[2].split(',').map(choice => choice.trim()).filter(Boolean);
+    }
+    return selection;
+}
+// Everything `shoalrun ask` and the answer eval share: read the project's chat and retrieval settings, load the passages and any
+// vectors, and wire up the optional layers. A layer that isn't configured is left out, and one that is configured but can't run
+// (Jev without a key) is left out with a note.
+export async function prepareAskRuntime(input) {
+    const settings = input.settings;
+    const readerFilters = validateReaderFilters(settings.readerFilters);
+    const chatConfig = validateChat(settings.chat, readerFilters);
+    const retrieval = validateRetrieval(settings.retrieval);
+    // --model replaces the main model only. Fallback and escalation models still inherit the config's settings.
+    const mainConfig = chatProviderConfig(chatConfig, { model: input.model });
+    const routes = chatRoutes(chatConfig, chatProviderConfig(chatConfig));
+    const chat = fallbackChat([createChatProvider(mainConfig), ...routes.fallbacks.map(createChatProvider)]);
+    let chunks;
+    try {
+        chunks = JSON.parse(await readFile(path.join(input.siteDirectory, 'ai', 'chunks.json'), 'utf8'));
+    }
+    catch (error) {
+        throw error.code === 'ENOENT' ? new Error(`No ai/chunks.json in ${input.siteDirectory}; run shoalrun index first`) : error;
+    }
+    const embeddings = await readEmbeddings(input.siteDirectory);
+    const retriever = new Retriever(chunks, embeddings);
+    const variants = retriever.variants();
+    const variant = input.channel && input.version && input.language ? `${input.channel}|${input.version}|${input.language}` : variants.length === 1 ? variants[0] : undefined;
+    if (!variant)
+        throw new Error(`The site has several publications (${variants.join(', ')}); pass --channel, --version, and --language`);
+    let embedQuery;
+    let embedTexts;
+    let embedding;
+    if (embeddings) {
+        const queryProvider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
+        if (queryProvider.space !== embeddings.meta.space || (embeddings.meta.backend && queryProvider.backend !== embeddings.meta.backend))
+            throw new Error(`${queryProvider.model} is not in the embedding space or backend of ${embeddings.meta.model}; set retrieval.embeddings.queryModel and baseUrl to compatible values`);
+        embedQuery = async (text, signal) => (await queryProvider.embed([text], 'query', signal))[0];
+        embedTexts = texts => queryProvider.embed(texts, 'query');
+        embedding = { provider: queryProvider.name, model: queryProvider.model, space: queryProvider.space, dimension: queryProvider.dimension };
+    }
+    // A reader view on the command line replaces the config's, so one run can answer for a different audience.
+    if (input.readerView && !readerFilters)
+        throw new Error('--reader-view needs readerFilters.facets in the site config');
+    const readerSelection = input.readerView ? validateReaderSelection(input.readerView, readerFilters, '--reader-view') : chatConfig?.readerView;
+    const notes = [];
+    const rerank = Boolean(chatConfig?.rerank) && !input.noRerank;
+    const scoring = chatConfig?.rerank;
+    const scorer = { ...(scoring?.endpoint ? { endpoint: jevEndpoint(scoring.endpoint) } : {}), ...(scoring?.model ? { model: scoring.model } : {}), ...(scoring?.keyEnv ? { keyEnv: scoring.keyEnv } : {}), ...(scoring?.stateFormat ? { stateFormat: scoring.stateFormat } : {}), ...(input.jevCacheDir ? { cacheDir: input.jevCacheDir } : {}) };
+    const scoringReady = jevAvailable(scoring?.keyEnv);
+    // A scorer that is configured but has no key counts as down, not as absent: it is what keeps off-topic questions from the model.
+    if (rerank && !scoringReady)
+        notes.push(`The relevance scorer has no key: set ${scoring?.keyEnv ?? 'JEV_API_KEY'}. Until then it counts as down, so ${scoring?.onError === 'answer' ? 'the model answers without the gate and the claim check' : 'questions get the closest pages and no model call'}`);
+    // Answer cards need semantic search and Jev. A configured but missing card file is a note, not an error, so the chat still answers.
+    let cards;
+    if (chatConfig?.cards && !input.noCards && rerank && scoringReady) {
+        const file = await readCards(input.siteDirectory);
+        if (!file)
+            notes.push('chat.cards is set but there is no ai/answers.json; run shoalrun answers to make it');
+        else if (!embedding || file.embedding.space !== embedding.space || file.embedding.dimension !== embedding.dimension)
+            notes.push('The answer cards were made with a different embedding model, so they are not used; run shoalrun answers again');
+        else
+            cards = { index: new CardIndex(file), threshold: chatConfig.cards.threshold, confirm: chatConfig.cards.confirm, jev: { ...scorer, maxCalls: 1 } };
+    }
+    // The shared store is for a hosted function. A local run keeps its counters in memory, so it never needs the store's keys.
+    const store = input.sharedStore && chatConfig?.budget?.store ? envBudgetStore(chatConfig.budget.store) : memoryBudgetStore();
+    const reported = new Set();
+    const onBudgetError = (error) => { if (!reported.has(error.message)) {
+        reported.add(error.message);
+        process.stderr.write(`Budget: ${error.message}. Questions get the closest pages, with no model call, until it works.\n`);
+    } };
+    return { ...(chatConfig?.budget ? { budget: new DailyBudget(store, chatConfig.budget, Date.now, onBudgetError), budgetStore: store } : {}), chat, notes, embedTexts, embedding, options: { ...(scoring?.onError ? { onScorerError: scoring.onError } : {}), retriever, chat, variant, readerSelection, embedQuery, passages: input.passages ?? chatConfig?.passages, gate: chatConfig?.gate, ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}), ...(rerank ? { jev: { ...scorer, top: 24, maxCalls: 2 } } : {}), ...(cards ? { cards } : {}), ...(input.cache && chatConfig?.cache ? { cache: new AnswerCache({ maxEntries: chatConfig.cache.maxEntries, ttlMs: chatConfig.cache.ttlMinutes * 60_000 }) } : {}), ...(routes.escalate && !input.noEscalate ? { escalate: { chat: createChatProvider(routes.escalate.config), when: routes.escalate.when } } : {}), ...(rerank && scoringReady && !input.noDirect && (input.direct || chatConfig?.direct) ? { direct: { threshold: input.direct?.threshold ?? chatConfig.direct.threshold, maxChars: input.direct?.maxChars ?? chatConfig?.direct?.maxChars ?? 1200, margin: chatConfig?.direct?.margin ?? 0.1, others: chatConfig?.direct?.others ?? 1, jev: { ...scorer, maxCalls: 2 } } } : {}), ...(rerank && scoringReady && chatConfig?.verify ? { verify: { ...chatConfig.verify, jev: { ...scorer, maxCalls: 3 } } } : {}) } };
+}

package/dist/ask-setup.d.ts

@@ -1,43 +1,4 @@
-import type { AskOptions } from './ask.js';
-import { type ChatProvider } from './chat.js';
-import { type ReaderSelection } from './reader-filters.js';
-import { DailyBudget, type BudgetStore } from './budget.js';
-export declare function parseReaderView(specs: string[]): ReaderSelection | undefined;
-export type AskSetupInput = {
-    sharedStore?: boolean;
-    siteDirectory: string;
-    configFile?: string;
-    settings?: Record<string, unknown>;
-    model?: string;
-    passages?: number;
-    channel?: string;
-    version?: string;
-    language?: string;
-    noRerank?: boolean;
-    noDirect?: boolean;
-    noEscalate?: boolean;
-    noCards?: boolean;
-    cache?: boolean;
-    direct?: {
-        threshold: number;
-        maxChars?: number;
-    };
-    jevCacheDir?: string;
-    readerView?: ReaderSelection;
-    maxTokens?: number;
-};
-export type AskSetup = {
-    budget?: DailyBudget;
-    budgetStore?: BudgetStore;
-    chat: ChatProvider;
-    options: Omit<AskOptions, 'question'>;
-    notes: string[];
-    embedTexts?: (texts: string[]) => Promise<Float32Array[]>;
-    embedding?: {
-        provider: string;
-        model: string;
-        space: string;
-        dimension: number;
-    };
-};
+import { type AskSetup, type AskSetupInput } from './ask-runtime.js';
+export { parseReaderView } from './ask-runtime.js';
+export type { AskSetup, AskSetupInput } from './ask-runtime.js';
 export declare function prepareAsk(input: AskSetupInput): Promise<AskSetup>;

package/dist/ask-setup.js

@@ -1,99 +1,11 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { AnswerCache } from './answer-cache.js';
-import { CardIndex, readCards } from './answer-cards.js';
-import { chatProviderConfig, chatRoutes, validateChat } from './chat-config.js';
-import { createChatProvider, fallbackChat } from './chat.js';
 import { loadConfig } from './config.js';
-import { validateReaderFilters, validateReaderSelection } from './reader-filters.js';
-import { createProvider, readEmbeddings } from './embeddings.js';
-import { DailyBudget, memoryBudgetStore } from './budget.js';
-import { envBudgetStore } from './budget-store.js';
-import { jevAvailable, jevEndpoint } from './jev.js';
-import { queryProviderConfig, validateRetrieval } from './retrieval-config.js';
-import { Retriever } from './retrieval.js';
-// `--reader-view audience=authors,maintainers`, repeatable for more than one filter.
-export function parseReaderView(specs) {
-    if (!specs.length)
-        return undefined;
-    const selection = {};
-    for (const spec of specs) {
-        const match = /^([a-z][a-z0-9-]*)=(.+)$/.exec(spec);
-        if (!match)
-            throw new Error(`--reader-view needs facet=choice[,choice], such as audience=authors; got ${JSON.stringify(spec)}`);
-        if (selection[match[1]])
-            throw new Error(`--reader-view names ${match[1]} twice`);
-        selection[match[1]] = match[2].split(',').map(choice => choice.trim()).filter(Boolean);
-    }
-    return selection;
-}
-// Everything `shoalrun ask` and the answer eval share: read the project's chat and retrieval settings, load the passages and any
-// vectors, and wire up the optional layers. A layer that isn't configured is left out, and one that is configured but can't run
-// (Jev without a key) is left out with a note.
+import { prepareAskRuntime } from './ask-runtime.js';
+export { parseReaderView } from './ask-runtime.js';
+// Local authoring/evaluation accepts a source config. Hosted functions import
+// ask-runtime directly and receive already-resolved settings instead.
 export async function prepareAsk(input) {
     if (!input.settings && !input.configFile)
         throw new Error('prepareAsk needs a config file or settings');
     const settings = input.settings ?? (await loadConfig(input.configFile)).value;
-    const readerFilters = validateReaderFilters(settings.readerFilters);
-    const chatConfig = validateChat(settings.chat, readerFilters);
-    const retrieval = validateRetrieval(settings.retrieval);
-    // --model replaces the main model only. Fallback and escalation models still inherit the config's settings.
-    const mainConfig = chatProviderConfig(chatConfig, { model: input.model });
-    const routes = chatRoutes(chatConfig, chatProviderConfig(chatConfig));
-    const chat = fallbackChat([createChatProvider(mainConfig), ...routes.fallbacks.map(createChatProvider)]);
-    let chunks;
-    try {
-        chunks = JSON.parse(await readFile(path.join(input.siteDirectory, 'ai', 'chunks.json'), 'utf8'));
-    }
-    catch (error) {
-        throw error.code === 'ENOENT' ? new Error(`No ai/chunks.json in ${input.siteDirectory}; run shoalrun index first`) : error;
-    }
-    const embeddings = await readEmbeddings(input.siteDirectory);
-    const retriever = new Retriever(chunks, embeddings);
-    const variants = retriever.variants();
-    const variant = input.channel && input.version && input.language ? `${input.channel}|${input.version}|${input.language}` : variants.length === 1 ? variants[0] : undefined;
-    if (!variant)
-        throw new Error(`The site has several publications (${variants.join(', ')}); pass --channel, --version, and --language`);
-    let embedQuery;
-    let embedTexts;
-    let embedding;
-    if (embeddings) {
-        const queryProvider = createProvider(queryProviderConfig(retrieval, embeddings.meta));
-        if (queryProvider.space !== embeddings.meta.space || (embeddings.meta.backend && queryProvider.backend !== embeddings.meta.backend))
-            throw new Error(`${queryProvider.model} is not in the embedding space or backend of ${embeddings.meta.model}; set retrieval.embeddings.queryModel and baseUrl to compatible values`);
-        embedQuery = async (text, signal) => (await queryProvider.embed([text], 'query', signal))[0];
-        embedTexts = texts => queryProvider.embed(texts, 'query');
-        embedding = { provider: queryProvider.name, model: queryProvider.model, space: queryProvider.space, dimension: queryProvider.dimension };
-    }
-    // A reader view on the command line replaces the config's, so one run can answer for a different audience.
-    if (input.readerView && !readerFilters)
-        throw new Error('--reader-view needs readerFilters.facets in the site config');
-    const readerSelection = input.readerView ? validateReaderSelection(input.readerView, readerFilters, '--reader-view') : chatConfig?.readerView;
-    const notes = [];
-    const rerank = Boolean(chatConfig?.rerank) && !input.noRerank;
-    const scoring = chatConfig?.rerank;
-    const scorer = { ...(scoring?.endpoint ? { endpoint: jevEndpoint(scoring.endpoint) } : {}), ...(scoring?.model ? { model: scoring.model } : {}), ...(scoring?.keyEnv ? { keyEnv: scoring.keyEnv } : {}), ...(scoring?.stateFormat ? { stateFormat: scoring.stateFormat } : {}), ...(input.jevCacheDir ? { cacheDir: input.jevCacheDir } : {}) };
-    const scoringReady = jevAvailable(scoring?.keyEnv);
-    // A scorer that is configured but has no key counts as down, not as absent: it is what keeps off-topic questions from the model.
-    if (rerank && !scoringReady)
-        notes.push(`The relevance scorer has no key: set ${scoring?.keyEnv ?? 'JEV_API_KEY'}. Until then it counts as down, so ${scoring?.onError === 'answer' ? 'the model answers without the gate and the claim check' : 'questions get the closest pages and no model call'}`);
-    // Answer cards need semantic search and Jev. A configured but missing card file is a note, not an error, so the chat still answers.
-    let cards;
-    if (chatConfig?.cards && !input.noCards && rerank && scoringReady) {
-        const file = await readCards(input.siteDirectory);
-        if (!file)
-            notes.push('chat.cards is set but there is no ai/answers.json; run shoalrun answers to make it');
-        else if (!embedding || file.embedding.space !== embedding.space || file.embedding.dimension !== embedding.dimension)
-            notes.push('The answer cards were made with a different embedding model, so they are not used; run shoalrun answers again');
-        else
-            cards = { index: new CardIndex(file), threshold: chatConfig.cards.threshold, confirm: chatConfig.cards.confirm, jev: { ...scorer, maxCalls: 1 } };
-    }
-    // The shared store is for a hosted function. A local run keeps its counters in memory, so it never needs the store's keys.
-    const store = input.sharedStore && chatConfig?.budget?.store ? envBudgetStore(chatConfig.budget.store) : memoryBudgetStore();
-    const reported = new Set();
-    const onBudgetError = (error) => { if (!reported.has(error.message)) {
-        reported.add(error.message);
-        process.stderr.write(`Budget: ${error.message}. Questions get the closest pages, with no model call, until it works.\n`);
-    } };
-    return { ...(chatConfig?.budget ? { budget: new DailyBudget(store, chatConfig.budget, Date.now, onBudgetError), budgetStore: store } : {}), chat, notes, embedTexts, embedding, options: { ...(scoring?.onError ? { onScorerError: scoring.onError } : {}), retriever, chat, variant, readerSelection, embedQuery, passages: input.passages ?? chatConfig?.passages, gate: chatConfig?.gate, ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}), ...(rerank ? { jev: { ...scorer, top: 24, maxCalls: 2 } } : {}), ...(cards ? { cards } : {}), ...(input.cache && chatConfig?.cache ? { cache: new AnswerCache({ maxEntries: chatConfig.cache.maxEntries, ttlMs: chatConfig.cache.ttlMinutes * 60_000 }) } : {}), ...(routes.escalate && !input.noEscalate ? { escalate: { chat: createChatProvider(routes.escalate.config), when: routes.escalate.when } } : {}), ...(rerank && scoringReady && !input.noDirect && (input.direct || chatConfig?.direct) ? { direct: { threshold: input.direct?.threshold ?? chatConfig.direct.threshold, maxChars: input.direct?.maxChars ?? chatConfig?.direct?.maxChars ?? 1200, margin: chatConfig?.direct?.margin ?? 0.1, others: chatConfig?.direct?.others ?? 1, jev: { ...scorer, maxCalls: 2 } } } : {}), ...(rerank && scoringReady && chatConfig?.verify ? { verify: { ...chatConfig.verify, jev: { ...scorer, maxCalls: 3 } } } : {}) } };
+    return prepareAskRuntime({ ...input, settings });
 }

package/dist/embeddings.d.ts

@@ -1,4 +1,4 @@
-import { type Chunk, type ChunkIndex } from './index-build.js';
+import type { Chunk, ChunkIndex } from './index-build.js';
 import { type Transport } from './provider-http.js';
 export type EmbedInputType = 'document' | 'query';
 export type EmbeddingProvider = {

package/dist/embeddings.js

@@ -1,7 +1,7 @@
 import { readFile, realpath, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
-import { aiDirectory } from './index-build.js';
+import { aiDirectory } from './ai-directory.js';
 import { postJson, throwIfCancelled } from './provider-http.js';
 const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 function normalize(vector) {

package/dist/function-package.js

@@ -55,4 +55,9 @@ export async function copyFunctionRuntime(dist, entry, target) {
     const done = new Set();
     for (const name of packages)
         await copyPackage(name, dist, target, done);
+    // Preserve the runtime author's license as well as the licenses retained in
+    // copied dependency packages. Custom runtime directories may have no parent license.
+    const license = path.join(dist, '..', 'LICENSE');
+    if (await stat(license).then(info => info.isFile(), () => false))
+        await cp(license, path.join(target, 'LICENSE.shoalrun'));
 }