Skip to content

Commit 3f77a8b

Browse files
neuromechanistneuromechanist
committed
docs: add community registry and widget deployment docs
Add comprehensive documentation for the YAML-driven community registry: - Registry overview with architecture diagram - Quick-start tutorial for adding new communities - Full YAML schema reference with validation rules - Extensions guide for Python plugins and MCP servers - Widget deployment guide with all configuration options Update mkdocs.yml navigation and OSA index page. Closes OpenScience-Collective/osa#49
1 parent 34e188d commit 3f77a8b

7 files changed

Lines changed: 948 additions & 0 deletions

File tree

‎docs/osa/deployment/widget.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
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+
| `allowPageContext` | boolean | `true` | Show page context toggle |
34+
| `pageContextDefaultEnabled` | boolean | `true` | Default state of page context |
35+
| `fullscreen` | boolean | `false` | Open chat in fullscreen mode |
36+
37+
### Minimal Configuration
38+
39+
Only `communityId` is required. Everything else has sensible defaults:
40+
41+
```html
42+
<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
43+
<script>
44+
OSAChatWidget.setConfig({
45+
communityId: 'bids'
46+
});
47+
</script>
48+
```
49+
50+
### Full Configuration
51+
52+
```html
53+
<script src="https://osa-demo.pages.dev/osa-chat-widget.js"></script>
54+
<script>
55+
OSAChatWidget.setConfig({
56+
communityId: 'hed',
57+
title: 'HED Assistant',
58+
initialMessage: 'Hi! I can help with HED annotations. What would you like to know?',
59+
placeholder: 'Ask about HED...',
60+
suggestedQuestions: [
61+
'What is HED?',
62+
'How do I annotate a button press?',
63+
'Validate my HED string',
64+
'What tools are available?'
65+
],
66+
showExperimentalBadge: false,
67+
allowPageContext: true,
68+
pageContextDefaultEnabled: true
69+
});
70+
</script>
71+
```
72+
73+
## Features
74+
75+
### Page Context Awareness
76+
77+
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.
78+
79+
Users can toggle this via a checkbox in the widget. The preference is persisted in localStorage.
80+
81+
### Chat History
82+
83+
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.
84+
85+
### Health Status
86+
87+
The widget shows backend connectivity status (Online/Offline) via a status indicator. It checks the `/health` endpoint on load.
88+
89+
### Resizable Window
90+
91+
Users can resize the chat window by dragging the top-left corner. The size is not persisted across page loads.
92+
93+
### Pop-out Window
94+
95+
Users can open the chat in a separate browser window for a larger workspace. The pop-out window shares the same session.
96+
97+
### Markdown Rendering
98+
99+
Assistant responses support full Markdown rendering including:
100+
101+
- Tables
102+
- Code blocks with syntax highlighting
103+
- Lists (ordered and unordered)
104+
- Links
105+
- Bold, italic, strikethrough
106+
107+
## Environment Detection
108+
109+
The widget auto-detects the environment based on the hostname:
110+
111+
| Hostname Pattern | Backend |
112+
|-----------------|---------|
113+
| `develop.*` | Dev worker (`osa-worker-dev`) |
114+
| `localhost` / `127.0.0.1` | Dev worker |
115+
| Everything else | Production worker (`osa-worker`) |
116+
117+
Override with `apiEndpoint`:
118+
119+
```javascript
120+
OSAChatWidget.setConfig({
121+
communityId: 'hed',
122+
apiEndpoint: 'https://your-custom-backend.example.com'
123+
});
124+
```
125+
126+
## Bot Protection
127+
128+
The widget supports Cloudflare Turnstile for bot protection:
129+
130+
```javascript
131+
OSAChatWidget.setConfig({
132+
communityId: 'hed',
133+
turnstileSiteKey: '0x4AAAAAA...'
134+
});
135+
```
136+
137+
When configured, users must complete a Turnstile challenge before sending messages. The token is included in API requests.
138+
139+
## API Endpoints
140+
141+
The widget communicates with two backend endpoints:
142+
143+
| Endpoint | Method | Description |
144+
|----------|--------|-------------|
145+
| `/{communityId}/ask` | POST | Send a question, get a response |
146+
| `/health` | GET | Check backend status |
147+
148+
### Request Format
149+
150+
```json
151+
{
152+
"question": "What is HED?",
153+
"page_context": {
154+
"url": "https://hedtags.org/docs/getting-started",
155+
"title": "Getting Started - HED"
156+
},
157+
"cf_turnstile_response": "token..."
158+
}
159+
```
160+
161+
### Response Format
162+
163+
```json
164+
{
165+
"answer": "HED (Hierarchical Event Descriptors) is...",
166+
"session_id": "abc123"
167+
}
168+
```
169+
170+
## Self-Hosting
171+
172+
To host the widget yourself:
173+
174+
1. Copy `osa-chat-widget.js` from the [frontend directory](https://github.com/OpenScience-Collective/osa/tree/main/frontend)
175+
2. Serve it from your static file server
176+
3. Update the script `src` to point to your hosted copy
177+
4. Set `apiEndpoint` to your OSA backend
178+
179+
```html
180+
<script src="https://your-cdn.example.com/osa-chat-widget.js"></script>
181+
<script>
182+
OSAChatWidget.setConfig({
183+
communityId: 'my-tool',
184+
apiEndpoint: 'https://your-backend.example.com'
185+
});
186+
</script>
187+
```
188+
189+
## Demo Page
190+
191+
The demo page at [osa-demo.pages.dev](https://osa-demo.pages.dev) showcases all available community assistants with URL-based routing:
192+
193+
- `/` - Landing page with community cards
194+
- `/hed` - HED assistant demo
195+
- `/bids` - BIDS assistant demo
196+
- `/eeglab` - EEGLAB assistant demo
197+
198+
Each community page auto-configures the widget with the appropriate settings.
199+
200+
## Troubleshooting
201+
202+
**Widget doesn't appear:**
203+
204+
- Check browser console for JavaScript errors
205+
- Verify the script URL is accessible
206+
- Ensure `communityId` contains only lowercase letters, numbers, and hyphens
207+
208+
**"Offline" status:**
209+
210+
- The backend may be down or unreachable
211+
- Check if `apiEndpoint` is correct for your environment
212+
- Network policies (CORS, CSP) may be blocking requests
213+
214+
**Chat history not persisting:**
215+
216+
- localStorage may be disabled or full
217+
- Private/incognito browsing clears localStorage on close
218+
- Different `communityId` values use different storage keys
219+
220+
**Page context not working:**
221+
222+
- Ensure `allowPageContext: true` (default)
223+
- User must enable the checkbox in the widget
224+
- 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)