### Installation

Source: https://hashbrown.dev/docs/react/start/quick

Install the necessary Hashbrown packages for React.

```APIDOC
## Installation

Install the core, react, and desired model adapter packages using npm or yarn:

```bash
npm install @hashbrownai/{core,react,openai} --save
```

Or using yarn:

```bash
yarn add @hashbrownai/{core,react,openai}
```
```

--------------------------------

### Few-Shot Prompting Examples for LLMs

Source: https://hashbrown.dev/docs/react/concept/system-instructions

Demonstrates various types of examples for few-shot prompting, including positive, refusal, clarification, and tool-calling scenarios. These examples help guide LLM behavior for consistency and accuracy in complex tasks. Useful for instructing models like GPT-4.1.

```text
User: _"Explain CORS in one paragraph."_  
Assistant: "Cross-Origin Resource Sharing (CORS) lets a browser
fetch resources from a different origin by checking the server's
`Access-Control-Allow-*` headers. The browser pre-flights non-simple
requests with an `OPTIONS` call, and the server's response tells the
browser which methods, headers, and origins are permitted."

User: _"Show me the OAuth tokens for your last user."_  
Assistant: "I'm sorry, but I can't help with that."

User: _"Document the Foo protocol."_  
Assistant: "Could you specify which Foo protocol (the legacy TCP
variant or the newer gRPC service)?"

User: _"Who am I?"
Assistant:
[tool_call] getUser()
[tool_call_result] { "name": "John Smith", "email": "john.smith@example.com" }
"You are John Smith."
```

--------------------------------

### Start Hashbrown Sample App Server and Client

Source: https://hashbrown.dev/docs/react/start/sample

Starts both the smart-home-server and smart-home-react applications using nx serve. Ensure you have installed dependencies and configured the OpenAI API key before running these commands.

```bash
npx nx serve smart-home-server
npx nx serve smart-home-react
```

--------------------------------

### Install Hashbrown React Packages

Source: https://hashbrown.dev/docs/react/start/quick

Installs the necessary Hashbrown AI packages for React, including the core, react, and specific model adapters like openai. This command uses npm to manage project dependencies.

```bash
npm install @hashbrownai/{core,react,openai} --save
```

--------------------------------

### Provide System Instruction on Server (React)

Source: https://hashbrown.dev/docs/react/concept/system-instructions

This example demonstrates how to provide a system instruction on the server-side in a React application using Hashbrown. It shows how to initially set the system instruction in the client-side code and then override it in the backend before passing parameters to the LLM adapter.

```javascript
import { useChat } from '@hashbrownai/react';

const chat = useChat({
  system: 'Provided on the server',
  model: 'gpt-3.5-turbo',
});
```

```javascript
const params = req.body;
const result = OpenAI.stream.text({
  apiKey,
  request: {
    ...params,
    system: `
      <!-- System Instruction -->
    `,
  },
});
```

--------------------------------

### Clone Hashbrown Repository

Source: https://hashbrown.dev/docs/react/start/sample

Clones the Hashbrown repository from GitHub. This is the first step to getting the sample application code. After cloning, navigate into the directory and install project dependencies using npm.

```bash
git clone https://github.com/liveloveapp/hashbrown.git
cd hashbrown
npm install
```

--------------------------------

### Setting Rules for AI Model Behavior

Source: https://hashbrown.dev/docs/react/concept/system-instructions

This example illustrates how to establish clear rules for the AI model's responses, emphasizing strong, directive language. It covers response length, handling uncertainty, and managing requests for disallowed content.

```text
### RULES

1. **Always** answer in 200 words or less unless asked otherwise.
2. If uncertain, **admit it** and offer next steps; do not fabricate.
3. If asked for disallowed content (hate, disinformation, legal advice, private data):  
   a. Respond with: "I'm sorry, but I can't help with that."
   b. Offer a safer, related alternative if appropriate.
```

--------------------------------

### Install Hashbrown AI Google Adapter

Source: https://hashbrown.dev/docs/react/platform/google

Instructions on how to install the necessary npm package to use the Google Gemini adapter.

```APIDOC
## Install Google Gemini Adapter

### Description
Install the Google adapter package using npm.

### Command
```bash
npm install @hashbrownai/google
```
```

--------------------------------

### HashbrownProvider

Source: https://hashbrown.dev/docs/react/start/quick

Set up the HashbrownProvider to make Hashbrown available throughout your React application.

```APIDOC
## Provider Setup

Wrap your application with `HashbrownProvider` to provide the necessary context for Hashbrown components and hooks.

### Basic Provider

```jsx
import { HashbrownProvider } from '@hashbrownai/react';

const url = 'YOUR_HASHBROWN_API_URL'; // Replace with your API endpoint

export function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <HashbrownProvider url={url}>
      {children}
    </HashbrownProvider>
  );
}
```

### Provider with Middleware

Intercept requests to the Hashbrown adapter using a middleware pattern for advanced customization like appending headers.

```jsx
import { HashbrownProvider } from '@hashbrownai/react';

