@yeyuan98/opencode-bioresearcher-plugin 1.5.2 → 1.5.3

package/dist/skills/bioresearcher-core/patterns/rate-limiting.md

@@ -1,167 +1,167 @@
-# Rate Limiting Pattern
-
-Enforce delays between API calls to respect rate limits and avoid throttling.
-
-## Overview
-
-Use this pattern when making sequential API calls to services with rate limits. This is especially important for BioMCP tools that query external biomedical databases.
-
-## Pattern Algorithm
-
-```
-1. Initialize: delay = D (based on service type)
-2. For each API call:
-   a. Make the API call
-   b. If more calls remain:
-      - Use blockingTimer(delay=D)
-   c. Continue to next call
-```
-
-## Parameters
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `delay` | 0.3 | Wait time in seconds between calls |
-
-## Tool: blockingTimer
-
-```
-blockingTimer(delay: number)
-```
-
-- Maximum delay: 300 seconds
-- Returns: "Timer completed: waited X seconds (actual elapsed: Ys)"
-
-## Recommended Delays by Service
-
-| Service Type | Recommended Delay | Reason |
-|--------------|-------------------|--------|
-| BioMCP tools | 0.3 - 0.5 seconds | NCBI/API rate limits |
-| External APIs | 1 - 2 seconds | General API etiquette |
-| NCBI FTP | 2 - 3 seconds | FTP server limits |
-| Web scraping | 3 - 5 seconds | Respect robots.txt |
-
-## Example: BioMCP Sequential Calls
-
-```
-# Configuration
-delay = 0.3  # 300ms between calls
-
-# Sequential BioMCP calls with rate limiting
-biomcp_search(query="gene:BRAF AND disease:melanoma")
-blockingTimer(delay=0.3)
-
-biomcp_fetch(id="NCT04280705")
-blockingTimer(delay=0.3)
-
-biomcp_article_getter(pmid="35271234")
-blockingTimer(delay=0.3)
-
-# Continue with more calls...
-```
-
-## Example: Batch Processing with Rate Limiting
-
-```
-# Configuration
-delay = 0.5  # 500ms for safety
-items = ["item1", "item2", "item3", "item4", "item5"]
-
-# Process with rate limiting
-for i, item in enumerate(items):
-    result = biomcp_fetch(id=item)
-    process(result)
-    
-    # Don't delay after the last item
-    if i < len(items) - 1:
-        blockingTimer(delay=delay)
-```
-
-## Example: Subagent Rate Limiting
-
-For bioresearcherDR_worker subagents:
-
-```
-# Worker configuration
-delay = 0.5  # Workers use slightly longer delay
-
-# Sequential research calls
-biomcp_search(query=gene_query)
-blockingTimer(delay=0.5)
-
-biomcp_article_searcher(genes=["BRAF"], diseases=["melanoma"])
-blockingTimer(delay=0.5)
-
-biomcp_trial_searcher(conditions=["melanoma"])
-blockingTimer(delay=0.5)
-```
-
-## Why Rate Limiting Matters
-
-1. **Avoid API bans**: Many services block IPs that exceed rate limits
-2. **Ensure reliability**: Steady requests are less likely to timeout
-3. **Respect resources**: Shared APIs serve many users
-4. **Comply with ToS**: Most APIs require reasonable request rates
-
-## Common Rate Limits
-
-| Service | Rate Limit | Source |
-|---------|------------|--------|
-| NCBI E-utilities | 3 requests/second | NCBI Guidelines |
-| PubMed API | 3 requests/second | NCBI Guidelines |
-| ClinicalTrials.gov | Varies | Check API docs |
-| MyGene.info | 10 requests/second | BioThings docs |
-| MyVariant.info | 10 requests/second | BioThings docs |
-
-## Integration with Retry Pattern
-
-When combining rate limiting with retries:
-
-```
-# Retry configuration
-max_attempts = 3
-retry_delay = 2
-rate_limit_delay = 0.3
-
-for attempt in range(max_attempts):
-    result = api_call()
-    if result.success:
-        break
-    
-    # Retry delay (longer)
-    if attempt < max_attempts - 1:
-        blockingTimer(delay=retry_delay)
-        retry_delay *= 2  # Exponential backoff
-    continue
-
-# Rate limit before next call
-blockingTimer(delay=rate_limit_delay)
-```
-
-## Best Practices
-
-1. **Be conservative**: Use 0.5s when uncertain about limits
-2. **Don't skip delays**: Even "quick" calls need spacing
-3. **Adjust for errors**: Increase delay if getting 429 errors
-4. **Document your delays**: Note why specific values were chosen
-5. **Parallel with caution**: Parallel calls multiply effective rate
-
-## Error Handling
-
-If you receive rate limit errors (HTTP 429):
-
-```
-# Detect rate limit error
-if response.status_code == 429:
-    # Increase delay and retry
-    blockingTimer(delay=5)  # Wait longer
-    retry_request()
-```
-
-## Integration with Other Patterns
-
-| Pattern | Integration |
-|---------|-------------|
-| `retry.md` | Rate limit delay + retry backoff |
-| `progress.md` | Rate limiting during batch progress |
-| `subagent-waves.md` | Each subagent applies its own rate limiting |
+# Rate Limiting Pattern
+
+Enforce delays between API calls to respect rate limits and avoid throttling.
+
+## Overview
+
+Use this pattern when making sequential API calls to services with rate limits. This is especially important for BioMCP tools that query external biomedical databases.
+
+## Pattern Algorithm
+
+```
+1. Initialize: delay = D (based on service type)
+2. For each API call:
+   a. Make the API call
+   b. If more calls remain:
+      - Use blockingTimer(delay=D)
+   c. Continue to next call
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `delay` | 0.3 | Wait time in seconds between calls |
+
+## Tool: blockingTimer
+
+```
+blockingTimer(delay: number)
+```
+
+- Maximum delay: 300 seconds
+- Returns: "Timer completed: waited X seconds (actual elapsed: Ys)"
+
+## Recommended Delays by Service
+
+| Service Type | Recommended Delay | Reason |
+|--------------|-------------------|--------|
+| BioMCP tools | 0.3 - 0.5 seconds | NCBI/API rate limits |
+| External APIs | 1 - 2 seconds | General API etiquette |
+| NCBI FTP | 2 - 3 seconds | FTP server limits |
+| Web scraping | 3 - 5 seconds | Respect robots.txt |
+
+## Example: BioMCP Sequential Calls
+
+```
+# Configuration
+delay = 0.3  # 300ms between calls
+
+# Sequential BioMCP calls with rate limiting
+biomcp_search(query="gene:BRAF AND disease:melanoma")
+blockingTimer(delay=0.3)
+
+biomcp_fetch(id="NCT04280705")
+blockingTimer(delay=0.3)
+
+biomcp_article_getter(pmid="35271234")
+blockingTimer(delay=0.3)
+
+# Continue with more calls...
+```
+
+## Example: Batch Processing with Rate Limiting
+
+```
+# Configuration
+delay = 0.5  # 500ms for safety
+items = ["item1", "item2", "item3", "item4", "item5"]
+
+# Process with rate limiting
+for i, item in enumerate(items):
+    result = biomcp_fetch(id=item)
+    process(result)
+    
+    # Don't delay after the last item
+    if i < len(items) - 1:
+        blockingTimer(delay=delay)
+```
+
+## Example: Subagent Rate Limiting
+
+For bioresearcherDR_worker subagents:
+
+```
+# Worker configuration
+delay = 0.5  # Workers use slightly longer delay
+
+# Sequential research calls
+biomcp_search(query=gene_query)
+blockingTimer(delay=0.5)
+
+biomcp_article_searcher(genes=["BRAF"], diseases=["melanoma"])
+blockingTimer(delay=0.5)
+
+biomcp_trial_searcher(conditions=["melanoma"])
+blockingTimer(delay=0.5)
+```
+
+## Why Rate Limiting Matters
+
+1. **Avoid API bans**: Many services block IPs that exceed rate limits
+2. **Ensure reliability**: Steady requests are less likely to timeout
+3. **Respect resources**: Shared APIs serve many users
+4. **Comply with ToS**: Most APIs require reasonable request rates
+
+## Common Rate Limits
+
+| Service | Rate Limit | Source |
+|---------|------------|--------|
+| NCBI E-utilities | 3 requests/second | NCBI Guidelines |
+| PubMed API | 3 requests/second | NCBI Guidelines |
+| ClinicalTrials.gov | Varies | Check API docs |
+| MyGene.info | 10 requests/second | BioThings docs |
+| MyVariant.info | 10 requests/second | BioThings docs |
+
+## Integration with Retry Pattern
+
+When combining rate limiting with retries:
+
+```
+# Retry configuration
+max_attempts = 3
+retry_delay = 2
+rate_limit_delay = 0.3
+
+for attempt in range(max_attempts):
+    result = api_call()
+    if result.success:
+        break
+    
+    # Retry delay (longer)
+    if attempt < max_attempts - 1:
+        blockingTimer(delay=retry_delay)
+        retry_delay *= 2  # Exponential backoff
+    continue
+
+# Rate limit before next call
+blockingTimer(delay=rate_limit_delay)
+```
+
+## Best Practices
+
+1. **Be conservative**: Use 0.5s when uncertain about limits
+2. **Don't skip delays**: Even "quick" calls need spacing
+3. **Adjust for errors**: Increase delay if getting 429 errors
+4. **Document your delays**: Note why specific values were chosen
+5. **Parallel with caution**: Parallel calls multiply effective rate
+
+## Error Handling
+
+If you receive rate limit errors (HTTP 429):
+
+```
+# Detect rate limit error
+if response.status_code == 429:
+    # Increase delay and retry
+    blockingTimer(delay=5)  # Wait longer
+    retry_request()
+```
+
+## Integration with Other Patterns
+
+| Pattern | Integration |
+|---------|-------------|
+| `retry.md` | Rate limit delay + retry backoff |
+| `progress.md` | Rate limiting during batch progress |
+| `subagent-waves.md` | Each subagent applies its own rate limiting |

package/dist/skills/gromacs-guides/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gromacs-guides
+description: Reusable guides for GROMACS molecular dynamics workflows
+allowedTools:
+  - Read
+  - Bash
+---
+
+# GROMACS Guides
+
+This skill provides reusable guides for common GROMACS molecular dynamics workflows.
+
+## Quick Start
+
+### Step 1: Load This Skill
+The skill is loaded automatically when agent calls `skill gromacs-guides`.
+
+### Step 2: Extract Skill Path
+From the `<skill_files>` section in the skill tool output, extract the `<skill_path>` value.
+
+### Step 3: Read the Relevant Guide
+```
+Read <skill_path>/guides/inspect_tpr.md
+Read <skill_path>/guides/create_index.md
+```
+
+## Available Guides
+
+| Task | Guide |
+|------|-------|
+| TPR inspection | `guides/inspect_tpr.md` |
+| Index file creation | `guides/create_index.md` |
+
+## Guide Summaries
+
+### inspect_tpr.md
+Commands for extracting molecule information from TPR files:
+- Quick summary and detailed dump commands
+- Molecule type/counts extraction
+- Cyclic molecule bond detection
+- Molecule independence checking
+
+### create_index.md
+Workflow for creating GROMACS index files:
+- Basic `make_ndx` usage
+- `splitch` artefact identification and fixing
+- Merge → verify → delete → rename workflow
+- C-alpha group creation

package/dist/skills/gromacs-guides/guides/create_index.md

@@ -0,0 +1,96 @@
+# Creating Index Files for Protein Chains
+
+## Basic Method
+
+```bash
+# Interactive mode
+gmx make_ndx -f <tpr_file> -o <index_file.ndx>
+
+# Non-interactive: split protein group by chain
+printf "splitch <protein_group>\nq\n" | gmx make_ndx -f <tpr_file> -o <index_file.ndx>
+```
+
+## Caveat: `splitch` Artefacts
+
+`splitch` uses topological connectivity and may incorrectly split a single chain into multiple groups when:
+- Hydrogen atoms were rebuilt by `pdb2gmx` (N-terminal residues get extra H1/H2/H3 atoms)
+- Residue numbering has gaps (e.g., residues 1-18, then 26-108)
+
+**Symptom**: After `splitch`, a single protein chain appears as multiple `Protein_chainN` groups where the atom counts don't match expected molecule boundaries.
+
+## Recommended Workflow: Fix Incorrectly Split Chains
+
+**Step 1: Identify the incorrect split**
+After `splitch`, press Enter (empty line) in `make_ndx` to list all groups. Compare atom counts against your expected molecule sizes.
+
+**Step 2: Merge the incorrectly split groups**
+```
+<group_N> | <group_M>
+```
+This creates a new merged group named `Protein_chainN_Protein_chainM` at the end of the list.
+
+**Step 3: Verify the merged group**
+Press Enter to list groups again. The merged group should have the correct total atom count.
+
+**Step 4: Delete the incorrect split groups**
+Delete in DESCENDING order to avoid index shifting confusion:
+```
+del <higher_index>
+del <lower_index>
+```
+After `k` deletions, the merged group index shifts down by `k`.
+
+**Step 5: Rename the merged group (optional)**
+```
+name <final_index> <custom_name>
+```
+
+## Generic Example (interactive `make_ndx` session)
+
+```
+> splitch 1
+Found N chains
+ 1:  XXX atoms (a to b)
+ 2:   YY atoms (c to d)     <-- suspiciously small, may be incorrect split
+ 3:  ZZZ atoms (e to f)     <-- remainder of same chain
+
+>                          <-- press Enter to list groups
+...
+ N  Protein_chain1         XXX atoms
+N+1 Protein_chain2          YY atoms   <-- wrong split (too small)
+N+2 Protein_chain3         ZZZ atoms   <-- wrong split (remainder)
+...
+
+> N+1 | N+2                 <-- merge the incorrectly split groups
+Merged two groups with OR: YY ZZZ -> (YY+ZZZ)
+
+>                          <-- press Enter to verify
+...
+ M  Protein_chain2_Protein_chain3   (YY+ZZZ) atoms   <-- correct total!
+
+> del N+2                   <-- delete higher index first
+> del N+1                   <-- then lower index
+
+>                          <-- press Enter
+...
+ M-2  Protein_chain2_Protein_chain3   (YY+ZZZ) atoms   <-- shifted!
+
+> name M-2 <your_chain_name>
+> q
+```
+
+**Key insight**: After deleting `k` groups that were created AFTER the merged group, the merged group's index decreases by `k`.
+
+## Non-interactive Equivalent
+
+```bash
+printf "splitch 1\n<group_N> | <group_M>\ndel <higher>\ndel <lower>\nname <final> <name>\nq\n" | \
+  gmx make_ndx -f <tpr_file> -o <index_file.ndx>
+```
+
+## Creating C-alpha Groups
+
+In `make_ndx` interactive mode:
+```
+a CA & <chain_group>      # creates C-alpha selection for specified chain
+```

package/dist/skills/gromacs-guides/guides/inspect_tpr.md

@@ -0,0 +1,93 @@
+# Inspecting TPR Files for Molecule Information
+
+## Quick Summary
+
+```bash
+gmx dump -s <tpr_file> 2>&1 | grep -A 5 "moltype"
+```
+
+## Detailed Breakdown
+
+```bash
+# Full dump (verbose)
+gmx dump -s <tpr_file>
+
+# Extract molecule block info
+gmx dump -s <tpr_file> 2>&1 | grep -E "(molblock|#molecules|moltype.*=)"
+```
+
+**Output interpretation:**
+```
+molblock (N):
+   moltype              = M "MoleculeName"    # Molecule type name
+   #molecules           = X                    # Number of copies in system
+
+moltype (M):
+   name="MoleculeName"
+   atoms:
+      atom (N):                              # N atoms in this molecule type
+```
+
+## Key Information to Extract
+
+| Information | How to Find |
+|-------------|-------------|
+| Molecule type names | `grep 'moltype.*='` after `gmx dump` |
+| Molecule counts | `grep '#molecules'` after `gmx dump` |
+| Atoms per molecule type | Check `atom (N):` line under each `moltype` section |
+| Solvent molecule count | Find SOL/Water moltype, read `#molecules` |
+| Ion counts by type | Find NA, CL, etc. moltypes, read `#molecules` each |
+| Protein molecule chains | Count moltypes with "Protein" or similar in name |
+
+## Detecting Cyclic Molecule Configuration
+
+For protein chains, check if the molecule is cyclic (e.g., cyclic peptides) by examining bonds within the moltype.
+
+**Detection strategy:**
+1. Get atom count for the moltype from `atom (N):` line (N atoms, indexed 0 to N-1)
+2. Search the Bond section for a bond between atom 0 and the C-terminal atom (typically atom N-2, which is the C atom before the terminal O)
+3. If such a bond exists, the molecule is cyclic
+
+**Bond format in gmx dump:**
+```
+      Bond:
+         nr: <count>
+         iatoms:
+            0 type=441 (BONDS)   0   2
+            1 type=442 (BONDS)   0 273    <-- bond from atom 0 to atom 273
+```
+
+**Example:** For a 275-atom cyclic peptide (atoms 0-274):
+- Atom 0: N-terminal N
+- Atom 273: C-terminal C (the backbone carbon)
+- Atom 274: C-terminal O
+- A bond `0 273` indicates the N-C cyclization
+
+**Quick check for cyclic bond:**
+```bash
+# Get atom count for a protein moltype
+gmx dump -s <tpr_file> 2>&1 | grep -A 1 "atom (" | head -4
+
+# Search for bonds involving atom 0 and the C-terminal atom (N-2)
+# Replace <N-2> with actual value (e.g., 273 for 275-atom molecule)
+gmx dump -s <tpr_file> 2>&1 | grep -E "BONDS.*0.*<N-2>"
+```
+
+**Example command for 275-atom molecule:**
+```bash
+gmx dump -s <tpr_file> 2>&1 | grep -E "BONDS.*0.*273"
+```
+
+## Checking Molecule Independence
+
+```bash
+gmx dump -s <tpr_file> 2>&1 | grep "bIntermolecularInteractions"
+```
+- `false` = Molecules are independent (correct for most simulations)
+- `true` = Bonded interactions exist between molecule types (unusual)
+
+## Quick System Overview
+
+```bash
+echo "q" | gmx make_ndx -f <tpr_file> 2>&1 | grep -E "(System|Protein|Water|Ion|atoms)"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeyuan98/opencode-bioresearcher-plugin",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "OpenCode plugin that adds a bioresearcher agent",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",