### Install AI-Suite

Source: https://github.com/cubos/ai-suite/blob/main/doc/getting-started.md

Install the package using npm, yarn, or pnpm.

```bash
# Using npm
npm install @cubos/ai-suite

# Using yarn
yarn add @cubos/ai-suite

# Using pnpm
pnpm add @cubos/ai-suite
```

--------------------------------

### Install AI-Suite

Source: https://github.com/cubos/ai-suite/blob/main/README.md

Use your preferred package manager to add the library to your project.

```bash
npm install @cubos/ai-suite
# or
pnpm add @cubos/ai-suite
# or
yarn add @cubos/ai-suite
```

--------------------------------

### Install AI-Suite package

Source: https://github.com/cubos/ai-suite/blob/main/doc/index.md

Install the package via npm to begin using the library.

```bash
npm install @cubos/ai-suite
```

--------------------------------

### Initialize and use AI-Suite

Source: https://github.com/cubos/ai-suite/blob/main/doc/index.md

Basic setup and chat completion request using the AISuite client.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'Hello!' }],
  { responseFormat: 'text' }
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### List, Retrieve, and Delete Files

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-file-upload.md

Examples for managing uploaded files in AI-Suite, including listing with pagination, retrieving metadata by ID, and deleting files.

```typescript
// List files (pagination optional)
const listResult = await aiSuite.file.list('gemini', { limit: 20 });
if (listResult.success) {
  console.log('Files:');
  for (const f of listResult.content) {
    console.log(f.id, f.filename, f.bytes, f.created_at);
  }
} else {
  console.error('List error:', listResult.error);
}
```

```typescript
// Retrieve file metadata by id
const retrieveResult = await aiSuite.file.retrieve('gemini', 'file-id-123', {});
if (retrieveResult.success) {
  console.log('File metadata:', retrieveResult.content);
} else {
  console.error('Retrieve error:', retrieveResult.error);
}
```

```typescript
// Delete file by id
const deleteResult = await aiSuite.file.delete('gemini', 'file-id-123', {});
if (deleteResult.success) {
  console.log('Deleted file:', deleteResult.content.id);
} else {
  console.error('Delete error:', deleteResult.error);
}
```

--------------------------------

### Basic Text Completion Example

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Demonstrates how to create a chat completion request for a text response. Ensure the response format is set to 'text'.

```typescript
const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'Hello!' }],
  {
    responseFormat: 'text',
    temperature: 0.7
  }
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### Supported Custom LLM Models

Source: https://context7.com/cubos/ai-suite/llms.txt

Provides examples for using custom LLM models with AI-Suite.

```typescript
// Custom LLM (any model name from your endpoint)
'custom-llm/llama3.2'
'custom-llm/mistral-7b'
```

--------------------------------

### Create Chat Completion with Google Gemini

Source: https://github.com/cubos/ai-suite/blob/main/doc/providers.md

Initiate a chat completion with a Google Gemini model. This example demonstrates configuring a 'thinking budget' for extended reasoning specific to Gemini 2.5 models.

```typescript
const response = await aiSuite.createChatCompletion(
  'gemini/gemini-2.5-pro',
  [{ role: 'user', content: 'Hello, world!' }],
  {
    thinking: {
      budget: 256,      // Thinking budget (only for gemini-2.5-pro)
      output: true      // Include thinking in output
    }
  }
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### JSON Schema Generation with Zod and OpenAI

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Generate structured recipe data using a Zod schema with the OpenAI API. Requires OPENAI_API_KEY. Ensure Zod is installed (`npm install zod`).

```typescript
import { AISuite } from '@cubos/ai-suite';
import { z } from 'zod';
import dotenv from 'dotenv';

dotenv.config();

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

// Define schema
const RecipeSchema = z.object({
  name: z.string(),
  description: z.string(),
  ingredients: z.array(z.object({
    name: z.string(),
    amount: z.string()
  })),
  steps: z.array(z.string()),
  prepTime: z.number(),
  servings: z.number()
});

async function generateRecipe() {
  const response = await aiSuite.createChatCompletion(
    'openai/gpt-4o',
    [{ role: 'user', content: 'Generate a simple pasta recipe' }],
    {
      responseFormat: 'json_schema',
      zodSchema: RecipeSchema
    }
  );

  if (response.success) {
    const recipe = response.content_object;
    console.log(`Recipe: ${recipe.name}`);
    console.log(`Description: ${recipe.description}`);
    console.log(`Prep Time: ${recipe.prepTime} minutes`);
    console.log(`Servings: ${recipe.servings}`);
    console.log('\nIngredients:');
    recipe.ingredients.forEach(ing => {
      console.log(`- ${ing.amount} ${ing.name}`);
    });
    console.log('\nSteps:');
    recipe.steps.forEach((step, i) => {
      console.log(`${i + 1}. ${step}`);
    });
  }
}

generateRecipe().catch(console.error);
```

--------------------------------

### Create Chat Completion with Grok

Source: https://github.com/cubos/ai-suite/blob/main/doc/providers.md

Send a chat completion request to a Grok model from xAI. This example shows how to configure 'reasoning effort' for extended reasoning.

```typescript
const response = await aiSuite.createChatCompletion(
  'grok/grok-3',
  [{ role: 'user', content: 'Explain quantum entanglement.' }],
  {
    reasoning: {
      effort: 'high'  // Use extended reasoning
    }
  }
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### JSON Schema Response Example

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Shows how to request a chat completion with a JSON schema response. Includes Zod schema definition and validation. The parsed, typed object is available in `response.content_object`.

```typescript
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email()
});

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'Generate a sample user profile' }],
  {
    responseFormat: 'json_schema',
    zodSchema: schema
  }
);

