@mate-academy/llm-gateway 8.8.2 → 8.8.4

package/dist/client/plainMessages.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plainMessagesToContentMessages = plainMessagesToContentMessages;
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+/**
+ * Maps the client's persisted plain-message history into the gateway's
+ * content-message shape. The single mapper both `generate` and `runAgent` use,
+ * so a persisted session replays identically through either surface.
+ */
+function plainMessagesToContentMessages(history) {
+    if (!history) {
+        return [];
+    }
+    return history.map((entry) => ({
+        role: entry.role === 'assistant' ? LLMService_typedefs_1.LLMRoles.Assistant : LLMService_typedefs_1.LLMRoles.User,
+        content: [{ type: LLMService_typedefs_1.LLMMessageContentType.TEXT, text: entry.text }],
+    }));
+}
+//# sourceMappingURL=plainMessages.js.map

package/dist/client/plainMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plainMessages.js","sourceRoot":"","sources":["../../src/client/plainMessages.ts"],"names":[],"mappings":";;AAiBA,wEAWC;AA5BD,+DAI+B;AAQ/B;;;;GAIG;AACH,SAAgB,8BAA8B,CAC5C,OAAsC;IAEtC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC7B,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,8BAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,8BAAQ,CAAC,IAAI;QACrE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,2CAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;KAClE,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/client/promptClientPort.typedefs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Fetch options for one live prompt read. Label and version are mutually
+ * exclusive, mirroring `@mate-academy/prompt-client`'s `GetPromptOptions` /
+ * `GetChatPromptOptions` shape so an implementation of `LLMGatewayPromptClient`
+ * needs no adapter to satisfy this port structurally. The port never sets
+ * prompt-client's `fallback` option: the gateway's own build-time snapshot is
+ * the outage fallback, so a live-fetch fallback would be redundant.
+ */
+export interface LLMPromptFetchByLabelOptions {
+    label?: string;
+    version?: never;
+    cacheTtlSeconds?: number;
+}
+export interface LLMPromptFetchByVersionOptions {
+    version?: number;
+    label?: never;
+    cacheTtlSeconds?: number;
+}
+export type LLMPromptFetchOptions = LLMPromptFetchByLabelOptions | LLMPromptFetchByVersionOptions;
+/**
+ * A live-fetched text prompt, shaped to match `@mate-academy/prompt-client`'s
+ * `LLMPrompt` field-for-field (`prompt`, not `text`) so a prompt-client
+ * instance satisfies `LLMGatewayPromptClient` without any adapter.
+ */
+export interface LLMFetchedTextPrompt {
+    prompt: string;
+    config: unknown;
+    version: number;
+    isFallback: boolean;
+}
+/**
+ * `role` is a plain `string`, not a closed enum: this is an open port meant to
+ * match any provider's message shape, not a gateway-owned closed set. A
+ * provider's own enum-typed role (e.g. prompt-client's `LLMPromptMessageRoles`)
+ * is assignable to `string`, so it satisfies this port; it would not be
+ * assignable to a fresh string-literal union.
+ */
+export interface LLMFetchedChatMessage {
+    role: string;
+    content: string;
+}
+export interface LLMFetchedChatPrompt {
+    messages: LLMFetchedChatMessage[];
+    config: unknown;
+    version: number;
+    isFallback: boolean;
+}
+/**
+ * The runtime prompt port the gateway client depends on instead of a
+ * Langfuse SDK client. `@mate-academy/prompt-client`'s `LLMPromptClient`
+ * satisfies this structurally (its extra `listPrompts`/`getPromptRecord`/
+ * `shutdown` methods are simply unused here), so wiring it in at the
+ * composition root needs no adapter layer. An implementation that throws on
+ * failure is expected and handled: the runtime catches every rejection and
+ * falls back to the build-time snapshot.
+ */
+export interface LLMGatewayPromptClient {
+    getPrompt(name: string, options?: LLMPromptFetchOptions): Promise<LLMFetchedTextPrompt>;
+    getChatPrompt(name: string, options?: LLMPromptFetchOptions): Promise<LLMFetchedChatPrompt>;
+}

package/dist/client/promptClientPort.typedefs.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=promptClientPort.typedefs.js.map

package/dist/client/promptClientPort.typedefs.js.map

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

package/dist/client/promptRegistry.runtime.d.ts

