@happyvertical/smrt-planner 0.0.0-stage → 0.0.1

package/dist/assistant/change.js

@@ -0,0 +1,209 @@
+import { CURRENCY_CODES } from "../settings/currencies.js";
+import { normalizeHex, THEME_PRESETS, } from "../theme/theme.js";
+/** Longest payment terms the assistant will write. */
+export const MAX_TERMS_LENGTH = 40;
+/** Longest reply the schema allows; bounds a model that starts to loop. */
+export const MAX_REPLY_LENGTH = 200;
+/** Shown when the model's answer cannot be read; never the raw output. */
+export const FALLBACK_REPLY = 'Sorry, say that again?';
+/** Most command calls one reply may carry. */
+export const MAX_COMMANDS = 8;
+/**
+ * The JSON Schema for one turn. `add` and `remove` are enums of recipe ids,
+ * so grammar-constrained decoding cannot produce an id that does not exist.
+ */
+export function buildResponseSchema(recipes, cookbooks = [], withSettings = false, withTheme = false) {
+    const ids = recipes.map((recipe) => recipe.id);
+    const list = { type: 'array', items: { enum: ids }, maxItems: ids.length };
+    const properties = {
+        reply: { type: 'string', maxLength: MAX_REPLY_LENGTH },
+        add: list,
+        remove: list,
+    };
+    if (cookbooks.length) {
+        properties.cookbook = { enum: [...cookbooks.map((c) => c.id), null] };
+    }
+    if (withSettings) {
+        properties.settings = {
+            type: 'object',
+            properties: {
+                currency: { type: 'string', pattern: '^[A-Z]{3}$' },
+                taxRate: { type: 'number', minimum: 0, maximum: 100 },
+                paymentTerms: { type: 'string', maxLength: MAX_TERMS_LENGTH },
+            },
+            additionalProperties: false,
+        };
+    }
+    if (withTheme) {
+        properties.theme = {
+            type: 'object',
+            properties: {
+                preset: { enum: [...THEME_PRESETS] },
+                primary: { type: 'string', pattern: '^#[0-9a-fA-F]{6}$' },
+                colorScheme: { enum: ['light', 'dark'] },
+            },
+            additionalProperties: false,
+        };
+    }
+    return {
+        type: 'object',
+        properties,
+        required: ['reply', 'add', 'remove'],
+        additionalProperties: false,
+    };
+}
+/** Keep only valid settings: circulating currency, tax 0-100, short terms. */
+export function parseSettings(value) {
+    const out = {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return out;
+    const object = value;
+    if (typeof object.currency === 'string') {
+        const code = object.currency.trim().toUpperCase();
+        if (CURRENCY_CODES.has(code))
+            out.currency = code;
+    }
+    const tax = object.taxRate;
+    if (typeof tax === 'number' &&
+        Number.isFinite(tax) &&
+        tax >= 0 &&
+        tax <= 100) {
+        out.taxRate = tax;
+    }
+    if (typeof object.paymentTerms === 'string') {
+        const terms = [...object.paymentTerms]
+            .map((ch) => ch.charCodeAt(0) < 32 || ch.charCodeAt(0) === 127 ? ' ' : ch)
+            .join('')
+            .trim();
+        if (terms && terms.length <= MAX_TERMS_LENGTH)
+            out.paymentTerms = terms;
+    }
+    return out;
+}
+/** Keep only a known preset, a hex colour and light or dark. */
+export function parseThemePatch(value) {
+    const out = {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return out;
+    const object = value;
+    if (typeof object.preset === 'string' &&
+        THEME_PRESETS.includes(object.preset)) {
+        out.preset = object.preset;
+    }
+    const primary = normalizeHex(object.primary);
+    if (primary)
+        out.primary = primary;
+    if (object.colorScheme === 'light' ||
+        object.colorScheme === 'dark' ||
+        object.colorScheme === 'system') {
+        out.colorScheme = object.colorScheme;
+    }
+    return out;
+}
+/** Remove Qwen3-style thinking, including a block cut off before it closed. */
+export function stripThinking(raw) {
+    return raw
+        .replace(/<think>[\s\S]*?<\/think>/gi, '')
+        .replace(/<think>[\s\S]*$/i, '')
+        .trim();
+}
+/** Pull a `reply` string out of JSON that does not parse (e.g. cut short). */
+function lenientReply(raw) {
+    const match = /"reply"\s*:\s*"((?:[^"\\]|\\.)*)/.exec(raw);
+    if (!match)
+        return null;
+    let text = match[1];
+    // A cut-off escape at the very end would make JSON.parse throw.
+    text = text.replace(/\\$/, '');
+    try {
+        text = JSON.parse(`"${text}"`);
+    }
+    catch {
+        text = text.replace(/\\n/g, ' ').replace(/\\"/g, '"');
+    }
+    return text.trim() || null;
+}
+/**
+ * Read a model reply. Thinking tags are dropped. Malformed JSON still yields
+ * its `reply` text when one can be found, otherwise a short fallback: raw model
+ * output is never shown. Prose with no JSON in it is kept as the reply.
+ * Unknown ids are dropped, an id that is both added and removed is ignored,
+ * and repeats collapse.
+ */
+export function parseChange(input, recipes, cookbooks = [], options = {}) {
+    const known = new Set(recipes.map((recipe) => recipe.id));
+    const raw = stripThinking(input);
+    const plain = (reply) => ({
+        reply,
+        add: [],
+        remove: [],
+        cookbook: null,
+        settings: {},
+        theme: {},
+    });
+    const looksLikeJson = /^[\s`]*[{[]/.test(raw) || /"reply"\s*:/.test(raw);
+    const unreadable = () => plain(looksLikeJson ? (lenientReply(raw) ?? FALLBACK_REPLY) : raw);
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return unreadable();
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return unreadable();
+    }
+    const object = value;
+    const pick = (field) => Array.isArray(field)
+        ? [
+            ...new Set(field.filter((id) => typeof id === 'string' && known.has(id))),
+        ]
+        : [];
+    const add = pick(object.add);
+    const remove = pick(object.remove);
+    const both = new Set(add.filter((id) => remove.includes(id)));
+    const commands = options.commands ? pickCommands(object.commands) : [];
+    return {
+        reply: typeof object.reply === 'string' ? object.reply.trim() : '',
+        add: add.filter((id) => !both.has(id)),
+        remove: remove.filter((id) => !both.has(id)),
+        cookbook: typeof object.cookbook === 'string' &&
+            cookbooks.some((c) => c.id === object.cookbook)
+            ? object.cookbook
+            : null,
+        settings: parseSettings(object.settings),
+        theme: parseThemePatch(object.theme),
+        ...(commands.length ? { commands } : {}),
+    };
+}
+/** `{ name, input }` entries; the controller rejects unknown names and bad input. */
+function pickCommands(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (out.length >= MAX_COMMANDS)
+            break;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const { name, input } = entry;
+        if (typeof name !== 'string')
+            continue;
+        out.push({ name, input: input ?? {} });
+    }
+    return out;
+}
+/** A sentence for the chat saying what changed, by recipe label. */
+export function describeChange(applied, recipes) {
+    const label = (id) => recipes.find((recipe) => recipe.id === id)?.label ?? id;
+    const names = (ids) => ids.map(label).join(', ');
+    const parts = [];
+    if (applied.added.length)
+        parts.push(`Added ${names(applied.added)}.`);
+    if (applied.removed.length)
+        parts.push(`Removed ${names(applied.removed)}.`);
+    if (applied.kept.length) {
+        parts.push(`Kept ${names(applied.kept)} (needed).`);
+    }
+    return parts.join(' ');
+}

package/dist/assistant/engine.d.ts

@@ -0,0 +1,20 @@
+import type { WebLLMEngineLike, WebLLMLoadProgress } from '@happyvertical/ai/local';
+export type LoadProgress = Pick<WebLLMLoadProgress, 'progress' | 'text'>;
+/** A model held in a Web Worker, with a way to stop and free it. */
+export interface LoadedModel {
+    engine: WebLLMEngineLike;
+    /** Free the GPU memory and end the worker. */
+    dispose(): void;
+}
+/** What `loadModel` needs from the browser; swapped out in tests. */
+export interface EngineHost {
+    createWorker(): Worker;
+    createEngine(worker: Worker, modelId: string, onProgress: (report: LoadProgress) => void): Promise<WebLLMEngineLike>;
+}
+/** The real host: a module worker running WebLLM. */
+export declare const browserHost: EngineHost;
+/**
+ * Download (or read from the browser cache) and compile a model in a worker.
+ * Aborting ends the worker, which stops the download, and rejects.
+ */
+export declare function loadModel(modelId: string, onProgress: (report: LoadProgress) => void, signal?: AbortSignal, host?: EngineHost): Promise<LoadedModel>;

package/dist/assistant/engine.js

@@ -0,0 +1,43 @@
+/** The real host: a module worker running WebLLM. */
+export const browserHost = {
+    createWorker: () => new Worker(new URL('./llm.worker.ts', import.meta.url), { type: 'module' }),
+    createEngine: async (worker, modelId, onProgress) => {
+        const { CreateWebWorkerMLCEngine } = await import('@mlc-ai/web-llm');
+        return CreateWebWorkerMLCEngine(worker, modelId, {
+            initProgressCallback: (report) => onProgress(report),
+        });
+    },
+};
+/**
+ * Download (or read from the browser cache) and compile a model in a worker.
+ * Aborting ends the worker, which stops the download, and rejects.
+ */
+export async function loadModel(modelId, onProgress, signal, host = browserHost) {
+    if (signal?.aborted)
+        throw new DOMException('Cancelled', 'AbortError');
+    const worker = host.createWorker();
+    const dispose = () => worker.terminate();
+    let onAbort;
+    const cancelled = new Promise((_, reject) => {
+        onAbort = () => {
+            dispose();
+            reject(new DOMException('Cancelled', 'AbortError'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        const engine = await Promise.race([
+            host.createEngine(worker, modelId, onProgress),
+            cancelled,
+        ]);
+        return { engine, dispose };
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+    finally {
+        if (onAbort)
+            signal?.removeEventListener('abort', onAbort);
+    }
+}

package/dist/assistant/llm.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/assistant/llm.worker.js

@@ -0,0 +1,7 @@
+import { WebWorkerMLCEngineHandler } from '@mlc-ai/web-llm';
+// Runs the model off the UI thread; the page talks to it through
+// `CreateWebWorkerMLCEngine` (see engine.ts).
+const handler = new WebWorkerMLCEngineHandler();
+self.onmessage = (message) => {
+    handler.onmessage(message);
+};

package/dist/assistant/match.d.ts

@@ -0,0 +1,59 @@
+import type { LibraryCookbook } from '../library/types.ts';
+import type { Recipe } from '../recipes/types.ts';
+/**
+ * Keyword matching: what the person typed, mapped to the cookbooks and recipes
+ * it probably means. Deterministic, local and fast. The model still decides
+ * what to do; matches only focus its prompt and back up a cookbook offer.
+ */
+export type MatchKind = 'recipe' | 'cookbook' | 'theme';
+export type Confidence = 'strong' | 'weak';
+export interface Match {
+    kind: MatchKind;
+    id: string;
+    score: number;
+    confidence: Confidence;
+    /** The terms found in the text, as written in the index. */
+    terms: string[];
+}
+type Tier = 'name' | 'synonym' | 'keyword';
+interface Term {
+    /** Normalised, space-separated words. */
+    text: string;
+    tier: Tier;
+    /** Weak terms count towards the score but never make a match strong. */
+    weak: boolean;
+    words: number;
+}
+interface Entry {
+    kind: MatchKind;
+    id: string;
+    terms: Term[];
+    /**
+     * The normalised label or name. A message that is exactly this ranks the
+     * entry first, ahead of another whose id merely ends in the same word
+     * (`Reports` is `reports.materialized`, not `analytics.reports`).
+     */
+    exact?: string;
+}
+export interface MatchIndex {
+    entries: Entry[];
+}
+/** Lowercase, strip accents and punctuation, fold plurals and possessives. */
+export declare function normalize(text: string): string;
+/**
+ * Extra words for the recipes, where the synonyms in the catalog are thin.
+ * Keyed by recipe id; a recipe without an entry still matches its label,
+ * id and synonyms.
+ */
+export declare const RECIPE_KEYWORDS: Readonly<Record<string, readonly string[]>>;
+/** Words that mean the person is talking about how the app looks. */
+export declare const THEME_KEYWORDS: readonly string[];
+/** Build the index for a set of recipes and cookbooks (and theming, when asked). */
+export declare function buildMatchIndex(recipes: readonly Pick<Recipe, 'id' | 'label' | 'synonyms'>[], cookbooks?: readonly (Pick<LibraryCookbook, 'id' | 'name'> & Partial<Pick<LibraryCookbook, 'keywords'>>)[], options?: {
+    theme?: boolean;
+}): MatchIndex;
+/** Distinct match terms an item has; the coverage tests count these. */
+export declare function termsOf(index: MatchIndex, kind: MatchKind, id: string): string[];
+/** Ranked matches for a message, best first. Empty when nothing matches. */
+export declare function matchText(index: MatchIndex, text: string): Match[];
+export {};

package/dist/assistant/match.js

@@ -0,0 +1,271 @@
+const TIER_WEIGHT = { name: 10, synonym: 6, keyword: 4 };
+/** A phrase says more than one of its words does. */
+const PHRASE_FACTOR = 1.5;
+/** Too common to point at anything, in labels and ids. */
+const STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'the',
+    'of',
+    'for',
+    'to',
+    'in',
+    'on',
+    'or',
+    'general',
+    'simple',
+]);
+/**
+ * Words that fit more than one trade or recipe. They add to a score but a
+ * match made only of them stays weak, so they never trigger a cookbook offer.
+ */
+const WEAK_WORDS = [
+    'car',
+    'vehicle',
+    'metal',
+    'steel',
+    'gates',
+    'studio',
+    'classes',
+    'members',
+    'shop',
+    'order',
+    'item',
+    'material',
+    'customer',
+    'sales',
+    'stock',
+    'schedule',
+    'terms',
+];
+/** Fold the way the text is folded, so index and message always agree. */
+function foldWord(word) {
+    if (word.length <= 3)
+        return word;
+    if (word.endsWith('ies'))
+        return `${word.slice(0, -3)}y`;
+    if (word.endsWith('sses'))
+        return word.slice(0, -2);
+    if (/(us|ss|is)$/.test(word))
+        return word;
+    if (word.endsWith('s'))
+        return word.slice(0, -1);
+    return word;
+}
+/** Lowercase, strip accents and punctuation, fold plurals and possessives. */
+export function normalize(text) {
+    return text
+        .normalize('NFD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/['’]s\b/g, '')
+        .replace(/['’]/g, '')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim()
+        .split(' ')
+        .filter(Boolean)
+        .map(foldWord)
+        .join(' ');
+}
+const WEAK = new Set(WEAK_WORDS.map(normalize));
+/**
+ * Extra words for the recipes, where the synonyms in the catalog are thin.
+ * Keyed by recipe id; a recipe without an entry still matches its label,
+ * id and synonyms.
+ */
+export const RECIPE_KEYWORDS = {
+    'commerce.customers': ['customer', 'client', 'contacts', 'patrons'],
+    'commerce.purchases': [
+        'purchase',
+        'buy supplies',
+        'reorder',
+        'order from suppliers',
+    ],
+    'commerce.sales': ['sell', 'sale', 'sales order', 'point of sale'],
+    'commerce.vendors': ['vendor', 'supplier', 'who we buy from'],
+    'inventory.stock': [
+        'inventory',
+        'track stock',
+        'stock levels',
+        'warehouse',
+        'count stock',
+    ],
+    'products.simple': ['product', 'price list', 'menu', 'things we sell'],
+    'products.clothing': ['clothes', 'shirts', 'fashion', 'sizes and colours'],
+    'products.ingredients': [
+        'ingredient',
+        'recipe',
+        'raw material',
+        'flour',
+        'components',
+    ],
+    'commerce.estimates': [
+        'estimate',
+        'quote',
+        'quotes for customers',
+        'price quote',
+        'bid',
+    ],
+    'commerce.wholesale': ['wholesale', 'bulk', 'trade customers', 'resellers'],
+    'commerce.invoicing': [
+        'invoice',
+        'send invoices',
+        'bill customers',
+        'get paid',
+        'receipts',
+    ],
+    'commerce.fulfillment': ['ship', 'shipping', 'courier', 'parcels', 'deliver'],
+    'commerce.agreements': ['contract', 'agreement', 'sign contracts'],
+    'commerce.leases': ['lease', 'rent out', 'equipment hire'],
+    'commerce.licenses': ['licence', 'licence sales', 'software licenses'],
+    'ledgers.bookkeeping': [
+        'books',
+        'keep the books',
+        'bookkeeper',
+        'accountant',
+        'expenses',
+    ],
+    'projects.tracker': ['project', 'task', 'to do list', 'bug', 'ticket'],
+    'events.calendar': [
+        'appointment',
+        'schedule appointments',
+        'event',
+        'meeting',
+        'reservation',
+    ],
+    'sales.pipeline': [
+        'lead',
+        'pipeline',
+        'prospect',
+        'follow up',
+        'sales funnel',
+    ],
+};
+function makeTerm(raw, tier) {
+    const text = normalize(raw);
+    if (!text)
+        return null;
+    const words = text.split(' ');
+    if (words.length === 1 && STOPWORDS.has(text))
+        return null;
+    const weak = tier !== 'name' && words.every((w) => WEAK.has(w));
+    return { text, tier, weak, words: words.length };
+}
+function collect(entry, raw, tier) {
+    const term = makeTerm(raw, tier);
+    if (!term)
+        return;
+    const existing = entry.terms.find((t) => t.text === term.text);
+    if (existing) {
+        if (TIER_WEIGHT[term.tier] > TIER_WEIGHT[existing.tier]) {
+            existing.tier = term.tier;
+            existing.weak = term.weak;
+        }
+        return;
+    }
+    entry.terms.push(term);
+}
+function wordsOf(raw) {
+    return normalize(raw)
+        .split(' ')
+        .filter((w) => w && !STOPWORDS.has(w));
+}
+/** Words that mean the person is talking about how the app looks. */
+export const THEME_KEYWORDS = [
+    'theme',
+    'colour',
+    'color',
+    'colour scheme',
+    'dark mode',
+    'light mode',
+    'brand',
+    'branding',
+    'style',
+    'warmer',
+    'cooler',
+    'font',
+];
+/** Build the index for a set of recipes and cookbooks (and theming, when asked). */
+export function buildMatchIndex(recipes, cookbooks = [], options = {}) {
+    const entries = [];
+    for (const recipe of recipes) {
+        const entry = {
+            kind: 'recipe',
+            id: recipe.id,
+            terms: [],
+            exact: normalize(recipe.label),
+        };
+        collect(entry, recipe.label, 'name');
+        // The last id segment (`pipeline` of `sales.pipeline`), not the package.
+        const last = recipe.id.split('.').pop() ?? '';
+        collect(entry, last.replace(/[-_]/g, ' '), 'name');
+        for (const word of wordsOf(recipe.label))
+            collect(entry, word, 'synonym');
+        for (const synonym of recipe.synonyms)
+            collect(entry, synonym, 'synonym');
+        for (const extra of RECIPE_KEYWORDS[recipe.id] ?? []) {
+            collect(entry, extra, 'keyword');
+        }
+        entries.push(entry);
+    }
+    for (const cookbook of cookbooks) {
+        const entry = {
+            kind: 'cookbook',
+            id: cookbook.id,
+            terms: [],
+            exact: normalize(cookbook.name),
+        };
+        collect(entry, cookbook.name, 'name');
+        collect(entry, cookbook.id.replace(/[-_]/g, ' '), 'name');
+        for (const keyword of cookbook.keywords ?? []) {
+            collect(entry, keyword, 'keyword');
+        }
+        entries.push(entry);
+    }
+    if (options.theme) {
+        const entry = { kind: 'theme', id: 'theme', terms: [] };
+        for (const word of THEME_KEYWORDS)
+            collect(entry, word, 'keyword');
+        entries.push(entry);
+    }
+    return { entries };
+}
+/** Distinct match terms an item has; the coverage tests count these. */
+export function termsOf(index, kind, id) {
+    return (index.entries.find((e) => e.kind === kind && e.id === id)?.terms ?? []).map((t) => t.text);
+}
+/** Ranked matches for a message, best first. Empty when nothing matches. */
+export function matchText(index, text) {
+    const normalized = normalize(text);
+    const haystack = ` ${normalized} `;
+    const out = [];
+    for (const entry of index.entries) {
+        let score = 0;
+        let strong = false;
+        const found = [];
+        for (const term of entry.terms) {
+            if (!haystack.includes(` ${term.text} `))
+                continue;
+            found.push(term.text);
+            score +=
+                TIER_WEIGHT[term.tier] *
+                    (term.words > 1 ? PHRASE_FACTOR : 1) *
+                    (term.weak ? 0.5 : 1);
+            if (!term.weak)
+                strong ||= true;
+        }
+        if (!found.length)
+            continue;
+        if (entry.exact && entry.exact === normalized)
+            score += 1;
+        out.push({
+            kind: entry.kind,
+            id: entry.id,
+            score,
+            confidence: strong ? 'strong' : 'weak',
+            terms: found,
+        });
+    }
+    return out.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}

package/dist/assistant/models.d.ts

@@ -0,0 +1,38 @@
+/** A WebLLM prebuilt model the assistant offers. */
+export interface AssistantModel {
+    /** A model id in WebLLM's prebuilt list. */
+    id: string;
+    label: string;
+    /** Approximate one-time download, in megabytes (cached afterwards). */
+    downloadMB: number;
+    /** GPU memory the model needs while running, in megabytes. */
+    vramMB: number;
+}
+export declare const DEFAULT_MODEL_ID = "Qwen3-1.7B-q4f16_1-MLC";
+/** Small instruction-tuned models; the first is the default. */
+export declare const ASSISTANT_MODELS: readonly AssistantModel[];
+export declare function getModel(id: string): AssistantModel | undefined;
+/** "about 1.1 GB" / "about 700 MB". */
+export declare function formatSize(megabytes: number): string;
+/** The label without its advice: "Qwen3 1.7B (recommended)" -> "Qwen3 1.7B". */
+export declare function shortLabel(model: AssistantModel): string;
+/** The model to suggest when the graphics card has room for it. */
+export declare const ROOMY_MODEL_ID = "Qwen3-4B-q4f16_1-MLC";
+/**
+ * Whether a graphics card whose largest single buffer is `maxBufferBytes` has
+ * room for the model (with some headroom). The default stays the default for
+ * small cards.
+ */
+export declare function hasRoomFor(model: AssistantModel, maxBufferBytes: number): boolean;
+interface GpuNavigator {
+    gpu?: {
+        requestAdapter(): Promise<{
+            limits?: {
+                maxBufferSize?: number;
+            };
+        } | null>;
+    };
+}
+/** The largest buffer the graphics card allows, or 0 when unknown. */
+export declare function graphicsBufferLimit(nav?: GpuNavigator | undefined): Promise<number>;
+export {};