if (response.success) {
  console.log(response.content_object);  // Parsed, typed object
}
```

--------------------------------

### Initialize and Use AI-Suite

Source: https://github.com/cubos/ai-suite/blob/main/README.md

Configure the client with API keys and execute a chat completion request.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY,
  anthropicKey: process.env.ANTHROPIC_API_KEY,
  geminiKey: process.env.GEMINI_API_KEY,
  deepseekKey: process.env.DEEPSEEK_API_KEY,
  grokKey: process.env.GROK_API_KEY,
});

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'Hello, world!' }],
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### AISuite Constructor

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Initializes the AISuite instance with provider API keys and optional configuration hooks.

```APIDOC
## Constructor

### Description
Initializes the main AISuite class with necessary API keys for supported providers and optional configuration hooks.

### Parameters
- **keys** (object) - Required - API keys and configuration for various providers:
  - **openaiKey** (string) - Optional
  - **anthropicKey** (string) - Optional
  - **geminiKey** (string) - Optional
  - **deepseekKey** (string) - Optional
  - **grokKey** (string) - Optional
  - **customURL** (string) - Optional - Base URL for custom OpenAI-compatible endpoints
  - **customLLMKey** (string) - Optional - API key for custom endpoints
- **options** (object) - Optional - Additional configuration:
  - **hooks** (object) - Optional - Custom request/response interceptors
  - **langFuse** (Langfuse) - Optional - Langfuse instance for tracking
```

--------------------------------

### Define Message Roles

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Structure conversations using developer, user, assistant, and tool roles to guide model behavior.

```typescript
const messages = [
  {
    role: 'developer',  // System/developer instructions
    content: 'You are a helpful assistant specialized in TypeScript'
  },
  {
    role: 'user',
    content: 'How do I define an interface?'
  },
  {
    role: 'assistant',
    content: 'You can define an interface like this: interface MyInterface { ... }'
  },
  {
    role: 'user',
    content: 'Can you show me an example?'
  }
];

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  messages,
  { responseFormat: 'text' }
);
```

--------------------------------

### Initialize AISuite with API Keys

Source: https://context7.com/cubos/ai-suite/llms.txt

Initialize the AISuite with API keys for various AI providers. Supports custom OpenAI-compatible endpoints.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY,
  anthropicKey: process.env.ANTHROPIC_API_KEY,
  geminiKey: process.env.GEMINI_API_KEY,
  deepseekKey: process.env.DEEPSEEK_API_KEY,
  grokKey: process.env.GROK_API_KEY,
  // Optional: for custom OpenAI-compatible endpoints (Ollama, vLLM, LM Studio)
  customURL: process.env.CUSTOM_LLM_URL,
  customLLMKey: process.env.CUSTOM_LLM_KEY
});
```

--------------------------------

### File Upload and Batch Processing with AI-Suite

Source: https://context7.com/cubos/ai-suite/llms.txt

Demonstrates uploading a JSONL file for batch processing, using the uploaded file, and listing/deleting files. Includes retry logic for file creation.

