@grafana/sigil-sdk-js 0.0.1

package/dist/utils.js

@@ -0,0 +1,331 @@
+const textEncoder = new TextEncoder();
+export function encodedSizeBytes(value) {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+}
+export function defaultOperationNameForMode(mode) {
+    return mode === 'STREAM' ? 'streamText' : 'generateText';
+}
+export function validateGeneration(generation) {
+    if (generation.id.trim().length === 0) {
+        return new Error('generation id is required');
+    }
+    if (generation.mode !== 'SYNC' && generation.mode !== 'STREAM') {
+        return new Error('generation.mode must be one of SYNC|STREAM');
+    }
+    if (generation.model.provider.trim().length === 0) {
+        return new Error('generation model provider is required');
+    }
+    if (generation.model.name.trim().length === 0) {
+        return new Error('generation model name is required');
+    }
+    for (let index = 0; index < (generation.input ?? []).length; index++) {
+        const error = validateMessage('generation.input', index, generation.input?.[index]);
+        if (error !== undefined) {
+            return error;
+        }
+    }
+    for (let index = 0; index < (generation.output ?? []).length; index++) {
+        const error = validateMessage('generation.output', index, generation.output?.[index]);
+        if (error !== undefined) {
+            return error;
+        }
+    }
+    for (let index = 0; index < (generation.tools ?? []).length; index++) {
+        const tool = generation.tools?.[index];
+        if (tool === undefined || tool.name.trim().length === 0) {
+            return new Error(`generation.tools[${index}].name is required`);
+        }
+    }
+    for (let index = 0; index < (generation.artifacts ?? []).length; index++) {
+        const error = validateArtifact(index, generation.artifacts?.[index]);
+        if (error !== undefined) {
+            return error;
+        }
+    }
+    if (generation.completedAt.getTime() < generation.startedAt.getTime()) {
+        return new Error('generation completedAt must not be earlier than startedAt');
+    }
+    return undefined;
+}
+export function validateToolExecution(toolExecution) {
+    if (toolExecution.toolName.trim().length === 0) {
+        return new Error('tool execution name is required');
+    }
+    if (toolExecution.completedAt.getTime() < toolExecution.startedAt.getTime()) {
+        return new Error('tool execution completedAt must not be earlier than startedAt');
+    }
+    return undefined;
+}
+export function validateEmbeddingStart(start) {
+    if (start.model.provider.trim().length === 0) {
+        return new Error('embedding.model.provider is required');
+    }
+    if (start.model.name.trim().length === 0) {
+        return new Error('embedding.model.name is required');
+    }
+    if (start.dimensions !== undefined && start.dimensions <= 0) {
+        return new Error('embedding.dimensions must be > 0');
+    }
+    if (start.encodingFormat !== undefined && start.encodingFormat.trim().length === 0) {
+        return new Error('embedding.encoding_format must not be blank');
+    }
+    return undefined;
+}
+export function validateEmbeddingResult(result) {
+    if (result.inputCount < 0) {
+        return new Error('embedding.input_count must be >= 0');
+    }
+    if (result.inputTokens !== undefined && result.inputTokens < 0) {
+        return new Error('embedding.input_tokens must be >= 0');
+    }
+    if (result.dimensions !== undefined && result.dimensions <= 0) {
+        return new Error('embedding.dimensions must be > 0');
+    }
+    return undefined;
+}
+export function asError(value) {
+    if (value instanceof Error) {
+        return value;
+    }
+    return new Error(String(value));
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function maybeUnref(timer) {
+    if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
+        const maybeTimer = timer;
+        maybeTimer.unref?.();
+    }
+}
+export function defaultSleep(durationMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+}
+export function cloneGeneration(generation) {
+    return {
+        ...generation,
+        model: cloneModelRef(generation.model),
+        input: generation.input?.map(cloneMessage),
+        output: generation.output?.map(cloneMessage),
+        tools: generation.tools?.map(cloneToolDefinition),
+        usage: generation.usage ? { ...generation.usage } : undefined,
+        startedAt: new Date(generation.startedAt),
+        completedAt: new Date(generation.completedAt),
+        tags: generation.tags ? { ...generation.tags } : undefined,
+        metadata: generation.metadata ? { ...generation.metadata } : undefined,
+        artifacts: generation.artifacts === null ? null : generation.artifacts?.map(cloneArtifact),
+    };
+}
+export function cloneGenerationResult(result) {
+    return {
+        ...result,
+        input: result.input?.map(cloneMessage),
+        output: result.output?.map(cloneMessage),
+        tools: result.tools?.map(cloneToolDefinition),
+        usage: result.usage ? { ...result.usage } : undefined,
+        completedAt: result.completedAt ? new Date(result.completedAt) : undefined,
+        tags: result.tags ? { ...result.tags } : undefined,
+        metadata: result.metadata ? { ...result.metadata } : undefined,
+        artifacts: result.artifacts?.map(cloneArtifact),
+    };
+}
+export function cloneGenerationStart(start) {
+    return {
+        ...start,
+        model: cloneModelRef(start.model),
+        tools: start.tools?.map(cloneToolDefinition),
+        tags: start.tags ? { ...start.tags } : undefined,
+        metadata: start.metadata ? { ...start.metadata } : undefined,
+        startedAt: start.startedAt ? new Date(start.startedAt) : undefined,
+    };
+}
+export function cloneEmbeddingStart(start) {
+    return {
+        ...start,
+        model: cloneModelRef(start.model),
+        tags: start.tags ? { ...start.tags } : undefined,
+        metadata: start.metadata ? { ...start.metadata } : undefined,
+        startedAt: start.startedAt ? new Date(start.startedAt) : undefined,
+    };
+}
+export function cloneEmbeddingResult(result) {
+    return {
+        ...result,
+        inputTexts: result.inputTexts ? [...result.inputTexts] : undefined,
+    };
+}
+export function cloneToolExecution(toolExecution) {
+    return {
+        ...toolExecution,
+        startedAt: new Date(toolExecution.startedAt),
+        completedAt: new Date(toolExecution.completedAt),
+    };
+}
+export function cloneToolExecutionStart(start) {
+    return {
+        ...start,
+        startedAt: start.startedAt ? new Date(start.startedAt) : undefined,
+    };
+}
+export function cloneToolExecutionResult(result) {
+    return {
+        ...result,
+        completedAt: result.completedAt ? new Date(result.completedAt) : undefined,
+    };
+}
+export function cloneModelRef(model) {
+    return { ...model };
+}
+export function cloneMessage(message) {
+    return {
+        ...message,
+        parts: message.parts?.map(cloneMessagePart),
+    };
+}
+export function cloneToolDefinition(tool) {
+    return { ...tool };
+}
+export function cloneArtifact(artifact) {
+    return { ...artifact };
+}
+export function newLocalID(prefix) {
+    const now = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `${prefix}-${now}-${rand}`;
+}
+function cloneMessagePart(part) {
+    switch (part.type) {
+        case 'text':
+            return {
+                type: 'text',
+                text: part.text,
+                metadata: part.metadata ? { ...part.metadata } : undefined,
+            };
+        case 'thinking':
+            return {
+                type: 'thinking',
+                thinking: part.thinking,
+                metadata: part.metadata ? { ...part.metadata } : undefined,
+            };
+        case 'tool_call':
+            return {
+                type: 'tool_call',
+                toolCall: { ...part.toolCall },
+                metadata: part.metadata ? { ...part.metadata } : undefined,
+            };
+        case 'tool_result':
+            return {
+                type: 'tool_result',
+                toolResult: { ...part.toolResult },
+                metadata: part.metadata ? { ...part.metadata } : undefined,
+            };
+    }
+}
+function validateMessage(path, index, message) {
+    if (message === undefined) {
+        return new Error(`${path}[${index}] is required`);
+    }
+    const role = normalizeRole(message.role);
+    if (role !== 'user' && role !== 'assistant' && role !== 'tool') {
+        return new Error(`${path}[${index}].role must be one of user|assistant|tool`);
+    }
+    const hasContent = typeof message.content === 'string' && message.content.trim().length > 0;
+    const parts = message.parts ?? [];
+    if (parts.length === 0 && !hasContent) {
+        return new Error(`${path}[${index}].parts must not be empty`);
+    }
+    for (let partIndex = 0; partIndex < parts.length; partIndex++) {
+        const part = parts[partIndex];
+        if (part === undefined) {
+            return new Error(`${path}[${index}].parts[${partIndex}] is required`);
+        }
+        const error = validatePart(path, index, partIndex, role, part);
+        if (error !== undefined) {
+            return error;
+        }
+    }
+    return undefined;
+}
+function validatePart(path, messageIndex, partIndex, role, part) {
+    const payloadFieldCount = payloadFieldsCount(part);
+    if (payloadFieldCount !== 1) {
+        return new Error(`${path}[${messageIndex}].parts[${partIndex}] must set exactly one payload field`);
+    }
+    switch (part.type) {
+        case 'text':
+            if (part.text.trim().length === 0) {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].text is required`);
+            }
+            return undefined;
+        case 'thinking':
+            if (role !== 'assistant') {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].thinking only allowed for assistant role`);
+            }
+            if (part.thinking.trim().length === 0) {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].thinking is required`);
+            }
+            return undefined;
+        case 'tool_call':
+            if (role !== 'assistant') {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].tool_call only allowed for assistant role`);
+            }
+            if (part.toolCall.name.trim().length === 0) {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].tool_call.name is required`);
+            }
+            return undefined;
+        case 'tool_result':
+            if (role !== 'tool') {
+                return new Error(`${path}[${messageIndex}].parts[${partIndex}].tool_result only allowed for tool role`);
+            }
+            return undefined;
+        default:
+            return new Error(`${path}[${messageIndex}].parts[${partIndex}].kind is invalid`);
+    }
+}
+function payloadFieldsCount(part) {
+    let count = 0;
+    if ('text' in part && typeof part.text === 'string' && part.text.trim().length > 0) {
+        count++;
+    }
+    if ('thinking' in part && typeof part.thinking === 'string' && part.thinking.trim().length > 0) {
+        count++;
+    }
+    if ('toolCall' in part && isRecord(part.toolCall)) {
+        count++;
+    }
+    if ('toolResult' in part && isRecord(part.toolResult)) {
+        count++;
+    }
+    return count;
+}
+function validateArtifact(index, artifact) {
+    if (artifact === undefined) {
+        return new Error(`generation.artifacts[${index}] is required`);
+    }
+    const kind = artifact.type.trim().toLowerCase();
+    switch (kind) {
+        case 'request':
+        case 'response':
+        case 'tools':
+        case 'provider_event':
+            break;
+        default:
+            return new Error(`generation.artifacts[${index}].kind is invalid`);
+    }
+    const payload = artifact.payload?.trim() ?? '';
+    const recordID = artifact.recordId?.trim() ?? '';
+    if (payload.length === 0 && recordID.length === 0) {
+        return new Error(`generation.artifacts[${index}] must provide payload or record_id`);
+    }
+    return undefined;
+}
+function normalizeRole(role) {
+    const normalized = role.trim().toLowerCase();
+    if (normalized === 'user' || normalized === 'assistant' || normalized === 'tool') {
+        return normalized;
+    }
+    return '';
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/docs/frameworks/google-adk.md

@@ -0,0 +1,84 @@
+# Google ADK Handler (`@grafana/sigil-sdk-js/google-adk`)
+
+Use `SigilGoogleAdkHandler` to map Google ADK session/invocation callbacks to Sigil generations.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js @google/adk
+```
+
+## Quickstart
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { withSigilGoogleAdkPlugins } from '@grafana/sigil-sdk-js/google-adk';
+
+const client = new SigilClient();
+const runnerConfig = withSigilGoogleAdkPlugins(undefined, client, {
+  providerResolver: 'auto',
+  agentName: 'adk-app',
+});
+```
+
+Or create the plugin explicitly:
+
+```ts
+import { createSigilGoogleAdkPlugin } from '@grafana/sigil-sdk-js/google-adk';
+
+const sigilPlugin = createSigilGoogleAdkPlugin(client, { providerResolver: 'auto' });
+const runnerConfig = { plugins: [sigilPlugin] };
+```
+
+`withSigilGoogleAdkPlugins(...)` appends Sigil instrumentation to ADK plugin config while preserving existing plugins.
+The appended plugin implements the ADK callback surface (`beforeRunCallback`, `onEventCallback`, `afterRunCallback`, model/tool lifecycle callbacks).
+
+## Streaming snippet
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { SigilGoogleAdkHandler } from '@grafana/sigil-sdk-js/google-adk';
+
+const client = new SigilClient();
+const handler = new SigilGoogleAdkHandler(client, { providerResolver: 'auto' });
+
+await handler.handleLLMStart(
+  { kwargs: { model: 'gemini-2.5-pro' } },
+  ['stream adk step'],
+  'run-1',
+  undefined,
+  { invocation_params: { model: 'gemini-2.5-pro', stream: true, session_id: 'adk-session-42' } }
+);
+await handler.handleLLMNewToken('step ', undefined, 'run-1');
+await handler.handleLLMNewToken('done', undefined, 'run-1');
+await handler.handleLLMEnd({ llm_output: { model_name: 'gemini-2.5-pro' } }, 'run-1');
+```
+
+## Conversation mapping
+
+Primary mapping is ADK conversation/session identity:
+
+1. `conversation_id` / `session_id` / `group_id`
+2. `thread_id`
+3. fallback: `sigil:framework:google-adk:<run_id>`
+
+## Metadata and lineage
+
+- Required: `sigil.framework.run_type`
+- Optional lineage: `sigil.framework.run_id`, `sigil.framework.parent_run_id`, `sigil.framework.thread_id`, `sigil.framework.event_id`, `sigil.framework.component_name`
+
+Tags:
+
+- `sigil.framework.name=google-adk`
+- `sigil.framework.source=handler`
+- `sigil.framework.language=javascript`
+
+## Provider resolver
+
+Uses explicit provider first, then payload, then model-prefix inference.
+
+## Troubleshooting
+
+- Reused ADK sessions should pass stable `session_id` for correct grouping.
+- Use `provider` option when model names are custom aliases.
+- Call `await client.shutdown()` to guarantee export flush.

