@lantos1618/better-ui 0.2.2 → 0.3.1

package/README.md

@@ -1,190 +1,273 @@
-# Better UI - AUI (Assistant-UI) System
+# Better UI
 
-A concise and elegant tool system for Next.js that enables AI assistants to control both frontend and backend through a fluent API.
+> A minimal, type-safe AI-first UI framework for building tools
 
-## 🚀 Quick Start
+[![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/)
 
-```tsx
-// Simple tool - just 2 methods
-const simpleTool = 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>);
+## What is Better UI?
 
-// Complex tool - adds client optimization
-const complexTool = aui
-  .tool('search')
-  .input(z.object({ query: z.string() }))
-  .execute(async ({ input }) => db.search(input.query))
-  .clientExecute(async ({ input, ctx }) => {
-    // Only when you need caching, offline, etc.
-    const cached = ctx.cache.get(input.query);
-    return cached || ctx.fetch('/api/tools/search', { body: input });
-  })
-  .render(({ data }) => <SearchResults results={data} />);
-```
+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.
 
-## ✨ Features
+**Key differentiator**: Unlike other AI tool libraries, Better UI includes **view integration** - tools can render their own results in UI.
 
-- **Fluent API**: Chain methods for clean, readable tool definitions
-- **Type Safety**: Full TypeScript support with Zod schemas
-- **Minimal Boilerplate**: Only `input()` and `execute()` are required
-- **Dual Execution**: Server-side execution with optional client-side optimization
-- **React Integration**: Seamless rendering of tool results
-- **AI-Ready**: Designed for AI assistants to control UI/backend
+## Installation
 
-## 🏗️ Architecture
+```bash
+npm install @lantos1618/better-ui zod
+```
 
+## Quick Start
+
+```typescript
+import { tool } from '@lantos1618/better-ui';
+import { z } from 'zod';
+
+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() }),
+});
+
+// Server implementation (runs on server)
+weather.server(async ({ city }) => {
+  const data = await weatherAPI.get(city);
+  return { temp: data.temp, condition: data.condition };
+});
+
+// View for rendering results (our differentiator!)
+weather.view((data) => (
+  <div className="weather-card">
+    <span>{data.temp}°</span>
+    <span>{data.condition}</span>
+  </div>
+));
 ```
-┌─────────────┐     ┌──────────────┐     ┌─────────────┐
-│   Client    │────▶│  AUI System  │────▶│   Server    │
-│  Component  │     │              │     │   Handler   │
-└─────────────┘     └──────────────┘     └─────────────┘
-       │                    │                     │
-       ▼                    ▼                     ▼
-  ToolRenderer     ClientExecutor         ToolExecutor
-                    (optional)            (server-side)
+
+## Core Concepts
+
+### 1. Tool Definition
+
+```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
+});
 ```
 
-## 📦 Installation
+### 2. Server Implementation
 
-```bash
-npm install
-npm run dev
+The `.server()` method defines logic that runs on the server (API routes, server components):
+
+```typescript
+myTool.server(async ({ query }, ctx) => {
+  // Direct access to databases, secrets, file system
+  const results = await db.search(query);
+  return { results };
+});
 ```
 
-## 🛠️ API Reference
+### 3. Client Implementation (Optional)
 
-### Tool Builder
+The `.client()` method defines what happens when called from the browser. If not specified, auto-fetches to `/api/tools/execute`.
 
-- `.tool(name)` - Create a new tool builder
-- `.input(schema)` - Define input validation with Zod
-- `.execute(handler)` - Server-side execution logic
-- `.clientExecute(handler)` - Optional client-side execution
-- `.render(component)` - React component for rendering results
-- `.description(text)` - Optional tool description
-- Returns a built tool object ready to use (no build step needed)
+```typescript
+myTool.client(async ({ query }, ctx) => {
+  // Custom client logic: caching, optimistic updates, etc.
+  const cached = ctx.cache.get(query);
+  if (cached) return cached;
 
-### React Components
+  return ctx.fetch('/api/search', {
+    method: 'POST',
+    body: JSON.stringify({ query })
+  });
+});
+```
+
+### 4. View (Our Differentiator)
 
-```tsx
-import { ToolExecutorProvider, ToolRenderer, useToolExecutor } from '@/lib/aui/client';
+The `.view()` method defines how to render the tool's results:
 
-// Provider setup
-<ToolExecutorProvider tools={[weatherTool, searchTool]}>
-  <App />
-</ToolExecutorProvider>
+```typescript
+myTool.view((data, { loading, error }) => {
+  if (loading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  return <Results items={data.results} />;
+});
+```
 
-// Render a tool result
-<ToolRenderer toolCall={toolCall} tool={weatherTool} />
+## Fluent Builder Alternative
 
-// Hook usage
-const executor = useToolExecutor();
-const result = await executor.execute(toolCall);
+```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} />);
 ```
 
-## 🔧 Usage Examples
+## React Usage
+
+```typescript
+import { useTool } from '@lantos1618/better-ui';
 
-### Basic Tool
-```tsx
-const weatherTool = aui
-  .tool('weather')
-  .input(z.object({ city: z.string() }))
-  .execute(async ({ input }) => {
-    const response = await fetch(`/api/weather?city=${input.city}`);
-    return response.json();
-  })
-  .render(({ data }) => (
-    <div className="weather-card">
-      <h3>{data.city}</h3>
-      <p>{data.temp}°F</p>
+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>
-  ));
+  );
+}
+
+// Or with auto-execution
+function WeatherWidget({ city }) {
+  const { data, loading } = useTool(weather, { city }, { auto: true });
+  return <weather.View data={data} loading={loading} />;
+}
 ```
 
-### Tool with Client Optimization
-```tsx
-const searchTool = aui
-  .tool('search')
-  .input(z.object({ query: z.string() }))
-  .execute(async ({ input }) => {
-    return await database.search(input.query);
-  })
-  .clientExecute(async ({ input, ctx }) => {
-    // Client-side caching and offline support
-    const cached = ctx.cache.get(input.query);
-    if (cached) return cached;
-    
-    const result = await ctx.fetch('/api/aui', {
-      method: 'POST',
-      body: JSON.stringify({
-        toolCall: { toolName: 'search', input }
-      })
-    });
-    
-    ctx.cache.set(input.query, result);
-    return result;
-  })
-  .render(({ data }) => <SearchResults results={data} />);
-```
-
-## 🗂️ Project Structure
-
-```
-better-ui/
-├── app/                    # Next.js app directory
-│   ├── api/               # API routes
-│   └── aui-demo/          # Demo pages
-├── lib/aui/               # AUI system core
-│   ├── core/              # Core builder and registry
-│   ├── client/            # Client-side execution
-│   ├── server/            # Server-side execution
-│   ├── tools/             # Example tools
-│   └── types/             # TypeScript definitions
-├── examples/              # Usage examples
-└── agent/                 # Development metadata
-```
-
-## 🧪 Testing
+## AI Integration
 
-```bash
-npm test
-npm run type-check
-npm run lint
+### With Vercel AI SDK
+
+```typescript
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = await streamText({
+    model: openai('gpt-4'),
+    messages,
+    tools: {
+      weather: weather.toAITool(),
+      search: search.toAITool(),
+    },
+  });
+
+  return result.toDataStreamResponse();
+}
 ```
 