```typescript
import { AISuite } from '@cubos/ai-suite';
import { readFileSync } from 'fs';

const aiSuite = new AISuite({
  geminiKey: process.env.GEMINI_API_KEY
});

// Upload JSONL file
const jsonl = readFileSync('./data.jsonl');
const file = new File([jsonl], 'data.jsonl', { type: 'text/jsonl' });

const uploadResult = await aiSuite.file.create('gemini', file, {
  retry: { attempts: 3, delay: (attempt) => attempt * 1000 }
});

if (uploadResult.success) {
  const fileId = uploadResult.content.id;

  // Use uploaded file for batch
  const batchResult = await aiSuite.batch.create(
    'gemini/gemini-2.0-flash',
    'chat/completions',
    { inputFileId: fileId },
    { temperature: 0.5 }
  );
}

// List uploaded files
const listResult = await aiSuite.file.list('gemini', { limit: 20 });
if (listResult.success) {
  for (const f of listResult.content) {
    console.log(f.id, f.filename, f.bytes);
  }
}

// Delete file
const deleteResult = await aiSuite.file.delete('gemini', 'file-id-123', {});
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/cubos/ai-suite/blob/main/doc/getting-started.md

Define API keys for supported providers in a .env file.

```bash
# .env file
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
DEEPSEEK_API_KEY=your_deepseek_key
GROK_API_KEY=your_grok_key
# For custom LLM providers (OpenAI-compatible APIs)
CUSTOM_LLM_URL=https://your-custom-endpoint.com/v1
CUSTOM_LLM_KEY=your_custom_key  # Optional, some endpoints don't require auth
```

--------------------------------

### Initialize AISuite Class

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Constructor for the main AISuite class, accepting API keys for various providers and optional hooks or Langfuse integration.

```typescript
constructor(
  keys: {
    openaiKey?: string;
    anthropicKey?: string;
    geminiKey?: string;
    deepseekKey?: string;
    grokKey?: string;
    customURL?: string;
    customLLMKey?: string;
  },
  options?: {
    hooks?: {
      handleRequest?: (req: unknown) => Promise<void>;
      handleResponse?: (req: unknown, res: unknown, metadata: Record<string, unknown>) => Promise<void>;
      failOnError?: boolean;
    };
    langFuse?: Langfuse;
  }
)
```

--------------------------------

### Initialize AISuite

Source: https://github.com/cubos/ai-suite/blob/main/doc/getting-started.md

Initialize the AISuite instance with API keys loaded from environment variables.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// Initialize AISuite with your API keys
const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY,
  anthropicKey: process.env.ANTHROPIC_API_KEY,
  geminiKey: process.env.GEMINI_API_KEY,
  deepseekKey: process.env.DEEPSEEK_API_KEY,
  grokKey: process.env.GROK_API_KEY,
  // Optional: for custom LLM providers
  customURL: process.env.CUSTOM_LLM_URL,
  customLLMKey: process.env.CUSTOM_LLM_KEY
});
```

--------------------------------

### Basic Q&A with OpenAI

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Perform a simple question-and-answer task using the OpenAI API. Ensure your OPENAI_API_KEY is set in your environment variables.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';

dotenv.config();

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

async function main() {
  const response = await aiSuite.createChatCompletion(
    'openai/gpt-4o',
    [{ role: 'user', content: 'What is the capital of France?' }],
    { responseFormat: 'text' }
  );

  if (response.success) {
    console.log(`Answer: ${response.content}`);
    console.log(`Tokens used: ${response.usage?.total_tokens}`);
  } else {
    console.error(`Error: ${response.error}`);
  }
}

main().catch(console.error);
```

--------------------------------

### AI Function Calling with OpenAI

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Demonstrates how to enable an AI assistant to call external functions, like fetching weather data, by defining tools and handling the AI's tool calls. Requires an OpenAI API key.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';

dotenv.config();

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

// Mock weather function
function getWeather(location: string): string {
  // In real app, call actual weather API
  return `The weather in ${location} is sunny, 22°C`;
}

async function weatherAssistant() {
  const tools = [{
    type: 'function' as const,
    function: {
      name: 'get_weather',
      description: 'Get the current weather for a location',
      parameters: {
        type: 'object' as const,
        properties: {
          location: {
            type: 'string' as const,
            description: 'The city name'
          }
        },
        required: ['location'],
        additionalProperties: false
      },
      additionalProperties: false,
      strict: true
    }
  }];

  const response = await aiSuite.createChatCompletion(
    'openai/gpt-4o',
    [{ role: 'user', content: 'What is the weather in Tokyo?' }],
    {
      responseFormat: 'text',
      tools
    }
  );

  if (response.success && response.tools) {
    // Execute the function
    for (const tool of response.tools) {
      if (tool.name === 'get_weather') {
        const location = tool.content.location as string;
        const weatherData = getWeather(location);
        console.log(weatherData);

        // Continue conversation with function result
        const followUp = await aiSuite.createChatCompletion(
          'openai/gpt-4o',
          [
            { role: 'user', content: 'What is the weather in Tokyo?' },
            { role: 'assistant', content: response.content || '' },
            { role: 'tool', content: weatherData, name: 'get_weather' }
          ],
          { responseFormat: 'text' }
        );

        if (followUp.success) {
          console.log('Assistant:', followUp.content);
        }
      }
    }
  }
}

weatherAssistant().catch(console.error);
```

--------------------------------

### Configure Thinking Mode for Gemini 2.5

Source: https://context7.com/cubos/ai-suite/llms.txt

Set a token budget for model analysis and optionally include the thinking process in the output.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  geminiKey: process.env.GEMINI_API_KEY
});

const response = await aiSuite.createChatCompletion(
  'gemini/gemini-2.5-pro',
  [{
    role: 'user',
    content: 'Analyze the ethical implications of AI in healthcare'
  }],
  {
    responseFormat: 'text',
    thinking: {
      budget: 1024,    // Token budget for thinking (0-16384)
      output: true     // Include thinking process in output
    }
  }
);

if (response.success) {
  console.log('Analysis:', response.content);
  console.log('Thinking tokens used:', response.usage?.thoughts_tokens);
  console.log('Total tokens:', response.usage?.total_tokens);
}
```

--------------------------------

### Create File in Node.js

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-file-upload.md

Reads a local .jsonl file and uploads it to AI-Suite. Ensure your Node.js adapter supports Buffer or File objects.

```typescript
import { readFileSync } from 'fs';