@@ -0,0 +1,121 @@
+import { LLMPurposes, type LLMModel, type LLMProviders } from '../LLMService.typedefs';
+import { type LLMLoggerInterface } from '../utilities/logger';
+import { type LLMFallbackMetricEmitter } from '../utilities/llmTracing';
+import { type LLMGatewayPromptClient } from '../client/promptClientPort.typedefs';
+import { type LLMPromptKind, type LLMPromptMessage, type LLMPromptSnapshot } from '../client/promptSnapshot.typedefs';
+import { type LLMPromptConfig } from '../client/llmConfig.schema';
+import { type LLMCapabilityRequirement } from '../client/defineLLMPrompts';
+/**
+ * The resolved, validated prompt the client uses for one call. For a `text`
+ * prompt `text` is the compiled body; for a `chat` prompt `messages` is the
+ * compiled role-tagged list (and `text` is their concatenation, kept for trace
+ * IO + token counting). `config`/`model` passed the gate; `isFallback` flags
+ * that the build-time snapshot was served (live fetch or gate failed), which the
+ * generation observation records and the fallback metric counts.
+ */
+export interface ResolvedPrompt {
+    name: string;
+    kind: LLMPromptKind;
+    text: string;
+    messages: LLMPromptMessage[];
+    config: LLMPromptConfig;
+    model: LLMModel<LLMProviders>;
+    version: number;
+    isFallback: boolean;
+}
+export interface ResolvePromptInput {
+    name: string;
+    kind: LLMPromptKind;
+    variables: Record<string, string>;
+    requires: LLMCapabilityRequirement[];
+    purpose: LLMPurposes;
+    label?: string;
+    versionOverride?: number;
+    labelOverride?: string;
+}
+export interface DescribePromptInput {
+    name: string;
+    kind: LLMPromptKind;
+    requires: LLMCapabilityRequirement[];
+    purpose: LLMPurposes;
+    label?: string;
+    versionOverride?: number;
+    labelOverride?: string;
+}
+/**
+ * The live-resolved routing metadata for a prompt — what the runtime would serve
+ * right now. `isFallback` flags that the build-time snapshot config was used
+ * (live fetch unreachable or its config failed the gate).
+ */
+export interface ResolvedPromptMetadata {
+    name: string;
+    provider: LLMProviders;
+    model: string;
+    promptVersion: number;
+    isFallback: boolean;
+}
+export interface PromptRegistryRuntimeConfig {
+    promptClient: LLMGatewayPromptClient | undefined;
+    snapshot: LLMPromptSnapshot;
+    defaultLabel: string;
+    cacheTtlSeconds?: number;
+    logger?: LLMLoggerInterface;
+    fallbackMetricEmitter?: LLMFallbackMetricEmitter;
+}
+/**
+ * Owns prompt resolution at runtime: a live SDK fetch (cached 60s,
+ * stale-while-revalidate) gated on every read, with the build-time snapshot as
+ * the outage fallback. The single validation gate runs against both the live and
+ * the fallback config; only a config that passes is ever served. When live and
+ * fallback are both unusable the caller decides (throws `LLMConfigError`).
+ */
+export declare class PromptRegistryRuntime {
+    private readonly promptClient;
+    private readonly snapshot;
+    private readonly defaultLabel;
+    private readonly cacheTtlSeconds;
+    private readonly logger;
+    private readonly fallbackMetricEmitter;
+    private hasWarnedThisProcess;
+    constructor(config: PromptRegistryRuntimeConfig);
+    /**
+     * Warms the SDK cache for every snapshot prompt without blocking boot. Each
+     * failure is swallowed so a Langfuse outage at pod start never delays serving;
+     * the snapshot already covers the gap. Dispatches to `getChatPrompt` for a
+     * chat-kind entry, else `getPrompt`.
+     */
+    refreshAll(): Promise<void>;
+    resolve(input: ResolvePromptInput): Promise<ResolvedPrompt | undefined>;
+    /**
+     * Resolves only the prompt's routing metadata (provider, model, version) via the
+     * same live-fetch + gate + snapshot-fallback path `resolve` uses, without
+     * compiling the body or requiring call-site variables. The vars-subset check is
+     * skipped (no variables to check); config/model/capability validation still
+     * applies, so a live config the gate would reject falls back to the snapshot.
+     * Returns what the runtime WOULD serve right now, including fallback.
+     */
+    describe(input: DescribePromptInput): Promise<ResolvedPromptMetadata | undefined>;
+    private describeFromSnapshot;
+    private gateConfig;
+    private tryResolveLive;
+    private tryResolveFallback;
+    private fetchLive;
+    private buildFetchOptions;
+    /**
+     * Substitutes variables into the prompt body. For a `chat` prompt every
+     * message's content is substituted and the roles are preserved; `text` is the
+     * messages concatenated (newline-joined), which the gate's unresolved-variable
+     * check and trace IO use. For a `text` prompt `messages` is empty.
+     */
+    private compileBody;
+    /**
+     * Substitutes one variable at a time. The replacement is a function, not a
+     * string: a string replacement would let `$&`, `$$`, `` $` `` and `$'` inside
+     * a variable's value act as replacement patterns, so any user-authored text
+     * carrying them would silently rewrite itself into the prompt.
+     */
+    private substitute;
+    private emitFallback;
+    private warnOnce;
+}
+export declare function snapshotEntryNames(snapshot: LLMPromptSnapshot): string[];

