@lantos1618/better-ui 0.2.3 → 0.3.1

package/README.md

@@ -1,262 +1,148 @@
-# 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 differentiator**: Unlike other AI tool libraries, Better UI includes **view integration** - tools can render their own results in UI.
 
-- **🚀 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)
+## Core Concepts
 
-Better UI seamlessly integrates with Vercel's AI SDK for building chat interfaces:
+### 1. Tool Definition
 
-### Basic Chat Integration
+```typescript
+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
+});
+```
 
-```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';
+### 2. Server Implementation
 
-// 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();
-  });
+The `.server()` method defines logic that runs on the server (API routes, server components):
 
-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();
-  });
+```typescript
+myTool.server(async ({ query }, ctx) => {
+  // Direct access to databases, secrets, file system
+  const results = await db.search(query);
+  return { results };
+});
+```
 
-// Convert to AI SDK format
-const tools = {
-  getWeather: weatherTool.toAISDKTool(),
-  getStockPrice: stockTool.toAISDKTool(),
-};
+### 3. Client Implementation (Optional)
 
-export async function POST(req: Request) {
-  const { messages } = await req.json();
+The `.client()` method defines what happens when called from the browser. If not specified, auto-fetches to `/api/tools/execute`.
 
-  const result = await streamText({
-    model: openai('gpt-4'),
-    messages: convertToCoreMessages(messages),
-    tools,
-    maxToolRoundtrips: 5,
+```typescript
+myTool.client(async ({ query }, ctx) => {
+  // Custom client logic: caching, optimistic updates, etc.
+  const cached = ctx.cache.get(query);
+  if (cached) return cached;
+
+  return ctx.fetch('/api/search', {
+    method: 'POST',
+    body: JSON.stringify({ query })
   });
-
-  return result.toDataStreamResponse();
-}
+});
 ```
 
-### React Chat Component
+### 4. View (Our Differentiator)
 
-```tsx
-// app/chat/page.tsx
-'use client';
+The `.view()` method defines how to render the tool's results:
 
-import { useChat } from 'ai/react';
-import { ToolExecutorProvider, ToolRenderer } from '@lantos1618/better-ui/client';
+```typescript
+myTool.view((data, { loading, error }) => {
+  if (loading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  return <Results items={data.results} />;
+});
+```
 
-export default function ChatPage() {
-  const { messages, input, handleInputChange, handleSubmit } = useChat();
+## Fluent Builder Alternative
 
-  return (
-    <ToolExecutorProvider tools={[weatherTool, stockTool]}>
-      <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>
-      </div>
-    </ToolExecutorProvider>
-  );
-}
+```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) }))
+  .view((data) => <ResultsList items={data.results} />);
 ```
 
-### Advanced Chat with Multiple Tools
+## React Usage
 
-```tsx
-// lib/ai-tools.ts
-import { aui } from '@lantos1618/better-ui';
-import { z } from 'zod';
+```typescript
+import { useTool } from '@lantos1618/better-ui';
 
-// 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>
-      ))}
+function WeatherWidget({ city }) {
+  const { data, loading, error, execute } = useTool(weather);
+
+  return (
+    <div>
+      <button onClick={() => execute({ city })}>Get Weather</button>
+      {loading && <Spinner />}
+      {error && <div>Error: {error.message}</div>}
+      {data && <weather.View data={data} />}
     </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} />
-  ));
+  );
+}
+
+// Or with auto-execution
+function WeatherWidget({ city }) {
+  const { data, loading } = useTool(weather, { city }, { auto: true });
+  return <weather.View data={data} loading={loading} />;
+}
 ```
 
-### Streaming with Tool Results
+## AI Integration
+
+### With Vercel AI SDK
 
-```tsx
-// app/api/chat/route.ts
+```typescript
 import { streamText } from 'ai';
 import { openai } from '@ai-sdk/openai';
 
@@ -267,15 +153,8 @@ export async function POST(req: Request) {
     model: openai('gpt-4'),
     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: weather.toAITool(),
+      search: search.toAITool(),
     },
   });
 
@@ -283,175 +162,112 @@ export async function POST(req: Request) {
 }
 ```
 
-## 🛠️ Pre-built Tools
-
-Better UI comes with a comprehensive set of pre-built tools:
+## API Reference
 
-### DOM Manipulation Tools
-- `clickTool` - Click elements on the page
-- `typeTool` - Type text into inputs
-- `scrollTool` - Scroll to elements
-- `selectTool` - Select dropdown options
+### `tool(config)` or `tool(name)`
 
