@telemetry-dev/sdk 0.1.10 → 0.1.12

package/README.md

@@ -111,6 +111,72 @@ The default is parent-based always-on. Session roots keep the configured root po
 Nested spans and explicitly parented spans keep the real parent's policy.
 The SDK installs the [session sampling wrapper](https://github.com/telemetry-dev/telemetry/blob/main/packages/otel/README.md#correlation-attributes) on its provider. This includes the global provider that Eve uses.
 
+## Prompts
+
+`getPrompt` fetches a prompt that you manage in telemetry.dev. Fetch it by its label, so that you
+deploy a version when you move the label, without a change to the code:
+
+```ts
+import OpenAI from "openai";
+import { getPrompt, init, withPrompt } from "@telemetry-dev/sdk";
+import { wrapOpenAI } from "@telemetry-dev/openai";
+
+init();
+const openai = wrapOpenAI(new OpenAI());
+
+const prompt = await getPrompt("support/reply", { label: "production" });
+const messages = prompt.compile({ customer_message, tone });
+
+const response = await withPrompt(prompt, () =>
+  openai.chat.completions.create({ model: prompt.model?.name ?? "gpt-4o", messages }),
+);
+
+// Pin one version, as in a test:
+const pinned = await getPrompt("support/reply", { version: 13 });
+```
+
+- Without `label` and `version`, getPrompt fetches the `production` label. A text prompt needs
+  `type: "text"`; getPrompt rejects a prompt of the other type.
+- `compile(variables)` puts the values in place of `{{name}}`. A missing value becomes an empty
+  text, and a value that is not a string becomes JSON. In a chat prompt, a placeholder message
+  becomes the list of messages in its variable. A text prompt compiles to a string.
+- The prompt also has `model`, `parameters`, `tools`, and `responseFormat` of its version.
+- getPrompt keeps each prompt. When the copy is older than `cacheTtlSeconds` (default 60), a call
+  returns it at once and fetches a new copy in the background. Only a call with no copy waits for a
+  fetch, for 10 seconds at most. Calls for the same prompt share one fetch.
+- If a fetch fails, getPrompt returns the last copy that it fetched and reports the error through
+  `onError`. With no copy, it returns the `fallback` option (`version` is `null` and `isFallback`
+  is `true`). With no fallback, it rejects with a `PromptError` whose `code` tells why, for
+  example `prompt_not_found`, `label_not_found`, `insufficient_scope`, `missing_api_key`, or
+  `timeout`. A response with a different status and no API error gives `http_<status>`, for
+  example `http_302` for a redirect. getPrompt does not send the request to the location of a
+  redirect, thus your key does not go to a different host. With no copy, the calls of the next 10
+  seconds (or the TTL, if it is shorter) get the same result without a fetch. After a 429 or 503
+  response with a `Retry-After` header, getPrompt does not fetch that prompt again before that time
+  (one hour at most). This is the one SDK function that can reject: your app cannot run without
+  its prompt.
+- getPrompt uses the API key and base URL of an enabled `init()`, or `TELEMETRY_DEV_API_KEY` and
+  `TELEMETRY_DEV_BASE_URL`, or its own `apiKey`, `baseUrl`, and `fetch` options. It reads the same
+  host that telemetry goes to, `https://ingest.telemetry.dev` by default. The key needs the read
+  scope for prompts.
+- When a label sends part of the traffic to a second version, each session keeps one version: the
+  choice uses the session id of `propagateAttributes` (or of `sessionMode: "process"`). Without a
+  session id, each call chooses at random.
+
+`withPrompt(prompt, fn)` records the prompt on each model call that starts inside `fn`:
+`td.prompt.name`, `td.prompt.version`, and `td.prompt.label` (only for a prompt fetched by label).
+When input capture is on, `td.prompt.variables` holds the JSON of the variables of the last
+`compile()` of that prompt object before `withPrompt` starts, or of the last `compile()` inside
+`fn`, after `mask` and truncation. If tasks that run at the same time share one prompt object, call
+`compile()` in `withPrompt`, or call getPrompt in each task. getPrompt returns a new object from
+the cache. If you do not, a task can record the variables of a different task. Tasks that run at the
+same time inside one `withPrompt` share its variables, so call `withPrompt` in each task that
+compiles its own. Model calls are the spans of type `generation` (operations `chat`,
+`text_completion`, and `generate_content`), including the spans of the provider integrations that
+use this SDK: OpenAI, Anthropic, Amazon Bedrock, Google GenAI, and OpenRouter. Spans from the AI SDK
+and TanStack AI integrations, and from other OpenTelemetry tracers, do not get the attributes.
+Messages from `compile()` that you pass to a model call outside `withPrompt` are not recorded.
+
 ## API
 
 - `init(options?)` — create the client (isolated OTel TracerProvider by default).
@@ -130,6 +196,8 @@ The SDK installs the [session sampling wrapper](https://github.com/telemetry-dev
 - `updateActiveSpan(fields)` — update the innermost active span.
 - `propagateAttributes({ userId, sessionId, metadata }, fn)` — stamps `user.id`,
   `gen_ai.conversation.id`, and `td.metadata.*` on every span and log record in scope.
+- `getPrompt(name, options?)` — fetch a prompt by label or version; see [Prompts](#prompts).
+- `withPrompt(prompt, fn)` — record the prompt on each model call in `fn`.
 - `log(message, { level, eventName, attributes }?)` — log record correlated to the active trace.
 - `getTraceparent()` — W3C traceparent of the active span (pass to other services; accept it via
   `startSpan(name, { parent })`).

package/dist/index.d.mts

@@ -16,7 +16,7 @@ type MaskFn<T = unknown> = (value: T, ctx: {
 interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;
@@ -257,4 +257,158 @@ interface ObserveOptions extends StartSpanOptions {
  */
 declare function observe<TThis, TArgs extends unknown[], TReturn>(fn: (this: TThis, ...args: TArgs) => TReturn, options?: ObserveOptions): (...args: TArgs) => TReturn;
 //#endregion
-export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ClientOverrides, type ExportMode, type GenerationFields, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+//#region src/prompts.d.ts
+/** A message of a chat prompt. A placeholder stands for a list of messages that the app passes. */
+type PromptMessage = {
+  readonly role: "system" | "user" | "assistant";
+  readonly content: string;
+} | {
+  readonly role: "placeholder";
+  readonly name: string;
+};
+/** A message that `compile()` makes from a prompt message. */
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+interface PromptModel {
+  readonly provider: string;
+  readonly name: string;
+}
+/** The parameters that are set in the version. A parameter that is not set is absent. */
+interface PromptParameters {
+  readonly temperature?: number;
+  readonly topP?: number;
+  readonly maxTokens?: number;
+  readonly frequencyPenalty?: number;
+  readonly presencePenalty?: number;
+  readonly stop?: readonly string[];
+  readonly seed?: number;
+  readonly toolChoice?: "auto" | "none" | "required" | {
+    readonly tool: string;
+  };
+  readonly parallelToolCalls?: boolean;
+}
+interface PromptTool {
+  readonly name: string;
+  readonly description: string;
+  /** JSON schema of the tool arguments. */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly strict: boolean;
+}
+type PromptResponseFormat = {
+  readonly type: "text";
+} | {
+  readonly type: "json_object";
+} | {
+  readonly type: "json_schema";
+  readonly name: string;
+  readonly schema: Readonly<Record<string, unknown>>;
+  readonly strict: boolean;
+};
+/**
+ * Values for `{{name}}` variables. A missing value, null, or undefined becomes an empty text, and a
+ * value that is not a string becomes JSON. A placeholder message takes a list of messages.
+ */
+type PromptVariables<M = ChatMessage> = Readonly<Record<string, string | number | boolean | null | undefined | readonly M[]>>;
+interface PromptBase {
+  readonly name: string;
+  /** The version that the app got; null for the fallback. */
+  readonly version: number | null;
+  /** The label that the prompt was fetched by; null when it was fetched by version. */
+  readonly label: string | null;
+  /** Null for the fallback. */
+  readonly model: PromptModel | null;
+  readonly parameters: PromptParameters;
+  readonly tools: readonly PromptTool[];
+  readonly responseFormat: PromptResponseFormat;
+  /** True when getPrompt could not fetch the prompt and returned the `fallback` option. */
+  readonly isFallback: boolean;
+}
+interface ChatPrompt extends PromptBase {
+  readonly type: "chat";
+  readonly messages: readonly PromptMessage[];
+  readonly text: null;
+  /**
+   * Fills in the variables and replaces each placeholder message with the messages in its
+   * variable. `withPrompt` records the variables of the last call before it starts or inside it.
+   */
+  compile<M = ChatMessage>(variables?: PromptVariables<M>): (ChatMessage | M)[];
+}
+interface TextPrompt extends PromptBase {
+  readonly type: "text";
+  readonly messages: readonly [];
+  readonly text: string;
+  /**
+   * Fills in the variables. `withPrompt` records the variables of the last call before it starts
+   * or inside it.
+   */
+  compile(variables?: PromptVariables): string;
+}
+type Prompt = ChatPrompt | TextPrompt;
+interface GetPromptOptionsBase {
+  /** Fetch the version that this label points to. Default "production" when `version` is not set. */
+  label?: string;
+  /** Fetch this version number. Do not set it together with `label`. */
+  version?: number;
+  /** Seconds before a call fetches a kept prompt again, in the background. Default 60. */
+  cacheTtlSeconds?: number;
+  /** API key with the prompts:read scope. Falls back to the initialized client, then `TELEMETRY_DEV_API_KEY`. */
+  apiKey?: string;
+  /** Falls back to the initialized client, then `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  baseUrl?: string;
+  /** Falls back to the initialized client's `fetch`, then `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+interface GetChatPromptOptions extends GetPromptOptionsBase {
+  /** Default "chat". getPrompt rejects a prompt of the other type. */
+  type?: "chat";
+  /** Messages to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: readonly PromptMessage[];
+}
+interface GetTextPromptOptions extends GetPromptOptionsBase {
+  type: "text";
+  /** Text to use when the prompt cannot be fetched and no copy of it is kept. */
+  fallback?: string;
+}
+type GetPromptOptions = GetChatPromptOptions | GetTextPromptOptions;
+/**
+ * Why getPrompt failed. `code` is the code of the API error (`prompt_not_found`,
+ * `label_not_found`, `insufficient_scope`, `invalid_api_key`, …), or `missing_api_key`,
+ * `timeout`, `network_error`, `invalid_response`, or `type_mismatch`. A response with a different
+ * status and no API error gives `http_<status>`, for example `http_302` for a redirect: getPrompt
+ * does not go to the location of a redirect.
+ */
+declare class PromptError extends Error {
+  readonly code: string;
+  readonly status?: number | undefined;
+  readonly name = "PromptError";
+  constructor(code: string, message: string, status?: number | undefined, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Fetches a prompt version from telemetry.dev and keeps it. When the copy is older than
+ * `cacheTtlSeconds`, a call returns it at once and fetches a new one in the background. Only a call
+ * with no copy waits for a fetch, at most 10 seconds. Calls for the same prompt share one fetch.
+ * When a fetch fails, getPrompt returns the last copy that it kept; with no copy it returns
+ * `fallback`. With neither it rejects with a `PromptError`: unlike the telemetry functions,
+ * getPrompt cannot fail open, because the app cannot run without the prompt. With no copy, the
+ * calls of the next 10 seconds (or the TTL, if it is shorter) fail the same way without a fetch.
+ *
+ * A label with a gradual rollout gives each session one version: the choice uses the session id
+ * of `propagateAttributes`, or a random choice per call without one.
+ */
+declare function getPrompt(name: string, options: GetTextPromptOptions): Promise<TextPrompt>;
+declare function getPrompt(name: string, options?: GetChatPromptOptions): Promise<ChatPrompt>;
+/**
+ * Runs `fn` with `prompt` as the prompt of each model call (generation span) that starts inside
+ * it: the spans get `td.prompt.name`, `td.prompt.version`, `td.prompt.label`, and, when input
+ * capture is on, `td.prompt.variables`. The variables are those of the last `compile()` of this
+ * prompt object before withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
+ * another task does not change them once withPrompt runs. Concurrent tasks in `fn` share the
+ * variables, so call withPrompt in each task that compiles its own.
+ */
+declare function withPrompt<T>(prompt: Prompt, fn: () => T): T;
+//#endregion
+export { type AgentFields, type BatchOptions, type BoundedCaptureDetails, type BoundedCaptureOptions, type BoundedCaptureResult, type ChatMessage, type ChatPrompt, type ClientOverrides, type ExportMode, type GenerationFields, type GetChatPromptOptions, type GetPromptOptions, type GetTextPromptOptions, type LogLevel, type LogOptions, type MaskFn, type ObserveOptions, type ParentRef, type Prompt, PromptError, type PromptMessage, type PromptModel, type PromptParameters, type PromptResponseFormat, type PromptTool, type PromptVariables, type PropagatedAttributes, SCOPE_NAME, type SdkLogLevel, type SpanCapturePolicy, type SpanFields, type SpanHandle, type SpanType, type StartSpanOptions, type TelemetryClient, type TelemetryOptions, TelemetrySpanProcessor, type TelemetrySpanProcessorOptions, type TextPrompt, type TokenUsage, type ToolFields, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getPrompt, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext, withPrompt };

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
+import { INVALID_SPAN_CONTEXT, ROOT_CONTEXT, SpanKind, SpanStatusCode, context, createContextKey, defaultTextMapGetter, defaultTextMapSetter, propagation, trace } from "@opentelemetry/api";
 import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator, parseTraceParent } from "@opentelemetry/core";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { BatchLogRecordProcessor, LoggerProvider, SimpleLogRecordProcessor } from "@opentelemetry/sdk-logs";
 import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
-import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createExportFailures, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
+import { AlsContextManager, BATCHED_METRIC_INTERVAL_MS, DEFAULT_BASE_URL, DEFAULT_BATCH, DORMANT_INTERVAL_MS, DURATION_BUCKETS, OUTPUT_CHUNK_HISTOGRAM, PROPAGATED_KEY, SCOPE_NAME, SCOPE_NAME as SCOPE_NAME$1, SCOPE_VERSION, StampingSpanProcessor, TelemetrySpanProcessor, activeContext, activeContext as activeContext$1, als, createExportFailures, createLogExporter, createMetricExporter, createMetricsPipeline, createTraceExporter, diag, jsonAttr, omitUndefined, otlpHeaders, propagateAttributes, propagatedFromContext, reportError, resolveEnv, sessionIdOf, sessionRootTracerProvider, sessionSampler, setLogLevel, sha256, withContext, withContext as withContext$1, withSessionParent } from "@telemetry-dev/otel";
 import { SeverityNumber } from "@opentelemetry/api-logs";
 //#region src/config.ts
 const DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536;
@@ -546,6 +546,330 @@ const NOOP_SPAN_HANDLE = {
 	end: () => {}
 };
 //#endregion
+//#region src/prompts.ts
+/**
+* Why getPrompt failed. `code` is the code of the API error (`prompt_not_found`,
+* `label_not_found`, `insufficient_scope`, `invalid_api_key`, …), or `missing_api_key`,
+* `timeout`, `network_error`, `invalid_response`, or `type_mismatch`. A response with a different
+* status and no API error gives `http_<status>`, for example `http_302` for a redirect: getPrompt
+* does not go to the location of a redirect.
+*/
+var PromptError = class extends Error {
+	name = "PromptError";
+	constructor(code, message, status, options) {
+		super(message, options);
+		this.code = code;
+		this.status = status;
+	}
+};
+const FETCH_TIMEOUT_MS = 1e4;
+/** The longest Retry-After that getPrompt honors, so that a bad header cannot stop fetches. */
+const MAX_RETRY_AFTER_MS = 36e5;
+/** How long a failed fetch with no copy answers calls, so that they do not each fetch again. */
+const ERROR_TTL_MS = 1e4;
+const MAX_CACHE_ENTRIES = 1e3;
+/** IMF-fixdate, the HTTP date that servers send: `Sun, 06 Nov 1994 08:49:37 GMT`. */
+const HTTP_DATE = /^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+const VARIABLE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+const MODEL_CALL_OPERATIONS = new Set([
+	"chat",
+	"text_completion",
+	"generate_content"
+]);
+const PROMPT_KEY = createContextKey("telemetry.dev prompt");
+const cache = /* @__PURE__ */ new Map();
+const compiledVariables = /* @__PURE__ */ new WeakMap();
+/** The Retry-After of the response that failed with this error, in milliseconds. */
+const retryAfter = /* @__PURE__ */ new WeakMap();
+async function getPrompt(name, options = {}) {
+	const type = options.type ?? "chat";
+	checkOptions(name, options, type);
+	const core = currentClient().core;
+	const env = resolveEnv();
+	const apiKey = options.apiKey ?? core?.config.apiKey ?? env.TELEMETRY_DEV_API_KEY;
+	const baseUrl = (options.baseUrl || core?.config.baseUrl || env.TELEMETRY_DEV_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+	const label = options.version === void 0 ? options.label ?? "production" : null;
+	const onError = core?.config.onError;
+	let response;
+	try {
+		if (!apiKey) throw new PromptError("missing_api_key", "No API key: pass apiKey or set TELEMETRY_DEV_API_KEY");
+		const url = new URL(`${baseUrl}/v1/prompts`);
+		url.searchParams.set("name", name);
+		if (label === null) url.searchParams.set("version", String(options.version));
+		else url.searchParams.set("label", label);
+		response = await load([
+			baseUrl,
+			keyFingerprint(apiKey),
+			name,
+			label === null ? `version:${options.version}` : `label:${label}`
+		].join("\0"), (options.cacheTtlSeconds ?? 60) * 1e3, () => fetchPrompt(url, {
+			authorization: `Bearer ${apiKey}`,
+			"x-telemetry-dev-sdk": core?.config.sdkName ?? "@telemetry-dev/sdk"
+		}, options.fetch ?? core?.config.fetchImpl ?? globalThis.fetch), onError);
+	} catch (error) {
+		if (options.fallback === void 0) throw error;
+		reportError(onError, error);
+		return createPrompt({
+			name,
+			type,
+			label,
+			version: null,
+			isFallback: true,
+			content: {
+				messages: type === "chat" ? options.fallback : [],
+				text: type === "text" ? options.fallback : null,
+				model: null,
+				parameters: {},
+				tools: [],
+				responseFormat: { type: "text" }
+			}
+		});
+	}
+	if (response.type !== type) throw new PromptError("type_mismatch", `${name} is a ${response.type} prompt; pass type: "${response.type}"`);
+	const chosen = response.rollout && inRollout(response) ? response.rollout : response;
+	return createPrompt({
+		name: response.name,
+		type,
+		label: response.label,
+		version: chosen.version,
+		isFallback: false,
+		content: chosen
+	});
+}
+/**
+* Runs `fn` with `prompt` as the prompt of each model call (generation span) that starts inside
+* it: the spans get `td.prompt.name`, `td.prompt.version`, `td.prompt.label`, and, when input
+* capture is on, `td.prompt.variables`. The variables are those of the last `compile()` of this
+* prompt object before withPrompt starts, or of the last `compile()` inside `fn`, so a compile in
+* another task does not change them once withPrompt runs. Concurrent tasks in `fn` share the
+* variables, so call withPrompt in each task that compiles its own.
+*/
+function withPrompt(prompt, fn) {
+	const scope = {
+		prompt,
+		variables: compiledVariables.get(prompt)
+	};
+	return withContext$1(activeContext$1().setValue(PROMPT_KEY, scope), fn);
+}
+/** The td.prompt.* attributes for a span with this operation that starts in `ctx`. */
+function promptAttributes(ctx, operation, capture) {
+	if (!MODEL_CALL_OPERATIONS.has(operation)) return void 0;
+	const scope = ctx.getValue(PROMPT_KEY) ?? activeContext$1().getValue(PROMPT_KEY);
+	if (!scope) return void 0;
+	const { prompt, variables } = scope;
+	return omitUndefined({
+		"td.prompt.name": prompt.name,
+		"td.prompt.version": prompt.version ?? void 0,
+		"td.prompt.label": prompt.label ?? void 0,
+		"td.prompt.variables": variables !== void 0 && capture.captureInput ? prepareCaptureValue("td.prompt.variables", variables, capture) : void 0
+	});
+}
+function checkOptions(name, options, type) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("name must be a non-empty string");
+	if (type !== "chat" && type !== "text") throw new TypeError("type must be \"chat\" or \"text\"");
+	if (options.label !== void 0 && options.version !== void 0) throw new TypeError("Pass label or version, not both");
+	if (options.version !== void 0 && (!Number.isSafeInteger(options.version) || options.version < 1)) throw new RangeError("version must be a positive integer");
+	const ttl = options.cacheTtlSeconds;
+	if (ttl !== void 0 && !(Number.isFinite(ttl) && ttl >= 0)) throw new RangeError("cacheTtlSeconds must be a non-negative number");
+	if (options.fallback !== void 0 && (type === "chat" ? !Array.isArray(options.fallback) : typeof options.fallback !== "string")) throw new TypeError(type === "chat" ? "fallback must be a list of messages" : "fallback must be a string");
+}
+/**
+* Returns the kept copy of a prompt, and fetches a new copy in the background when it is older
+* than the TTL. Only a call with no copy waits for a fetch. A failed fetch with no copy fails the
+* calls of the next ERROR_TTL_MS (or the TTL, if it is shorter) without a fetch.
+*/
+async function load(key, ttlMs, fetchResponse, onError) {
+	let entry = cache.get(key);
+	if (!entry) {
+		if (cache.size >= MAX_CACHE_ENTRIES) cache.delete(cache.keys().next().value);
+		entry = {
+			checkedAt: 0,
+			retryAt: 0
+		};
+		cache.set(key, entry);
+	}
+	const fresh = Date.now() < Math.max(entry.checkedAt + (entry.response ? ttlMs : Math.min(ttlMs, ERROR_TTL_MS)), entry.retryAt);
+	if (entry.response) {
+		if (!fresh) entry.pending ??= refresh(entry, fetchResponse, onError);
+		return entry.response;
+	}
+	if (fresh) throw entry.error;
+	return entry.pending ??= refresh(entry, fetchResponse, onError);
+}
+function refresh(entry, fetchResponse, onError) {
+	return fetchResponse().then((response) => {
+		entry.response = response;
+		entry.retryAt = 0;
+		return response;
+	}, (error) => {
+		const delay = error instanceof PromptError ? retryAfter.get(error) : void 0;
+		entry.retryAt = delay === void 0 ? 0 : Date.now() + delay;
+		if (!entry.response) {
+			entry.error = error;
+			throw error;
+		}
+		reportError(onError, error);
+		return entry.response;
+	}).finally(() => {
+		entry.checkedAt = Date.now();
+		entry.pending = void 0;
+	});
+}
+async function fetchPrompt(url, headers, fetchImpl) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+	try {
+		const res = await fetchImpl(url, {
+			method: "GET",
+			headers,
+			signal: controller.signal,
+			redirect: "manual"
+		});
+		const body = await res.json().catch(() => void 0);
+		if (!res.ok) {
+			const error = isRecord(body) && isRecord(body.error) ? body.error : {};
+			const failure = new PromptError(typeof error.code === "string" ? error.code : `http_${res.status}`, typeof error.message === "string" ? error.message : `telemetry.dev returned ${res.status}`, res.status);
+			const delay = retryAfterMs(res);
+			if (delay !== void 0) retryAfter.set(failure, delay);
+			throw failure;
+		}
+		const response = parseResponse(body);
+		if (!response) throw new PromptError("invalid_response", "telemetry.dev returned a prompt it cannot read");
+		return response;
+	} catch (error) {
+		if (controller.signal.aborted) throw new PromptError("timeout", `Fetching the prompt took more than ${FETCH_TIMEOUT_MS} ms`);
+		if (error instanceof PromptError) throw error;
+		throw new PromptError("network_error", "Could not reach telemetry.dev", void 0, { cause: error });
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function createPrompt(input) {
+	const { content, type } = input;
+	const prompt = Object.freeze({
+		name: input.name,
+		type,
+		version: input.version,
+		label: input.label,
+		messages: content.messages,
+		text: content.text,
+		model: content.model,
+		parameters: content.parameters,
+		tools: content.tools,
+		responseFormat: content.responseFormat,
+		isFallback: input.isFallback,
+		compile(variables = {}) {
+			compiledVariables.set(prompt, variables);
+			const scope = activeContext$1().getValue(PROMPT_KEY);
+			if (scope?.prompt === prompt) scope.variables = variables;
+			return type === "chat" ? compileMessages(content.messages, variables) : fill(content.text ?? "", variables);
+		}
+	});
+	return prompt;
+}
+function compileMessages(messages, variables) {
+	return messages.flatMap((message) => {
+		if (message.role !== "placeholder") return [{
+			role: message.role,
+			content: fill(message.content, variables)
+		}];
+		const value = Object.hasOwn(variables, message.name) ? variables[message.name] : void 0;
+		if (value == null) return [];
+		if (!Array.isArray(value)) throw new TypeError(`The ${message.name} variable must be a list of messages`);
+		return value;
+	});
+}
+function fill(text, variables) {
+	return text.replace(VARIABLE, (_tag, name) => {
+		const value = Object.hasOwn(variables, name) ? variables[name] : void 0;
+		if (value == null) return "";
+		return typeof value === "string" ? value : jsonAttr(value) ?? "";
+	});
+}
+function inRollout(response) {
+	const sessionId = sessionIdOf(activeContext$1()) ?? currentClient().core?.config.processSessionId;
+	return (sessionId === void 0 ? Math.floor(Math.random() * 100) : fnv1a(`${response.name}:${response.label}:${sessionId}`) % 100) < response.rollout.percent;
+}
+function fnv1a(text) {
+	let hash = 2166136261;
+	for (const byte of new TextEncoder().encode(text)) hash = Math.imul(hash ^ byte, 16777619) >>> 0;
+	return hash;
+}
+function keyFingerprint(apiKey) {
+	const digest = sha256(new TextEncoder().encode(apiKey)).subarray(0, 16);
+	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The Retry-After of a 429 or 503 response, as seconds or an IMF-fixdate HTTP date, capped. */
+function retryAfterMs(res) {
+	if (res.status !== 429 && res.status !== 503) return void 0;
+	const value = res.headers.get("retry-after")?.trim();
+	if (!value) return void 0;
+	let ms;
+	if (/^\d+$/.test(value)) ms = Number(value) * 1e3;
+	else if (HTTP_DATE.test(value)) ms = Date.parse(value) - Date.now();
+	else return void 0;
+	return ms > 0 ? Math.min(ms, MAX_RETRY_AFTER_MS) : void 0;
+}
+function parseResponse(body) {
+	if (!isRecord(body)) return void 0;
+	const { name, type, label, version, rollout } = body;
+	if (typeof name !== "string" || type !== "chat" && type !== "text" || label !== null && typeof label !== "string" || !isVersion(version)) return;
+	const content = parseContent(body, type);
+	if (!content) return void 0;
+	if (rollout == null) return deepFreeze({
+		name,
+		type,
+		label,
+		version,
+		...content,
+		rollout: null
+	});
+	if (!isRecord(rollout) || !isVersion(rollout.version) || !Number.isInteger(rollout.percent) || rollout.percent < 0 || rollout.percent > 100) return;
+	const rolloutContent = parseContent(rollout, type);
+	if (!rolloutContent) return void 0;
+	return deepFreeze({
+		name,
+		type,
+		label,
+		version,
+		...content,
+		rollout: {
+			percent: rollout.percent,
+			version: rollout.version,
+			...rolloutContent
+		}
+	});
+}
+function parseContent(value, type) {
+	const { messages, text, model, parameters, tools, responseFormat } = value;
+	if (!(type === "chat" ? Array.isArray(messages) && messages.every(isPromptMessage) : typeof text === "string") || !isRecord(model) || typeof model.provider !== "string" || typeof model.name !== "string" || !isRecord(parameters) || !Array.isArray(tools) || !tools.every((tool) => isRecord(tool) && typeof tool.name === "string") || !isRecord(responseFormat) || typeof responseFormat.type !== "string") return;
+	return {
+		messages: type === "chat" ? messages : [],
+		text: type === "text" ? text : null,
+		model,
+		parameters,
+		tools,
+		responseFormat
+	};
+}
+function isPromptMessage(value) {
+	if (!isRecord(value)) return false;
+	return value.role === "placeholder" ? typeof value.name === "string" : (value.role === "system" || value.role === "user" || value.role === "assistant") && typeof value.content === "string";
+}
+function isVersion(value) {
+	return Number.isSafeInteger(value) && value >= 1;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepFreeze(value) {
+	if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const item of Object.values(value)) deepFreeze(item);
+	}
+	return value;
+}
+//#endregion
 //#region src/span.ts
 const SPAN_META = /* @__PURE__ */ new WeakMap();
 const SEVERITY_ERROR = 17;
@@ -621,6 +945,7 @@ function createSpanHandle(core, name, options = {}) {
 		"gen_ai.conversation.id": sessionId
 	}), sessionId, core.config.apiKey);
 	const attrs = fieldsToAttributes(options, meta.type, meta.capture);
+	const operation = attrs["gen_ai.operation.name"] ?? SPAN_TYPE_OPERATIONS[meta.type];
 	const span = core.tracer.startSpan(name, {
 		kind: options.kind ?? SpanKind.INTERNAL,
 		startTime: options.startTime,
@@ -628,6 +953,7 @@ function createSpanHandle(core, name, options = {}) {
 		attributes: {
 			"gen_ai.operation.name": SPAN_TYPE_OPERATIONS[meta.type],
 			...propagatedFromContext(parentCtx),
+			...promptAttributes(parentCtx, operation, meta.capture),
 			...attrs
 		}
 	}, parentCtx);
@@ -815,4 +1141,4 @@ function observe(fn, options) {
 	return wrapped;
 }
 //#endregion
-export { SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext };
+export { PromptError, SCOPE_NAME, TelemetrySpanProcessor, activeContext, boundedCapture, boundedCaptureDetails, captureEnabled, captureMasked, extractW3cContext, flush, getPrompt, getTraceparent, init, injectW3cContext, log, observe, propagateAttributes, shutdown, startActiveSpan, startSpan, updateActiveSpan, withContext, withPrompt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telemetry-dev/sdk",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Pure TypeScript SDK for telemetry.dev: LLM traces, logs, and GenAI metrics on OpenTelemetry, for Node and edge runtimes.",
   "keywords": [
     "genai",

package/src/config.ts

@@ -22,7 +22,7 @@ export type MaskFn<T = unknown> = (value: T, ctx: { key: string }) => T;
 export interface TelemetryOptions {
   /** telemetry.dev ingest key (`td_live_…`). Falls back to `TELEMETRY_DEV_API_KEY`. When absent the SDK is a no-op. */
   apiKey?: string;
-  /** Ingest base URL. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
+  /** Base URL for telemetry export and getPrompt. Falls back to `TELEMETRY_DEV_BASE_URL`, then `https://ingest.telemetry.dev`. */
   baseUrl?: string;
   /** Deployment environment label. Falls back to `TELEMETRY_DEV_ENVIRONMENT`, then `production`. */
   environment?: string;

package/src/index.ts

@@ -46,6 +46,25 @@ export { log, type LogOptions } from "./logs.ts";
 
 export { observe, type ObserveOptions } from "./observe.ts";
 
+export {
+  type ChatMessage,
+  type ChatPrompt,
+  type GetChatPromptOptions,
+  getPrompt,
+  type GetPromptOptions,
+  type GetTextPromptOptions,
+  type Prompt,
+  PromptError,
+  type PromptMessage,
+  type PromptModel,
+  type PromptParameters,
+  type PromptResponseFormat,
+  type PromptTool,
+  type PromptVariables,
+  type TextPrompt,
+  withPrompt,
+} from "./prompts.ts";
+
 export {
   activeContext,
   extractW3cContext,