@polyxd/runtime 0.4.0

package/dist/runtime.d.ts

@@ -0,0 +1,131 @@
+import { type MemoryStore } from "./memory.ts";
+import type { Audit, Capability, Direction, Generator, Message, Report, UIDocument, Usage } from "./types.ts";
+export interface RuntimeOptions {
+    generator: Generator;
+    /** The product's Design Direction, applied in the prompt and in the checks. */
+    direction?: Direction;
+    /** Where the screen shown for each intent is remembered. No memory when left out. */
+    memory?: MemoryStore;
+    /** How many times a failed document goes back to the model with its problems. Default 2. */
+    maxRepairs?: number;
+    /** Send warnings back for repair too, not only errors. Default false. */
+    repairWarnings?: boolean;
+    /** How many of the Direction's exemplars go in the prompt, chosen by relevance. Default 2. */
+    exemplars?: number;
+    /** Turns an exemplar's `document` path into the document. Exemplars given as paths are skipped without it. */
+    resolveExemplar?: (path: string) => unknown | Promise<unknown>;
+    /** The components generated screens may use. Default: every surface component in the spec. */
+    components?: string[];
+    /**
+     * Replaces the default document checks (`staticAudit` from `@polyxd/verifier/static`) with your
+     * own. It gets the same options the verifier takes. The generated-document checks still run.
+     */
+    audit?: Audit;
+    /** Privacy-safe events: counts, timings, validity and check ids. Never the ask, the data or the document. */
+    onEvent?: (event: RuntimeEvent) => void;
+}
+/** One request for a screen. */
+export interface Ask {
+    /** What the person asked, in their words. */
+    ask: string;
+    /** A stable key for what they're trying to do, such as `money.send`. Memory is kept by it. */
+    intent: string;
+    /** The capabilities the surface may trigger, by name. */
+    capabilities?: Record<string, Capability>;
+    /** The host data the surface binds to. Documents are checked against it. */
+    data?: unknown;
+    /** A spec pattern the surface should follow, when the host already knows. */
+    pattern?: string;
+    signal?: AbortSignal;
+}
+export interface Result {
+    /** The accepted document; after giving up, the last one that parsed, if any. */
+    document: UIDocument | undefined;
+    /** What the checks found in `document`. `report.valid` is false when the runtime gave up. */
+    report: Report;
+    /** How many times the model was called. */
+    attempts: number;
+    usage: Usage;
+}
+/** What a stream yields, in order: `started`, then per attempt its `text` and `attempt`, then `repaired` if a repair worked, then `done` or `error`. */
+export type Progress = {
+    type: "started";
+    remembered: boolean;
+    exemplars: number;
+} | {
+    type: "text";
+    attempt: number;
+    text: string;
+} | {
+    type: "attempt";
+    attempt: number;
+    report: Report;
+} | {
+    type: "repaired";
+    attempt: number;
+    report: Report;
+} | {
+    type: "done";
+    result: Result;
+} | {
+    type: "error";
+    reason: ErrorReason;
+    error?: unknown;
+    result?: Result;
+};
+export type ErrorReason = "invalid" | "aborted" | "generator" | "setup";
+/** The events `onEvent` receives. Numbers, booleans and check ids only. */
+export type RuntimeEvent = {
+    type: "started";
+    maxAttempts: number;
+    exemplars: number;
+    remembered: boolean;
+    promptChars: number;
+} | {
+    type: "text";
+    attempt: number;
+    chars: number;
+} | {
+    type: "attempt";
+    attempt: number;
+    ms: number;
+    chars: number;
+    valid: boolean;
+    errors: number;
+    warnings: number;
+    checks: string[];
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    type: "repaired";
+    attempt: number;
+} | {
+    type: "done";
+    attempts: number;
+    ms: number;
+    warnings: number;
+    checks: string[];
+    inputTokens: number;
+    outputTokens: number;
+} | {
+    type: "error";
+    reason: ErrorReason;
+    attempts: number;
+    ms: number;
+    status?: number;
+    checks?: string[];
+};
+export interface Runtime {
+    /** Generates, checks and repairs a document for one ask. */
+    generate(ask: Ask, options?: {
+        onProgress?: (progress: Progress) => void;
+    }): Promise<Result>;
+    /** The same, as an async iterator of progress. Stopping early aborts the model call. */
+    stream(ask: Ask): AsyncGenerator<Progress, void, undefined>;
+    /** The exact prompt `generate` would send first, for inspection and tests. */
+    prompt(ask: Ask): Promise<{
+        system: string;
+        messages: Message[];
+    }>;
+}
+export declare function createRuntime(options: RuntimeOptions): Runtime;

