Skip to content

Commit a670fc9

Browse files
neuromechanistneuromechanist
authored
Merge pull request #4 from OpenScience-Collective/feature/issue-49-registry-docs
docs: add community registry and widget deployment documentation
2 parents 34e188d + 11f84ca commit a670fc9

7 files changed

Lines changed: 962 additions & 0 deletions

File tree

‎docs/osa/deployment/widget.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
# Widget Deployment
2+
3+
The OSA Chat Widget is an embeddable JavaScript component that adds an AI assistant to any website. It connects to the OSA backend and provides a floating chat interface.
4+
5+
## Quick Integration
6+
7+
Add two script tags to your HTML:
8+
9+
```html
10+
<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
11+
<script>
12+
OSAChatWidget.setConfig({
13+
communityId: 'hed'
14+
});
15+
</script>
16+
```
17+
18+
The widget appears as a chat bubble in the bottom-right corner of the page.
19+
20+
## Configuration Options
21+
22+
| Option | Type | Default | Description |
23+
|--------|------|---------|-------------|
24+
| `communityId` | string | `'hed'` | Which community assistant to use |
25+
| `title` | string | `'HED Assistant'` | Widget header title |
26+
| `initialMessage` | string | HED greeting | First message shown to user |
27+
| `placeholder` | string | `'Ask about HED...'` | Input placeholder text |
28+
| `suggestedQuestions` | string[] | HED questions | Clickable suggestion buttons |
29+
| `apiEndpoint` | string | Auto-detected | Backend API URL |
30+
| `storageKey` | string | Auto-derived | localStorage key for chat history |
31+
| `turnstileSiteKey` | string | `null` | Cloudflare Turnstile site key |
32+
| `showExperimentalBadge` | boolean | `true` | Show beta/experimental badge |
33+
| `repoUrl` | string | OSA GitHub URL | URL for the "Powered by" footer link |
34+
| `repoName` | string | `'Open Science Assistant'` | Display name in footer |
35+
| `allowPageContext` | boolean | `true` | Show page context toggle |
36+
| `pageContextDefaultEnabled` | boolean | `true` | Default state of page context |
37+
| `pageContextStorageKey` | string | `'osa-page-context-enabled'` | localStorage key for page context preference |
38+
| `pageContextLabel` | string | `'Share page URL...'` | Label text for the page context checkbox |
39+
| `fullscreen` | boolean | `false` | Open chat in fullscreen mode |
40+
41+
### Minimal Configuration
42+
43+
Only `communityId` is required. Everything else has sensible defaults:
44+
45+
```html
46+
<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
47+
<script>
48+
OSAChatWidget.setConfig({
49+
communityId: 'bids'
50+
});
51+
</script>
52+
```
53+
54+
### Full Configuration
55+
56+
```html
57+
<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
58+
<script>
59+
OSAChatWidget.setConfig({
60+
communityId: 'hed',
61+
title: 'HED Assistant',
62+
initialMessage: 'Hi! I can help with HED annotations. What would you like to know?',
63+
placeholder: 'Ask about HED...',
64+
suggestedQuestions: [
65+
'What is HED?',
66+
'How do I annotate a button press?',
67+
'Validate my HED string',
68+
'What tools are available?'
69+
],
70+
showExperimentalBadge: false,
71+
allowPageContext: true,
72+
pageContextDefaultEnabled: true
73+
});
74+
</script>
75+
```
76+
77+
## Features
78+
79+
### Page Context Awareness
80+
81+
When enabled, the widget can share the current page's URL and title with the assistant. This helps provide contextually relevant answers when the widget is embedded on documentation pages.
82+
83+
Users can toggle this via a checkbox in the widget. The preference is persisted in localStorage.
84+
85+
### Chat History
86+
87+
Conversations are persisted in localStorage using a key derived from the `communityId`. Each community has its own chat history. Users can clear history via the reset button.
88+
89+
### Health Status
90+
91+
The widget shows backend connectivity status (Online/Offline) via a status indicator. It checks the `/health` endpoint on load.
92+
93+
### Resizable Window
94+
95+
Users can resize the chat window by dragging the top-left corner. The size is not persisted across page loads.
96+
97+
### Pop-out Window
98+
99+
Users can open the chat in a separate browser window for a larger workspace. The pop-out window shares the same session.
100+
101+
### Markdown Rendering
102+
103+
Assistant responses support full Markdown rendering including:
104+
105+
- Tables
106+
- Code blocks with copy button
107+
- Lists (ordered and unordered)
108+
- Links
109+
- Bold and italic
110+
111+
## Environment Detection
112+
113+
The widget auto-detects the environment based on the hostname:
114+
115+
| Hostname Pattern | Backend |
116+
|-----------------|---------|
117+
| `develop.*` | Dev worker (`osa-worker-dev`) |
118+
| `localhost` / `127.0.0.1` | Dev worker |
119+
| Everything else | Production worker (`osa-worker`) |
120+
121+
Override with `apiEndpoint`:
122+
123+
```javascript
124+
OSAChatWidget.setConfig({
125+
communityId: 'hed',
126+
apiEndpoint: 'https://your-custom-backend.example.com'
127+
});
128+
```
129+
130+
## Bot Protection
131+
132+
The widget supports Cloudflare Turnstile for bot protection:
133+
134+
```javascript
135+
OSAChatWidget.setConfig({
136+
communityId: 'hed',
137+
turnstileSiteKey: '0x4AAAAAA...'
138+
});
139+
```
140+
141+
When configured, users must complete a Turnstile challenge before sending messages. The token is included in API requests.
142+
143+
## API Endpoints
144+
145+
The widget communicates with two backend endpoints:
146+
147+
| Endpoint | Method | Description |
148+
|----------|--------|-------------|
149+
| `/{communityId}/ask` | POST | Send a question, get a response |
150+
| `/health` | GET | Check backend status |
151+
152+
### Request Format
153+
154+
```json
155+
{
156+
"question": "What is HED?",
157+
"page_context": {
158+
"url": "https://hedtags.org/docs/getting-started",
159+
"title": "Getting Started - HED"
160+
}
161+
}
162+
```
163+
164+
The `cf_turnstile_response` field is also sent by the widget when Turnstile is configured, but this is consumed by the Cloudflare Worker proxy, not the backend API.
165+
166+
### Response Format
167+
168+
```json
169+
{
170+
"answer": "HED (Hierarchical Event Descriptors) is...",
171+
"tool_calls": []
172+
}
173+
```
174+
175+
## Self-Hosting
176+
177+
To host the widget yourself:
178+
179+
1. Copy `osa-chat-widget.js` from the [frontend directory](https://github.com/OpenScience-Collective/osa/tree/main/frontend)
180+
2. Serve it from your static file server
181+
3. Update the script `src` to point to your hosted copy
182+
4. Set `apiEndpoint` to your OSA backend
183+
184+
```html
185+
<script src="https://your-cdn.example.com/osa-chat-widget.js"></script>
186+
<script>
187+
OSAChatWidget.setConfig({
188+
communityId: 'my-tool',
189+
apiEndpoint: 'https://your-backend.example.com'
190+
});
191+
</script>
192+
```
193+
194+
## Demo Page
195+
196+
The demo page at [osa-demo.pages.dev](https://osa-demo.pages.dev) showcases all available community assistants with URL-based routing:
197+
198+
- `/` - Landing page with community cards
199+
- `/hed` - HED assistant demo
200+
- `/bids` - BIDS assistant demo
201+
- `/eeglab` - EEGLAB assistant demo
202+
203+
Each community page auto-configures the widget with the appropriate settings.
204+
205+
## Troubleshooting
206+
207+
**Widget doesn't appear:**
208+
209+
- Check browser console for JavaScript errors
210+
- Verify the script URL is accessible
211+
- Ensure `communityId` contains only letters, numbers, hyphens, and underscores (the backend registry uses kebab-case IDs)
212+
213+
**"Offline" status:**
214+
215+
- The backend may be down or unreachable
216+
- Check if `apiEndpoint` is correct for your environment
217+
- Network policies (CORS, CSP) may be blocking requests
218+
219+
**Chat history not persisting:**
220+
221+
- localStorage may be disabled or full
222+
- Private/incognito browsing clears localStorage on close
223+
- Different `communityId` values use different storage keys
224+
225+
**Page context not working:**
226+
227+
- Ensure `allowPageContext: true` (default)
228+
- User must enable the checkbox in the widget
229+
- The page URL is sent; the backend fetches the content

‎docs/osa/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,14 @@ uv run osa ask -a hed "How do I annotate a button press?"
5959

6060
- [Getting Started](getting-started.md) - Installation and setup
6161
- [Architecture](architecture.md) - System design and diagrams
62+
- [Community Registry](registry/index.md) - YAML-driven assistant configuration
63+
- [Adding a Community](registry/quick-start.md) - Add a new assistant in 5 minutes
64+
- [Schema Reference](registry/schema-reference.md) - Full YAML config reference
65+
- [Extensions](registry/extensions.md) - Python plugins and MCP servers
6266
- [CLI Reference](cli-reference.md) - Command-line interface
6367
- [API Reference](api-reference.md) - REST API documentation
68+
- [Knowledge Sync](knowledge-sync.md) - Syncing GitHub, papers, and forums
69+
- [Widget Deployment](deployment/widget.md) - Embed the chat widget
6470
- [Tools](tools/index.md) - Available tools
6571
- [Development](development.md) - Contributing to OSA
6672

0 commit comments

Comments
 (0)