Files
Fhatuwani SikhwariandGitHub dc997668ba fix(react): correct useStreaming completion content (#312)
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
2026-11-12 18:53:10 -08:00
..
2026-09-08 23:50:28 -07:00

@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