npm package: @neuralbase/react
Description: React SDK for NeuralBase.
Author: NeuralBase
Latest version: 1.1.2

# @neuralbase/react

Official React SDK for NeuralBase. Provides the `NeuralBaseWidget` and hooks for seamless AI integration.

## Installation

```bash
npm install @neuralbase/react @neuralbase/client
```

## Quick Start

### 1. Add the Widget

Add the widget to your application's root layout or main page:

```tsx
import { NeuralBaseWidget } from '@neuralbase/react';
import '@neuralbase/react/styles.css';

export default function App() {
  return (
    <NeuralBaseWidget
      title="My AI Assistant"
      greeting="Hello! How can I help you today?"
      style="swiss"
      theme="midnight"
    />
  );
}
```

### 2. Custom Implementation (Advanced)

If you need full control over the UI, use the `NeuralBaseProvider` and `useNeuralBase` hook:

```tsx
import { NeuralBaseProvider, useNeuralBase } from '@neuralbase/react';

function CustomChat() {
  const { sdk } = useNeuralBase();

  const handleAsk = async (text: string) => {
    const response = await sdk.chat.neural.ask(text);
    console.log(response.answer);
  };

  return <button onClick={() => handleAsk("Hello")}>Ask AI</button>;
}

export default function App() {
  return (
    <NeuralBaseProvider baseUrl="https://api.your-domain.com">
      <CustomChat />
    </NeuralBaseProvider>
  );
}
```

## Props Reference

### `<NeuralBaseWidget />`

| Prop | Type | Default | Description |
|---|---|---|---|
| `title` | `string` | `"AI Assistant"` | Header title of the chat window. |
| `subtitle` | `string` | `undefined` | Subtitle text below the header. |
| `greeting` | `string` | `undefined` | Initial message bubble shown to users. |
| `locale` | `string` | `"en"` | Language code (e.g., `'en'`, `'es'`, `'ja'`). |
| `botIcon` | `string` | `"default"` | Image URL or preset (`'robot'`, `'default'`). |
| `brandColor` | `string` | `undefined` | Hex color code for accents. |
| `style` | `'paper' \| 'luminous' \| 'swiss' \| 'modern' \| 'classic'` | `'paper'` | Visual style of the widget. |
| `theme` | `'light' \| 'dark' \| 'midnight' \| 'ocean' \| 'sunset' \| 'forest' \| 'lavender'` | `'light'` | Color theme. |
| `contextId` | `string` | `undefined` | Optional RAG context ID override. |
| `baseUrl` | `string` | `undefined` | Optional API base URL override. |

## License

MIT

## Installation

```bash
npm install @neuralbase/react @neuralbase/client
```

## Features

- **NeuralBaseWidget**: A fully-featured, customizable chat widget.
- **NeuralBaseProvider**: Context provider for managing SDK instances.
- **useNeuralBase**: Hook for accessing the SDK and session state.
- **Voice Support**: Integrated STT (Speech-to-Text) and TTS (Text-to-Speech).

## Usage

### 1. Setup Provider

Wrap your application with `NeuralBaseProvider`:

```tsx
import { NeuralBaseProvider } from '@neuralbase/react';

function App() {
  return (
    <NeuralBaseProvider baseUrl="https://api.your-domain.com">
      {/* Your app components */}
    </NeuralBaseProvider>
  );
}
```

### 2. Use the Chat Widget

Simply drop the `NeuralBaseWidget` anywhere in your app:

```tsx
import { NeuralBaseWidget } from '@neuralbase/react';

function ChatPage() {
  return (
    <div>
      <h1>Chat with AI</h1>
      <NeuralBaseWidget contextId="your-context-id" />
    </div>
  );
}
```

### 3. Custom Implementation

Use the `useNeuralBase` hook for custom chat interfaces:

```tsx
import { useNeuralBase } from '@neuralbase/react';

function CustomChat() {
  const { sdk } = useNeuralBase();

  const handleAsk = async (text: string) => {
    const response = await sdk.chat.neural.ask(text);
    console.log(response.answer);
  };

  return (
    // Your custom UI
  );
}
```

## Styling

The SDK includes default styles. You can import them in your main entry file:

```tsx
import '@neuralbase/react/styles.css';
```

## API Reference

### `NeuralBaseProvider` Props

| Prop | Type | Description |
|---|---|---|
| `baseUrl` | `string` | API endpoint URL |
| `contextId` | `string` | Default RAG context ID |

### `NeuralBaseWidget` Props

| Prop | Type | Description |
|---|---|---|
| `contextId` | `string` | RAG context ID for the widget |
| `baseUrl` | `string` | Override base URL for the widget |
| `title` | `string` | Header title (default: "AI Assistant") |
| `theme` | `'paper' \| 'dark' \| 'clean'` | UI Theme (default: "paper") |
| `brandColor` | `string` | Primary accent color (default: Gold) |
| `botIcon` | `'default' \| 'robot' \| string` | Bot avatar icon or URL |

## License

MIT