@lantos1618/better-ui 0.1.0

package/lib/aui/client-executor.ts

@@ -0,0 +1,417 @@
+import { AUIContext } from './core';
+import { AIControlledTool } from './ai-control';
+
+export interface CacheStrategy {
+  key: (toolName: string, input: any) => string;
+  ttl?: number; // Time to live in milliseconds
+  maxSize?: number; // Maximum number of cached items
+}
+
+export interface ClientExecutorOptions {
+  baseUrl?: string;
+  cache?: {
+    enabled: boolean;
+    strategy?: CacheStrategy;
+    storage?: 'memory' | 'localStorage' | 'sessionStorage';
+  };
+  retry?: {
+    attempts?: number;
+    delay?: number;
+    backoff?: 'linear' | 'exponential';
+  };
+  timeout?: number;
+  headers?: HeadersInit;
+}
+
+interface CacheEntry {
+  data: any;
+  timestamp: number;
+  ttl?: number;
+}
+
+export class ClientExecutor {
+  private cache: Map<string, CacheEntry> = new Map();
+  private options: Required<ClientExecutorOptions>;
+  private localStorage?: Storage;
+  private sessionStorage?: Storage;
+
+  constructor(options: ClientExecutorOptions = {}) {
+    this.options = {
+      baseUrl: options.baseUrl || '/api/aui/execute',
+      cache: {
+        enabled: options.cache?.enabled ?? true,
+        strategy: options.cache?.strategy || {
+          key: (tool, input) => `${tool}:${JSON.stringify(input)}`,
+          ttl: 5 * 60 * 1000, // 5 minutes default
+          maxSize: 100,
+        },
+        storage: options.cache?.storage || 'memory',
+      },
+      retry: {
+        attempts: options.retry?.attempts ?? 3,
+        delay: options.retry?.delay ?? 1000,
+        backoff: options.retry?.backoff || 'exponential',
+      },
+      timeout: options.timeout ?? 30000, // 30 seconds default
+      headers: options.headers || {},
+    };
+
+    if (typeof window !== 'undefined') {
+      this.localStorage = window.localStorage;
+      this.sessionStorage = window.sessionStorage;
+    }
+  }
+
+  async execute<TInput = any, TOutput = any>(
+    toolName: string,
+    input: TInput,
+    context?: Partial<AUIContext>
+  ): Promise<TOutput> {
+    // Check cache first if enabled
+    if (this.options.cache.enabled) {
+      const cached = this.getFromCache(toolName, input);
+      if (cached !== null) {
+        return cached;
+      }
+    }
+
+    // Execute with retry logic
+    let lastError: Error | null = null;
+    for (let attempt = 0; attempt < this.options.retry.attempts!; attempt++) {
+      try {
+        const result = await this.executeOnce<TInput, TOutput>(
+          toolName,
+          input,
+          context
+        );
+
+        // Store in cache if enabled
+        if (this.options.cache.enabled) {
+          this.storeInCache(toolName, input, result);
+        }
+
+        return result;
+      } catch (error) {
+        lastError = error as Error;
+        
+        // Don't retry on certain errors
+        if (error instanceof Error) {
+          if (error.message.includes('Tool') && error.message.includes('not found')) {
+            throw error; // Don't retry if tool doesn't exist
+          }
+          if (error.message.includes('Rate limit')) {
+            throw error; // Don't retry on rate limit
+          }
+        }
+
+        // Calculate delay for next attempt
+        if (attempt < this.options.retry.attempts! - 1) {
+          const delay = this.calculateRetryDelay(attempt);
+          await this.sleep(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Execution failed after retries');
+  }
+
+  private async executeOnce<TInput = any, TOutput = any>(
+    toolName: string,
+    input: TInput,
+    context?: Partial<AUIContext>
+  ): Promise<TOutput> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(
+      () => controller.abort(),
+      this.options.timeout
+    );
+
+    try {
+      const response = await fetch(this.options.baseUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.options.headers,
+        },
+        body: JSON.stringify({
+          tool: toolName,
+          input,
+          context,
+        }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || `HTTP ${response.status}`);
+      }
+
+      const result = await response.json();
+      return result.data || result;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error(`Execution timeout after ${this.options.timeout}ms`);
+      }
+      
+      throw error;
+    }
+  }
+
+  private getFromCache(toolName: string, input: any): any | null {
+    const key = this.options.cache.strategy!.key(toolName, input);
+    
+    // Check appropriate storage
+    let entry: CacheEntry | null = null;
+    
+    switch (this.options.cache.storage) {
+      case 'localStorage':
+        if (this.localStorage) {
+          const stored = this.localStorage.getItem(key);
+          if (stored) {
+            try {
+              entry = JSON.parse(stored);
+            } catch {
+              // Invalid cache entry
+            }
+          }
+        }
+        break;
+        
+      case 'sessionStorage':
+        if (this.sessionStorage) {
+          const stored = this.sessionStorage.getItem(key);
+          if (stored) {
+            try {
+              entry = JSON.parse(stored);
+            } catch {
+              // Invalid cache entry
+            }
+          }
+        }
+        break;
+        
+      default: // memory
+        entry = this.cache.get(key) || null;
+    }
+    
+    if (!entry) return null;
+    
+    // Check if entry is still valid
+    const now = Date.now();
+    const ttl = entry.ttl || this.options.cache.strategy!.ttl;
+    
+    if (ttl && now - entry.timestamp > ttl) {
+      // Entry expired
+      this.removeFromCache(key);
+      return null;
+    }
+    
+    return entry.data;
+  }
+
+  private storeInCache(toolName: string, input: any, data: any): void {
+    const key = this.options.cache.strategy!.key(toolName, input);
+    const entry: CacheEntry = {
+      data,
+      timestamp: Date.now(),
+      ttl: this.options.cache.strategy!.ttl,
+    };
+    
+    switch (this.options.cache.storage) {
+      case 'localStorage':
+        if (this.localStorage) {
+          try {
+            this.localStorage.setItem(key, JSON.stringify(entry));
+            this.enforceMaxSize('localStorage');
+          } catch {
+            // Storage quota exceeded
+          }
+        }
+        break;
+        
+      case 'sessionStorage':
+        if (this.sessionStorage) {
+          try {
+            this.sessionStorage.setItem(key, JSON.stringify(entry));
+            this.enforceMaxSize('sessionStorage');
+          } catch {
+            // Storage quota exceeded
+          }
+        }
+        break;
+        
+      default: // memory
+        this.cache.set(key, entry);
+        this.enforceMaxSize('memory');
+    }
+  }
+
+  private removeFromCache(key: string): void {
+    switch (this.options.cache.storage) {
+      case 'localStorage':
+        if (this.localStorage) {
+          this.localStorage.removeItem(key);
+        }
+        break;
+        
+      case 'sessionStorage':
+        if (this.sessionStorage) {
+          this.sessionStorage.removeItem(key);
+        }
+        break;
+        
+      default:
+        this.cache.delete(key);
+    }
+  }
+
+  private enforceMaxSize(storage: 'memory' | 'localStorage' | 'sessionStorage'): void {
+    const maxSize = this.options.cache.strategy!.maxSize;
+    if (!maxSize) return;
+    
+    if (storage === 'memory') {
+      if (this.cache.size > maxSize) {
+        // Remove oldest entries
+        const entries = Array.from(this.cache.entries());
+        entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+        
+        const toRemove = entries.slice(0, entries.length - maxSize);
+        toRemove.forEach(([key]) => this.cache.delete(key));
+      }
+    } else {
+      const storageObj = storage === 'localStorage' ? this.localStorage : this.sessionStorage;
+      if (!storageObj) return;
+      
+      // Get all cache keys
+      const cacheKeys: Array<{ key: string; timestamp: number }> = [];
+      for (let i = 0; i < storageObj.length; i++) {
+        const key = storageObj.key(i);
+        if (key) {
+          try {
+            const entry = JSON.parse(storageObj.getItem(key)!);
+            if (entry && entry.timestamp) {
+              cacheKeys.push({ key, timestamp: entry.timestamp });
+            }
+          } catch {
+            // Skip invalid entries
+          }
+        }
+      }
+      
+      if (cacheKeys.length > maxSize) {
+        cacheKeys.sort((a, b) => a.timestamp - b.timestamp);
+        const toRemove = cacheKeys.slice(0, cacheKeys.length - maxSize);
+        toRemove.forEach(({ key }) => storageObj.removeItem(key));
+      }
+    }
+  }
+
+  private calculateRetryDelay(attempt: number): number {
+    const baseDelay = this.options.retry.delay!;
+    
+    if (this.options.retry.backoff === 'exponential') {
+      return baseDelay * Math.pow(2, attempt);
+    }
+    
+    return baseDelay * (attempt + 1);
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  clearCache(): void {
+    switch (this.options.cache.storage) {
+      case 'localStorage':
+        if (this.localStorage) {
+          this.localStorage.clear();
+        }
+        break;
+        
+      case 'sessionStorage':
+        if (this.sessionStorage) {
+          this.sessionStorage.clear();
+        }
+        break;
+        
+      default:
+        this.cache.clear();
+    }
+  }
+
+  getCacheStats(): {
+    size: number;
+    storage: string;
+    enabled: boolean;
+  } {
+    let size = 0;
+    
+    switch (this.options.cache.storage) {
+      case 'localStorage':
+        size = this.localStorage?.length || 0;
+        break;
+        
+      case 'sessionStorage':
+        size = this.sessionStorage?.length || 0;
+        break;
+        
+      default:
+        size = this.cache.size;
+    }
+    
+    return {
+      size,
+      storage: this.options.cache.storage!,
+      enabled: this.options.cache.enabled,
+    };
+  }
+}
+
+// Default client executor instance
+export const clientExecutor = new ClientExecutor();
+
+// Enhanced client execution with optimistic updates
+export async function executeClientTool<TInput = any, TOutput = any>(
+  toolName: string,
+  input: TInput,
+  options?: {
+    optimistic?: () => TOutput;
+    onSuccess?: (result: TOutput) => void;
+    onError?: (error: Error) => void;
+    context?: Partial<AUIContext>;
+  }
+): Promise<TOutput> {
+  // Return optimistic result immediately if provided
+  if (options?.optimistic) {
+    const optimisticResult = options.optimistic();
+    
+    // Execute in background
+    clientExecutor.execute<TInput, TOutput>(toolName, input, options?.context)
+      .then(result => {
+        options?.onSuccess?.(result);
+      })
+      .catch(error => {
+        options?.onError?.(error);
+      });
+    
+    return optimisticResult;
+  }
+  
+  // Normal execution
+  try {
+    const result = await clientExecutor.execute<TInput, TOutput>(
+      toolName,
+      input,
+      options?.context
+    );
+    options?.onSuccess?.(result);
+    return result;
+  } catch (error) {
+    options?.onError?.(error as Error);
+    throw error;
+  }
+}

package/lib/aui/components/ToolRenderer.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import { AUITool } from '../index';
+
+interface ToolRendererProps {
+  tool: AUITool;
+  input?: any;
+  result?: any;
+  loading?: boolean;
+  error?: Error;
+}
+
+export function ToolRenderer({ tool, input, result, loading, error }: ToolRendererProps) {
+  if (!tool.renderer) {
+    return (
+      <div className="p-4 bg-gray-100 rounded">
+        <pre className="text-sm">{JSON.stringify(result, null, 2)}</pre>
+      </div>
+    );
+  }
+
+  return tool.renderer({ data: result, input, loading, error });
+}

package/lib/aui/core.ts

@@ -0,0 +1,137 @@
+import { ReactElement } from 'react';
+import { z } from 'zod';
+
+export interface AUIContext {
+  cache: Map<string, any>;
+  fetch: typeof fetch;
+  user?: any;
+  session?: any;
+  env?: Record<string, string>;
+  headers?: HeadersInit;
+  cookies?: Record<string, string>;
+  isServer?: boolean;
+}
+
+export interface ToolConfig<TInput, TOutput> {
+  name: string;
+  inputSchema?: z.ZodType<TInput>;
+  executeHandler?: (params: { input: TInput; ctx?: AUIContext }) => Promise<TOutput> | TOutput;
+  clientHandler?: (params: { input: TInput; ctx: AUIContext }) => Promise<TOutput> | TOutput;
+  renderHandler?: (props: { data: TOutput; input?: TInput; loading?: boolean; error?: Error }) => ReactElement;
+  middleware?: Array<(params: { input: TInput; ctx: AUIContext; next: () => Promise<TOutput> }) => Promise<TOutput>>;
+  description?: string;
+  tags?: string[];
+}
+
+export class AUITool<TInput = any, TOutput = any> {
+  protected config: ToolConfig<TInput, TOutput> = { name: '' };
+
+  constructor(name: string) {
+    this.config.name = name;
+  }
+
+  input<T>(schema: z.ZodType<T>): AUITool<T, TOutput> {
+    this.config.inputSchema = schema as any;
+    return this as any;
+  }
+
+  execute<O>(handler: (params: { input: TInput; ctx?: AUIContext }) => O | Promise<O>): AUITool<TInput, O> {
+    this.config.executeHandler = handler as any;
+    return this as any;
+  }
+
+  clientExecute(handler: (params: { input: TInput; ctx: AUIContext }) => TOutput | Promise<TOutput>): this {
+    this.config.clientHandler = handler;
+    return this;
+  }
+
+  render(component: (props: { data: TOutput; input?: TInput; loading?: boolean; error?: Error }) => ReactElement): this {
+    this.config.renderHandler = component;
+    return this;
+  }
+
+  async run(input: TInput, ctx?: AUIContext): Promise<TOutput> {
+    const validated = this.config.inputSchema ? this.config.inputSchema.parse(input) : input;
+    const context = ctx || {
+      cache: new Map(),
+      fetch: globalThis.fetch?.bind(globalThis) || (() => Promise.reject(new Error('Fetch not available'))),
+      isServer: typeof window === 'undefined',
+    };
+    
+    // Apply middleware if present
+    if (this.config.middleware?.length) {
+      let index = 0;
+      const next = async (): Promise<TOutput> => {
+        if (index >= this.config.middleware!.length) {
+          return this.executeCore(validated, context);
+        }
+        const middleware = this.config.middleware![index++];
+        return middleware({ input: validated, ctx: context, next });
+      };
+      return next();
+    }
+    
+    return this.executeCore(validated, context);
+  }
+  
+  private async executeCore(input: TInput, ctx: AUIContext): Promise<TOutput> {
+    // Use clientHandler if it exists and we're on the client
+    if (!ctx.isServer && this.config.clientHandler) {
+      return this.config.clientHandler({ input, ctx });
+    }
+    
+    if (!this.config.executeHandler) {
+      throw new Error(`Tool ${this.config.name} has no execute handler`);
+    }
+    
+    return this.config.executeHandler({ input, ctx });
+  }
+  
+  middleware(fn: (params: { input: TInput; ctx: AUIContext; next: () => Promise<TOutput> }) => Promise<TOutput>): this {
+    if (!this.config.middleware) {
+      this.config.middleware = [];
+    }
+    this.config.middleware.push(fn);
+    return this;
+  }
+  
+  describe(description: string): this {
+    this.config.description = description;
+    return this;
+  }
+  
+  tag(...tags: string[]): this {
+    if (!this.config.tags) {
+      this.config.tags = [];
+    }
+    this.config.tags.push(...tags);
+    return this;
+  }
+
+  get name() { return this.config.name; }
+  get schema() { return this.config.inputSchema; }
+  get inputSchema() { return this.config.inputSchema; }
+  get outputSchema() { return undefined; } // Can be extended if needed
+  get isServerOnly() { return !this.config.clientHandler; }
+  get metadata() { return { description: this.config.description, tags: this.config.tags }; }
+  get renderer() { return this.config.renderHandler; }
+  get description() { return this.config.description; }
+  get tags() { return this.config.tags || []; }
+  
+  toJSON() {
+    return {
+      name: this.config.name,
+      description: this.config.description,
+      tags: this.config.tags || [],
+      hasInput: !!this.config.inputSchema,
+      hasExecute: !!this.config.executeHandler,
+      hasClientExecute: !!this.config.clientHandler,
+      hasRender: !!this.config.renderHandler,
+      hasMiddleware: !!(this.config.middleware && this.config.middleware.length > 0)
+    };
+  }
+  
+  getConfig(): Readonly<ToolConfig<TInput, TOutput>> {
+    return { ...this.config };
+  }
+}

package/lib/aui/demo.tsx

@@ -0,0 +1,89 @@
+import aui from './index';
+import { z } from 'zod';
+
+// ============================================
+// EXACT API AS REQUESTED BY USER
+// ============================================
+
+// 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>);
+
+// Complex tool - adds client optimization
+const complexTool = aui
+  .tool('search')
+  .input(z.object({ query: z.string() }))
+  .execute(async ({ input }) => {
+    // Mock database search
+    return { results: [`Result for ${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', { 
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input)
+    }).then(r => r.json());
+  })
+  .render(({ data }) => <SearchResults results={data} />);
+
+// Component for rendering search results
+function SearchResults({ results }: { results: any }) {
+  return (
+    <div>
+      {results.results?.map((r: string, i: number) => (
+        <div key={i}>{r}</div>
+      ))}
+    </div>
+  );
+}
+
+// ============================================
+// USAGE EXAMPLES
+// ============================================
+
+// Direct execution
+async function exampleUsage() {
+  const ctx = aui.createContext();
+  
+  // Execute weather tool
+  const weatherResult = await simpleTool.run({ city: 'Tokyo' }, ctx);
+  console.log(weatherResult); // { temp: 72, city: 'Tokyo' }
+  
+  // Execute search tool
+  const searchResult = await complexTool.run({ query: 'AI tools' }, ctx);
+  console.log(searchResult); // { results: ['Result for AI tools'] }
+}
+
+// React component usage
+import { useAUITool } from './hooks/useAUITool';
+
+export function WeatherWidget() {
+  const { execute, data, loading } = useAUITool(simpleTool);
+  
+  return (
+    <div>
+      <button onClick={() => execute({ city: 'Tokyo' })}>
+        Get Weather
+      </button>
+      {loading && <span>Loading...</span>}
+      {data && simpleTool.renderer && simpleTool.renderer({ data })}
+    </div>
+  );
+}
+
+// AI Agent can discover and use tools
+export function getToolsForAI() {
+  return aui.getTools().map((tool: any) => ({
+    name: tool.name,
+    description: tool.description,
+    schema: tool.schema,
+    execute: (input: any) => tool.run(input)
+  }));
+}
+
+export { simpleTool, complexTool };