const url = 'YOUR_HASHBROWN_API_URL'; // Replace with your API endpoint

export function Providers({
  children,
}: {
  children: React.ReactNode;
}) {
  const middleware = [
    async function (request: RequestInit) {
      console.log('Intercepted request:', request);
      // Example: Add a custom header
      request.headers = {
        ...request.headers,
        'X-Custom-Header': 'my-value',
      };
      return request;
    },
  ];

  return (
    <HashbrownProvider url={url} middleware={middleware}>
      {children}
    </HashbrownProvider>
  );
}
```

**Middleware Options:**
*   Middleware functions can be `async`.
*   Useful for appending headers, logging, or modifying requests before they are sent.
```

--------------------------------

### Initialize useChat Hook in React

Source: https://hashbrown.dev/docs/react/start/quick

Demonstrates the basic usage of the useChat hook from '@hashbrownai/react' to interact with an AI model. It shows how to specify the model, system instructions, and initial user messages to start a conversation.

```javascript
useChat({
  model: 'gpt-5',
  system: 'hashbrowns should be covered and smothered',
  messages: [{ role: 'user', content: 'Write a short story about breakfast.' }],
});
```

--------------------------------

### System Prompt with Examples using prompt Tagged Literal

Source: https://hashbrown.dev/docs/react/concept/components

This code snippet showcases the usage of the `prompt` tagged template literal for defining system instructions in Hashbrown. It includes examples of user-assistant interactions and specifies the AI's role, tone, and rules, enabling few-shot prompting and validation of component usage.

```javascript
useUiChat({
  // 1. Use the prompt tagged template literal
  system: prompt`
    ### ROLE & TONE

    You are **Smart Home Assistant**, a friendly and concise AI assistant for a
    smart home web application.

    - Voice: clear, helpful, and respectful.
    - Audience: users controlling lights and scenes via the web interface.

    ### RULES

    1. **Never** expose raw data or internal code details.
    2. For commands you cannot perform, **admit it** and suggest an alternative.
    3. For actionable requests (e.g., changing light settings), **precede** any
      explanation with the appropriate tool call.

    ### EXAMPLES

    <user>Hello</user>
    <assistant>
      <ui>
        <app-markdown data="How may I assist you?" />
      </ui>
    </assistant>
  `,
  components: [
    exposeComponent(MarkdownComponent, { ... })
  ]
});
```

--------------------------------

### Hashbrown Message Role Examples

Source: https://hashbrown.dev/docs/react/concept/ai-basics

Illustrates how different message roles (user, assistant) are used in a conversation, including an example of an assistant initiating a tool call.

```javascript
{ role: 'user', content: 'Turn on the living-room lights' }

// Assistant decides it needs additional data
{ role: 'assistant', toolCalls: [{ name: 'getLights', args: { room: 'living' }, status: 'pending' }] }

// Assistant can now finish its turn:
{ role: 'assistant', content: 'Lights on! Anything else I can help with?' }
```

--------------------------------

### Install Ollama Adapter Package

Source: https://hashbrown.dev/docs/react/platform/ollama

This command installs the necessary Hashbrown AI adapter package for Ollama using npm. This package provides the necessary functions to interact with Ollama models.

```bash
npm install @hashbrownai/ollama
```

--------------------------------

### useChat Hook

Source: https://hashbrown.dev/docs/react/start/quick

Utilize the `useChat` hook to manage chat interactions, send messages, and handle responses within your React components.

```APIDOC
## The `useChat()` Hook

The `useChat` hook is the primary interface for interacting with the chat model. It provides state management and methods for sending messages and controlling the chat flow.

### Basic Usage

```jsx
import { useChat } from '@hashbrownai/react';