package/dist/client/promptRegistry.runtime.js

@@ -0,0 +1,264 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptRegistryRuntime = void 0;
+exports.snapshotEntryNames = snapshotEntryNames;
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+const llmTracing_1 = require("../utilities/llmTracing");
+const validationGate_1 = require("../client/validationGate");
+const CHAT_MESSAGE_ROLES = [
+    'system',
+    'user',
+    'assistant',
+];
+const DEFAULT_CACHE_TTL_SECONDS = 60;
+const PROMPT_FETCH_WARN_PREFIX = 'Langfuse prompt fetch degraded';
+/**
+ * Owns prompt resolution at runtime: a live SDK fetch (cached 60s,
+ * stale-while-revalidate) gated on every read, with the build-time snapshot as
+ * the outage fallback. The single validation gate runs against both the live and
+ * the fallback config; only a config that passes is ever served. When live and
+ * fallback are both unusable the caller decides (throws `LLMConfigError`).
+ */
+class PromptRegistryRuntime {
+    promptClient;
+    snapshot;
+    defaultLabel;
+    cacheTtlSeconds;
+    logger;
+    fallbackMetricEmitter;
+    hasWarnedThisProcess = false;
+    constructor(config) {
+        this.promptClient = config.promptClient;
+        this.snapshot = config.snapshot;
+        this.defaultLabel = config.defaultLabel;
+        this.cacheTtlSeconds = config.cacheTtlSeconds ?? DEFAULT_CACHE_TTL_SECONDS;
+        this.logger = config.logger?.child('PromptRegistryRuntime');
+        this.fallbackMetricEmitter
+            = config.fallbackMetricEmitter ?? llmTracing_1.noopFallbackMetricEmitter;
+    }
+    /**
+     * Warms the SDK cache for every snapshot prompt without blocking boot. Each
+     * failure is swallowed so a Langfuse outage at pod start never delays serving;
+     * the snapshot already covers the gap. Dispatches to `getChatPrompt` for a
+     * chat-kind entry, else `getPrompt`.
+     */
+    async refreshAll() {
+        if (!this.promptClient) {
+            return;
+        }
+        await Promise.allSettled(Object.values(this.snapshot).map((entry) => this.fetchLive({
+            name: entry.name,
+            kind: entry.kind,
+            variables: {},
+            requires: [],
+            purpose: LLMService_typedefs_1.LLMPurposes.Completion,
+            label: this.defaultLabel,
+        })));
+    }
+    async resolve(input) {
+        const live = await this.tryResolveLive(input);
+        if (live) {
+            return live;
+        }
+        return this.tryResolveFallback(input);
+    }
+    /**
+     * Resolves only the prompt's routing metadata (provider, model, version) via the
+     * same live-fetch + gate + snapshot-fallback path `resolve` uses, without
+     * compiling the body or requiring call-site variables. The vars-subset check is
+     * skipped (no variables to check); config/model/capability validation still
+     * applies, so a live config the gate would reject falls back to the snapshot.
+     * Returns what the runtime WOULD serve right now, including fallback.
+     */
+    async describe(input) {
+        const live = await this.fetchLive({ ...input, variables: {} });
+        if (live && !live.isFallback) {
+            const gate = this.gateConfig(live.config, input);
+            if (gate.valid) {
+                return {
+                    name: input.name,
+                    provider: gate.config.provider,
+                    model: gate.config.model,
+                    promptVersion: live.version,
+                    isFallback: false,
+                };
+            }
+            this.emitFallback({ ...input, variables: {} }, `live-${gate.reason}`);
+        }
+        return this.describeFromSnapshot(input);
+    }
+    describeFromSnapshot(input) {
+        const entry = this.snapshot[input.name];
+        if (!entry) {
+            return undefined;
+        }
+        const gate = this.gateConfig(entry.config, input);
+        if (!gate.valid) {
+            return undefined;
+        }
+        return {
+            name: input.name,
+            provider: gate.config.provider,
+            model: gate.config.model,
+            promptVersion: entry.version,
+            isFallback: true,
+        };
+    }
+    gateConfig(rawConfig, input) {
+        return (0, validationGate_1.runValidationGate)({
+            rawConfig,
+            requires: input.requires,
+            purpose: input.purpose,
+        });
+    }
+    async tryResolveLive(input) {
+        const fetched = await this.fetchLive(input);
+        if (!fetched || fetched.isFallback) {
+            return undefined;
+        }
+        const compiled = this.compileBody(input.kind, fetched.body, input.variables);
+        const gate = (0, validationGate_1.runValidationGate)({
+            rawConfig: fetched.config,
+            requires: input.requires,
+            purpose: input.purpose,
+        });
+        if (!gate.valid) {
+            this.emitFallback(input, `live-${gate.reason}`);
+            return undefined;
+        }
+        return {
+            name: input.name,
+            kind: input.kind,
+            text: compiled.text,
+            messages: compiled.messages,
+            config: gate.config,
+            model: gate.model,
+            version: fetched.version,
+            isFallback: false,
+        };
+    }
+    tryResolveFallback(input) {
+        const entry = this.snapshot[input.name];
+        if (!entry) {
+            return undefined;
+        }
+        const compiled = this.compileBody(input.kind, input.kind === 'chat' ? entry.fallbackMessages : entry.fallbackText, input.variables);
+        const gate = (0, validationGate_1.runValidationGate)({
+            rawConfig: entry.config,
+            requires: input.requires,
+            purpose: input.purpose,
+        });
+        if (!gate.valid) {
+            return undefined;
+        }
+        this.emitFallback(input, 'snapshot-served');
+        return {
+            name: input.name,
+            kind: input.kind,
+            text: compiled.text,
+            messages: compiled.messages,
+            config: gate.config,
+            model: gate.model,
+            version: entry.version,
+            isFallback: true,
+        };
+    }
+    async fetchLive(input) {
+        if (!this.promptClient) {
+            return undefined;
+        }
+        const options = this.buildFetchOptions({
+            label: input.labelOverride ?? input.label ?? this.defaultLabel,
+            version: input.versionOverride,
+        });
+        try {
+            if (input.kind === 'chat') {
+                const fetched = await this.promptClient.getChatPrompt(input.name, options);
+                return {
+                    body: toPromptMessages(fetched.messages),
+                    config: fetched.config,
+                    version: fetched.version,
+                    isFallback: fetched.isFallback,
+                };
+            }
+            const fetched = await this.promptClient.getPrompt(input.name, options);
+            return {
+                body: fetched.prompt,
+                config: fetched.config,
+                version: fetched.version,
+                isFallback: fetched.isFallback,
+            };
+        }
+        catch (error) {
+            this.warnOnce(input.name, error);
+            return undefined;
+        }
+    }
+    buildFetchOptions(options) {
+        if (options.version === undefined) {
+            return { label: options.label, cacheTtlSeconds: this.cacheTtlSeconds };
+        }
+        return { version: options.version, cacheTtlSeconds: this.cacheTtlSeconds };
+    }
+    /**
+     * Substitutes variables into the prompt body. For a `chat` prompt every
+     * message's content is substituted and the roles are preserved; `text` is the
+     * messages concatenated (newline-joined), which the gate's unresolved-variable
+     * check and trace IO use. For a `text` prompt `messages` is empty.
+     */
+    compileBody(kind, body, variables) {
+        if (kind === 'chat') {
+            const sourceMessages = Array.isArray(body) ? body : [];
+            const messages = sourceMessages.map((message) => ({
+                role: message.role,
+                content: this.substitute(message.content, variables),
+            }));
+            return {
+                text: messages.map((message) => message.content).join('\n'),
+                messages,
+            };
+        }
+        const text = typeof body === 'string'
+            ? this.substitute(body, variables)
+            : '';
+        return { text, messages: [] };
+    }
+    /**
+     * Substitutes one variable at a time. The replacement is a function, not a
+     * string: a string replacement would let `$&`, `$$`, `` $` `` and `$'` inside
+     * a variable's value act as replacement patterns, so any user-authored text
+     * carrying them would silently rewrite itself into the prompt.
+     */
+    substitute(text, variables) {
+        return Object.entries(variables).reduce((accumulator, [key, value]) => accumulator.replace(new RegExp(`{{\\s*${escapeRegExp(key)}\\s*}}`, 'g'), () => value), text);
+    }
+    emitFallback(input, reason) {
+        this.fallbackMetricEmitter({ promptName: input.name, reason });
+    }
+    warnOnce(name, error) {
+        if (this.hasWarnedThisProcess) {
+            return;
+        }
+        this.hasWarnedThisProcess = true;
+        this.logger?.warn(PROMPT_FETCH_WARN_PREFIX, {
+            promptName: name,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+exports.PromptRegistryRuntime = PromptRegistryRuntime;
+function snapshotEntryNames(snapshot) {
+    return Object.values(snapshot).map((entry) => entry.name);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function toPromptMessages(messages) {
+    return messages.flatMap((message) => (isKnownRole(message.role)
+        ? [{ role: message.role, content: message.content }]
+        : []));
+}
+function isKnownRole(role) {
+    return CHAT_MESSAGE_ROLES.includes(role);
+}
+//# sourceMappingURL=promptRegistry.runtime.js.map

package/dist/client/promptRegistry.runtime.js.map

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

package/dist/client/promptSnapshot.typedefs.d.ts

@@ -0,0 +1,55 @@
+import { type LLMPromptConfigParams } from '../client/llmConfig.schema';
+/**
+ * A value a prompt variable may take at a call site. Numbers/booleans are
+ * stringified during compile (matching `promptBuilder`); the union keeps the
+ * generated `compile()` signatures ergonomic without widening to `unknown`.
+ */
+export type LLMVariableValue = string | number | boolean;
+export type LLMPromptKind = 'text' | 'chat';
+/**
+ * A role a chat-prompt message can carry. Mirrors the roles Langfuse chat
+ * prompts use; the v2 client maps `system` to the provider's instructions slot
+ * and `user`/`assistant` to the conversation, preserving the message structure
+ * the prompt declares (plan §1.2 "prompt owns message structure").
+ */
+export type LLMPromptMessageRole = 'system' | 'user' | 'assistant';
+/**
+ * One compiled chat-prompt message. `content` has had its `{{variables}}`
+ * substituted already when it reaches a call site.
+ */
+export interface LLMPromptMessage {
+    role: LLMPromptMessageRole;
+    content: string;
+}
+/**
+ * The config shape stored in the generated snapshot. `provider` is a plain
+ * string here (not the `LLMProviders` enum) so the emitted JSON literal
+ * type-checks without an enum cast; the runtime gate re-parses it through the
+ * zod schema into the strict `LLMPromptConfig` before it is ever served.
+ */
+export interface LLMPromptConfigSnapshot {
+    provider: string;
+    model: string;
+    params?: LLMPromptConfigParams;
+}
+/**
+ * One prompt's build-time snapshot, emitted by `npm run langfuse:generate` into
+ * the gitignored `langfusePrompts.generated.ts`. It is the outage fallback: the
+ * runtime registry serves it whenever a live fetch or config validation fails.
+ * Prompt variables are intentionally absent because their contract is owned by
+ * application code.
+ *
+ * `fallbackText` is the body for a `text` prompt; `fallbackMessages` is the
+ * role-tagged message list for a `chat` prompt. Exactly one is meaningful per
+ * `kind`; the other is left empty so the snapshot stays a plain JSON literal.
+ */
+export interface LLMPromptSnapshotEntry {
+    name: string;
+    kind: LLMPromptKind;
+    version: number;
+    labels: string[];
+    fallbackText: string;
+    fallbackMessages: LLMPromptMessage[];
+    config: LLMPromptConfigSnapshot;
+}
+export type LLMPromptSnapshot = Record<string, LLMPromptSnapshotEntry>;

package/dist/client/promptSnapshot.typedefs.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=promptSnapshot.typedefs.js.map

package/dist/client/promptSnapshot.typedefs.js.map

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

package/dist/client/promptVariables.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The one place a prompt variable becomes the string the prompt compiler
+ * substitutes. Both a code-supplied `variables` map and the arguments a parent
+ * model passes to a typed delegation tool go through it, so a variable a
+ * subagent receives from the model compiles exactly like one written in code.
+ */
+export declare function stringifyPromptVariables(variables: Record<string, unknown>): Record<string, string>;

package/dist/client/promptVariables.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyPromptVariables = stringifyPromptVariables;
+/**
+ * The one place a prompt variable becomes the string the prompt compiler
+ * substitutes. Both a code-supplied `variables` map and the arguments a parent
+ * model passes to a typed delegation tool go through it, so a variable a
+ * subagent receives from the model compiles exactly like one written in code.
+ */
+function stringifyPromptVariables(variables) {
+    return Object.fromEntries(Object.entries(variables).map(([key, value]) => [key, String(value)]));
+}
+//# sourceMappingURL=promptVariables.js.map

package/dist/client/promptVariables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptVariables.js","sourceRoot":"","sources":["../../src/client/promptVariables.ts"],"names":[],"mappings":";;AAMA,4DAMC;AAZD;;;;;GAKG;AACH,SAAgB,wBAAwB,CACtC,SAAkC;IAElC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CACtE,CAAC;AACJ,CAAC"}

package/dist/client/snapshotRuntime.d.ts

@@ -0,0 +1,17 @@
+import { type LLMPromptMessage } from '../client/promptSnapshot.typedefs';
+import { type CompileFromSnapshotOptions } from '../client/snapshotRuntime.typedefs';
+/**
+ * Compiles a `text` prompt straight from the build-time snapshot, substituting
+ * the call-site variables into `fallbackText`. This is the offline path the
+ * generated `compile<Prompt>()` helpers use: no Langfuse fetch, no validation
+ * gate, no cache — an unknown name compiles to an empty string rather than
+ * throwing, so a snapshot that lags a prompt rename degrades instead of
+ * crashing the caller.
+ */
+export declare function compileTextFromSnapshot(options: CompileFromSnapshotOptions): string;
+/**
+ * The `chat` counterpart of `compileTextFromSnapshot`: substitutes into every
+ * message's content and preserves the roles the prompt declares. An unknown
+ * name compiles to an empty message list.
+ */
+export declare function compileMessagesFromSnapshot(options: CompileFromSnapshotOptions): LLMPromptMessage[];

package/dist/client/snapshotRuntime.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileTextFromSnapshot = compileTextFromSnapshot;
+exports.compileMessagesFromSnapshot = compileMessagesFromSnapshot;
+/**
+ * Compiles a `text` prompt straight from the build-time snapshot, substituting
+ * the call-site variables into `fallbackText`. This is the offline path the
+ * generated `compile<Prompt>()` helpers use: no Langfuse fetch, no validation
+ * gate, no cache — an unknown name compiles to an empty string rather than
+ * throwing, so a snapshot that lags a prompt rename degrades instead of
+ * crashing the caller.
+ */
+function compileTextFromSnapshot(options) {
+    const entry = options.snapshot[options.name];
+    return substituteVariables(entry ? entry.fallbackText : '', options.variables);
+}
+/**
+ * The `chat` counterpart of `compileTextFromSnapshot`: substitutes into every
+ * message's content and preserves the roles the prompt declares. An unknown
+ * name compiles to an empty message list.
+ */
+function compileMessagesFromSnapshot(options) {
+    const entry = options.snapshot[options.name];
+    const messages = entry ? entry.fallbackMessages : [];
+    return messages.map((message) => ({
+        role: message.role,
+        content: substituteVariables(message.content, options.variables),
+    }));
+}
+/**
+ * Replaces every `{{ variable }}` occurrence (surrounding whitespace optional)
+ * with its value. The replacement is passed as a function so a value containing
+ * `$&`, `$$` or `` $` `` is inserted verbatim instead of being expanded as a
+ * `String.replace` substitution pattern.
+ */
+function substituteVariables(text, variables) {
+    return Object.entries(variables).reduce((compiled, [key, value]) => compiled.replace(new RegExp(`{{\\s*${escapeRegExp(key)}\\s*}}`, 'g'), () => String(value)), text);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=snapshotRuntime.js.map

package/dist/client/snapshotRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotRuntime.js","sourceRoot":"","sources":["../../src/client/snapshotRuntime.ts"],"names":[],"mappings":";;AAcA,0DAMC;AAOD,kEAUC;AA/BD;;;;;;;GAOG;AACH,SAAgB,uBAAuB,CACrC,OAAmC;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;AACjF,CAAC;AAED;;;;GAIG;AACH,SAAgB,2BAA2B,CACzC,OAAmC;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAErD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC;KACjE,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAC1B,IAAY,EACZ,SAA2C;IAE3C,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,MAAM,CACrC,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAC1C,IAAI,MAAM,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,EACnD,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CACpB,EACD,IAAI,CACL,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC"}