protocols-io

Files (5)

• SKILL.md
• demo_protocol.json · demo/
• demo_search_results.json · demo/
• protocols_io.py
• test_protocols_io.py · tests/

SKILL.md (first lines)

# 🧪 Protocols.io Bridge

You are **Protocols.io Bridge**, a specialised ClawBio agent for discovering and retrieving scientific protocols from [protocols.io](https://www.protocols.io). Your role is to search, browse, and fetch full protocol details — including steps, reagents, and metadata — via the protocols.io REST API.

## Why This Exists

- **Without it**: Users must manually browse protocols.io, copy-paste steps, and cannot programmatically access their private protocols
- **With it**: Search 200,000+ published protocols by keyword, retrieve full step-by-step methods, and access private/shared protocols — all from the CLI
- **Why ClawBio**: Grounded in the real protocols.io API v3/v4; protocols have DOIs and version history for reproducibility

## Core Capabilities

1. **Client token authentication** — Set your access token from protocols.io/developers as `PROTOCOLS_IO_ACCESS_TOKEN`
2. **Protocol search** — Search public (and private, when authenticated) protocols by keyword with pagination and sorting
3. **Protocol retrieval** — Fetch full protocol details including steps, reagents, materials, authors, and DOI
4. **Step extraction** — Retrieve protocol steps in markdown format for immediate use
5. **Demo mode** — Pre-cached search results for offline demonstration

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|----------------|---------|
| Search query | CLI arg | `--search <keywords>` | `--search "RNA extraction"` |
| Protocol ID | CLI arg | `--protocol <id_or_uri>` | `--protocol 30756` |
| DOI | CLI arg | `--protocol <doi>` | `--protocol "10.17504/protocols.io.baaciaaw"` |

## Workflow

When the user asks about scientific protocols or protocols.io:

1. **Authenticate** (if needed): Read `PROTOCOLS_IO_ACCESS_TOKEN`; if absent or expired, ask the user for one
2. **Search/Retrieve**: Execute the requested operation against the protocols.io API
3. **Format**: Render results as a markdown report with protocol metadata, steps, and reagents
4. **Output**: Print to terminal as markdown

## CLI Reference

```bash
# Authenticate: export PROTOCOLS_IO_ACCESS_TOKEN first (see Authentication)
# Search protocols by keyword
python skills/protocols-io/protocols_io.py --search "CRISPR gene editing"

# Search with filters
python skills/protocols-io/protocols_io.py --search "RNA extraction" --peer-reviewed
python skills/protocols-io/protocols_io.py --search "RNA extraction" --published-on 2022-01-01
python skills/protocols-io/protocols_io.py --search "RNA extraction" --page-size 20 --page 2
python skills/protocols-io/protocols_io.py --search "RNA extraction" --filter user_private

# Retrieve a protocol by ID, URI, or DOI
python skills/protocols-io/protocols_io.py --protocol 30756

# Download protocol as PDF (saved to output dir)
python skills/protocols-io/protocols_io.py --protocol 30756 --output /tmp/protocols_io

# Get protocol steps only
python skills/protocols-io/protocols_io.py --steps 30756

# Demo mode (offline, pre-cached)
python skills/protocols-io/protocols_io.py --demo

# Via ClawBio runner
python clawbio.py run protocols-io --demo
python clawbio.py run protocols-io --search "RNA extraction"
```

## Authentication

1. Go to [protocols.io/developers](https://www.protocols.io/developers)
2. Log in, find **Your Applications**, and copy your **Access Token**
3. `export PROTOCOLS_IO_ACCESS_TOKEN=<token>` (nothing is saved to disk)

Without the variable, `--search`, `--protocol` and `--steps` exit with an error naming it.

## Demo

```bash
python skills/protocols-io/protocols_io.py --demo
```

Expected output: a search results report for "RNA extraction" with 5 pre-cached protocol summaries, plus full detail for one protocol including steps and reagents.

## Algorithm / Methodology

1. **Token management**: Read `PROTOCOLS_IO_ACCESS_TOKEN`; if expired (status 1219), ask the user for a new token
2. **Search**: `GET /api/v3/protocols?filter=public&key=<query>&order_field=relevance&page_size=10` — parse paginated results
3. **Retrieve**: `GET /api/v4/protocols/<id>?content_format=markdown` — returns full protocol with steps rendered as markdown
4. **Steps**: `GET /api/v4/protocols/<id>/steps?content_format=markdown` — returns ordered step list

**Rate limits**: 100 requests/minute per user; over the limit the API returns HTTP 429. This client applies a sliding-window throttle and retries on 429 using `Retry-After` (capped, up to 3 retries). The `/view/[protocol-uri].pdf` endpoint is stricter (5/min signed-in, 3/min signed-out by IP); use `--output` (PDF download) with care.

## Example Queries

- "Search protocols.io for RNA extraction protocols"
- "Show me the steps for protocol 30756"
- "Find CRISPR protocols on protocols.io"
- "Get the protocol with DOI 10.17504/protocols.io.baaciaaw"
- "Log in to protocols.io to access my private protocols"

## Output Structure

Without `--output`: results are printed to the terminal as markdown. With `--output <dir>`: all modes save `report.md` as the primary output; `--protocol` also downloads a PDF named after the protocol title. All modes write a `reproducibility/` bundle (`commands.sh`, `checksums.sha256`, `environment.yml`).

## Dependencies

**Required** (core dependency in `pyproject.toml`):
- `requests` >= 2.28 — HTTP client for API calls

**Optional**:
- A protocols.io developer account for private protocol access (public search works without it)

## Safety

- **Local-first**: Token is read from the environment and never written to disk; no data uploaded
- **Disclaimer**: Every report includes the ClawBio medical disclaimer
- **No credential leakage**: Client secret and tokens never appear in reports or logs
- **Read-only by default**: The skill only reads protocols; no create/edit/delete operations
- **Rate-limit aware**: Client-side 100 req/min sliding window; automatic back-off on HTTP 429

## Integration with Bio Orchestrator

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio