@grafana/sigil-sdk-js 0.0.1

package/docs/frameworks/llamaindex.md

@@ -0,0 +1,82 @@
+# LlamaIndex Handler (`@grafana/sigil-sdk-js/llamaindex`)
+
+Use `SigilLlamaIndexHandler` to map LlamaIndex workflow/agent callback lifecycles to Sigil generations.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js llamaindex
+```
+
+## Quickstart
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { withSigilLlamaIndexCallbacks } from '@grafana/sigil-sdk-js/llamaindex';
+import { CallbackManager, Settings } from 'llamaindex';
+
+const client = new SigilClient();
+const callbackManager = new CallbackManager();
+const config = withSigilLlamaIndexCallbacks({ callbackManager }, client, {
+  providerResolver: 'auto',
+  agentName: 'llamaindex-app',
+});
+
+Settings.callbackManager = config.callbackManager;
+```
+
+`withSigilLlamaIndexCallbacks(...)` registers Sigil listeners through LlamaIndex's callback-manager API and returns the configured `callbackManager`.
+If you already own a manager instance, use `attachSigilLlamaIndexCallbacks(existingManager, client, options)`.
+
+## Streaming snippet
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { SigilLlamaIndexHandler } from '@grafana/sigil-sdk-js/llamaindex';
+
+const client = new SigilClient();
+const handler = new SigilLlamaIndexHandler(client, { providerResolver: 'auto' });
+
+await handler.handleLLMStart(
+  { kwargs: { model: 'claude-sonnet-4-5' } },
+  ['stream workflow update'],
+  'run-1',
+  undefined,
+  { invocation_params: { model: 'claude-sonnet-4-5', streaming: true, session_id: 'workflow-42' } }
+);
+await handler.handleLLMNewToken('partial ', undefined, 'run-1');
+await handler.handleLLMNewToken('answer', undefined, 'run-1');
+await handler.handleLLMEnd({ llm_output: { model_name: 'claude-sonnet-4-5' } }, 'run-1');
+```
+
+## Conversation mapping
+
+Conversation ID precedence:
+
+1. `conversation_id` / `session_id` / `group_id`
+2. `thread_id`
+3. fallback: `sigil:framework:llamaindex:<run_id>`
+
+## Metadata and lineage
+
+- `sigil.framework.run_type` is always set.
+- Lineage keys are set when present: `run_id`, `thread_id`, `parent_run_id`, `component_name`, `retry_attempt`, `event_id`.
+
+Required tags:
+
+- `sigil.framework.name=llamaindex`
+- `sigil.framework.source=handler`
+- `sigil.framework.language=javascript`
+
+## Provider resolver
+
+- `gpt-`/`o1`/`o3`/`o4` -> `openai`
+- `claude-` -> `anthropic`
+- `gemini-` -> `gemini`
+- otherwise `custom`
+
+## Troubleshooting
+
+- If lineage metadata is missing, include it in callback metadata payload.
+- Keep `captureInputs` and `captureOutputs` enabled for full generation reconstruction.
+- Call `await client.flush()` at checkpoints in long-running workers.

package/docs/frameworks/openai-agents.md

@@ -0,0 +1,88 @@
+# OpenAI Agents Handler (`@grafana/sigil-sdk-js/openai-agents`)
+
+Use `SigilOpenAIAgentsHandler` to map OpenAI Agents lifecycle callbacks to Sigil generations.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js @openai/agents
+```
+
+## Quickstart
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { withSigilOpenAIAgentsHooks } from '@grafana/sigil-sdk-js/openai-agents';
+import { Runner } from '@openai/agents';
+
+const client = new SigilClient();
+const runner = new Runner();
+const sigilHooks = withSigilOpenAIAgentsHooks(runner, client, {
+  providerResolver: 'auto',
+  agentName: 'openai-agents-app',
+  agentVersion: '1.0.0',
+});
+
+// optional cleanup if the runner lifecycle ends
+sigilHooks.detach();
+```
+
+`withSigilOpenAIAgentsHooks(...)` attaches Sigil listeners directly to OpenAI Agents `RunHooks`/`AgentHooks` emitters (`Runner` or `Agent`).
+
+## Streaming snippet
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { SigilOpenAIAgentsHandler } from '@grafana/sigil-sdk-js/openai-agents';
+
+const client = new SigilClient();
+const handler = new SigilOpenAIAgentsHandler(client, { providerResolver: 'auto' });
+
+await handler.handleLLMStart(
+  { kwargs: { model: 'gpt-5' } },
+  ['stream status'],
+  'run-1',
+  undefined,
+  { invocation_params: { model: 'gpt-5', stream: true, session_id: 'session-42' } }
+);
+await handler.handleLLMNewToken('hello ', undefined, 'run-1');
+await handler.handleLLMNewToken('world', undefined, 'run-1');
+await handler.handleLLMEnd({ llm_output: { model_name: 'gpt-5' } }, 'run-1');
+```
+
+## Conversation mapping
+
+Conversation ID precedence:
+
+1. `conversation_id` / `session_id` / `group_id` from callback metadata or invocation payload
+2. framework thread id (`thread_id`)
+3. deterministic fallback: `sigil:framework:openai-agents:<run_id>`
+
+## Metadata and lineage
+
+Injected metadata keys:
+
+- `sigil.framework.run_type` (required)
+- `sigil.framework.run_id`
+- `sigil.framework.thread_id`
+- `sigil.framework.parent_run_id`
+- `sigil.framework.component_name`
+- `sigil.framework.retry_attempt`
+- `sigil.framework.event_id`
+
+Required framework tags:
+
+- `sigil.framework.name=openai-agents`
+- `sigil.framework.source=handler`
+- `sigil.framework.language=javascript`
+
+## Provider resolver
+
+Order: explicit provider option -> framework payload provider -> model prefix inference -> `custom`.
+
+## Troubleshooting
+
+- No events exported: ensure you passed a `Runner`/`Agent` instance (not run options) to `withSigilOpenAIAgentsHooks`.
+- Missing conversation grouping: pass `conversation_id` or `session_id` in callback metadata/config.
+- Unknown provider: set `provider` explicitly in handler options.
+- No flush at shutdown: call `await client.shutdown()`.

