Skip to content

Commit 4c7ddb2

Browse files
neuromechanistneuromechanist
committed
Add MNE-Python tools docs and update knowledge sync
1 parent 5e64409 commit 4c7ddb2

2 files changed

Lines changed: 176 additions & 2 deletions

File tree

‎docs/osa/knowledge-sync.md‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ OSA includes a knowledge discovery system that syncs community-specific content
44

55
## Overview
66

7-
The knowledge system supports six sync types:
7+
The knowledge system supports seven sync types:
88

99
| Sync Type | Source | Description |
1010
|-----------|--------|-------------|
@@ -13,6 +13,7 @@ The knowledge system supports six sync types:
1313
| **Docstrings** | GitHub repos | MATLAB/Python function documentation |
1414
| **Mailman** | Mailman archives | Mailing list messages |
1515
| **FAQ** | Large Language Model (LLM) summarization | Frequently Asked Questions (FAQ) entries generated from mailing list threads |
16+
| **Discourse** | Discourse public JSON API | Forum topics with first post and accepted answers |
1617
| **BEPs** | bids-website + GitHub PRs | BIDS Extension Proposals (BIDS community only) |
1718

1819
!!! note "Discovery, Not Answers"
@@ -211,9 +212,36 @@ uv run osa sync beps --community bids
211212
|--------|-------------|
212213
| `-c, --community` | Community ID (default: `bids`) |
213214

215+
### `osa sync discourse`
216+
217+
Sync Discourse forum topics from a community's Discourse instance. Uses the public JSON API (no authentication required).
218+
219+
```bash
220+
# Sync forum topics for a community
221+
uv run osa sync discourse --community mne
222+
223+
# Full sync (not incremental)
224+
uv run osa sync discourse --community mne --full
225+
226+
# Limit number of topics (for testing)
227+
uv run osa sync discourse --community mne --max 10
228+
```
229+
230+
**Options:**
231+
232+
| Option | Description |
233+
|--------|-------------|
234+
| `-c, --community` | Community ID (default: `mne`) |
235+
| `--full` | Full sync instead of incremental |
236+
| `--max` | Maximum topics to sync (for testing) |
237+
238+
The syncer uses patient rate limiting (1 request per second by default) to respect the Discourse API limits (200 requests per minute). Topics are stored with their first post and either the accepted answer or the highest-voted reply.
239+
240+
Discourse forums are configured in `config.yaml` under `discourse`.
241+
214242
### `osa sync all`
215243

216-
Sync all knowledge sources for one or all communities. Runs GitHub, papers, and BEPs (for BIDS) in sequence.
244+
Sync all knowledge sources for one or all communities. Runs GitHub, papers, Discourse, and BEPs (for BIDS) in sequence.
217245