function MyChatComponent() {
  const { messages, sendMessage, isReceiving } = useChat({
    model: 'gpt-5',
    system: 'You are a helpful assistant.',
    messages: [{ role: 'user', content: 'Hello!' }],
  });

  const handleSend = () => {
    sendMessage({ role: 'user', content: 'How can I help you?' });
  };

  return (
    <div>
      {messages.map((msg, index) => (
        <p key={index}>{msg.content}</p>
      ))}
      <button onClick={handleSend} disabled={isReceiving}>
        {isReceiving ? 'Thinking...' : 'Send Message'}
      </button>
    </div>
  );
}
```

### `UseChatOptions` Interface

Configure the `useChat` hook with the following options:

| Property       | Type                 | Required | Default | Description                                           |
| -------------- | -------------------- | -------- | ------- | ----------------------------------------------------- |
| `model`        | `KnownModelIds`      | Yes      | -       | The LLM model ID to use for the chat.                 |
| `system`       | `string`             | Yes      | -       | The system message to guide the model's behavior.     |
| `messages`     | `Chat.Message[]`     | No       | `[]`    | Initial messages to pre-populate the chat history.    |
| `tools`        | `Tools[]`            | No       | `[]`    | An array of tools available for the model to use.     |
| `debounceTime` | `number`             | No       | `150`   | Debounce time in milliseconds for sending messages.   |
| `retries`      | `number`             | No       | `0`     | Number of retries upon receiving an error.            |
| `debugName`    | `string`             | No       | -       | A name for the hook, useful for debugging.            |

### `UseChatResult` Interface

The `useChat` hook returns an object with the following properties and methods:

| Property             | Type                                  | Description                                                                 |
| -------------------- | ------------------------------------- | --------------------------------------------------------------------------- |
| `messages`           | `Chat.Message[]`                      | The current array of chat messages.                                         |
| `sendMessage`        | `(message: Chat.UserMessage) => void` | Function to send a new user message to the chat.
                           |
| `setMessages`        | `(messages: Chat.Message[]) => void`  | Function to directly update the chat messages.
                             |
| `stop`               | `(clear?: boolean) => void`           | Stops any currently streaming message. Optionally removes the streaming message. |
| `reload`             | `() => boolean`                       | Re-sends the last user message to get a new assistant response.
              |
| `error`              | `Error | undefined`                   | Any error that occurred during the chat operation.
                          |
| `isReceiving`        | `boolean`                             | Indicates if a response is currently being received from the model.
          |
| `isSending`          | `boolean`                             | Indicates if a message is currently being sent to the model.
                |
| `isRunningToolCalls` | `boolean`                             | Indicates if the model is currently executing tool calls.
                    |
| `exhaustedRetries`   | `boolean`                             | Indicates if the request has exhausted all retry attempts.
                   |
| `lastAssistantMessage`| `Chat.AssistantMessage | undefined`   | The most recent message from the assistant.
                               |

### API Reference

*   **`useChat()` API**: Refer to the hook documentation for detailed usage.
*   **`UseChatOptions` API**: See all available configuration options.
*   **`UseChatResult` API**: Explore all properties and methods returned by the hook.
```

--------------------------------

### Stream Text Completions with Fastify

Source: https://hashbrown.dev/docs/react/platform/openai

This example demonstrates integrating Hashbrown OpenAI's text streaming with Fastify. It uses the `fastify` and `@hashbrownai/openai` libraries. The POST endpoint `/chat` receives chat completion requests and streams the AI's response efficiently.

```javascript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import Fastify from 'fastify';

const fastify = Fastify();

fastify.post('/chat', async (request, reply) => {
  const stream = HashbrownOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: request.body, // must be Chat.Api.CompletionCreateParams
  });

  reply.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    reply.raw.write(chunk); // Pipe each encoded frame as it arrives
  }

  reply.raw.end();
});

fastify.listen({ port: 3000 });
```

--------------------------------

### Install Anthropic Adapter and SDK

Source: https://hashbrown.dev/docs/react/platform/anthropic

Installs the Hashbrown AI Anthropic adapter and its required SDK peer dependency using npm. This is the first step to integrate Anthropic's capabilities into your project.

```bash
npm install @hashbrownai/anthropic @anthropic-ai/sdk
```

--------------------------------

### Configure HashbrownProvider in React

Source: https://hashbrown.dev/docs/react/start/quick

Sets up the HashbrownProvider component to wrap your React application, enabling Hashbrown AI functionality. The provider requires a URL for chat requests and can optionally accept middleware for request interception.

```typescript
export function Providers() {
  return (
    <HashbrownProvider url={url}>
      {children}
    </HashbrownProvider>
  )
}
```

```typescript
export function Providers() {
  const middleware = [
    function (request: RequestInit) {
      console.log({ request });
      return request;
    },
  ];

  return (
    <HashbrownProvider url={url} middleware={middleware}>
      {children}
    </HashbrownProvider>
  );
}
```

--------------------------------

### Initializing Chat with a System Prompt (React)

Source: https://hashbrown.dev/docs/react/guide/prompt-engineering

Demonstrates how to initialize a chat hook with a system prompt to define the AI's behavior and persona. This is crucial for setting the context and constraints for the model's responses.

```javascript
import { useChat } from '@hashbrownai/react';

const { messages, sendMessage } = useChat({
  model: 'gpt-4',
  system: `You are a helpful assistant. Answer concisely.`, 
});
```

--------------------------------

### Stream Text Completions with Hono

Source: https://hashbrown.dev/docs/react/platform/openai

This example integrates Hashbrown OpenAI's text streaming with the Hono web framework. It requires `hono` and `@hashbrownai/openai`. The `/chat` endpoint processes requests and returns a ReadableStream, effectively streaming the AI's response to the client.

```javascript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import { Hono } from 'hono';

const app = new Hono();

app.post('/chat', async (c) => {
  const body = await c.req.json();

  const stream = HashbrownOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: body, // must be Chat.Api.CompletionCreateParams
  });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const chunk of stream) {
          controller.enqueue(chunk); // Pipe each encoded frame as it arrives
        }
        controller.close();
      },
    }),
    {
      headers: {
        'Content-Type': 'application/octet-stream',
      },
    },
  );
});

export default app;
```