-### API Tools
-- `fetchTool` - Make HTTP requests
-- `graphqlTool` - Execute GraphQL queries
+Create a new tool with object config or fluent builder.
 
-### Form Tools
-- `formGeneratorTool` - Create dynamic forms
-- `formValidatorTool` - Validate form data
-
-### Data Tools
-- `databaseQueryTool` - Query databases
-- `dataTransformTool` - Transform data structures
+```typescript
+// Object config
+const t = tool({
+  name: string,
+  description?: string,
+  input: ZodSchema,
+  output?: ZodSchema,
+  tags?: string[],
+  cache?: { ttl: number, key?: (input) => string },
+});
 
-### State Management
-- `stateManagerTool` - Manage application state
-- `localStorageTool` - Persist data locally
+// Fluent builder
+const t = tool('name')
+  .description(string)
+  .input(ZodSchema)
+  .output(ZodSchema)
+  .tags(...string[])
+  .cache({ ttl, key? });
+```
 
-## 📚 Full API Reference
+### `.server(handler)`
 
-### Core Builder Methods
+Define server-side implementation.
 
 ```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)
+t.server(async (input, ctx) => {
+  // ctx.env, ctx.headers, ctx.user, ctx.session available
+  return result;
+});
 ```
 
-### React Hooks & Components
-
-```tsx
-// Provider for tool execution
-<ToolExecutorProvider tools={tools}>
-  <App />
-</ToolExecutorProvider>
+### `.client(handler)`
 
-// Render tool results
-<ToolRenderer toolCall={toolCall} tool={tool} />
-
-// Hook for manual execution
-const executor = useToolExecutor();
-const result = await executor.execute(toolCall);
-
-// Hook for tool discovery
-const tools = useToolRegistry();
-const weatherTools = tools.getByTag('weather');
-```
-
-### AI Assistant Integration
+Define client-side implementation (optional).
 
 ```typescript
-import { createAIAssistant } from '@lantos1618/better-ui';
-
-const assistant = createAIAssistant({
-  model: 'gpt-4',
-  tools: [weatherTool, searchTool],
-  systemPrompt: 'You are a helpful assistant.',
+t.client(async (input, ctx) => {
+  // ctx.cache, ctx.fetch, ctx.optimistic available
+  return result;
 });
-
-const response = await assistant.chat('What\'s the weather in NYC?');
-```
-
-## 🏗️ Architecture
-
-```
-┌──────────────┐     ┌──────────────┐     ┌──────────────┐
-│   AI Model   │────▶│  AUI System  │────▶│   Your App   │
-│  (GPT, etc)  │     │              │     │              │
-└──────────────┘     └──────────────┘     └──────────────┘
-       │                    │                     │
-       ▼                    ▼                     ▼
-  Tool Calls         Tool Registry         Tool Execution
-                    Type Validation         React Rendering
-                   Client/Server Split      State Management
 ```
 
-## 🧪 Testing
-
-```bash
-# Run all tests
-npm test
-
-# Run with coverage
-npm run test:coverage
+### `.view(component)`
 
-# Type checking
-npm run type-check
+Define React component for rendering results.
 
-# Linting
-npm run lint
+```typescript
+t.view((data, { loading, error }) => <Component data={data} />);
 ```
 
-## 🚀 Deployment
-
-### Vercel Deployment
+### `useTool(tool, input?, options?)`
 
-```bash
-# Install Vercel CLI
-npm i -g vercel
-
-# Deploy
-vercel
+React hook for executing tools.
 
-# Deploy with environment variables
-vercel --env API_KEY=xxx
+```typescript
+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,      // Auto-execute on mount
+  onSuccess: (data) => {},
+  onError: (error) => {},
+});
 ```
 
-### Environment Variables
-
-```env
-# Required for AI features
-OPENAI_API_KEY=your_api_key
+## Project Structure
 
-# Optional
-DATABASE_URL=your_db_url
-REDIS_URL=your_redis_url
+```
+src/
+  tool.tsx          # Core tool() API
+  react/
+    useTool.ts      # React hook
+  index.ts          # Main exports
+
+app/
+  demo/             # Demo page
+  api/chat/         # Chat API route
+  api/tools/        # Tool execution API
+
+lib/
+  tools.tsx         # Example tool definitions
+
+docs/
+  API_V2.md         # Full API documentation
 ```
 
-## 📖 Examples
-
-Check out our example applications:
-
-- [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
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-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
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) for details.
-
-## 🙏 Acknowledgments
-
-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
-
-## 📞 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
+```
 
----
+## License
 
-Built with ❤️ by the Better UI team
+MIT