@grafana/sigil-sdk-js 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/LICENSE +3 -0
  2. package/README.md +367 -0
  3. package/dist/client.d.ts +102 -0
  4. package/dist/client.d.ts.map +1 -0
  5. package/dist/client.js +1502 -0
  6. package/dist/client.js.map +1 -0
  7. package/dist/config.d.ts +9 -0
  8. package/dist/config.d.ts.map +1 -0
  9. package/dist/config.js +190 -0
  10. package/dist/config.js.map +1 -0
  11. package/dist/content_capture.d.ts +35 -0
  12. package/dist/content_capture.d.ts.map +1 -0
  13. package/dist/content_capture.js +123 -0
  14. package/dist/content_capture.js.map +1 -0
  15. package/dist/context.d.ts +11 -0
  16. package/dist/context.d.ts.map +1 -0
  17. package/dist/context.js +53 -0
  18. package/dist/context.js.map +1 -0
  19. package/dist/exporters/default.d.ts +3 -0
  20. package/dist/exporters/default.d.ts.map +1 -0
  21. package/dist/exporters/default.js +34 -0
  22. package/dist/exporters/default.js.map +1 -0
  23. package/dist/exporters/grpc.d.ts +14 -0
  24. package/dist/exporters/grpc.d.ts.map +1 -0
  25. package/dist/exporters/grpc.js +369 -0
  26. package/dist/exporters/grpc.js.map +1 -0
  27. package/dist/exporters/http.d.ts +8 -0
  28. package/dist/exporters/http.d.ts.map +1 -0
  29. package/dist/exporters/http.js +258 -0
  30. package/dist/exporters/http.js.map +1 -0
  31. package/dist/frameworks/google-adk/index.d.ts +136 -0
  32. package/dist/frameworks/google-adk/index.d.ts.map +1 -0
  33. package/dist/frameworks/google-adk/index.js +509 -0
  34. package/dist/frameworks/google-adk/index.js.map +1 -0
  35. package/dist/frameworks/langchain/index.d.ts +29 -0
  36. package/dist/frameworks/langchain/index.d.ts.map +1 -0
  37. package/dist/frameworks/langchain/index.js +70 -0
  38. package/dist/frameworks/langchain/index.js.map +1 -0
  39. package/dist/frameworks/langgraph/index.d.ts +29 -0
  40. package/dist/frameworks/langgraph/index.d.ts.map +1 -0
  41. package/dist/frameworks/langgraph/index.js +70 -0
  42. package/dist/frameworks/langgraph/index.js.map +1 -0
  43. package/dist/frameworks/llamaindex/index.d.ts +43 -0
  44. package/dist/frameworks/llamaindex/index.d.ts.map +1 -0
  45. package/dist/frameworks/llamaindex/index.js +493 -0
  46. package/dist/frameworks/llamaindex/index.js.map +1 -0
  47. package/dist/frameworks/openai-agents/index.d.ts +33 -0
  48. package/dist/frameworks/openai-agents/index.d.ts.map +1 -0
  49. package/dist/frameworks/openai-agents/index.js +531 -0
  50. package/dist/frameworks/openai-agents/index.js.map +1 -0
  51. package/dist/frameworks/shared.d.ts +57 -0
  52. package/dist/frameworks/shared.d.ts.map +1 -0
  53. package/dist/frameworks/shared.js +1032 -0
  54. package/dist/frameworks/shared.js.map +1 -0
  55. package/dist/frameworks/vercel-ai-sdk/hooks.d.ts +18 -0
  56. package/dist/frameworks/vercel-ai-sdk/hooks.d.ts.map +1 -0
  57. package/dist/frameworks/vercel-ai-sdk/hooks.js +672 -0
  58. package/dist/frameworks/vercel-ai-sdk/hooks.js.map +1 -0
  59. package/dist/frameworks/vercel-ai-sdk/index.d.ts +8 -0
  60. package/dist/frameworks/vercel-ai-sdk/index.d.ts.map +1 -0
  61. package/dist/frameworks/vercel-ai-sdk/index.js +7 -0
  62. package/dist/frameworks/vercel-ai-sdk/index.js.map +1 -0
  63. package/dist/frameworks/vercel-ai-sdk/mapping.d.ts +49 -0
  64. package/dist/frameworks/vercel-ai-sdk/mapping.d.ts.map +1 -0
  65. package/dist/frameworks/vercel-ai-sdk/mapping.js +660 -0
  66. package/dist/frameworks/vercel-ai-sdk/mapping.js.map +1 -0
  67. package/dist/frameworks/vercel-ai-sdk/types.d.ts +126 -0
  68. package/dist/frameworks/vercel-ai-sdk/types.d.ts.map +1 -0
  69. package/dist/frameworks/vercel-ai-sdk/types.js +2 -0
  70. package/dist/frameworks/vercel-ai-sdk/types.js.map +1 -0
  71. package/dist/index.d.ts +12 -0
  72. package/dist/index.d.ts.map +1 -0
  73. package/dist/index.js +12 -0
  74. package/dist/index.js.map +1 -0
  75. package/dist/providers/anthropic.d.ts +35 -0
  76. package/dist/providers/anthropic.d.ts.map +1 -0
  77. package/dist/providers/anthropic.js +581 -0
  78. package/dist/providers/anthropic.js.map +1 -0
  79. package/dist/providers/gemini.d.ts +42 -0
  80. package/dist/providers/gemini.d.ts.map +1 -0
  81. package/dist/providers/gemini.js +650 -0
  82. package/dist/providers/gemini.js.map +1 -0
  83. package/dist/providers/openai.d.ts +67 -0
  84. package/dist/providers/openai.d.ts.map +1 -0
  85. package/dist/providers/openai.js +1007 -0
  86. package/dist/providers/openai.js.map +1 -0
  87. package/dist/types.d.ts +461 -0
  88. package/dist/types.d.ts.map +1 -0
  89. package/dist/types.js +2 -0
  90. package/dist/types.js.map +1 -0
  91. package/dist/utils.d.ts +25 -0
  92. package/dist/utils.d.ts.map +1 -0
  93. package/dist/utils.js +331 -0
  94. package/dist/utils.js.map +1 -0
  95. package/docs/frameworks/google-adk.md +84 -0
  96. package/docs/frameworks/langchain.md +102 -0
  97. package/docs/frameworks/langgraph.md +137 -0
  98. package/docs/frameworks/llamaindex.md +82 -0
  99. package/docs/frameworks/openai-agents.md +88 -0
  100. package/docs/frameworks/vercel-ai-sdk.md +124 -0
  101. package/docs/index.md +22 -0
  102. package/docs/providers/anthropic.md +69 -0
  103. package/docs/providers/gemini.md +86 -0
  104. package/docs/providers/openai.md +151 -0
  105. package/package.json +80 -0
  106. package/proto/opentelemetry/proto/collector/trace/v1/trace_service.proto +77 -0
  107. package/proto/opentelemetry/proto/common/v1/common.proto +115 -0
  108. package/proto/opentelemetry/proto/resource/v1/resource.proto +44 -0
  109. package/proto/opentelemetry/proto/trace/v1/trace.proto +357 -0
  110. package/proto/sigil/v1/generation_ingest.proto +145 -0
