ai-site-pilot 0.3.0 → 0.4.1

package/README.md

@@ -5,91 +5,36 @@
 
 AI chat widget that can **control and navigate your website**. Unlike typical chatbots that just answer questions, Site Pilot can take actions—scroll to sections, open modals, filter content, and more.
 
+Works with any AI model (Gemini, GPT-4, Claude, Llama) via [OpenRouter](https://openrouter.ai).
+
 ## Features
 
 - 🎯 **Tool System** - Define custom actions the AI can take on your site
-- 🌊 **Streaming** - Real-time streaming responses with SSE
+- 🌊 **Streaming** - Real-time streaming responses
+- 🤖 **Any Model** - GPT-4, Claude, Gemini, Llama - just change one string
 - 🎤 **Speech** - Voice input and text-to-speech output
 - 🎨 **Themeable** - CSS variables for easy customization
 - 📱 **Responsive** - Works on all screen sizes
-- ⚡ **Vercel AI SDK** - Works with any LLM provider
-
-## How It Works
-
-The package provides the chat UI and streaming infrastructure. **You teach the AI about your specific site** through:
-
-1. **System Prompt** - Tell the AI what sections, data, and features exist on your site
-2. **Tool Definitions** - Define what actions the AI can take (filter, navigate, open modals)
-3. **Client Handlers** - Write the code that actually executes those actions
-
-```
-User: "Show me your mobile apps"
-         ↓
-   AI understands request
-         ↓
-   AI calls filter_by_category("Mobile") tool
-         ↓
-   Your handler receives the call
-         ↓
-   Your code filters the UI
-```
-
-The AI doesn't automatically know your site structure—you teach it via the system prompt. See the [complete example](#teaching-the-ai-your-site) below.
+- 🆓 **Free Tier** - Gemini 2.0 Flash is free on OpenRouter
 
 ## Installation
 
 ```bash
 npm install ai-site-pilot
-
-# Choose your backend (pick ONE):
-npm install @google/genai          # Gemini (recommended, no AI SDK needed)
-npm install ai @ai-sdk/google      # Vercel AI SDK with Gemini
-npm install ai @ai-sdk/openai      # Vercel AI SDK with OpenAI
 ```
 
 ## Quick Start
 
-### 1. Create the API Route
-
-**Option A: Gemini Direct (Recommended)** - No Vercel AI SDK needed!
-
-```typescript
-// app/api/chat/route.ts
-import { createGeminiHandler } from 'ai-site-pilot/api';
-import { defineTool } from 'ai-site-pilot/tools';
-
-const navigateTool = defineTool({
-  name: 'navigate',
-  description: 'Navigate to a section of the page',
-  parameters: {
-    type: 'object',
-    properties: {
-      section: {
-        type: 'string',
-        description: 'Section to navigate to',
-        enum: ['home', 'products', 'about', 'contact'],
-      },
-    },
-    required: ['section'],
-  },
-});
+### 1. Get an OpenRouter API Key
 
-export const POST = createGeminiHandler({
-  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
-  model: 'gemini-2.0-flash',
-  systemPrompt: `You are a helpful assistant for our website.
-You can navigate users to different sections using the navigate tool.`,
-  tools: [navigateTool],
-});
-```
+Sign up at [openrouter.ai](https://openrouter.ai) and get your API key.
 
-**Option B: Vercel AI SDK** - Works with any AI SDK provider
+### 2. Create the API Route
 
 ```typescript
 // app/api/chat/route.ts
-import { createChatHandler } from 'ai-site-pilot/api';
+import { createHandler } from 'ai-site-pilot/api';
 import { defineTool } from 'ai-site-pilot/tools';
-import { google } from '@ai-sdk/google';
 
 const navigateTool = defineTool({
   name: 'navigate',
@@ -107,15 +52,15 @@ const navigateTool = defineTool({
   },
 });
 
-export const POST = createChatHandler({
-  model: google('gemini-2.0-flash'),
+export const POST = createHandler({
+  model: 'google/gemini-2.0-flash-exp:free',  // Free! Or use any model
   systemPrompt: `You are a helpful assistant for our website.
 You can navigate users to different sections using the navigate tool.`,
   tools: [navigateTool],
 });
 ```
 
-### 2. Add the Component
+### 3. Add the Component
 
 ```tsx
 // app/layout.tsx or components/ChatWidget.tsx
@@ -144,88 +89,88 @@ export function ChatWidget() {
 }
 ```
 
-## API Reference
+### 4. Add Environment Variable
 
-### `<SitePilot />`
+```bash
+# .env.local
+OPENROUTER_API_KEY=sk-or-...
+```
 
-Main chat widget component.
+That's it!
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `apiEndpoint` | `string` | required | API endpoint for chat |
-| `theme` | `SitePilotTheme` | `{}` | Theme configuration |
-| `suggestions` | `Suggestion[]` | `[]` | Suggestion prompts |
-| `features` | `SitePilotFeatures` | `{}` | Feature toggles |
-| `onToolCall` | `(name, args) => void` | - | Tool call handler |
-| `defaultOpen` | `boolean` | `false` | Initial open state |
-| `placeholder` | `string` | `'Type a message...'` | Input placeholder |
-| `welcomeMessage` | `string` | `'Hi! I'm here to help...'` | Welcome message |
+## Available Models
 
-#### Theme Options
+Change the `model` string to use any model:
 
-```typescript
-interface SitePilotTheme {
-  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-  borderRadius?: number;
-
-  // Colors - all accept CSS color values (hex, rgb, hsl)
-  accentColor?: string;         // Primary accent '#f59e0b'
-  accentColorDark?: string;     // Gradient end '#d97706'
-  backgroundColor?: string;      // Panel background '#0F0720'
-  textColor?: string;           // Primary text '#ffffff'
-  textMutedColor?: string;      // Secondary text '#a1a1aa'
-  borderColor?: string;         // Border 'rgba(255,255,255,0.1)'
-  userMessageBg?: string;       // User message bubble
-  assistantMessageBg?: string;  // Assistant message bubble
-}
-```
+| Model | ID | Notes |
+|-------|-----|-------|
+| Gemini 2.0 Flash | `google/gemini-2.0-flash-exp:free` | **Free!** |
+| GPT-4o | `openai/gpt-4o` | Best overall |
+| Claude 3.5 Sonnet | `anthropic/claude-3.5-sonnet` | Best for coding |
+| Llama 3.1 70B | `meta-llama/llama-3.1-70b-instruct` | Open source |
 
-#### Feature Toggles
+See all models at [openrouter.ai/models](https://openrouter.ai/models)
 
-```typescript
-interface SitePilotFeatures {
-  speech?: boolean;      // Voice input (default: true)
-  tts?: boolean;         // Text-to-speech (default: true)
-  fullscreen?: boolean;  // Fullscreen mode (default: true)
-  suggestions?: boolean; // Show suggestions (default: true)
-}
-```
+## API Reference
 
-### `createGeminiHandler()`
+### `createHandler()`
 
-Factory for creating Next.js API route handlers using Gemini directly (no AI SDK needed).
+Creates a Next.js API route handler.
 
 ```typescript
-import { createGeminiHandler } from 'ai-site-pilot/api';
+import { createHandler } from 'ai-site-pilot/api';
 
-export const POST = createGeminiHandler({
-  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,  // Optional, uses env var by default
-  model: 'gemini-2.0-flash',                          // Default: gemini-2.0-flash
+export const POST = createHandler({
+  // Required
   systemPrompt: 'You are a helpful assistant...',
+
+  // Optional
+  apiKey: process.env.OPENROUTER_API_KEY,  // Uses env var by default
+  model: 'google/gemini-2.0-flash-exp:free',  // Default
   tools: [myTool1, myTool2],
   temperature: 0.7,
+  siteUrl: 'https://mysite.com',  // Shown in OpenRouter dashboard
+  siteName: 'My Site',
 });
 ```
 
-### `createChatHandler()`
-
-Factory for creating Next.js API route handlers using Vercel AI SDK.
+### `<SitePilot />`
 
-```typescript
-import { createChatHandler } from 'ai-site-pilot/api';
+Main chat widget component.
 
-export const POST = createChatHandler({
-  model: google('gemini-2.0-flash'),  // Any Vercel AI SDK model
-  systemPrompt: 'You are a helpful assistant...',
-  tools: [myTool1, myTool2],
-  temperature: 0.7,
-  maxTokens: 1000,
-});
+```tsx
+<SitePilot
+  apiEndpoint="/api/chat"
+  suggestions={[{ text: 'Help me', icon: '❓' }]}
+  onToolCall={(name, args) => { /* handle tool calls */ }}
+  theme={{ accent: 'pink' }}  // or accentColor: '#ec4899'
+  features={{ speech: true, tts: true }}
+  welcomeMessage="Hi! How can I help?"
+  placeholder="Type a message..."
+  defaultOpen={false}
+/>
 ```
 
+### Theme Presets
+
+Use the `accent` prop for easy theming:
+
+| Preset | Color |
+|--------|-------|
+| `amber` | Default orange/amber |
+| `pink` | Hot pink |
+| `blue` | Primary blue |
+| `green` | Emerald green |
+| `purple` | Violet purple |
+| `red` | Coral red |
+| `cyan` | Teal cyan |
+| `orange` | Bright orange |
+
+Or use `accentColor` with any hex color: `accentColor: '#8b5cf6'`
+
 ### `defineTool()`
 
-Helper for defining tools with type safety.
+Helper for defining tools.
 
 ```typescript
 import { defineTool } from 'ai-site-pilot/tools';
@@ -241,166 +186,21 @@ const searchTool = defineTool({
     },
     required: ['query'],
   },
-  handler: async ({ query, category }) => {
-    // Client-side handler (optional)
-    const results = await searchProducts(query, category);
-    displayResults(results);
-  },
 });
 ```
 
-### `useChat()`
-
-Hook for custom chat implementations.
-
-```typescript
-import { useChat } from 'ai-site-pilot/hooks';
-
-function MyCustomChat() {
-  const {
-    messages,
-    input,
-    setInput,
-    isLoading,
-    sendMessage,
-    clearMessages,
-  } = useChat({
-    apiEndpoint: '/api/chat',
-    onToolCall: (name, args) => {
-      // Handle tool calls
-    },
-  });
-
-  return (
-    // Your custom UI
-  );
-}
-```
-
-## Styling
-
-### CSS Variables
-
-Override these variables to customize the appearance:
-
-```css
-.pilot-container {
-  --pilot-accent-h: 38;       /* Hue */
-  --pilot-accent-s: 92%;      /* Saturation */
-  --pilot-accent-l: 50%;      /* Lightness */
-  --pilot-bg: #0F0720;        /* Background */
-  --pilot-text: #ffffff;       /* Text color */
-  --pilot-text-muted: #a1a1aa; /* Muted text */
-  --pilot-border: rgba(255, 255, 255, 0.1);
-  --pilot-radius: 24px;
-}
-```
-
-### Tailwind Integration
-
-If using Tailwind, you can extend your config:
-
-```javascript
-// tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        pilot: {
-          accent: 'hsl(var(--pilot-accent-h), var(--pilot-accent-s), var(--pilot-accent-l))',
-        },
-      },
-    },
-  },
-};
-```
-
-## Use Cases
-
-### E-commerce
-
-```typescript
-const tools = [
-  defineTool({
-    name: 'search_products',
-    description: 'Search product catalog',
-    parameters: { /* ... */ },
-  }),
-  defineTool({
-    name: 'add_to_cart',
-    description: 'Add item to shopping cart',
-    parameters: { /* ... */ },
-  }),
-  defineTool({
-    name: 'show_category',
-    description: 'Filter products by category',
-    parameters: { /* ... */ },
-  }),
-];
-```
-
-### Documentation Sites
-
-```typescript
-const tools = [
-  defineTool({
-    name: 'search_docs',
-    description: 'Search documentation',
-    parameters: { /* ... */ },
-  }),
-  defineTool({
-    name: 'navigate_to_page',
-    description: 'Go to a documentation page',
-    parameters: { /* ... */ },
-  }),
-];
-```
-
-### Portfolio Sites
-
-```typescript
-const tools = [
-  defineTool({
-    name: 'open_project',
-    description: 'Open project details modal',
-    parameters: { /* ... */ },
-  }),
-  defineTool({
-    name: 'filter_by_category',
-    description: 'Filter projects by category',
-    parameters: { /* ... */ },
-  }),
-];
-```
-
 ## Custom API Implementation
 
-If you need to implement your own API route (e.g., using a different AI provider), the widget expects Server-Sent Events (SSE) in this format:
-
-### SSE Streaming Format
+If you need to use a different AI provider, implement this SSE format:
 
 ```
 data: {"type":"text","content":"Hello, "}
