brainkb-assistant/README.md

A configurable, standalone BrainKB Assistant that can be integrated into any website

# BrainKB Assistant

A configurable, standalone chat widget that can be integrated into any website. It supports REST APIs, WebSocket connections, and provides a rich set of features for knowledge base interactions.

## 🚀 Quick Start

### Installation

```bash
npm install brainkb-assistant
```

### Basic Usage

```jsx
import BrainKBAssistant from 'brainkb-assistant';

function App() {
  const config = {
    api: {
      endpoint: 'https://api.example.com/chat',
      type: 'rest'
    },
    branding: {
      title: 'BrainKB Assistant'
    }
  };

  return (
    <div>
      <h1>My Website</h1>
      <BrainKBAssistant config={config} />
    </div>
  );
}
```

## ✨ Features

- **🔧 Configurable** - Easy to customize branding, features, and API endpoints
- **🌐 Universal** - Works with React, Next.js, static HTML, and any web framework
- **📱 Responsive** - Adapts to different screen sizes and devices
- **🎯 Context Aware** - Automatically detects current page content
- **💬 Rich Chat** - Markdown support, file uploads, quick actions
- **📊 Enhanced Tables** - Professional table rendering with download functionality
- **📥 Smart Downloads** - Multi-format data export (CSV, JSON, TSV)
- **🔗 API Flexible** - Supports REST APIs and WebSocket connections
- **🔐 JWT Authentication** - Secure authentication with username/password
- **🎨 Customizable** - Branding, colors, positioning, and features
- **📦 Standalone** - No dependencies on your existing codebase
- **🔄 Dynamic Response Parsing** - Handles any API response structure
- **✨ Professional UI** - Beautiful gradients, animations, and modern design

## 📚 Documentation

- [Installation Guide](./INSTALLATION.md) - Complete setup instructions
- [Setup Guide](./SETUP_GUIDE.md) - Detailed integration guide
- [Examples](./examples/) - Integration examples for different platforms

## 🔧 Configuration

### Basic Configuration

```javascript
const config = {
  branding: {
    title: 'BrainKB Assistant',
    subtitle: 'Knowledge Helper',
    primaryColor: 'from-purple-600 to-blue-600'
  },
  api: {
    endpoint: 'https://api.example.com/chat',
    type: 'rest', // or 'websocket'
    streaming: true, // Enable streaming responses
    headers: {
      'Authorization': 'Bearer your-token'
    }
  },
  features: {
    enableQuickActions: true,
    enableFileUpload: true,
    enableContextDetection: true,
    enableMarkdown: true,
    enableMessageEditing: true,
    enableCodeRendering: true,
    enableTypingIndicator: true
  },
  ui: {
    position: 'bottom-right', // bottom-right, bottom-left, top-right, top-left
    size: {
      width: '600px',
      height: '700px'
    },
    theme: 'light', // light, dark, auto
    zIndex: 999999
  },
  quickActions: [
    {
      id: 'help',
      label: '❓ Get Help',
      action: 'help',
      description: 'Get assistance'
    }
  ]
};
```

### JWT Authentication Configuration

```javascript
const config = {
  api: {
    endpoint: 'https://api.example.com/chat',
    type: 'rest',
    streaming: true,
    
    // JWT Authentication
    auth: {
      enabled: true,
      type: 'jwt',
      jwtEndpoint: 'https://api.example.com/auth/login',
      username: 'your-username',
      password: 'your-password',
      
      // Optional: Custom token field names
      tokenKey: 'access_token',        // Default: 'access_token'
      refreshTokenKey: 'refresh_token', // Default: 'refresh_token'
      
      // Optional: Auto-refresh configuration
      autoRefresh: true,               // Default: false
      refreshThreshold: 300,           // Refresh 5 minutes before expiry
    },
  },
  // ... other configuration
};
```

## 🎯 Integration Examples

### React Application
```jsx
import BrainKBAssistant from 'brainkb-assistant';

function App() {
  const config = {
    api: {
      endpoint: 'https://api.example.com/chat'
    },
    branding: {
      title: 'My Assistant'
    }
  };

  return (
    <div>
      <h1>My React App</h1>
      <BrainKBAssistant config={config} />
    </div>
  );
}
```

### Next.js Application
```tsx
// app/layout.tsx
import BrainKBAssistant from 'brainkb-assistant';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const config = {
    api: {
      endpoint: process.env.NEXT_PUBLIC_API_ENDPOINT
    }
  };

  return (
    <html lang="en">
      <body>
        {children}
        <BrainKBAssistant config={config} />
      </body>
    </html>
  );
}
```

### Static HTML
```html
<!DOCTYPE html>
<html>
<head>
    <script src="https://unpkg.com/brainkb-assistant@latest/dist/index.js"></script>
</head>
<body>
    <h1>My Website</h1>
    <script>
        const config = {
            api: {
                endpoint: 'https://api.example.com/chat'
            }
        };
        BrainKBAssistant.init({ config });
    </script>
</body>
</html>
```

## 🔄 Dynamic Response Handling

The assistant now includes intelligent response parsing that handles any API response structure:

```javascript
// These response formats all work:
{ content: "Hello world" }
{ message: "Hello world" }
{ data: { text: "Hello world" } }
"Hello world"
["Hello", "world"]
{ custom_field: "Hello world" }
```

## 🛠️ Development

```bash
# Clone the repository
git clone https://github.com/brainkb/brainkb-assistant.git

# Install dependencies
npm install

# Start development mode
npm run dev

# Build for production
npm run build

# Publish to npm
npm publish
```

## 📦 Package Structure

```
brainkb-assistant/
├── src/
│   ├── components/
│   │   ├── BrainKBAssistant.tsx
│   │   └── BrainKBAssistantWrapper.tsx
│   ├── styles/
│   │   └── brainkb-assistant.css
│   └── index.ts
├── examples/
│   ├── react-integration.jsx
│   ├── nextjs-integration.tsx
│   ├── static-html-integration.html
│   └── nodejs-server.js
├── dist/
│   ├── index.js
│   ├── index.esm.js
│   └── index.d.ts
└── package.json
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Run tests: `npm test`
5. Commit your changes: `git commit -am 'Add feature'`
6. Push to the branch: `git push origin feature-name`
7. Submit a pull request

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

## 🆘 Support

- 📖 [Documentation](./SETUP_GUIDE.md)
- 💡 [Examples](./examples/)
- 🐛 [Issues](https://github.com/brainkb/brainkb-assistant/issues)
- 💬 [Discussions](https://github.com/brainkb/brainkb-assistant/discussions)