dev-specialisms:hashbrown-core

What this skill does

# Hashbrown Development Skill

## Overview

Hashbrown is a React library for building LLM-powered applications with generative UI, client-side tool calling, streaming, and sandboxed JavaScript execution. It provides React hooks (`useChat`, `useUiChat`, etc.) that connect to a Node.js backend adapter, which securely communicates with LLM providers (OpenAI, Anthropic, Google, Azure, Bedrock, Ollama).

**Architecture**: React frontend (using Hashbrown hooks) + Node.js backend adapter (proxies LLM API requests)

## Quick Start Workflow

### 1. Choose the Right Hook

| Hook                      | Multi-turn Chat | Single Input | Structured Output | Tool Calling | Generate UI |
| ------------------------- | :-------------: | :----------: | :---------------: | :----------: | :---------: |
| `useChat`                 |       ✅        |      ❌      |        ❌         |      ✅      |     ❌      |
| `useStructuredChat`       |       ✅        |      ❌      |        ✅         |      ✅      |     ❌      |
| `useCompletion`           |       ❌        |      ✅      |        ❌         |      ✅      |     ❌      |
| `useStructuredCompletion` |       ❌        |      ✅      |        ✅         |      ✅      |     ❌      |
| `useUiChat`               |       ✅        |      ❌      |        ✅         |      ✅      |     ✅      |

### 2. Generate Boilerplate

Use the scripts to scaffold components and servers:

```bash
# List available templates
python scripts/list-templates.py

# Generate a component
python scripts/generate-component.py simple-chat ./src/components

# Generate a backend server
python scripts/generate-server.py basic-chat-server ./backend
```

**Available component templates:**

- `simple-chat` - Basic text-only chat with `useChat`
- `ui-chat-with-components` - Generative UI with `useUiChat` and `exposeComponent`
- `client-side-tool-calling` - Tool calling with `useTool`
- `js-runtime-chart-generator` - Sandboxed JS execution for data visualization
- `structured-data-form` - Form generation from natural language with Skillet schemas
- `streaming-chat-ui` - Streaming responses with loading states
- `multi-threaded-chat-ui` - Multi-conversation management with threads
- `predictive-text-input` - Autocomplete/suggestions powered by LLM
- `chat-with-voice-input` - Voice input with speech recognition

**Available server templates:**

- `basic-chat-server` - Simple Express server with OpenAI adapter
- `streaming-chat-server` - Streaming support for real-time responses
- `chat-server-with-data` - Server with database/context injection
- `chat-server-with-threads` - Persistent conversation threads
- `server-with-authentication` - Auth-protected endpoints

### 3. Consult References for Details

Load reference documentation as needed for deep implementation details:

- **[getting-started.md](references/getting-started.md)** - Installation, setup, hook overview
- **[core-concepts.md](references/core-concepts.md)** - Generative UI, tool calling, JS runtime, streaming
- **[structured-data.md](references/structured-data.md)** - Skillet schema language for type-safe JSON output
- **[platform-integration.md](references/platform-integration.md)** - LLM provider adapters (OpenAI, Anthropic, Google, etc.)
- **[advanced-guides.md](references/advanced-guides.md)** - Chatbots, threads, MCP, predictive actions
- **[best-practices.md](references/best-practices.md)** - Prompt engineering, model selection, ethics
- **[INDEX.md](references/INDEX.md)** - Navigation map of all documentation

## Core Capabilities

### 1. Generative UI

Expose React components to the LLM so it can render your UI dynamically.

```tsx
import { useUiChat, exposeComponent } from '@hashbrownai/react'
import { s } from '@hashbrownai/core'
import { MyCard } from './MyCard'

const exposedCard = exposeComponent(MyCard, {
  name: 'MyCard',
  description: 'A card to display information',
  props: { title: s.string('The title'), content: s.string('The body') },
})

const { messages } = useUiChat({
  components: [exposedCard],
  model: 'gpt-4',
  system: 'Render cards to show information to the user.',
})

// messages[1].ui will contain <MyCard title="..." content="..." />
```

