Examples Overview

Explore 35+ runnable examples demonstrating every feature of aimatey, organized by complexity from beginner to advanced.

By Skill Level

⭐ Beginner → 01. Basics | 02. Providers
⭐⭐ Intermediate → 03. Middleware | 04. Routing | 05. HTTP Servers | 06. SDK Wrappers
⭐⭐⭐ Advanced → 07. Advanced Patterns | 08. Observability
🎯 Specialized → 09. React | 10. CLI Tools

By Feature

Getting Started → Basics
Multiple Providers → Providers | Routing
Performance → Middleware
Production → Advanced Patterns
Monitoring → Observability

📂 All Examples

01. Basics

Complexity: ⭐ Beginner Time to complete: 5-10 minutes each

Learn the fundamentals of aimatey with these simple examples.

Example	Description	Key Concepts
01-hello-world	Your first bridge	Bridge, Frontend, Backend
02-streaming	Real-time responses	Streaming, Async generators
03-error-handling	Handle errors gracefully	Error handling, Validation
04-reverse-bridge	Swap frontend/backend	Adapter flexibility

Start here if: You’re new to aimatey or want to understand core concepts.

02. Providers

Complexity: ⭐ Beginner Time to complete: 5-10 minutes each

Work with different AI providers.

Example	Description	Provider
01-anthropic	Anthropic Claude	Anthropic (Claude 3.5)
02-openai	OpenAI integration	OpenAI (GPT-4, GPT-3.5)
03-google-gemini	Google Gemini	Google (Gemini 1.5)
04-local-models	Local models	Ollama, LMStudio
05-multiple-providers	Multiple providers	Router pattern
06-provider-switching	Switch providers at runtime	Any provider

Start here if: You want to understand provider-specific features.

03. Middleware

Complexity: ⭐⭐ Intermediate Time to complete: 10-15 minutes each

Add powerful middleware to your pipelines.

Example	Description	Performance
01-logging	Request/response logging	-
02-caching	Response caching	1000x+ speedup
03-retry	Auto retry on failure	Improved reliability
04-transform	Modify requests/responses	Custom behavior
05-cost-tracking	Track API costs	Cost visibility
06-middleware-stack	Compose middleware	<10ms overhead

Start here if: You need logging, caching, retry, or cost tracking.

04. Routing

Complexity: ⭐⭐ Intermediate Time to complete: 15-20 minutes each

Intelligently route requests across providers.

Example	Description	Use Case
01-round-robin	Load balancing	Distribute load
02-fallback	Automatic failover	High availability
03-weighted-routing	Weighted load distribution	Gradual rollouts
04-cost-based-routing	Choose cheapest provider	Cost optimization
05-custom-strategy	Build your own routing logic	Custom strategies

Start here if: You need multi-provider routing or failover.

05. HTTP Servers

Complexity: ⭐⭐ Intermediate Time to complete: 15-20 minutes each

Integrate with web frameworks.

Example	Description	Framework
01-express	Express.js integration	Express
02-hono	Edge-ready server	Hono
03-node-http	Native Node.js HTTP	Node.js http
websocket-server	WebSocket streaming chat	WebSockets

Start here if: You’re building an HTTP API.

06. SDK Wrappers

Complexity: ⭐⭐ Intermediate Time to complete: 10-15 minutes each

Drop-in replacements for official SDKs.

Example	Description	Compatibility
01-openai-sdk	OpenAI SDK wrapper	100% compatible
02-anthropic-sdk	Anthropic SDK wrapper	100% compatible
chrome-ai-wrapper	Chrome AI compatibility	Chrome AI API

Start here if: You want SDK compatibility.

07. Advanced Patterns

Complexity: ⭐⭐⭐ Advanced Time to complete: 20-30 minutes each

Production-ready patterns for real-world applications.

Example	Description	Performance
01-streaming-aggregation	Parallel streaming	Real-time comparison
02-observability	Metrics and tracing	Production monitoring
03-testing	Testing AI integrations	Mock adapters
04-cli-tool	Build a CLI tool	Command-line apps
05-react-integration	React patterns	Hooks, streaming UI
06-performance	Performance tuning	Benchmarks
07-production	Production deployment	Best practices
08-edge-deployment	Edge deployment	Workers, Deno

Start here if: You’re building production systems.

08. Observability

Complexity: ⭐⭐⭐ Advanced Time to complete: 20-30 minutes each

Monitor and trace your AI requests.

Example	Description	Platform
basic-jaeger	OpenTelemetry + Jaeger	Local (Docker)
honeycomb	Honeycomb integration	SaaS
sampling	Sampling strategies	Configurable
multi-provider	Multi-provider tracing	All providers

Start here if: You need monitoring and observability.

09. React

Complexity: 🎯 Specialized Time to complete: 15-20 minutes

Frontend integration with React.

Example	Description	Hooks
react-hooks	React hooks	useChat, useCompletion, useObject
05-react-integration	React integration patterns	Custom hooks, streaming

Start here if: You’re building React applications.

10. CLI Tools

Complexity: 🎯 Specialized Time to complete: 10-15 minutes

Command-line utilities.

Example	Description	Tools
04-cli-tool	CLI tools	Format conversion, interactive prompts

Start here if: You need CLI tooling.

🚀 Running Examples

Prerequisites

# Install dependencies
cd /path/to/aimatey
npm install
npm run build

# Set up API keys (create .env file)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Run Any Example

npx tsx packages/aimatey-docs/examples/01-basics/01-hello-world.ts
npx tsx packages/aimatey-docs/examples/03-middleware/01-logging.ts
npx tsx packages/aimatey-docs/examples/07-advanced-patterns/01-streaming-aggregation.ts

📚 Learning Paths

Beginner Path (Recommended for Newcomers)

Intermediate Path

Advanced Path

💡 Tips

Start Simple: Begin with 01-hello-world to understand the basics
Read Comments: Every example has detailed inline comments
Experiment: Modify examples to learn how they work
Use Shared Utils: The _shared/ directory has helpful utilities
Check Prerequisites: Each example lists what you need to run it

Getting Started - Installation and setup
API Reference - Complete API documentation
IR Format Guide - In-depth guides
Patterns - Production patterns

Ready to start? Jump to Hello World or explore examples by category above!