@hanzo/react 0.1.2 → 1.0.0

package/README.md

@@ -1,83 +1,347 @@
-# 📚 rollup-jest-boilerplate
+# @hanzo/react
 
-> Full featured boilerplate for building JavaScript libraries the modern way.
+React package for building AI-powered applications with generative UI, where users interact through natural language.
 
 ## Features
-- 📜 [Rollup.js](https://rollupjs.org/guide/en) configuration providing compatibility with different module systems (CommonJS, ECMAScript, UMD for `<script>` tags)
-- 🃏 [Jest](http://jestjs.io/) setup with watch mode working
-- 🛀 [Renovate](https://github.com/apps/renovate) configuration for auto updates (you have to activate it via https://github.com/apps/renovate)
-- ✅ [Travis CI](https://travis-ci.com/)
-- 🏗 [.nvmrc](https://github.com/creationix/nvm) file to enforce the Node.js version for contributors and continuous integration
-- ⚡️ Ready to publish and use
-
-## How to use
-
-Decide of a new library name, let's say `new-super-library` (🤦🏼‍♀️), then in a terminal:
-
-```sh
-curl --output rollup-jest-boilerplate.zip -LOk https://github.com/algolia/rollup-jest-boilerplate/archive/master.zip
-unzip rollup-jest-boilerplate.zip
-rm rollup-jest-boilerplate.zip
-mv rollup-jest-boilerplate-master new-super-library
+
+- 🤖 **Generative UI** - Dynamically render React components in AI responses
+- 🔄 **Real-time Streaming** - Stream AI responses with progress tracking
+- 💬 **Message Threads** - Manage conversation history and context
+- 🛠️ **Tool Calling** - Let AI execute functions during conversations
+- 🔌 **Model Context Protocol** - MCP integration for enhanced AI capabilities
+- 🎨 **Component Registry** - Register custom components for AI to use
+- 🔐 **Authentication** - Built-in auth support for user management
+- 📎 **File Attachments** - Handle images, documents, and other files
+- 💡 **Smart Suggestions** - Provide contextual suggestions to users
+- ⚡ **TypeScript Support** - Full type safety and IntelliSense
+
+## Installation
+
+```bash
+npm install @hanzo/react
+# or
+pnpm add @hanzo/react
+# or
+yarn add @hanzo/react
 ```
 
-**Next steps:**
-- search the project for `rollup-starter-lib` and replace everywhere with `new-super-library`
-- start coding in [src/index.js](src/index.js)
-- profit 💸
+## Quick Start
+
+```tsx
+import { HanzoProvider, useMessage } from '@hanzo/react'
+
+function App() {
+  return (
+    <HanzoProvider apiKey={process.env.HANZO_API_KEY}>
+      <ChatInterface />
+    </HanzoProvider>
+  )
+}
 
-## Live examples
+function ChatInterface() {
+  const { sendMessage, isLoading, lastMessage } = useMessage()
+  
+  const handleSubmit = async (text: string) => {
+    const response = await sendMessage(text)
+    console.log('AI Response:', response)
+  }
+  
+  return (
+    <div>
+      <input onKeyDown={(e) => {
+        if (e.key === 'Enter') {
+          handleSubmit(e.currentTarget.value)
+        }
+      }} />
+      {isLoading && <p>Loading...</p>}
+      {lastMessage && <div>{lastMessage.content}</div>}
+    </div>
+  )
+}
+```
+
+## Core Concepts
 
-Those examples are using the live published version of this boilerplate library on [npm](https://www.npmjs.com/rollup-jest-boilerplate) and they run with [CodeSandbox](https://codesandbox.io/).
+### HanzoProvider
 
-- [ECMAScript](https://codesandbox.io/s/7ojknnqjl6?module=%2Fsrc%2Findex.js)
-- [CommonJS](https://codesandbox.io/s/o5q018q609?module=%2Fsrc%2Findex.js)
-- [UMD](https://codesandbox.io/s/jyqqp21rv), this leverages [jsDelivr npm CDN](https://www.jsdelivr.com/features)
+The root component that provides Hanzo context to your app:
 
-## Developer environment requirements
+```tsx
+<HanzoProvider
+  apiKey="your-api-key"
+  apiUrl="https://api.hanzo.ai/v1"
+  model="gpt-4-turbo-preview"
+  components={[/* your components */]}
+  tools={[/* your tools */]}
+  enableStreaming={true}
+  enableMCP={true}
+  onMessage={(message) => console.log('New message:', message)}
+  onError={(error) => console.error('Error:', error)}
+>
+  <YourApp />
+</HanzoProvider>
+```
 
-To run this project, you will need:
+### Generative UI Components
 
-- Node.js >= v10.5.0, use nvm - [install instructions](https://github.com/creationix/nvm#install-script)
+Register components that AI can dynamically render:
 
-## Running tests
+```tsx
+const components = [
+  {
+    name: 'weather-card',
+    component: WeatherCard,
+    description: 'Display weather information',
+    parameters: z.object({
+      city: z.string(),
+      temperature: z.number(),
+      conditions: z.string()
+    })
+  }
+]
 
-```sh
-npm
-npm test
-npm test --watch
+<HanzoProvider components={components}>
+  {/* AI can now render WeatherCard in responses */}
+</HanzoProvider>
 ```
 
-## Dev mode
+### Message Hooks
+
+Send messages and handle responses:
+
+```tsx
+// Basic messaging
+const { sendMessage, isLoading, error } = useMessage()
 
-When developing you can run:
+// Streaming responses
+const { streamMessage, currentMessage, progress } = useStreaming()
 
+// Thread management
+const { threads, activeThread, createThread, switchThread } = useThread()
 ```
-npm run watch
+
+### Tool Calling
+
+Add tools that AI can execute:
+
+```tsx
+const tools = [
+  {
+    name: 'calculator',
+    description: 'Perform calculations',
+    parameters: z.object({
+      expression: z.string()
+    }),
+    execute: async ({ expression }) => {
+      return { result: eval(expression) }
+    }
+  }
+]
+
+<HanzoProvider tools={tools}>
+  {/* AI can now use the calculator tool */}
+</HanzoProvider>
 ```
 
-This will regenerate the build files each time a source file is changed and serve on http://127.0.0.1:5000.
+## Available Hooks
+
+### Core Hooks
+- `useHanzo()` - Access complete Hanzo context
+- `useMessage()` - Send messages and manage state
+- `useStreaming()` - Stream AI responses in real-time
+- `useThread()` - Manage conversation threads
 
-### Previewing umd build in the browser
+### Component & Tool Hooks
+- `useComponent()` - Dynamically register/render components
+- `useTool()` - Execute and manage AI tools
+- `useGenerativeUI()` - Generate UI components on the fly
 
-If your package works in the browser, you can open `dev/index.html` to try it out.
+### Utility Hooks
+- `useSuggestions()` - Provide intelligent suggestions
+- `useModelConfig()` - Configure and switch AI models
+- `useAttachments()` - Handle file attachments
+- `useAuth()` - Manage user authentication
+- `useMCP()` - Model Context Protocol integration
 
-## Publishing
+## Examples
 
-```sh
-npm publish
+### Chat Application
+
+```tsx
+import { HanzoProvider, useMessage, useStreaming } from '@hanzo/react'
+
+function ChatApp() {
+  const [messages, setMessages] = useState([])
+  const { sendMessage } = useMessage()
+  const { streamMessage, currentMessage, isStreaming } = useStreaming()
+  
+  const handleSend = async (text: string) => {
+    // Add user message
+    setMessages(prev => [...prev, { role: 'user', content: text }])
+    
+    // Stream AI response
+    await streamMessage(text)
+    
+    // Add AI message when complete
+    setMessages(prev => [...prev, { 
+      role: 'assistant', 
+      content: currentMessage 
+    }])
+  }
+  
+  return (
+    <div>
+      {messages.map((msg, i) => (
+        <div key={i} className={msg.role}>
+          {msg.content}
+        </div>
+      ))}
+      {isStreaming && <div>{currentMessage}</div>}
+    </div>
+  )
+}
 ```
 
-## Additional tooling
+### Custom Components
+
+```tsx
+// Define a custom visualization component
+function DataChart({ data, type }) {
+  return <Chart data={data} type={type} />
+}
+
+// Register it with Hanzo
+const components = [
+  {
+    name: 'data-chart',
+    component: DataChart,
+    description: 'Visualize data in a chart',
+    parameters: z.object({
+      data: z.array(z.number()),
+      type: z.enum(['bar', 'line', 'pie'])
+    })
+  }
+]
+
+// Use in your app
+<HanzoProvider components={components}>
+  <ChatInterface />
+</HanzoProvider>
+```
+
+### Tool Integration
+
+```tsx
+const tools = [
+  {
+    name: 'fetchData',
+    description: 'Fetch data from API',
+    parameters: z.object({
+      endpoint: z.string().url()
+    }),
+    execute: async ({ endpoint }) => {
+      const response = await fetch(endpoint)
+      return response.json()
+    }
+  },
+  {
+    name: 'saveToDatabase',
+    description: 'Save data to database',
+    parameters: z.object({
+      collection: z.string(),
+      data: z.any()
+    }),
+    execute: async ({ collection, data }) => {
+      await db.collection(collection).insert(data)
+      return { success: true }
+    }
+  }
+]
+
+<HanzoProvider tools={tools}>
+  {/* AI can now fetch data and save to database */}
+</HanzoProvider>
+```
+
+## TypeScript
+
+Full TypeScript support with type definitions:
+
+```tsx
+import type { 
+  HanzoComponent, 
+  HanzoTool, 
+  Message, 
+  Thread 
+} from '@hanzo/react'
+
+const component: HanzoComponent = {
+  name: 'my-component',
+  component: MyComponent,
+  description: 'A typed component',
+  parameters: z.object({
+    title: z.string(),
+    count: z.number()
+  })
+}
+
+const tool: HanzoTool = {
+  name: 'my-tool',
+  description: 'A typed tool',
+  parameters: z.object({
+    input: z.string()
+  }),
+  execute: async ({ input }) => {
+    return { processed: input.toUpperCase() }
+  }
+}
+```
+
+## API Reference
+
+### HanzoProvider Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `apiKey` | `string` | Yes | - | Your Hanzo API key |
+| `apiUrl` | `string` | No | `https://api.hanzo.ai/v1` | API endpoint URL |
+| `model` | `string` | No | `gpt-4-turbo-preview` | AI model to use |
+| `components` | `HanzoComponent[]` | No | `[]` | Registered components |
+| `tools` | `HanzoTool[]` | No | `[]` | Available tools |
+| `initialMessages` | `Message[]` | No | `[]` | Initial conversation |
+| `enableStreaming` | `boolean` | No | `true` | Enable streaming |
+| `enableMCP` | `boolean` | No | `false` | Enable MCP |
+| `onMessage` | `(message: Message) => void` | No | - | Message callback |
+| `onError` | `(error: Error) => void` | No | - | Error callback |
+
+### Hook Options
+
+Most hooks accept configuration options:
+
+```tsx
+const { sendMessage } = useMessage({
+  threadId: 'custom-thread',
+  onSuccess: (message) => console.log('Sent:', message),
+  onError: (error) => console.error('Error:', error),
+  autoRetry: true,
+  maxRetries: 3,
+  retryDelay: 1000
+})
+
+const { streamMessage } = useStreaming({
+  onChunk: (chunk) => console.log('Chunk:', chunk),
+  onComplete: (message) => console.log('Complete:', message),
+  bufferSize: 5,
+  throttleMs: 100
+})
+```
 
-Based on your need, you might want to add:
-- [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)
-- [TypeScript](https://www.typescriptlang.org/) support
-- Monorepo support with [Lerna](https://lernajs.io/)
-- CHANGELOG.md generation with [conventional-changelog](https://github.com/conventional-changelog)
+## License
 
-If so, please do and open pull requests when you feel like it.
+BSD-3-Clause © Hanzo AI, Inc.
 
-## Original idea
+## Support
 
-I initially used [rollup/rollup-starter-lib](https://github.com/rollup/rollup-starter-lib) but really needed that Jest support so I did it.
+- Documentation: [https://ui.hanzo.ai/docs/hanzo-react](https://ui.hanzo.ai/docs/hanzo-react)
+- GitHub: [https://github.com/hanzoai/ui](https://github.com/hanzoai/ui)
+- Discord: [https://discord.gg/hanzo](https://discord.gg/hanzo)

package/dist/index.d.mts

@@ -0,0 +1,255 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+import { z } from 'zod';
+import { ClassValue } from 'clsx';
+
+interface HanzoComponent {
+    name: string;
+    component: React$1.ComponentType<any>;
+    description?: string;
+    parameters?: z.ZodType<any>;
+    generateUI?: (params: any) => React$1.ReactElement;
+}
+interface HanzoTool {
+    name: string;
+    description: string;
+    parameters: z.ZodType<any>;
+    execute: (params: any) => Promise<any>;
+}
+interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string | React$1.ReactElement;
+    timestamp: Date;
+    threadId: string;
+    toolCalls?: ToolCall[];
+    metadata?: Record<string, any>;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: any;
+    result?: any;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+}
+interface Thread {
+    id: string;
+    messages: Message[];
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, any>;
+}
+interface HanzoContextValue {
+    apiKey?: string;
+    apiUrl?: string;
+    model?: string;
+    components: Map<string, HanzoComponent>;
+    tools: Map<string, HanzoTool>;
+    threads: Map<string, Thread>;
+    activeThreadId?: string;
+    sendMessage: (content: string, threadId?: string) => Promise<Message>;
+    streamMessage: (content: string, threadId?: string) => AsyncGenerator<Message>;
+    createThread: (metadata?: Record<string, any>) => Thread;
+    switchThread: (threadId: string) => void;
+    deleteThread: (threadId: string) => void;
+    registerComponent: (component: HanzoComponent) => void;
+    unregisterComponent: (name: string) => void;
+    renderComponent: (name: string, props: any) => React$1.ReactElement | null;
+    registerTool: (tool: HanzoTool) => void;
+    unregisterTool: (name: string) => void;
+    executeTool: (name: string, params: any) => Promise<any>;
+    isStreaming: boolean;
+    responseStage?: 'thinking' | 'generating' | 'tool-calling' | 'completed';
+    error?: Error;
+}
+interface HanzoProviderProps {
+    children: React$1.ReactNode;
+    apiKey?: string;
+    apiUrl?: string;
+    model?: string;
+    components?: HanzoComponent[];
+    tools?: HanzoTool[];
+    initialMessages?: Message[];
+    onMessage?: (message: Message) => void;
+    onError?: (error: Error) => void;
+    enableStreaming?: boolean;
+    enableMCP?: boolean;
+    mcpServers?: string[];
+}
+declare function HanzoProvider({ children, apiKey, apiUrl, model, components: initialComponents, tools: initialTools, initialMessages, onMessage, onError, enableStreaming, enableMCP, // eslint-disable-line @typescript-eslint/no-unused-vars
+mcpServers }: HanzoProviderProps): react_jsx_runtime.JSX.Element;
+declare function useHanzo(): HanzoContextValue;
+
+interface UseMessageOptions {
+    threadId?: string;
+    onSuccess?: (message: Message) => void;
+    onError?: (error: Error) => void;
+    autoRetry?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface UseMessageReturn {
+    sendMessage: (content: string) => Promise<Message>;
+    sendMessageWithAttachments: (content: string, attachments: File[]) => Promise<Message>;
+    isLoading: boolean;
+    error: Error | null;
+    lastMessage: Message | null;
+    clearError: () => void;
+    retry: () => Promise<void>;
+}
+declare function useMessage(options?: UseMessageOptions): UseMessageReturn;
+
+interface UseStreamingOptions {
+    threadId?: string;
+    onChunk?: (chunk: string) => void;
+    onComplete?: (message: Message) => void;
+    onError?: (error: Error) => void;
+    bufferSize?: number;
+    throttleMs?: number;
+}
+interface UseStreamingReturn {
+    streamMessage: (content: string) => Promise<void>;
+    isStreaming: boolean;
+    currentMessage: string;
+    error: Error | null;
+    stopStreaming: () => void;
+    clearMessage: () => void;
+    progress: number;
+}
+declare function useStreaming(options?: UseStreamingOptions): UseStreamingReturn;
+
+declare function cn(...inputs: ClassValue[]): string;
+
+declare function generateId(prefix?: string): string;
+
+declare function parseStream(stream: ReadableStream<Uint8Array>): Promise<string>;
+
+interface UseThreadOptions {
+    maxThreads?: number;
+    autoArchive?: boolean;
+}
+interface UseThreadReturn {
+    threads: Map<string, any>;
+    activeThread: any | undefined;
+    createThread: (metadata?: Record<string, any>) => any;
+    switchThread: (threadId: string) => void;
+    deleteThread: (threadId: string) => void;
+    updateThreadMetadata: (threadId: string, metadata: Record<string, any>) => void;
+    getThreadMessages: (threadId: string) => any[];
+    clearThread: (threadId: string) => void;
+}
+interface UseComponentOptions {
+    lazy?: boolean;
+}
+interface UseComponentReturn {
+    registerComponent: (component: any) => void;
+    unregisterComponent: (name: string) => void;
+    renderComponent: (name: string, props: any) => React.ReactElement | null;
+    getComponent: (name: string) => any | undefined;
+    hasComponent: (name: string) => boolean;
+    listComponents: () => string[];
+}
+interface UseToolOptions {
+    timeout?: number;
+}
+interface UseToolReturn {
+    executeTool: (name: string, params: any) => Promise<any>;
+    registerTool: (tool: any) => void;
+    unregisterTool: (name: string) => void;
+    isExecuting: boolean;
+    lastResult: any | null;
+    error: Error | null;
+}
+interface UseSuggestionsOptions {
+    maxSuggestions?: number;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+}
+interface UseSuggestionsReturn {
+    suggestions: any[];
+    getSuggestions: (options?: any) => Promise<void>;
+    acceptSuggestion: (suggestion: any) => void;
+    dismissSuggestion: (id: string) => void;
+    isLoading: boolean;
+}
+interface UseModelConfigOptions {
+    defaultModel?: string;
+}
+interface UseModelConfigReturn {
+    currentModel: string;
+    availableModels: any[];
+    switchModel: (modelId: string) => void;
+    updateParameters: (params: any) => void;
+    resetToDefaults: () => void;
+}
+interface UseMCPOptions {
+    autoConnect?: boolean;
+}
+interface UseMCPReturn {
+    connectServer: (config: any) => Promise<void>;
+    disconnectServer: (id: string) => void;
+    connectedServers: any[];
+    executeServerTool: (serverId: string, tool: string, params: any) => Promise<any>;
+    getServerResources: (serverId: string) => any[];
+    isConnected: (serverId: string) => boolean;
+}
+interface UseGenerativeUIOptions {
+    cacheResults?: boolean;
+}
+interface UseGenerativeUIReturn {
+    generateUI: (options: any) => Promise<React.ReactElement>;
+    isGenerating: boolean;
+    generatedComponents: React.ReactElement[];
+    clearComponents: () => void;
+    saveComponent: (name: string, component: React.ReactElement) => void;
+}
+interface UseAuthOptions {
+    provider?: string;
+}
+interface UseAuthReturn {
+    user: any | null;
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    signIn: (options?: any) => Promise<void>;
+    signOut: () => Promise<void>;
+    getToken: () => Promise<string | null>;
+    refreshToken: () => Promise<void>;
+}
+interface UseAttachmentsOptions {
+    maxSize?: number;
+    allowedTypes?: string[];
+    autoUpload?: boolean;
+}
+interface UseAttachmentsReturn {
+    attachments: any[];
+    addAttachment: (file: File) => Promise<any>;
+    removeAttachment: (id: string) => void;
+    clearAttachments: () => void;
+    uploadAttachment: (attachment: any) => Promise<void>;
+    isUploading: boolean;
+    uploadProgress: number;
+}
+
+interface Suggestion {
+    id: string;
+    text: string;
+    metadata?: Record<string, any>;
+}
+interface Model {
+    id: string;
+    name: string;
+    description: string;
+    parameters?: Record<string, any>;
+}
+interface Attachment {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    url?: string;
+    file?: File;
+}
+
+declare const VERSION = "1.0.0";
+
+export { type Attachment, type HanzoComponent, type HanzoContextValue, HanzoProvider, type HanzoProviderProps, type HanzoTool, type Message, type Model, type Suggestion, type Thread, type ToolCall, type UseAttachmentsOptions, type UseAttachmentsReturn, type UseAuthOptions, type UseAuthReturn, type UseComponentOptions, type UseComponentReturn, type UseGenerativeUIOptions, type UseGenerativeUIReturn, type UseMCPOptions, type UseMCPReturn, type UseMessageOptions, type UseMessageReturn, type UseModelConfigOptions, type UseModelConfigReturn, type UseStreamingOptions, type UseStreamingReturn, type UseSuggestionsOptions, type UseSuggestionsReturn, type UseThreadOptions, type UseThreadReturn, type UseToolOptions, type UseToolReturn, VERSION, cn, generateId, parseStream, useHanzo, useMessage, useStreaming };