package/dist/runtime.js

@@ -0,0 +1,190 @@
+import { checkDocument, generatedChecks, toReport } from "./audit.js";
+import { GeneratorError } from "./adapters/http.js";
+import { directionRules, relevantExemplars } from "./direction.js";
+import { forMemory } from "./memory.js";
+import { parseDocument } from "./parse.js";
+import { repairPrompt, systemPrompt, userPrompt } from "./prompt.js";
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+const checkIds = (findings) => [...new Set(findings.map((f) => f.check))].sort();
+const aborted = (signal, err) => signal?.aborted === true || err?.name === "AbortError";
+export function createRuntime(options) {
+    const maxAttempts = Math.max(0, options.maxRepairs ?? 2) + 1;
+    const rules = directionRules(options.direction);
+    const system = systemPrompt({ components: options.components });
+    async function exemplarsFor(ask) {
+        const chosen = relevantExemplars(options.direction?.exemplars ?? [], ask.ask, ask.intent, options.exemplars ?? 2);
+        const out = [];
+        for (const e of chosen) {
+            const doc = typeof e.document === "string" ? (options.resolveExemplar ? await options.resolveExemplar(e.document) : undefined) : e.document;
+            if (doc && typeof doc === "object")
+                out.push({ request: e.request, document: doc });
+        }
+        return out;
+    }
+    async function prepare(ask) {
+        const previous = options.memory ? await options.memory.get(ask.intent) : undefined;
+        const exemplars = await exemplarsFor(ask);
+        const user = userPrompt({ ask: ask.ask, intent: ask.intent, pattern: ask.pattern, capabilities: ask.capabilities, data: ask.data, direction: options.direction, exemplars, previous });
+        return { user, remembered: previous !== undefined, exemplars: exemplars.length };
+    }
+    async function check(doc, ask) {
+        const checked = ask.data !== undefined ? { ...doc, data: ask.data } : doc;
+        const auditOptions = { rules, emphasisBudget: options.direction?.profile?.emphasisBudget, missingData: ask.data !== undefined ? "error" : "warning" };
+        if (ask.capabilities)
+            auditOptions.registry = { name: "ask", capabilities: ask.capabilities };
+        const found = options.audit ? await options.audit(checked, auditOptions) : checkDocument(checked, auditOptions);
+        return [...found, ...generatedChecks(doc, options.direction, options.components)];
+    }
+    async function run(ask, onProgress, signal) {
+        const started = now();
+        const ms = () => Math.round(now() - started);
+        const event = (e) => {
+            try {
+                options.onEvent?.(e);
+            }
+            catch {
+                // An analytics hook never breaks generation.
+            }
+        };
+        const usage = { inputTokens: 0, outputTokens: 0 };
+        let attempts = 0;
+        const fail = (reason, error, result) => {
+            onProgress({ type: "error", reason, error, result });
+            event({ type: "error", reason, attempts, ms: ms(), ...(error instanceof GeneratorError && error.status !== undefined ? { status: error.status } : {}), ...(result ? { checks: checkIds(result.report.findings) } : {}) });
+        };
+        let prepared;
+        try {
+            prepared = await prepare(ask);
+        }
+        catch (err) {
+            fail("setup", err);
+            throw err;
+        }
+        onProgress({ type: "started", remembered: prepared.remembered, exemplars: prepared.exemplars });
+        event({ type: "started", maxAttempts, exemplars: prepared.exemplars, remembered: prepared.remembered, promptChars: system.length + prepared.user.length });
+        let messages = [{ role: "user", content: prepared.user }];
+        let last = { document: undefined, report: toReport([]) };
+        while (attempts < maxAttempts) {
+            attempts++;
+            const attempt = attempts;
+            const attemptStarted = now();
+            let chars = 0;
+            let text;
+            let used;
+            try {
+                if (signal?.aborted)
+                    throw signal.reason ?? new DOMException("Aborted", "AbortError");
+                const out = await options.generator.generate({
+                    system,
+                    messages,
+                    signal,
+                    onText: (piece) => {
+                        chars += piece.length;
+                        onProgress({ type: "text", attempt, text: piece });
+                        event({ type: "text", attempt, chars: piece.length });
+                    },
+                });
+                if (signal?.aborted)
+                    throw signal.reason ?? new DOMException("Aborted", "AbortError");
+                ({ text, usage: used } = typeof out === "string" ? { text: out, usage: undefined } : out);
+            }
+            catch (err) {
+                fail(aborted(signal, err) ? "aborted" : "generator", err);
+                throw err;
+            }
+            // A generator that doesn't stream still shows its text once.
+            if (chars === 0 && text) {
+                chars = text.length;
+                onProgress({ type: "text", attempt, text });
+                event({ type: "text", attempt, chars });
+            }
+            const u = { inputTokens: used?.inputTokens ?? 0, outputTokens: used?.outputTokens ?? 0 };
+            usage.inputTokens += u.inputTokens;
+            usage.outputTokens += u.outputTokens;
+            const parsed = parseDocument(text);
+            const findings = parsed.error !== undefined ? [{ severity: "error", check: "json:parse", message: parsed.error }] : await check(parsed.document, ask);
+            const report = toReport(findings);
+            const document = parsed.document;
+            onProgress({ type: "attempt", attempt, report });
+            event({ type: "attempt", attempt, ms: Math.round(now() - attemptStarted), chars, valid: report.valid, errors: report.errors, warnings: report.warnings, checks: checkIds(report.findings), ...u });
+            if (document)
+                last = { document, report };
+            else if (!last.document)
+                last = { document: undefined, report };
+            const blocking = report.findings.filter((f) => f.severity === "error" || (options.repairWarnings && attempt < maxAttempts));
+            if (document && !blocking.length) {
+                if (attempt > 1) {
+                    onProgress({ type: "repaired", attempt, report });
+                    event({ type: "repaired", attempt });
+                }
+                if (options.memory) {
+                    try {
+                        await options.memory.set(ask.intent, forMemory(document));
+                    }
+                    catch {
+                        // Memory is a convenience: a full or unavailable store doesn't lose a good document.
+                    }
+                }
+                const result = { document, report, attempts, usage };
+                onProgress({ type: "done", result });
+                event({ type: "done", attempts, ms: ms(), warnings: report.warnings, checks: checkIds(report.findings), ...usage });
+                return result;
+            }
+            messages = [
+                { role: "user", content: prepared.user },
+                { role: "assistant", content: text },
+                { role: "user", content: repairPrompt(blocking) },
+            ];
+        }
+        const result = { document: last.document, report: { ...last.report, valid: false }, attempts, usage };
+        fail("invalid", undefined, result);
+        return result;
+    }
+    /** An abort signal that follows the ask's and can also be aborted by the runtime. */
+    function linked(signal) {
+        const controller = new AbortController();
+        if (signal?.aborted)
+            controller.abort(signal.reason);
+        else
+            signal?.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+        return controller;
+    }
+    return {
+        generate: (ask, opts = {}) => run(ask, opts.onProgress ?? (() => { }), ask.signal),
+        async *stream(ask) {
+            const controller = linked(ask.signal);
+            const queue = [];
+            let wake;
+            let finished = false;
+            const push = (p) => {
+                queue.push(p);
+                wake?.();
+            };
+            run(ask, push, controller.signal).then(() => { }, () => { }).finally(() => {
+                finished = true;
+                wake?.();
+            });
+            try {
+                for (;;) {
+                    if (queue.length) {
+                        yield queue.shift();
+                        continue;
+                    }
+                    if (finished)
+                        return;
+                    await new Promise((resolve) => (wake = resolve));
+                    wake = undefined;
+                }
+            }
+            finally {
+                if (!finished)
+                    controller.abort(new DOMException("The stream was closed", "AbortError"));
+            }
+        },
+        async prompt(ask) {
+            const { user } = await prepare(ask);
+            return { system, messages: [{ role: "user", content: user }] };
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+import type { UIDocument } from "@polyxd/core";
+import type { Capability, CapabilityRegistry } from "@polyxd/spec/capabilities";
+import type { Rule } from "@polyxd/spec/patterns";
+export type { UIDocument, Capability, CapabilityRegistry, Rule };
+/** A component as the generator is told about it (from the spec, at build time). */
+export interface CatalogComponent {
+    name: string;
+    /** Shell components are the product's authored frame and never appear in a generated document. */
+    shell: boolean;
+    /** Its props and when to use it, as one entry of the system prompt. */
+    line: string;
+}
+/** A spec pattern: what the generator is told, and the checks a document that declares it must pass. */
+export interface CatalogPattern {
+    id: string;
+    name: string;
+    summary: string;
+    whenToUse: string[];
+    structure: string[];
+    checks: Rule[];
+}
+/** A Design Direction (`direction.schema.json`). Only the parts the runtime reads are typed. */
+export interface Direction {
+    name: string;
+    version?: string;
+    designSystem?: string;
+    profile?: {
+        density?: "compact" | "comfortable" | "spacious";
+        emphasisBudget?: number;
+        dataDisplay?: "auto" | "prefer-charts" | "prefer-tables" | "prefer-metrics";
+        motion?: "none" | "subtle" | "expressive";
+        disclosure?: "show-everything" | "progressive";
+        freedom?: "strict" | "guided" | "open";
+    };
+    voice?: Record<string, any>;
+    patterns?: {
+        prefer?: string[];
+        disallow?: string[];
+        custom?: string[];
+    };
+    rules?: Rule[];
+    /** `document` is a path in the schema; the runtime also takes the document itself. */
+    exemplars?: {
+        request: string;
+        document: string | UIDocument;
+    }[];
+}
+/** An exemplar ready for the prompt: the request and the document it was answered with. */
+export interface Exemplar {
+    request: string;
+    document: UIDocument;
+}
+export interface Message {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+}
+/** What the runtime asks of a model: one system prompt, a short conversation, and streaming text. */
+export interface GenerateRequest {
+    system: string;
+    messages: Message[];
+    signal?: AbortSignal;
+    /** Called with each piece of text as it arrives. */
+    onText?: (text: string) => void;
+}
+export interface GeneratorOutput {
+    text: string;
+    usage?: Partial<Usage>;
+}
+/** Any model behind one call. The adapters implement it; so can your own code or a fake in tests. */
+export interface Generator {
+    /** A short name for the adapter, such as "anthropic". */
+    readonly name: string;
+    generate(request: GenerateRequest): Promise<GeneratorOutput | string>;
+}
+export interface Finding {
+    severity: "error" | "warning";
+    /** A check id such as `spec`, `pattern:root-is-confirm`, `rule:money-moves-in-confirm` or `json:parse`. */
+    check: string;
+    message: string;
+}
+export interface Report {
+    /** No errors. Warnings don't make a document invalid. */
+    valid: boolean;
+    errors: number;
+    warnings: number;
+    findings: Finding[];
+}
+/** What the runtime passes to the checks: the same shape as the verifier's `staticAudit` options. */
+export interface AuditOptions {
+    /** Only the capabilities offered for this ask. */
+    registry?: CapabilityRegistry;
+    /** The Direction's rules and its compiled voice. */
+    rules?: Rule[];
+    /** The Direction's `profile.emphasisBudget`. */
+    emphasisBudget?: number;
+    /** How a binding that reads nothing from the data is reported: "error" when the ask carries data, "warning" when it doesn't. */
+    missingData?: "warning" | "error";
+}
+/** A document check. `staticAudit` from `@polyxd/verifier/static` fits this shape, and is the default. */
+export type Audit = (doc: any, options: AuditOptions) => Finding[] | Promise<Finding[]>;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@polyxd/runtime",
+  "version": "0.4.0",
+  "description": "Generates a spec-valid Polyxd UI document for an ask with the model you choose: applies a Design Direction, validates and repairs, streams, and remembers the screen per intent",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "build:catalog": "node scripts/build-catalog.ts",
+    "test": "node --test \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@polyxd/core": "^0.4.0",
+    "@polyxd/spec": "^0.4.0",
+    "@polyxd/verifier": "^0.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visualfart/polyxd.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://polyxd.com",
+  "bugs": "https://github.com/visualfart/polyxd/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}