const jsonl = readFileSync('./data.jsonl');

const file = new File([jsonl], 'data.jsonl', { type: 'text/jsonl' });

const response = await aiSuite.file.create(
  'gemini',
  file
  {
    retry: {
      attempts: 3,
      delay: (attempt) => attempt * 1000, // Exponential backoff: 1s, 2s, 3s
    },
  }
);
```

--------------------------------

### Custom Provider Implementation Skeleton

Source: https://github.com/cubos/ai-suite/blob/main/doc/providers.md

Use this skeleton to create a new provider. Implement the constructor, _createChatCompletion, and handleError methods according to your provider's logic. Ensure the CustomModels type includes all models supported by your provider.

```typescript
import { ProviderBase, ChatOptions } from './_base';
import { MessageModel, SuccessChatCompletion, ErrorChatCompletion } from '../types/chat';

export type CustomModels = 'model-1' | 'model-2';

export class CustomProvider extends ProviderBase {
  constructor(apiKey: string, model: string, hooks?: any) {
    super();
    // Initialize your provider client
  }

  async _createChatCompletion(
    messages: MessageModel[],
    options: ChatOptions
  ): Promise<SuccessChatCompletion> {
    // Implement custom provider logic here
    // Return SuccessChatCompletion object
  }

  handleError(error: Error): Pick<ErrorChatCompletion, 'error' | 'raw' | 'tag'> {
    // Implement error handling
    return {
      error: error.message,
      raw: error,
      tag: 'Unknown'
    };
  }
}
```

--------------------------------

### Configure Custom LLM Providers

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Connect to any OpenAI-compatible API by specifying a customURL and optional authentication key.

```typescript
// Example: Using Ollama
const aiSuite = new AISuite({
  customURL: 'http://localhost:11434/v1',
  customLLMKey: 'not-needed'  // Ollama doesn't require auth
});

const response = await aiSuite.createChatCompletion(
  'custom-llm/llama3.2',
  [{ role: 'user', content: 'Hello!' }],
  {
    responseFormat: 'text',
    temperature: 0.7
  }
);

// Example: Using vLLM
const vllmSuite = new AISuite({
  customURL: 'http://your-vllm-server:8000/v1',
  customLLMKey: 'optional-key'
});

// Example: Using LM Studio
const lmStudioSuite = new AISuite({
  customURL: 'http://localhost:1234/v1',
});
```

--------------------------------

### Initialize AISuite with Custom LLM Endpoint

Source: https://github.com/cubos/ai-suite/blob/main/doc/providers.md

Configure AI-Suite to use a custom OpenAI-compatible API endpoint, such as a self-hosted LLM. Provide the custom URL and an optional API key if required.

```typescript
const aiSuite = new AISuite({
  customURL: 'http://localhost:11434/v1',  // Example: Ollama endpoint
  customLLMKey: 'optional-api-key'         // Some endpoints don't need auth
});

const response = await aiSuite.createChatCompletion(
  'custom-llm/llama3.2',  // Model name from your custom endpoint
  [{ role: 'user', content: 'Hello, world!' }]
);

if (response.success) {
  console.log(response.content);
}
```

--------------------------------

### Configure Reasoning Models

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Utilizes extended reasoning capabilities for models like OpenAI o1/o3 or Grok by setting the reasoning effort level.

```typescript
const response = await aiSuite.createChatCompletion(
  'openai/o1',
  [{ role: 'user', content: 'Solve this complex problem: ...' }],
  {
    responseFormat: 'text',
    reasoning: {
      effort: 'high'  // 'low' | 'medium' | 'high'
    }
  }
);

if (response.success) {
  console.log('Response:', response.content);
  console.log('Reasoning tokens used:', response.usage?.reasoning_tokens);
  console.log('Total tokens:', response.usage?.total_tokens);
}
```

--------------------------------

### Create Batch using Input File ID

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-batch.md

Instead of an inline batch array, supply the ID of a file already uploaded via `aiSuite.file.create`. This is supported for OpenAI and Gemini.

```typescript
const result = await aiSuite.batch.create(
  'gemini/gemini-2.0-flash',
  'chat/completions',
  {
    inputFileId: 'files/abc123',
  },
  {
    temperature: 0.5,
  },
);
```

--------------------------------

### Create and Manage Batch Chat Completions

Source: https://context7.com/cubos/ai-suite/llms.txt

Initiate asynchronous batch jobs for processing multiple chat completion requests. The code demonstrates creating a batch, polling for its completion status, and retrieving the output file ID.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

// Create batch job
const createResult = await aiSuite.batch.create(
  'openai/gpt-4o-mini',
  'chat/completions',
  {
    batch: [
      {
        customId: 'req-1',
        params: {
          mensagens: [{ role: 'user', content: 'What is the capital of France?' }]
        }
      },
      {
        customId: 'req-2',
        params: {
          mensagens: [{ role: 'user', content: 'What is 2 + 2?' }]
        }
      }
    ]
  },
  { temperature: 0.7, maxOutputTokens: 512 }
);

if (createResult.success) {
  const batchId = createResult.content.id;
  console.log('Batch created:', batchId);

  // Poll until complete
  let batch;
  do {
    const result = await aiSuite.batch.retrieve('openai/gpt-4o-mini', batchId, {});
    if (!result.success) break;

    batch = result.content;
    console.log('Status:', batch.status, '— counts:', batch.requestCounts);

    if (batch.status !== 'completed') {
      await new Promise(resolve => setTimeout(resolve, 5000));
    }
  } while (batch.status !== 'completed' && batch.status !== 'failed');

  console.log('Output file:', batch?.outputFileId);
}
```

