TrackContext

context on a trace is structured data for RAG and retrieval: which documents or chunks informed the model, how they were retrieved, and optional high-level instructions. It appears in the Noryen UI alongside the prompt and response.

Do not confuse this with noryen.setContext(), which only merges default metadata keys into every event. TrackContext is the context field on track() (and on events emitted by wrappers).

Shape

TrackContext supports:

documents — array of items with required content, plus optional id, source, score, and metadata
retrieval — optional query, method, and k
instructions — optional string (for example system or policy text you want grouped with the trace)

Manual track()

When you are not using a wrapper (for example custom fetch to OpenRouter), pass context on noryen.track():

track-with-context.ts

import { noryen } from "@noryen/sdk";

noryen.init({ apiKey: process.env.NORYEN_API_KEY });

noryen.track({
  model: "google/gemini-2.0-flash-001",
  provider: "openrouter",
  prompt: "Analyze the user health summary.",
  response: "{ … }",
  latency: 1200,
  metadata: { feature: "personal_plan_generation" },
  context: {
    instructions: "You are a health assistant…",
    documents: [
      {
        content: "Structured health data or placeholder for an attachment.",
        source: "app.health_data",
      },
    ],
    retrieval: {
      query: "user health data analysis",
      method: "manual",
      k: 1,
    },
  },
});

Wrappers

Provider wrappers can fill in trace context automatically from messages and provider-specific payloads (for example tool results, file search, grounding metadata). You do not need to duplicate that in track() when the wrapped client already carries the information.

Document tags in prompts

If your prompts embed chunks as <document>…</document>, enable parsing when wrapping the OpenAI client:

openai-with-tags.ts

import OpenAI from "openai";
import { noryen } from "@noryen/sdk";

noryen.init({ apiKey: process.env.NORYEN_API_KEY });

const client = noryen.wrapOpenAI(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  { parseDocumentTags: true },
);

Extracted blocks are attached to the trace context for debugging and evaluation.

Metadata and setContext