@mate-academy/llm-gateway 7.5.0 → 8.0.0-canary.0

package/README.md

@@ -59,6 +59,7 @@ npm install @mate-academy/llm-gateway
 ## Features
 
 - Support for multiple LLM providers (OpenAI, Google Generative AI)
+- **Langfuse Tracing**: Required, env-driven Langfuse observability constructed once per process. Generations, tool observations, usage, and cost are captured automatically at every LLM call; fire-and-forget so a tracing failure never blocks or fails a call. Disabled cleanly via the `LangfuseDisabled` token or absent env.
 - **Structured Output**: Type-safe JSON responses with schema validation
 - **Extensible Schema Architecture**: Driver pattern with provider-specific adapters
 - **LLM Metrics & Reporting**: Comprehensive metrics collection with automatic cost calculation
@@ -79,6 +80,169 @@ npm install @mate-academy/llm-gateway
 
 ## Usage
 
+### Langfuse Tracing
+
+Tracing is configured from environment once per process at the composition root
+(the consumer's DI container / serverless core) and injected — feature code never
+touches Langfuse credentials. Construct it with `createLangfuseTracer`, which
+reads the connection config and registers the active tracer. Missing credentials
+or the explicit `LangfuseDisabled` token resolve to a no-op tracer, so nothing
+breaks before rollout.
+
+```typescript
+import {
+  createLangfuseTracer,
+  LangfuseDisabled,
+  withLLMTrace,
+  flushLLMTraces,
+} from '@mate-academy/llm-gateway';
+
+// Once per process, at the composition root:
+const tracer = createLangfuseTracer(
+  process.env.LANGFUSE_PUBLIC_KEY
+    ? {
+        baseUrl: process.env.LANGFUSE_BASE_URL,
+        publicKey: process.env.LANGFUSE_PUBLIC_KEY,
+        secretKey: process.env.LANGFUSE_SECRET_KEY,
+        environment: process.env.LANGFUSE_ENVIRONMENT,
+        // 'batched' for long-running processes, 'immediate' for Lambda
+        exportMode: 'batched',
+      }
+    : LangfuseDisabled,
+);
+```
+
+Once constructed, every gateway completion / assistance call emits a Langfuse
+`generation` observation (full prompt/completion content, model, params, usage,
+cost) at the same success/error points the metrics reporter already wraps;
+assistance tool loops emit a child `tool` observation per tool call. All of this
+is fire-and-forget — a Langfuse failure never blocks or fails an LLM call.
+
+For code outside a traced base class, wrap work in a trace so nested gateway
+calls attach to it automatically:
+
+```typescript
+await withLLMTrace('my-operation', { feature: 'city-prediction' }, async () => {
+  // gateway calls here nest under the trace via OTel context
+});
+```
+
+Short-lived processes (Lambdas, scripts) must flush before exit, since buffered
+events are lost otherwise:
+
+```typescript
+await flushLLMTraces(); // alias of the SDK forceFlush; safe no-op when disabled
+```
+
+The CloudWatch fallback-serving metric (`LangfuseFallbackServed`, namespace
+`LLMGateway`) is exposed via `emitLangfuseFallbackServed`; inject a real emitter
+with `setFallbackMetricEmitter` at the composition root (defaults to a no-op so
+the package carries no AWS dependency).
+
+To assert emitted observations in tests, inject an OTel `InMemorySpanExporter`
+via the `spanExporter` config field (export mode defaults to `immediate` when one
+is set, so `flush()` makes spans available synchronously):
+
+```typescript
+import { InMemorySpanExporter } from '@opentelemetry/sdk-trace-base';
+
+const exporter = new InMemorySpanExporter();
+const tracer = createLangfuseTracer({ ...config, spanExporter: exporter });
+
+await tracer.withTrace('MyUseCase', {}, async () => {
+  // ... gateway calls ...
+});
+await tracer.flush();
+
+const names = exporter.getFinishedSpans().map((span) => span.name);
+```
+
+### v2 Client (`createLLMClient`)
+
+The v2 client is the prompt-name-first call surface. A call site names the
+operation (the Langfuse prompt name); everything else — prompt text, model,
+provider, params, credentials, reporter wiring, tracing, structured output —
+resolves from it inside the package. Build it once at the composition root and
+inject it via DI; feature code never sees configuration or credentials.
+
+```typescript
+import {
+  createLLMClient,
+  defineLLMPrompts,
+  LLMSchema,
+} from '@mate-academy/llm-gateway';
+import { LLMPrompt, langfusePromptSnapshot } from './langfusePrompts.generated';
+
+const llmPromptRegistry = defineLLMPrompts({
+  [LLMPrompt.CityPredictionPredictCityName]: {
+    schema: LLMSchema.object({ cityName: LLMSchema.string().nullable() }),
+  },
+});
+
+const llm = createLLMClient({
+  registry: llmPromptRegistry,
+  snapshot: langfusePromptSnapshot,
+  credentials: async ({ provider, promptName, product }) => providerOptions,
+  reporting: { reporter },
+  logger,
+  context: { product, appEnvironment },
+  mode: 'production',
+});
+
+const { cityName } = await llm.generate(
+  LLMPrompt.CityPredictionPredictCityName,
+  { variables: { locationName, countryName }, context: { userId } },
+);
+```
+
+- **Typed end to end.** The client is generic over `typeof registry`. Variables
+  are typed from the generated snapshot (strict on required names, tolerant of
+  extras so a Langfuse edit can never break a build); the return type is the
+  bound schema's inferred type, or `string` when no schema is bound.
+- **Single validation gate on every fetch.** Vars subset, `config` zod-parse,
+  provider/model in the gateway map, param ceilings, and the resolved model's
+  capabilities vs the registry `requires`. Any failure serves the last-known-good
+  snapshot and emits the `LangfuseFallbackServed` metric; `LLMConfigError` throws
+  only when the live config and the fallback are both unusable.
+- **Errors throw with a taxonomy** (`LLMGatewayError` base + `LLMProviderError`,
+  `LLMSchemaValidationError`, `LLMAbortedError`, `LLMConfigError`); validated
+  `data` is the return value, never an `'error' in response` union.
+- **Override gating.** `mode: 'production'` rejects per-call `overrides` with
+  `LLMConfigError`; only `mode: 'experiment'` (harness/playground/tests) honors
+  them.
+- **Chat-type prompts.** A prompt seeded as a Langfuse `chat` prompt binds with
+  `kind: 'chat'`. `compile()` produces a role-tagged message array with variables
+  substituted across every message; at call time a leading `system` message maps
+  to the provider's instructions slot and the final `user` message is the request,
+  preserving the message structure the prompt declares (plan §1.2). The validation
+  gate checks the variable subset across all message contents.
+- **Per-call schema override.** Pass `schema` in the `generate` options to override
+  the registry binding's schema for one call; the return type follows the call-site
+  schema. Use it when the output contract is dynamic (e.g. a schema whose shape
+  depends on runtime input). A binding may omit `schema` when callers always pass
+  one. The schema is the code-owned output contract, honored in every mode.
+- **`describePrompt(name)`.** Read-only accessor returning the
+  `{ provider, model, promptVersion, isFallback }` the runtime would serve right
+  now (same resolve/cache/fallback path as `generate`, no provider call). Use it
+  where analytics events need the resolved model name — keeping it off `generate`'s
+  data-only return.
+
+#### Prompt snapshot codegen
+
+`langfusePrompts.generated.ts` is produced by `npm run langfuse:generate` (root),
+which fetches every labeled prompt and emits the `LLMPrompt` enum, per-prompt
+variable unions, typed `compile()` helpers, and the snapshot used as the outage
+fallback. It is gitignored exactly like GraphQL generated files: regenerated
+locally on demand, in CI before image builds (with a cached-artifact fallback so a
+Langfuse outage never fails a build), and refreshed non-blocking at API pod boot.
+
+#### Escape hatch
+
+`@mate-academy/llm-gateway/advanced` re-exports `LLMServiceFactory`, the provider
+services, and the model maps for the rare call site needing raw control. It
+bypasses prompt management, the validation gate, and config-in-prompt routing —
+prefer the v2 client.
+
 ### Logger Interface
 
 The package accepts an optional logger that implements the `LLMLoggerInterface` interface. Most logging libraries are compatible (`@mate-academy/logger`, winston, pino, etc.). If no logger is provided, no logging will occur.

package/dist/LLMService.typedefs.d.ts

@@ -248,6 +248,11 @@ export type LLMCompletionResult = LLMRequestResult<{
  */
 export type LLMMethodBaseOptions<Reporter extends LLMReporterInterface<any> | undefined> = {
     abortSignal?: AbortSignal;
+    /**
+     * Per-call Langfuse trace context. The prompt name (PR2) names the generation
+     * observation; absent it, the base service falls back to `<service>/<method>`.
+     */
+    traceContext?: LLMCallTraceContext;
 } & (Reporter extends LLMReporterInterface<infer R> ? R extends undefined ? {
     reporterContext?: never;
 } : {
@@ -255,6 +260,14 @@ export type LLMMethodBaseOptions<Reporter extends LLMReporterInterface<any> | un
 } : {
     reporterContext?: never;
 });
+/**
+ * Per-call trace context threaded into a single gateway call. PR2 supplies the
+ * prompt name; PR1 only wires the threading.
+ */
+export type LLMCallTraceContext = {
+    promptName?: string;
+    metadata?: Record<string, string | number | boolean>;
+};
 /**
  * Options for sending a message to an LLM service.
  * @template Provider - The LLM provider type
@@ -274,8 +287,6 @@ export type LLMStructuredResult<T = any> = LLMRequestResult<{
     text: string;
     data?: T;
     parseError?: string;
-    toolIterationsUsed?: number;
-    toolIterationsExhausted?: true;
 }>;
 /**
  * Limits for files that can be uploaded to LLM services.
@@ -390,8 +401,6 @@ export type LLMAssistanceOptions<Provider extends LLMProviders, Reporter extends
  */
 export type LLMAssistanceResult = LLMRequestResult<{
     text: string;
-    toolIterationsUsed?: number;
-    toolIterationsExhausted?: true;
 }>;
 /**
  * Options for a one-shot prompt in a newly created chat.

package/dist/LLMService.typedefs.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAkCA;;GAEG;AACH,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yDAAyC,CAAA;IACzC,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAoBD;;GAEG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,wCAAyB,CAAA;IACzB,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB;AAiLD;;GAEG;AACH,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,mCAAuB,CAAA;AACzB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;GAEG;AACH,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,gDAAuB,CAAA;IACvB,kDAAyB,CAAA;AAC3B,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AA8HD;;GAEG;AACH,IAAY,sBAeX;AAfD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,yDAA+B,CAAA;IAC/B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,oDAA0B,CAAA;IAC1B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;AACzB,CAAC,EAfW,sBAAsB,sCAAtB,sBAAsB,QAejC"}
+{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAkCA;;GAEG;AACH,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yDAAyC,CAAA;IACzC,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAoBD;;GAEG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,wCAAyB,CAAA;IACzB,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB;AAiLD;;GAEG;AACH,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,mCAAuB,CAAA;AACzB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;GAEG;AACH,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,gDAAuB,CAAA;IACvB,kDAAyB,CAAA;AAC3B,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AA0ID;;GAEG;AACH,IAAY,sBAeX;AAfD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,yDAA+B,CAAA;IAC/B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,oDAA0B,CAAA;IAC1B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;AACzB,CAAC,EAfW,sBAAsB,sCAAtB,sBAAsB,QAejC"}

package/dist/advanced.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+export { LLMServiceFactory } from './LLMService.factory';
+export { LLM_SERVICE_FACTORIES, LLM_SERVICE_MODELS, } from './LLMService.constants';
+export * from './providers';
+export * from './services';

package/dist/advanced.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_SERVICE_MODELS = exports.LLM_SERVICE_FACTORIES = exports.LLMServiceFactory = void 0;
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+var LLMService_factory_1 = require("./LLMService.factory");
+Object.defineProperty(exports, "LLMServiceFactory", { enumerable: true, get: function () { return LLMService_factory_1.LLMServiceFactory; } });
+var LLMService_constants_1 = require("./LLMService.constants");
+Object.defineProperty(exports, "LLM_SERVICE_FACTORIES", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_FACTORIES; } });
+Object.defineProperty(exports, "LLM_SERVICE_MODELS", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_MODELS; } });
+__exportStar(require("./providers"), exports);
+__exportStar(require("./services"), exports);
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAC1B,+DAGgC;AAF9B,6HAAA,qBAAqB,OAAA;AACrB,0HAAA,kBAAkB,OAAA;AAEpB,8CAA4B;AAC5B,6CAA2B"}

package/dist/client/codegen/extractVariables.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extracts the plain variable names a prompt references, matching the runtime
+ * compile path (only `{{var}}` survives the conditional drop, see plan §1.3).
+ * Section/closer tokens (`{{#cond}}`, `{{/cond}}`) are excluded so the generated
+ * required-variable set agrees with what the validation gate counts as provided.
+ */
+export declare function extractRequiredVariables(promptText: string): string[];

package/dist/client/codegen/extractVariables.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractRequiredVariables = extractRequiredVariables;
+const VARIABLE_PATTERN = /{{\s*([\w.]+)\s*}}/g;
+/**
+ * Extracts the plain variable names a prompt references, matching the runtime
+ * compile path (only `{{var}}` survives the conditional drop, see plan §1.3).
+ * Section/closer tokens (`{{#cond}}`, `{{/cond}}`) are excluded so the generated
+ * required-variable set agrees with what the validation gate counts as provided.
+ */
+function extractRequiredVariables(promptText) {
+    const names = new Set();
+    for (const match of promptText.matchAll(VARIABLE_PATTERN)) {
+        const token = match[1];
+        if (!token.startsWith('#') && !token.startsWith('/')) {
+            names.add(token);
+        }
+    }
+    return [...names].sort();
+}
+//# sourceMappingURL=extractVariables.js.map

package/dist/client/codegen/extractVariables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractVariables.js","sourceRoot":"","sources":["../../../src/client/codegen/extractVariables.ts"],"names":[],"mappings":";;AAQA,4DAYC;AApBD,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAE/C;;;;;GAKG;AACH,SAAgB,wBAAwB,CAAC,UAAkB;IACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAEvB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC"}

package/dist/client/codegen/fetchPromptRecords.d.ts

@@ -0,0 +1,14 @@
+import { type LangfuseClient } from '@langfuse/client';
+import { type CodegenPromptRecord } from '../../client/codegen/renderSnapshot';
+export interface FetchPromptRecordsOptions {
+    label: string;
+    onWarn?: (message: string) => void;
+}
+/**
+ * Fetches every prompt that carries the given label from the Langfuse project and
+ * shapes it into a codegen record. A prompt whose `config` does not satisfy the
+ * gateway schema is skipped with a warning rather than failing the build — the
+ * governor (PR3) is the edit-time gate; codegen never crashes on a bad live
+ * config so a Langfuse edit can never break a build.
+ */
+export declare function fetchPromptRecords(client: LangfuseClient, options: FetchPromptRecordsOptions): Promise<CodegenPromptRecord[]>;

package/dist/client/codegen/fetchPromptRecords.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPromptRecords = fetchPromptRecords;
+const llmConfig_schema_1 = require("../../client/llmConfig.schema");
+const extractVariables_1 = require("../../client/codegen/extractVariables");
+const CHAT_MESSAGE_ROLES = [
+    'system',
+    'user',
+    'assistant',
+];
+const DEFAULT_PAGE_SIZE = 100;
+/**
+ * Fetches every prompt that carries the given label from the Langfuse project and
+ * shapes it into a codegen record. A prompt whose `config` does not satisfy the
+ * gateway schema is skipped with a warning rather than failing the build — the
+ * governor (PR3) is the edit-time gate; codegen never crashes on a bad live
+ * config so a Langfuse edit can never break a build.
+ */
+async function fetchPromptRecords(client, options) {
+    const names = await listPromptNames(client, options.label);
+    const records = [];
+    for (const name of names) {
+        const record = await fetchSingleRecord(client, name, options);
+        if (record) {
+            records.push(record);
+        }
+    }
+    return records;
+}
+async function listPromptNames(client, label) {
+    const names = [];
+    const collectPage = async (page) => {
+        const response = await client.api.prompts.list({
+            label,
+            page,
+            limit: DEFAULT_PAGE_SIZE,
+        });
+        for (const meta of response.data) {
+            names.push(meta.name);
+        }
+        return response.meta.totalPages;
+    };
+    const totalPages = await collectPage(1);
+    for (let page = 2; page <= totalPages; page += 1) {
+        await collectPage(page);
+    }
+    return names;
+}
+async function fetchSingleRecord(client, name, options) {
+    const prompt = await client.api.prompts.get(name, { label: options.label });
+    const parsedConfig = llmConfig_schema_1.llmPromptConfigSchema.safeParse(prompt.config);
+    if (!parsedConfig.success) {
+        options.onWarn?.(`Skipping "${name}": config does not satisfy the gateway schema `
+            + `(${parsedConfig.error.issues.map((issue) => issue.message).join('; ')})`);
+        return undefined;
+    }
+    const kind = prompt.type;
+    const fallbackText = kind === 'text' ? String(prompt.prompt) : '';
+    const fallbackMessages = kind === 'chat' ? toFallbackMessages(prompt.prompt) : [];
+    const variableSource = kind === 'chat'
+        ? fallbackMessages.map((message) => message.content).join('\n')
+        : fallbackText;
+    return {
+        name,
+        kind,
+        version: prompt.version,
+        labels: prompt.labels,
+        requiredVariables: (0, extractVariables_1.extractRequiredVariables)(variableSource),
+        fallbackText,
+        fallbackMessages,
+        config: parsedConfig.data,
+    };
+}
+function toFallbackMessages(promptBody) {
+    if (!Array.isArray(promptBody)) {
+        return [];
+    }
+    return promptBody.flatMap((message) => {
+        if (!isRecord(message)) {
+            return [];
+        }
+        const role = String(message.role ?? '');
+        if (!isKnownRole(role)) {
+            return [];
+        }
+        return [{ role, content: String(message.content ?? '') }];
+    });
+}
+function isKnownRole(role) {
+    return CHAT_MESSAGE_ROLES.includes(role);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+//# sourceMappingURL=fetchPromptRecords.js.map

package/dist/client/codegen/fetchPromptRecords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchPromptRecords.js","sourceRoot":"","sources":["../../../src/client/codegen/fetchPromptRecords.ts"],"names":[],"mappings":";;AA8BA,gDAgBC;AA7CD,gEAAkE;AAMlE,wEAA6E;AAG7E,MAAM,kBAAkB,GAAoC;IAC1D,QAAQ;IACR,MAAM;IACN,WAAW;CACZ,CAAC;AAEF,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAO9B;;;;;;GAMG;AACI,KAAK,UAAU,kBAAkB,CACtC,MAAsB,EACtB,OAAkC;IAElC,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,OAAO,GAA0B,EAAE,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAE9D,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,MAAsB,EACtB,KAAa;IAEb,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,KAAK,EAAE,IAAY,EAAmB,EAAE;QAC1D,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;YAC7C,KAAK;YACL,IAAI;YACJ,KAAK,EAAE,iBAAiB;SACzB,CAAC,CAAC;QAEH,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACjC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;IAClC,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,CAAC,CAAC,CAAC;IAExC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,UAAU,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,iBAAiB,CAC9B,MAAsB,EACtB,IAAY,EACZ,OAAkC;IAElC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5E,MAAM,YAAY,GAAG,wCAAqB,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEpE,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1B,OAAO,CAAC,MAAM,EAAE,CACd,aAAa,IAAI,gDAAgD;cAC/D,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5E,CAAC;QAEF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAqB,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClE,MAAM,gBAAgB,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,MAAM,cAAc,GAAG,IAAI,KAAK,MAAM;QACpC,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC/D,CAAC,CAAC,YAAY,CAAC;IAEjB,OAAO;QACL,IAAI;QACJ,IAAI;QACJ,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,iBAAiB,EAAE,IAAA,2CAAwB,EAAC,cAAc,CAAC;QAC3D,YAAY;QACZ,gBAAgB;QAChB,MAAM,EAAE,YAAY,CAAC,IAAI;KAC1B,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,UAAmB;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QACpC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAExC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC"}

package/dist/client/codegen/generateSnapshot.d.ts

@@ -0,0 +1,18 @@
+export interface GenerateSnapshotOptions {
+    baseUrl: string;
+    publicKey: string;
+    secretKey: string;
+    label: string;
+    outputPath: string;
+    onLog?: (message: string) => void;
+}
+/**
+ * The codegen entry point invoked by `npm run langfuse:generate`. Lists labeled
+ * prompts from the project, validates each config, renders the snapshot file, and
+ * writes it to `outputPath`. An empty project is valid: it produces an empty but
+ * type-correct snapshot. The caller owns the CI cached-artifact fallback (this
+ * throws on an unreachable Langfuse host so the caller can fall back).
+ */
+export declare function generateSnapshot(options: GenerateSnapshotOptions): Promise<{
+    promptCount: number;
+}>;

package/dist/client/codegen/generateSnapshot.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSnapshot = generateSnapshot;
+const node_fs_1 = require("node:fs");
+const client_1 = require("@langfuse/client");
+const fetchPromptRecords_1 = require("../../client/codegen/fetchPromptRecords");
+const renderSnapshot_1 = require("../../client/codegen/renderSnapshot");
+/**
+ * The codegen entry point invoked by `npm run langfuse:generate`. Lists labeled
+ * prompts from the project, validates each config, renders the snapshot file, and
+ * writes it to `outputPath`. An empty project is valid: it produces an empty but
+ * type-correct snapshot. The caller owns the CI cached-artifact fallback (this
+ * throws on an unreachable Langfuse host so the caller can fall back).
+ */
+async function generateSnapshot(options) {
+    const log = options.onLog ?? (() => undefined);
+    const client = new client_1.LangfuseClient({
+        baseUrl: options.baseUrl,
+        publicKey: options.publicKey,
+        secretKey: options.secretKey,
+    });
+    log(`Fetching prompts labeled "${options.label}" from ${options.baseUrl}`);
+    const records = await (0, fetchPromptRecords_1.fetchPromptRecords)(client, {
+        label: options.label,
+        onWarn: (message) => log(message),
+    });
+    const fileContent = (0, renderSnapshot_1.renderSnapshotFile)(records, { onWarn: (message) => log(message) });
+    (0, node_fs_1.writeFileSync)(options.outputPath, fileContent, 'utf8');
+    log(`Wrote ${records.length} prompt(s) to ${options.outputPath}`);
+    return { promptCount: records.length };
+}
+//# sourceMappingURL=generateSnapshot.js.map

package/dist/client/codegen/generateSnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateSnapshot.js","sourceRoot":"","sources":["../../../src/client/codegen/generateSnapshot.ts"],"names":[],"mappings":";;AAqBA,4CAwBC;AA7CD,qCAAwC;AACxC,6CAAkD;AAClD,4EAAyE;AACzE,oEAAqE;AAWrE;;;;;;GAMG;AACI,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,uBAAc,CAAC;QAChC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;KAC7B,CAAC,CAAC;IAEH,GAAG,CAAC,6BAA6B,OAAO,CAAC,KAAK,UAAU,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAG,MAAM,IAAA,uCAAkB,EAAC,MAAM,EAAE;QAC/C,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;KAClC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,IAAA,mCAAkB,EAAC,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEvF,IAAA,uBAAa,EAAC,OAAO,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAEvD,GAAG,CAAC,SAAS,OAAO,CAAC,MAAM,iBAAiB,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAElE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;AACzC,CAAC"}

package/dist/client/codegen/index.d.ts

@@ -0,0 +1,5 @@
+export * from './extractVariables';
+export * from './promptName';
+export * from './renderSnapshot';
+export * from './fetchPromptRecords';
+export * from './generateSnapshot';

package/dist/client/codegen/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./extractVariables"), exports);
+__exportStar(require("./promptName"), exports);
+__exportStar(require("./renderSnapshot"), exports);
+__exportStar(require("./fetchPromptRecords"), exports);
+__exportStar(require("./generateSnapshot"), exports);
+//# sourceMappingURL=index.js.map

package/dist/client/codegen/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/codegen/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+CAA6B;AAC7B,mDAAiC;AACjC,uDAAqC;AACrC,qDAAmC"}

package/dist/client/codegen/promptName.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a Langfuse prompt name (`<feature-slug>/<operation>`, kebab-case with
+ * slash-separated virtual folders) into the PascalCase `LLMPrompt` enum member.
+ * `city-prediction/predict-city-name` → `CityPredictionPredictCityName`. The
+ * underscore subprompt convention (`_sections`) is preserved as a segment so
+ * section prompts get distinct members.
+ */
+export declare function promptNameToEnumMember(promptName: string): string;

package/dist/client/codegen/promptName.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptNameToEnumMember = promptNameToEnumMember;
+/**
+ * Converts a Langfuse prompt name (`<feature-slug>/<operation>`, kebab-case with
+ * slash-separated virtual folders) into the PascalCase `LLMPrompt` enum member.
+ * `city-prediction/predict-city-name` → `CityPredictionPredictCityName`. The
+ * underscore subprompt convention (`_sections`) is preserved as a segment so
+ * section prompts get distinct members.
+ */
+function promptNameToEnumMember(promptName) {
+    return promptName
+        .split(/[/\-_]/)
+        .filter((segment) => segment.length > 0)
+        .map(capitalize)
+        .join('');
+}
+function capitalize(segment) {
+    return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+//# sourceMappingURL=promptName.js.map

package/dist/client/codegen/promptName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promptName.js","sourceRoot":"","sources":["../../../src/client/codegen/promptName.ts"],"names":[],"mappings":";;AAOA,wDAMC;AAbD;;;;;;GAMG;AACH,SAAgB,sBAAsB,CAAC,UAAkB;IACvD,OAAO,UAAU;SACd,KAAK,CAAC,QAAQ,CAAC;SACf,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,GAAG,CAAC,UAAU,CAAC;SACf,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,OAAe;IACjC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/client/codegen/renderSnapshot.d.ts

@@ -0,0 +1,25 @@
+import { type LLMPromptConfig } from '../../client/llmConfig.schema';
+import { type LLMPromptKind, type LLMPromptMessage } from '../../client/promptSnapshot.typedefs';
+export interface CodegenPromptRecord {
+    name: string;
+    kind: LLMPromptKind;
+    version: number;
+    labels: string[];
+    requiredVariables: string[];
+    fallbackText: string;
+    fallbackMessages: LLMPromptMessage[];
+    config: LLMPromptConfig;
+}
+export interface RenderSnapshotOptions {
+    onWarn?: (message: string) => void;
+}
+/**
+ * Renders the full `langfusePrompts.generated.ts` content from fetched prompt
+ * records: the `LLMPrompt` enum, per-prompt required-variable unions, the
+ * `LLMPromptVariableMap` the client infers from, typed `compile()` helpers
+ * (strict on required vars, tolerant of extras), and the snapshot constant used
+ * as the outage fallback. A prompt whose enum member is not a valid TS
+ * identifier is skipped with a warning rather than emitted — a hostile prompt
+ * name can never produce a file that fails the build.
+ */
+export declare function renderSnapshotFile(records: CodegenPromptRecord[], options?: RenderSnapshotOptions): string;