package/docs/frameworks/vercel-ai-sdk.md

@@ -0,0 +1,124 @@
+# Vercel AI SDK Hooks (`@grafana/sigil-sdk-js/vercel-ai-sdk`)
+
+Use `createSigilVercelAiSdk(...)` to instrument Vercel AI SDK v5 calls with Sigil generation export, spans, metrics, tool execution spans, and streaming TTFT.
+
+Supported AI SDK line:
+
+- `ai` v5 (`generateText`, `streamText`)
+- Baseline generation export uses `onStepFinish` (and `onError` for streams). This path is v5-compatible and records tool executions from step `toolResults`.
+- When `experimental_onStepStart`, `experimental_onToolCallStart`, and `experimental_onToolCallFinish` are available (v6+), Sigil also captures richer per-step input messages and tool timing correlation.
+- Experimental callbacks can change in patch releases. Keep `ai` pinned to a tested minor line (`v5.x` or `v6.x`) in production.
+
+## Install
+
+```bash
+pnpm add @grafana/sigil-sdk-js ai
+```
+
+## Quickstart
+
+```ts
+import { SigilClient } from '@grafana/sigil-sdk-js';
+import { createSigilVercelAiSdk } from '@grafana/sigil-sdk-js/vercel-ai-sdk';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const client = new SigilClient();
+const sigil = createSigilVercelAiSdk(client, {
+  agentName: 'research-agent',
+  agentVersion: '1.0.0',
+});
+
+const result = await generateText({
+  model: openai('gpt-5'),
+  prompt: 'Summarize this ticket in one paragraph.',
+  ...sigil.generateTextHooks({ conversationId: 'chat-123' }),
+});
+```
+
+The model object stays untouched. Sigil only consumes hook callbacks.
+
+## Conversation ID (required for multi-turn continuity)
+
+Vercel AI SDK is stateless on the server side. For multi-turn grouping, pass a stable `conversationId` per call:
+
+```ts
+const hooks = sigil.generateTextHooks({ conversationId: 'customer-42' });
+```
+
+Precedence:
+
+1. `generateTextHooks({ conversationId })` / `streamTextHooks({ conversationId })`
+2. `resolveConversationId(stepStartEvent)` from global integration options
+3. fallback `sigil:framework:vercel-ai-sdk:<response.id>` (single-response scope)
+
+## Multi-step agentic loop (`generateText`)
+
+```ts
+import { generateText, stopWhen } from 'ai';
+
+const result = await generateText({
+  model: openai('gpt-5'),
+  prompt: 'What is the weather in Paris?',
+  tools: {
+    weather: {
+      description: 'Read weather by city',
+      inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+      execute: async ({ city }) => ({ city, temp_c: 18 }),
+    },
+  },
+  stopWhen: stopWhen.stepCountIs(2),
+  ...sigil.generateTextHooks({ conversationId: 'weather-chat-1' }),
+});
+```
+
+Each model step emits one generation with:
+
+- `metadata["sigil.framework.step_type"]` (`initial`, `continue`, `tool-result`)
+- per-step input captured when `experimental_onStepStart` is available (including prior tool result messages)
+
+## Streaming (`streamText`) and TTFT
+
+```ts
+import { streamText } from 'ai';
+import { anthropic } from '@ai-sdk/anthropic';
+
+const stream = streamText({
+  model: anthropic('claude-sonnet-4-5'),
+  prompt: 'Stream a concise status update.',
+  ...sigil.streamTextHooks({ conversationId: 'stream-chat-1' }),
+});
+
+for await (const _chunk of stream.textStream) {
+  // consume stream
+}
+```
+
+`streamTextHooks()` records TTFT from the first text chunk (`onChunk` with `chunk.type === "text"`).
+
+## Privacy controls
+
+Disable model/tool payload capture:
+
+```ts
+const sigil = createSigilVercelAiSdk(client, {
+  captureInputs: false,
+  captureOutputs: false,
+});
+```
+
+- `captureInputs=false`: no generation input messages and no tool arguments
+- `captureOutputs=false`: no generation output text and no tool results
+
+## Troubleshooting
+
+- Missing usage numbers:
+  - Provider may not return usage fields in AI SDK `onStepFinish`.
+  - Sigil handles missing usage safely and exports zeros only when usage payloads exist.
+- Missing TTFT:
+  - TTFT is only emitted for `streamText` steps where text chunks are observed.
+- Tool span not appearing:
+  - Ensure tool has `execute` and AI SDK emits tool lifecycle callbacks.
+  - `toolCallId` must be present in callback payloads.
+- Stream errors not exported:
+  - Make sure `onError` is reachable in your stream-consumption path.

