# @quandis/qbo4.ai

Lit web components for the [qbo4.AI](https://github.com/quandis/qbo4.AI) conversational AI platform. Provides a streaming chat interface, agent selector, and admin UI for managing AI agents — all backed by the `qbo4.AI` ASP.NET Core REST API.

## Installation

```bash
npm install @quandis/qbo4.ai
```

## Quick start

Wrap your components in `<qbo-config>` once to set the API base URL, then use the components anywhere inside it:

```html
<script type="module" src="node_modules/@quandis/qbo4.ai/wwwroot/js/qbo4.ai.min.js"></script>

<qbo-config api-base="/ai">
  <qbo-agent id="picker"></qbo-agent>
  <qbo-chat id="chat"></qbo-chat>
</qbo-config>

<script type="module">
  document.getElementById('picker')
    .addEventListener('agent-selected', e => {
      document.getElementById('chat').agent = e.detail.name;
    });
</script>
```

## TypeScript / bundler usage

```ts
import { QboConfig, QboAgent, QboChat, QboAiAgentManager } from '@quandis/qbo4.ai';
```

All components self-register their custom elements on import. Types and declaration files are included.

## Components

### `<qbo-config>`

Context provider. Wrap your component tree once; all descendant components receive the configuration automatically via [Lit Context](https://lit.dev/docs/data/context/).

| Attribute  | Type     | Description                                      |
|------------|----------|--------------------------------------------------|
| `api-base` | `string` | Base URL for the AI REST API (e.g. `/ai`)        |

```html
<qbo-config api-base="/ai">
  <!-- components go here -->
</qbo-config>
```

---

### `<qbo-agent>`

Fetches the list of registered agents from the API and renders a `<select>`. Fires `agent-selected` when the user picks one.

| Attribute  | Type     | Description                                        |
|------------|----------|----------------------------------------------------|
| `api-base` | `string` | Override API endpoint (defaults to context + `/agent`) |

| Event            | Detail              | Description                        |
|------------------|---------------------|------------------------------------|
| `agent-selected` | `{ name: string }` | Fired when the user selects an agent |

```html
<qbo-agent id="picker"></qbo-agent>
<script type="module">
  document.getElementById('picker')
    .addEventListener('agent-selected', e => console.log(e.detail.name));
</script>
```

---

### `<qbo-chat>`

Streaming chat backed by `POST /ai/agent/{name}/chat`. Renders user and assistant messages with Markdown and syntax highlighting. Includes a collapsible conversation history panel backed by `localStorage`.

| Attribute  | Type      | Description                                          |
|------------|-----------|------------------------------------------------------|
| `agent`    | `string`  | Name of the agent to chat with                       |
| `api-base` | `string`  | Override API endpoint                                |
| `mermaid`  | `boolean` | Enable Mermaid diagram rendering (loaded on demand)  |

```html
<qbo-chat agent="my-agent" mermaid></qbo-chat>
```

Connect it to `<qbo-agent>`:

```js
document.getElementById('picker')
  .addEventListener('agent-selected', e => {
    document.getElementById('chat').agent = e.detail.name;
  });
```

---

### `<qbo-ai-agent-manager>`

Full CRUD admin UI for managing agents, system instructions, tool functions, API keys, and corpus documents. Intended for admin/configuration pages.

| Attribute  | Type     | Description           |
|------------|----------|-----------------------|
| `api-base` | `string` | Override API endpoint |

Supports Anthropic, Google, and OpenAI providers with per-provider model suggestions.

```html
<qbo-config api-base="/ai">
  <qbo-ai-agent-manager></qbo-ai-agent-manager>
</qbo-config>
```

---

### `<qbo-ai-agent-documents>`

Corpus document manager for a single agent. Renders a file list with upload drop zone and delete controls. Used internally by `<qbo-ai-agent-manager>`.

| Attribute   | Type     | Description              |
|-------------|----------|--------------------------|
| `agent-id`  | `number` | ID of the target agent   |
| `api-base`  | `string` | Override API endpoint    |

| Event               | Detail                           |
|---------------------|----------------------------------|
| `document-uploaded` | `{ doc: ICorpusDocumentInfo }`   |
| `document-deleted`  | `{ documentName: string }`       |

## API requirements

Components expect the following endpoints, served by the `qbo4.AI.Web` ASP.NET package:

| Method | Path                               | Used by                          |
|--------|------------------------------------|----------------------------------|
| GET    | `{api-base}/agent`                 | `<qbo-agent>`, `<qbo-ai-agent-manager>` |
| POST   | `{api-base}/agent/{name}/chat`     | `<qbo-chat>` (SSE streaming)     |
| GET    | `{api-base}/agent/{id}`            | `<qbo-ai-agent-manager>`         |
| POST   | `{api-base}/agent`                 | `<qbo-ai-agent-manager>`         |
| PUT    | `{api-base}/agent/{id}`            | `<qbo-ai-agent-manager>`         |
| DELETE | `{api-base}/agent/{id}`            | `<qbo-ai-agent-manager>`         |
| GET    | `{api-base}/agent/{id}/documents`  | `<qbo-ai-agent-documents>`       |
| POST   | `{api-base}/agent/{id}/documents`  | `<qbo-ai-agent-documents>`       |
| DELETE | `{api-base}/agent/{id}/documents/{name}` | `<qbo-ai-agent-documents>` |

## License

MIT — © Quandis, Inc.
