@anvia/langfuse 0.3.9 → 0.5.0

package/README.md

@@ -63,6 +63,8 @@ explicit options always win.
 | `environment` | `LANGFUSE_TRACING_ENVIRONMENT`| Tag attached to every trace.                               |
 | `release`     | `LANGFUSE_RELEASE`            | Tag attached to every trace.                               |
 | `serviceName` | `LANGFUSE_SERVICE_NAME`       | Recorded on the root observation and as the OTel `service.name` resource attribute. |
+| `captureMode` | —                             | `"safe"` (default) records instructions/messages plus request summaries; `"full"` includes documents, tool definitions, schemas, and additional parameters. |
+| `captureMaxBytes` | —                          | Maximum encoded size per captured value; defaults to 262,144 bytes and must be at least 96. |
 
 ```ts
 const tracing = langfuse.create({
@@ -73,24 +75,26 @@ const tracing = langfuse.create({
 
 ## Observation metadata
 
-The adapter records extra data on Langfuse observations so the UI
-shows everything the agent runtime emits:
+The adapter records structured model and runtime data while keeping
+the default capture surface bounded:
 
-- **Generation observations** carry `providerRequest` and `modelInfo`
-  (with `provider`, `defaultModel`, and `capabilities`) on start, and
-  `firstDeltaMs` on end. `usageDetails` always includes
-  `cachedInputTokens` and `cacheCreationInputTokens`.
+- **Generation observations** carry system instructions, model messages,
+  the resolved model, and `modelInfo`. Full capture also includes the
+  sanitized `providerRequest`.
+  `completionStartTime` and `firstDeltaMs` provide native time-to-first-token data.
+- **Usage details** use mutually exclusive `input`, `output`, cache, and
+  reasoning buckets so Langfuse can infer cost without double counting.
 - **Generation observations** receive a `generation.update({ output: { delta } })`
   call for every streaming delta (`text_delta`, `reasoning_delta`,
   `tool_call`), so the Langfuse UI reflects partial output as the
   model produces it.
-- **Tool observations** carry `toolDefinition` and `toolMetadata` on
-  start, and `structuredResult` on end.
+- **Tool observations** carry arguments on start and structured results on
+  end. Definitions and tool metadata are included when `captureMode: "full"`.
 - **Root run observation** carries `serviceName` and the configured
   `metadata` from `AgentRunStartArgs`.
 
-User-supplied `trace.metadata` always wins over the built-in fields
-above (the spread order preserves it).
+Binary and base64 bodies are replaced with omission markers. Oversized
+values are replaced with deterministic bounded previews.
 
 ## Eval Scores
 
@@ -110,6 +114,7 @@ const reporter = createLangfuseEvalReporter(tracing, {
   onMissingTrace: "ignore", // "ignore" | "warn" | "throw"
   truncateInputAt: 2048, // max bytes for case input/expected summaries
   includeMessages: true, // include output.messages in score metadata
+  includeContext: false, // opt in to context/retrievalContext score metadata
 });
 ```
 
