@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/assistant/theme-undo.svelte.js

@@ -0,0 +1,50 @@
+export const isThemeUndoRef = (value) => !!value &&
+    typeof value === 'object' &&
+    value.kind === 'theme-undo' &&
+    typeof value.undoId === 'string';
+/**
+ * Theme changes the assistant made. They apply at once (they are cheap to
+ * reverse), and each keeps the theme it replaced so the chat can offer Undo.
+ */
+export class ThemeUndos {
+    store;
+    controller;
+    undos = $state({});
+    counter = 0;
+    /**
+     * With a controller, Undo first goes through its undo command (the path
+     * every other client uses). That undoes the whole document, so it is only
+     * tried while nothing else changed since (no `force`); otherwise, or when
+     * the controller no longer holds the entry, the theme the change replaced is
+     * put back on its own, leaving later edits alone.
+     */
+    constructor(store, controller) {
+        this.store = store;
+        this.controller = controller;
+    }
+    record(previous, commandUndoId) {
+        const id = `theme-undo-${++this.counter}`;
+        this.undos[id] = {
+            id,
+            previous: previous
+                ? structuredClone($state.snapshot(previous))
+                : undefined,
+            status: 'available',
+            ...(commandUndoId ? { commandUndoId } : {}),
+        };
+        return { kind: 'theme-undo', undoId: id };
+    }
+    undo(id) {
+        const entry = this.undos[id];
+        if (entry?.status !== 'available')
+            return;
+        const undone = entry.commandUndoId &&
+            this.controller?.run({
+                name: 'undo',
+                input: { undoId: entry.commandUndoId },
+            }).ok;
+        if (!undone)
+            this.store.write(entry.previous);
+        entry.status = 'undone';
+    }
+}

package/dist/assistant/transport.d.ts