package/docs/index.md

@@ -0,0 +1,22 @@
+# Sigil JS SDK Docs
+
+This directory contains public SDK usage docs for the TypeScript/JavaScript package.
+
+## Start Here
+
+- SDK overview and core API: `../README.md`
+
+## Provider Guides
+
+- `providers/openai.md`
+- `providers/anthropic.md`
+- `providers/gemini.md`
+
+## Framework Guides
+
+- `frameworks/langchain.md`
+- `frameworks/langgraph.md`
+- `frameworks/openai-agents.md`
+- `frameworks/llamaindex.md`
+- `frameworks/google-adk.md`
+- `frameworks/vercel-ai-sdk.md`

package/docs/providers/anthropic.md

@@ -0,0 +1,69 @@
+# Sigil JS Provider Helper: Anthropic
+
+This helper maps strict Anthropic Messages payloads into Sigil `Generation` records.
+
+## Embeddings support
+
+This helper currently supports Anthropic Messages APIs only. Native Anthropic embeddings endpoints are not available in the official SDK/API surface used in this repository.
+
+## Scope
+
+- Wrapper calls:
+  - `anthropic.messages.create(client, request, providerCall, options?)`
+  - `anthropic.messages.stream(client, request, providerCall, options?)`
+- Mapper functions:
+  - `anthropic.messages.fromRequestResponse(request, response, options?)`
+  - `anthropic.messages.fromStream(request, summary, options?)`
+- Raw artifacts (debug opt-in):
+  - `request`
+  - `response` (sync)
+  - `provider_event` (stream)
+
+## Wrapper-first example
+
+```ts
+import { SigilClient, anthropic } from "@grafana/sigil-sdk-js";
+
+const client = new SigilClient();
+
+const response = await anthropic.messages.create(
+  client,
+  {
+    model: "claude-sonnet-4-5",
+    max_tokens: 256,
+    messages: [{ role: "user", content: [{ type: "text", text: "Hello" }] }],
+  },
+  async (request) => provider.messages.create(request)
+);
+```
+
+## Explicit flow example
+
+```ts
+const recorder = client.startGeneration({
+  model: { provider: "anthropic", name: "claude-sonnet-4-5" },
+});
+
+try {
+  const response = await provider.messages.create(request);
+  recorder.setResult(anthropic.messages.fromRequestResponse(request, response));
+} catch (error) {
+  recorder.setCallError(error);
+  throw error;
+} finally {
+  recorder.end();
+}
+```
+
+## Raw artifact policy
+
+- Default OFF.
+- Enable only for debug workflows with `{ rawArtifacts: true }`.
+
+## Provider metadata mapping
+
+In addition to normalized usage fields, Anthropic server-tool counters are mapped into Sigil metadata when present:
+
+- `sigil.gen_ai.usage.server_tool_use.web_search_requests`
+- `sigil.gen_ai.usage.server_tool_use.web_fetch_requests`
+- `sigil.gen_ai.usage.server_tool_use.total_requests`

