> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-mintlify-java-core-statsig-options-migrati.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Node AI SDK

> Statsig's Node SDK for AI Application Configuration & Telemetry

<Callout icon="github">
  <a href="https://github.com/statsig-io/statsig-ai-node" target="_blank" rel="noreferrer">Node AI SDK on Github</a>,
  <a href="https://www.npmjs.com/package/@statsig/statsig-ai" target="_blank" rel="noreferrer">NPM Package</a>
</Callout>

<Warning>
  This SDK is available in an open beta, and its methods may change. We encourage you to reach out on [Slack](https://statsig.com/slack) for help getting setup, and so we can communicate changes.
</Warning>

## Overview

The Statsig Node AI SDK lets you manage your prompts, online and offline evals, and debug your LLM applications in production. It depends upon the [Statsig Node Server SDK](/server-core/node-core), but provides convenient hooks for AI-specific functionality.

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```js npm theme={null}
      npm install @statsig/statsig-ai
      ```

      ```js pnpm theme={null}
      pnpm add @statsig/statsig-ai
      ```

      ```js yarn theme={null}
      yarn add @statsig/statsig-ai
      ```
    </CodeGroup>

    If you have unique setup needs like a frozen lockfile, take a look at the [Node Server SDK docs](/server-core/node-core#installation) - the AI SDK will install Node Server if you don't already have it.
  </Step>

  <Step title="Initialize the SDK">
    If you already have a Statsig instance, you can pass it into the SDK. Otherwise, we'll create an instance for you internally.

    <Tabs>
      <Tab title="Don't use Statsig">
        Initialize the AI SDK with a Server Secret Key from the Statsig console.

        <Warning>
          Server Secret Keys should always be kept private. If you expose one, you can
          disable and recreate it in the Statsig console.
        </Warning>

        ```js theme={null}
        import { StatsigAI } from '@statsig/statsig-ai';

        const statsigAI = new StatsigAI({'YOUR_SERVER_SECRET_KEY'});
        await statsigAI.initialize();
        ```

        <Accordion title="Initializing With Options">
          Optionally, you can configure [StatsigOptions](/server-core/node-core#statsig-options) and [StatsigAI](#ai-options) options:

          ```js theme={null}
          import { StatsigAI, StatsigAIOptions } from '@statsig/statsig-ai';
          import { StatsigOptions } from '@statsig/statsig-server-core-node';

          // if you want to configure any statsig options, this is optional:
          const statsigOptions: StatsigOptions = {
            environment: 'production',
          };

          // if you would like to configure any statsigAI options, this is optional:
          const statsigAIOptions: StatsigAIOptions = {
            enableDefaultOtel: true,
          };
          const statsigAI = new StatsigAI({'YOUR_SERVER_SECRET_KEY', statsigOptions}, statsigAIOptions);
          await statsigAI.initialize();

          // if you would like to use any statsig methods, you can access the statsig instance from the statsigAI instance:
          const gate = statsigAI.getStatsig().checkGate(statsigUser, 'my_gate');
          ```
        </Accordion>
      </Tab>

      <Tab title="Already have Statsig instance">
        After installation, initialize the SDK with a [Server Secret Key from the Statsig console](https://console.statsig.com/api_keys).

        <Warning>
          Server Secret Keys should always be kept private. If you expose one, you can
          disable and recreate it in the Statsig console.
        </Warning>

        If you initialize this way, the AI SDK won’t handle initialization, flushing, or shutdown.

        ```js theme={null}
        import { Statsig } from '@statsig/statsig-server-core-node';
        import { StatsigAI } from '@statsig/statsig-ai';

        const statsig = new Statsig('YOUR_SERVER_SECRET_KEY', { environment: 'production' });
        await statsig.initialize();

        const statsigAI = new StatsigAI({'YOUR_SERVER_SECRET_KEY', statsig}, statsigAIOptions);
        await statsigAI.initialize();
        ```

        <Accordion title="Initializing With Options">
          Optionally, you can configure [StatsigOptions](/server-core/node-core#statsig-options) and [StatsigAI](#ai-options) options:

          ```js theme={null}
          import { Statsig } from '@statsig/statsig-server-core-node';
          import { StatsigAI, StatsigAIOptions } from '@statsig/statsig-ai';

          const statsig = new Statsig('YOUR_SERVER_SECRET_KEY', {
            environment: 'production',
          });
          await statsig.initialize();

          // if you would like to configure any statsigAI options, this is optional:
          const statsigAIOptions: StatsigAIOptions = {
            enableDefaultOtel: true,
          };
          const statsigAI = new StatsigAI({'YOUR_SERVER_SECRET_KEY', statsig}, statsigAIOptions);
          await statsigAI.initialize();
          ```
        </Accordion>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Using the SDK

### Getting a Prompt

Statsig can act as the control plane for your LLM prompts, allowing you to version and change them without deploying code. For more information, see the [Prompts](/ai-evals/prompts) documentation.

```js theme={null}
import { StatsigUser } from '@statsig/statsig-ai';
// Create a user object
const user = new StatsigUser({ userID: 'a-user' });

// Get the prompt
const myPrompt = statsigAI.getPrompt(user, 'my_prompt');

// Use the live version of the prompt
const liveVersion = myPrompt.getLive();

// Get the candidate versions of the prompt
const candidateVersions = myPrompt.getCandidates();

// Use the live version of the prompt in a completion
const response = await openai.chat.completions.create({
  model: liveVersion.getModel({ fallback: 'gpt-4' }), // optional fallback
  temperature: liveVersion.getTemperature(),
  max_tokens: liveVersion.getMaxTokens(),
  messages: [{ role: 'user', content: 'Your prompt here' }],
});
```

### Logging Eval Results

When running an [online eval](/ai-evals/online-evals), you can log results back to Statsig for analysis.
Provide a score between 0 and 1, along with the grader name and any useful metadata (e.g., session IDs).
Currently, you must provide the grader manually — future releases will support automated grading options.

```js theme={null}
import { StatsigUser } from '@statsig/statsig-ai';

const livePromptVersion = statsigAI.getPrompt(user, 'my_prompt').getLive();
// Create a user object
const user = new StatsigUser({ userID: 'a-user' });

// Log the results of the eval
statsigAI.logEvalGrade(user, livePromptVersion, 0.5, 'my_grader', {
  session_id: '1234567890',
});

// flush otel events or wait for the configured otel exporter flush interval
await statsigAI.flush();
```

### OpenTelemetry (OTEL)

The AI SDK works with OpenTelemetry for sending telemetry to Statsig.
You can either turn on the default OTel integration in the `StatsigAIOptions`, or set up your own OTel to send traces to Statsig.
More advanced OTel configuration and exporter support are on the way.

```js theme={null}
import { StatsigAI, StatsigAIOptions } from '@statsig/statsig-ai';
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { NodeSDK } from '@opentelemetry/sdk-node';


const statsigAIOptions: StatsigAIOptions = {
  enableDefaultOtel: true,
};
const statsigAI = new StatsigAI({'YOUR_SERVER_SECRET_KEY'}, statsigAIOptions);
await statsigAI.initialize();

// flush otel events
await statsigAI.flush();

// or if you are using your own otel instance, you can setup the export to statsig with an OTLP exporter.
const statsigExporter = new OTLPTraceExporter({
  url: 'https://api.statsig.com/otlp/v1/traces',
  headers: {
    'statsig-api-key': 'YOUR_SERVER_SECRET_KEY',
  },
});

const otel = new NodeSDK({
    serviceName: 'my-service',
    spanProcessors: [new BatchSpanProcessor(statsigExporter)],
});
otel.start();

```

### Wrapping OpenAI

The Statsig OpenAI Wrapper automatically adds tracing and log events to your OpenAI SDK usage, giving you in-console visibility with minimal setup.

```js theme={null}
import { wrapOpenAI, StatsigAI } from '@statsig/statsig-ai';
import { OpenAI } from 'openai';

// if you have your own otel, you do not need an statsigAI instance here.
// But if you want to use the default Otel on statsigAI, you need to initialize the SDK.
statsigAI = new StatsigAI({"YOUR_SERVER_SECRET_KEY"});
await statsigAI.initialize();

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

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello, world!" }],
});
```

### AI Options

Options for configuring the AI SDK. Pass these into the `StatsigAI` constructor. See [Initializing with Options](#initializing-with-options).

#### Configuration Properties

<ResponseField name="enableDefaultOtel" type="boolean">
  Enables Statsig's default OpenTelemetry setup for automatic tracing and instrumentation. Defaults to false.
</ResponseField>

<ResponseField name="statsigTracingConfig" type="StatsigTracingConfig">
  Configuration object for tracing and instrumentation settings.
</ResponseField>

<ResponseField name="serviceName" type="string">
  Name of the service for tracing identification. Used in OpenTelemetry spans and traces.
</ResponseField>

<ResponseField name="enableAutoInstrumentation" type="boolean">
  Enables automatic instrumentation of common libraries and frameworks for tracing. Defaults to false.
</ResponseField>

```typescript theme={null}
export interface StatsigTracingConfig {
  serviceName?: string;
  enableAutoInstrumentation?: boolean;
}

export interface StatsigAIOptions {
  enableDefaultOtel?: boolean;
  statsigTracingConfig?: StatsigTracingConfig;
}
```

## Using other SDK methods

Whether you passed in a Statsig instance or not, you can access the Statsig instance from the statsigAI instance, and use its many methods:

```javascript theme={null}
// Check a gate value
const gate = statsigAI.getStatsig().checkGate(statsigUser, 'my_gate');

// Log an event
statsigAI.getStatsig().logEvent(statsigUser, 'my_event', { value: 1 });
```

Refer to the [Statsig Node SDK](/server-core/node-core) docs for more information on how to use the Core Statsig SDK methods, plus information on advanced setup + singleton usage.