@@ -0,0 +1,73 @@
+import type { AssistantTransport } from '@happyvertical/smrt-chat/svelte';
+import { type PlannerController } from '../planner/commands/index.ts';
+import type { Recipe } from '../recipes/types.ts';
+import type { ThemeSetting } from '../theme/theme.ts';
+import { type RecipeStore, type SettingsStore, type ThemeStore } from './change.ts';
+import type { OfferRef } from './offers.svelte.ts';
+import { type CookbookBrief } from './prompt.ts';
+import type { ThemeUndoRef } from './theme-undo.svelte.ts';
+/** The slice of `@happyvertical/ai`'s provider the transport uses. */
+export interface ChatModel {
+    message(text: string, options?: {
+        history?: {
+            role: 'system' | 'user' | 'assistant';
+            content: string;
+        }[];
+        responseSchema?: Record<string, unknown> | string;
+        temperature?: number;
+        maxTokens?: number;
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+export interface BrowserTransportOptions {
+    /** The loaded model; null until the visitor has downloaded one. */
+    model: () => ChatModel | null;
+    store: RecipeStore;
+    recipes: readonly Recipe[];
+    /** Cookbooks the assistant may offer (id, name, summary). */
+    cookbooks?: readonly CookbookBrief[];
+    /** Proposes a cookbook; the person's click applies it. Null: already pending. */
+    offers?: {
+        offer(cookbookId: string): OfferRef | null;
+        /** True when a cookbook is applied or pending; omit to never back up. */
+        engaged?(): boolean;
+    };
+    /** The app settings the assistant may read and change. */
+    settings?: SettingsStore;
+    /** The app theme the assistant may change; each change can be undone. */
+    theme?: ThemeStore;
+    themeUndos?: {
+        record(previous: ThemeSetting | undefined, commandUndoId?: string): ThemeUndoRef;
+    };
+    /**
+     * The planner controller every change goes through. Omitted, one is made
+     * over `store`, `settings` and `theme`, so the assistant needs no more than
+     * it did before; the app passes its own so manual edits and the assistant
+     * share one Undo history and one snapshot.
+     */
+    controller?: PlannerController;
+    /**
+     * Apply `commands` a reply carries, through the controller. Only for a
+     * server the host chose (host mode); a local or bring-your-own model's
+     * reply is held to the schema's recipes, settings and theme.
+     */
+    acceptCommands?: boolean | (() => boolean);
+    /** Said when `model()` is null; the default asks for a download. */
+    unavailable?: string | (() => string);
+    now?: () => number;
+    /** Called with each reply the model produced (not errors), e.g. to read it aloud. */
+    onReply?: (text: string) => void;
+}
+export interface BrowserAssistantTransport extends AssistantTransport {
+    /** Stop the turn in flight, if any. */
+    abort(): void;
+}
+/** The one line the chat opens with. */
+export declare const GREETING = "What would you like to build?";
+/**
+ * An `AssistantTransport` that runs entirely in the browser: one thread, kept
+ * in memory, whose turns go to the on-device model with the recipes as a
+ * constrained schema. The model's `add`/`remove` are applied through the same
+ * recipe store the Planner cards drive. It never navigates.
+ */
+export declare function createBrowserAssistantTransport(options: BrowserTransportOptions): BrowserAssistantTransport;

package/dist/assistant/transport.js

@@ -0,0 +1,231 @@
+import { createSliceController, } from "../planner/commands/index.js";
+import { buildResponseSchema, describeChange, parseChange, } from "./change.js";
+import { buildMatchIndex, matchText } from "./match.js";
+import { buildSystemPrompt } from "./prompt.js";
+const THREAD_TITLE = 'Plan your app';
+/** The one line the chat opens with. */
+export const GREETING = 'What would you like to build?';
+/** Earlier turns sent back to the model; a small model needs a short context. */
+const HISTORY_TURNS = 6;
+/** A turn's JSON fits well inside this; a looping model is cut off, not left running. */
+const MAX_REPLY_TOKENS = 400;
+const hasKeys = (value) => Object.keys(value).length > 0;
+/** Run one command; what it said, or nothing when it was refused. */
+function runCommand(controller, name, input) {
+    const result = controller.run({ name, input });
+    return result.ok
+        ? { summary: result.receipt.summary, undoId: result.receipt.undoId }
+        : { summary: '' };
+}
+const runSummary = (controller, name, input) => runCommand(controller, name, input).summary;
+/**
+ * Command calls from a host server, in order. A refused one is said once and
+ * stops the rest, so a half-applied sequence never looks complete.
+ */
+function runCommands(controller, calls) {
+    const lines = [];
+    for (const call of calls) {
+        const result = controller.run(call);
+        if (!result.ok) {
+            lines.push(`The server's ${call.name} was refused: ${result.error.message}`);
+            break;
+        }
+        if (result.receipt.summary)
+            lines.push(result.receipt.summary);
+    }
+    return lines.join(' ');
+}
+/**
+ * The model's `add` and `remove` as commands, reported as one change: what
+ * really ended up on or off, after `requires`, and what was kept because
+ * another recipe needs it.
+ */
+function applyRecipes(controller, change) {
+    const added = change.add.length
+        ? controller.run({ name: 'add_recipes', input: { ids: change.add } })
+        : null;
+    const removed = change.remove.length
+        ? controller.run({ name: 'remove_recipes', input: { ids: change.remove } })
+        : null;
+    const on = added?.ok ? (added.receipt.changes?.added ?? []) : [];
+    const off = removed?.ok ? (removed.receipt.changes?.removed ?? []) : [];
+    return {
+        // A recipe added and removed in one turn (one pulled in by the other) is neither.
+        added: on.filter((id) => !off.includes(id)),
+        removed: off.filter((id) => !on.includes(id)),
+        kept: removed?.ok ? (removed.receipt.changes?.kept ?? []) : [],
+    };
+}
+/**
+ * An `AssistantTransport` that runs entirely in the browser: one thread, kept
+ * in memory, whose turns go to the on-device model with the recipes as a
+ * constrained schema. The model's `add`/`remove` are applied through the same
+ * recipe store the Planner cards drive. It never navigates.
+ */
+export function createBrowserAssistantTransport(options) {
+    const now = options.now ?? (() => Date.now());
+    let counter = 0;
+    const id = (prefix) => `${prefix}-${++counter}`;
+    const thread = {
+        id: 'planner',
+        title: THREAD_TITLE,
+        isResolved: false,
+        messageCount: 0,
+        lastMessageAt: null,
+    };
+    const messages = [];
+    const seen = new Map();
+    let controller = null;
+    const push = (role, content, clientRequestId, toolCallData) => {
+        const message = {
+            id: id('m'),
+            threadId: thread.id,
+            content,
+            role,
+            createdAt: new Date(now()),
+            ...(clientRequestId ? { clientRequestId } : {}),
+        };
+        if (toolCallData)
+            message.toolCallData = toolCallData;
+        messages.push(message);
+        thread.messageCount = messages.length;
+        thread.lastMessageAt = message.createdAt;
+        return message;
+    };
+    const planner = options.controller ??
+        createSliceController({
+            store: options.store,
+            settings: options.settings,
+            theme: options.theme,
+        });
+    const index = buildMatchIndex(options.recipes, options.cookbooks ?? [], {
+        theme: !!options.theme,
+    });
+    const greeting = push('assistant', GREETING);
+    async function turn(text) {
+        const model = options.model();
+        if (!model) {
+            return {
+                content: (typeof options.unavailable === 'function'
+                    ? options.unavailable()
+                    : options.unavailable) ??
+                    'Download a model first, then I can help. The cards on the Planner page work without one.',
+            };
+        }
+        controller = new AbortController();
+        try {
+            const cookbooks = options.cookbooks ?? [];
+            const prior = messages
+                .filter((m) => m !== greeting)
+                .slice(0, -1)
+                .slice(-HISTORY_TURNS)
+                .map((m) => ({
+                role: m.role,
+                content: m.content,
+            }));
+            const matches = matchText(index, text);
+            const raw = await model.message(text, {
+                history: [
+                    {
+                        role: 'system',
+                        content: buildSystemPrompt(options.recipes, options.store.ids, cookbooks, options.settings?.read(), matches, options.theme ? { current: options.theme.read() } : undefined),
+                    },
+                    ...prior,
+                ],
+                responseSchema: buildResponseSchema(options.recipes, cookbooks, !!options.settings, !!options.theme),
+                temperature: 0,
+                maxTokens: MAX_REPLY_TOKENS,
+                signal: controller.signal,
+            });
+            const change = parseChange(raw, options.recipes, cookbooks, {
+                commands: typeof options.acceptCommands === 'function'
+                    ? options.acceptCommands()
+                    : options.acceptCommands,
+            });
+            const applied = applyRecipes(planner, change);
+            const settingsText = options.settings && hasKeys(change.settings)
+                ? runSummary(planner, 'set_settings', change.settings)
+                : '';
+            const previousTheme = options.theme?.read();
+            const themed = options.theme && hasKeys(change.theme)
+                ? runCommand(planner, 'set_theme', change.theme)
+                : null;
+            const undo = themed?.undoId && options.themeUndos
+                ? options.themeUndos.record(previousTheme, themed.undoId)
+                : undefined;
+            const commandText = (change.commands ?? []).length
+                ? runCommands(planner, change.commands ?? [])
+                : '';
+            const summary = [
+                describeChange(applied, options.recipes),
+                settingsText,
+                themed?.summary ?? '',
+                commandText,
+            ]
+                .filter(Boolean)
+                .join(' ');
+            // Backstop: a small model sometimes misses a plain "I run a bakery".
+            // A strong cookbook match is offered anyway (never applied without the
+            // click) when the model offered none and none is applied or pending.
+            // Strong recipe matches are only hinted, never added.
+            const strongCookbook = matches.find((m) => m.kind === 'cookbook' && m.confidence === 'strong')?.id;
+            const cookbookId = change.cookbook ??
+                (strongCookbook && options.offers?.engaged?.() === false
+                    ? strongCookbook
+                    : null);
+            const offer = cookbookId
+                ? (options.offers?.offer(cookbookId) ?? undefined)
+                : undefined;
+            const offered = offer
+                ? cookbooks.find((c) => c.id === cookbookId)
+                : undefined;
+            const line = change.reply || (offered ? `Set up ${offered.name}?` : '');
+            const reply = [line, summary].filter(Boolean).join(' ');
+            if (line)
+                options.onReply?.(line);
+            // One ref renders as is; a cookbook offer and a theme Undo in one turn ride together.
+            const refs = offer && undo ? [offer, undo] : (offer ?? undo);
+            return { content: reply || 'Done.', refs };
+        }
+        catch (error) {
+            if (controller?.signal.aborted)
+                return { content: 'Stopped.' };
+            const detail = error instanceof Error ? error.message : String(error);
+            return { content: `Sorry, the model could not answer: ${detail}` };
+        }
+        finally {
+            controller = null;
+        }
+    }
+    return {
+        async listThreads() {
+            return [thread];
+        },
+        async createThread() {
+            return thread;
+        },
+        async loadMessages() {
+            return [...messages];
+        },
+        async sendMessage(input) {
+            const cached = seen.get(input.clientRequestId);
+            if (cached)
+                return cached;
+            const userMessage = push('user', input.content, input.clientRequestId);
+            const reply = await turn(input.content);
+            const result = {
+                inProgress: false,
+                userMessage,
+                assistantMessage: push('assistant', reply.content, undefined, reply.refs),
+            };
+            seen.set(input.clientRequestId, result);
+            return result;
+        },
+        async uploadAttachment(file) {
+            throw new Error(`The assistant cannot take attachments (${file.name}).`);
+        },
+        abort() {
+            controller?.abort();
+        },
+    };
+}

package/dist/assistant/voice-host.d.ts

@@ -0,0 +1,10 @@
+import type { LocalSpeechModel, SpeechModelId } from './voice.svelte.ts';
+export { createHandsFreeCapture } from '@happyvertical/smrt-ui/forms/hands-free';
+/**
+ * The real speech model: Moonshine or Whisper in a Web Worker, built by this
+ * app because the worker is the one module that imports
+ * `@huggingface/transformers`, and the engine (`@happyvertical/speech`) is
+ * loaded here too, so only this app's bundler pulls those libraries in. Kept
+ * apart from the voice logic so tests never load a worker.
+ */
+export declare function createSpeechModel(model: SpeechModelId): LocalSpeechModel;

package/dist/assistant/voice-host.js

@@ -0,0 +1,17 @@
+import { createLocalSpeechModel } from '@happyvertical/smrt-svelte/browser-ai';
+import SpeechWorker from '@happyvertical/smrt-svelte/browser-ai/whisper-worker?worker';
+export { createHandsFreeCapture } from '@happyvertical/smrt-ui/forms/hands-free';
+/**
+ * The real speech model: Moonshine or Whisper in a Web Worker, built by this
+ * app because the worker is the one module that imports
+ * `@huggingface/transformers`, and the engine (`@happyvertical/speech`) is
+ * loaded here too, so only this app's bundler pulls those libraries in. Kept
+ * apart from the voice logic so tests never load a worker.
+ */
+export function createSpeechModel(model) {
+    return createLocalSpeechModel({
+        model,
+        createWorker: () => new SpeechWorker(),
+        loadSpeech: () => import('@happyvertical/speech/local'),
+    });
+}

package/dist/assistant/voice.svelte.d.ts

@@ -0,0 +1,107 @@
+import { type BrowserSpeechSupport, type LocalSpeechModel as SpeechModelHandle, type STTAdapter } from '@happyvertical/smrt-svelte/browser-ai';
+/**
+ * Voice typing for the assistant. The browser's own speech recognition is
+ * used where it works (Chrome, Edge, Safari). Where it does not (Firefox has
+ * none; Brave has the API with no speech service behind it), the visitor is
+ * offered a one-time download of a small speech model that then runs on their
+ * own device. Nothing is downloaded without their say-so.
+ */
+/** The downloadable model the offer drives (smrt-svelte's `LocalSpeechModel`). */
+export type LocalSpeechModel = SpeechModelHandle;
+/** The speech models the visitor can pick (smrt-svelte's short names). */
+export type SpeechModelId = 'moonshine-base' | 'moonshine-tiny' | 'whisper-tiny.en';
+export interface SpeechModelChoice {
+    id: SpeechModelId;
+    label: string;
+    /** One line on what it is good for. */
+    note: string;
+    /** smrt-svelte adapter type that runs it. */
+    adapter: 'moonshine' | 'whisper-local';
+    /** First-download size in bytes (smrt-svelte's estimate). */
+    bytes: number;
+}
+/**
+ * Moonshine base first: it is accurate enough for plain talking, where the
+ * tiny model garbled words. Tiny stays for the quickest, least exact option.
+ */
+export declare const SPEECH_MODELS: readonly SpeechModelChoice[];
+export declare const DEFAULT_SPEECH_MODEL: SpeechModelId;
+export declare function speechModelChoice(id: SpeechModelId): SpeechModelChoice;
+export type VoiceStatus = 
+/** Probing the browser. */
+'checking'
+/** The browser's own speech recognition works; nothing to offer. */
+ | 'browser'
+/** Not usable here: offer the local model (or turn on a cached one). */
+ | 'offer' | 'downloading' | 'ready' | 'error'
+/** The visitor said "not now" for this visit. */
+ | 'dismissed';
+export type DictationSource = () => Promise<STTAdapter>;
+export interface VoiceOptions {
+    storage: Storage | null;
+    /** Makes the downloadable model. Not called when the browser's works. */
+    createModel: (model: SpeechModelId) => LocalSpeechModel;
+    probe?: () => Promise<BrowserSpeechSupport>;
+    /** Builds the dictation source for the browser's own recogniser. */
+    browserSource?: () => DictationSource;
+    /** Builds the dictation source that records and transcribes locally. */
+    localSource?: (model: LocalSpeechModel, choice: SpeechModelChoice) => DictationSource;
+}
+export declare const VOICE_PREFS_KEY = "smrt-planner:voice:v1";
+/** Whether the visitor has downloaded (and so accepted) the local model. */
+export declare function loadVoiceConsent(storage: Storage | null): boolean;
+export declare function saveVoiceConsent(storage: Storage | null, local: boolean): void;
+/** Whether the visitor chose the downloadable model over the browser's own. */
+export declare function loadPreferLocal(storage: Storage | null): boolean;
+/** The speech model the visitor chose (Moonshine base until they say). */
+export declare function loadSpeechModel(storage: Storage | null): SpeechModelId;
+/** What to do for a probe result, given what is on the device. */
+export type VoicePlan = 'browser' | 'offer' | 'enable-cached';
+export declare function planVoice(support: BrowserSpeechSupport, consented: boolean, cached: boolean): VoicePlan;
+export declare class VoiceSession {
+    status: VoiceStatus;
+    /** Whether the model files are already on this device. */
+    cached: boolean;
+    /** Download progress, 0 to 1. */
+    progress: number;
+    error: string;
+    /** Whether the browser's own recogniser works here (whatever is in use). */
+    browserWorks: boolean;
+    /** The visitor chose the downloadable model even where the browser's works. */
+    preferLocal: boolean;
+    /** The size the offer shows, in bytes. */
+    size: number;
+    /** The chosen downloadable model. */
+    model: SpeechModelId;
+    /** Every byte is in and the model is being prepared ("Getting ready"). */
+    preparing: boolean;
+    /** The dictation source for the composer, or null when voice is off. */
+    dictation: DictationSource | null;
+    private handle;
+    private abort;
+    private readonly options;
+    /**
+     * Bumped by every init, enable and restart. Async work captures the value
+     * it started under and drops its result when a newer one has begun, so a
+     * superseded probe or download cannot overwrite the current status or
+     * dictation source.
+     */
+    private generation;
+    constructor(options: VoiceOptions);
+    /** Probe the browser and decide what to offer. Call once. */
+    init(): Promise<void>;
+    private probeAndOffer;
+    /** Download (or read from the cache) and turn voice typing on. */
+    enable(): Promise<void>;
+    /** Switch between the browser's recogniser and the downloadable model. */
+    setPreferLocal(on: boolean): Promise<void>;
+    /** Pick the downloadable model; the new one is offered (or turned on if cached). */
+    setModel(id: SpeechModelId): Promise<void>;
+    /** Save a changed choice, let go of the current model, and decide again. */
+    private restart;
+    /** Stop a download in progress. */
+    cancel(): void;
+    /** "Not now": hide the offer for this visit. */
+    dismiss(): void;
+    dispose(): void;
+}