pyric 0.0.1 → 0.1.0-alpha.10

package/dist/ai/schema.js

@@ -0,0 +1,174 @@
+/**
+ * `Schema` builder classes for `pyric/ai` — a faithful port of the installed
+ * `@firebase/ai@2.12.0` schema-builder (dist/index.node.mjs), including the
+ * `toJSON()` serialization the SDK relies on when the request body is
+ * JSON.stringify'd: `required` derived from `optionalProperties`, nested
+ * schemas serialized recursively, `anyOf` with no top-level type.
+ *
+ * ONE deliberate delta from the installed 2.12.0, pinned by the registry row
+ * ai#schema-string-enum: `Schema.enumString` sets `format: 'enum'` (GoogleAI
+ * accepts only `enum` and `date-time` formats; the installed builder omits
+ * it and produces requests GoogleAI rejects).
+ */
+import { AIError, AIErrorCode } from './errors.js';
+import { SchemaType } from './enums.js';
+/**
+ * Parent class encompassing all Schema types. Converts with
+ * `JSON.stringify()` into the JSON string the REST endpoints accept.
+ */
+export class Schema {
+    type;
+    format;
+    nullable;
+    constructor(schemaParams) {
+        if (!schemaParams.type && !schemaParams.anyOf) {
+            throw new AIError(AIErrorCode.INVALID_SCHEMA, "A schema must have either a 'type' or an 'anyOf' array of sub-schemas.");
+        }
+        for (const paramKey in schemaParams) {
+            this[paramKey] = schemaParams[paramKey];
+        }
+        this.type = schemaParams.type;
+        this.format = Object.prototype.hasOwnProperty.call(schemaParams, 'format')
+            ? schemaParams.format
+            : undefined;
+        this.nullable = Object.prototype.hasOwnProperty.call(schemaParams, 'nullable')
+            ? !!schemaParams.nullable
+            : false;
+    }
+    /** Serialization the request body applies via `JSON.stringify`. */
+    toJSON() {
+        const obj = { type: this.type };
+        for (const prop in this) {
+            if (Object.prototype.hasOwnProperty.call(this, prop) && this[prop] !== undefined) {
+                if (prop !== 'required' || this.type === SchemaType.OBJECT) {
+                    obj[prop] = this[prop];
+                }
+            }
+        }
+        return obj;
+    }
+    static array(arrayParams) {
+        return new ArraySchema(arrayParams, arrayParams.items);
+    }
+    static object(objectParams) {
+        return new ObjectSchema(objectParams, objectParams.properties, objectParams.optionalProperties);
+    }
+    static string(stringParams) {
+        return new StringSchema(stringParams);
+    }
+    static enumString(stringParams) {
+        // Pinned delta vs installed 2.12.0: GoogleAI requires format 'enum'.
+        return new StringSchema({ format: 'enum', ...stringParams }, stringParams.enum);
+    }
+    static integer(integerParams) {
+        return new IntegerSchema(integerParams);
+    }
+    static number(numberParams) {
+        return new NumberSchema(numberParams);
+    }
+    static boolean(booleanParams) {
+        return new BooleanSchema(booleanParams);
+    }
+    static anyOf(anyOfParams) {
+        return new AnyOfSchema(anyOfParams);
+    }
+}
+/** Schema class for "integer" types. */
+export class IntegerSchema extends Schema {
+    constructor(schemaParams) {
+        super({ type: SchemaType.INTEGER, ...schemaParams });
+    }
+}
+/** Schema class for "number" types. */
+export class NumberSchema extends Schema {
+    constructor(schemaParams) {
+        super({ type: SchemaType.NUMBER, ...schemaParams });
+    }
+}
+/** Schema class for "boolean" types. */
+export class BooleanSchema extends Schema {
+    constructor(schemaParams) {
+        super({ type: SchemaType.BOOLEAN, ...schemaParams });
+    }
+}
+/** Schema class for "string" types, with or without enum values. */
+export class StringSchema extends Schema {
+    enum;
+    constructor(schemaParams, enumValues) {
+        super({ type: SchemaType.STRING, ...schemaParams });
+        this.enum = enumValues;
+    }
+    toJSON() {
+        const obj = super.toJSON();
+        if (this.enum) {
+            obj['enum'] = this.enum;
+        }
+        return obj;
+    }
+}
+/** Schema class for "array" types; `items` is the member schema. */
+export class ArraySchema extends Schema {
+    items;
+    constructor(schemaParams, items) {
+        super({ type: SchemaType.ARRAY, ...schemaParams });
+        this.items = items;
+    }
+    toJSON() {
+        const obj = super.toJSON();
+        obj.items = this.items.toJSON();
+        return obj;
+    }
+}
+/** Schema class for "object" types; `properties` maps names to Schemas. */
+export class ObjectSchema extends Schema {
+    properties;
+    optionalProperties;
+    constructor(schemaParams, properties, optionalProperties = []) {
+        super({ type: SchemaType.OBJECT, ...schemaParams });
+        this.properties = properties;
+        this.optionalProperties = optionalProperties;
+    }
+    toJSON() {
+        const obj = super.toJSON();
+        const serialized = { ...this.properties };
+        const required = [];
+        for (const propertyKey of this.optionalProperties) {
+            if (!Object.prototype.hasOwnProperty.call(this.properties, propertyKey)) {
+                throw new AIError(AIErrorCode.INVALID_SCHEMA, `Property "${propertyKey}" specified in "optionalProperties" does not exist.`);
+            }
+        }
+        for (const propertyKey in this.properties) {
+            if (Object.prototype.hasOwnProperty.call(this.properties, propertyKey)) {
+                serialized[propertyKey] = this.properties[propertyKey].toJSON();
+                if (!this.optionalProperties.includes(propertyKey)) {
+                    required.push(propertyKey);
+                }
+            }
+        }
+        obj.properties = serialized;
+        if (required.length > 0) {
+            obj.required = required;
+        }
+        delete obj.optionalProperties;
+        return obj;
+    }
+}
+/** Schema for a value conforming to ANY of the provided sub-schemas. */
+export class AnyOfSchema extends Schema {
+    anyOf;
+    constructor(schemaParams) {
+        if (schemaParams.anyOf.length === 0) {
+            throw new AIError(AIErrorCode.INVALID_SCHEMA, "The 'anyOf' array must not be empty.");
+        }
+        super({ ...schemaParams, type: undefined });
+        this.anyOf = schemaParams.anyOf;
+    }
+    toJSON() {
+        const obj = super.toJSON();
+        if (this.anyOf && Array.isArray(this.anyOf)) {
+            obj.anyOf = this.anyOf.map((s) => s.toJSON());
+        }
+        return obj;
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/ai/schema.js.map

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

package/dist/ai/scripting.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `pyric/ai/scripting` — the sandbox-only authoring surface for the
+ * scripted answer engine (cdd-deltas #97).
+ *
+ *   - {@link script} wires an ordered entry queue into a sandbox AI
+ *     handle's scripted engine: raw Gemini envelopes (captures paste in),
+ *     shorthands (`text` / `json` / `functionCall` / `chunks` / `error`),
+ *     and matchers (substring / regex / predicate). The wire-error entry
+ *     form `{ error: { httpStatus, body } }` — an HTTP capture pasted
+ *     whole — normalizes into the broker's envelope shorthand here.
+ *   - {@link encodeSse} frames envelopes exactly as production's SSE wire
+ *     does (`ai-generate-stream-framing`): `data: `-prefixed complete JSON
+ *     events separated by CRLF CRLF.
+ *
+ * Everything else (expansion, synthesis, framing semantics) is the broker's
+ * — this module only adapts authoring shapes; it never duplicates envelope
+ * synthesis.
+ */
+import { type ScriptMatcher, type ScriptRespond, type WireResponse } from './broker/index.js';
+import type { AI } from './types.js';
+export type { ScriptEntry, ScriptMatcher, ScriptRespond } from './broker/index.js';
+/** An HTTP error capture pasted whole: status + the wire error body. */
+export interface HttpErrorRespond {
+    error: {
+        httpStatus: number;
+        body: {
+            error: {
+                code?: number;
+                message?: string;
+                status?: string;
+                details?: Array<Record<string, unknown>>;
+            };
+        };
+    };
+}
+/** A script entry as authored: broker entries plus the HTTP-capture error form. */
+export interface ScriptingEntry {
+    match?: ScriptMatcher;
+    respond: ScriptRespond | HttpErrorRespond;
+}
+/**
+ * Append entries to the scripted engine behind a sandbox AI handle. Entries
+ * are consumed at most once, first unconsumed match wins, matcher-less
+ * entries are unconditional FIFO (broker semantics).
+ */
+export declare function script(ai: AI, entries: ScriptingEntry[]): void;
+/**
+ * Encode complete response envelopes as the captured SSE framing bytes:
+ * every event is `data: <complete JSON>`, events separated by CRLF CRLF
+ * (`ai-generate-stream-framing`: allEventsDataPrefixed, separatorIsCrlfCrlf).
+ */
+export declare function encodeSse(envelopes: WireResponse[]): string;
+//# sourceMappingURL=scripting.d.ts.map

package/dist/ai/scripting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripting.d.ts","sourceRoot":"","sources":["../../src/ai/scripting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAErC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEnF,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE;YACJ,KAAK,EAAE;gBACL,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,OAAO,CAAC,EAAE,MAAM,CAAC;gBACjB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAChB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;aAC1C,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,aAAa,GAAG,gBAAgB,CAAC;CAC3C;AAgCD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,IAAI,CAgB9D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,MAAM,CAE3D"}

package/dist/ai/scripting.js

@@ -0,0 +1,73 @@
+/**
+ * `pyric/ai/scripting` — the sandbox-only authoring surface for the
+ * scripted answer engine (cdd-deltas #97).
+ *
+ *   - {@link script} wires an ordered entry queue into a sandbox AI
+ *     handle's scripted engine: raw Gemini envelopes (captures paste in),
+ *     shorthands (`text` / `json` / `functionCall` / `chunks` / `error`),
+ *     and matchers (substring / regex / predicate). The wire-error entry
+ *     form `{ error: { httpStatus, body } }` — an HTTP capture pasted
+ *     whole — normalizes into the broker's envelope shorthand here.
+ *   - {@link encodeSse} frames envelopes exactly as production's SSE wire
+ *     does (`ai-generate-stream-framing`): `data: `-prefixed complete JSON
+ *     events separated by CRLF CRLF.
+ *
+ * Everything else (expansion, synthesis, framing semantics) is the broker's
+ * — this module only adapts authoring shapes; it never duplicates envelope
+ * synthesis.
+ */
+import { ScriptedEngine, } from './broker/index.js';
+import { AIError, AIErrorCode } from './errors.js';
+import { targetOf } from './target.js';
+function isHttpErrorRespond(respond) {
+    if (respond === null || typeof respond !== 'object' || !('error' in respond))
+        return false;
+    const error = respond.error;
+    return (error !== null &&
+        typeof error === 'object' &&
+        'httpStatus' in error &&
+        typeof error.httpStatus === 'number');
+}
+function normalizeEntry(entry) {
+    if (!isHttpErrorRespond(entry.respond)) {
+        return entry;
+    }
+    const { httpStatus, body } = entry.respond.error;
+    const wire = body?.error ?? {};
+    return {
+        ...(entry.match !== undefined ? { match: entry.match } : {}),
+        respond: {
+            error: {
+                code: wire.code ?? httpStatus,
+                message: wire.message ?? '',
+                status: wire.status ?? 'INVALID_ARGUMENT',
+                ...(wire.details !== undefined ? { details: wire.details } : {}),
+            },
+        },
+    };
+}
+/**
+ * Append entries to the scripted engine behind a sandbox AI handle. Entries
+ * are consumed at most once, first unconsumed match wins, matcher-less
+ * entries are unconditional FIFO (broker semantics).
+ */
+export function script(ai, entries) {
+    const target = targetOf(ai);
+    if (target.kind !== 'sandbox') {
+        throw new AIError(AIErrorCode.UNSUPPORTED, 'script(ai, entries) is unavailable for a transport-backed AI handle.');
+    }
+    const engine = target.broker.engine;
+    if (!(engine instanceof ScriptedEngine)) {
+        throw new AIError(AIErrorCode.UNSUPPORTED, "script(ai, entries) requires the scripted engine (the getAI(sandbox) default, or engine: { kind: 'scripted' }).");
+    }
+    engine.push(...entries.map(normalizeEntry));
+}
+/**
+ * Encode complete response envelopes as the captured SSE framing bytes:
+ * every event is `data: <complete JSON>`, events separated by CRLF CRLF
+ * (`ai-generate-stream-framing`: allEventsDataPrefixed, separatorIsCrlfCrlf).
+ */
+export function encodeSse(envelopes) {
+    return envelopes.map((envelope) => `data: ${JSON.stringify(envelope)}\r\n\r\n`).join('');
+}
+//# sourceMappingURL=scripting.js.map

package/dist/ai/scripting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripting.js","sourceRoot":"","sources":["../../src/ai/scripting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,cAAc,GAKf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA0BvC,SAAS,kBAAkB,CAAC,OAAkC;IAC5D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,MAAM,KAAK,GAAI,OAA4B,CAAC,KAAK,CAAC;IAClD,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,YAAY,IAAI,KAAK;QACrB,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CACrC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAqB;IAC3C,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,OAAO,KAAoB,CAAC;IAC9B,CAAC;IACD,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;IAC/B,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,OAAO,EAAE;YACP,KAAK,EAAE;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,UAAU;gBAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE;gBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,kBAAkB;gBACzC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjE;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,EAAM,EAAE,OAAyB;IACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,OAAO,CACf,WAAW,CAAC,WAAW,EACvB,sEAAsE,CACvE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,YAAY,cAAc,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,OAAO,CACf,WAAW,CAAC,WAAW,EACvB,iHAAiH,CAClH,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,SAAyB;IACjD,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3F,CAAC"}

package/dist/ai/target.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sandbox routing for `pyric/ai`: every {@link AI} handle carries its broker
+ * and sandbox behind {@link TARGET_SYMBOL}. Production selection belongs to
+ * package resolution and never enters this module.
+ */
+import type { Sandbox } from '../sandbox/types/service.js';
+import type { AI, AITarget } from './types.js';
+export declare const TARGET_SYMBOL: unique symbol;
+/**
+ * Recover the dispatch target for an {@link AI} handle. Throws if the handle
+ * wasn't produced by this package — the brand is the only way in.
+ */
+export declare function targetOf(ai: AI): AITarget;
+/**
+ * Brand-based discriminator for `getAI`: a {@link Sandbox} carries
+ * `onCurrentUserChanged` and `withAuth`, which a Firebase-shaped app container
+ * never has.
+ */
+export declare function isSandbox(target: unknown): target is Sandbox;
+//# sourceMappingURL=target.d.ts.map

package/dist/ai/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../src/ai/target.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,aAAa,EAAE,OAAO,MAAkC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,QAAQ,CAMzC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,OAAO,CAO5D"}

package/dist/ai/target.js

@@ -0,0 +1,29 @@
+/**
+ * Sandbox routing for `pyric/ai`: every {@link AI} handle carries its broker
+ * and sandbox behind {@link TARGET_SYMBOL}. Production selection belongs to
+ * package resolution and never enters this module.
+ */
+export const TARGET_SYMBOL = Symbol('pyric/ai/target');
+/**
+ * Recover the dispatch target for an {@link AI} handle. Throws if the handle
+ * wasn't produced by this package — the brand is the only way in.
+ */
+export function targetOf(ai) {
+    const target = ai[TARGET_SYMBOL];
+    if (!target) {
+        throw new TypeError('pyric/ai: unrecognized AI handle — was it produced by getAI(...)?');
+    }
+    return target;
+}
+/**
+ * Brand-based discriminator for `getAI`: a {@link Sandbox} carries
+ * `onCurrentUserChanged` and `withAuth`, which a Firebase-shaped app container
+ * never has.
+ */
+export function isSandbox(target) {
+    return (typeof target === 'object'
+        && target !== null
+        && typeof target.onCurrentUserChanged === 'function'
+        && typeof target.withAuth === 'function');
+}
+//# sourceMappingURL=target.js.map

package/dist/ai/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/ai/target.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,CAAC,MAAM,aAAa,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAEtE;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,EAAM;IAC7B,MAAM,MAAM,GAAI,EAAqC,CAAC,aAAa,CAAC,CAAC;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAe;IACvC,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;WACvB,MAAM,KAAK,IAAI;WACf,OAAQ,MAAkB,CAAC,oBAAoB,KAAK,UAAU;WAC9D,OAAQ,MAAkB,CAAC,QAAQ,KAAK,UAAU,CACtD,CAAC;AACJ,CAAC"}