Installation

Get aimatey up and running in 2 minutes.

Prerequisites

• Node.js 18.0.0 or higher
• npm 9.0.0 or higher (or yarn/pnpm)
• TypeScript 5.0+ (optional but recommended)

Quick Install

Install the main package to get started quickly:

npm install @johnhenry/aimatey

This installs the umbrella package which includes commonly-used adapters and utilities.

Package-Specific Installation

For more control over bundle size, install only the packages you need:

Core Packages

# Essential packages
npm install @johnhenry/aimatey-core        # Bridge, Router, Middleware
npm install @johnhenry/aimatey-types       # TypeScript type definitions
npm install @johnhenry/aimatey-errors      # Error classes and utilities
npm install @johnhenry/aimatey-utils       # Shared utility functions

Frontend Adapters

Choose the input format you want to use:

npm install @johnhenry/aimatey-frontend    # All frontend adapters

Each format lives at its own import subpath, so bundlers only include what you import:

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';       // OpenAI format
import { AnthropicFrontendAdapter } from '@johnhenry/aimatey-frontend/anthropic'; // Anthropic format
import { GeminiFrontendAdapter } from '@johnhenry/aimatey-frontend/gemini';       // Google Gemini format
import { MistralFrontendAdapter } from '@johnhenry/aimatey-frontend/mistral';     // Mistral format

Backend Adapters

Choose which AI providers you want to support:

npm install @johnhenry/aimatey-backend     # All backend adapters, one package

Each provider lives at its own import subpath, so unused providers stay out of your bundle:

import { OpenAIBackendAdapter } from '@johnhenry/aimatey-backend/openai';       // OpenAI
import { AnthropicBackendAdapter } from '@johnhenry/aimatey-backend/anthropic'; // Anthropic (Claude)
import { GeminiBackendAdapter } from '@johnhenry/aimatey-backend/gemini';       // Google Gemini
import { OllamaBackendAdapter } from '@johnhenry/aimatey-backend/ollama';       // Ollama (local)
import { GroqBackendAdapter } from '@johnhenry/aimatey-backend/groq';           // Groq (fast inference)

All backend provider subpaths

# Cloud providers
@johnhenry/aimatey-backend/openai
@johnhenry/aimatey-backend/anthropic
@johnhenry/aimatey-backend/gemini
@johnhenry/aimatey-backend/mistral
@johnhenry/aimatey-backend/cohere
@johnhenry/aimatey-backend/groq
@johnhenry/aimatey-backend/ai21
@johnhenry/aimatey-backend/anyscale
@johnhenry/aimatey-backend/aws-bedrock
@johnhenry/aimatey-backend/azure-openai
@johnhenry/aimatey-backend/cerebras
@johnhenry/aimatey-backend/cloudflare
@johnhenry/aimatey-backend/dashscope
@johnhenry/aimatey-backend/deepinfra
@johnhenry/aimatey-backend/deepseek
@johnhenry/aimatey-backend/fireworks
@johnhenry/aimatey-backend/github-models
@johnhenry/aimatey-backend/huggingface
@johnhenry/aimatey-backend/inception
@johnhenry/aimatey-backend/moonshot
@johnhenry/aimatey-backend/nvidia
@johnhenry/aimatey-backend/omniroute
@johnhenry/aimatey-backend/openrouter
@johnhenry/aimatey-backend/perplexity
@johnhenry/aimatey-backend/replicate
@johnhenry/aimatey-backend/sambanova
@johnhenry/aimatey-backend/together-ai
@johnhenry/aimatey-backend/xai

# Local/Self-Hosted
@johnhenry/aimatey-backend/ollama
@johnhenry/aimatey-backend/lmstudio

Optional Packages

# Middleware (logging, caching, retry, etc.)
npm install @johnhenry/aimatey-middleware

# HTTP server integration
npm install @johnhenry/aimatey-http        # Express, Fastify, Hono, Node.js http

# React hooks
npm install @johnhenry/aimatey-react-core
npm install @johnhenry/aimatey-react-hooks

# SDK wrappers (drop-in replacements)
npm install @johnhenry/aimatey-wrapper

