@lantos1618/better-ui 0.2.3 → 0.4.0

package/README.md

@@ -1,457 +1,374 @@
-# Better UI - AUI (Assistant-UI) System
+# Better UI
 
-> A powerful, type-safe tool system for Next.js that enables AI assistants to control both frontend and backend operations through a fluent API.
+> A minimal, type-safe AI-first UI framework for building tools
 
 [![npm version](https://img.shields.io/npm/v/@lantos1618/better-ui.svg)](https://www.npmjs.com/package/@lantos1618/better-ui)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
-[![Next.js](https://img.shields.io/badge/Next.js-15.5-black)](https://nextjs.org/)
 
-## 🎯 What is Better UI?
+## What is Better UI?
 
-Better UI is an **AI-first UI framework** that revolutionizes how AI assistants interact with web applications. It provides a clean, type-safe abstraction layer that allows AI models to execute both frontend and backend operations seamlessly.
+Better UI provides a clean, fluent API for creating tools that AI assistants can execute. Define input/output schemas with Zod, implement server and client logic separately, and render results with React components.
 
-### Key Benefits
+**Key differentiators**:
+- **View integration** - tools render their own results in UI (no other framework does this)
+- **Multi-provider support** - OpenAI, Anthropic, Google Gemini, OpenRouter
+- **Streaming tool views** - progressive partial data rendering
+- **Pre-made chat components** - drop-in `<Chat />` with automatic tool view rendering
+- **Server infrastructure** - rate limiting, caching, Next.js/Express adapters
 
-- **🚀 Minimal Boilerplate**: Create powerful tools with just 2 required methods
-- **🔒 Type Safety**: Full TypeScript + Zod schema validation
-- **🎨 AI-Native**: Built specifically for AI assistants to control applications
-- **⚡ Performance**: Smart client-side caching and optimization
-- **🔧 Extensible**: Easy to create custom tools for any use case
-
-## 📦 Installation
+## Installation
 
 ```bash
-npm install @lantos1618/better-ui
-# or
-yarn add @lantos1618/better-ui
-# or
-bun add @lantos1618/better-ui
+npm install @lantos1618/better-ui zod
 ```
 
-## 🚀 Quick Start
-
-### 1. Simple Tool (2 methods only!)
+## Quick Start
 
-```tsx
-import { aui } from '@lantos1618/better-ui';
+```typescript
+import { tool } from '@lantos1618/better-ui';
 import { z } from 'zod';
 
-const weatherTool = aui
-  .tool('weather')
-  .input(z.object({ city: z.string() }))
-  .execute(async ({ input }) => ({ temp: 72, city: input.city }))
-  .render(({ data }) => <div>{data.city}: {data.temp}°</div>);
-```
+const weather = tool({
+  name: 'weather',
+  description: 'Get weather for a city',
+  input: z.object({ city: z.string() }),
+  output: z.object({ temp: z.number(), condition: z.string() }),
+});
 
-### 2. Advanced Tool with Client Optimization
+// Server implementation (runs on server)
+weather.server(async ({ city }) => {
+  const data = await weatherAPI.get(city);
+  return { temp: data.temp, condition: data.condition };
+});
 
-```tsx
-const searchTool = aui
-  .tool('search')
-  .input(z.object({ query: z.string() }))
-  .execute(async ({ input }) => db.search(input.query))
-  .clientExecute(async ({ input, ctx }) => {
-    // Optional: Add caching, offline support, optimistic updates
-    const cached = ctx.cache.get(input.query);
-    return cached || ctx.fetch('/api/tools/search', { body: input });
-  })
-  .render(({ data }) => <SearchResults results={data} />);
+// View for rendering results (our differentiator!)
+weather.view((data) => (
+  <div className="weather-card">
+    <span>{data.temp}</span>
+    <span>{data.condition}</span>
+  </div>
+));
 ```
 
-## 💻 AI SDK Integration (Vercel AI SDK)
-
-Better UI seamlessly integrates with Vercel's AI SDK for building chat interfaces:
-
-### Basic Chat Integration
+## Drop-in Chat UI
 
 ```tsx
-// app/api/chat/route.ts
-import { openai } from '@ai-sdk/openai';
-import { streamText, convertToCoreMessages } from 'ai';
-import { aui } from '@lantos1618/better-ui';
-import { z } from 'zod';
-
-// Define your tools
-const weatherTool = aui
-  .tool('getWeather')
-  .description('Get current weather for a city')
-  .input(z.object({ 
-    city: z.string().describe('City name'),
-    unit: z.enum(['celsius', 'fahrenheit']).optional() 
-  }))
-  .execute(async ({ input }) => {
-    // Fetch real weather data
-    const response = await fetch(`https://api.weather.com/v1/weather?city=${input.city}`);
-    return response.json();
-  });
-
-const stockTool = aui
-  .tool('getStockPrice')
-  .description('Get current stock price')
-  .input(z.object({ 
-    symbol: z.string().describe('Stock symbol (e.g., AAPL)') 
-  }))
-  .execute(async ({ input }) => {
-    const response = await fetch(`https://api.stocks.com/v1/quote/${input.symbol}`);
-    return response.json();
-  });
-
-// Convert to AI SDK format
-const tools = {
-  getWeather: weatherTool.toAISDKTool(),
-  getStockPrice: stockTool.toAISDKTool(),
-};
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const result = await streamText({
-    model: openai('gpt-4'),
-    messages: convertToCoreMessages(messages),
-    tools,
-    maxToolRoundtrips: 5,
-  });
+import { Chat } from '@lantos1618/better-ui/components';
 
-  return result.toDataStreamResponse();
+function App() {
+  return (
+    <Chat
+      endpoint="/api/chat"
+      tools={{ weather, search, counter }}
+      className="h-[600px]"
+      placeholder="Ask something..."
+    />
+  );
 }
 ```
 
-### React Chat Component
+Or compose your own layout:
 
 ```tsx
-// app/chat/page.tsx
-'use client';
-
-import { useChat } from 'ai/react';
-import { ToolExecutorProvider, ToolRenderer } from '@lantos1618/better-ui/client';
-
-export default function ChatPage() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat();
+import { ChatProvider, Thread, Composer } from '@lantos1618/better-ui/components';
 
+function App() {
   return (
-    <ToolExecutorProvider tools={[weatherTool, stockTool]}>
+    <ChatProvider endpoint="/api/chat" tools={tools}>
       <div className="flex flex-col h-screen">
-        <div className="flex-1 overflow-y-auto p-4">
-          {messages.map((message) => (
-            <div key={message.id} className="mb-4">
-              <div className="font-bold">{message.role}:</div>
-              <div>{message.content}</div>
-              
-              {/* Render tool calls with Better UI */}
-              {message.toolInvocations?.map((toolCall) => (
-                <ToolRenderer 
-                  key={toolCall.toolCallId}
-                  toolCall={toolCall}
-                  tool={tools[toolCall.toolName]}
-                />
-              ))}
-            </div>
-          ))}
-        </div>
-        
-        <form onSubmit={handleSubmit} className="p-4 border-t">
-          <input
-            value={input}
-            onChange={handleInputChange}
-            placeholder="Ask about weather or stocks..."
-            className="w-full p-2 border rounded"
-          />
-        </form>
+        <Thread className="flex-1 overflow-y-auto" />
+        <Composer placeholder="Type a message..." />
       </div>
-    </ToolExecutorProvider>
+    </ChatProvider>
   );
 }
 ```
 
-### Advanced Chat with Multiple Tools
+Tool results in chat automatically render using the tool's `.view()` component.
 
-```tsx
-// lib/ai-tools.ts
-import { aui } from '@lantos1618/better-ui';
-import { z } from 'zod';
+## Multi-Provider Support
 
-// Database search tool
-export const searchDatabaseTool = aui
-  .tool('searchDatabase')
-  .description('Search internal database')
-  .input(z.object({
-    query: z.string(),
-    filters: z.object({
-      category: z.string().optional(),
-      dateRange: z.object({
-        start: z.string().optional(),
-        end: z.string().optional(),
-      }).optional(),
-    }).optional(),
-  }))
-  .execute(async ({ input }) => {
-    // Your database logic
-    return await db.search(input.query, input.filters);
-  })
-  .clientExecute(async ({ input, ctx }) => {
-    // Client-side caching
-    const cacheKey = JSON.stringify(input);
-    const cached = ctx.cache.get(cacheKey);
-    if (cached && Date.now() - cached.timestamp < 60000) {
-      return cached.data;
-    }
-    
-    const result = await ctx.fetch('/api/search', { 
-      method: 'POST',
-      body: JSON.stringify(input)
-    });
-    
-    ctx.cache.set(cacheKey, { data: result, timestamp: Date.now() });
-    return result;
-  })
-  .render(({ data }) => (
-    <div className="grid gap-2">
-      {data.results.map((item) => (
-        <div key={item.id} className="p-2 border rounded">
-          <h3>{item.title}</h3>
-          <p>{item.description}</p>
-        </div>
-      ))}
-    </div>
-  ));
-
-// Chart generation tool
-export const createChartTool = aui
-  .tool('createChart')
-  .description('Generate interactive charts')
-  .input(z.object({
-    type: z.enum(['line', 'bar', 'pie', 'scatter']),
-    data: z.array(z.object({
-      label: z.string(),
-      value: z.number(),
-    })),
-    title: z.string().optional(),
-  }))
-  .execute(async ({ input }) => input)
-  .render(({ data }) => (
-    <ChartComponent type={data.type} data={data.data} title={data.title} />
-  ));
-
-// Form generation tool
-export const generateFormTool = aui
-  .tool('generateForm')
-  .description('Create dynamic forms')
-  .input(z.object({
-    fields: z.array(z.object({
-      name: z.string(),
-      type: z.enum(['text', 'number', 'email', 'select', 'checkbox']),
-      label: z.string(),
-      required: z.boolean().optional(),
-      options: z.array(z.string()).optional(),
-    })),
-    submitUrl: z.string(),
-  }))
-  .execute(async ({ input }) => input)
-  .render(({ data }) => (
-    <DynamicForm fields={data.fields} submitUrl={data.submitUrl} />
-  ));
+```typescript
+import { createProvider } from '@lantos1618/better-ui';
+
+// OpenAI
+const provider = createProvider({ provider: 'openai', model: 'gpt-4o' });
+
+// Anthropic
+const provider = createProvider({ provider: 'anthropic', model: 'claude-4-sonnet' });
+
+// Google Gemini
+const provider = createProvider({ provider: 'google', model: 'gemini-2.5-pro' });
+
+// OpenRouter (access any model)
+const provider = createProvider({
+  provider: 'openrouter',
+  model: 'anthropic/claude-4-sonnet',
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
 ```
 
-### Streaming with Tool Results
+Use with the chat handler:
 
-```tsx
-// app/api/chat/route.ts
-import { streamText } from 'ai';
-import { openai } from '@ai-sdk/openai';
+```typescript
+import { streamText, convertToModelMessages } from 'ai';
+import { createProvider } from '@lantos1618/better-ui';
+
+const provider = createProvider({ provider: 'openai', model: 'gpt-4o' });
 
 export async function POST(req: Request) {
   const { messages } = await req.json();
-
-  const result = await streamText({
-    model: openai('gpt-4'),
-    messages,
+  const result = streamText({
+    model: provider.model(),
+    messages: convertToModelMessages(messages),
     tools: {
-      searchDatabase: searchDatabaseTool.toAISDKTool(),
-      createChart: createChartTool.toAISDKTool(),
-      generateForm: generateFormTool.toAISDKTool(),
-    },
-    toolChoice: 'auto', // Let AI decide when to use tools
-    async onToolCall({ toolCall, toolResult }) {
-      // Log tool usage for analytics
-      console.log(`Tool ${toolCall.toolName} called with:`, toolCall.args);
-      console.log(`Result:`, toolResult);
+      weather: weatherTool.toAITool(),
     },
   });
-
-  return result.toDataStreamResponse();
+  return result.toUIMessageStreamResponse();
 }
 ```
 
-## 🛠️ Pre-built Tools
+## Streaming Tool Views
 
-Better UI comes with a comprehensive set of pre-built tools:
+Tools can stream partial results progressively:
 
-### DOM Manipulation Tools
-- `clickTool` - Click elements on the page
-- `typeTool` - Type text into inputs
-- `scrollTool` - Scroll to elements
-- `selectTool` - Select dropdown options
+```typescript
+import { useToolStream } from '@lantos1618/better-ui';
 
-### API Tools
-- `fetchTool` - Make HTTP requests
-- `graphqlTool` - Execute GraphQL queries
+// Define a streaming tool
+const analysis = tool({
+  name: 'analysis',
+  input: z.object({ query: z.string() }),
+  output: z.object({ summary: z.string(), score: z.number() }),
+});
 
-### Form Tools
-- `formGeneratorTool` - Create dynamic forms
-- `formValidatorTool` - Validate form data
+analysis.stream(async ({ query }, { stream }) => {
+  stream({ summary: 'Analyzing...' });       // Partial update
+  const result = await analyzeData(query);
+  stream({ summary: result.summary });        // More data
+  return { summary: result.summary, score: result.score }; // Final
+});
 
-### Data Tools
-- `databaseQueryTool` - Query databases
-- `dataTransformTool` - Transform data structures
+// In a component:
+function AnalysisWidget({ query }) {
+  const { data, streaming, loading, execute } = useToolStream(analysis);
 
-### State Management
-- `stateManagerTool` - Manage application state
-- `localStorageTool` - Persist data locally
+  return (
+    <div>
+      <button onClick={() => execute({ query })}>Analyze</button>
+      {loading && <p>Starting...</p>}
+      {streaming && <p>Streaming: {data?.summary}</p>}
+      {data?.score && <p>Score: {data.score}</p>}
+    </div>
+  );
+}
+```
 
-## 📚 Full API Reference
+## Core Concepts
 
-### Core Builder Methods
+### 1. Tool Definition
 
 ```typescript
-aui
-  .tool(name: string)                    // Create tool with name
-  .description(text: string)              // Add description (for AI)
-  .tags(...tags: string[])               // Add tags for discovery
-  .input(schema: ZodSchema)              // Input validation schema
-  .execute(handler: ExecuteHandler)      // Server-side logic (required)
-  .clientExecute(handler: ClientHandler) // Client-side logic (optional)
-  .render(component: RenderFunction)     // React component (optional)
-  .stream(handler: StreamHandler)        // Streaming support (optional)
+const myTool = tool({
+  name: 'myTool',
+  description: 'What this tool does',
+  input: z.object({ /* input schema */ }),
+  output: z.object({ /* output schema */ }),
+  tags: ['category', 'type'],
+  cache: { ttl: 60000 }, // optional caching
+});
 ```
 
-### React Hooks & Components
-
-```tsx
-// Provider for tool execution
-<ToolExecutorProvider tools={tools}>
-  <App />
-</ToolExecutorProvider>
-
-// Render tool results
-<ToolRenderer toolCall={toolCall} tool={tool} />
+### 2. Server Implementation
 
-// Hook for manual execution
-const executor = useToolExecutor();
-const result = await executor.execute(toolCall);
+The `.server()` method defines logic that runs on the server (API routes, server components):
 
-// Hook for tool discovery
-const tools = useToolRegistry();
-const weatherTools = tools.getByTag('weather');
+```typescript
+myTool.server(async ({ query }, ctx) => {
+  // Direct access to databases, secrets, file system
+  const results = await db.search(query);
+  return { results };
+});
 ```
 
-### AI Assistant Integration
+### 3. Client Implementation (Optional)
+
+The `.client()` method defines what happens when called from the browser. If not specified, auto-fetches to `/api/tools/execute`.
 
 ```typescript
-import { createAIAssistant } from '@lantos1618/better-ui';
+myTool.client(async ({ query }, ctx) => {
+  const cached = ctx.cache.get(query);
+  if (cached) return cached;
 
-const assistant = createAIAssistant({
-  model: 'gpt-4',
-  tools: [weatherTool, searchTool],
-  systemPrompt: 'You are a helpful assistant.',
+  return ctx.fetch('/api/search', {
+    method: 'POST',
+    body: JSON.stringify({ query })
+  });
 });
-
-const response = await assistant.chat('What\'s the weather in NYC?');
 ```
 
-## 🏗️ Architecture
+### 4. View (Our Differentiator)
 
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│   AI Model   │────▶│  AUI System  │────▶│   Your App   │
-│  (GPT, etc)  │     │              │     │              │
-└──────────────┘     └──────────────┘     └──────────────┘
-       │                    │                     │
-       ▼                    ▼                     ▼
-  Tool Calls         Tool Registry         Tool Execution
-                    Type Validation         React Rendering
-                   Client/Server Split      State Management
+The `.view()` method defines how to render the tool's results:
+
+```typescript
+myTool.view((data, { loading, error, streaming }) => {
+  if (loading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  if (streaming) return <PartialResults data={data} />;
+  return <Results items={data.results} />;
+});
 ```
 
-## 🧪 Testing
+### 5. Streaming
 
-```bash
-# Run all tests
-npm test
+The `.stream()` method enables progressive partial updates:
 
-# Run with coverage
-npm run test:coverage
+```typescript
+myTool.stream(async ({ query }, { stream }) => {
+  stream({ status: 'searching...' });
+  const results = await search(query);
+  stream({ results, status: 'done' });
+  return { results, status: 'done', count: results.length };
+});
+```
 
-# Type checking
-npm run type-check
+## Fluent Builder Alternative
 
-# Linting
-npm run lint
+```typescript
+const search = tool('search')
+  .description('Search the database')
+  .input(z.object({ query: z.string() }))
+  .output(z.object({ results: z.array(z.string()) }))
+  .server(async ({ query }) => ({ results: await db.search(query) }))
+  .stream(async ({ query }, { stream }) => {
+    stream({ results: [] });
+    const results = await db.search(query);
+    return { results };
+  })
+  .view((data) => <ResultsList items={data.results} />);
 ```
 
-## 🚀 Deployment
+## React Hooks
 
-### Vercel Deployment
+### `useTool(tool, input?, options?)`
 
-```bash
-# Install Vercel CLI
-npm i -g vercel
+```typescript
+import { useTool } from '@lantos1618/better-ui';
+
+const {
+  data,      // Result data
+  loading,   // Loading state
+  error,     // Error if any
+  execute,   // Execute function
+  reset,     // Reset state
+  executed,  // Has been executed
+} = useTool(myTool, initialInput, {
+  auto: false,
+  onSuccess: (data) => {},
+  onError: (error) => {},
+});
+```
 
-# Deploy
-vercel
+### `useToolStream(tool, options?)`
 
-# Deploy with environment variables
-vercel --env API_KEY=xxx
+```typescript
+import { useToolStream } from '@lantos1618/better-ui';
+
+const {
+  data,       // Progressive partial data
+  finalData,  // Complete validated data (when done)
+  streaming,  // True while receiving partial updates
+  loading,    // True before first chunk
+  error,
+  execute,
+  reset,
+} = useToolStream(myTool);
 ```
 
-### Environment Variables
+### `useTools(tools, options?)`
 
-```env
-# Required for AI features
-OPENAI_API_KEY=your_api_key
+```typescript
+import { useTools } from '@lantos1618/better-ui';
 
-# Optional
-DATABASE_URL=your_db_url
-REDIS_URL=your_redis_url
-```
+const tools = useTools({ weather, search });
 
-## 📖 Examples
+await tools.weather.execute({ city: 'London' });
+await tools.search.execute({ query: 'restaurants' });
 
-Check out our example applications:
+tools.weather.data;    // Weather result
+tools.search.loading;  // Search loading state
+```
 
-- [Chat Application](./examples/chat-app) - Full chat UI with tool execution
-- [Dashboard](./examples/dashboard) - Analytics dashboard with AI controls
-- [Form Builder](./examples/form-builder) - Dynamic form generation
-- [Data Explorer](./examples/data-explorer) - Database exploration tool
+## Chat Components
 
-## 🤝 Contributing
+Import from `@lantos1618/better-ui/components`:
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+| Component | Description |
+|-----------|-------------|
+| `Chat` | All-in-one chat component (ChatProvider + Thread + Composer) |
+| `ChatProvider` | Context provider wrapping AI SDK's `useChat` |
+| `Thread` | Message list with auto-scroll |
+| `Message` | Single message with automatic tool view rendering |
+| `Composer` | Input form with send button |
+| `ToolResult` | Renders a tool's `.View` in chat context |
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+All components accept `className` for styling customization.
 
-## 📄 License
+## Providers
 
-MIT License - see [LICENSE](LICENSE) for details.
+| Provider | Package Required | Example Model |
+|----------|-----------------|---------------|
+| OpenAI | `@ai-sdk/openai` (included) | `gpt-4o`, `gpt-5.2` |
+| Anthropic | `@ai-sdk/anthropic` (optional) | `claude-4-sonnet` |
+| Google | `@ai-sdk/google` (optional) | `gemini-2.5-pro` |
+| OpenRouter | `@ai-sdk/openai` (included) | `anthropic/claude-4-sonnet` |
+
+```bash
+# Optional providers
+npm install @ai-sdk/anthropic  # For Anthropic
+npm install @ai-sdk/google     # For Google Gemini
+```
 
-## 🙏 Acknowledgments
+## Project Structure
 
-Built with:
-- [Next.js](https://nextjs.org/) - The React framework
-- [TypeScript](https://www.typescriptlang.org/) - Type safety
-- [Zod](https://zod.dev/) - Schema validation
-- [Vercel AI SDK](https://sdk.vercel.ai/) - AI integration
+```
+src/
+  tool.tsx            # Core tool() API with streaming
+  react/
+    useTool.ts        # React hooks (useTool, useTools)
+    useToolStream.ts  # Streaming hook
+  components/
+    Chat.tsx          # All-in-one chat component
+    ChatProvider.tsx   # Chat context provider
+    Thread.tsx        # Message list
+    Message.tsx       # Single message
+    Composer.tsx      # Input form
+    ToolResult.tsx    # Tool view renderer
+  providers/
+    openai.ts         # OpenAI adapter
+    anthropic.ts      # Anthropic adapter
+    google.ts         # Google Gemini adapter
+    openrouter.ts     # OpenRouter adapter
+  adapters/
+    nextjs.ts         # Next.js route handlers
+    express.ts        # Express middleware
+  index.ts            # Main exports
+```
 
-## 📞 Support
+## Development
 
-- [GitHub Issues](https://github.com/lantos1618/better-ui/issues)
-- [Documentation](https://docs.better-ui.dev)
-- Email: support@better-ui.dev
+```bash
+npm install
+npm run dev          # Run dev server
+npm run build:lib    # Build library
+npm run build        # Build everything
+npm run type-check   # TypeScript check
+npm test             # Run tests
+```
 
----
+## License
 
-Built with ❤️ by the Better UI team
+MIT