NestJS Profiler
API Reference

nest-profiler-ai

Types and API of the AI SDK collector.

AiCollectorModuleOptions

Prop

Type

AiCaptureLevel

type AiCaptureLevel = 'none' | 'metadata' | 'redacted' | 'full';

How much of one kind of content reaches a stored profile. none keeps the figures and records nothing of what was said, metadata keeps the shape ([text omitted · 1842 chars]), redacted is the default and masks credentials and personal data, and full stores it verbatim with no masking.

AiCaptureFieldLevels

A level per content field, for the setups where one field is more sensitive than the rest. Resolution runs from the narrowest: a field, then the group it belongs to (prompt covers instructions and messages, tools covers the three tool fields), then default. runtimeContext is outside that chain — the AI SDK's runtimeContext on a call and each tool's toolContext hold the application's own state rather than what was said, so they are recorded only when the field is named, not even by capture: 'full'. providerPayload, the raw bodies exchanged with the provider, is outside it for the same reason.

Prop

Type

AiCaptureOptions

type AiCaptureOptions = AiCaptureLevel | AiCaptureFieldLevels;

AI_CAPTURE_FIELDS / AI_CAPTURE_GROUPS

const AI_CAPTURE_FIELDS: readonly AiCaptureField[];
const AI_CAPTURE_GROUPS: { prompt: [...]; tools: [...] };

Every field a level can be set on, and the shorthands that cover several of them at once.

AiRedactionOptions

What the redacted level masks, on top of the built-in detectors it shares with the rest of the profiler.

Prop

Type

AiSanitizer

type AiSanitizer = (text: string, context: AiRedactionContext) => string;

A scrubber of the host's own, run over every text that is kept, after the built-in masking.

AiRedactionContext

What is being masked, handed to sanitize: the content field (or 'error' for a provider message), the role of the message it belongs to, and the tool it belongs to.

Prop

Type

AI_PII_PATTERNS

const AI_PII_PATTERNS: readonly RegExp[];

The personal-data shapes the redacted level masks beyond the credential detectors: email addresses, international phone numbers, IBANs and US social-security numbers. Exported so a host can see exactly what is matched, and extend it through redaction.patterns.

AiCallEntry

One provider round-trip. A tool loop records several, distinguished by step.

Prop

Type

AiProviderPayload

The call as the provider saw it, recorded only where capture.providerPayload asks for it.

Prop

Type

AiToolExecutionEntry

One tool the SDK ran between two model calls — real time, spent outside the model.

Prop

Type

instrumentAgentClass

function instrumentAgentClass(agentClass: unknown): boolean;

Teaches every AI SDK agent in the process to name itself in the profiles it produces, by wrapping generate and stream on the agent class's prototype. AiCollectorModule calls it at startup with the SDK's ToolLoopAgent, so an application never has to — it is exported for a host that drives the collector itself.

This is what keeps agent attribution free of any call-site change: the application declares its agent's identity the way the SDK already asks it to, with the id setting, and never imports the profiler to get it recorded. The wrapper only reads id and opens an async frame around the original call; it changes no argument, no result and no error, and agents built before it ran are covered too since a method is looked up on the prototype at call time.

Returns whether this call instrumented the class — false if it was already done, or if the installed ai exposes no such class.

profileAgent

function profileAgent<A extends AiAgentLike>(agent: A, options?: ProfileAgentOptions): A;

The escape hatch, for the two cases instrumentAgentClass cannot reach: an agent that implements the SDK's Agent interface itself rather than extending ToolLoopAgent, and an agent whose panel name should differ from its id. A ToolLoopAgent with an id needs none of this.

const support = profileAgent(myCustomAgent, { id: 'support', name: 'Support agent' });

await support.generate({ prompt });
await pipeAgentUIStreamToResponse({ agent: support, uiMessages, response });

The returned agent is the same object to every caller, so it can be provided in place of the original and handed to createAgentUIStream, createAgentUIStreamResponse or pipeAgentUIStreamToResponse unchanged. When both apply, the wrapper's name wins over the id the class instrumentation would have used.

Unlike the id route, this puts an import of this package in application code. With the dev-dependency install that file must stay out of production code; to keep the call there, install the profiler as a regular dependency behind the runtime gate.

AiAgentInfo

Which agent drove a generation, as recorded on every entry it produced.

Prop

Type

ProfileAgentOptions

Prop

Type

AiAgentLike

What profileAgent needs of an agent — the AI SDK's Agent, and anything shaped like it.

Prop