--------------------------------

### Compare AI Providers

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Compares responses from multiple AI providers for the same prompt and saves the comparison to a markdown file. Ensure API keys for OpenAI, Anthropic, and Gemini are set in your environment variables.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';
import fs from 'fs';

dotenv.config();

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY,
  anthropicKey: process.env.ANTHROPIC_API_KEY,
  geminiKey: process.env.GEMINI_API_KEY
});

async function compareProviders() {
  const prompt = 'Explain the concept of recursion in programming to a beginner.';
  const messages = [{ role: 'user', content: prompt }];

  const responses = await aiSuite.createChatCompletionMultiResult(
    [
      'openai/gpt-4o',
      'anthropic/claude-3-5-sonnet-20241022',
      'gemini/gemini-2.5-flash'
    ],
    messages,
    { responseFormat: 'text' }
  );

  // Format the results
  let comparison = `# AI Provider Comparison\n\n`;
  comparison += `**Prompt:** ${prompt}\n\n`;

  const [openaiResponse, anthropicResponse, geminiResponse] = responses;

  if (openaiResponse.success) {
    comparison += `## OpenAI (GPT-4o)\n\n${openaiResponse.content}\n\n`;
    comparison += `*Execution time: ${openaiResponse.execution_time}ms*\n`;
    comparison += `*Tokens: ${openaiResponse.usage?.total_tokens}*\n\n`;
  }

  if (anthropicResponse.success) {
    comparison += `## Anthropic (Claude 3.5 Sonnet)\n\n${anthropicResponse.content}\n\n`;
    comparison += `*Execution time: ${anthropicResponse.execution_time}ms*\n`;
    comparison += `*Tokens: ${anthropicResponse.usage?.total_tokens}*\n\n`;
  }

  if (geminiResponse.success) {
    comparison += `## Google (Gemini 2.5 Flash)\n\n${geminiResponse.content}\n\n`;
    comparison += `*Execution time: ${geminiResponse.execution_time}ms*\n`;
    comparison += `*Tokens: ${geminiResponse.usage?.total_tokens}*\n\n`;
  }

  // Save to file
  fs.writeFileSync('ai-comparison.md', comparison);
  console.log('Comparison saved to ai-comparison.md');
}

compareProviders().catch(console.error);
```

--------------------------------

### Enable Tool/Function Calling

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Define tools with functions, their parameters, and descriptions to allow the AI to call external functions. The response will indicate which tool to call and with what arguments.

```typescript
const tools = [{
  type: 'function' as const,
  function: {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    parameters: {
      type: 'object' as const,
      properties: {
        location: {
          type: 'string' as const,
          description: 'The city name'
        },
        unit: {
          type: 'string' as const,
          description: 'Temperature unit (celsius or fahrenheit)'
        }
      },
      required: ['location'],
      additionalProperties: false
    },
    additionalProperties: false,
    strict: true
  }
}];

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'What is the weather in Paris?' }],
  {
    responseFormat: 'text',
    tools
  }
);

if (response.success && response.tools) {
  for (const tool of response.tools) {
    console.log(`Calling ${tool.name} with:`, tool.content);
    // Execute your function and send result back
  }
}
```

--------------------------------

### Connect to Custom LLM Providers

Source: https://context7.com/cubos/ai-suite/llms.txt

Configure AI Suite to connect to any OpenAI-compatible API endpoint, including self-hosted models like Ollama, LM Studio, or vLLM. For Ollama, the customLLMKey is not required.

```typescript
import { AISuite } from '@cubos/ai-suite';

// Using Ollama
const ollamaSuite = new AISuite({
  customURL: 'http://localhost:11434/v1',
  customLLMKey: 'not-needed'  // Ollama doesn't require auth
});

const response = await ollamaSuite.createChatCompletion(
  'custom-llm/llama3.2',  // Model name from your endpoint
  [{ role: 'user', content: 'What is TypeScript?' }],
  { responseFormat: 'text', temperature: 0.7 }
);

// Using LM Studio
const lmStudioSuite = new AISuite({
  customURL: 'http://localhost:1234/v1'
});