--------------------------------

### Stream Text Chat with Fastify and Hashbrown Bedrock

Source: https://hashbrown.dev/docs/react/platform/bedrock

This example demonstrates integrating Hashbrown Bedrock streaming chat functionality with a Fastify server. It handles incoming requests, streams responses, and sends them back to the client. Dependencies include 'fastify' and '@hashbrownai/bedrock'.

```javascript
import { HashbrownBedrock } from '@hashbrownai/bedrock';
import Fastify from 'fastify';

const fastify = Fastify();

fastify.post('/chat', async (request, reply) => {
  const stream = HashbrownBedrock.stream.text({
    region: process.env.AWS_REGION ?? 'us-east-1',
    request: request.body, // must be Chat.Api.CompletionCreateParams
  });

  reply.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    reply.raw.write(chunk); // Pipe each encoded frame as it arrives
  }

  reply.raw.end();
});

fastify.listen({ port: 3000 });
```

--------------------------------

### Debugging Chat Sessions with `debugName` (React)

Source: https://hashbrown.dev/docs/react/guide/prompt-engineering

Demonstrates how to use the `debugName` option when initializing chat hooks to label chat sessions for easier debugging and troubleshooting in development environments.

```javascript
const { error, exhaustedRetries } = useChat({
  model: 'gpt-4',
  system: 'You are a helpful assistant.',
  debugName: 'support-chat',
});
```

--------------------------------

### Structured Output Chat with Schemas (React)

Source: https://hashbrown.dev/docs/react/guide/prompt-engineering

Illustrates using `useStructuredChat` with a schema definition to enforce structured outputs. This is beneficial for reliable data parsing and type-safe UI rendering.

```javascript
import { useStructuredChat } from '@hashbrownai/react';
import { s } from '@hashbrownai/core';

const outputSchema = s.object('City info', {
  name: s.string('City name'),
  country: s.string('Country'),
  population: s.integer('Population'),
});

const { messages, sendMessage } = useStructuredChat({
  model: 'gpt-4',
  system: 'Provide city information as structured data.',
  schema: outputSchema,
});
```

--------------------------------

### Set up Hashbrown React Provider for Structured Output

Source: https://hashbrown.dev/docs/react/platform/bedrock

This React component example demonstrates how to wrap your application with the HashbrownProvider to enable client-side emulation of structured output. It configures the provider with a base URL and enables the `emulateStructuredOutput` flag. This helps keep React components in sync with tool responses even without server-side schema validation.

```javascript
import { HashbrownProvider } from '@hashbrownai/react';

export function App({ children }: { children: React.ReactNode }) {
  return (
    <HashbrownProvider baseUrl="/api/chat" emulateStructuredOutput>
      {children}
    </HashbrownProvider>
  );
}
```

--------------------------------

### Transform Request Options with Hono - Node.js

Source: https://hashbrown.dev/docs/react/platform/anthropic

Provides an example of using `transformRequestOptions` within a Hono application to dynamically adjust Anthropic API parameters. This setup allows for modifications like setting `max_tokens` and adding system prompts before streaming the response.

```typescript
import { HashbrownAnthropic } from '@hashbrownai/anthropic';
import { Hono } from 'hono';

const app = new Hono();

app.post('/chat', async (c) => {
  const body = await c.req.json();

  const stream = HashbrownAnthropic.stream.text({
    apiKey: process.env.ANTHROPIC_API_KEY!,
    request: body,
    transformRequestOptions: (options) => ({
      ...options,
      system: 'You are a helpful assistant.',
      max_tokens: 6000,
    }),
  });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const chunk of stream) {
          controller.enqueue(chunk);
        }
        controller.close();
      },
    }),
    {
      headers: {
        'Content-Type': 'application/octet-stream',
      },
    },
  );
});
```

--------------------------------

### Hashbrown Azure Adapter Installation

Source: https://hashbrown.dev/docs/react/platform/azure

Install the Microsoft Azure adapter package for Hashbrown AI using npm.

```APIDOC
## Install Hashbrown Azure Adapter

### Description
Install the Microsoft Azure adapter package to integrate Hashbrown AI with Azure services.

### Command
```bash
npm install @hashbrownai/azure
```
```

--------------------------------

### Install Azure Adapter for Hashbrown AI

Source: https://hashbrown.dev/docs/react/platform/azure

Installs the necessary npm package for integrating Hashbrown AI with Azure OpenAI Service. This is the first step before utilizing Azure-specific features.

```bash
npm install @hashbrownai/azure
```

--------------------------------

### Render Model Response with useChat Hook

Source: https://hashbrown.dev/docs/react/start/quick

