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

Monitoring + Tracing

npm install @know-your-ai/node

Firewall

npm install @know-your-ai/node @know-your-ai/firewall

Evaluation SDK

npm install @know-your-ai/evaluate

CLI

npm install -g @know-your-ai/cli
# or
curl -fsSL https://knowyourai.hydrox.ai/cli/install.sh | bash

Quick start

1. Get your DSN

Go to Settings → API Keys in the Know Your AI dashboard and copy your DSN. It looks like:

https://kya_xxx:[e-mail]/your-product-id

2. Initialize the SDK

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

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

Monitoring

Track requests, tokens, cost, and latency in production.

Tracing

Visualize multi-step AI agent interactions as span trees.

Firewall

Block dangerous inputs and flag risky outputs in real time.

Evaluate

Run security evaluations programmatically.