package/docs/frameworks/langchain.md

@@ -0,0 +1,102 @@
+# LangChain Handler (`@grafana/sigil-sdk-js/langchain`)
+
+Use `SigilLangChainHandler` to map LangChain callback lifecycle events to Sigil generation records.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js @langchain/core @langchain/openai
+```
+
+## Usage
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { withSigilLangChainCallbacks } from '@grafana/sigil-sdk-js/langchain';
+
+const client = new SigilClient();
+const config = withSigilLangChainCallbacks(undefined, client, {
+  providerResolver: 'auto',
+  agentName: 'langchain-app',
+});
+```
+
+## End-to-end example (invoke + stream)
+
+```ts
+import { ChatOpenAI } from '@langchain/openai';
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import {
+  SigilLangChainHandler,
+  withSigilLangChainCallbacks,
+} from '@grafana/sigil-sdk-js/langchain';
+
+const client = new SigilClient();
+const handler = new SigilLangChainHandler(client, {
+  providerResolver: 'auto',
+  agentName: 'langchain-example',
+  agentVersion: '1.0.0',
+});
+
+const llm = new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 });
+
+// Non-stream call -> SYNC generation mode.
+const result = await llm.invoke(
+  'Summarize why retry budgets matter.',
+  withSigilLangChainCallbacks(undefined, client, { providerResolver: 'auto' })
+);
+console.log(result.content);
+
+// Stream call -> STREAM generation mode + TTFT tracking.
+const stream = await llm.stream(
+  'Give me three short reliability tips.',
+  withSigilLangChainCallbacks(undefined, client, { providerResolver: 'auto' })
+);
+for await (const chunk of stream) {
+  if (chunk.content) process.stdout.write(String(chunk.content));
+}
+process.stdout.write('\n');
+
+// Advanced usage: instantiate and pass a handler manually.
+const handler = new SigilLangChainHandler(client, { providerResolver: 'auto' });
+await llm.invoke('manual handler wiring', { callbacks: [handler] });
+
+await client.shutdown();
+```
+
+## Contract
+
+- `handleLLMStart` / `handleChatModelStart` starts recorder lifecycle.
+- `handleLLMNewToken` sets first-token timestamp and accumulates streamed output.
+- `handleLLMEnd` maps output + usage and ends recorder.
+- `handleLLMError` sets call error and ends recorder.
+- `handleToolStart` / `handleToolEnd` / `handleToolError` maps into `startToolExecution(...)`.
+- `handleChainStart` / `handleChainEnd` / `handleChainError` emits framework chain spans.
+- `handleRetrieverStart` / `handleRetrieverEnd` / `handleRetrieverError` emits framework retriever spans.
+
+Framework tags and metadata are always injected:
+
+- `sigil.framework.name=langchain`
+- `sigil.framework.source=handler`
+- `sigil.framework.language=javascript`
+- `metadata["sigil.framework.run_id"]=<framework run id>`
+- `metadata["sigil.framework.thread_id"]=<thread id>` (when present in callback metadata/config)
+- `metadata["sigil.framework.parent_run_id"]=<parent run id>` (when available)
+- `metadata["sigil.framework.component_name"]=<serialized component name>`
+- `metadata["sigil.framework.run_type"]=<llm|chat|tool|chain|retriever>`
+- `metadata["sigil.framework.tags"]=<normalized callback tags>`
+- `metadata["sigil.framework.retry_attempt"]=<attempt>` (when available)
+- `metadata["sigil.framework.event_id"]=<event id>` (when available)
+- generation span attributes mirror low-cardinality framework metadata keys
+
+Conversation mapping is conversation-first:
+
+- `conversation_id` / `session_id` / `group_id` first
+- then `thread_id`
+- deterministic fallback `sigil:framework:langchain:<run_id>`
+
+Provider resolver behavior:
+
+- explicit provider metadata when available
+- model prefix inference (`gpt-`/`o1`/`o3`/`o4` -> `openai`, `claude-` -> `anthropic`, `gemini-` -> `gemini`)
+- fallback `custom`

