Quick Start

Get started with ai.matey in less than 5 minutes. This guide will walk you through creating your first bridge and making AI requests.

1. Install ai.matey

npm install ai.matey.core ai.matey.frontend ai.matey.backend

2. Get API Keys

You’ll need an API key from at least one provider. We recommend starting with Anthropic (Claude) as it’s reliable and has good free tier:

# Sign up at https://console.anthropic.com/
# Get your API key and set it in your environment
export ANTHROPIC_API_KEY=sk-ant-...

Alternatively, use any of these providers:

• OpenAI - GPT-4, GPT-3.5
• Google AI Studio - Gemini (free tier available)
• Groq - Fast inference (free tier available)
• Ollama - Local models (no API key needed)

3. Create Your First Bridge

Create a file called hello.ts:

import { Bridge } from 'ai.matey.core';
import { OpenAIFrontendAdapter } from 'ai.matey.frontend/openai';
import { AnthropicBackendAdapter } from 'ai.matey.backend/anthropic';

// Create a bridge: OpenAI format → Anthropic execution
const bridge = new Bridge(
  new OpenAIFrontendAdapter(),
  new AnthropicBackendAdapter({
    apiKey: process.env.ANTHROPIC_API_KEY
  })
);

// Make a request using OpenAI format
const response = await bridge.chat({
  model: 'gpt-4', // Will be mapped to claude-3-5-sonnet
  messages: [
    { role: 'user', content: 'What is ai.matey?' }
  ]
});

console.log(response.choices[0].message.content);

4. Run It

npx tsx hello.ts

You should see Claude’s response, even though you wrote the code in OpenAI format!

What Just Happened?

Your Code (OpenAI format)
         ↓
OpenAI Frontend Adapter (parses OpenAI format)
         ↓
Intermediate Representation (IR) - Universal format
         ↓
Anthropic Backend Adapter (converts IR to Anthropic format)
         ↓
Claude API (executes the request)
         ↓
Response (converted back through the pipeline)

This is the power of ai.matey: write once, run anywhere.

Common Patterns

Pattern 1: Direct Backend (No Bridge)

For simple use cases, use backends directly:

import { AnthropicBackendAdapter } from 'ai.matey.backend/anthropic';

const backend = new AnthropicBackendAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY
});

// Execute using Intermediate Representation (IR) format
const response = await backend.execute({
  model: 'claude-3-5-sonnet-20241022',
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});

Pattern 2: Streaming

Stream responses in real-time:

const stream = await bridge.chatStream({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'Write a haiku about TypeScript' }
  ],
  stream: true
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) {
    process.stdout.write(delta);
  }
}

Pattern 3: Multiple Providers with Fallback

Route to multiple providers with automatic fallback:

import { Bridge, createRouter } from 'ai.matey.core';
import { OpenAIFrontendAdapter } from 'ai.matey.frontend/openai';
import { OpenAIBackendAdapter } from 'ai.matey.backend/openai';
import { AnthropicBackendAdapter } from 'ai.matey.backend/anthropic';

const router = createRouter({
  routingStrategy: 'fallback'
})
  .register('openai', new OpenAIBackendAdapter({
    apiKey: process.env.OPENAI_API_KEY
  }))
  .register('anthropic', new AnthropicBackendAdapter({
    apiKey: process.env.ANTHROPIC_API_KEY
  }))
  .setFallbackChain(['openai', 'anthropic']); // Try OpenAI first, fall back to Anthropic

const bridge = new Bridge(
  new OpenAIFrontendAdapter(),
  router
);

// If OpenAI fails, automatically tries Anthropic
const response = await bridge.chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Pattern 4: With Middleware

Add logging, caching, or retry logic:

import { Bridge } from 'ai.matey.core';
import { OpenAIFrontendAdapter } from 'ai.matey.frontend/openai';
import { AnthropicBackendAdapter } from 'ai.matey.backend/anthropic';
import { createLoggingMiddleware, createRetryMiddleware } from 'ai.matey.middleware';

const bridge = new Bridge(
  new OpenAIFrontendAdapter(),
  new AnthropicBackendAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
  [
    createLoggingMiddleware({ level: 'info' }),
    createRetryMiddleware({ maxAttempts: 3 })
  ]
);

// Now all requests are logged and automatically retried on failure
const response = await bridge.chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Switching Providers

The beauty of ai.matey is that switching providers is trivial. Just change the backend:

// Development: Use local Ollama
const devBackend = new OllamaBackendAdapter({
  baseURL: 'http://localhost:11434'
});

// Production: Use OpenAI
const prodBackend = new OpenAIBackendAdapter({
  apiKey: process.env.OPENAI_API_KEY
});

// Choose based on environment
const backend = process.env.NODE_ENV === 'production'
  ? prodBackend
  : devBackend;

const bridge = new Bridge(
  new OpenAIFrontendAdapter(),
  backend
);

// Same code works with both!
const response = await bridge.chat({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Frontend Adapters

You can also swap the frontend to use different API formats:

import { AnthropicFrontendAdapter } from 'ai.matey.frontend/anthropic';
import { OpenAIBackendAdapter } from 'ai.matey.backend/openai';

// Accept Anthropic format → Execute on OpenAI
const bridge = new Bridge(
  new AnthropicFrontendAdapter(),
  new OpenAIBackendAdapter({ apiKey: process.env.OPENAI_API_KEY })
);

// Now use Anthropic's API format
const response = await bridge.chat({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 100,
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});

Next Steps

Learn the Concepts

• Core Concepts - Understand Bridge, Router, Middleware, and IR
• Your First Bridge - Detailed step-by-step tutorial

Explore Examples

• Hello World - Simplest example
• Streaming - Real-time responses
• Middleware - Add logging, caching, retry
• Routing - Multi-provider routing

Dive Deeper

• IR Format Guide - Understand the IR format
• Backend Package - All 24+ supported providers
• Middleware Package - All middleware types
• Advanced Patterns - Production-ready patterns

Integration Guides

• HTTP Servers - Express, Fastify, Hono
• React Hooks - useChat, useCompletion
• Testing - Test your AI integrations

Common Issues

Missing API Key Error

Error: Missing required API key

Solution: Set your API key in the environment:

export ANTHROPIC_API_KEY=sk-ant-...

Or load from a .env file using dotenv:

npm install dotenv

import 'dotenv/config';

Module Import Errors

Cannot find module 'ai.matey.core'

Solution: Make sure you’ve installed all required packages:

npm install ai.matey.core ai.matey.frontend ai.matey.backend

Model Mapping

By default, models are automatically mapped between providers:

• gpt-4 → claude-3-5-sonnet-20241022 (OpenAI → Anthropic)
• gpt-3.5-turbo → claude-3-haiku-20240307 (OpenAI → Anthropic)

To use specific models, check the Backend Adapters documentation.

Need Help?

• Examples - Browse 35+ working examples
• API Reference - Complete API documentation
• GitHub Issues - Report bugs or ask questions
• Contributing - Contribute to ai.matey

---

Ready to build? Continue to Core Concepts to learn the fundamentals, or jump straight to Your First Bridge for a hands-on tutorial!