Kairoz AI
Docs
JavaScript/TypeScript SDK

JavaScript/TypeScript SDK

Official Kairoz SDK for JavaScript/TypeScript.

JavaScript/TypeScript SDK

Access the Kairoz API easily and professionally using our official JavaScript/TypeScript SDK. Here you'll find installation guides, configuration, and practical examples.

Installation

npm install kairoz

Quick Start

import { Kairoz } from "kairoz";
// or
const { Kairoz } = require("kairoz");
 
const client = new Kairoz({
  apiKey: "your-api-key", // optional
  baseUrl: "https://api.kairozai.com", // optional
  maxRetries: 2, // optional
});

Configuration

You can configure the SDK using the constructor or environment variables:

  • apiKey: Your Kairoz API Key (KAIROZ_API_KEY)
  • baseUrl: API base URL (optional, defaults to https://api.kairozai.com)
  • maxRetries: Maximum number of retries (optional, defaults to 2)

Example

// All parameters are optional except apiKey
const client = new Kairoz({
  apiKey: "your-api-key",
  baseUrl: "https://api.kairozai.com",
  maxRetries: 3,
});

Or using environment variables:

KAIROZ_API_KEY=your-api-key
KAIROZ_API_URL=https://api.kairozai.com

Usage Guide

Getting a Prompt

const prompt = await client.getPrompt("prompt-name");
const promptByLabel = await client.getPrompt("prompt-name", {
  label: "production",
});
const promptByVersion = await client.getPrompt("prompt-name", { version: "2" });

Note: If the prompt does not exist (404), the SDK throws an error immediately and does not retry the request.

Creating a Prompt

Text Prompt

const textPrompt = await client.createPrompt({
  name: "greeting",
  type: "text",
  prompt: "Hello {{name}}!",
  config: { temperature: 0.7 },
  labels: ["greeting"],
});

Chat Prompt

const chatPrompt = await client.createPrompt({
  name: "chat-assistant",
  type: "chat",
  prompt: [
    { role: "system", content: "You are a {{type}} assistant" },
    { role: "user", content: "Hello {{name}}!" },
    { role: "assistant", content: "How can I help you?" },
  ],
  config: { temperature: 0.8 },
  labels: ["chat", "assistant"],
});

Formatting Prompts

You can replace variables in prompts using the format method, which returns a new Prompt instance with the formatted content.

Text

import { Kairoz } from "kairoz";
// or
const { Kairoz } = require("kairoz");
 
const kairoz = new Kairoz({ apiKey: "your-api-key" });
const prompt = await kairoz.getPrompt("greeting");
 
const formattedPrompt = prompt.format({
  name: "John",
  service: "Kairoz",
});
// formattedPrompt is a new Prompt instance with the formatted content
console.log(formattedPrompt.prompt); // "Hello John! Welcome to Kairoz."

Chat

const kairoz = new Kairoz({ apiKey: "your-api-key" });
const prompt = await kairoz.getPrompt("chat-greeting");
 
const formattedPrompt = prompt.format({
  type: "friendly",
  name: "John",
});
// formattedPrompt is a new Prompt instance with the formatted messages
console.log(formattedPrompt.prompt);
// [
//   { role: 'system', content: 'You are a friendly assistant' },
//   { role: 'user', content: 'Hello John!' },
//   { role: 'assistant', content: 'How can I help you?' }
// ]

Additional Methods

validate()

The validate method ensures that the prompt object is correctly structured and throws an error if any validation fails.

Example:

import { Prompt } from "kairoz";
 
const prompt = new Prompt(
  "example",
  "text",
  "Hello {{name}}!",
  { temperature: 0.7 },
  ["example-label"],
);
 
try {
  prompt.validate();
  console.log("Prompt is valid");
} catch (error) {
  console.error("Validation failed:", error.message);
}

toDict()

The toDict method converts a Prompt object into a plain object that can be sent to the API.

Example:

const prompt = new Prompt(
  "example",
  "text",
  "Hello {{name}}!",
  { temperature: 0.7 },
  ["example-label"],
);
 
const promptData = prompt.toDict();
console.log(promptData);
// Output:
// {
//   name: 'example',
//   type: 'text',
//   messages: [{ role: 'user', content: 'Hello {{name}}!' }],
//   config: { temperature: 0.7 },
//   labels: ['example-label']
// }

fromDict()

Tracing

The tracing module allows you to monitor and log the execution flow of your application, capturing valuable information about the performance and behavior of your code. Here’s how to use it.

Initialization

To start using tracing, you must first initialize the tracker with your API key. This should be done once when your application starts.

import { initializeTracking } from "kairoz";
 
initializeTracking({ apiKey: "your-api-key" });

Basic Usage

Tracing is implemented by starting a trace and then creating generations or spans within it. You must manually end each trace, generation, or span.

  • Trace: Represents the complete execution flow of an operation. Created with startTrace().
  • Generation: Used to log a generation from a language model (LLM). Created with trace.generation().
  • Span: A generic execution block that you can use to monitor any part of your code. Created with trace.span().

Complete Example

import { initializeTracking, startTrace } from "kairoz";
 
// Initialize once
initializeTracking({ apiKey: "your-api-key" });
 
async function handleUserRequest() {
  // Start a trace
  const trace = startTrace("example-trace", {
    userId: "user-123",
    sessionId: "session-abc",
    metadata: { key: "value" },
    tags: ["tag1", "tag2"],
  });
 
  try {
    // Log a generation within the trace
    const generation = trace.generation("example-generation", "gpt-4", {
      input: { prompt: "Hello world" },
      metadata: { provider: "openai" },
    });
 
    // Simulate an LLM call
    const output = "This is a generated response.";
    const usage = { inputTokens: 10, outputTokens: 20 };
 
    // End the generation with the result
    generation.end(output, usage);
 
    // Log a span within the trace
    const span = trace.span("example-span", {
      input: { data: "some data" },
      metadata: { source: "internal" },
    });
 
    // Simulate an operation
    const result = "Processed data";
 
    // End the span with the result
    span.end(result);
 
    // End the trace
    trace.end({ status: "success" });
  } catch (error) {
    // End the trace with an error
    trace.end({ error: error.message });
    console.error("An error occurred:", error);
  }
}
 
handleUserRequest();

Using OpenAI with Provider Fallback

The Kairoz SDK also provides a seamless way to use OpenAI-compatible APIs with automatic fallback to other providers.

Basic Setup

import { KairozOpenAI, Providers } from "kairoz";
// or
const { KairozOpenAI, Providers } = require("kairoz");
 
// Configure with primary and fallback providers
const openai = new KairozOpenAI({
  primary: Providers.OpenAI("your-openai-api-key"),
  fallback: Providers.Anthropic("your-anthropic-api-key"),
  enableLogging: true,
});

Chat Completions with Fallback

async function exampleUsage() {
  try {
    // Chat completions with automatic fallback
    const chatResponse = await openai.chat.completions.create({
      model: "gpt-4",
      model_fallback: "claude-3-5-sonnet-20240620",
      messages: [{ role: "user", content: "Hello, how are you?" }],
    });
    console.log("Chat response:", chatResponse.choices[0].message.content);
  } catch (error) {
    console.error("Error:", error);
  }
}
 
// Run the example
exampleUsage();

Available Providers

The SDK supports multiple providers that can be used as primary or fallback:

  • OpenAI: Providers.OpenAI(apiKey)
  • Anthropic: Providers.Anthropic(apiKey)
  • Groq: Providers.Groq(apiKey)
  • Together.ai: Providers.Together(apiKey)
  • Azure OpenAI: Providers.AzureOpenAI(apiKey, endpoint)
  • LM Studio: Providers.LMStudio(apiKey, baseUrl)

Advanced Configuration Examples

// OpenAI + Groq
const openaiWithGroq = new KairozOpenAI({
  primary: Providers.OpenAI(process.env.OPENAI_API_KEY),
  fallback: Providers.Groq(process.env.GROQ_API_KEY),
  enableLogging: true,
});
 
// OpenAI + Together.ai
const openaiWithTogether = new KairozOpenAI({
  primary: Providers.OpenAI(process.env.OPENAI_API_KEY),
  fallback: Providers.Together(process.env.TOGETHER_API_KEY),
  enableLogging: true,
});
 
// Azure OpenAI + OpenAI
const azureWithOpenAI = new KairozOpenAI({
  primary: Providers.AzureOpenAI(
    process.env.AZURE_API_KEY,
    process.env.AZURE_ENDPOINT,
  ),
  fallback: Providers.OpenAI(process.env.OPENAI_API_KEY),
  enableLogging: true,
});
 
// Local LM Studio + OpenAI
const localWithOpenAI = new KairozOpenAI({
  primary: Providers.LMStudio("dummy-key", "http://localhost:1234/v1"),
  fallback: Providers.OpenAI(process.env.OPENAI_API_KEY),
  enableLogging: true,
});

The fromDict method populates a Prompt object from a plain object.

Example:

const promptData = {
  name: "example",
  type: "text",
  prompt: "Hello {{name}}!",
  config: { temperature: 0.7 },
  labels: ["example-label"],
};
 
const prompt = new Prompt("", "text", "");
prompt.fromDict(promptData);
 
console.log(prompt);
// Output:
// Prompt {
//   name: 'example',
//   type: 'text',
//   prompt: 'Hello {{name}}!',
//   config: { temperature: 0.7 },
//   labels: ['example-label']
// }

Complete Examples

Create and Use a Text Prompt

import { Kairoz, Prompt } from "kairoz";
// or
const { Kairoz, Prompt } = require("kairoz");
 
const client = new Kairoz({ apiKey: "your-api-key" });
 
const prompt = await client.createPrompt({
  name: "custom-greeting",
  type: "text",
  prompt: "Hello {{name}}! Welcome to {{service}}.",
  config: { temperature: 0.7 },
  labels: ["greetings"],
});
 
const savedPrompt = await client.getPrompt("custom-greeting");
const formattedPrompt = savedPrompt.format({
  name: "Mary",
  service: "Kairoz",
});
console.log(formattedPrompt.prompt); // "Hello Mary! Welcome to Kairoz."

Create and Use a Chat Prompt

import { Kairoz, Prompt } from "kairoz";
// or
const { Kairoz, Prompt } = require("kairoz");
 
const client = new Kairoz({ apiKey: "your-api-key" });
 
const prompt = await client.createPrompt({
  name: "chat-assistant",
  type: "chat",
  prompt: [
    { role: "system", content: "You are a {{type}} assistant" },
    { role: "user", content: "Hi! My name is {{name}}" },
    { role: "assistant", content: "How can I help you?" },
  ],
  config: { temperature: 0.8 },
  labels: ["chat", "assistant"],
});
 
const savedPrompt = await client.getPrompt("chat-assistant");
const formattedPrompt = savedPrompt.format({
  type: "friendly",
  name: "Charles",
});
console.log(formattedPrompt.prompt);
// [
//   { role: 'system', content: 'You are a friendly assistant' },
//   { role: 'user', content: 'Hi! My name is Charles' },
//   { role: 'assistant', content: 'How can I help you?' }
// ]

Error Handling

  • If the prompt does not exist (404), the SDK throws an error and does not retry the request.
  • If a text prompt is not a string: "Text prompts must have a string prompt".
  • If a chat prompt is not an array: "Chat prompts must have a list of messages".
  • If a message is missing role or content: "Each message must have 'role' and 'content' fields".
  • If a variable is missing during formatting: "Variable '{name}' not found".

Additional Notes

  • The SDK supports both CommonJS (require) and ES Modules (import).
  • All main functions are asynchronous and return Promises.
  • The SDK validates data before sending to the API and throws descriptive errors if something is wrong.
Python