Olakai SDK

A TypeScript SDK for tracking AI interactions with simple event-based API. Monitor your AI agents, applications, track usage patterns, and enforce content policies with just a few lines of code.

Why Use Olakai SDK?

• AI Monitoring: Track every AI interaction in your application
• Content Control: Automatically block sensitive or inappropriate content
• Analytics: Get insights into AI usage patterns and performance
• Simple Integration: Works with a simple event-based API - just call olakai()
• Production Ready: Handles errors gracefully, works offline, retries automatically

Installation

npm install @olakai/sdk
# or
yarn add @olakai/sdk
# or
pnpm add @olakai/sdk

Quick Start

1. Initialize the SDK

import { olakaiConfig } from "@olakai/sdk";

// Initialize once in your app
olakaiConfig({
  apiKey: "your-olakai-api-key",
  // endpoint is optional, defaults to https://app.olakai.ai
  debug: false, // Set to true for development
});

2. Track AI Events

import { olakai } from "@olakai/sdk";

// Track any AI interaction
olakai("event", "ai_activity", {
  prompt: "Write a product description for wireless headphones",
  response:
    "Experience crystal-clear sound with our premium wireless headphones...",
  task: "Content Generation",
  userEmail: "[email protected]",
  tokens: 150,
  chatId: "cckej2lc40c0np1s3mcvef5ss", // Groups related interactions
  customDimensions: {
    dim1: "EMEA",
    dim2: "United Kingdom",
    dim3: "Internal Processing",
  },
  customMetrics: {
    metric1: 150,
    metric2: 2.5,
  },
});

That's it! Your AI interactions are now being tracked and monitored.

Real-World Examples

E-commerce AI Assistant

import { olakai } from "@olakai/sdk";

async function generateProductDescription(product: Product) {
  const prompt = `Write a compelling product description for: ${product.name}`;

  // Call your AI service
  const response = await openai.chat.completions.create({
    model: "gpt-4",
    messages: [{ role: "user", content: prompt }],
  });

  const description = response.choices[0].message.content;

  // Track the interaction
  olakai("event", "ai_activity", {
    prompt,
    response: description,
    task: "Communication Strategy",
    subTask: "message crafting",
    tokens: response.usage?.total_tokens || 0,
    chatId: `product-${product.id}`,
    customDimensions: {
      dim1: product.category,
      dim2: product.brand,
      dim3: "gpt-4",
    },
    customMetrics: {
      metric1: product.price,
      metric2: response.usage?.total_tokens || 0,
    },
  });

  return description;
}

Customer Support Chatbot

import { olakai } from "@olakai/sdk";

async function handleCustomerQuery(query: string, customerId: string) {
  const systemPrompt = "You are a helpful customer support agent...";

  const response = await openai.chat.completions.create({
    model: "gpt-3.5-turbo",
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: query },
    ],
  });

  const answer = response.choices[0].message.content;

  // Track with customer context
  olakai("event", "ai_activity", {
    prompt: query,
    response: answer,
    task: "Customer Experience",
    subTask: "user onboarding support",
    tokens: response.usage?.total_tokens || 0,
    chatId: `support-${customerId}`,
    customDimensions: {
      dim1: "customer-support",
      dim2: "gpt-3.5-turbo",
      dim3: "tier-1",
    },
  });

  return answer;
}

API Reference

olakaiConfig(config)

Initialize the SDK with your configuration.

olakaiConfig({
  apiKey: string;        // Required: Your Olakai API key
  endpoint?: string;     // Optional: API endpoint (default: https://app.olakai.ai)
  debug?: boolean;       // Optional: Enable debug logging (default: false)
});

olakai(eventType, eventName, params)

Track AI events with simple event-based API.