# CLI tools
npm install @johnhenry/aimatey-cli

# Testing utilities
npm install @johnhenry/aimatey-testing

Verify Installation

Create a simple test file to verify installation:

test.ts

import { Bridge } from '@johnhenry/aimatey-core';
import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';
import { OpenAIBackendAdapter } from '@johnhenry/aimatey-backend/openai';

console.log('aimatey installed successfully!');

const bridge = new Bridge(
  new OpenAIFrontendAdapter(),
  new OpenAIBackendAdapter({ apiKey: 'test-key' })
);

console.log('Bridge created:', bridge ? '✓' : '✗');

Run it:

npx tsx test.ts
# Should output: aimatey installed successfully!
#                Bridge created: ✓

Environment Setup

1. Create Environment File

Create a .env file in your project root:

.env

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-...

# Google Gemini
GOOGLE_API_KEY=...

# Other providers (as needed)
DEEPSEEK_API_KEY=...
GROQ_API_KEY=...
MISTRAL_API_KEY=...
HUGGINGFACE_API_KEY=...

# Local models (optional)
OLLAMA_BASE_URL=http://localhost:11434
LMSTUDIO_BASE_URL=http://localhost:1234

2. Load Environment Variables

Node.js

npm install dotenv

import 'dotenv/config';

const apiKey = process.env.ANTHROPIC_API_KEY;

TypeScript with Vite/Vitest

Environment variables are loaded automatically from .env files.

const apiKey = import.meta.env.VITE_ANTHROPIC_API_KEY;

TypeScript Configuration

For optimal TypeScript support, configure your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true
  }
}

Installation by Use Case

For Chat Applications

npm install @johnhenry/aimatey-core \
            @johnhenry/aimatey-frontend \
            @johnhenry/aimatey-backend \
            @johnhenry/aimatey-middleware

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';
import { AnthropicBackendAdapter } from '@johnhenry/aimatey-backend/anthropic';

For HTTP APIs

npm install @johnhenry/aimatey-core \
            @johnhenry/aimatey-frontend \
            @johnhenry/aimatey-backend \
            @johnhenry/aimatey-http

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';

For React Apps

npm install @johnhenry/aimatey-core \
            @johnhenry/aimatey-frontend \
            @johnhenry/aimatey-backend \
            @johnhenry/aimatey-react-core \
            @johnhenry/aimatey-react-hooks

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';
import { OpenAIBackendAdapter } from '@johnhenry/aimatey-backend/openai';

For Local Development

npm install @johnhenry/aimatey-core \
            @johnhenry/aimatey-frontend \
            @johnhenry/aimatey-backend

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';
import { OllamaBackendAdapter } from '@johnhenry/aimatey-backend/ollama';

Then install and run Ollama:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.2

# Ollama server runs on http://localhost:11434

Troubleshooting

Module Not Found Error

Error: Cannot find module '@johnhenry/aimatey-core'

Solution: Ensure you’ve installed the package:

npm install @johnhenry/aimatey-core

Type Errors in TypeScript

Could not find a declaration file for module '@johnhenry/aimatey-core'

Solution: Install type definitions:

npm install @johnhenry/aimatey-types

ESM vs CommonJS Issues

aimatey is an ES Module (ESM) package. If you’re using CommonJS:

package.json:

{
  "type": "module"
}

Or use .mjs file extensions.

Import Path Issues

Use full import paths including the adapter name:

✅ Correct:

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend/openai';
import { AnthropicBackendAdapter } from '@johnhenry/aimatey-backend/anthropic';

❌ Incorrect:

import { OpenAIFrontendAdapter } from '@johnhenry/aimatey-frontend';

Next Steps

• Quick Start - Build your first bridge
• Core Concepts - Understand the architecture
• Your First Bridge - Step-by-step tutorial
• Examples - Explore working code

Package Versions

All aimatey packages use synchronized versioning. Install matching versions:

# Good (matching versions)
@johnhenry/[email protected]
@johnhenry/[email protected]
@johnhenry/[email protected]

# Avoid (mismatched versions)
@johnhenry/[email protected]
@johnhenry/[email protected]

Check the latest version on npm.