> ## Documentation Index
> Fetch the complete documentation index at: https://hydroxai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Install and configure the @know-your-ai SDK to monitor, trace, evaluate, and protect your AI applications.

The **@know-your-ai** SDK is a TypeScript toolkit for monitoring, tracing, evaluating, and securing AI model interactions. It follows a modular architecture with five packages that work together or independently.

## Packages

| Package                  | Description                                                         |
| ------------------------ | ------------------------------------------------------------------- |
| `@know-your-ai/node`     | Primary entry point — monitoring & tracing for Node.js applications |
| `@know-your-ai/core`     | Core library (used internally by `node` and `firewall`)             |
| `@know-your-ai/firewall` | Content safety validation via hooks                                 |
| `@know-your-ai/evaluate` | Programmatic evaluation SDK — datasets, evaluations, test runs      |
| `@know-your-ai/cli`      | Command-line interface for running evaluations from the terminal    |

```
@know-your-ai/node    → @know-your-ai/core
@know-your-ai/firewall → @know-your-ai/core
@know-your-ai/cli     → @know-your-ai/evaluate
```

## Requirements

* **Node.js** >= 18
* **TypeScript** (optional but recommended) — all packages ship with `.d.ts` type definitions
* ESM and CommonJS are both supported

## Installation

<Tabs>
  <Tab title="Monitoring + Tracing">
    ```bash theme={null}
    npm install @know-your-ai/node
    ```
  </Tab>

  <Tab title="Firewall">
    ```bash theme={null}
    npm install @know-your-ai/node @know-your-ai/firewall
    ```
  </Tab>

  <Tab title="Evaluation SDK">
    ```bash theme={null}
    npm install @know-your-ai/evaluate
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    npm install -g @know-your-ai/cli
    # or
    curl -fsSL https://knowyourai.hydrox.ai/cli/install.sh | bash
    ```
  </Tab>
</Tabs>

## Quick start

### 1. Get your DSN

Go to **Settings → API Keys** in the [Know Your AI dashboard](https://knowyourai.hydrox.ai) and copy your **DSN**. It looks like:

```
https://kya_xxx:da2-xxx@api.knowyourai.hydrox.ai/your-product-id
```

### 2. Initialize the SDK

```typescript theme={null}
import * as KnowYourAI from '@know-your-ai/node';

KnowYourAI.init({
  dsn: process.env.KNOW_YOUR_AI_DSN!,
  environment: 'production',
  integrations: [
    KnowYourAI.googleGenAIIntegration(),
  ],
});
```

### 3. Instrument your AI client

```typescript theme={null}
import { GoogleGenAI } from '@google/genai';

const genAI = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });
const client = KnowYourAI.instrumentGoogleGenAIClient(genAI);

// Use `client` as normal — all calls are automatically tracked
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Explain quantum computing in one sentence.',
});
console.log(response.text);
```

That's it. Requests, tokens, latency, cost, and errors are now tracked in your monitoring dashboard.

## Configuration reference

All configuration is passed to `KnowYourAI.init()`:

| Option                 | Type                  | Default        | Description                                                |
| ---------------------- | --------------------- | -------------- | ---------------------------------------------------------- |
| `dsn`                  | `string`              | *required*     | DSN from the dashboard                                     |
| `environment`          | `string`              | `'production'` | Environment identifier (e.g. `'staging'`, `'development'`) |
| `debug`                | `boolean`             | `false`        | Enable debug logging                                       |
| `sampleRate`           | `number`              | `1.0`          | Sampling rate (`0.0` – `1.0`)                              |
| `batchSize`            | `number`              | `10`           | Events to batch before sending                             |
| `flushInterval`        | `number`              | `5000`         | Max milliseconds before flushing events                    |
| `traceMode`            | `boolean`             | `true`         | Send complete trace trees (vs individual events)           |
| `recordInputs`         | `boolean`             | `true`         | Capture user input messages                                |
| `recordOutputs`        | `boolean`             | `true`         | Capture AI responses                                       |
| `recordRequestParams`  | `boolean`             | `true`         | Capture temperature, maxTokens, etc.                       |
| `enableDeduplication`  | `boolean`             | `true`         | Deduplicate payload content for traces                     |
| `enableCostEstimation` | `boolean`             | `true`         | Estimate cost per request                                  |
| `release`              | `string`              | —              | Your application version string                            |
| `integrations`         | `Integration[]`       | `[]`           | SDK integrations (e.g. Google GenAI, Firewall)             |
| `onCapture`            | `function`            | —              | Callback invoked for every captured event                  |
| `beforeRequest`        | `BeforeRequestHook[]` | —              | Pre-request hooks                                          |
| `afterResponse`        | `AfterResponseHook[]` | —              | Post-response hooks                                        |

## What's next

<CardGroup cols={2}>
  <Card title="Monitoring" icon="chart-line" href="/sdk/monitoring">
    Track requests, tokens, cost, and latency in production.
  </Card>

  <Card title="Tracing" icon="diagram-project" href="/sdk/tracing">
    Visualize multi-step AI agent interactions as span trees.
  </Card>

  <Card title="Firewall" icon="shield" href="/sdk/firewall">
    Block dangerous inputs and flag risky outputs in real time.
  </Card>

  <Card title="Evaluate" icon="check-double" href="/sdk/evaluate">
    Run security evaluations programmatically.
  </Card>
</CardGroup>