Examples Overview

Explore 35+ runnable examples demonstrating every feature of ai.matey, 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 ai.matey 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 ai.matey 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-openai	OpenAI integration	OpenAI (GPT-4, GPT-3.5)
02-anthropic	Anthropic Claude	Anthropic (Claude 3.5)
03-gemini	Google Gemini	Google (Gemini 1.5)
04-local-ollama	Local models	Ollama (Llama 3, Mistral)
05-multi-provider	Multiple providers	Router pattern

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-complexity-based	Route by query complexity	Cost optimization
04-parallel-dispatch	Fan-out to multiple backends	Comparison/consensus
05-cost-optimized	Choose cheapest provider	84% cost savings

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-node-http	Native Node.js HTTP	Node.js http
02-express	Express.js integration	Express
03-hono	Edge-ready server	Hono
04-streaming-http	SSE streaming	Server-Sent Events

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
03-chrome-ai	Chrome AI compatibility	Chrome AI API
04-wrapper-utils	Stream utilities	50+ functions

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-websocket-chat	WebSocket chat	Multi-client support
03-batch-processing	Batch requests	21+ req/s throughput
04-health-monitoring	Provider health checks	Real-time dashboard
05-middleware-chain	Complex middleware	Chain of Responsibility

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
01-jaeger	OpenTelemetry + Jaeger	Local (Docker)
02-honeycomb	Honeycomb integration	SaaS
03-sampling	Sampling strategies	Configurable
04-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
01-hooks	React hooks	useChat, useCompletion, useObject

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
01-cli-basics	CLI tools	Format conversion, backend generation

Start here if: You need CLI tooling.

🚀 Running Examples

Prerequisites

# Install dependencies
cd /path/to/ai.matey
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 examples/01-basics/01-hello-world.ts
npx tsx examples/03-middleware/01-logging.ts
npx tsx 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!