package/docs/providers/gemini.md

@@ -0,0 +1,86 @@
+# Sigil JS Provider Helper: Gemini
+
+This helper maps strict Gemini `model/contents/config` payloads into Sigil `Generation` records.
+
+## Scope
+
+- Wrapper calls:
+  - `gemini.models.generateContent(client, model, contents, config, providerCall, options?)`
+  - `gemini.models.generateContentStream(client, model, contents, config, providerCall, options?)`
+  - `gemini.models.embedContent(client, model, contents, config, providerCall, options?)`
+- Mapper functions:
+  - `gemini.models.fromRequestResponse(model, contents, config, response, options?)`
+  - `gemini.models.fromStream(model, contents, config, summary, options?)`
+  - `gemini.models.embeddingFromResponse(model, contents, config, response)`
+- Raw artifacts (debug opt-in):
+  - `request`
+  - `response` (sync)
+  - `provider_event` (stream)
+
+## Wrapper-first example
+
+```ts
+import { SigilClient, gemini } from "@grafana/sigil-sdk-js";
+
+const client = new SigilClient();
+
+const model = "gemini-2.5-pro";
+const contents = [{ role: "user", parts: [{ text: "Hello" }] }];
+const config = { maxOutputTokens: 256 };
+
+const response = await gemini.models.generateContent(
+  client,
+  model,
+  contents,
+  config,
+  async (reqModel, reqContents, reqConfig) =>
+    provider.models.generateContent({ model: reqModel, contents: reqContents, config: reqConfig })
+);
+```
+
+## Explicit flow example
+
+```ts
+const recorder = client.startGeneration({
+  model: { provider: "gemini", name: model },
+});
+
+try {
+  const response = await provider.models.generateContent({ model, contents, config });
+  recorder.setResult(gemini.models.fromRequestResponse(model, contents, config, response));
+} catch (error) {
+  recorder.setCallError(error);
+  throw error;
+} finally {
+  recorder.end();
+}
+```
+
+## Embedding example
+
+```ts
+const embeddingResponse = await gemini.models.embedContent(
+  client,
+  'gemini-embedding-001',
+  [{ parts: [{ text: 'hello' }] }, { parts: [{ text: 'world' }] }],
+  { outputDimensionality: 256 },
+  async (reqModel, reqContents, reqConfig) =>
+    provider.models.embedContent({ model: reqModel, contents: reqContents, config: reqConfig })
+);
+
+console.log(embeddingResponse.embeddings?.length ?? 0);
+```
+
+## Raw artifact policy
+
+- Default OFF.
+- Enable only for debug workflows with `{ rawArtifacts: true }`.
+
+## Provider metadata mapping
+
+Gemini-specific fields are mapped as follows:
+
+- `usage.thoughtsTokenCount` -> normalized `usage.reasoningTokens`
+- `usage.toolUsePromptTokenCount` -> metadata `sigil.gen_ai.usage.tool_use_prompt_tokens`
+- `config.thinkingConfig.thinkingBudget` -> metadata `sigil.gen_ai.request.thinking.budget_tokens`
+- `config.thinkingConfig.thinkingLevel` -> metadata `sigil.gen_ai.request.thinking.level`

package/docs/providers/openai.md

