ai.matey.react.core

Core React hooks for AI chat interactions.

Part of the ai.matey monorepo.

Installation

``bash
npm install ai.matey.react.core
`

Quick Start

$3

`tsx
import { useChat } from 'ai.matey.react.core';

function ChatComponent() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
api: '/api/chat',
});

return (


`tsx
import { useChat } from 'ai.matey.react.core';
import { OpenAIBackend } from 'ai.matey.backend/openai';

// Create backend (could also be Anthropic, Gemini, Ollama, etc.)
const backend = new OpenAIBackend({
apiKey: process.env.REACT_APP_OPENAI_API_KEY,
});

function ChatComponent() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
direct: {
backend,
systemPrompt: 'You are a helpful assistant.',
},
});

return (


- useChat - Chat interface with streaming support
- useCompletion - Text completion interface
- useObject - Structured object generation

$3

- Message - Chat message type
- ToolCall, ToolInvocation, Tool - Tool calling types
- UseChatOptions, UseChatReturn - useChat types
- UseCompletionOptions, UseCompletionReturn - useCompletion types
- UseObjectOptions, UseObjectReturn - useObject types
- DirectBackend, DirectModeOptions, DirectToolCallHandler - Direct mode types

API Reference

$3

React hook for building chat interfaces with streaming support.

Supports two modes:
1. HTTP Mode (default): Uses api endpoint with fetch
2. Direct Mode: Uses direct.backend for direct backend access

`tsx
const {
messages, // Message[] - Chat history
input, // string - Current input value
setInput, // (value: string) => void - Set input
handleInputChange, // (e: ChangeEvent) => void - Input change handler
handleSubmit, // (e?: FormEvent) => void - Form submit handler
append, // (message: Message | string) => Promise
reload, // () => Promise - Reload last response
stop, // () => void - Stop streaming
setMessages, // (messages: Message[]) => void
isLoading, // boolean - Request in progress
error, // Error | undefined
data, // unknown[] | undefined - Additional data
} = useChat(options);
`

#### HTTP Mode Options

`tsx
useChat({
api: '/api/chat', // API endpoint (default: '/api/chat')
initialMessages: [], // Initial messages
initialInput: '', // Initial input value
id: 'chat-1', // Chat instance ID
headers: {}, // Request headers
body: {}, // Extra request body fields
onFinish: (message) => {}, // Called when response completes
onError: (error) => {}, // Called on error
onResponse: (response) => {}, // Called with fetch response
streamProtocol: 'data', // 'data' (SSE) or 'text'
});
`

#### Direct Mode Options

`tsx
useChat({
direct: {
// Required: Backend adapter (any ai.matey backend or Bridge)
backend: myBackendAdapter,

// Optional: System prompt
systemPrompt: 'You are a helpful assistant.',

// Optional: Default IR parameters
defaultParameters: {
temperature: 0.7,
maxTokens: 1000,
},

// Optional: Available tools
tools: [
{
name: 'get_weather',
description: 'Get weather for a location',
parameters: { / JSON Schema / },
},
],

// Optional: Tool call handler
onToolCall: async (name, input, id) => {
return 'Tool result';
},

// Optional: Auto-execute tools (default: false)
autoExecuteTools: true,

// Optional: Max tool rounds (default: 10)
maxToolRounds: 5,
},
// Common options still work
initialMessages: [],
onFinish: (message) => {},
onError: (error) => {},
});
`

$3

React hook for text completion interfaces.

`tsx
const {
completion, // string - Current completion
input, // string - Current input
setInput, // (value: string) => void
handleInputChange,
handleSubmit,
complete, // (prompt: string) => Promise
stop,
isLoading,
error,
} = useCompletion({
api: '/api/completion',
// ... similar options to useChat
});
`

$3

React hook for generating structured objects.

`tsx
const {
object, // T | undefined - Generated object
submit, // (input: string) => void
isLoading,
error,
} = useObject({
api: '/api/object',
schema: myZodSchema, // Zod schema for validation
});
`

Direct Mode vs HTTP Mode

| Feature | HTTP Mode | Direct Mode |
|---------|-----------|-------------|
| Setup | Requires API endpoint | Just a backend adapter |
| Server needed | Yes | No |
| Use case | Full-stack apps | Electron, browser extensions, testing |
| Streaming | Via SSE | Native async iterators |
| Tool calling | Via API | Built-in with wrapper-ir` |

License

MIT - see LICENSE for details.