package/docs/frameworks/langgraph.md

@@ -0,0 +1,137 @@
+# LangGraph Handler (`@grafana/sigil-sdk-js/langgraph`)
+
+Use `SigilLangGraphHandler` to map LangGraph callback lifecycle events to Sigil generation records.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js @langchain/core @langchain/langgraph @langchain/openai
+```
+
+## Usage
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { withSigilLangGraphCallbacks } from '@grafana/sigil-sdk-js/langgraph';
+
+const client = new SigilClient();
+const config = withSigilLangGraphCallbacks(undefined, client, { providerResolver: 'auto' });
+```
+
+## End-to-end example (graph invoke + stream)
+
+```ts
+import { ChatOpenAI } from '@langchain/openai';
+import { END, START, StateGraph, Annotation } from '@langchain/langgraph';
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import {
+  SigilLangGraphHandler,
+  withSigilLangGraphCallbacks,
+} from '@grafana/sigil-sdk-js/langgraph';
+
+const GraphState = Annotation.Root({
+  prompt: Annotation<string>(),
+  answer: Annotation<string>(),
+});
+
+const client = new SigilClient();
+const handler = new SigilLangGraphHandler(client, {
+  providerResolver: 'auto',
+  agentName: 'langgraph-example',
+  agentVersion: '1.0.0',
+});
+const llm = new ChatOpenAI({ model: 'gpt-4o-mini', temperature: 0 });
+
+const graph = new StateGraph(GraphState)
+  .addNode('model', async (state) => {
+    const response = await llm.invoke(
+      state.prompt,
+      withSigilLangGraphCallbacks(undefined, client, { providerResolver: 'auto' })
+    );
+    return { answer: String(response.content) };
+  })
+  .addEdge(START, 'model')
+  .addEdge('model', END)
+  .compile();
+
+// Non-stream graph invocation.
+const out = await graph.invoke({ prompt: 'Explain SLO burn rate in one paragraph.', answer: '' });
+console.log(out.answer);
+
+// Streamed graph updates.
+for await (const _event of graph.stream({ prompt: 'List three practical alerting tips.', answer: '' })) {
+  // Consume events to drive streamed model execution.
+}
+
+// Advanced usage: instantiate and pass a handler manually.
+const handler = new SigilLangGraphHandler(client, { providerResolver: 'auto' });
+await llm.invoke('manual handler wiring', { callbacks: [handler] });
+
+await client.shutdown();
+```
+
+## Persistent thread example (LangGraph checkpointer)
+
+```ts
+import { MemorySaver } from '@langchain/langgraph';
+
+const checkpointer = new MemorySaver();
+const persistedGraph = new StateGraph(GraphState)
+  .addNode('model', async (state) => {
+    const response = await llm.invoke(state.prompt, { callbacks: [handler] });
+    return { answer: String(response.content) };
+  })
+  .addEdge(START, 'model')
+  .addEdge('model', END)
+  .compile({ checkpointer });
+const threadConfig = {
+  ...withSigilLangGraphCallbacks(undefined, client, { providerResolver: 'auto' }),
+  configurable: { thread_id: 'customer-42' },
+};
+
+await persistedGraph.invoke({ prompt: 'Remember that my timezone is UTC+1.', answer: '' }, threadConfig);
+await persistedGraph.invoke({ prompt: 'What timezone did I just give you?', answer: '' }, threadConfig);
+```
+
+When `thread_id` is present, the handler records:
+
+- `conversationId=<thread_id>`
+- `metadata["sigil.framework.run_id"]=<run id>`
+- `metadata["sigil.framework.thread_id"]=<thread id>`
+- generation span attributes `sigil.framework.run_id` and `sigil.framework.thread_id`
+
+When `conversation_id` / `session_id` / `group_id` is present, that value is used as primary `conversationId`.
+
+## Contract
+
+- `handleLLMStart` / `handleChatModelStart` starts recorder lifecycle.
+- `handleLLMNewToken` sets first-token timestamp and accumulates streamed output.
+- `handleLLMEnd` maps output + usage and ends recorder.
+- `handleLLMError` sets call error and ends recorder.
+- `handleToolStart` / `handleToolEnd` / `handleToolError` maps into `startToolExecution(...)`.
+- `handleChainStart` / `handleChainEnd` / `handleChainError` emits framework chain spans.
+- `handleRetrieverStart` / `handleRetrieverEnd` / `handleRetrieverError` emits framework retriever spans.
+
+Framework tags and metadata are always injected:
+
+- `sigil.framework.name=langgraph`
+- `sigil.framework.source=handler`
+- `sigil.framework.language=javascript`
+- `metadata["sigil.framework.run_id"]=<framework run id>`
+- `metadata["sigil.framework.thread_id"]=<thread id>` (when present in callback metadata/config)
+- `metadata["sigil.framework.parent_run_id"]=<parent run id>` (when available)
+- `metadata["sigil.framework.component_name"]=<serialized component name>`
+- `metadata["sigil.framework.run_type"]=<llm|chat|tool|chain|retriever>`
+- `metadata["sigil.framework.tags"]=<normalized callback tags>`
+- `metadata["sigil.framework.retry_attempt"]=<attempt>` (when available)
+- `metadata["sigil.framework.event_id"]=<event id>` (when available)
+- `metadata["sigil.framework.langgraph.node"]=<node id>` (when callback context exposes it)
+- generation span attributes mirror low-cardinality framework metadata keys
+
+Fallback conversation mapping uses `sigil:framework:langgraph:<run_id>` when no framework session key is available.
+
+Provider resolver behavior:
+
+- explicit provider metadata when available
+- model prefix inference (`gpt-`/`o1`/`o3`/`o4` -> `openai`, `claude-` -> `anthropic`, `gemini-` -> `gemini`)
+- fallback `custom`