-
 data: {"type":"text","content":"how can I help?"}
-
 data: {"type":"tool","name":"navigate","args":{"section":"products"}}
-
 data: {"type":"done"}
 ```
 
-#### Event Types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| `text` | Streaming text chunk | `{"type":"text","content":"Hello"}` |
-| `tool` | Tool/function call | `{"type":"tool","name":"navigate","args":{"section":"home"}}` |
-| `done` | Stream complete | `{"type":"done"}` |
-| `error` | Error occurred | `{"type":"error","message":"Something went wrong"}` |
-
-### SSE Utilities
-
-Use the built-in SSE helpers for custom implementations:
+Use the built-in SSE helpers:
 
 ```typescript
 import { createSSEEncoder, getSSEHeaders } from 'ai-site-pilot/api';
@@ -410,13 +210,8 @@ export async function POST(req: Request) {
 
   const stream = new ReadableStream({
     async start(controller) {
-      // Stream text
       controller.enqueue(sse.encodeText('Hello!'));
-
-      // Send tool call
       controller.enqueue(sse.encodeTool('navigate', { section: 'products' }));
-
-      // Done
       controller.enqueue(sse.encodeDone());
       controller.close();
     },
@@ -428,15 +223,14 @@ export async function POST(req: Request) {
 
 ## Handling Tool-Only Responses
 
-When the AI calls tools without providing text, you can customize the fallback message:
+When the AI calls tools without text, customize the fallback:
 
 ```typescript
 import { SitePilot, createFallbackMessageGenerator } from 'ai-site-pilot';
 
 const generateFallback = createFallbackMessageGenerator({
-  navigate: (args) => `Scrolled to **${args.section}** section.`,
-  filter_products: (args) => `Showing **${args.category}** products.`,
-  search: (args) => `Found results for "${args.query}".`,
+  navigate: (args) => `Scrolled to **${args.section}**.`,
+  filter: (args) => `Showing **${args.category}** items.`,
 });
 
 <SitePilot
@@ -449,9 +243,7 @@ const generateFallback = createFallbackMessageGenerator({
 
 - React 18+ or React 19
 - Next.js 13+ (for API routes)
-- One of:
-  - `@google/genai` (Gemini direct - recommended)
-  - `ai` + provider package (Vercel AI SDK)
+- OpenRouter API key (free at [openrouter.ai](https://openrouter.ai))
 
 ## License
 

package/dist/api/index.d.mts

@@ -1,66 +1,16 @@
-import { LanguageModel } from 'ai';
 import { T as ToolDefinition } from '../types--7jDyUM6.mjs';
-import { S as StreamEvent } from '../types-K00dDlBC.mjs';
+import { S as StreamEvent } from '../types-UmyDfs25.mjs';
 
 /**
- * Factory for creating Next.js API route handlers
+ * Universal chat handler using OpenRouter
+ * Works with any model: Gemini, GPT-4, Claude, Llama, etc.
+ * No SDK required - just standard fetch.
  */
 
-interface ChatHandlerConfig {
-    /** The AI model to use (from Vercel AI SDK) */
-    model: LanguageModel;
-    /** System prompt for the AI */
-    systemPrompt: string;
-    /** Tool definitions for the AI */
-    tools?: ToolDefinition[];
-    /** Temperature for response generation (0-1) */
-    temperature?: number;
-    /** Maximum tokens in response */
-    maxTokens?: number;
-}
-/**
- * Create a Next.js API route handler for chat
- *
- * Works with any Vercel AI SDK compatible model including:
- * - Google Gemini (@ai-sdk/google)
- * - OpenAI (@ai-sdk/openai)
- * - Anthropic (@ai-sdk/anthropic)
- * - And more...
- *
- * @example
- * ```ts
- * // app/api/chat/route.ts
- * import { createChatHandler } from 'ai-site-pilot/api';
- * import { google } from '@ai-sdk/google';
- *
- * export const POST = createChatHandler({
- *   model: google('gemini-2.0-flash'),
- *   systemPrompt: 'You are a helpful assistant...',
- *   tools: myTools,
- * });
- * ```
- *
- * @example Using OpenAI
- * ```ts
- * import { openai } from '@ai-sdk/openai';
- *
- * export const POST = createChatHandler({
- *   model: openai('gpt-4o'),
- *   systemPrompt: 'You are a helpful assistant...',
- * });
- * ```
- */
-declare function createChatHandler(config: ChatHandlerConfig): (req: Request) => Promise<Response>;
-
-/**
- * Gemini-specific handler using @google/genai directly
- * No Vercel AI SDK required!
- */
-
-interface GeminiHandlerConfig {
-    /** Google AI API key (or set GOOGLE_GENERATIVE_AI_API_KEY env var) */
+interface HandlerConfig {
+    /** OpenRouter API key (or set OPENROUTER_API_KEY env var) */
     apiKey?: string;
-    /** Gemini model to use (default: gemini-2.0-flash) */
+    /** Model to use (e.g., 'google/gemini-2.0-flash-exp:free', 'openai/gpt-4o', 'anthropic/claude-3.5-sonnet') */
     model?: string;
     /** System prompt for the AI */
     systemPrompt: string;
@@ -68,27 +18,33 @@ interface GeminiHandlerConfig {
     tools?: ToolDefinition[];
     /** Temperature for response generation (0-1) */
     temperature?: number;
+    /** Your site URL (shown in OpenRouter dashboard) */
+    siteUrl?: string;
+    /** Your app name (shown in OpenRouter dashboard) */
+    siteName?: string;
 }
 /**
- * Create a Next.js API route handler for Gemini
+ * Create a Next.js API route handler using OpenRouter
  *
- * Uses @google/genai directly - no Vercel AI SDK required!
- * Works with Gemini 2.0+ models.
+ * Works with any model - just change the model string:
+ * - 'google/gemini-2.0-flash-exp:free' (free!)
+ * - 'openai/gpt-4o'
+ * - 'anthropic/claude-3.5-sonnet'
+ * - 'meta-llama/llama-3.1-70b-instruct'
  *
  * @example
  * ```ts
  * // app/api/chat/route.ts
- * import { createGeminiHandler } from 'ai-site-pilot/api';
+ * import { createHandler } from 'ai-site-pilot/api';
  *
- * export const POST = createGeminiHandler({
- *   apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
- *   model: 'gemini-2.0-flash',
+ * export const POST = createHandler({
+ *   model: 'google/gemini-2.0-flash-exp:free',
  *   systemPrompt: 'You are a helpful assistant...',
  *   tools: myTools,
  * });
  * ```
  */
-declare function createGeminiHandler(config: GeminiHandlerConfig): (req: Request) => Promise<Response>;
+declare function createHandler(config: HandlerConfig): (req: Request) => Promise<Response>;
 
 /**
  * SSE streaming utilities
@@ -113,4 +69,4 @@ declare function getSSEHeaders(): HeadersInit;
  */
 declare function parseSSEStream(reader: ReadableStreamDefaultReader<Uint8Array>): AsyncGenerator<StreamEvent>;
 
-export { type ChatHandlerConfig, type GeminiHandlerConfig, createChatHandler, createGeminiHandler, createSSEEncoder, getSSEHeaders, parseSSEStream };
+export { type HandlerConfig, createHandler, createSSEEncoder, getSSEHeaders, parseSSEStream };