// Using vLLM
const vllmSuite = new AISuite({
  customURL: 'http://your-vllm-server:8000/v1',
  customLLMKey: 'optional-api-key'
});

const vllmResponse = await vllmSuite.createChatCompletion(
  'custom-llm/meta-llama/Llama-2-7b-chat-hf',
  [{ role: 'user', content: 'Hello!' }],
  { responseFormat: 'text' }
);
```

--------------------------------

### Implement Tool and Function Calling

Source: https://context7.com/cubos/ai-suite/llms.txt

Defines tools with JSON Schema parameters and handles tool execution within the conversation flow. Requires feeding the tool output back into the chat completion.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

// Define tools
const tools = [{
  type: 'function' as const,
  function: {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    parameters: {
      type: 'object' as const,
      properties: {
        location: {
          type: 'string' as const,
          description: 'The city name'
        },
        unit: {
          type: 'string' as const,
          description: 'Temperature unit (celsius or fahrenheit)'
        }
      },
      required: ['location'],
      additionalProperties: false
    },
    additionalProperties: false,
    strict: true
  }
}];

// Mock function
function getWeather(location: string): string {
  return `The weather in ${location} is sunny, 22°C`;
}

const response = await aiSuite.createChatCompletion(
  'openai/gpt-4o',
  [{ role: 'user', content: 'What is the weather in Tokyo?' }],
  { responseFormat: 'text', tools }
);

if (response.success && response.tools) {
  for (const tool of response.tools) {
    if (tool.name === 'get_weather') {
      const location = tool.content.location as string;
      const weatherData = getWeather(location);

      // Continue conversation with function result
      const followUp = await aiSuite.createChatCompletion(
        'openai/gpt-4o',
        [
          { role: 'user', content: 'What is the weather in Tokyo?' },
          { role: 'assistant', content: response.content || '' },
          { role: 'tool', content: weatherData, name: 'get_weather' }
        ],
        { responseFormat: 'text' }
      );

      if (followUp.success) {
        console.log('Assistant:', followUp.content);
      }
    }
  }
}
```

--------------------------------

### Create Batch

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-batch.md

Creates a new batch for chat completions or embeddings using either an inline array or a pre-uploaded file ID.

```APIDOC
## POST /batch/create

### Description
Creates a new batch job for processing multiple requests asynchronously.

### Parameters
#### Request Body
- **model** (string) - Required - The provider and model identifier (e.g., 'openai/gpt-4o-mini')
- **endpoint** (string) - Required - The endpoint type: 'chat/completions' or 'embeddings'
- **batch** (array) - Optional - Inline array of request objects
- **inputFileId** (string) - Optional - ID of a pre-uploaded file (OpenAI and Gemini only)
- **options** (object) - Optional - Model-specific configuration (e.g., temperature, maxOutputTokens, dimensions)
```

--------------------------------

### Enable Thinking Mode with Gemini 2.5

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Configures the Gemini provider with a specific thinking budget and output enabled for deep reasoning tasks.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';

dotenv.config();

const aiSuite = new AISuite({
  geminiKey: process.env.GEMINI_API_KEY
});

async function deepAnalysis() {
  const response = await aiSuite.createChatCompletion(
    'gemini/gemini-2.5-pro',
    [{
      role: 'user',
      content: 'Analyze the ethical implications of AI in healthcare'
    }],
    {
      responseFormat: 'text',
      thinking: {
        budget: 1024,
        output: true
      }
    }
  );

  if (response.success) {
    console.log('Analysis:', response.content);
    console.log('\nThinking tokens used:', response.usage?.thoughts_tokens);
  }
}

deepAnalysis().catch(console.error);
```

--------------------------------

### Compare multiple AI providers

Source: https://github.com/cubos/ai-suite/blob/main/doc/index.md

Execute a single prompt across multiple models simultaneously to compare results.

```typescript
const responses = await aiSuite.createChatCompletionMultiResult(
  ['openai/gpt-4o', 'anthropic/claude-3-5-sonnet-20241022', 'gemini/gemini-2.5-flash'],
  [{ role: 'user', content: 'Explain quantum computing' }],
  { responseFormat: 'text' }
);

const [openai, claude, gemini] = responses;
// Compare responses and execution times
```

--------------------------------

### Connect to Custom LLM via Ollama

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Configures the suite to communicate with a local Ollama instance by providing a custom URL.

```typescript
import { AISuite } from '@cubos/ai-suite';

const aiSuite = new AISuite({
  customURL: 'http://localhost:11434/v1',
  customLLMKey: 'not-needed'
});

async function main() {
  const response = await aiSuite.createChatCompletion(
    'custom-llm/llama3.2',
    [{ role: 'user', content: 'What is TypeScript?' }],
    {
      responseFormat: 'text',
      temperature: 0.7
    }
  );

  if (response.success) {
    console.log(response.content);
  } else {
    console.error('Error:', response.error);
  }
}