Type

AiToolDefinition

A tool as it was declared to the model, with the schema the model had to fill.

Prop

Type

AiToolOrigin

type AiToolOrigin = 'local' | 'mcp' | 'provider' | 'harness';

Where a tool comes from, which decides who runs it: local is declared in the application's code, mcp was discovered on an MCP server at runtime, and provider is built into the model itself (a provider-run web search, say) and never executes in the application at all.

harness is built into the coding-agent runtime a HarnessAgent drives (Claude Code's Bash or Read) and runs in its sandbox rather than in the application.

AiMessage

One message of the conversation as it was sent to the model.

Prop

Type

AiMessagePart

A message part that is not plain text — a tool call, a tool result, an attachment. An attachment is recorded as its media type and its size or URL, never as its bytes.

Prop

Type

AiApproval

A human-in-the-loop decision on one tool call.

Prop

Type

AiCallSettings

The sampling settings a call was made with — what a reproduction would need.

Prop

Type

AiTokenUsage

Prop

Type

AiCollectorData

What the collector exposes to its panel.

Prop

Type

AiModelPricing

What one model charges. Rates are per per tokens — a million by default, the unit providers publish. A rate left out falls back to the one it refines, so a model with no cache discount and no separate thinking rate needs only input and output.

Prop

Type

AiPricingTable

type AiPricingTable = Record<string, AiModelPricing>;

Prices by model. A key is provider:model (openai:gpt-4o-mini) or the bare model id (gpt-4o-mini), matched in that order and case-insensitively. A provider arrives qualified by its transport (openai.responses), and its root is tried too.

AiPricingSource

type AiPricingSource = () => AiPricingTable | Promise<AiPricingTable>;

Loads a price table from wherever the prices live. Called when the module starts and, once pricingTtl has passed, again in the background — never on the path of a model call.

estimateCost

function estimateCost(
  usage: AiTokenUsage | undefined,
  provider: string,
  model: string,
): number | undefined;

What a call cost, from its token counts and the configured prices — undefined when the model has no price. Cached and thinking tokens are billed at their own rate and are already counted in the input and output totals, so each is taken out before its rate is applied. The collector applies this itself; call it directly only to cost something of your own.

mcpToolNamesOf

function mcpToolNamesOf(tools: unknown): Set<string>;

The names of the MCP tools in a tool set, told apart from local ones by the marks @ai-sdk/mcp's client leaves on every tool it builds. The collector calls it on each operation's start event — the last point at which a tool still says where it came from, since the provider only ever sees names and schemas — so tools discovered through that client are labelled mcp with nothing declared.

markMcpTools

function markMcpTools(names: readonly string[]): void;

Declares tool names as coming from an MCP server. Only needed for an integration that builds its MCP tools itself rather than through @ai-sdk/mcp's client, which mcpToolNamesOf recognises on its own. Call it once after loading a server's tools.

Unlike the automatic path, this puts an import of this package in application code. With the dev-dependency install that file must stay out of production code; to keep the call there, install the profiler as a regular dependency behind the runtime gate.

AI_ENTRYPOINT_TYPE

const AI_ENTRYPOINT_TYPE = 'ai';

The Profile.entrypoint.type a profiled HTTP request is promoted to once it has called a model.

AiInstrumentation

interface AiInstrumentation {
  install(integration: Telemetry): void | Promise<void>;
}

An optional integration for an agent implementation the AI SDK core does not ship, listed in AiCollectorModule.forRoot({ instrumentations }). Implementations are NestJS providers. install runs once at startup, after the collector has registered its telemetry integration; one that fails is logged and never takes the application down.

Subpath /pricing

Ready-made pricingSource loaders for public price lists, kept off the main entry for applications that hardcode their prices or load them from their own store.

import { fetchLiteLLMPricing } from '@eleven-labs/nest-profiler-ai/pricing';

AiCollectorModule.forRoot({ pricingSource: () => fetchLiteLLMPricing() });

fetchOpenRouterPricing

function fetchOpenRouterPricing(options?: OpenRouterPricingOptions): Promise<AiPricingTable>;

Reads the prices of every model OpenRouter serves, ready to hand to pricingSource. The list is public, so no key is needed. Model ids come back as OpenRouter writes them (openai/gpt-4o-mini), which is what the AI SDK reports for a call that went through OpenRouter.

Prop

Type

fetchLiteLLMPricing

function fetchLiteLLMPricing(options?: LiteLLMPricingOptions): Promise<AiPricingTable>;

Reads the prices LiteLLM keeps for every model of every provider, ready to hand to pricingSource. The file is public, so no key is needed. Model ids come back the way a provider's own API names them (claude-haiku-4-5, gpt-4o-mini), with the prompt-cache rates — the list to pick for direct provider calls and for a HarnessAgent driving Claude Code or Codex, which report tokens but no cost.

Prop

Type

Subpath /harness

Everything specific to @ai-sdk/harness lives here, so the package's main entry never imports it. @ai-sdk/harness is an optional peer dependency, needed only when this subpath is used.

HarnessInstrumentation

import { HarnessInstrumentation } from '@eleven-labs/nest-profiler-ai/harness';

AiCollectorModule.forRoot({ instrumentations: [HarnessInstrumentation] });

Profiles the turns of every HarnessAgent in the process — Claude Code, Codex or any other coding-agent runtime driven through the AI SDK. It imports @ai-sdk/harness/agent when installed and hands the class to instrumentHarnessAgentClass.

instrumentHarnessAgentClass

function instrumentHarnessAgentClass(agentClass: unknown, integration: Telemetry): boolean;

The HarnessAgent counterpart of instrumentAgentClass. It wraps generate, stream, continueGenerate and continueStream on the class's prototype so each turn is named after the agent's id, and completes the agent's telemetry setting with integration on its first turn — a HarnessAgent reports to no integration otherwise, not even the global ones. HarnessInstrumentation calls it, so an application never has to.

Returns whether this call instrumented the class — false if it was already done, or if what was passed is not a class.

HARNESS_OPERATION

const HARNESS_OPERATION = 'ai.harness';

The operation a call recorded from a HarnessAgent turn carries, where generateText records ai.generateText.

Public exports

import { AiCollectorModule } from '@eleven-labs/nest-profiler-ai';
import { AiCollector } from '@eleven-labs/nest-profiler-ai';
import { markMcpTools, isMcpTool, mcpToolNamesOf } from '@eleven-labs/nest-profiler-ai';
import { profileAgent, instrumentAgentClass } from '@eleven-labs/nest-profiler-ai';
import {
  configureAiPricing,
  loadAiPricing,
  resetAiPricing,
  pricingFor,
  estimateCost,
} from '@eleven-labs/nest-profiler-ai';
import {
  AI_COLLECTOR_OPTIONS,
  AI_ENTRIES_KEY,
  AI_ENTRYPOINT_TYPE,
  buildAiEntrypointType,
  isAiCall,
} from '@eleven-labs/nest-profiler-ai';
import {
  AI_CAPTURE_FIELDS,
  AI_CAPTURE_GROUPS,
  AI_PII_PATTERNS,
} from '@eleven-labs/nest-profiler-ai';

import type {
  AiCollectorModuleOptions,
  AiCollectorModuleAsyncOptions,
  AiInstrumentation,
  AiAgentInfo,
  AiAgentLike,
  ProfileAgentOptions,
  AiEntry,
  AiCallEntry,
  AiToolExecutionEntry,
  AiCollectorData,
  AiToolDefinition,
  AiToolCall,
  AiToolOrigin,
  AiApproval,
  AiMessage,
  AiMessagePart,
  AiMessageRole,
  AiCallSettings,
  AiTokenUsage,
  AiProviderPayload,
  AiCaptureLevel,
  AiCaptureField,
  AiCaptureFieldLevels,
  AiCaptureGroup,
  AiCaptureOptions,
  AiCaptureOrigin,
  AiRedactionContext,
  AiRedactionOptions,
  AiSanitizer,
  AiModelPricing,
  AiPricingTable,
  AiPricingSource,
  AiPricingConfig,
} from '@eleven-labs/nest-profiler-ai';

// Price lists — their own subpath:
import { fetchOpenRouterPricing, fetchLiteLLMPricing } from '@eleven-labs/nest-profiler-ai/pricing';
import type {
  OpenRouterPricingOptions,
  LiteLLMPricingOptions,
} from '@eleven-labs/nest-profiler-ai/pricing';

// Harness agents — their own subpath:
import {
  HarnessInstrumentation,
  instrumentHarnessAgentClass,
  HARNESS_OPERATION,
} from '@eleven-labs/nest-profiler-ai/harness';

Drive the options from ConfigService (or any provider) with forRootAsync(), added to the dev-only bundle's imports in place of forRoot(). It resolves option values only — for the enabled flag and when to prefer forRoot, see Enabling and disabling the profiler.

Powered & maintained by

On this page