Files
ui/pkg/react/README.md

7.8 KiB

@hanzo/react

React package for building AI-powered applications with generative UI, where users interact through natural language.

Features

  • 🤖 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

npm install @hanzo/react
# or
pnpm add @hanzo/react
# or
yarn add @hanzo/react

Quick Start

import { HanzoProvider, useMessage } from '@hanzo/react'

function App() {
  return (
    <HanzoProvider apiKey={process.env.HANZO_API_KEY}>
      <ChatInterface />
    </HanzoProvider>
  )
}

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

HanzoProvider

The root component that provides Hanzo context to your app:

<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>

Generative UI Components

Register components that AI can dynamically render:

const components = [
  {
    name: 'weather-card',
    component: WeatherCard,
    description: 'Display weather information',
    parameters: z.object({
      city: z.string(),
      temperature: z.number(),
      conditions: z.string()
    })
  }
]

<HanzoProvider components={components}>
  {/* AI can now render WeatherCard in responses */}
</HanzoProvider>

Message Hooks

Send messages and handle responses:

// Basic messaging
const { sendMessage, isLoading, error } = useMessage()

// Streaming responses
const { streamMessage, currentMessage, progress } = useStreaming()

Tool Calling

Add tools that AI can execute:

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>

Available Hooks

  • useHanzo() - Access complete Hanzo context
  • useMessage() - Send messages and manage state
  • useStreaming() - Stream AI responses in real-time

Planned: useThread, useComponent, useTool, useGenerativeUI, useSuggestions, useModelConfig, useAttachments, useAuth, and useMCP are not implemented yet.

Examples

Chat Application

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>
  )
}

Custom Components

// 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

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:

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:

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
})

License

MIT © Hanzo AI, Inc. — see LICENSE.md. HIP-0137 (hanzoai/hips).

Support