**When to use**: Build browser agents, dynamic dashboards, form builders, or any UI that should adapt based on LLM decisions.

**Reference**: See [core-concepts.md](references/core-concepts.md) for detailed component exposure patterns.

### 2. Client-Side Tool Calling

Allow the LLM to call client-side functions to access app state or perform actions.

```tsx
import { useChat, useTool } from '@hashbrownai/react'

const getUserTool = useTool({
  name: 'getUser',
  description: 'Get current user information',
  handler: async () => ({ name: 'Jane Doe' }),
  deps: [],
})

const { messages } = useChat({
  tools: [getUserTool],
  model: 'gpt-4',
})
```

**When to use**: Let the LLM access application state, trigger actions, or interact with external APIs.

**Reference**: See [core-concepts.md](references/core-concepts.md) for tool definition patterns.

### 3. Structured Data Output

Use Skillet schemas to get type-safe, validated JSON from the LLM.

```tsx
import { useStructuredCompletion } from '@hashbrownai/react'
import { s } from '@hashbrownai/core'

const schema = s.object('Response', {
  name: s.string('User name'),
  age: s.number('User age'),
  interests: s.array('List of interests', s.string('An interest')),
})

const { data } = useStructuredCompletion({
  schema,
  model: 'gpt-4',
  prompt: 'Extract user info: John is 30 and likes hiking and reading.',
})

// data will be typed as { name: string; age: number; interests: string[] }
```

**When to use**: Extract structured information, build forms from natural language, parse documents, or transform unstructured text to JSON.

**Reference**: See [structured-data.md](references/structured-data.md) for Skillet schema language details.

### 4. Sandboxed JavaScript Execution

Execute LLM-generated JavaScript safely in a WASM-based QuickJS sandbox.

```tsx
import { useRuntime, useToolJavaScript, useChat } from '@hashbrownai/react'

const runtime = useRuntime({ functions: [] })
const jsTool = useToolJavaScript({ runtime })
const chat = useChat({ tools: [jsTool], model: 'gpt-4' })
```

**When to use**: Let the LLM perform complex calculations, data transformations, or generate visualizations using code.

**Reference**: See [core-concepts.md](references/core-concepts.md) for runtime configuration.

### 5. Platform Integration

Connect to any LLM provider via backend adapters:

```typescript
// Backend server (Node.js)
import { HashbrownOpenAI } from '@hashbrownai/openai'

const stream = HashbrownOpenAI.stream.text({
  apiKey: process.env.OPENAI_API_KEY,
  request,
})
```

**Supported platforms**: OpenAI, Anthropic, Google, Azure, Bedrock, Ollama, Writer, and custom adapters.

**Reference**: See [platform-integration.md](references/platform-integration.md) for all adapter configurations.

## Common Patterns

### Building a Chat Interface

1. Generate component: `python scripts/generate-component.py simple-chat ./src`
2. Generate server: `python scripts/generate-server.py basic-chat-server ./backend`
3. Wrap app in `<HashbrownProvider url="/api/chat">`
4. Customize system prompt and model in component

### Adding Generative UI

1. Generate: `python scripts/generate-component.py ui-chat-with-components ./src`
2. Create presentational React components
3. Expose with `exposeComponent(Component, { name, description, props })`
4. Pass to `useUiChat({ components: [...] })`
5. Write system prompt instructing when to use components

### Implementing Tool Calling

1. Define tools with `useTool({ name, description, handler })`
2. Pass to chat hook: `useChat({ tools: [...] })`
3. Tools are automatically called by the LLM when needed
4. Tool results are sent back to LLM in the conversation

### Streaming Structured Data

1. Use `s.streaming` modifier in Skillet schema:
   ```tsx
   const schema = s.object('Re