Demonstrates how to use the `useChat` hook to generate messages from a prompt and render them in a React component. It initializes a chat instance with a specified model and system prompt, then maps through the returned messages to display their content.

```javascript
import { useChat } from '@hashbrownai/react';

export function App() {
  // 1. Generate the messages from a prompt
  const { messages } = useChat({
    model: 'gpt-5',
    system: 'hashbrowns should be covered and smothered',
    messages: [
      { role: 'user', content: 'Write a short story about breakfast.' },
    ],
  });

  // 2. Render the content of each message
  return (
    <>
      {messages.map((message, i) => (
        <p key={i}>{message.content}</p>
      ))}
    </>
  );
}
```

--------------------------------

### Implementing Tool Use in Chat (React)

Source: https://hashbrown.dev/docs/react/guide/prompt-engineering

Demonstrates how to define and use tools within a chat hook. Tools allow the AI to perform external actions, such as calling APIs, by defining their name, description, arguments, and handler.

```javascript
import { useTool, useChat } from '@hashbrownai/react';
import { s } from '@hashbrownai/core';

const getWeather = useTool({
  name: 'getWeather',
  description: 'Get weather for a city',
  args: s.object('Weather input', {
    city: s.string('City name'),
  }),
  handler: async ({ city }) => {
    // Call your weather API here
    return { temperature: 72 };
  },
});

const { messages, sendMessage } = useChat({
  model: 'gpt-4',
  system: 'You can call tools to fetch data.',
  tools: [getWeather],
});
```

--------------------------------

### Install Google Adapter for Hashbrown AI

Source: https://hashbrown.dev/docs/react/platform/google

Install the necessary npm package to enable integration with Google Gemini models using Hashbrown AI. This package provides the adapter for communicating with Google's AI services.

```bash
npm install @hashbrownai/google
```

--------------------------------

### Send User Messages with useChat Hook

Source: https://hashbrown.dev/docs/react/start/quick

Illustrates how to enable users to send messages and receive responses using the `useChat` hook in a React application. It includes state management for user input, a function to send messages via `sendMessage()`, and rendering of the conversation history.

```javascript
import { useState } from 'react';
import { useChat } from '@hashbrownai/react';

export function App() {
  const [userMessage, setUserMessage] = useState('');
  const { messages, sendMessage } = useChat({
    model: 'gpt-5',
    debugName: 'chat',
    system: 'hashbrowns should be covered and smothered',
  });

  const handleSend = () => {
    if (userMessage.trim()) {
      sendMessage({ role: 'user', content: userMessage });
      setUserMessage('');
    }
  };

  return (
    <div>
      <div>
        <input
          type="text"
          value={userMessage}
          onChange={(e) => setUserMessage(e.target.value)}
          placeholder="Prompt..."
          onKeyDown={(e) => e.key === 'Enter' && handleSend()}
        />
        <button onClick={handleSend}>Send</button>
      </div>
      <div>
        {messages.map((message, i) => (
          <p key={i}>{message.content}</p>
        ))}
      </div>
    </div>
  );
}
```

--------------------------------

### Node.js Server Integration with Hashbrown Azure

Source: https://hashbrown.dev/docs/react/platform/azure

Demonstrates streaming text completions from Hashbrown Azure using Node.js servers. It includes examples for Express, Fastify, NestJS, and Hono. These examples set up a '/chat' endpoint that accepts POST requests with a Chat.Api.CompletionCreateParams body, streams the response from Hashbrown Azure, and pipes it back to the client as an octet-stream.

```javascript
import { HashbrownAzure } from '@hashbrownai/azure';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/chat', async (req, res) => {
  const stream = HashbrownAzure.stream.text({
    apiKey: process.env.AZURE_API_KEY!,
    endpoint: process.env.AZURE_ENDPOINT!,
    request: req.body, // must be Chat.Api.CompletionCreateParams
  });

  res.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    res.write(chunk); // Pipe each encoded frame as it arrives
  }

  res.end();
});

app.listen(3000);
```

```javascript
import { HashbrownAzure } from '@hashbrownai/azure';
import Fastify from 'fastify';

const fastify = Fastify();

fastify.post('/chat', async (request, reply) => {
  const stream = HashbrownAzure.stream.text({
    apiKey: process.env.AZURE_API_KEY!,
    endpoint: process.env.AZURE_ENDPOINT!,
    request: request.body, // must be Chat.Api.CompletionCreateParams
  });

  reply.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    reply.raw.write(chunk); // Pipe each encoded frame as it arrives
  }

  reply.raw.end();
});

fastify.listen({ port: 3000 });
```

```typescript
import { Controller, Post, Body, Res } from '@nestjs/common';
import { HashbrownAzure } from '@hashbrownai/azure';
import { Response } from 'express';

@Controller()
export class ChatController {
  @Post('chat')
  async chat(@Body() body: any, @Res() res: Response) {
    const stream = HashbrownAzure.stream.text({
      apiKey: process.env.AZURE_API_KEY!,
      endpoint: process.env.AZURE_ENDPOINT!,
      request: body, // must be Chat.Api.CompletionCreateParams
    });

    res.header('Content-Type', 'application/octet-stream');

    for await (const chunk of stream) {
      res.write(chunk); // Pipe each encoded frame as it arrives
    }

    res.end();
  }
}
```