package/LICENSE ADDED
@@ -0,0 +1,3 @@
1
+ SPDX-License-Identifier: Apache-2.0
2
+
3
+ See /LICENSE at repository root for full license text.
package/README.md ADDED
@@ -0,0 +1,367 @@
1
+ # Grafana Sigil TypeScript/JavaScript SDK
2
+
3
+ Sigil records normalized LLM generation and tool-execution telemetry using your OpenTelemetry tracer/meter setup.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pnpm add @grafana/sigil-sdk-js
9
+ ```
10
+
11
+ ## Validation
12
+
13
+ Run the shared core conformance suite for the JavaScript SDK from the repo root:
14
+
15
+ ```bash
16
+ mise run test:ts:sdk-conformance
17
+ ```
18
+
19
+ Run the cross-language aggregate core conformance suite from the repo root:
20
+
21
+ ```bash
22
+ mise run sdk:conformance
23
+ ```
24
+
25
+ ## Quick Start
26
+
27
+ ```ts
28
+ import { SigilClient } from "@grafana/sigil-sdk-js";
29
+
30
+ const client = new SigilClient({
31
+ generationExport: {
32
+ protocol: "http",
33
+ endpoint: "http://localhost:8080/api/v1/generations:export",
34
+ auth: { mode: "tenant", tenantId: "dev-tenant" },
35
+ },
36
+ api: {
37
+ endpoint: "http://localhost:8080",
38
+ },
39
+ });
40
+
41
+ await client.startGeneration(
42
+ {
43
+ conversationId: "conv-1",
44
+ model: { provider: "openai", name: "gpt-5" },
45
+ },
46
+ async (recorder) => {
47
+ const outputText = "Hello from model";
48
+ recorder.setResult({
49
+ output: [{ role: "assistant", content: outputText }],
50
+ });
51
+ }
52
+ );
53
+
54
+ await client.shutdown();
55
+ ```
56
+
57
+ Configure OTEL exporters (traces/metrics) in your application OTEL SDK setup. You can optionally pass `tracer` and `meter` directly to `SigilClient`.
58
+
59
+ Quick OTEL setup pattern before creating the Sigil client:
60
+
61
+ ```ts
62
+ import { NodeSDK } from "@opentelemetry/sdk-node";
63
+
64
+ const otel = new NodeSDK();
65
+ await otel.start();
66
+ ```
67
+
68
+ ## Core API
69
+
70
+ - `startGeneration(...)` and `startStreamingGeneration(...)`
71
+ - `startToolExecution(...)`
72
+ - Recorder methods: `setResult(...)`, `setCallError(...)`, `end()`, `getError()`
73
+ - Lifecycle: `flush()`, `shutdown()`
74
+
75
+ ### Manual `try/finally` style
76
+
77
+ ```ts
78
+ const recorder = client.startGeneration({
79
+ model: { provider: "anthropic", name: "claude-sonnet-4-5" },
80
+ });
81
+
82
+ try {
83
+ recorder.setResult({
84
+ output: [{ role: "assistant", content: "Done" }],
85
+ });
86
+ } catch (error) {
87
+ recorder.setCallError(error);
88
+ throw error;
89
+ } finally {
90
+ recorder.end();
91
+ }
92
+ ```
93
+
94
+ ## Embedding Observability
95
+
96
+ Use `startEmbedding(...)` for embedding API calls. Embedding recording creates OTel spans and SDK metrics only, and does not enqueue generation exports.
97
+
98
+ ```ts
99
+ await client.startEmbedding(
100
+ {
101
+ agentName: "retrieval-worker",
102
+ agentVersion: "1.0.0",
103
+ model: { provider: "openai", name: "text-embedding-3-small" },
104
+ },
105
+ async (recorder) => {
106
+ const response = await openai.embeddings.create(request);
107
+ recorder.setResult({
108
+ inputCount: request.input.length,
109
+ inputTokens: response.usage?.prompt_tokens ?? 0,
110
+ inputTexts: request.input,
111
+ responseModel: response.model,
112
+ });
113
+ }
114
+ );
115
+ ```
116
+
117
+ Input text capture is opt-in:
118
+
119
+ ```ts
120
+ const client = new SigilClient({
121
+ embeddingCapture: {
122
+ captureInput: true,
123
+ maxInputItems: 20,
124
+ maxTextLength: 1024,
125
+ },
126
+ });
127
+ ```
128
+
129
+ `embeddingCapture.captureInput` may expose PII/document content in spans. Keep it disabled by default and enable it only for scoped debugging.
130
+
131
+ TraceQL examples:
132
+
133
+ - `traces{gen_ai.operation.name="embeddings"}`
134
+ - `traces{gen_ai.operation.name="embeddings" && gen_ai.request.model="text-embedding-3-small"}`
135
+ - `traces{gen_ai.operation.name="embeddings" && error.type!=""}`
136
+
137
+ ## Tool Execution Example
138
+
139
+ ```ts
140
+ await client.startToolExecution(
141
+ {
142
+ toolName: "weather",
143
+ includeContent: true,
144
+ },
145
+ async (recorder) => {
146
+ recorder.setResult({
147
+ arguments: { city: "Paris" },
148
+ result: { temp_c: 18 },
149
+ });
150
+ }
151
+ );
152
+ ```
153
+
154
+ ## Provider Helpers
155
+
156
+ - OpenAI: `docs/providers/openai.md`
157
+ - Anthropic: `docs/providers/anthropic.md`
158
+ - Gemini: `docs/providers/gemini.md`
159
+
160
+ ## Framework Handlers
161
+
162
+ Use module subpath exports for framework callback integrations:
163
+
164
+ - LangChain: `@grafana/sigil-sdk-js/langchain`
165
+ - LangGraph: `@grafana/sigil-sdk-js/langgraph`
166
+ - OpenAI Agents: `@grafana/sigil-sdk-js/openai-agents`
167
+ - LlamaIndex: `@grafana/sigil-sdk-js/llamaindex`
168
+ - Google ADK: `@grafana/sigil-sdk-js/google-adk`
169
+ - Vercel AI SDK: `@grafana/sigil-sdk-js/vercel-ai-sdk`
170
+ - LangChain guide: `docs/frameworks/langchain.md`
171
+ - LangGraph guide: `docs/frameworks/langgraph.md`
172
+ - OpenAI Agents guide: `docs/frameworks/openai-agents.md`
173
+ - LlamaIndex guide: `docs/frameworks/llamaindex.md`
174
+ - Google ADK guide: `docs/frameworks/google-adk.md`
175
+ - Vercel AI SDK guide: `docs/frameworks/vercel-ai-sdk.md`
176
+
177
+ ```ts
178
+ import { SigilClient } from "@grafana/sigil-sdk-js";
179
+ import { withSigilLangChainCallbacks } from "@grafana/sigil-sdk-js/langchain";
180
+ import { withSigilLangGraphCallbacks } from "@grafana/sigil-sdk-js/langgraph";
181
+ import { withSigilOpenAIAgentsHooks } from "@grafana/sigil-sdk-js/openai-agents";
182
+ import { withSigilLlamaIndexCallbacks } from "@grafana/sigil-sdk-js/llamaindex";
183
+ import { withSigilGoogleAdkPlugins } from "@grafana/sigil-sdk-js/google-adk";
184
+ import { createSigilVercelAiSdk } from "@grafana/sigil-sdk-js/vercel-ai-sdk";
185
+ import { Runner } from "@openai/agents";
186
+ import { CallbackManager } from "llamaindex";
187
+
188
+ const client = new SigilClient();
189
+ const langChainConfig = withSigilLangChainCallbacks(undefined, client, { providerResolver: "auto" });
190
+ const langGraphConfig = withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" });
191
+ const runner = new Runner();
192
+ const openAIAgentsHooks = withSigilOpenAIAgentsHooks(runner, client, { providerResolver: "auto" });
193
+ const callbackManager = new CallbackManager();
194
+ const llamaIndexConfig = withSigilLlamaIndexCallbacks({ callbackManager }, client, { providerResolver: "auto" });
195
+ const googleAdkRunnerConfig = withSigilGoogleAdkPlugins(undefined, client, { providerResolver: "auto" });
196
+ const vercelAiSdk = createSigilVercelAiSdk(client, { agentName: "vercel-agent" });
197
+ ```
198
+
199
+ Each framework handler injects:
200
+
201
+ - `sigil.framework.name` (`langchain`, `langgraph`, `openai-agents`, `llamaindex`, `google-adk`, or `vercel-ai-sdk`)
202
+ - `sigil.framework.source` (`handler` for existing callback handlers, `framework` for Vercel AI SDK hooks)
203
+ - `sigil.framework.language` (`javascript` for existing callback handlers, `typescript` for Vercel AI SDK hooks)
204
+ - `metadata["sigil.framework.run_id"]`
205
+ - `metadata["sigil.framework.thread_id"]` (when present)
206
+ - `metadata["sigil.framework.parent_run_id"]` (when available)
207
+ - `metadata["sigil.framework.component_name"]`
208
+ - `metadata["sigil.framework.run_type"]`
209
+ - `metadata["sigil.framework.tags"]`
210
+ - `metadata["sigil.framework.retry_attempt"]` (when available)
211
+ - `metadata["sigil.framework.event_id"]` (when available)
212
+ - `metadata["sigil.framework.langgraph.node"]` (LangGraph when available)
213
+
214
+ Conversation mapping is conversation-first:
215
+
216
+ - `conversation_id` / `session_id` / `group_id` from framework context first
217
+ - then `thread_id`
218
+ - deterministic fallback `sigil:framework:<framework_name>:<run_id>`
219
+
220
+ When present in generation metadata, low-cardinality framework keys are copied onto generation span attributes.
221
+
222
+ For LangGraph persistence, pass `configurable.thread_id` and reuse it across invocations:
223
+
224
+ ```ts
225
+ const threadConfig = {
226
+ ...withSigilLangGraphCallbacks(undefined, client, { providerResolver: "auto" }),
227
+ configurable: { thread_id: 'customer-42' },
228
+ };
229
+ await graph.invoke({ prompt: 'Remember my timezone is UTC+1.', answer: '' }, threadConfig);
230
+ await graph.invoke({ prompt: 'What timezone did I give you?', answer: '' }, threadConfig);
231
+ ```
232
+
233
+ ## Behavior
234
+
235
+ - Generation modes are explicit: `SYNC` and `STREAM`.
236
+ - Generation export supports HTTP, gRPC, and `none` (instrumentation-only).
237
+ - Traces/metrics use `config.tracer`/`config.meter` when provided, otherwise OTEL globals.
238
+ - Exports are asynchronous with bounded queueing and retry/backoff.
239
+ - `flush()` drains queued generations; `shutdown()` flushes and closes generation exporters.
240
+ - Empty tool names produce a no-op tool recorder.
241
+ - Generation/tool spans always include SDK identity attributes:
242
+ - `sigil.sdk.name=sdk-js`
243
+ - Normalized generation metadata always includes the same SDK identity key; conflicting caller values are overwritten.
244
+ - Raw provider artifacts are opt-in (`rawArtifacts: true`).
245
+
246
+ ## Instrumentation-only mode (no generation send)
247
+
248
+ Set `generationExport.protocol` to `"none"` to keep generation/tool instrumentation and spans while disabling generation transport.
249
+
250
+ ```ts
251
+ const client = new SigilClient({
252
+ generationExport: {
253
+ protocol: "none",
254
+ },
255
+ });
256
+ ```
257
+
258
+ ## SDK metrics
259
+
260
+ The SDK emits these OTel histograms through your configured OTEL meter provider:
261
+
262
+ - `gen_ai.client.operation.duration`
263
+ - `gen_ai.client.token.usage`
264
+ - `gen_ai.client.time_to_first_token`
265
+ - `gen_ai.client.tool_calls_per_operation`
266
+
267
+ ## Generation export auth modes
268
+
269
+ Auth is configured for `generationExport`.
270
+
271
+ - `mode: "none"`
272
+ - `mode: "tenant"` (requires `tenantId`, injects `X-Scope-OrgID`)
273
+ - `mode: "bearer"` (requires `bearerToken`, injects `Authorization: Bearer <token>`)
274
+ - `mode: "basic"` (requires `basicPassword` + `basicUser` or `tenantId`, injects `Authorization: Basic <base64(user:password)>`; also injects `X-Scope-OrgID` when `tenantId` is set — for self-hosted multi-tenancy only, not needed for Grafana Cloud)
275
+
276
+ Invalid mode/field combinations throw during client config resolution.
277
+
278
+ If explicit headers already contain `Authorization` or `X-Scope-OrgID`, explicit headers take precedence.
279
+
280
+ ```ts
281
+ const client = new SigilClient({
282
+ generationExport: {
283
+ protocol: "http",
284
+ endpoint: "http://localhost:8080/api/v1/generations:export",
285
+ auth: { mode: "tenant", tenantId: "prod-tenant" },
286
+ },
287
+ api: {
288
+ endpoint: "http://localhost:8080",
289
+ },
290
+ });
291
+ ```
292
+
293
+ ### Grafana Cloud auth (basic)
294
+
295
+ For Grafana Cloud, use `basic` auth mode. The username is your Grafana Cloud instance/tenant ID and the password is your Grafana Cloud API key:
296
+
297
+ ```ts
298
+ const client = new SigilClient({
299
+ generationExport: {
300
+ protocol: "http",
301
+ endpoint: "https://<your-stack>.grafana.net/api/v1/generations:export",
302
+ auth: {
303
+ mode: "basic",
304
+ tenantId: process.env.GRAFANA_CLOUD_INSTANCE_ID,
305
+ basicPassword: process.env.GRAFANA_CLOUD_API_KEY,
306
+ },
307
+ },
308
+ });
309
+ ```
310
+
311
+ If your deployment requires a distinct username, set `basicUser` explicitly:
312
+
313
+ ```ts
314
+ auth: {
315
+ mode: "basic",
316
+ tenantId: process.env.GRAFANA_CLOUD_INSTANCE_ID,
317
+ basicUser: process.env.GRAFANA_CLOUD_INSTANCE_ID,
318
+ basicPassword: process.env.GRAFANA_CLOUD_API_KEY,
319
+ },
320
+ ```
321
+
322
+ ## Env-secret wiring example
323
+
324
+ The SDK does not auto-load env vars. Resolve env secrets in your app and map them into config.
325
+
326
+ ```ts
327
+ const generationBearerToken = (process.env.SIGIL_GEN_BEARER_TOKEN ?? "").trim();
328
+
329
+ const client = new SigilClient({
330
+ generationExport: {
331
+ protocol: "http",
332
+ endpoint: "http://localhost:8080/api/v1/generations:export",
333
+ auth:
334
+ generationBearerToken.length > 0
335
+ ? { mode: "bearer", bearerToken: generationBearerToken }
336
+ : { mode: "tenant", tenantId: "dev-tenant" },
337
+ },
338
+ api: {
339
+ endpoint: "http://localhost:8080",
340
+ },
341
+ });
342
+ ```
343
+
344
+ Common topology:
345
+
346
+ - Grafana Cloud: generation `basic` mode with instance ID and API key.
347
+ - Self-hosted direct to Sigil: generation `tenant` mode.
348
+ - Traces/metrics via OTEL Collector/Alloy: configure exporters in your app OTEL SDK setup.
349
+ - Enterprise proxy: generation `bearer` mode to proxy; proxy authenticates and forwards tenant header upstream.
350
+
351
+ ## Conversation Ratings
352
+
353
+ Use the SDK helper to submit user-facing ratings:
354
+
355
+ ```ts
356
+ const result = await client.submitConversationRating("conv-123", {
357
+ ratingId: "rat-123",
358
+ rating: "CONVERSATION_RATING_VALUE_BAD",
359
+ comment: "Answer ignored user context",
360
+ metadata: { channel: "assistant-ui" },
361
+ source: "sdk-js",
362
+ });
363
+
364
+ console.log(result.rating.rating, result.summary.hasBadRating);
365
+ ```
366
+
367
+ `submitConversationRating` sends requests to `api.endpoint` (default `http://localhost:8080`) and uses the same generation-export auth headers (`tenant` or `bearer`) already configured on the SDK client.
@@ -0,0 +1,102 @@
1
+ import { type Span } from '@opentelemetry/api';
2
+ import type { ContentCaptureMode, ConversationRatingInput, EmbeddingRecorder, EmbeddingResult, EmbeddingStart, Generation, GenerationMode, GenerationRecorder, GenerationStart, RecorderCallback, SigilDebugSnapshot, SigilSdkConfigInput, SubmitConversationRatingResponse, ToolExecution, ToolExecutionRecorder, ToolExecutionStart } from './types.js';
3
+ export declare class SigilClient {
4
+ private readonly config;
5
+ private readonly nowFn;
6
+ private readonly sleepFn;
7
+ private readonly logger;
8
+ private readonly generationExporter;
9
+ private readonly tracer;
10
+ private readonly meter;
11
+ private readonly operationDurationHistogram;
12
+ private readonly tokenUsageHistogram;
13
+ private readonly ttftHistogram;
14
+ private readonly toolCallsHistogram;
15
+ private readonly generations;
16
+ private readonly toolExecutions;
17
+ private readonly pendingGenerations;
18
+ private flushPromise;
19
+ private flushRequested;
20
+ private flushTimer;
21
+ private shutdownPromise;
22
+ private shuttingDown;
23
+ private closed;
24
+ /**
25
+ * Creates a Sigil SDK client.
26
+ *
27
+ * `inputConfig` is merged with defaults.
28
+ */
29
+ constructor(inputConfig?: SigilSdkConfigInput);
30
+ /**
31
+ * Starts a generation recorder (`SYNC` mode).
32
+ *
33
+ * Overloads:
34
+ * - returns recorder for manual lifecycle
35
+ * - executes callback and auto-ends recorder
36
+ */
37
+ startGeneration(start: GenerationStart): GenerationRecorder;
38
+ startGeneration<TResult>(start: GenerationStart, callback: RecorderCallback<GenerationRecorder, TResult>): Promise<TResult>;
39
+ /**
40
+ * Starts a streaming generation recorder (`STREAM` mode).
41
+ *
42
+ * Overloads:
43
+ * - returns recorder for manual lifecycle
44
+ * - executes callback and auto-ends recorder
45
+ */
46
+ startStreamingGeneration(start: GenerationStart): GenerationRecorder;
47
+ startStreamingGeneration<TResult>(start: GenerationStart, callback: RecorderCallback<GenerationRecorder, TResult>): Promise<TResult>;
48
+ /**
49
+ * Starts an embeddings recorder.
50
+ *
51
+ * Overloads:
52
+ * - returns recorder for manual lifecycle
53
+ * - executes callback and auto-ends recorder
54
+ */
55
+ startEmbedding(start: EmbeddingStart): EmbeddingRecorder;
56
+ startEmbedding<TResult>(start: EmbeddingStart, callback: RecorderCallback<EmbeddingRecorder, TResult>): Promise<TResult>;
57
+ /**
58
+ * Starts a tool execution recorder.
59
+ *
60
+ * Empty tool names return a no-op recorder to keep instrumentation safe.
61
+ */
62
+ startToolExecution(start: ToolExecutionStart): ToolExecutionRecorder;
63
+ startToolExecution<TResult>(start: ToolExecutionStart, callback: RecorderCallback<ToolExecutionRecorder, TResult>): Promise<TResult>;
64
+ /** Submits a user-facing conversation rating through Sigil HTTP API. */
65
+ submitConversationRating(conversationId: string, input: ConversationRatingInput): Promise<SubmitConversationRatingResponse>;
66
+ /** Forces immediate drain of queued generation exports. */
67
+ flush(): Promise<void>;
68
+ /** Flushes pending generations and shuts down the generation exporter. */
69
+ shutdown(): Promise<void>;
70
+ /** Returns a cloned in-memory snapshot for debugging and tests. */
71
+ debugSnapshot(): SigilDebugSnapshot;
72
+ internalNow(): Date;
73
+ internalRecordGeneration(generation: Generation): void;
74
+ internalRecordToolExecution(toolExecution: ToolExecution): void;
75
+ internalEnqueueGeneration(generation: Generation): void;
76
+ internalLogWarn(message: string, error?: unknown): void;
77
+ internalResolveGenerationContentCaptureMode(seed: GenerationStart): ContentCaptureMode;
78
+ internalResolveToolIncludeContent(seed: ToolExecutionStart): boolean;
79
+ internalStartGenerationSpan(seed: GenerationStart, mode: GenerationMode, startedAt: Date): Span;
80
+ internalStartEmbeddingSpan(seed: EmbeddingStart, startedAt: Date): Span;
81
+ internalStartToolExecutionSpan(seed: ToolExecutionStart, startedAt: Date): Span;
82
+ internalApplyTraceContextFromSpan(span: Span, generation: Generation): void;
83
+ internalSyncGenerationSpan(span: Span, generation: Generation): void;
84
+ internalClearSpanConversationTitle(span: Span): void;
85
+ internalFinalizeGenerationSpan(span: Span, generation: Generation, callError: string | undefined, validationError: Error | undefined, enqueueError: Error | undefined, firstTokenAt: Date | undefined, precomputedCallErrorCategory?: string): void;
86
+ internalFinalizeEmbeddingSpan(span: Span, seed: EmbeddingStart, result: EmbeddingResult, hasResult: boolean, callError: Error | undefined, localError: Error | undefined, startedAt: Date, completedAt: Date): void;
87
+ internalFinalizeToolExecutionSpan(span: Span, toolExecution: ToolExecution, localError: Error | undefined): Error | undefined;
88
+ private recordGenerationMetrics;
89
+ private recordEmbeddingMetrics;
90
+ private recordTokenUsage;
91
+ private recordToolExecutionMetrics;
92
+ private assertOpen;
93
+ private startGenerationWithMode;
94
+ private triggerAsyncFlush;
95
+ private flushInternal;
96
+ private drainPendingGenerations;
97
+ private exportWithRetry;
98
+ private logRejectedResults;
99
+ private stopFlushTimer;
100
+ private logWarn;
101
+ }
102
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}