@moduna/otel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moduna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @moduna/otel
+
+[![npm version](https://img.shields.io/npm/v/%40moduna%2Fotel.svg)](https://www.npmjs.com/package/@moduna/otel)
+[![npm downloads](https://img.shields.io/npm/dm/%40moduna%2Fotel.svg)](https://www.npmjs.com/package/@moduna/otel)
+[![license](https://img.shields.io/npm/l/%40moduna%2Fotel.svg)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6.svg)](https://www.typescriptlang.org/)
+[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-enabled-425cc7.svg)](https://opentelemetry.io/)
+[![pnpm](https://img.shields.io/badge/package%20manager-pnpm-f69220.svg)](https://pnpm.io/)
+[![GitHub stars](https://img.shields.io/github/stars/Moduna-AI/node-otel-sdk.svg?style=social)](https://github.com/Moduna-AI/node-otel-sdk/stargazers)
+
+OpenTelemetry setup for Moduna AI traces in Node.js apps, including Vercel AI SDK and LangChain.
+
+## Project Health
+
+| Metric | Status |
+| --- | --- |
+| Package | [`@moduna/otel`](https://www.npmjs.com/package/@moduna/otel) |
+| Runtime | Node.js ESM |
+| Types | TypeScript declarations included |
+| License | MIT |
+| Package managers | npm, pnpm, bun |
+| Frameworks | Vercel AI SDK, LangChain |
+| Telemetry | OpenTelemetry traces |
+
+## Install
+
+```bash
+npm install @moduna/otel
+pnpm add @moduna/otel
+bun add @moduna/otel
+```
+
+## Setup
+
+Set the Moduna key using either a shell or a `.env` file:
+
+```bash
+export MODUNA_API_KEY="your-moduna-key"
+```
+
+or create a `.env` file with:
+
+```env
+MODUNA_API_KEY=your-moduna-key
+```
+
+## One-line integration
+
+```ts
+import ModunaOTEL from "@moduna/otel";
+
+const otel = new ModunaOTEL({
+    agentName: "my-ai-app",
+    framework: "vercel-ai-sdk",
+});
+```
+
+## Framework Usage
+
+Choose the framework you are using with Moduna OTEL.
+
+<details open>
+<summary><strong>Vercel AI SDK</strong></summary>
+
+Pass per-call conversation or session identifiers to `generateText` and `streamText`.
+
+```ts
+const result = await generateText({
+    model,
+    prompt,
+    experimental_telemetry: otel.vercelTelemetry({
+        conversationId: "conversation-123",
+        sessionId: "session-456",
+    }),
+});
+```
+
+The IDs are attached to the generated spans as Moduna telemetry metadata.
+
+</details>
+
+<details>
+<summary><strong>LangChain</strong></summary>
+
+Use Moduna as a LangChain callback handler.
+
+```ts
+import ModunaOTEL from "@moduna/otel";
+import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+
+const otel = new ModunaOTEL({
+    agentName: "my-ai-app",
+    framework: "langchain",
+});
+const handler = otel.langChainHandler();
+const model = new ChatGoogleGenerativeAI({ model: "gemini-1.5-pro" });
+
+const result = await model.invoke("Hello, world!", {
+    callbacks: [handler],
+    metadata: {
+        conversationId: "conversation-123",
+        sessionId: "session-456",
+    },
+});
+```
+
+Or register it globally for all LangChain runs.
+
+```ts
+otel.registerGlobalLangChainHandler();
+
+const result = await model.invoke("Hello, world!", {
+    metadata: {
+        conversationId: "conversation-123",
+        sessionId: "session-456",
+    },
+});
+```
+
+</details>
+
+## Development
+
+Format, lint, or build with:
+
+```bash
+pnpm run build
+pnpm run lint
+pnpm test
+```

package/dist/interface/ModunaOTELConfig.d.ts

@@ -0,0 +1,41 @@
+import type { ModunaOTELFramework, ModunaOTELSDKIntegration } from "../types/SupportedSDK.js";
+/**
+ * Shared configuration for the Moduna OpenTelemetry SDK.
+ */
+interface ModunaOTELBaseConfig {
+    /**
+     * API key for authenticating with Moduna. Falls back to MODUNA_API_KEY.
+     */
+    apiKey?: string;
+    /**
+     * Service name attached to emitted OpenTelemetry resources.
+     */
+    agentName: string;
+    /**
+     * Additional OTLP headers sent with telemetry exports.
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration options for a ModunaOTEL instance.
+ */
+export type ModunaOTELConfig = ModunaOTELBaseConfig & ({
+    /**
+     * Framework that will use the Moduna OpenTelemetry SDK.
+     */
+    framework: ModunaOTELFramework;
+    /**
+     * Deprecated. Use framework instead.
+     */
+    sdkIntegration?: ModunaOTELSDKIntegration;
+} | {
+    /**
+     * Framework that will use the Moduna OpenTelemetry SDK.
+     */
+    framework?: ModunaOTELFramework;
+    /**
+     * Deprecated. Use framework instead.
+     */
+    sdkIntegration: ModunaOTELSDKIntegration;
+});
+export {};

package/dist/interface/ModunaOTELConfig.js

@@ -0,0 +1 @@
+export {};

package/dist/services/ModunaLangChainCallbackHandler.d.ts

@@ -0,0 +1,90 @@
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import type { Serialized } from "@langchain/core/load/serializable";
+import type { BaseMessage } from "@langchain/core/messages";
+import type { LLMResult } from "@langchain/core/outputs";
+import type { ModunaTraceContext } from "../types/TraceContext.js";
+/**
+ * Configuration for Moduna's LangChain callback handler.
+ */
+export interface ModunaLangChainCallbackHandlerConfig {
+    /**
+     * Default trace identifiers used when a LangChain call has no metadata.
+     */
+    traceContext?: ModunaTraceContext;
+}
+/**
+ * LangChain callback handler that emits Moduna OpenTelemetry spans.
+ */
+export declare class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
+    /**
+     * Stable handler name used by LangChain callback manager de-duplication.
+     */
+    name: string;
+    private readonly defaultTraceContext;
+    private readonly runs;
+    /**
+     * Creates a LangChain callback handler for Moduna spans.
+     *
+     * @param config Optional default trace identifiers.
+     */
+    constructor(config?: ModunaLangChainCallbackHandlerConfig);
+    /**
+     * Starts a span for a LangChain chat model run.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param messages Messages sent to the chat model.
+     * @param runId LangChain run identifier.
+     * @param parentRunId Parent run identifier, when present.
+     * @param extraParams Provider-specific run parameters.
+     * @param tags LangChain run tags.
+     * @param metadata LangChain run metadata.
+     * @param runName LangChain run name.
+     */
+    handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void;
+    /**
+     * Starts a span for a LangChain LLM run.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param prompts Prompts sent to the LLM.
+     * @param runId LangChain run identifier.
+     * @param parentRunId Parent run identifier, when present.
+     * @param extraParams Provider-specific run parameters.
+     * @param tags LangChain run tags.
+     * @param metadata LangChain run metadata.
+     * @param runName LangChain run name.
+     */
+    handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): void;
+    /**
+     * Records a streamed token count signal on the active LangChain span.
+     *
+     * @param _token New token emitted by LangChain.
+     * @param _idx Token indices from LangChain.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMNewToken(_token: string, _idx: unknown, runId: string): void;
+    /**
+     * Ends the span for a successful LangChain run.
+     *
+     * @param output LangChain LLM output.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMEnd(output: LLMResult, runId: string): void;
+    /**
+     * Records an error and ends the span for a failed LangChain run.
+     *
+     * @param error Error emitted by LangChain.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMError(error: unknown, runId: string): void;
+    private startRun;
+    private applyModelAttributes;
+    private applyTraceContext;
+    private getString;
+    private toError;
+}
+/**
+ * Registers a Moduna LangChain callback handler for all LangChain runs.
+ *
+ * @param handler Handler to register globally.
+ */
+export declare const registerGlobalModunaLangChainHandler: (handler: ModunaLangChainCallbackHandler) => void;

package/dist/services/ModunaLangChainCallbackHandler.js

@@ -0,0 +1,191 @@
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
+import { registerConfigureHook, setContextVariable } from "@langchain/core/context";
+const MODUNA_LANGCHAIN_HANDLER_CONTEXT_KEY = "moduna.otel.langchain.callbackHandler";
+let isConfigureHookRegistered = false;
+/**
+ * LangChain callback handler that emits Moduna OpenTelemetry spans.
+ */
+export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
+    /**
+     * Stable handler name used by LangChain callback manager de-duplication.
+     */
+    name = "moduna_otel_langchain_callback_handler";
+    defaultTraceContext;
+    runs = new Map();
+    /**
+     * Creates a LangChain callback handler for Moduna spans.
+     *
+     * @param config Optional default trace identifiers.
+     */
+    constructor(config = {}) {
+        super();
+        this.defaultTraceContext = config.traceContext ?? {};
+    }
+    /**
+     * Starts a span for a LangChain chat model run.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param messages Messages sent to the chat model.
+     * @param runId LangChain run identifier.
+     * @param parentRunId Parent run identifier, when present.
+     * @param extraParams Provider-specific run parameters.
+     * @param tags LangChain run tags.
+     * @param metadata LangChain run metadata.
+     * @param runName LangChain run name.
+     */
+    handleChatModelStart(llm, messages, runId, parentRunId, extraParams, tags, metadata, runName) {
+        this.startRun({
+            extraParams,
+            inputCount: messages.length,
+            llm,
+            metadata,
+            parentRunId,
+            runId,
+            runName,
+            runType: "chat_model",
+            tags,
+        });
+    }
+    /**
+     * Starts a span for a LangChain LLM run.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param prompts Prompts sent to the LLM.
+     * @param runId LangChain run identifier.
+     * @param parentRunId Parent run identifier, when present.
+     * @param extraParams Provider-specific run parameters.
+     * @param tags LangChain run tags.
+     * @param metadata LangChain run metadata.
+     * @param runName LangChain run name.
+     */
+    handleLLMStart(llm, prompts, runId, parentRunId, extraParams, tags, metadata, runName) {
+        this.startRun({
+            extraParams,
+            inputCount: prompts.length,
+            llm,
+            metadata,
+            parentRunId,
+            runId,
+            runName,
+            runType: "llm",
+            tags,
+        });
+    }
+    /**
+     * Records a streamed token count signal on the active LangChain span.
+     *
+     * @param _token New token emitted by LangChain.
+     * @param _idx Token indices from LangChain.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMNewToken(_token, _idx, runId) {
+        this.runs.get(runId)?.span.addEvent("langchain.llm.token");
+    }
+    /**
+     * Ends the span for a successful LangChain run.
+     *
+     * @param output LangChain LLM output.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMEnd(output, runId) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return;
+        }
+        run.span.setAttribute("langchain.output.generations", output.generations.length);
+        run.span.setStatus({ code: SpanStatusCode.OK });
+        run.span.end();
+        this.runs.delete(runId);
+    }
+    /**
+     * Records an error and ends the span for a failed LangChain run.
+     *
+     * @param error Error emitted by LangChain.
+     * @param runId LangChain run identifier.
+     */
+    handleLLMError(error, runId) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return;
+        }
+        run.span.recordException(this.toError(error));
+        run.span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: this.toError(error).message,
+        });
+        run.span.end();
+        this.runs.delete(runId);
+    }
+    startRun(input) {
+        const tracer = trace.getTracer("moduna-langchain");
+        const span = tracer.startSpan(input.runName ?? "langchain.llm", {
+            kind: SpanKind.CLIENT,
+        });
+        span.setAttribute("moduna.framework", "langchain");
+        span.setAttribute("sdk.integration", "langchain");
+        span.setAttribute("langchain.run.id", input.runId);
+        span.setAttribute("langchain.run.type", input.runType);
+        span.setAttribute("langchain.input.count", input.inputCount);
+        if (input.parentRunId) {
+            span.setAttribute("langchain.parent_run.id", input.parentRunId);
+        }
+        if (input.tags?.length) {
+            span.setAttribute("langchain.tags", input.tags.join(","));
+        }
+        this.applyModelAttributes(span, input.llm, input.extraParams);
+        this.applyTraceContext(span, input.metadata);
+        this.runs.set(input.runId, { span });
+    }
+    applyModelAttributes(span, llm, extraParams) {
+        const modelName = this.getString(extraParams?.invocation_params, "model") ??
+            this.getString(extraParams?.invocation_params, "modelName") ??
+            this.getString(llm, "name") ??
+            llm.id.join(".");
+        span.setAttribute("gen_ai.system", "google");
+        span.setAttribute("gen_ai.request.model", modelName);
+        span.setAttribute("langchain.serialized.id", llm.id.join("."));
+    }
+    applyTraceContext(span, metadata) {
+        const traceContext = {
+            conversationId: this.getString(metadata, "conversationId") ??
+                this.getString(metadata, "moduna.conversation.id") ??
+                this.defaultTraceContext.conversationId,
+            sessionId: this.getString(metadata, "sessionId") ??
+                this.getString(metadata, "moduna.session.id") ??
+                this.defaultTraceContext.sessionId,
+        };
+        if (traceContext.conversationId) {
+            span.setAttribute("moduna.conversation.id", traceContext.conversationId);
+        }
+        if (traceContext.sessionId) {
+            span.setAttribute("moduna.session.id", traceContext.sessionId);
+        }
+    }
+    getString(value, key) {
+        if (!value || typeof value !== "object") {
+            return undefined;
+        }
+        const record = value;
+        const result = record[key];
+        return typeof result === "string" ? result : undefined;
+    }
+    toError(error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+}
+/**
+ * Registers a Moduna LangChain callback handler for all LangChain runs.
+ *
+ * @param handler Handler to register globally.
+ */
+export const registerGlobalModunaLangChainHandler = (handler) => {
+    if (!isConfigureHookRegistered) {
+        registerConfigureHook({
+            contextVar: MODUNA_LANGCHAIN_HANDLER_CONTEXT_KEY,
+            inheritable: true,
+        });
+        isConfigureHookRegistered = true;
+    }
+    setContextVariable(MODUNA_LANGCHAIN_HANDLER_CONTEXT_KEY, handler);
+};

package/dist/services/ModunaOTEL.d.ts

@@ -0,0 +1,92 @@
+import type { AttributeValue } from "@opentelemetry/api";
+import type { ModunaOTELConfig } from "../interface/ModunaOTELConfig.js";
+import type { TraceCallback } from "../types/TraceCallback.js";
+import type { ModunaTelemetryMetadata, ModunaTraceContext } from "../types/TraceContext.js";
+import { ModunaLangChainCallbackHandler } from "./ModunaLangChainCallbackHandler.js";
+/**
+ * Vercel AI SDK compatible telemetry settings.
+ */
+export interface ModunaVercelTelemetrySettings {
+    /**
+     * Enables Vercel AI SDK telemetry for the current model call.
+     */
+    isEnabled: true;
+    /**
+     * Per-call Moduna metadata attached to the generated OpenTelemetry spans.
+     */
+    metadata: ModunaTelemetryMetadata & Record<string, AttributeValue>;
+}
+/**
+ * One-line OpenTelemetry setup for Moduna AI traces.
+ */
+export declare class ModunaOTEL {
+    private static readonly shared;
+    private readonly framework;
+    /**
+     * Creates a Moduna OTEL wrapper and starts telemetry asynchronously.
+     *
+     * @param config SDK configuration for the current application.
+     */
+    constructor(config: ModunaOTELConfig);
+    /**
+     * Creates and starts a ModunaOTEL instance.
+     *
+     * @param config SDK configuration for the current application.
+     * @returns The started ModunaOTEL wrapper.
+     */
+    static start(config: ModunaOTELConfig): Promise<ModunaOTEL>;
+    /**
+     * Starts the singleton OpenTelemetry SDK.
+     */
+    start(): Promise<void>;
+    /**
+     * Shuts down the singleton OpenTelemetry SDK.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Creates telemetry settings for one Vercel AI SDK generateText or streamText call.
+     *
+     * @param context Conversation or session identifiers for the current AI call.
+     * @returns Vercel AI SDK experimental telemetry settings.
+     */
+    vercelTelemetry(context?: ModunaTraceContext): ModunaVercelTelemetrySettings;
+    /**
+     * Creates a LangChain callback handler for per-call usage.
+     *
+     * @param context Default conversation or session identifiers.
+     * @returns LangChain callback handler that emits Moduna spans.
+     */
+    langChainHandler(context?: ModunaTraceContext): ModunaLangChainCallbackHandler;
+    /**
+     * Registers a LangChain callback handler for all LangChain runs.
+     *
+     * @param context Default conversation or session identifiers.
+     * @returns The globally registered LangChain callback handler.
+     */
+    registerGlobalLangChainHandler(context?: ModunaTraceContext): ModunaLangChainCallbackHandler;
+    /**
+     * Instruments a callback with a Moduna span.
+     *
+     * @param spanName Name for the emitted span.
+     * @param callback Callback executed inside the active span.
+     * @returns The callback result.
+     */
+    instrument<T>(spanName: string, callback: TraceCallback<T>): Promise<T>;
+    /**
+     * Instruments a callback with a Moduna span and per-call trace context.
+     *
+     * @param spanName Name for the emitted span.
+     * @param context Conversation or session identifiers for the current AI call.
+     * @param callback Callback executed inside the active span.
+     * @returns The callback result.
+     */
+    instrument<T>(spanName: string, context: ModunaTraceContext, callback: TraceCallback<T>): Promise<T>;
+    private normalizeConfig;
+    private createSDK;
+    private startSafely;
+    private createTraceMetadata;
+    private applyTraceContext;
+    private parseInstrumentArgs;
+    private warnOnce;
+}
+export default ModunaOTEL;

package/dist/services/ModunaOTEL.js

@@ -0,0 +1,243 @@
+import process from "node:process";
+import { SpanKind, trace } from "@opentelemetry/api";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import { ModunaLangChainCallbackHandler, registerGlobalModunaLangChainHandler, } from "./ModunaLangChainCallbackHandler.js";
+const DEFAULT_ENDPOINT = "https://volex-otel-git-506013021984.us-central1.run.app/v1/traces";
+class SilentOTLPTraceExporter extends OTLPTraceExporter {
+    onFailure;
+    /**
+     * Creates an OTLP exporter that reports failures without breaking user code.
+     *
+     * @param config OTLP HTTP exporter configuration.
+     * @param onFailure Callback invoked when export fails.
+     */
+    constructor(config, onFailure) {
+        super(config);
+        this.onFailure = onFailure;
+    }
+    /**
+     * Exports spans and converts synchronous exporter failures into callback results.
+     *
+     * @param spans Readable spans from the OpenTelemetry processor.
+     * @param resultCallback OpenTelemetry export completion callback.
+     */
+    export(spans, resultCallback) {
+        try {
+            return super.export(spans, (result) => {
+                if (result.error || result.code !== 0) {
+                    this.onFailure(result.error ??
+                        new Error(`Moduna OTEL exporter failed with code ${result.code}.`));
+                }
+                resultCallback(result);
+            });
+        }
+        catch (error) {
+            this.onFailure(error);
+            resultCallback(this.createFailureResult(error));
+        }
+    }
+    createFailureResult(error) {
+        return {
+            code: 1,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * One-line OpenTelemetry setup for Moduna AI traces.
+ */
+export class ModunaOTEL {
+    static shared = {
+        started: false,
+        warned: false,
+    };
+    framework;
+    /**
+     * Creates a Moduna OTEL wrapper and starts telemetry asynchronously.
+     *
+     * @param config SDK configuration for the current application.
+     */
+    constructor(config) {
+        const normalizedConfig = this.normalizeConfig(config);
+        this.framework = normalizedConfig.framework;
+        ModunaOTEL.shared.sdk ??= this.createSDK(normalizedConfig);
+        void this.start();
+    }
+    /**
+     * Creates and starts a ModunaOTEL instance.
+     *
+     * @param config SDK configuration for the current application.
+     * @returns The started ModunaOTEL wrapper.
+     */
+    static async start(config) {
+        const otel = new ModunaOTEL(config);
+        await otel.start();
+        return otel;
+    }
+    /**
+     * Starts the singleton OpenTelemetry SDK.
+     */
+    async start() {
+        if (ModunaOTEL.shared.started) {
+            return;
+        }
+        ModunaOTEL.shared.startPromise ??= this.startSafely();
+        await ModunaOTEL.shared.startPromise;
+    }
+    /**
+     * Shuts down the singleton OpenTelemetry SDK.
+     */
+    async shutdown() {
+        const sdk = ModunaOTEL.shared.sdk;
+        if (!ModunaOTEL.shared.started || !sdk) {
+            return;
+        }
+        try {
+            await sdk.shutdown();
+        }
+        catch (error) {
+            this.warnOnce(error);
+        }
+        finally {
+            ModunaOTEL.shared.started = false;
+            ModunaOTEL.shared.startPromise = undefined;
+        }
+    }
+    /**
+     * Creates telemetry settings for one Vercel AI SDK generateText or streamText call.
+     *
+     * @param context Conversation or session identifiers for the current AI call.
+     * @returns Vercel AI SDK experimental telemetry settings.
+     */
+    vercelTelemetry(context = {}) {
+        return {
+            isEnabled: true,
+            metadata: this.createTraceMetadata(context),
+        };
+    }
+    /**
+     * Creates a LangChain callback handler for per-call usage.
+     *
+     * @param context Default conversation or session identifiers.
+     * @returns LangChain callback handler that emits Moduna spans.
+     */
+    langChainHandler(context = {}) {
+        return new ModunaLangChainCallbackHandler({
+            traceContext: context,
+        });
+    }
+    /**
+     * Registers a LangChain callback handler for all LangChain runs.
+     *
+     * @param context Default conversation or session identifiers.
+     * @returns The globally registered LangChain callback handler.
+     */
+    registerGlobalLangChainHandler(context = {}) {
+        const handler = this.langChainHandler(context);
+        registerGlobalModunaLangChainHandler(handler);
+        return handler;
+    }
+    /**
+     * Instruments a callback with optional Moduna trace context.
+     */
+    async instrument(spanName, contextOrCallback, callback) {
+        const { traceContext, traceCallback } = this.parseInstrumentArgs(contextOrCallback, callback);
+        const tracer = trace.getTracer("moduna-gen-ai");
+        return tracer.startActiveSpan(spanName, { kind: SpanKind.CLIENT }, async (span) => {
+            span.setAttribute("moduna.framework", this.framework);
+            span.setAttribute("sdk.integration", this.framework);
+            this.applyTraceContext(span, traceContext);
+            try {
+                return await traceCallback(span);
+            }
+            catch (error) {
+                span.recordException(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    normalizeConfig(config) {
+        return {
+            agentName: config.agentName,
+            apiKey: config.apiKey ?? process.env.MODUNA_API_KEY,
+            framework: config.framework ?? config.sdkIntegration,
+            headers: config.headers,
+        };
+    }
+    createSDK(config) {
+        return new NodeSDK({
+            resource: resourceFromAttributes({
+                [ATTR_SERVICE_NAME]: config.agentName,
+                "moduna.framework": config.framework,
+                "sdk.integration": config.framework,
+            }),
+            traceExporter: new SilentOTLPTraceExporter({
+                url: DEFAULT_ENDPOINT,
+                headers: {
+                    ...(config.apiKey
+                        ? { Authorization: `Bearer ${config.apiKey}` }
+                        : {}),
+                    ...config.headers,
+                },
+            }, (error) => this.warnOnce(error)),
+        });
+    }
+    async startSafely() {
+        const sdk = ModunaOTEL.shared.sdk;
+        if (!sdk) {
+            return;
+        }
+        try {
+            await Promise.resolve(sdk.start());
+            ModunaOTEL.shared.started = true;
+        }
+        catch (error) {
+            this.warnOnce(error);
+        }
+    }
+    createTraceMetadata(context) {
+        return {
+            ...(context.conversationId
+                ? { "moduna.conversation.id": context.conversationId }
+                : {}),
+            ...(context.sessionId
+                ? { "moduna.session.id": context.sessionId }
+                : {}),
+        };
+    }
+    applyTraceContext(span, context) {
+        const metadata = this.createTraceMetadata(context);
+        for (const [key, value] of Object.entries(metadata)) {
+            span.setAttribute(key, value);
+        }
+    }
+    parseInstrumentArgs(contextOrCallback, callback) {
+        if (typeof contextOrCallback === "function") {
+            return {
+                traceContext: {},
+                traceCallback: contextOrCallback,
+            };
+        }
+        if (!callback) {
+            throw new TypeError("ModunaOTEL.instrument requires a callback.");
+        }
+        return {
+            traceContext: contextOrCallback,
+            traceCallback: callback,
+        };
+    }
+    warnOnce(error) {
+        if (ModunaOTEL.shared.warned) {
+            return;
+        }
+        ModunaOTEL.shared.warned = true;
+        console.warn("Moduna OTEL failed to send telemetry.", error);
+    }
+}
+export default ModunaOTEL;

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+export { default, ModunaOTEL } from "../services/ModunaOTEL.js";
+export { ModunaLangChainCallbackHandler, registerGlobalModunaLangChainHandler, } from "../services/ModunaLangChainCallbackHandler.js";
+export type { ModunaLangChainCallbackHandlerConfig } from "../services/ModunaLangChainCallbackHandler.js";
+export type { ModunaVercelTelemetrySettings } from "../services/ModunaOTEL.js";
+export type { ModunaOTELConfig } from "../interface/ModunaOTELConfig.js";
+export type { ModunaOTELFramework, ModunaOTELSDKIntegration, } from "../types/SupportedSDK.js";
+export type { TraceCallback } from "../types/TraceCallback.js";
+export type { ModunaTelemetryMetadata, ModunaTelemetryMetadataKey, ModunaTraceContext, } from "../types/TraceContext.js";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { default, ModunaOTEL } from "../services/ModunaOTEL.js";
+export { ModunaLangChainCallbackHandler, registerGlobalModunaLangChainHandler, } from "../services/ModunaLangChainCallbackHandler.js";

package/dist/types/SupportedSDK.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Frameworks supported by the Moduna OpenTelemetry SDK.
+ */
+export type ModunaOTELFramework = "langchain" | "vercel-ai-sdk";
+/**
+ * Deprecated alias kept for existing consumers that still pass sdkIntegration.
+ */
+export type ModunaOTELSDKIntegration = ModunaOTELFramework;

package/dist/types/SupportedSDK.js

@@ -0,0 +1 @@
+export {};

package/dist/types/TraceCallback.d.ts

@@ -0,0 +1,2 @@
+import type { Span } from "@opentelemetry/api";
+export type TraceCallback<T> = (span: Span) => Promise<T> | T;

package/dist/types/TraceCallback.js

@@ -0,0 +1 @@
+export {};

package/dist/types/TraceContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-call identifiers that are attached to Moduna trace spans.
+ */
+export interface ModunaTraceContext {
+    /**
+     * Identifier for a multi-message conversation.
+     */
+    conversationId?: string;
+    /**
+     * Identifier for a broader user or application session.
+     */
+    sessionId?: string;
+}
+/**
+ * Metadata keys emitted for Vercel AI SDK telemetry spans.
+ */
+export type ModunaTelemetryMetadataKey = "moduna.conversation.id" | "moduna.session.id";
+/**
+ * Vercel AI SDK metadata generated from Moduna trace context.
+ */
+export type ModunaTelemetryMetadata = Partial<Record<ModunaTelemetryMetadataKey, string>>;

package/dist/types/TraceContext.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@moduna/otel",
+  "version": "1.0.0",
+  "private": false,
+  "description": "One-line OpenTelemetry setup for Moduna AI traces.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.46",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-node": "^0.218.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "langchain": "^1.4.0",
+    "openai": "^6.38.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/google": "^3.0.73",
+    "@langchain/google-genai": "^2.1.30",
+    "@types/node": "^25.6.2",
+    "ai": "^6.0.182",
+    "biome": "^0.3.3",
+    "tsx": "^4.12.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "format": "biome format",
+    "lint": "biome lint",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "test": "pnpm run build && pnpm run typecheck",
+    "pack:dry-run": "pnpm pack --dry-run",
+    "test:vercel-ai-sdk": "tsx test/vercel-ai-sdk.ts",
+    "test:langchain": "tsx test/langchain.ts"
+  }
+}