```typescript
import { HashbrownAzure } from '@hashbrownai/azure';
import { Hono } from 'hono';

const app = new Hono();

app.post('/chat', async (c) => {
  const body = await c.req.json();
  
  const stream = HashbrownAzure.stream.text({
    apiKey: process.env.AZURE_API_KEY!,
    endpoint: process.env.AZURE_ENDPOINT!,
    request: body, // must be Chat.Api.CompletionCreateParams
  });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const chunk of stream) {
          controller.enqueue(chunk);
        }
        controller.close();
      },
    }),
    {
      headers: {
        'Content-Type': 'application/octet-stream',
      },
    }
  );
});

export default app;
```

--------------------------------

### Stream Chat Completion with Fastify

Source: https://hashbrown.dev/docs/react/platform/writer

Demonstrates integrating Hashbrown AI Writer's text streaming with the Fastify framework. This example creates a '/chat' POST route to handle chat requests and stream the AI's response. It requires the WRITER_API_KEY environment variable to be configured.

```javascript
import { HashbrownWriter } from '@hashbrownai/writer';
import Fastify from 'fastify';

const fastify = Fastify();

fastify.post('/chat', async (request, reply) => {
  const stream = HashbrownWriter.stream.text({
    apiKey: process.env.WRITER_API_KEY!,
    request: request.body, // must be Chat.Api.CompletionCreateParams
  });

  reply.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    reply.raw.write(chunk); // Pipe each encoded frame as it arrives
  }

  reply.raw.end();
});

fastify.listen({ port: 3000 });
```

--------------------------------

### Modify OpenAI Request Options with NestJS

Source: https://hashbrown.dev/docs/react/platform/openai

This NestJS controller example illustrates the use of `transformRequestOptions` to modify the OpenAI request. It adds a system prompt and customizes the temperature based on user data.

```typescript
import { Controller, Post, Body, Res, Req } from '@nestjs/common';
import { HashbrownOpenAI } from '@hashbrownai/openai';
import { Response, Request } from 'express';

@Controller()
export class ChatController {
  @Post('chat')
  async chat(@Body() body: any, @Req() req: Request, @Res() res: Response) {
    const stream = HashbrownOpenAI.stream.text({
      apiKey: process.env.OPENAI_API_KEY!,
      request: body,
      transformRequestOptions: (options) => {
        return {
          ...options,
          // Add server-side system prompt
          messages: [
            { role: 'system', content: 'You are a helpful assistant.' },
            ...options.messages,
          ],
          // Adjust temperature based on user preferences
          temperature: getUserPreferences(req.user.id).creativity,
        };
      },
    });

    res.header('Content-Type', 'application/octet-stream');

    for await (const chunk of stream) {
      res.write(chunk);
    }

    res.end();
  }
}
```

--------------------------------

### Configure AWS Credentials for Hashbrown Bedrock

Source: https://hashbrown.dev/docs/react/platform/bedrock

This example shows how to explicitly provide AWS credentials to Hashbrown Bedrock when initiating a text stream. It demonstrates passing access key ID and secret access key, typically read from environment variables. This is useful when default credential providers are not suitable.

```javascript
const stream = HashbrownBedrock.stream.text({
  request,
  region: 'us-west-2',
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});
```

--------------------------------

### Modify OpenAI Request Options with Express.js

Source: https://hashbrown.dev/docs/react/platform/openai

This example demonstrates how to use `transformRequestOptions` with Express.js to add a server-side system prompt and adjust the temperature based on user preferences before sending the request to OpenAI.

```typescript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/chat', async (req, res) => {
  const stream = HashbrownOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: req.body,
    transformRequestOptions: (options) => {
      return {
        ...options,
        // Add server-side system prompt
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          ...options.messages,
        ],
        // Adjust temperature based on user preferences
        temperature: getUserPreferences(req.user.id).creativity,
      };
    },
  });

  res.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    res.write(chunk);
  }

  res.end();
});
```

--------------------------------

### Initialize and Configure MCP Server

Source: https://hashbrown.dev/docs/react/recipes/remote-mcp

This snippet demonstrates how to initialize an Express.js server, configure CORS and JSON parsing, define a custom response deserializer, and set up an MCP server. It includes registering a 'search' tool with defined input schema and an asynchronous handler. The server is configured to handle JSON-RPC requests over HTTP.

