mirror of
https://github.com/hanzoai/ui.git
synced 2026-11-20 20:07:34 +00:00
Complete with the text streamed in this call rather than the stale currentMessage closure, treat the provider stream as one cumulative assistant reply (skipping the user echo), and drop currentMessage from the callback deps so streamMessage keeps its identity. Fixes #308 Claude-Session: https://claude.ai/code/session_015XYKLix9PSyn6Jw2HWKprk
@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 contextuseMessage()- Send messages and manage stateuseStreaming()- 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
- Documentation: https://ui.hanzo.ai/docs/hanzo-react
- GitHub: https://github.com/hanzoai/ui
- Discord: https://discord.gg/CJCyAsm9Vr