main().catch(console.error);
```

--------------------------------

### Enable Thinking Models

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Configure thinking budgets for models like Gemini 2.5 to manage the model's internal thought process and output.

```typescript
const response = await aiSuite.createChatCompletion(
  'gemini/gemini-2.5-pro',
  [{ role: 'user', content: 'Analyze this problem deeply...' }],
  {
    responseFormat: 'text',
    thinking: {
      budget: 512,
      output: true
    }
  }
);

if (response.success) {
  console.log('Thoughts tokens:', response.usage?.thoughts_tokens);
}
```

--------------------------------

### List Batches

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-batch.md

Lists batch jobs for a specific model with pagination support.

```APIDOC
## GET /batch/list

### Description
Returns a list of batch jobs associated with the specified model.

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of records to return
- **after** (string) - Optional - Cursor for pagination (ID of the last item)
```

--------------------------------

### Create Batch Chat Completions

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-batch.md

Use this to submit multiple chat completion requests in a single batch. Ensure the provider and endpoint are correctly specified.

```typescript
const result = await aiSuite.batch.create(
  'openai/gpt-4o-mini',
  'chat/completions',
  {
    batch: [
      {
        customId: 'req-1',
        params: {
          mensagens: [{ role: 'user', content: 'What is the capital of France?' }],
        },
      },
      {
        customId: 'req-2',
        params: {
          mensagens: [{ role: 'user', content: 'What is 2 + 2?' }],
        },
      },
    ],
  },
  {
    temperature: 0.7,
    maxOutputTokens: 512,
  },
);

if (result.success) {
  console.log('Batch created:', result.content.id);
  console.log('Status:', result.content.status);
} else {
  console.error('Error:', result.error);
}
```

--------------------------------

### Supported OpenAI Chat Models

Source: https://context7.com/cubos/ai-suite/llms.txt

Lists available model strings for OpenAI chat completions.

```typescript
// OpenAI Chat Models
'openai/gpt-4o'
'openai/gpt-4o-mini'
'openai/gpt-4-turbo'
'openai/gpt-4'
'openai/gpt-3.5-turbo'
'openai/o1'
'openai/o3'
```

--------------------------------

### Enable Reasoning Models

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Configure reasoning effort for models like OpenAI o1/o3 or Grok to control the depth of the model's internal processing.

```typescript
const response = await aiSuite.createChatCompletion(
  'openai/o1',
  [{ role: 'user', content: 'Solve this complex math problem...' }],
  {
    responseFormat: 'text',
    reasoning: {
      effort: 'high'
    }
  }
);

if (response.success) {
  console.log('Reasoning tokens:', response.usage?.reasoning_tokens);
}
```

--------------------------------

### List Batches

Source: https://github.com/cubos/ai-suite/blob/main/doc/usage-batch.md

Retrieve a list of batches, with options to limit the number of results and paginate using the `after` parameter.

```typescript
const result = await aiSuite.batch.list('openai/gpt-4o-mini', { limit: 10 });

if (result.success) {
  for (const b of result.content) {
    console.log(b.id, b.endpoint, b.status, b.requestCounts);
  }

  if (result.has_next_page) {
    // pass the last batch id as `after` for the next page
    const next = await aiSuite.batch.list('openai/gpt-4o-mini', {
      limit: 10,
      after: result.content.at(-1)?.id,
    });
  }
} else {
  console.error('List error:', result.error);
}
```

--------------------------------

### Complex Reasoning with OpenAI o1

Source: https://github.com/cubos/ai-suite/blob/main/doc/examples.md

Utilizes the 'openai/o1' model with a 'high' reasoning effort to solve a complex word problem. Displays the answer and detailed token usage, including reasoning tokens.

```typescript
import { AISuite } from '@cubos/ai-suite';
import dotenv from 'dotenv';

dotenv.config();

const aiSuite = new AISuite({
  openaiKey: process.env.OPENAI_API_KEY
});

async function solveComplexProblem() {
  const response = await aiSuite.createChatCompletion(
    'openai/o1',
    [{ 
      role: 'user',
      content: 'A farmer has 17 sheep. All but 9 die. How many sheep are left?'
    }],
    {
      responseFormat: 'text',
      reasoning: {
        effort: 'high'
      }
    }
  );

  if (response.success) {
    console.log('Answer:', response.content);
    console.log('\nToken usage:');
    console.log('- Input tokens:', response.usage?.input_tokens);
    console.log('- Reasoning tokens:', response.usage?.reasoning_tokens);
    console.log('- Output tokens:', response.usage?.output_tokens);
    console.log('- Total tokens:', response.usage?.total_tokens);
  }
}

solveComplexProblem().catch(console.error);
```

--------------------------------

### Send PDF Document with Chat Completion

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Use `InputContentFile` to send a PDF document. Ensure the file is read using `readFileSync` and passed directly as a Buffer. Supported media types include PDF, PNG, JPG, JPEG, GIF, and WebP.

```typescript
import { readFileSync } from 'fs';

const pdf = readFileSync('./document.pdf');