olakai("event", "ai_activity", {
  // Required
  prompt: string;         // The AI prompt/input
  response: string;      // The AI response/output

  // Optional - User & Session
  userEmail?: string;        // User email for tracking
  chatId?: string;       // UUID to group related activities

  // Optional - Categorization
  task?: string;         // Task name (e.g., "Content Generation")
  subTask?: string;      // Sub-task name (e.g., "Blog Post")

  // Optional - Metrics
  tokens?: number;       // Token count used
  requestTime?: number;  // Request duration in milliseconds
  shouldScore?: boolean; // Whether to score this activity

  // Optional - Custom Data
  customDimensions?: {  // String dimensions for categorization
    dim1?: string;
    dim2?: string;
    dim3?: string;
    dim4?: string;
    dim5?: string;
    [key: string]: string | undefined;
  };
  customMetrics?: {     // Numeric metrics for analysis
    metric1?: number;
    metric2?: number;
    metric3?: number;
    metric4?: number;
    metric5?: number;
    [key: string]: number | undefined;
  };
});

olakaiReport(prompt, response, options)

Most common: direct reporting without function wrapping.

await olakaiReport("Generate a blog post", "Here's your blog post content...", {
  task: "Content Generation",
  userEmail: "[email protected]",
  tokens: 150,
});

olakaiMonitor(fn, options)

Wrap functions for automatic tracking.

const monitoredFunction = olakaiMonitor(
  async (input: string) => {
    // Your AI logic here
    return await aiModel.generate(input);
  },
  {
    task: "Content Generation",
    subTask: "Blog Post",
    userEmail: "[email protected]",
  },
);

Error Handling

Content Blocking

When Olakai's control system blocks content, an OlakaiBlockedError is thrown:

import { OlakaiBlockedError } from "@olakai/sdk";

try {
  const result = await monitoredFunction("sensitive content");
} catch (error) {
  if (error instanceof OlakaiBlockedError) {
    console.error("Content blocked:", error.details);

    // Handle different blocking reasons
    if (error.details.detectedSensitivity.includes("PII")) {
      // Handle personally identifiable information
    }
    if (!error.details.isAllowedPersona) {
      // Handle unauthorized user
    }
  }
}

Error Details

The OlakaiBlockedError contains:

{
  message: string;
  details: {
    detectedSensitivity: string[];  // ["PII", "PHI", "CODE", "SECRET"]
    isAllowedPersona: boolean;      // User authorization status
  };
}

Best Practices

1. Use Meaningful Task Names

// ✅ Good - Descriptive and hierarchical
olakai("event", "ai_activity", {
  prompt,
  response,
  task: "Customer Support",
  subTask: "Ticket Resolution",
  // ...
});

// ❌ Avoid - Too generic
olakai("event", "ai_activity", {
  prompt,
  response,
  task: "AI",
  // ...
});

2. Group Related Interactions

// Use consistent chatId for related interactions
const sessionId = "chat-" + Date.now();

olakai("event", "ai_activity", {
  prompt: "What's the weather like?",
  response: "I can't check real-time weather...",
  chatId: sessionId,
  // ...
});

olakai("event", "ai_activity", {
  prompt: "What about tomorrow?",
  response: "I still can't check weather...",
  chatId: sessionId, // Same session
  // ...
});

3. Use Custom Dimensions for Analytics

olakai("event", "ai_activity", {
  prompt,
  response,
  customDimensions: {
    dim1: "e-commerce", // Business domain
    dim2: "product-description", // Use case
    dim3: "gpt-4", // AI model
    dim4: "premium-tier", // User tier
  },
  customMetrics: {
    metric1: productPrice, // Product value
    metric2: responseTime, // Performance
    metric3: tokenCount, // Cost
  },
});

4. Handle Errors Gracefully

// Always wrap in try-catch for production
try {
  olakai("event", "ai_activity", params);
} catch (error) {
  // Log but don't break your app
  console.warn("Failed to track AI event:", error);
}

Troubleshooting

Common Issues

"Events not being tracked"

• Ensure olakaiConfig() was called first
• Check your API key and endpoint URL
• Enable debug mode to see detailed logs

"TypeScript errors"

• Make sure you're using TypeScript 4.0+
• The SDK uses automatic type inference

"Performance concerns"

• Tracking is asynchronous and won't block your app
• Use olakai() for fire-and-forget tracking
• Use olakaiReport() only when you need to await completion

Debug Mode

Enable debug logging to troubleshoot issues:

olakaiConfig({
  apiKey: "your-key",
  debug: true, // Shows detailed logs
});

Support

• Full Documentation
• Support Email
• Report Issues

License

MIT © Olakai