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()`

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