const response = await aiSuite.createChatCompletion(
  'anthropic/claude-3-5-sonnet-20241022',
  [
    {
      role: 'user',
      content: {
        type: 'file',
        mediaType: 'application/pdf',
        file: pdf,  // readFileSync returns a Buffer, use it directly
        fileName: 'document.pdf'
      }
    },
    {
      role: 'user',
      content: 'Summarize the contents of this PDF'
    }
  ],
  { responseFormat: 'text' }
);
```

--------------------------------

### createChatCompletion

Source: https://context7.com/cubos/ai-suite/llms.txt

Sends a chat completion request to a single AI provider and returns a typed result including content, token usage, and execution time.

```APIDOC
## createChatCompletion

### Description
Sends a chat completion request to a single AI provider. Returns a typed result containing the response content, token usage, execution time, and tool calls if applicable.

### Parameters
- **model** (string) - Required - The provider/model identifier (e.g., 'openai/gpt-4o').
- **messages** (array) - Required - An array of message objects with 'role' and 'content'.
- **options** (object) - Optional - Configuration including 'responseFormat' and 'temperature'.

### Response
- **success** (boolean) - Indicates if the request was successful.
- **content** (string) - The generated response content.
- **usage** (object) - Token usage statistics.
- **execution_time** (number) - Time taken in milliseconds.
- **error** (string) - Error message if request failed.
- **tag** (string) - Error category (e.g., 'InvalidAuth', 'RateLimitExceeded').
```

--------------------------------

### Supported DeepSeek Models

Source: https://context7.com/cubos/ai-suite/llms.txt

Lists available model strings for DeepSeek chat and reasoning models.

```typescript
// DeepSeek Models
'deepseek/deepseek-chat'
'deepseek/deepseek-coder'
'deepseek/deepseek-reasoner'
```

--------------------------------

### Supported Grok Models

Source: https://context7.com/cubos/ai-suite/llms.txt

Lists available model strings for Grok models, including vision.

```typescript
// Grok Models
'grok/grok-3'
'grok/grok-3-mini'
'grok/grok-3-fast'
'grok/grok-vision-beta'
```

--------------------------------

### Enable Thinking Mode for Gemini

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Configures the thinking budget for Gemini 2.5 models to allow for deeper analysis and optional output of the thinking process.

```typescript
const response = await aiSuite.createChatCompletion(
  'gemini/gemini-2.5-pro',
  [{ role: 'user', content: 'Analyze this complex problem deeply...' }],
  {
    responseFormat: 'text',
    thinking: {
      budget: 1024,     // Token budget for thinking (0-16384)
      output: true      // Include thinking process in output
    }
  }
);

if (response.success) {
  console.log('Response:', response.content);
  console.log('Thinking tokens used:', response.usage?.thoughts_tokens);
}
```

--------------------------------

### Compare Multiple AI Providers

Source: https://github.com/cubos/ai-suite/blob/main/doc/advanced-usage.md

Executes chat completions across multiple models simultaneously and returns an array of responses in the order of the provided models.

```typescript
const responses = await aiSuite.createChatCompletionMultiResult(
  [
    'openai/gpt-4o',
    'anthropic/claude-3-5-sonnet-20241022',
    'gemini/gemini-2.5-flash'
  ],
  [{ role: 'user', content: 'Explain quantum computing in simple terms.' }],
  {
    responseFormat: 'text',
    temperature: 0.7
  }
);

// Responses is an array in the same order as providers
const [openaiResponse, claudeResponse, geminiResponse] = responses;

if (openaiResponse.success) {
  console.log('OpenAI:', openaiResponse.content);
  console.log('Time:', openaiResponse.execution_time + 'ms');
}

if (claudeResponse.success) {
  console.log('Claude:', claudeResponse.content);
  console.log('Time:', claudeResponse.execution_time + 'ms');
}

if (geminiResponse.success) {
  console.log('Gemini:', geminiResponse.content);
  console.log('Time:', geminiResponse.execution_time + 'ms');
}
```

--------------------------------

### ChatOptionsBase Interface

Source: https://github.com/cubos/ai-suite/blob/main/doc/api-reference.md

Base interface for chat options, including common settings like temperature, token limits, and retry configurations.

```typescript
interface ChatOptionsBase {
  stream?: boolean;  // Currently not supported
  temperature?: number;  // Default: 0.7

  // Token management
  maxOutputTokens?: number;

  // Tools/Functions
  tools?: ToolModel[];

  // Retry configuration
  retry?: {
    attempts: number;
    delay?: (attempt: number) => number;  // Default: exponential backoff
  };

  // Reasoning (OpenAI o1/o3, Grok)
  reasoning?: {
    effort: 'low' | 'medium' | 'high';
  };

  // Thinking (Gemini 2.5)
  thinking?: {
    budget: number;   // Thinking budget tokens
    output: boolean;  // Include thinking in output
  };

  // Langfuse tracking metadata
  metadata?: Record<string, unknown> & {
    langFuse?: {
      userId?: string;
      environment?: string;
      sessionId?: string;
      name?: string;
      tags?: string[];
    };
  };
}
```