AI.tools()

Complete API reference for the KoAI client

ValidationResult

interface ValidationResult {
  valid: boolean;
  errors: string[];
  tokenCount: number;
  estimatedCost: number;
}

Example

const tokenCount = await ai.tokenCount('Hello, world!');
console.log(`Token count: ${tokenCount}`);

const validation = ai.validateMessage('Very long message...');
if (!validation.valid) {
  console.log('Validation errors:', validation.errors);
}

Event Handling

on()

Listen for events.

on(event: string, handler: Function): void

off()

Remove event listener.

off(event: string, handler: Function): void

Events

EventDescriptionHandler Signature
responseNew response received(response: ChatResponse) => void
errorError occurred(error: Error) => void
tokenUsageToken usage update(usage: TokenUsage) => void
toolCallTool was called(toolCall: ToolCall) => void

Example

ai.on('response', (response) => {
  console.log(`Received response: ${response.content.length} chars`);
});

ai.on('error', (error) => {
  console.error('AI Error:', error.message);
});

ai.on('tokenUsage', (usage) => {
  console.log(`Tokens used: ${usage.totalTokens}`);
});

Error Handling

KoAIError

Base error class for all KoAI errors.

class KoAIError extends Error {
  code: string;
  statusCode?: number;
  retryable: boolean;
  metadata?: Record<string, any>;
}

Error Codes

CodeDescriptionRetryable
INVALID_API_KEYAPI key is invalidNo
RATE_LIMIT_EXCEEDEDRate limit exceededYes
CONTEXT_LENGTH_EXCEEDEDMessage too longNo
MODEL_NOT_FOUNDModel not availableNo
NETWORK_ERRORNetwork connectivity issueYes
TIMEOUTRequest timed outYes

Example

try {
  const response = await ai.chat('Hello');
} catch (error) {
  if (error instanceof KoAIError) {
    console.log(`Error code: ${error.code}`);
    console.log(`Retryable: ${error.retryable}`);
    
    if (error.retryable) {
      // Implement retry logic
      await new Promise(resolve => setTimeout(resolve, 1000));
      // Retry the request
    }
  }
}

Advanced Features

Custom Providers

Register custom AI providers.

interface CustomProvider {
  name: string;
  endpoint: string;
  headers?: Record<string, string>;
  transform?: {
    request: (data: any) => any;
    response: (data: any) => ChatResponse;
  };
}

ai.registerProvider(customProvider);

Middleware

Add middleware for request/response processing.

ai.use(async (context, next) => {
  console.log('Before request:', context.message);
  const response = await next();
  console.log('After response:', response.content);
  return response;
});

Debugging

Enable debug mode for detailed logging.

const ai = new KoAI({
  apiKey: process.env.OPENAI_API_KEY,
  debug: true,
  logLevel: 'verbose'
});