-## 🚀 Development
+## API Reference
+
+### `tool(config)` or `tool(name)`
+
+Create a new tool with object config or fluent builder.
+
+```typescript
+// Object config
+const t = tool({
+  name: string,
+  description?: string,
+  input: ZodSchema,
+  output?: ZodSchema,
+  tags?: string[],
+  cache?: { ttl: number, key?: (input) => string },
+});
+
+// Fluent builder
+const t = tool('name')
+  .description(string)
+  .input(ZodSchema)
+  .output(ZodSchema)
+  .tags(...string[])
+  .cache({ ttl, key? });
+```
 
-```bash
-# Start development server
-npm run dev
+### `.server(handler)`
+
+Define server-side implementation.
+
+```typescript
+t.server(async (input, ctx) => {
+  // ctx.env, ctx.headers, ctx.user, ctx.session available
+  return result;
+});
+```
+
+### `.client(handler)`
 
-# Build for production
-npm run build
+Define client-side implementation (optional).
 
-# Start production server
-npm start
+```typescript
+t.client(async (input, ctx) => {
+  // ctx.cache, ctx.fetch, ctx.optimistic available
+  return result;
+});
 ```
 
-## 📚 Documentation
+### `.view(component)`
 
-- [AUI System Overview](AUI.md) - Detailed system documentation
-- [Examples](./examples/) - Complete usage examples
-- [API Reference](./lib/aui/README.md) - Core API documentation
+Define React component for rendering results.
 
-## 🤝 Contributing
+```typescript
+t.view((data, { loading, error }) => <Component data={data} />);
+```
+
+### `useTool(tool, input?, options?)`
+
+React hook for executing tools.
+
+```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) => {},
+});
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
+## Project Structure
 
-## 📄 License
+```
+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
+```
 
-This project is private and proprietary.
+## Development
+
+```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 ❤️ using Next.js, TypeScript, and Zod.
+MIT