pyric 0.0.1 → 0.1.0-alpha.10

package/dist/ai/broker/broker.js

@@ -0,0 +1,184 @@
+/**
+ * The sandbox AI broker — the ONE in-process Gemini-wire model every plane
+ * consumes (house pattern: the messaging broker):
+ *
+ *   - the client mirror (`pyric/ai`, next stage) calls generateContent /
+ *     streamGenerateContent / countTokens exactly like `rtdb.*` / `auth.*`
+ *     will over the worker protocol (cdd-deltas #98.3);
+ *   - Pyric Studio & tracing consume the typed `service_mutation` events the
+ *     broker emits onto the sandbox's unified `onEvent` stream;
+ *   - answering is delegated through ONE seam ({@link AnswerEngine},
+ *     cdd-deltas #97): `scripted` (default, zero-I/O) or `openai`.
+ *
+ * The broker validates requests LIKE PRODUCTION does — before any engine
+ * runs — throwing {@link AiBrokerError} carrying the exact captured error
+ * envelope:
+ *   - empty/missing `contents`            → `ai-error-empty-contents`
+ *   - a role outside the captured list    → `ai-error-bad-role`
+ *   - a model-turn functionCall part with no thoughtSignature
+ *                                         → `ai-error-fncall-missing-thought-signature`
+ *
+ * Event emission is best-effort behind one small choke-point ({@link emit}):
+ * a throw from the emit path (or any event consumer downstream) must never
+ * poison the AI operation the caller just completed — handler errors are the
+ * consumer's problem, never the broker's (the sandbox's emit fan-out already
+ * isolates listener throws; this guard covers the emit path itself).
+ */
+import { emitSandboxEvent, makeServiceMutationEvent } from 'pyric/sandbox/internal';
+import { AiBrokerError, Synthesizer, badRole, emptyContents, missingThoughtSignature } from './synthesizer.js';
+import { ScriptedEngine } from './scripted-engine.js';
+import { OpenAiEngine } from './openai-engine.js';
+/**
+ * Roles production accepts, from the captured rejection text
+ * (`ai-error-bad-role`): "Please use a valid role: SYSTEM, SYSTEM_1, USER,
+ * ASSISTANT, DEVELOPER, CONTEXT, USER_CONTEXT, MODEL, USER." — compared
+ * case-insensitively (the SDK sends lowercase `user`/`model`). `FUNCTION` is
+ * additionally accepted: the captured message omits it, yet production
+ * accepted the SDK's function-response turn (`ai-function-response-round`),
+ * and the installed SDK threads those turns with role `function`.
+ */
+const ACCEPTED_ROLES = new Set([
+    'SYSTEM',
+    'SYSTEM_1',
+    'USER',
+    'ASSISTANT',
+    'DEVELOPER',
+    'CONTEXT',
+    'USER_CONTEXT',
+    'MODEL',
+    'FUNCTION',
+]);
+function isAnswerEngine(value) {
+    return typeof value.generateContent === 'function';
+}
+export class AiBroker {
+    engine;
+    sandbox;
+    constructor(options = {}) {
+        this.sandbox = options.sandbox;
+        const engine = options.engine ?? { kind: 'scripted' };
+        if (isAnswerEngine(engine)) {
+            this.engine = engine;
+        }
+        else if (engine.kind === 'scripted') {
+            this.engine = new ScriptedEngine(engine.script ?? [], new Synthesizer());
+        }
+        else {
+            this.engine = new OpenAiEngine(engine);
+        }
+    }
+    async generateContent(req, model) {
+        this.validate(req, model);
+        const response = await this.engine.generateContent(req, model);
+        this.emit('generate_content', model, {
+            contentCount: req.contents.length,
+            finishReason: response.candidates?.[0]?.finishReason,
+            totalTokenCount: response.usageMetadata?.totalTokenCount,
+            responseId: response.responseId,
+        });
+        return response;
+    }
+    /**
+     * Chunk objects with the captured framing SEMANTICS (finishReason last
+     * chunk only, usageMetadata every chunk). Validation runs EAGERLY — a bad
+     * request throws here, before iteration, the way production answers with
+     * an HTTP error instead of a stream.
+     */
+    streamGenerateContent(req, model) {
+        this.validate(req, model);
+        const inner = this.engine.streamGenerateContent(req, model);
+        const emit = (chunkCount) => this.emit('stream_generate_content', model, {
+            contentCount: req.contents.length,
+            chunkCount,
+        });
+        return (async function* wrapped() {
+            let chunkCount = 0;
+            for await (const chunk of inner) {
+                chunkCount++;
+                yield chunk;
+            }
+            emit(chunkCount);
+        })();
+    }
+    async countTokens(req, model) {
+        this.validateContents(req, model);
+        const response = await this.engine.countTokens(req, model);
+        this.emit('count_tokens', model, { totalTokens: response.totalTokens });
+        return response;
+    }
+    // ── Production-shaped validation ──────────────────────────────────────────
+    validate(req, model) {
+        this.validateContents(req, model);
+        // Model turns threading a functionCall back in MUST carry the
+        // thoughtSignature production minted (`ai-error-fncall-missing-thought-signature`).
+        for (let i = 0; i < req.contents.length; i++) {
+            const content = req.contents[i];
+            if ((content.role ?? '').toUpperCase() !== 'MODEL')
+                continue;
+            for (const part of content.parts ?? []) {
+                if (part.functionCall && part.thoughtSignature === undefined) {
+                    // `position` is the 1-based index of the offending content turn.
+                    this.reject(model, missingThoughtSignature(part.functionCall.name, i + 1));
+                }
+            }
+        }
+    }
+    validateContents(req, model) {
+        const contents = req.contents;
+        if (!Array.isArray(contents) || contents.length === 0) {
+            this.reject(model, emptyContents());
+        }
+        for (const content of contents) {
+            const role = content.role ?? '';
+            if (!ACCEPTED_ROLES.has(role.toUpperCase())) {
+                this.reject(model, badRole(role));
+            }
+        }
+    }
+    /** Emit the rejection onto the event stream, then throw the wire envelope. */
+    reject(model, envelope) {
+        this.emit('request_rejected', model, {
+            code: envelope.error.code,
+            status: envelope.error.status,
+            message: envelope.error.message,
+        });
+        throw new AiBrokerError(envelope);
+    }
+    // ── Event emission (Studio stream consumer seam) ──────────────────────────
+    /**
+     * Land a broker operation on the sandbox's unified event stream.
+     * Best-effort, storage-precedent: a throw from the emit path must never
+     * fail the AI operation the caller just completed.
+     */
+    emit(op, model, detail) {
+        if (this.sandbox === undefined)
+            return;
+        try {
+            emitSandboxEvent(this.sandbox, makeServiceMutationEvent({
+                service: 'ai',
+                op,
+                path: model,
+                auth: null,
+                detail,
+            }), { service: 'ai' });
+        }
+        catch {
+            // Observational — never let event emission break an AI op.
+        }
+    }
+}
+/**
+ * Fixture helper: extract `behavior.raw` from a parsed oracle observation
+ * JSON so a capture pastes straight into a script entry
+ * (`{ respond: loadObservationEnvelope(obs) }`). Captures are the corpus.
+ */
+export function loadObservationEnvelope(obsJson) {
+    const raw = obsJson?.behavior?.raw;
+    if (raw === null ||
+        typeof raw !== 'object' ||
+        !Array.isArray(raw.candidates)) {
+        throw new Error('loadObservationEnvelope: observation has no behavior.raw response envelope (expected a capture with candidates)');
+    }
+    return structuredClone(raw);
+}
+//# sourceMappingURL=broker.js.map