@@ -127,6 +132,10 @@ const reporter = createLangfuseEvalReporter(tracing, {
 - `includeMessages` controls whether `output.messages` (if present)
   is included in score metadata.
 
+- `includeContext` controls whether case `context` and
+  `retrievalContext` are included in score metadata. It defaults to
+  `false` because retrieved documents may contain sensitive data.
+
 ### Trace resolution
 
 The reporter resolves a trace ID for each case in three tiers:
@@ -231,8 +240,8 @@ trace?.addEvent("validation.passed");
 trace?.addAttributes({ quality: "high" });
 ```
 
-`addEvent` creates a Langfuse `event` observation under the active
-root and ends it immediately. `addAttributes` updates the root
+`addEvent` creates an instantaneous Langfuse `event` observation under the active
+root. `addAttributes` updates the root
 observation's metadata. Both calls bubble up to Langfuse via the
 existing OpenTelemetry span processor.
 
@@ -306,6 +315,7 @@ For eval suites, `runEvalAsExperiment` runs the suite and posts a
 dataset run alongside the metric scores:
 
 ```ts
+import { agentEvalTarget } from "@anvia/core/evals";
 import { runEvalAsExperiment } from "@anvia/langfuse";
 
 const { suite, datasetRun } = await runEvalAsExperiment(
@@ -315,7 +325,7 @@ const { suite, datasetRun } = await runEvalAsExperiment(
       { id: "c-1", input: "a", expected: "A" },
       { id: "c-2", input: "b", expected: "B" },
     ],
-    target: async (input) => input.toUpperCase(),
+    target: agentEvalTarget(supportAgent),
     metrics: [/* ... */],
     reporters: [/* existing reporters still score */],
   },
@@ -323,12 +333,19 @@ const { suite, datasetRun } = await runEvalAsExperiment(
     tracing,
     datasetName: "smoke-set",
     runName: "smoke-run",
+    publishScores: true,
+    reporterOptions: { onMissingTrace: "warn" },
   },
 );
 
 console.log(suite.passed, datasetRun.posted);
 ```
 
+`publishScores` adds a Langfuse eval reporter without replacing reporters
+already configured on the suite. `agentEvalTarget(...)` returns the response trace used to attach
+each score. Set `includeContexts: true` only when case context may be persisted in Langfuse dataset
+metadata.
+
 ### Options
 
 - `createLangfuseDatasetClient(tracing, options)`:
@@ -369,13 +386,12 @@ const prompts = createLangfusePromptClient(tracing);
 const prompt = await prompts.getPrompt("support.system");
 console.log(prompt.prompt, prompt.version);
 
-await tracing.startRun({
-  agentName: "support",
-  prompt: { role: "user", content: [{ type: "text", text: "hi" }] },
-  history: [],
-  maxTurns: 3,
-  promptRef: { name: "support.system", version: prompt.version },
-});
+await agent
+  .prompt("hi")
+  .withTrace({
+    promptRef: { name: "support.system", version: prompt.version },
+  })
+  .send();
 ```
 
 `promptRef` is also accepted on `trace.metadata` (keys
@@ -424,9 +440,10 @@ const tracing = langfuse.create({
 });
 ```
 
-- `redactInputs` redacts text on root inputs, chat history, and tool
-  arguments.
-- `redactOutputs` redacts generation output text and tool results.
+- `redactInputs` redacts system instructions, root inputs, chat history,
+  tool arguments, request metadata, and nested-agent inputs.
+- `redactOutputs` redacts streaming/final generation output, errors,
+  tool results, transcripts, and nested-agent outputs.
 - `"deep"` recurses into nested objects and arrays (in addition to
   top-level strings).
 

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { AgentObserver } from '@anvia/core/observability';
 import { EvalReporter, EvalSuiteResult, RunEvalSuiteOptions } from '@anvia/core/evals';
 
 type LangfuseRedactionMode = boolean | "deep";
+type LangfuseCaptureMode = "safe" | "full";
 type LangfuseRedactionOptions$1 = {
     patterns?: RedactorPattern$1[];
     replacement?: string;
@@ -22,6 +23,8 @@ type LangfuseTracingOptions = {
     scoreBatchSize?: number | undefined;
     scoreFlushIntervalMs?: number | undefined;
     scoreMaxRetries?: number | undefined;
+    captureMode?: LangfuseCaptureMode | undefined;
+    captureMaxBytes?: number | undefined;
     redactInputs?: LangfuseRedactionMode | undefined;
     redactOutputs?: LangfuseRedactionMode | undefined;
     redaction?: LangfuseRedactionOptions$1 | undefined;
@@ -60,6 +63,7 @@ type LangfuseEvalReporterOptions = {
     onMissingTrace?: "ignore" | "warn" | "throw" | undefined;
     truncateInputAt?: number | undefined;
     includeMessages?: boolean | undefined;
+    includeContext?: boolean | undefined;
 };
 type LangfuseDatasetClientOptions = {
     baseUrl?: string | undefined;
@@ -157,6 +161,9 @@ type RunEvalAsExperimentOptions<Input, Output, Expected = unknown> = Omit<Langfu
     client?: LangfuseDatasetClient;
     pageSize?: number | undefined;
     timeoutMs?: number | undefined;
+    publishScores?: boolean | undefined;
+    reporterOptions?: LangfuseEvalReporterOptions | undefined;
+    includeContexts?: boolean | undefined;
 };
 type RunEvalAsExperimentResult<Input, Output, Expected = unknown> = {
     suite: EvalSuiteResult<Input, Output, Expected>;
@@ -193,4 +200,4 @@ declare const langfuse: {
     create(options?: LangfuseTracingOptions): LangfuseTracing;
 };
 
-export { DEFAULT_PATTERNS, type LangfuseChatMessage, type LangfuseDataset, type LangfuseDatasetClient, type LangfuseDatasetClientOptions, type LangfuseDatasetItem, type LangfuseEvalReporterOptions, type LangfusePrompt, type LangfusePromptClient, type LangfusePromptClientOptions, type LangfusePromptGetOptions, type LangfuseRedactionMode, type LangfuseRedactionOptions, type LangfuseRunExperimentOptions, type LangfuseRunExperimentResult, type LangfuseRunItemError, type LangfuseRunItemResult, type LangfuseScoreArgs, type LangfuseScoreDataType, LangfuseScoreError, type LangfuseTraceHandle, type LangfuseTracing, type LangfuseTracingOptions, type PiiRedactor, type RedactorPattern, type RunEvalAsExperimentOptions, type RunEvalAsExperimentResult, createLangfuseDatasetClient, createLangfuseEvalReporter, createLangfusePromptClient, createPiiRedactor, langfuse, runEvalAsExperiment };
+export { DEFAULT_PATTERNS, type LangfuseCaptureMode, type LangfuseChatMessage, type LangfuseDataset, type LangfuseDatasetClient, type LangfuseDatasetClientOptions, type LangfuseDatasetItem, type LangfuseEvalReporterOptions, type LangfusePrompt, type LangfusePromptClient, type LangfusePromptClientOptions, type LangfusePromptGetOptions, type LangfuseRedactionMode, type LangfuseRedactionOptions, type LangfuseRunExperimentOptions, type LangfuseRunExperimentResult, type LangfuseRunItemError, type LangfuseRunItemResult, type LangfuseScoreArgs, type LangfuseScoreDataType, LangfuseScoreError, type LangfuseTraceHandle, type LangfuseTracing, type LangfuseTracingOptions, type PiiRedactor, type RedactorPattern, type RunEvalAsExperimentOptions, type RunEvalAsExperimentResult, createLangfuseDatasetClient, createLangfuseEvalReporter, createLangfusePromptClient, createPiiRedactor, langfuse, runEvalAsExperiment };