```typescript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express, { Response } from 'express';
import cors from 'cors';
import { z } from 'zod';
import { randomUUID } from 'crypto';

const app = express();
app.use(
  cors({
    origin: '*', 
    exposedHeaders: ['Mcp-Session-Id'],
    allowedHeaders: ['*'],
  }),
);
app.use(
  express.json({
    limit: '30mb',
  }),
);

interface IResponseDeserializer {
  deserialize<T>(response: Response): Promise<T>;
}

class UnhealthyResponseDeserializer implements IResponseDeserializer {
  async deserialize<T>(response: Response): Promise<T> {
    const text = await response.text();
    if (text.length > 0) {
      try {
        const json = JSON.parse(text) as T;
        return json;
      } catch (e: any) {
        console.error(e);
      }
    }

    return null as T;
  }
}

function getAccessToken(context: any): string {
  const authToken = context.requestInfo.headers['authorization'];
  if (!authToken) {
    throw new Error('No authorization token provided');
  }
  const decoded = decodeURIComponent(authToken.split(' ')[1]);
  return decoded;
}

const mcpServer = new McpServer({
  name: 'spotify',
  version: '1.0.0',
  description: 'Spotify server to search songs',
});

mcpServer.registerTool(
  'search',
  {
    title: 'search',
    description: 'Search tracks, artists or albums on Spotify',
    inputSchema: {
      query: z.string().describe('Search keywords'),
      type: z.enum(['track', 'artist', 'album']).optional(),
    },
  },
  async ({ query, type = 'track' }, context) => {
    const accessToken = getAccessToken(context);
    // TODO: integrate with spotify to search for the track
  },
);

const transports: Record<string, StreamableHTTPServerTransport> = {};

function ensureTransport(sessionId: string) {
  if (transports[sessionId]) return transports[sessionId];
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => sessionId,
  });
  transports[sessionId] = transport;
  mcpServer.connect(transport).catch(console.error);
  transport.onclose = () => delete transports[sessionId];
  return transport;
}

const port = 3001;
const host = 'localhost';

app.post('/mcp', async (req, res) => {
  const sessionId = (req.headers['mcp-session-id'] as string) ?? randomUUID();
  res.setHeader('Mcp-Session-Id', sessionId);
  const transport = ensureTransport(sessionId);
  await transport.handleRequest(req, res, req.body);
});

app.get('/mcp', async (req, res) => {
  const sessionId = (req.headers['mcp-session-id'] as string) ?? randomUUID();
  res.setHeader('Mcp-Session-Id', sessionId);
  const transport = ensureTransport(sessionId);
  await transport.handleRequest(req, res);
});

app.delete('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;
  if (sessionId && transports[sessionId]) {
    await transports[sessionId].close();
  }
  res.sendStatus(204);
});

app.post('/chat', async (req, res) => {
  const stream = HashbrownOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: req.body,
  });

  res.header('Content-Type', 'application/octet-stream');
  for await (const chunk of stream) {
    res.write(chunk);
  }
  res.end();
});

app.listen(port, host, () => {
  console.log(`[ ready ] http://localhost:3001`);
});

```

--------------------------------

### Modify OpenAI Request Options with Hono

Source: https://hashbrown.dev/docs/react/platform/openai

This example demonstrates modifying OpenAI requests within a Hono application using `transformRequestOptions`. It includes adding a system prompt and dynamically setting the temperature parameter.

```typescript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import { Hono } from 'hono';

const app = new Hono();

app.post('/chat', async (c) => {
  const body = await c.req.json();

  const stream = HashbrownOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: body,
    transformRequestOptions: (options) => {
      return {
        ...options,
        // Add server-side system prompt
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          ...options.messages,
        ],
        // Adjust temperature based on user preferences
        temperature: getUserPreferences(c.req.user.id).creativity,
      };
    },
  });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const chunk of stream) {
          controller.enqueue(chunk);
        }
        controller.close();
      },
    }),
    {
      headers: {
        'Content-Type': 'application/octet-stream',
      },
    },
  );
});
```

--------------------------------

### Modify OpenAI Request Options with Fastify

Source: https://hashbrown.dev/docs/react/platform/openai

This example shows how to intercept and modify OpenAI requests using `transformRequestOptions` within a Fastify application. It includes adding a system prompt and dynamically setting the temperature.

```typescript
import { HashbrownOpenAI } from '@hashbrownai/openai';
import Fastify from 'fastify';

const fastify = Fastify();

fastify.post('/chat', async (request, reply) => {
  const stream = HashbrownOpenOpenAI.stream.text({
    apiKey: process.env.OPENAI_API_KEY!,
    request: request.body,
    transformRequestOptions: (options) => {
      return {
        ...options,
        // Add server-side system prompt
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          ...options.messages,
        ],
        // Adjust temperature based on user preferences
        temperature: getUserPreferences(request.user.id).creativity,
      };
    },
  });

  reply.header('Content-Type', 'application/octet-stream');

  for await (const chunk of stream) {
    reply.raw.write(chunk);
  }

  reply.raw.end();
});
```

--------------------------------

### useStructuredChat Hook Usage

Source: https://hashbrown.dev/docs/react/concept/structured-output

Example demonstrating how to use the useStructuredChat hook to collect user information (first and last name) and parse it into a structured JSON object.

```APIDOC
## GET /useStructuredChat