@@ -0,0 +1,151 @@
+# Sigil JS Provider Helper: OpenAI
+
+This helper now mirrors official OpenAI SDK shapes for both Chat Completions and Responses.
+
+## Public API
+
+- Chat Completions wrappers:
+  - `openai.chat.completions.create(client, request, providerCall, options?)`
+  - `openai.chat.completions.stream(client, request, providerCall, options?)`
+- Chat Completions mappers:
+  - `openai.chat.completions.fromRequestResponse(request, response, options?)`
+  - `openai.chat.completions.fromStream(request, summary, options?)`
+
+- Responses wrappers:
+  - `openai.responses.create(client, request, providerCall, options?)`
+  - `openai.responses.stream(client, request, providerCall, options?)`
+- Responses mappers:
+  - `openai.responses.fromRequestResponse(request, response, options?)`
+  - `openai.responses.fromStream(request, summary, options?)`
+
+- Embeddings wrapper:
+  - `openai.embeddings.create(client, request, providerCall, options?)`
+- Embeddings mapper:
+  - `openai.embeddings.fromRequestResponse(request, response)`
+
+## Integration styles
+
+- Strict wrappers: call OpenAI and record in one step.
+- Manual instrumentation: call OpenAI yourself, then map strict OpenAI request/response payloads with `fromRequestResponse` or `fromStream`.
+
+## Responses-first wrapper example
+
+```ts
+import OpenAI from 'openai';
+import { SigilClient, openai } from '@grafana/sigil-sdk-js';
+
+const sigil = new SigilClient();
+const provider = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const response = await openai.responses.create(
+  sigil,
+  {
+    model: 'gpt-5',
+    instructions: 'Be concise',
+    input: 'Summarize rollout status in 3 bullets',
+    max_output_tokens: 300,
+  },
+  async (request) => provider.responses.create(request)
+);
+
+console.log(response.output_text);
+```
+
+## Chat Completions stream example
+
+```ts
+const summary = await openai.chat.completions.stream(
+  sigil,
+  {
+    model: 'gpt-5',
+    stream: true,
+    messages: [{ role: 'user', content: 'Stream a short status update' }],
+  },
+  async (request) => {
+    const stream = await provider.chat.completions.create(request);
+    const events = [];
+    for await (const event of stream) {
+      events.push(event);
+    }
+    return { events };
+  }
+);
+```
+
+## Manual instrumentation example (strict mapper)
+
+```ts
+const request = {
+  model: 'gpt-5',
+  instructions: 'Be concise',
+  input: 'Summarize rollout status in 3 bullets',
+};
+
+const options = {
+  conversationId: 'conv-1',
+  agentName: 'assistant',
+  agentVersion: '1.0.0',
+};
+
+const recorder = sigil.startGeneration({
+  conversationId: options.conversationId,
+  agentName: options.agentName,
+  agentVersion: options.agentVersion,
+  model: { provider: 'openai', name: request.model },
+});
+
+try {
+  const response = await provider.responses.create(request);
+  recorder.setResult(openai.responses.fromRequestResponse(request, response, options));
+} catch (error) {
+  recorder.setCallError(error);
+  throw error;
+} finally {
+  recorder.end();
+}
+```
+
+## Embeddings example
+
+```ts
+const embeddingResponse = await openai.embeddings.create(
+  sigil,
+  {
+    model: 'text-embedding-3-small',
+    input: ['hello', 'world'],
+  },
+  async (request) => provider.embeddings.create(request)
+);
+
+console.log(embeddingResponse.model);
+```
+
+## Raw artifact policy
+
+Raw artifacts are OFF by default.
+
+- Chat artifact names:
+  - `openai.chat.request`
+  - `openai.chat.response`
+  - `openai.chat.tools`
+  - `openai.chat.stream_events`
+- Responses artifact names:
+  - `openai.responses.request`
+  - `openai.responses.response`
+  - `openai.responses.tools`
+  - `openai.responses.stream_events`
+
+Enable only for debugging:
+
+```ts
+{ rawArtifacts: true }
+```
+
+## Usage mapping notes
+
+OpenAI usage details map into normalized token usage fields:
+
+- Chat Completions: `prompt_tokens_details.cached_tokens` -> `usage.cacheReadInputTokens`
+- Chat Completions: `completion_tokens_details.reasoning_tokens` -> `usage.reasoningTokens`
+- Responses: `input_tokens_details.cached_tokens` -> `usage.cacheReadInputTokens`
+- Responses: `output_tokens_details.reasoning_tokens` -> `usage.reasoningTokens`