@kernl-sdk/lmnr 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @kernl-sdk/lmnr@0.1.0 build /Users/andjones/Documents/projects/kernl/packages/observability/laminar
+> tsc && tsc-alias --resolve-full-paths
+

package/dist/convert.d.ts

@@ -0,0 +1,8 @@
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { SpanData, EventData } from "kernl/tracing";
+export type SpanType = "DEFAULT" | "LLM" | "TOOL";
+export declare const SPAN_NAME: Codec<SpanData, string>;
+export declare const SPAN_TYPE: Codec<SpanData["kind"], SpanType>;
+export declare const SPAN_INPUT: Codec<SpanData, Record<string, unknown>>;
+export declare const EVENT_ATTRIBUTES: Codec<EventData, Record<string, string | number | boolean>>;
+//# sourceMappingURL=convert.d.ts.map

package/dist/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../src/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEzD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAElD,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAgB7C,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAgBvD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ/D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAClC,SAAS,EACT,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAoB1C,CAAC"}

package/dist/convert.js

@@ -0,0 +1,62 @@
+export const SPAN_NAME = {
+    encode: (data) => {
+        switch (data.kind) {
+            case "thread":
+                return `thread.${data.agentId}`;
+            case "model.call":
+                return `model.${data.provider}.${data.modelId}`;
+            case "tool.call":
+                return `tool.${data.toolId}`;
+            default:
+                return `kernl.unknown`;
+        }
+    },
+    decode: () => {
+        throw new Error("SPAN_NAME.decode: unimplemented");
+    },
+};
+export const SPAN_TYPE = {
+    encode: (kind) => {
+        switch (kind) {
+            case "thread":
+                return "DEFAULT";
+            case "model.call":
+                return "LLM";
+            case "tool.call":
+                return "TOOL";
+            default:
+                return "DEFAULT";
+        }
+    },
+    decode: () => {
+        throw new Error("SPAN_TYPE.decode: unimplemented");
+    },
+};
+export const SPAN_INPUT = {
+    encode: (data) => {
+        const { kind, ...rest } = data;
+        return rest;
+    },
+    decode: () => {
+        throw new Error("SPAN_INPUT.decode: unimplemented");
+    },
+};
+export const EVENT_ATTRIBUTES = {
+    encode: (data) => {
+        const result = {};
+        for (const [key, value] of Object.entries(data)) {
+            if (typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean") {
+                result[key] = value;
+            }
+            else if (value !== undefined) {
+                result[key] = JSON.stringify(value);
+            }
+        }
+        return result;
+    },
+    decode: () => {
+        throw new Error("EVENT_ATTRIBUTES.decode: unimplemented");
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { LaminarTracer, type LaminarTracerOptions } from "./subscriber.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { LaminarTracer } from "./subscriber.js";

package/dist/subscriber.d.ts

@@ -0,0 +1,87 @@
+import type { Subscriber, SpanId, SpanData, EventData } from "kernl/tracing";
+export interface LaminarTracerOptions {
+    /**
+     * Laminar project API key.
+     * If not provided, uses the LMNR_PROJECT_API_KEY environment variable.
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the Laminar API.
+     * Defaults to https://api.lmnr.ai
+     */
+    baseUrl?: string;
+    /**
+     * Tags to apply to all spans.
+     */
+    tags?: string[];
+    /**
+     * Metadata to apply to all spans.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A Laminar tracer that exports spans and events to Laminar.
+ *
+ * Usage:
+ * ```ts
+ * import { Kernl } from 'kernl';
+ * import { LaminarTracer } from '@kernl-sdk/lmnr';
+ *
+ * const kernl = new Kernl({
+ *   tracer: new LaminarTracer({
+ *     apiKey: process.env.LMNR_PROJECT_API_KEY,
+ *   }),
+ * });
+ * ```
+ */
+export declare class LaminarTracer implements Subscriber {
+    private spans;
+    private nextId;
+    private options;
+    constructor(options?: LaminarTracerOptions);
+    /**
+     * Check if a span should be recorded. Always returns true.
+     */
+    enabled(_data: SpanData): boolean;
+    /**
+     * Create a new span and send it to Laminar.
+     * Sets gen_ai semantic convention attributes for LLM spans.
+     */
+    span(data: SpanData, parent: SpanId | null): SpanId;
+    /**
+     * Called when entering a span's execution context.
+     * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+     */
+    enter(_spanId: SpanId): void;
+    /**
+     * Called when exiting a span's execution context.
+     * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+     */
+    exit(_spanId: SpanId): void;
+    /**
+     * Record additional data on an active span.
+     * Updates gen_ai semantic convention attributes for LLM responses.
+     */
+    record(spanId: SpanId, delta: Partial<SpanData>): void;
+    /**
+     * Record an error on a span.
+     */
+    error(spanId: SpanId, error: Error): void;
+    /**
+     * Close a span, ending its duration and sending it to Laminar.
+     */
+    close(spanId: SpanId): void;
+    /**
+     * Emit a standalone event to Laminar.
+     */
+    event(data: EventData, _parent: SpanId | null): void;
+    /**
+     * Flush pending spans to Laminar.
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the tracer and flush remaining data.
+     */
+    shutdown(_timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../src/subscriber.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,QAAQ,EACR,SAAS,EAIV,MAAM,eAAe,CAAC;AAgBvB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,aAAc,YAAW,UAAU;IAC9C,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAuB;gBAE1B,OAAO,GAAE,oBAAyB;IAqB9C;;OAEG;IACH,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO;IAIjC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAyCnD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI5B;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAE3B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;IA6DtD;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAMzC;;OAEG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAO3B;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAOpD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjD"}

package/dist/subscriber.js

@@ -0,0 +1,183 @@
+import { Laminar } from "@lmnr-ai/lmnr";
+import { SPAN_NAME, SPAN_TYPE, SPAN_INPUT, EVENT_ATTRIBUTES } from "./convert.js";
+import { extractSessionId, extractUserId, setPromptAttributes, setCompletionAttributes, } from "./utils.js";
+/**
+ * A Laminar tracer that exports spans and events to Laminar.
+ *
+ * Usage:
+ * ```ts
+ * import { Kernl } from 'kernl';
+ * import { LaminarTracer } from '@kernl-sdk/lmnr';
+ *
+ * const kernl = new Kernl({
+ *   tracer: new LaminarTracer({
+ *     apiKey: process.env.LMNR_PROJECT_API_KEY,
+ *   }),
+ * });
+ * ```
+ */
+export class LaminarTracer {
+    spans = new Map();
+    nextId = 0;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        const apiKey = options.apiKey ?? process.env.LMNR_PROJECT_API_KEY;
+        if (!apiKey) {
+            throw new Error("LaminarTracer requires an API key. " +
+                "Pass { apiKey: '...' } or set LMNR_PROJECT_API_KEY environment variable.");
+        }
+        // Initialize Laminar if not already initialized
+        if (!Laminar.initialized()) {
+            Laminar.initialize({
+                projectApiKey: apiKey,
+                baseUrl: options.baseUrl,
+                instrumentModules: {}, // disable auto-instrumentation
+            });
+        }
+    }
+    /**
+     * Check if a span should be recorded. Always returns true.
+     */
+    enabled(_data) {
+        return true;
+    }
+    /**
+     * Create a new span and send it to Laminar.
+     * Sets gen_ai semantic convention attributes for LLM spans.
+     */
+    span(data, parent) {
+        const id = `span_${this.nextId++}`;
+        // get parent context for linking
+        const parentRecord = parent ? this.spans.get(parent) : null;
+        const parentSpanContext = parentRecord?.context ?? undefined;
+        // extract session/user from thread context
+        const sessionId = extractSessionId(data);
+        const userId = extractUserId(data);
+        // create the Laminar span
+        const s = Laminar.startSpan({
+            name: SPAN_NAME.encode(data),
+            spanType: SPAN_TYPE.encode(data.kind),
+            input: SPAN_INPUT.encode(data),
+            parentSpanContext,
+            tags: this.options.tags,
+            sessionId,
+            userId,
+            metadata: this.options.metadata,
+        });
+        // set gen_ai semantic convention attributes for LLM spans
+        if (data.kind === "model.call") {
+            s.setAttribute("gen_ai.system", data.provider);
+            s.setAttribute("gen_ai.request.model", data.modelId);
+            // Format input messages for native UI
+            if (data.request?.input) {
+                setPromptAttributes(s, data.request.input);
+            }
+        }
+        // get context for future children
+        const context = Laminar.getLaminarSpanContext(s);
+        this.spans.set(id, { span: s, data, context });
+        return id;
+    }
+    /**
+     * Called when entering a span's execution context.
+     * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+     */
+    enter(_spanId) {
+        // Laminar tracks timing from startSpan() to end()
+    }
+    /**
+     * Called when exiting a span's execution context.
+     * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+     */
+    exit(_spanId) { }
+    /**
+     * Record additional data on an active span.
+     * Updates gen_ai semantic convention attributes for LLM responses.
+     */
+    record(spanId, delta) {
+        const record = this.spans.get(spanId);
+        if (!record)
+            return;
+        Object.assign(record.data, delta);
+        switch (record.data.kind) {
+            case "thread": {
+                const d = delta;
+                if (d.state) {
+                    record.span.setAttribute("thread.state", JSON.stringify(d.state));
+                }
+                if (d.result !== undefined) {
+                    record.span.setAttribute("lmnr.span.output", JSON.stringify(d.result));
+                }
+                if (d.error) {
+                    record.span.setAttribute("thread.error", d.error);
+                }
+                break;
+            }
+            case "model.call": {
+                const d = delta;
+                if (!d.response)
+                    break;
+                if (d.response.usage) {
+                    record.span.setAttribute("gen_ai.usage.input_tokens", d.response.usage.inputTokens?.total ?? 0);
+                    record.span.setAttribute("gen_ai.usage.output_tokens", d.response.usage.outputTokens?.total ?? 0);
+                }
+                if (d.response.content) {
+                    setCompletionAttributes(record.span, d.response.content);
+                    record.span.setAttribute("lmnr.span.output", JSON.stringify(d.response.content));
+                }
+                break;
+            }
+            case "tool.call": {
+                const d = delta;
+                if (d.result !== undefined) {
+                    record.span.setAttribute("lmnr.span.output", JSON.stringify(d.result));
+                }
+                if (d.error) {
+                    record.span.setAttribute("tool.call.error", d.error);
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * Record an error on a span.
+     */
+    error(spanId, error) {
+        const record = this.spans.get(spanId);
+        if (!record)
+            return;
+        record.span.recordException(error);
+    }
+    /**
+     * Close a span, ending its duration and sending it to Laminar.
+     */
+    close(spanId) {
+        const record = this.spans.get(spanId);
+        if (!record)
+            return;
+        record.span.end();
+        this.spans.delete(spanId);
+    }
+    /**
+     * Emit a standalone event to Laminar.
+     */
+    event(data, _parent) {
+        Laminar.event({
+            name: data.kind,
+            attributes: EVENT_ATTRIBUTES.encode(data),
+        });
+    }
+    /**
+     * Flush pending spans to Laminar.
+     */
+    async flush() {
+        await Laminar.flush();
+    }
+    /**
+     * Shutdown the tracer and flush remaining data.
+     */
+    async shutdown(_timeout) {
+        await Laminar.shutdown();
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+import type { Span } from "@lmnr-ai/lmnr";
+import type { SpanData } from "kernl/tracing";
+export declare function extractSessionId(data: SpanData): string | undefined;
+export declare function extractUserId(data: SpanData): string | undefined;
+export declare function setPromptAttributes(span: Span, items: Array<{
+    kind: string;
+    role?: string;
+    content?: Array<{
+        kind: string;
+        text?: string;
+    }>;
+}>): void;
+export declare function setCompletionAttributes(span: Span, items: Array<{
+    kind: string;
+    role?: string;
+    text?: string;
+}>): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAMnE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,CAMhE;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClD,CAAC,GACD,IAAI,CAaN;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC3D,IAAI,CAYN"}

package/dist/utils.js

@@ -0,0 +1,43 @@
+export function extractSessionId(data) {
+    if (data.kind === "thread" && data.context) {
+        const ctx = data.context;
+        if (typeof ctx.sessionId === "string")
+            return ctx.sessionId;
+    }
+    return undefined;
+}
+export function extractUserId(data) {
+    if (data.kind === "thread" && data.context) {
+        const ctx = data.context;
+        if (typeof ctx.userId === "string")
+            return ctx.userId;
+    }
+    return undefined;
+}
+export function setPromptAttributes(span, items) {
+    let idx = 0;
+    for (const item of items) {
+        if (item.kind === "message" && item.role && item.content) {
+            span.setAttribute(`gen_ai.prompt.${idx}.role`, item.role);
+            const content = item.content
+                .filter((p) => p.kind === "text")
+                .map((p) => p.text)
+                .join("");
+            span.setAttribute(`gen_ai.prompt.${idx}.content`, content);
+            idx++;
+        }
+    }
+}
+export function setCompletionAttributes(span, items) {
+    let idx = 0;
+    for (const item of items) {
+        if (item.kind === "message" && item.role) {
+            span.setAttribute(`gen_ai.completion.${idx}.role`, item.role);
+            idx++;
+        }
+        if ((item.kind === "text" || item.kind === "reasoning") && item.text) {
+            span.setAttribute(`gen_ai.completion.${idx}.content`, item.text);
+            idx++;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@kernl-sdk/lmnr",
+  "version": "0.1.0",
+  "description": "Laminar observability integration for kernl",
+  "keywords": [
+    "kernl",
+    "laminar",
+    "tracing",
+    "observability",
+    "llm"
+  ],
+  "author": "dremnik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kernl-sdk/kernl.git",
+    "directory": "packages/observability/laminar"
+  },
+  "homepage": "https://github.com/kernl-sdk/kernl#readme",
+  "bugs": {
+    "url": "https://github.com/kernl-sdk/kernl/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias --resolve-full-paths",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@kernl-sdk/shared": "workspace:*",
+    "kernl": "workspace:*"
+  },
+  "peerDependencies": {
+    "@lmnr-ai/lmnr": ">=0.8.0"
+  },
+  "devDependencies": {
+    "@lmnr-ai/lmnr": "^0.8.6",
+    "@types/node": "^24.10.0",
+    "tsc-alias": "^1.8.10",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.8"
+  }
+}

package/src/convert.ts

@@ -0,0 +1,74 @@
+import type { Codec } from "@kernl-sdk/shared/lib";
+import type { SpanData, EventData } from "kernl/tracing";
+
+export type SpanType = "DEFAULT" | "LLM" | "TOOL";
+
+export const SPAN_NAME: Codec<SpanData, string> = {
+  encode: (data) => {
+    switch (data.kind) {
+      case "thread":
+        return `thread.${data.agentId}`;
+      case "model.call":
+        return `model.${data.provider}.${data.modelId}`;
+      case "tool.call":
+        return `tool.${data.toolId}`;
+      default:
+        return `kernl.unknown`;
+    }
+  },
+  decode: () => {
+    throw new Error("SPAN_NAME.decode: unimplemented");
+  },
+};
+
+export const SPAN_TYPE: Codec<SpanData["kind"], SpanType> = {
+  encode: (kind) => {
+    switch (kind) {
+      case "thread":
+        return "DEFAULT";
+      case "model.call":
+        return "LLM";
+      case "tool.call":
+        return "TOOL";
+      default:
+        return "DEFAULT";
+    }
+  },
+  decode: () => {
+    throw new Error("SPAN_TYPE.decode: unimplemented");
+  },
+};
+
+export const SPAN_INPUT: Codec<SpanData, Record<string, unknown>> = {
+  encode: (data) => {
+    const { kind, ...rest } = data;
+    return rest;
+  },
+  decode: () => {
+    throw new Error("SPAN_INPUT.decode: unimplemented");
+  },
+};
+
+export const EVENT_ATTRIBUTES: Codec<
+  EventData,
+  Record<string, string | number | boolean>
+> = {
+  encode: (data) => {
+    const result: Record<string, string | number | boolean> = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+      ) {
+        result[key] = value;
+      } else if (value !== undefined) {
+        result[key] = JSON.stringify(value);
+      }
+    }
+    return result;
+  },
+  decode: () => {
+    throw new Error("EVENT_ATTRIBUTES.decode: unimplemented");
+  },
+};

package/src/index.ts

@@ -0,0 +1 @@
+export { LaminarTracer, type LaminarTracerOptions } from "./subscriber";

package/src/subscriber.ts

@@ -0,0 +1,264 @@
+import { Laminar, type LaminarSpanContext, type Span } from "@lmnr-ai/lmnr";
+import type {
+  Subscriber,
+  SpanId,
+  SpanData,
+  EventData,
+  ModelCallSpan,
+  ToolCallSpan,
+  ThreadSpan,
+} from "kernl/tracing";
+
+import { SPAN_NAME, SPAN_TYPE, SPAN_INPUT, EVENT_ATTRIBUTES } from "./convert";
+import {
+  extractSessionId,
+  extractUserId,
+  setPromptAttributes,
+  setCompletionAttributes,
+} from "./utils";
+
+interface SpanRecord {
+  span: Span;
+  data: SpanData;
+  context: LaminarSpanContext | null;
+}
+
+export interface LaminarTracerOptions {
+  /**
+   * Laminar project API key.
+   * If not provided, uses the LMNR_PROJECT_API_KEY environment variable.
+   */
+  apiKey?: string;
+
+  /**
+   * Base URL for the Laminar API.
+   * Defaults to https://api.lmnr.ai
+   */
+  baseUrl?: string;
+
+  /**
+   * Tags to apply to all spans.
+   */
+  tags?: string[];
+
+  /**
+   * Metadata to apply to all spans.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * A Laminar tracer that exports spans and events to Laminar.
+ *
+ * Usage:
+ * ```ts
+ * import { Kernl } from 'kernl';
+ * import { LaminarTracer } from '@kernl-sdk/lmnr';
+ *
+ * const kernl = new Kernl({
+ *   tracer: new LaminarTracer({
+ *     apiKey: process.env.LMNR_PROJECT_API_KEY,
+ *   }),
+ * });
+ * ```
+ */
+export class LaminarTracer implements Subscriber {
+  private spans = new Map<SpanId, SpanRecord>();
+  private nextId = 0;
+  private options: LaminarTracerOptions;
+
+  constructor(options: LaminarTracerOptions = {}) {
+    this.options = options;
+
+    const apiKey = options.apiKey ?? process.env.LMNR_PROJECT_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "LaminarTracer requires an API key. " +
+          "Pass { apiKey: '...' } or set LMNR_PROJECT_API_KEY environment variable.",
+      );
+    }
+
+    // Initialize Laminar if not already initialized
+    if (!Laminar.initialized()) {
+      Laminar.initialize({
+        projectApiKey: apiKey,
+        baseUrl: options.baseUrl,
+        instrumentModules: {}, // disable auto-instrumentation
+      });
+    }
+  }
+
+  /**
+   * Check if a span should be recorded. Always returns true.
+   */
+  enabled(_data: SpanData): boolean {
+    return true;
+  }
+
+  /**
+   * Create a new span and send it to Laminar.
+   * Sets gen_ai semantic convention attributes for LLM spans.
+   */
+  span(data: SpanData, parent: SpanId | null): SpanId {
+    const id = `span_${this.nextId++}`;
+
+    // get parent context for linking
+    const parentRecord = parent ? this.spans.get(parent) : null;
+    const parentSpanContext = parentRecord?.context ?? undefined;
+
+    // extract session/user from thread context
+    const sessionId = extractSessionId(data);
+    const userId = extractUserId(data);
+
+    // create the Laminar span
+    const s = Laminar.startSpan({
+      name: SPAN_NAME.encode(data),
+      spanType: SPAN_TYPE.encode(data.kind),
+      input: SPAN_INPUT.encode(data),
+      parentSpanContext,
+      tags: this.options.tags,
+      sessionId,
+      userId,
+      metadata: this.options.metadata as Record<string, any>,
+    });
+
+    // set gen_ai semantic convention attributes for LLM spans
+    if (data.kind === "model.call") {
+      s.setAttribute("gen_ai.system", data.provider);
+      s.setAttribute("gen_ai.request.model", data.modelId);
+
+      // Format input messages for native UI
+      if (data.request?.input) {
+        setPromptAttributes(s, data.request.input);
+      }
+    }
+
+    // get context for future children
+    const context = Laminar.getLaminarSpanContext(s);
+
+    this.spans.set(id, { span: s, data, context });
+    return id;
+  }
+
+  /**
+   * Called when entering a span's execution context.
+   * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+   */
+  enter(_spanId: SpanId): void {
+    // Laminar tracks timing from startSpan() to end()
+  }
+
+  /**
+   * Called when exiting a span's execution context.
+   * Laminar tracks timing from startSpan() to end(), so this is a no-op.
+   */
+  exit(_spanId: SpanId): void {}
+
+  /**
+   * Record additional data on an active span.
+   * Updates gen_ai semantic convention attributes for LLM responses.
+   */
+  record(spanId: SpanId, delta: Partial<SpanData>): void {
+    const record = this.spans.get(spanId);
+    if (!record) return;
+
+    Object.assign(record.data, delta);
+
+    switch (record.data.kind) {
+      case "thread": {
+        const d = delta as Partial<ThreadSpan>;
+        if (d.state) {
+          record.span.setAttribute("thread.state", JSON.stringify(d.state));
+        }
+        if (d.result !== undefined) {
+          record.span.setAttribute(
+            "lmnr.span.output",
+            JSON.stringify(d.result),
+          );
+        }
+        if (d.error) {
+          record.span.setAttribute("thread.error", d.error);
+        }
+        break;
+      }
+      case "model.call": {
+        const d = delta as Partial<ModelCallSpan>;
+        if (!d.response) break;
+        if (d.response.usage) {
+          record.span.setAttribute(
+            "gen_ai.usage.input_tokens",
+            d.response.usage.inputTokens?.total ?? 0,
+          );
+          record.span.setAttribute(
+            "gen_ai.usage.output_tokens",
+            d.response.usage.outputTokens?.total ?? 0,
+          );
+        }
+        if (d.response.content) {
+          setCompletionAttributes(record.span, d.response.content);
+          record.span.setAttribute(
+            "lmnr.span.output",
+            JSON.stringify(d.response.content),
+          );
+        }
+        break;
+      }
+      case "tool.call": {
+        const d = delta as Partial<ToolCallSpan>;
+        if (d.result !== undefined) {
+          record.span.setAttribute(
+            "lmnr.span.output",
+            JSON.stringify(d.result),
+          );
+        }
+        if (d.error) {
+          record.span.setAttribute("tool.call.error", d.error);
+        }
+        break;
+      }
+    }
+  }
+
+  /**
+   * Record an error on a span.
+   */
+  error(spanId: SpanId, error: Error): void {
+    const record = this.spans.get(spanId);
+    if (!record) return;
+    record.span.recordException(error);
+  }
+
+  /**
+   * Close a span, ending its duration and sending it to Laminar.
+   */
+  close(spanId: SpanId): void {
+    const record = this.spans.get(spanId);
+    if (!record) return;
+    record.span.end();
+    this.spans.delete(spanId);
+  }
+
+  /**
+   * Emit a standalone event to Laminar.
+   */
+  event(data: EventData, _parent: SpanId | null): void {
+    Laminar.event({
+      name: data.kind,
+      attributes: EVENT_ATTRIBUTES.encode(data),
+    });
+  }
+
+  /**
+   * Flush pending spans to Laminar.
+   */
+  async flush(): Promise<void> {
+    await Laminar.flush();
+  }
+
+  /**
+   * Shutdown the tracer and flush remaining data.
+   */
+  async shutdown(_timeout?: number): Promise<void> {
+    await Laminar.shutdown();
+  }
+}

package/src/utils.ts

@@ -0,0 +1,57 @@
+import type { Span } from "@lmnr-ai/lmnr";
+import type { SpanData } from "kernl/tracing";
+
+export function extractSessionId(data: SpanData): string | undefined {
+  if (data.kind === "thread" && data.context) {
+    const ctx = data.context as Record<string, unknown>;
+    if (typeof ctx.sessionId === "string") return ctx.sessionId;
+  }
+  return undefined;
+}
+
+export function extractUserId(data: SpanData): string | undefined {
+  if (data.kind === "thread" && data.context) {
+    const ctx = data.context as Record<string, unknown>;
+    if (typeof ctx.userId === "string") return ctx.userId;
+  }
+  return undefined;
+}
+
+export function setPromptAttributes(
+  span: Span,
+  items: Array<{
+    kind: string;
+    role?: string;
+    content?: Array<{ kind: string; text?: string }>;
+  }>,
+): void {
+  let idx = 0;
+  for (const item of items) {
+    if (item.kind === "message" && item.role && item.content) {
+      span.setAttribute(`gen_ai.prompt.${idx}.role`, item.role);
+      const content = item.content
+        .filter((p): p is { kind: "text"; text: string } => p.kind === "text")
+        .map((p) => p.text)
+        .join("");
+      span.setAttribute(`gen_ai.prompt.${idx}.content`, content);
+      idx++;
+    }
+  }
+}
+
+export function setCompletionAttributes(
+  span: Span,
+  items: Array<{ kind: string; role?: string; text?: string }>,
+): void {
+  let idx = 0;
+  for (const item of items) {
+    if (item.kind === "message" && item.role) {
+      span.setAttribute(`gen_ai.completion.${idx}.role`, item.role);
+      idx++;
+    }
+    if ((item.kind === "text" || item.kind === "reasoning") && item.text) {
+      span.setAttribute(`gen_ai.completion.${idx}.content`, item.text);
+      idx++;
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}