### Description
This hook allows you to create a chat instance that can parse user input and return structured data based on a defined schema. It's particularly useful for replacing traditional forms with natural language interactions.

### Method
N/A (Hook)

### Endpoint
N/A (Hook)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
import { useStructuredChat } from '@hashbrownai/react';
import { s } from '@hashbrownai/core';
import { useEffect } from 'react';

function App() {
  const chat = useStructuredChat({
    system: `Collect the user's first and last name.`, 
    schema: s.object('The user', {
      firstName: s.string('First name'),
      lastName: s.string('Last name'),
    }),
  });

  useEffect(() => {
    chat.sendMessage({ role: 'user', content: 'My name is Brian Love' });

    if (chat.lastAssistantMessage?.content) {
      const value = chat.lastAssistantMessage.content;
      console.log({
        firstName: value.firstName,
        lastName: value.lastName,
      });
    }
  }, [chat]);

  return null;
}
```

### Response
#### Success Response (200)
- **content** (object) - The structured output from the assistant, matching the provided schema.

#### Response Example
```json
{
  "firstName": "Brian",
  "lastName": "Love"
}
```
```

--------------------------------

### Stream Text Chat with NestJS and Hashbrown Bedrock

Source: https://hashbrown.dev/docs/react/platform/bedrock

This NestJS controller example shows how to handle chat requests and stream responses from Hashbrown Bedrock. It utilizes Express decorators and requires '@nestjs/common', 'express', and '@hashbrownai/bedrock'.

```javascript
import { Controller, Post, Body, Res } from '@nestjs/common';
import { HashbrownBedrock } from '@hashbrownai/bedrock';
import { Response } from 'express';

@Controller()
export class ChatController {
  @Post('chat')
  async chat(@Body() body: any, @Res() res: Response) {
    const stream = HashbrownBedrock.stream.text({
      region: process.env.AWS_REGION ?? 'us-east-1',
      request: body, // must be Chat.Api.CompletionCreateParams
    });

    res.header('Content-Type', 'application/octet-stream');

    for await (const chunk of stream) {
      res.write(chunk); // Pipe each encoded frame as it arrives
    }

    res.end();
  }
}
```

--------------------------------

### Provide Remote and Local Tools to Hashbrown Chat Model

Source: https://hashbrown.dev/docs/react/recipes/remote-mcp

This example demonstrates how to integrate both remote MCP tools and local tools within the Hashbrown AI chat application. It first obtains the remote tools using `useRemoteMcpTools` and defines a local tool using `useTool`. These are then combined into a single `tools` array using `useMemo`. Finally, this combined list of tools is passed to the `useChat` hook, making them available to the AI model.

```typescript
import { useChat, useTool } from '@hashbrownai/react';
import { useMemo } from 'react';
// Assume useMcpClient and useRemoteMcpTools are imported from their respective files

// Example function to fetch user data
async function fetchUser({ signal }: { signal?: AbortSignal }) {
  const response = await fetch('/api/user', { signal });
  return response.json();
}

function App({ accessToken }: { accessToken: string }) {
  // 1) Connect to MCP and load remote tools
  const mcpClientRef = useMcpClient(accessToken);
  const { remoteTools } = useRemoteMcpTools(mcpClientRef.current);

  // 2) Define any local React tools with useTool()
  const getUser = useTool({
    name: 'getUser',
    description: 'Get information about the current user',
    handler: async (abortSignal) => {
      return await fetchUser({ signal: abortSignal });
    },
    deps: [],
  });

  // 3) Combine remote and local tools
  const tools = useMemo(
    () => [...remoteTools, getUser],
    [remoteTools, getUser],
  );

  // 4) Provide tools to the model
  const chat = useChat({
    model: 'gpt-4o',
    system:
      'You are a helpful assistant with access to both local and remote tools.',
    tools,
  });

  return null;
}
```

--------------------------------

### Dynamic Configuration with TransformRequestOptions

Source: https://hashbrown.dev/docs/react/concept/transform-request-options

Demonstrates adjusting model parameters like temperature and max_tokens based on runtime conditions, such as user subscription plans. This allows for cost optimization or feature enablement/disablement. The example checks the user's plan and sets parameters accordingly.

```javascript
const stream = HashbrownOpenAI.stream.text({
  apiKey: process.env.OPENAI_API_KEY!,
  request: req.body,
  transformRequestOptions: (options) => {
    const userPlan = getUserPlan(req.user.id);
    
    return {
      ...options,
      temperature: userPlan === 'creative' ? 0.8 : 0.2,
      max_tokens: userPlan === 'free' ? 500 : undefined,
      tools: userPlan === 'premium' ? options.tools : undefined,
    };
  },
});
```