@uselemma/tracing 3.0.3 → 4.0.0

package/dist/client.js

@@ -0,0 +1,660 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lemma = exports.TraceHandle = exports.TraceContext = exports.NoopSpanHandle = exports.SpanHandle = void 0;
+exports.active = active;
+const node_async_hooks_1 = require("node:async_hooks");
+const debug_mode_1 = require("./debug-mode");
+const activeTrace = new node_async_hooks_1.AsyncLocalStorage();
+function required(value, envName) {
+    if (value?.trim())
+        return value.trim();
+    throw new Error(`@uselemma/tracing: Missing ${envName}`);
+}
+function iso(value) {
+    if (value == null)
+        return value;
+    return value instanceof Date ? value.toISOString() : value;
+}
+function errorMessage(error) {
+    if (error == null)
+        return null;
+    return error instanceof Error ? error.message : String(error);
+}
+function timestampMs(value) {
+    if (value == null)
+        return null;
+    const ms = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+}
+function elapsedMs(start, end) {
+    const startMs = timestampMs(start);
+    const endMs = timestampMs(end);
+    if (startMs == null || endMs == null)
+        return undefined;
+    return Math.max(0, endMs - startMs);
+}
+function serializeAttribute(value) {
+    if (value == null)
+        return value;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function addDefined(attributes, key, value) {
+    if (value !== undefined)
+        attributes[key] = value;
+}
+function flattenMessage(attributes, prefix, message) {
+    if (message && typeof message === "object" && !Array.isArray(message)) {
+        for (const [key, value] of Object.entries(message)) {
+            addDefined(attributes, `${prefix}.message.${key}`, serializeAttribute(value));
+        }
+        return;
+    }
+    addDefined(attributes, `${prefix}.message.content`, serializeAttribute(message));
+}
+function flattenDocument(attributes, prefix, document) {
+    if (document && typeof document === "object" && !Array.isArray(document)) {
+        for (const [key, value] of Object.entries(document)) {
+            addDefined(attributes, `${prefix}.document.${key}`, serializeAttribute(value));
+        }
+        return;
+    }
+    addDefined(attributes, `${prefix}.document.content`, serializeAttribute(document));
+}
+function contractAttributes(options) {
+    const attributes = {};
+    addDefined(attributes, "input.mime_type", options.inputMimeType);
+    addDefined(attributes, "output.mime_type", options.outputMimeType);
+    addDefined(attributes, "llm.model_name", options.llmModelName ?? options.model);
+    addDefined(attributes, "llm.provider", options.llmProvider);
+    addDefined(attributes, "llm.system", options.llmSystem);
+    addDefined(attributes, "llm.invocation_parameters", serializeAttribute(options.llmInvocationParameters));
+    addDefined(attributes, "llm.tools", serializeAttribute(options.llmTools));
+    addDefined(attributes, "llm.token_count.prompt", options.llmTokenCountPrompt ?? options.usage?.inputTokens);
+    addDefined(attributes, "llm.token_count.completion", options.llmTokenCountCompletion ?? options.usage?.outputTokens);
+    addDefined(attributes, "llm.token_count.total", options.llmTokenCountTotal);
+    addDefined(attributes, "llm.prompt_template.template", options.llmPromptTemplate);
+    addDefined(attributes, "llm.prompt_template.variables", serializeAttribute(options.llmPromptTemplateVariables));
+    addDefined(attributes, "llm.prompt_template.version", options.llmPromptTemplateVersion);
+    addDefined(attributes, "tool.description", options.toolDescription);
+    addDefined(attributes, "tool.parameters", serializeAttribute(options.toolParameters));
+    addDefined(attributes, "embedding.model_name", options.embeddingModelName);
+    addDefined(attributes, "embedding.invocation_parameters", serializeAttribute(options.embeddingInvocationParameters));
+    addDefined(attributes, "embedding.embeddings", serializeAttribute(options.embeddingEmbeddings));
+    addDefined(attributes, "reranker.model_name", options.rerankerModelName);
+    options.llmInputMessages?.forEach((message, index) => {
+        flattenMessage(attributes, `llm.input_messages.${index}`, message);
+    });
+    options.llmOutputMessages?.forEach((message, index) => {
+        flattenMessage(attributes, `llm.output_messages.${index}`, message);
+    });
+    options.retrievalDocuments?.forEach((document, index) => {
+        flattenDocument(attributes, `retrieval.documents.${index}`, document);
+    });
+    options.rerankerInputDocuments?.forEach((document, index) => {
+        flattenDocument(attributes, `reranker.input_documents.${index}`, document);
+    });
+    options.rerankerOutputDocuments?.forEach((document, index) => {
+        flattenDocument(attributes, `reranker.output_documents.${index}`, document);
+    });
+    return attributes;
+}
+function spanAttributes(options) {
+    const attributes = {
+        ...(options.attributes ?? {}),
+        ...contractAttributes(options),
+    };
+    return Object.keys(attributes).length > 0 ? attributes : undefined;
+}
+function normalizeSpan(options, fallbackType) {
+    const startedAt = options.startedAt ?? new Date();
+    const endedAt = options.endedAt ?? new Date();
+    return {
+        id: options.id,
+        parent_id: options.parentId ?? options.parentSpanId,
+        name: options.name,
+        type: options.type ?? fallbackType,
+        input: options.input,
+        output: options.output,
+        metadata: options.metadata,
+        attributes: spanAttributes(options),
+        started_at: iso(startedAt) ?? new Date().toISOString(),
+        ended_at: iso(endedAt) ?? new Date().toISOString(),
+        duration_ms: options.durationMs,
+        status: options.status ?? (options.error ? "ERROR" : undefined),
+        error: errorMessage(options.error),
+        model: options.model,
+        usage: options.usage
+            ? {
+                input_tokens: options.usage.inputTokens,
+                output_tokens: options.usage.outputTokens,
+            }
+            : undefined,
+        tool_name: options.toolName,
+    };
+}
+function warnNoop(message) {
+    console.warn(`@uselemma/tracing: ${message}`);
+}
+function isTraceEndOptions(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        ("output" in value || "durationMs" in value));
+}
+class SpanHandle {
+    trace;
+    options;
+    id;
+    ended = false;
+    payload;
+    constructor(trace, options, payload) {
+        this.trace = trace;
+        this.options = options;
+        this.id = options.id ?? crypto.randomUUID();
+        this.payload =
+            payload ??
+                this.trace.addSpan({
+                    ...this.options,
+                    id: this.id,
+                    startedAt: this.options.startedAt ?? new Date(),
+                    endedAt: this.options.endedAt ?? null,
+                });
+    }
+    end(options = {}) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        Object.assign(this.payload, normalizeSpan({
+            ...this.options,
+            ...options,
+            id: this.id,
+            startedAt: this.options.startedAt,
+            endedAt: options.endedAt ?? new Date(),
+        }, this.options.type ?? "span"));
+        this.trace.changed();
+    }
+    startSpan(options) {
+        const spanOptions = typeof options === "string" ? { name: options } : options;
+        return this.trace.startSpan({
+            ...spanOptions,
+            parentId: spanOptions.parentId ?? this.id,
+        });
+    }
+    startGeneration(options) {
+        const generationOptions = typeof options === "string" ? { name: options } : options;
+        return this.trace.startGeneration({
+            ...generationOptions,
+            parentId: generationOptions.parentId ?? this.id,
+        });
+    }
+    startTool(options) {
+        const toolOptions = typeof options === "string" ? { name: options } : options;
+        return this.trace.startTool({
+            ...toolOptions,
+            parentId: toolOptions.parentId ?? this.id,
+        });
+    }
+    recordSpan(options) {
+        const spanOptions = typeof options === "string" ? { name: options } : options;
+        return this.trace.recordSpan({
+            ...spanOptions,
+            parentId: spanOptions.parentId ?? this.id,
+        });
+    }
+    recordGeneration(options) {
+        const generationOptions = typeof options === "string" ? { name: options } : options;
+        this.trace.recordGeneration({
+            ...generationOptions,
+            parentId: generationOptions.parentId ?? this.id,
+        });
+    }
+    recordTool(options) {
+        const toolOptions = typeof options === "string" ? { name: options } : options;
+        this.trace.recordTool({
+            ...toolOptions,
+            parentId: toolOptions.parentId ?? this.id,
+        });
+    }
+    span(options) {
+        return typeof options === "string"
+            ? this.startSpan(options)
+            : this.recordSpan(options);
+    }
+    /** @deprecated Use recordGeneration() or startGeneration(). */
+    generation(options) {
+        this.recordGeneration(options);
+    }
+    /** @deprecated Use recordTool() or startTool(). */
+    tool(options) {
+        this.recordTool(options);
+    }
+}
+exports.SpanHandle = SpanHandle;
+class NoopSpanHandle {
+    id = "";
+    end() { }
+    startSpan() {
+        return this;
+    }
+    startGeneration() {
+        return this;
+    }
+    startTool() {
+        return this;
+    }
+    recordSpan() {
+        return this;
+    }
+    recordGeneration() { }
+    recordTool() { }
+    span() {
+        return this;
+    }
+    generation() { }
+    tool() { }
+}
+exports.NoopSpanHandle = NoopSpanHandle;
+class TraceContext {
+    options;
+    onChange;
+    spans = [];
+    traceOutput;
+    traceError = null;
+    id;
+    constructor(options, onChange) {
+        this.options = options;
+        this.onChange = onChange;
+        this.options.name ??= "trace";
+        this.options.id ??= crypto.randomUUID();
+        this.id = this.options.id;
+        this.traceOutput = options.output;
+    }
+    input(value) {
+        this.options.input = value;
+        this.changed();
+    }
+    output(value) {
+        this.traceOutput = value;
+        this.changed();
+    }
+    duration(durationMs) {
+        this.options.durationMs = durationMs;
+        this.changed();
+    }
+    fail(error) {
+        this.traceError = errorMessage(error);
+        this.changed();
+    }
+    changed() {
+        this.onChange?.();
+    }
+    setChangeHandler(onChange) {
+        this.onChange = onChange;
+    }
+    addSpan(options) {
+        const span = normalizeSpan(options, "span");
+        this.spans.push(span);
+        this.changed();
+        return span;
+    }
+    recordSpan(options) {
+        if (typeof options === "string") {
+            return this.startSpan({ name: options });
+        }
+        const spanId = options.id ?? crypto.randomUUID();
+        const span = this.addSpan({ ...options, id: spanId });
+        const handle = new SpanHandle(this, {
+            ...options,
+            id: spanId,
+            startedAt: span.started_at,
+            endedAt: span.ended_at,
+        }, span);
+        handle.end({ endedAt: span.ended_at ?? new Date() });
+        return handle;
+    }
+    recordGeneration(options) {
+        const generationOptions = typeof options === "string" ? { name: options } : options;
+        this.spans.push(normalizeSpan({ ...generationOptions, type: "generation" }, "generation"));
+        this.changed();
+    }
+    recordTool(options) {
+        const toolOptions = typeof options === "string" ? { name: options } : options;
+        this.spans.push(normalizeSpan({ ...toolOptions, type: "tool" }, "tool"));
+        this.changed();
+    }
+    startSpan(options) {
+        const spanOptions = typeof options === "string" ? { name: options } : options;
+        return new SpanHandle(this, {
+            ...spanOptions,
+            id: spanOptions.id ?? crypto.randomUUID(),
+            startedAt: spanOptions.startedAt ?? new Date(),
+        });
+    }
+    startGeneration(options) {
+        return this.startSpan({ ...options, type: "generation" });
+    }
+    startTool(options) {
+        return this.startSpan({ ...options, type: "tool" });
+    }
+    span(options) {
+        return typeof options === "string"
+            ? this.startSpan(options)
+            : this.recordSpan(options);
+    }
+    /** @deprecated Use recordGeneration() or startGeneration(). */
+    generation(options) {
+        this.recordGeneration(options);
+    }
+    /** @deprecated Use recordTool() or startTool(). */
+    tool(options) {
+        this.recordTool(options);
+    }
+    toPayload(projectId, startedAt, endedAt, replace = false) {
+        return {
+            project_id: projectId,
+            trace: {
+                id: this.options.id,
+                name: this.options.name ?? "trace",
+                input: this.options.input,
+                output: this.traceOutput,
+                metadata: this.options.metadata,
+                thread_id: this.options.threadId,
+                user_id: this.options.userId,
+                environment: this.options.environment,
+                started_at: startedAt.toISOString(),
+                ended_at: endedAt.toISOString(),
+                duration_ms: this.options.durationMs ?? elapsedMs(startedAt, endedAt),
+                status: this.traceError ? "ERROR" : undefined,
+                error: this.traceError,
+                spans: this.spans,
+            },
+            replace,
+        };
+    }
+}
+exports.TraceContext = TraceContext;
+class TraceHandle extends TraceContext {
+    flushFn;
+    startedAt;
+    flushTimer;
+    flushPromise = Promise.resolve();
+    constructor(options, flushFn, startedAt = new Date()) {
+        super(options);
+        this.flushFn = flushFn;
+        this.startedAt = startedAt;
+        this.setChangeHandler(() => this.scheduleFlush());
+        this.scheduleFlush();
+    }
+    flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        const endedAt = new Date();
+        this.flushPromise = this.flushPromise.then(() => this.flushFn(this, this.startedAt, endedAt));
+        return this.flushPromise;
+    }
+    async end(outputOrOptions) {
+        if (isTraceEndOptions(outputOrOptions)) {
+            if ("output" in outputOrOptions) {
+                this.output(outputOrOptions.output);
+            }
+            if (outputOrOptions.durationMs != null) {
+                this.duration(outputOrOptions.durationMs);
+            }
+        }
+        else if (arguments.length > 0) {
+            this.output(outputOrOptions);
+        }
+        await this.flush();
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = undefined;
+            void this.flush().catch(() => {
+                // Surface delivery failures to callers that await flush/end.
+            });
+        }, 0);
+    }
+}
+exports.TraceHandle = TraceHandle;
+class Lemma {
+    apiKey;
+    projectId;
+    baseUrl;
+    fetchImpl;
+    traces = new Map();
+    constructor(options = {}) {
+        this.apiKey = required(options.apiKey ?? process.env.LEMMA_API_KEY, "LEMMA_API_KEY");
+        this.projectId = required(options.projectId ?? process.env.LEMMA_PROJECT_ID, "LEMMA_PROJECT_ID");
+        this.baseUrl = (options.baseUrl ?? "https://api.uselemma.ai").replace(/\/+$/, "");
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    trace(options = {}, fn) {
+        const traceOptions = typeof options === "string" ? { name: options } : options;
+        if (!fn) {
+            const handle = new TraceHandle(traceOptions, (trace, startedAt, endedAt) => this.flushTrace(trace, startedAt, endedAt, true));
+            this.traces.set(handle.id, handle);
+            (0, debug_mode_1.lemmaDebug)("client", "trace handle created", {
+                traceId: handle.id,
+                name: traceOptions.name ?? "trace",
+            });
+            return handle;
+        }
+        const context = new TraceContext(traceOptions);
+        const startedAt = new Date();
+        (0, debug_mode_1.lemmaDebug)("client", "trace started", {
+            traceId: context.id,
+            name: traceOptions.name ?? "trace",
+        });
+        return (async () => {
+            try {
+                const result = await activeTrace.run(context, () => fn(context));
+                if (traceOptions.output === undefined) {
+                    context.output(result);
+                }
+                await this.flushTrace(context, startedAt, new Date());
+                return result;
+            }
+            catch (error) {
+                context.fail(error);
+                await this.flushTrace(context, startedAt, new Date());
+                throw error;
+            }
+        })();
+    }
+    recordSpan(options) {
+        if (typeof options === "string") {
+            return active().recordSpan(options);
+        }
+        const context = this.detachedTraceFor(options.traceId, "span");
+        if (!context)
+            return new NoopSpanHandle();
+        const { traceId: _traceId, parentSpanId, parentId, ...spanOptions } = options;
+        if (parentId && !parentSpanId) {
+            warnNoop("span has a parent, but parentSpanId was not provided; skipping span");
+            return new NoopSpanHandle();
+        }
+        return context.recordSpan({
+            name: "span",
+            ...spanOptions,
+            parentId: parentSpanId ?? null,
+        });
+    }
+    recordGeneration(options) {
+        if (typeof options === "string") {
+            active().recordGeneration(options);
+            return;
+        }
+        const context = this.detachedTraceFor(options.traceId, "generation");
+        if (!context)
+            return;
+        const { traceId: _traceId, parentSpanId, parentId, ...generationOptions } = options;
+        if (parentId && !parentSpanId) {
+            warnNoop("generation has a parent, but parentSpanId was not provided; skipping generation");
+            return;
+        }
+        context.recordGeneration({
+            name: "generation",
+            ...generationOptions,
+            parentId: parentSpanId ?? null,
+        });
+    }
+    recordTool(options) {
+        if (typeof options === "string") {
+            active().recordTool(options);
+            return;
+        }
+        const context = this.detachedTraceFor(options.traceId, "tool");
+        if (!context)
+            return;
+        const { traceId: _traceId, parentSpanId, parentId, ...toolOptions } = options;
+        if (parentId && !parentSpanId) {
+            warnNoop("tool has a parent, but parentSpanId was not provided; skipping tool");
+            return;
+        }
+        context.recordTool({
+            name: "tool",
+            ...toolOptions,
+            parentId: parentSpanId ?? null,
+        });
+    }
+    startSpan(options) {
+        if ("traceId" in options) {
+            const context = this.detachedTraceFor(options.traceId, "span");
+            if (!context)
+                return new NoopSpanHandle();
+            const { traceId: _traceId, parentSpanId, parentId, ...spanOptions } = options;
+            if (parentId && !parentSpanId) {
+                warnNoop("span has a parent, but parentSpanId was not provided; skipping span");
+                return new NoopSpanHandle();
+            }
+            return context.startSpan({
+                name: "span",
+                ...spanOptions,
+                parentId: parentSpanId ?? null,
+            });
+        }
+        return active().startSpan(options);
+    }
+    startGeneration(options) {
+        if ("traceId" in options) {
+            const context = this.detachedTraceFor(options.traceId, "generation");
+            if (!context)
+                return new NoopSpanHandle();
+            const { traceId: _traceId, parentSpanId, parentId, ...generationOptions } = options;
+            if (parentId && !parentSpanId) {
+                warnNoop("generation has a parent, but parentSpanId was not provided; skipping generation");
+                return new NoopSpanHandle();
+            }
+            return context.startGeneration({
+                name: "generation",
+                ...generationOptions,
+                parentId: parentSpanId ?? null,
+            });
+        }
+        return active().startGeneration(options);
+    }
+    startTool(options) {
+        if ("traceId" in options) {
+            const context = this.detachedTraceFor(options.traceId, "tool");
+            if (!context)
+                return new NoopSpanHandle();
+            const { traceId: _traceId, parentSpanId, parentId, ...toolOptions } = options;
+            if (parentId && !parentSpanId) {
+                warnNoop("tool has a parent, but parentSpanId was not provided; skipping tool");
+                return new NoopSpanHandle();
+            }
+            return context.startTool({
+                name: "tool",
+                ...toolOptions,
+                parentId: parentSpanId ?? null,
+            });
+        }
+        return active().startTool(options);
+    }
+    /** @deprecated Use startSpan() or recordSpan(). */
+    span(options) {
+        return typeof options === "string"
+            ? active().startSpan({ name: options })
+            : this.recordSpan(options);
+    }
+    /** @deprecated Use recordGeneration() or startGeneration(). */
+    generation(options) {
+        this.recordGeneration(options);
+    }
+    /** @deprecated Use recordTool() or startTool(). */
+    tool(options) {
+        this.recordTool(options);
+    }
+    traceFor(traceId) {
+        const trace = this.traces.get(traceId);
+        if (!trace) {
+            throw new Error(`@uselemma/tracing: unknown trace id "${traceId}"`);
+        }
+        return trace;
+    }
+    detachedTraceFor(traceId, kind) {
+        if (!traceId) {
+            warnNoop(`${kind} handle requires traceId; skipping ${kind}`);
+            return null;
+        }
+        const trace = this.traces.get(traceId);
+        if (!trace) {
+            warnNoop(`unknown trace id "${traceId}"; skipping ${kind}`);
+            return null;
+        }
+        return trace;
+    }
+    async flushTrace(context, startedAt, endedAt, replace = false) {
+        const payload = context.toPayload(this.projectId, startedAt, endedAt, replace);
+        const url = `${this.baseUrl}/traces/ingest`;
+        (0, debug_mode_1.lemmaDebug)("client", "sending trace", {
+            traceId: payload.trace.id,
+            name: payload.trace.name,
+            spanCount: payload.trace.spans.length,
+            url,
+            replace,
+        });
+        const response = await this.fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            (0, debug_mode_1.lemmaDebug)("client", "trace ingest failed", {
+                traceId: payload.trace.id,
+                status: response.status,
+                body,
+            });
+            throw new Error(`@uselemma/tracing: failed to ingest trace (${response.status})${body ? `: ${body}` : ""}`);
+        }
+        (0, debug_mode_1.lemmaDebug)("client", "trace sent", {
+            traceId: payload.trace.id,
+            status: response.status,
+        });
+    }
+}
+exports.Lemma = Lemma;
+function active() {
+    const trace = activeTrace.getStore();
+    if (!trace) {
+        throw new Error("@uselemma/tracing: no active trace context");
+    }
+    return trace;
+}
+//# sourceMappingURL=client.js.map