@falai/agent 0.1.0

package/docs/PROVIDERS.md

@@ -0,0 +1,472 @@
+# AI Providers Guide
+
+This guide covers the available AI providers and how to configure them for optimal performance.
+
+## Overview
+
+`@falai/agent` uses a **strategy pattern** for AI providers, allowing you to:
+
+- ✅ Switch between different AI providers easily
+- ✅ Configure provider-specific settings
+- ✅ Use backup models for failover
+- ✅ Customize retry logic and timeouts
+
+---
+
+## Available Providers
+
+### 🌐 OpenRouter (Multi-Model Access)
+
+**Package:** `openai` (OpenRouter uses OpenAI-compatible API)
+
+#### Overview
+
+OpenRouter provides access to 200+ AI models through a single unified API, including models from OpenAI, Anthropic, Google, Meta, and more. Perfect for:
+
+- Access to multiple model providers
+- Cost optimization through model selection
+- Fallback across different providers
+- Comparing model performance
+
+#### Installation
+
+```bash
+bun add openai
+# or
+npm install openai
+```
+
+#### Basic Usage
+
+```typescript
+import { OpenRouterProvider } from "@falai/agent";
+
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "openai/gpt-5", // Required - specify your model
+  siteUrl: "https://yourapp.com", // Optional: for rankings
+  siteName: "Your App Name", // Optional: for rankings
+});
+```
+
+#### Configuration Options
+
+All models are specified by the user - see https://openrouter.ai/models for the full list.
+
+```typescript
+const provider = new OpenRouterProvider({
+  // Required
+  apiKey: string;
+  model: string; // e.g., "openai/gpt-5", "anthropic/claude-sonnet-4.5", etc.
+
+  // Optional
+  backupModels?: string[]; // Default: []
+  siteUrl?: string; // Your app URL for OpenRouter rankings
+  siteName?: string; // Your app name for OpenRouter rankings
+  config?: Partial<Omit<ChatCompletionCreateParamsNonStreaming, "model" | "messages">>; // Uses openai package types
+  retryConfig?: {
+    timeout?: number; // Default: 60000ms (60s)
+    retries?: number; // Default: 3
+  };
+});
+```
+
+#### Example: Custom Configuration
+
+```typescript
+const provider = new OpenRouterProvider({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  model: "anthropic/claude-sonnet-4.5",
+  backupModels: ["openai/gpt-5", "google/gemini-2.5-flash"],
+  siteUrl: "https://myapp.com",
+  siteName: "My AI Agent",
+  config: {
+    temperature: 0.7,
+    max_tokens: 2048,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 45000,
+    retries: 2,
+  },
+});
+```
+
+---
+
+### 🤖 Gemini (Google AI)
+
+**Package:** `@google/genai`
+
+#### Installation
+
+```bash
+bun add @google/genai
+# or
+npm install @google/genai
+```
+
+#### Basic Usage
+
+```typescript
+import { GeminiProvider } from "@falai/agent";
+
+const provider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro", // Required - specify your model
+});
+```
+
+#### Configuration Options
+
+All models are specified by the user - check [Google AI Studio](https://ai.google.dev/) for available models.
+
+```typescript
+const provider = new GeminiProvider({
+  // Required
+  apiKey: string;
+  model: string; // e.g., "models/gemini-2.5-pro", "models/gemini-2.5-flash", etc.
+
+  // Optional
+  backupModels?: string[]; // Default: []
+  config?: Partial<GenerateContentConfig>; // Uses @google/genai package types
+  retryConfig?: {
+    timeout?: number; // Default: 60000ms (60s)
+    retries?: number; // Default: 3
+  };
+});
+```
+
+#### Example: Advanced Configuration
+
+```typescript
+const provider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
+  backupModels: ["models/gemini-2.5-flash"],
+  config: {
+    thinkingConfig: {
+      includeThoughts: false,
+      thinkingBudget: 8192,
+    },
+  },
+  retryConfig: {
+    timeout: 45000,
+    retries: 2,
+  },
+});
+```
+
+---
+
+### 🧠 OpenAI
+
+**Package:** `openai`
+
+#### Installation
+
+```bash
+bun add openai
+# or
+npm install openai
+```
+
+#### Basic Usage
+
+```typescript
+import { OpenAIProvider } from "@falai/agent";
+
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5", // Required - specify your model
+});
+```
+
+#### Configuration Options
+
+All models are specified by the user - see [OpenAI Models](https://platform.openai.com/docs/models) for available options.
+
+```typescript
+const provider = new OpenAIProvider({
+  // Required
+  apiKey: string;
+  model: string; // e.g., "gpt-5", "gpt-5-mini", etc.
+
+  // Optional
+  organization?: string;
+  backupModels?: string[]; // Default: []
+  config?: Partial<Omit<ChatCompletionCreateParamsNonStreaming, "model" | "messages">>; // Uses openai package types
+  retryConfig?: {
+    timeout?: number; // Default: 60000ms (60s)
+    retries?: number; // Default: 3
+  };
+});
+```
+
+#### Example: Advanced Configuration
+
+```typescript
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
+  backupModels: ["gpt-5-mini"],
+  config: {
+    temperature: 0.7,
+    max_tokens: 2048,
+    top_p: 0.9,
+  },
+  retryConfig: {
+    timeout: 45000,
+    retries: 2,
+  },
+});
+```
+
+---
+
+## Retry & Backup Logic
+
+Both providers implement **robust retry logic** with:
+
+### Automatic Retries
+
+- ⏱️ Exponential backoff between retries
+- ⚙️ Configurable timeout and retry count
+- 🔄 Automatic fallback to backup models
+
+### When Backup Models Are Used
+
+Backup models are automatically tried when:
+
+- ❌ Primary model returns 500 (Internal Server Error)
+- ❌ Primary model returns 503 (Service Unavailable)
+- ❌ Primary model returns 429 (Rate Limit)
+- ❌ Model is overloaded or unavailable
+- ❌ Request times out
+
+### Example: Backup Flow
+
+```typescript
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5", // Primary
+  backupModels: [
+    "gpt-5-mini", // Try first
+    "gpt-5-nano", // Try second
+  ],
+  retryConfig: {
+    timeout: 30000,
+    retries: 2,
+  },
+});
+
+// If gpt-5 fails with 500 error:
+// 1. Retry gpt-5 (up to 2 times with exponential backoff)
+// 2. If still failing, try gpt-5-mini
+// 3. If that fails, try gpt-5-nano
+// 4. If all fail, throw error
+```
+
+---
+
+## Switching Providers
+
+You can easily switch between providers:
+
+```typescript
+import { Agent, GeminiProvider, OpenAIProvider } from "@falai/agent";
+
+// Use Gemini
+const geminiAgent = new Agent({
+  name: "Gemini Assistant",
+  ai: new GeminiProvider({
+    apiKey: process.env.GEMINI_API_KEY!,
+  }),
+});
+
+// Use OpenAI
+const openaiAgent = new Agent({
+  name: "OpenAI Assistant",
+  ai: new OpenAIProvider({
+    apiKey: process.env.OPENAI_API_KEY!,
+  }),
+});
+
+// Both agents have the same interface!
+```
+
+---
+
+## Environment Variables
+
+It's recommended to store API keys in environment variables:
+
+```bash
+# .env
+GEMINI_API_KEY=your-gemini-api-key-here
+OPENAI_API_KEY=your-openai-api-key-here
+```
+
+Then load them:
+
+```typescript
+import { config } from "dotenv";
+config();
+
+const geminiProvider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+});
+
+const openaiProvider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+});
+```
+
+---
+
+## Custom Providers
+
+Want to add a custom provider? Implement the `AiProvider` interface:
+
+```typescript
+import {
+  AiProvider,
+  GenerateMessageInput,
+  GenerateMessageOutput,
+} from "@falai/agent";
+
+export class CustomProvider implements AiProvider {
+  public readonly name = "custom";
+
+  async generateMessage<TContext = unknown>(
+    input: GenerateMessageInput<TContext>
+  ): Promise<GenerateMessageOutput> {
+    // Your implementation here
+    const response = await yourApiCall(input.prompt);
+
+    return {
+      message: response.text,
+      metadata: {
+        model: "your-model",
+        tokensUsed: response.tokens,
+      },
+    };
+  }
+}
+```
+
+See the [API Reference](./API_REFERENCE.md) for the full `AiProvider` interface definition.
+
+---
+
+## Best Practices
+
+### 1. Use Environment-Specific Configs
+
+```typescript
+const isDev = process.env.NODE_ENV === "development";
+
+const provider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: isDev ? "models/gemini-2.5-flash" : "models/gemini-2.5-pro",
+  retryConfig: {
+    timeout: isDev ? 10000 : 60000,
+    retries: isDev ? 1 : 3,
+  },
+});
+```
+
+### 2. Configure Backup Models by Use Case
+
+```typescript
+// For critical production apps
+const productionProvider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5-pro",
+  backupModels: ["gpt-5", "gpt-5-mini"], // More capable backups
+});
+
+// For high-volume, low-cost
+const volumeProvider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5-mini",
+  backupModels: ["gpt-5-nano"], // Faster, cheaper model
+});
+```
+
+### 3. Monitor Provider Performance
+
+```typescript
+const response = await agent.generateMessage(input);
+
+console.log(`Model used: ${response.metadata?.model}`);
+console.log(`Tokens used: ${response.metadata?.tokensUsed}`);
+console.log(`Finish reason: ${response.metadata?.finishReason}`);
+```
+
+---
+
+## Troubleshooting
+
+### API Key Not Found
+
+```
+Error: apiKey is required
+```
+
+**Solution:** Ensure your environment variable is set correctly:
+
+```typescript
+if (!process.env.GEMINI_API_KEY) {
+  throw new Error("GEMINI_API_KEY environment variable is required");
+}
+```
+
+### Rate Limit Errors
+
+```
+Error: 429 Too Many Requests
+```
+
+**Solution:** Configure retry logic and backup models:
+
+```typescript
+const provider = new OpenAIProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: "gpt-5",
+  backupModels: ["gpt-5-mini"], // Fallback to cheaper model
+  retryConfig: {
+    retries: 5, // More retries
+    timeout: 90000, // Longer timeout
+  },
+});
+```
+
+### Timeout Errors
+
+```
+Error: Operation timed out after 60000ms
+```
+
+**Solution:** Increase timeout or reduce max tokens:
+
+```typescript
+const provider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
+  config: {
+    // No max_tokens parameter needed for Gemini
+  },
+  retryConfig: {
+    timeout: 120000, // 2 minutes
+  },
+});
+```
+
+---
+
+## Next Steps
+
+- 📖 [Getting Started](./GETTING_STARTED.md) - Build your first agent
+- 🔧 [API Reference](./API_REFERENCE.md) - Full API documentation
+- 📝 [Examples](../examples/) - Real-world examples

package/docs/PUBLISHING.md

@@ -0,0 +1,174 @@
+# Publishing Guide
+
+## Pre-publish Checklist
+
+### 1. Build and Test
+```bash
+# Clean previous builds
+rm -rf dist/
+
+# Build the package
+bun run build
+
+# Verify types and linting
+bun typecheck
+bun lint
+
+# Test the build (optional - create a test project)
+npm pack
+# This creates a .tgz file you can test locally
+```
+
+### 2. Version Management
+
+Update version in `package.json`:
+```json
+{
+  "version": "0.1.0"  // Follow semver: major.minor.patch
+}
+```
+
+**Semver Guidelines:**
+- **Patch** (0.1.X): Bug fixes, documentation updates
+- **Minor** (0.X.0): New features, backwards compatible
+- **Major** (X.0.0): Breaking changes
+
+### 3. Verify Package Contents
+
+```bash
+# Dry run to see what will be published
+npm publish --dry-run
+
+# Check the files that will be included
+npm pack --dry-run
+```
+
+Should include:
+- ✅ `dist/` - Compiled JavaScript + type definitions
+- ✅ `docs/` - Documentation
+- ✅ `examples/` - Example files
+- ✅ `README.md` - Package documentation
+- ✅ `LICENSE` - MIT license
+
+Should NOT include:
+- ❌ `src/*.ts` source files (only .d.ts)
+- ❌ `node_modules/`
+- ❌ Development configs
+
+## Publishing to npm
+
+### First Time Setup
+
+```bash
+# Login to npm (one time)
+npm login
+# Enter your npm credentials
+```
+
+### Publish
+
+```bash
+# Make sure you're on main/master
+git checkout main
+git pull
+
+# Ensure everything is committed
+git status
+
+# Build
+bun run build
+
+# Publish to npm with public access
+npm publish --access public
+
+# Or if you want to test first, use a tag
+npm publish --tag beta --access public
+```
+
+### After Publishing
+
+```bash
+# Tag the release in git
+git tag v0.1.0
+git push origin v0.1.0
+
+# Verify on npm
+npm view @falai/agent
+```
+
+## Post-Publish
+
+1. **Update GitHub Release**
+   - Go to https://github.com/gusnips/falai/releases
+   - Create a new release for the tag
+   - Add release notes
+
+2. **Verify Installation**
+   ```bash
+   # In a new project
+   npm install @falai/agent
+   # or
+   bun add @falai/agent
+   ```
+
+3. **Test the Published Package**
+   ```bash
+   # Create test project
+   mkdir test-agent && cd test-agent
+   bun init -y
+   bun add @falai/agent
+   
+   # Try importing
+   echo 'import { Agent } from "@falai/agent"; console.log(Agent);' > test.ts
+   bun run test.ts
+   ```
+
+## Troubleshooting
+
+### "You do not have permission to publish"
+- Make sure you're logged in: `npm whoami`
+- Verify you have access to the `@falai` scope
+- Contact scope owner if needed
+
+### "Package already exists"
+- You can't republish the same version
+- Bump version in `package.json` and try again
+
+### "Missing required files"
+- Check `package.json` `files` field
+- Ensure `dist/` exists after build
+- Run `npm pack --dry-run` to preview
+
+### Types not working
+- Verify `types` field in `package.json`
+- Ensure `.d.ts` files are in `dist/`
+- Check `tsconfig.json` has `"declaration": true`
+
+## Version History
+
+- **0.1.0** - Initial release
+  - Core agent framework
+  - Route DSL
+  - Gemini provider
+  - Full TypeScript support
+  - Declarative configuration
+
+## Useful Commands
+
+```bash
+# Check what version is published
+npm view @falai/agent version
+
+# See all published versions
+npm view @falai/agent versions
+
+# Unpublish a version (within 24 hours, use carefully!)
+npm unpublish @falai/agent@0.1.0
+
+# Deprecate a version (preferred over unpublish)
+npm deprecate @falai/agent@0.1.0 "This version has been deprecated. Please upgrade to 0.2.0"
+```
+
+---
+
+**Made with ❤️ for the community**

package/docs/README.md

@@ -0,0 +1,68 @@
+# Documentation
+
+Welcome to the `@falai/agent` documentation!
+
+## 📖 Documentation Structure
+
+### Getting Started
+
+- **[Getting Started Guide](./GETTING_STARTED.md)** - Build your first agent in 5 minutes
+
+### Core Concepts
+
+- **[Constructor Options](./CONSTRUCTOR_OPTIONS.md)** - Comprehensive guide to declarative vs fluent configuration
+- **[Package Structure](./STRUCTURE.md)** - Architecture and design principles
+
+### Reference
+
+- **[API Reference](./API_REFERENCE.md)** - Complete API documentation for all classes, methods, and types
+- **[AI Providers Guide](./PROVIDERS.md)** - Gemini, OpenAI, and custom providers
+- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to the project
+- **[Publishing Guide](./PUBLISHING.md)** - How to publish updates to npm
+
+## 🎯 Quick Links
+
+### By Use Case
+
+**First time here?**
+→ Start with [Getting Started](./GETTING_STARTED.md)
+
+**Building a complex agent?**
+→ Check [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
+
+**Need specific API details?**
+→ Browse the [API Reference](./API_REFERENCE.md)
+
+**Understanding the codebase?**
+→ Read [Package Structure](./STRUCTURE.md)
+
+### By Topic
+
+- **Agent Configuration**: [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
+- **Conversation Flows**: [API Reference - Routes](./API_REFERENCE.md#route)
+- **Tools & Functions**: [API Reference - Tools](./API_REFERENCE.md#definetool)
+- **Disambiguation**: [API Reference - Observations](./API_REFERENCE.md#observation)
+- **AI Providers**: [API Reference - GeminiProvider](./API_REFERENCE.md#geminiprovider)
+
+## 💡 Examples
+
+Check out the [`examples/`](../examples/) directory for complete, runnable examples:
+
+- **[Declarative Agent](../examples/declarative-agent.ts)** - Full constructor-based configuration
+- **[Travel Agent](../examples/travel-agent.ts)** - Complex multi-route travel booking system
+- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Disambiguation with observations
+
+## 🤝 Contributing
+
+Found an error in the docs? Want to add examples? See our [**Contributing Guide**](./CONTRIBUTING.md) for:
+
+- How to set up your development environment
+- Code style guidelines
+- Pull request process
+- Ways you can help
+
+We welcome all contributions - from typo fixes to new features!
+
+---
+
+**Made with ❤️ for the community**