218246
```bash
219247
# Sync everything for one community
@@ -315,6 +343,7 @@ Each community's assistant gets knowledge discovery tools based on its configura
315343
| `search_{community}_papers` | Search academic papers | `citations` |
316344
| `search_{community}_code_docs` | Search code docstrings | `docstrings` |
317345
| `search_{community}_faq` | Search mailing list FAQ | `mailman` + `faq_generation` |
346+
| `search_{community}_forum` | Search Discourse forum topics | `discourse` |
318347

319348
See the [Tools](tools/index.md) section for detailed tool documentation per community.
320349

‎docs/osa/tools/mne.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# MNE-Python Tools
2+
3+
The MNE-Python assistant provides tools for documentation retrieval, knowledge search, code docstring search, and Discourse forum search.
4+
5+
## Overview
6+
7+
| Tool | Type | Description |
8+
|------|------|-------------|
9+
| `retrieve_mne_docs` | Document retrieval | Fetch MNE tutorials and guides |
10+
| `search_mne_discussions` | Knowledge search | Search GitHub issues and PRs |
11+
| `list_mne_recent` | Knowledge search | List recent GitHub activity |
12+
| `search_mne_papers` | Knowledge search | Search academic papers |
13+
| `search_mne_code_docs` | Code docstrings | Search Python function documentation |
14+
| `search_mne_forum` | Forum search | Search Discourse forum topics |
15+
16+
## Document Retrieval
17+
18+
### `retrieve_mne_docs`
19+
20+
Fetches documentation from 31 configured MNE sources, covering the full M/EEG analysis pipeline from data import through source estimation.
21+
22+
**Preloaded docs** (embedded in system prompt):
23+
24+
- MNE Cookbook (typical M/EEG workflow)
25+
- MNE Tools Suite (ecosystem overview)
26+
27+
**On-demand docs (29):** organized by category:
28+
29+
- **Introduction (3):** overview, Python concepts, raw data structure
30+
- **I/O (3):** reading raw data, reading epoched data, reading forward/inverse
31+
- **Raw (2):** interactive raw data visualization, filtering
32+
- **Preprocessing (5):** regression-based artifact removal, ICA, Signal Space Projection (SSP), Maxwell filtering, repairing bad channels
33+
- **Epochs (3):** creating epochs, handling metadata, visualizing epochs
34+
- **Evoked (2):** creating evoked objects, whitening evoked data
35+
- **Time-frequency (2):** frequency/time-frequency analysis, spectral connectivity
36+
- **Forward (2):** head model and forward computation, source space
37+
- **Inverse (3):** Minimum Norm Estimates (MNE), dynamic Statistical Parametric Mapping (dSPM), beamformers
38+
- **Statistics (2):** spatiotemporal cluster permutation, sensor-space statistics
39+
- **Machine learning (1):** decoding with MNE and scikit-learn
40+
- **Clinical (1):** sleep staging with MNE
41+
42+
All documentation sources point to rendered HTML pages on `mne.tools/stable/` which are automatically converted to markdown by the fetcher.
43+
44+
## Knowledge Search Tools
45+
46+
These tools search the MNE community's synced knowledge database.
47+
48+
### `search_mne_discussions`
49+
50+
Search GitHub issues and PRs across MNE repositories.
51+
52+
**Parameters:**
53+
54+
| Parameter | Type | Default | Description |
55+
|-----------|------|---------|-------------|
56+
| `query` | `str` | required | Search query |
57+
| `include_issues` | `bool` | `True` | Include issues in results |
58+
| `include_prs` | `bool` | `True` | Include pull requests |
59+
| `limit` | `int` | `5` | Maximum results |
60+
61+
**Tracked repositories:**
62+
63+
- `mne-tools/mne-python`
64+
- `mne-tools/mne-bids`
65+
- `mne-tools/mne-connectivity`
66+
- `mne-tools/mne-icalabel`
67+
- `mne-tools/mne-lsl`
68+
69+
### `list_mne_recent`
70+
71+
List recent GitHub activity ordered by creation date.
72+
73+
**Parameters:**
74+
75+
| Parameter | Type | Default | Description |
76+
|-----------|------|---------|-------------|
77+
| `item_type` | `str` | `"all"` | Filter: `"all"`, `"issue"`, or `"pr"` |
78+
| `repo` | `str \| None` | `None` | Filter by repository |
79+
| `status` | `str \| None` | `None` | Filter: `"open"` or `"closed"` |
80+
| `limit` | `int` | `10` | Maximum results |
81+
82+
### `search_mne_papers`
83+
84+
Search academic papers related to MNE-Python.
85+
86+
**Parameters:**
87+
88+
| Parameter | Type | Default | Description |
89+
|-----------|------|---------|-------------|
90+
| `query` | `str` | required | Search query |
91+
| `limit` | `int` | `5` | Maximum results |
92+
93+
**Tracked citation DOIs:**
94+
95+
- `10.3389/fnins.2013.00267` (Gramfort et al. 2013, main MNE paper)
96+
- `10.1016/j.neuroimage.2013.10.027` (Gramfort et al. 2014)
97+
- `10.21105/joss.01896` (MNE-BIDS)
98+
- `10.21105/joss.04484` (MNE-ICALabel)
99+
- `10.21105/joss.08088` (MNE-LSL)
100+
101+
## Code Docstring Search
102+
103+
### `search_mne_code_docs`
104+
105+
Search Python docstrings extracted from MNE ecosystem repositories. Covers functions, classes, and methods across all 5 tracked repos.
106+
107+
**Parameters:**
108+
109+
| Parameter | Type | Default | Description |
110+
|-----------|------|---------|-------------|
111+
| `query` | `str` | required | Search query (e.g., "read_raw_edf", "Epochs") |
112+
| `limit` | `int` | `5` | Maximum results |
113+
114+
**Tracked repositories (Python only):**
115+
116+
- `mne-tools/mne-python` (800+ Python files)
117+
- `mne-tools/mne-bids`
118+
- `mne-tools/mne-connectivity`
119+
- `mne-tools/mne-icalabel`
120+
- `mne-tools/mne-lsl`
121+
122+
## Discourse Forum Search
123+
124+
### `search_mne_forum`
125+
126+
Search topics from the MNE Discourse forum ([mne.discourse.group](https://mne.discourse.group)). Returns topic titles, post previews, accepted answers, and direct links.
127+
128+
**Parameters:**
129+
130+
| Parameter | Type | Default | Description |
131+
|-----------|------|---------|-------------|
132+
| `query` | `str` | required | Search query |
133+
| `category` | `str \| None` | `None` | Filter by Discourse category |
134+
| `limit` | `int` | `5` | Maximum results |
135+
136+
The forum database is synced weekly from the Discourse public API (6000+ topics, 30000+ posts). Topics include the first post and the accepted answer (or highest-voted reply).
137+
138+
## Sync Schedule
139+
140+
| Source | Schedule | Notes |
141+
|--------|----------|-------|
142+
| GitHub | Weekly, Mon 2:30 UTC | Issues and PRs from 5 repos |
143+
| Papers | Weekly, Mon 3:30 UTC | From OpenALEX, Semantic Scholar, PubMed |
144+
| Docstrings | Weekly, Mon 4:30 UTC | Python docstrings from 5 repos |
145+
| Discourse | Weekly, Mon 5:30 UTC | Forum topics with patient rate limiting (1 req/s) |

0 commit comments

Comments
 (0)