package/dist/ai/broker/broker.js.map

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

package/dist/ai/broker/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * AI broker barrel — the in-process Gemini-wire model for the sandbox's ai
+ * surface (CDD map #92; rulings in packages/conformance/docs/ai/cdd-deltas.md).
+ * NOT wired into package exports yet: the `pyric/ai` mirror layer (next
+ * stage) owns the public surface.
+ */
+export { AiBroker, loadObservationEnvelope, type AiBrokerOptions } from './broker.js';
+export { ScriptedEngine, lastUserText, promptTextOf } from './scripted-engine.js';
+export { OpenAiEngine, ToolCallBuffer, SseParser, DONE_SENTINEL, geminiToOpenAIRequest, normalizeSchema, mapFinishReason, openAIToGeminiResponse, openAIChunkToParts, type OpenAiEngineOptions, type OpenAIRequest, type OpenAIResponse, type OpenAIStreamChunk, type OpenAIMessage, type OpenAIToolCall, } from './openai-engine.js';
+export { AiBrokerError, Synthesizer, errorEnvelope, unknownModel, badRole, emptyContents, missingThoughtSignature, resolveModelVersion, estimateTokens, mintThoughtSignature, mintFunctionCallId, type SynthesizeOptions, } from './synthesizer.js';
+export type { AnswerEngine, CountTokensRequest, CountTokensResponse, EngineConfig, GenerateContentRequest, RawEnvelope, ScriptEntry, ScriptMatcher, ScriptRespond, ScriptShorthand, WireCandidate, WireChunk, WireContent, WireErrorEnvelope, WirePart, WireResponse, WireUsageMetadata, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/broker/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/broker/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,YAAY,EACZ,cAAc,EACd,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,YAAY,EACZ,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,sBAAsB,EACtB,WAAW,EACX,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,YAAY,EACZ,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/ai/broker/index.js

@@ -0,0 +1,11 @@
+/**
+ * AI broker barrel — the in-process Gemini-wire model for the sandbox's ai
+ * surface (CDD map #92; rulings in packages/conformance/docs/ai/cdd-deltas.md).
+ * NOT wired into package exports yet: the `pyric/ai` mirror layer (next
+ * stage) owns the public surface.
+ */
+export { AiBroker, loadObservationEnvelope } from './broker.js';
+export { ScriptedEngine, lastUserText, promptTextOf } from './scripted-engine.js';
+export { OpenAiEngine, ToolCallBuffer, SseParser, DONE_SENTINEL, geminiToOpenAIRequest, normalizeSchema, mapFinishReason, openAIToGeminiResponse, openAIChunkToParts, } from './openai-engine.js';
+export { AiBrokerError, Synthesizer, errorEnvelope, unknownModel, badRole, emptyContents, missingThoughtSignature, resolveModelVersion, estimateTokens, mintThoughtSignature, mintFunctionCallId, } from './synthesizer.js';
+//# sourceMappingURL=index.js.map

package/dist/ai/broker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/broker/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAwB,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EACL,YAAY,EACZ,cAAc,EACd,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,sBAAsB,EACtB,kBAAkB,GAOnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,OAAO,EACP,aAAa,EACb,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GAEnB,MAAM,kBAAkB,CAAC"}

package/dist/ai/broker/openai-engine.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The OpenAI AnswerEngine: Gemini wire in, OpenAI-compatible upstream
+ * (Ollama, llama.cpp, any /v1/chat/completions) out, Gemini wire back.
+ *
+ * The translation core was validated end-to-end against the real firebase/ai
+ * 2.12.0 SDK before landing here as pure, unit-testable functions; only
+ * `OpenAiEngine` does I/O.
+ *
+ * The five lossy edges that validation pinned, all handled here:
+ *   1. Gemini functionResponse has no tool_call_id → synthesized FIFO id
+ *      matching per function name ({@link geminiToOpenAIRequest}).
+ *   2. OpenAI streams tool-call ARGUMENT FRAGMENTS; Gemini streams WHOLE
+ *      functionCall parts → {@link ToolCallBuffer} accumulates fragments and
+ *      the engine emits whole parts on the finish chunk.
+ *   3. Never forward OpenAI's `data: [DONE]` sentinel — the SDK JSON.parses
+ *      every event and dies with PARSE_FAILED (engine skips it).
+ *   4. Thought parts are SKIPPED when replaying history to OpenAI
+ *      (`part.thought` filter in the request walk).
+ *   5. thoughtSignature has no OpenAI equivalent → minted on the Gemini
+ *      side by the synthesizer's decoration pass (production signs even
+ *      trivial text parts, and rejects unsigned functionCall turns).
+ *
+ * Plus: `content_filter` maps to SAFETY (faithful — makes response.text()
+ * throw exactly like production).
+ */
+import { Synthesizer } from './synthesizer.js';
+import type { AnswerEngine, CountTokensRequest, CountTokensResponse, GenerateContentRequest, WireChunk, WirePart, WireResponse } from './types.js';
+export interface OpenAIToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface OpenAIMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: OpenAIToolCall[];
+    tool_call_id?: string;
+}
+export interface OpenAIRequest {
+    model: string;
+    messages: OpenAIMessage[];
+    stream?: boolean;
+    stream_options?: {
+        include_usage: boolean;
+    };
+    tools?: Array<{
+        type: 'function';
+        function: Record<string, unknown>;
+    }>;
+    tool_choice?: string;
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    stop?: string[];
+    response_format?: {
+        type: 'json_object';
+    } | {
+        type: 'json_schema';
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean;
+        };
+    };
+    frequency_penalty?: number;
+    presence_penalty?: number;
+}
+export interface OpenAIResponse {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: string;
+            content: string | null;
+            tool_calls?: OpenAIToolCall[];
+            reasoning?: string;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface OpenAIStreamChunk {
+    id: string;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string;
+            reasoning?: string;
+            tool_calls?: Array<Partial<OpenAIToolCall> & {
+                index: number;
+            }>;
+        };
+        finish_reason: string | null;
+    }>;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export declare function geminiToOpenAIRequest(model: string, req: GenerateContentRequest, stream: boolean): OpenAIRequest;
+/**
+ * Gemini schemas allow uppercase type names ("STRING") and a `nullable`
+ * flag; OpenAI/JSON-Schema wants lowercase types. Normalize defensively and
+ * strip fields JSON Schema validators reject.
+ */
+export declare function normalizeSchema(schema: unknown): Record<string, unknown> | undefined;
+export declare function mapFinishReason(reason: string | null | undefined): string;
+export declare function openAIToGeminiResponse(resp: OpenAIResponse): WireResponse;
+/**
+ * One OpenAI stream chunk → the TEXT parts of one Gemini chunk (or null for
+ * frames carrying nothing representable). Tool-call fragments are NOT
+ * handled here — they buffer in {@link ToolCallBuffer} and emit whole on the
+ * finish chunk (lossy edge #2).
+ */
+export declare function openAIChunkToParts(chunk: OpenAIStreamChunk): WirePart[];
+/**
+ * Accumulates OpenAI streamed tool-call fragments (indexed deltas whose
+ * `arguments` arrive as string pieces) into whole Gemini functionCall parts.
+ */
+export declare class ToolCallBuffer {
+    private readonly byIndex;
+    add(deltas: Array<Partial<OpenAIToolCall> & {
+        index: number;
+    }> | undefined): void;
+    get size(): number;
+    /** Emit whole functionCall parts (args parsed to an object) and reset. */
+    flush(): WirePart[];
+}
+/**
+ * Incremental SSE `data:` payload extractor. Push decoded text as it
+ * arrives; get back complete event payload strings. Handles both LF LF and
+ * CRLF CRLF separators. Emits the `[DONE]` sentinel verbatim — CALLERS must
+ * skip it (lossy edge #3); the engine never forwards it downstream.
+ */
+export declare class SseParser {
+    private buffer;
+    push(text: string): string[];
+}
+export declare const DONE_SENTINEL = "[DONE]";
+export interface OpenAiEngineOptions {
+    baseUrl: string;
+    model?: string;
+    modelMap?: Record<string, string>;
+    fetch?: typeof fetch;
+    synthesizer?: Synthesizer;
+}
+export declare class OpenAiEngine implements AnswerEngine {
+    private readonly baseUrl;
+    private readonly defaultModel;
+    private readonly modelMap;
+    /** Call-signature only (not `typeof fetch`): the wrapper below carries none
+     *  of the runtime's static props (e.g. Bun's `fetch.preconnect`). */
+    private readonly fetchImpl;
+    private readonly synth;
+    constructor(options: OpenAiEngineOptions);
+    /** Gemini model id → upstream model: modelMap[model] ?? config.model ?? passthrough. */
+    resolveUpstreamModel(model: string): string;
+    generateContent(req: GenerateContentRequest, model: string): Promise<WireResponse>;
+    streamGenerateContent(req: GenerateContentRequest, model: string): AsyncIterable<WireChunk>;
+    /** No OpenAI equivalent — deterministic synthesized estimate, wire-true envelope. */
+    countTokens(req: CountTokensRequest, _model: string): Promise<CountTokensResponse>;
+    private post;
+}
+//# sourceMappingURL=openai-engine.d.ts.map

package/dist/ai/broker/openai-engine.d.ts.map

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