flow-bio

Files (5)

• SKILL.md
• demo_cache.json · data/
• flow_bio.py
• __init__.py · tests/
• test_flow_bio.py · tests/

SKILL.md (first lines)

# Flow Bio Bridge

**ClawBio's gateway to the Flow.bio platform — browse, search, upload, and launch bioinformatics pipelines on Flow from the command line.**

## Why This Exists

Flow.bio is a bioinformatics platform hosting curated Nextflow pipelines with managed compute, sample tracking, and collaborative project management. But interacting with Flow requires navigating the web UI or writing custom API scripts.

Flow Bio Bridge makes the platform **agent-accessible**: authenticate once, then list pipelines, upload samples, launch executions, and poll for results — all from the CLI or via the ClawBio orchestrator.

- **Without it**: Users must switch between web UI and local analysis, manually track execution IDs, and write one-off upload scripts
- **With it**: A single CLI covers discovery, upload, execution, and status checking across any Flow instance
- **Why ClawBio**: Chain Flow pipeline outputs with local ClawBio skills (e.g. Flow RNA-seq → ClawBio diffviz)

## Core Capabilities

1. **Authentication** — Login via username/password, existing JWT token, or environment variables
2. **Pipeline discovery** — List and inspect available Nextflow pipelines with versions and parameter schemas
3. **Sample management** — List, search, and upload samples with metadata and organism tagging
4. **Project browsing** — List owned/shared projects and their contents
5. **Execution tracking** — Launch pipeline runs, poll status, and retrieve logs
6. **Search** — Full-text search across samples, projects, data, and executions
7. **Data listing** — Browse owned and shared data files
8. **Organism & type discovery** — List available organisms and sample types for uploads
9. **Overview mode** — Live overview of any Flow instance; public data without credentials, full account view with login

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| FASTQ (single-end) | `.fq`, `.fastq`, `.fq.gz` | reads1 | `sample_R1.fastq.gz` |
| FASTQ (paired-end) | `.fq`, `.fastq`, `.fq.gz` | reads1, reads2 | `sample_R1.fastq.gz`, `sample_R2.fastq.gz` |
| Any data file | any | — | annotation, reference, BED, etc. |

## Workflow

When the user asks to interact with Flow.bio:

1. **Authenticate**: Use stored token, env vars, or prompt for credentials
2. **Discover**: List pipelines, sample types, organisms as needed
3. **Act**: Upload samples, launch executions, or query status
4. **Report**: Write structured output (JSON + markdown) to output directory
5. **Bundle**: Generate reproducibility commands and checksums

## CLI Reference

```bash
# Login (stores token for subsequent calls)
python skills/flow-bio/flow_bio.py --login --username USER --password PASS
python skills/flow-bio/flow_bio.py --login --token TOKEN

# Discovery
python skills/flow-bio/flow_bio.py --pipelines
python skills/flow-bio/flow_bio.py --samples
python skills/flow-bio/flow_bio.py --projects
python skills/flow-bio/flow_bio.py --organisms
python skills/flow-bio/flow_bio.py --sample-types
python skills/flow-bio/flow_bio.py --executions
python skills/flow-bio/flow_bio.py --data

# Inspect details
python skills/flow-bio/flow_bio.py --execution EXEC_ID
python skills/flow-bio/flow_bio.py --sample SAMPLE_ID
python skills/flow-bio/flow_bio.py --pipeline PIPELINE_ID

# Inspect details via clawbio.py runner (uses --*-detail flags)
python clawbio.py run flow --execution-detail EXEC_ID
python clawbio.py run flow --sample-detail SAMPLE_ID
python clawbio.py run flow --pipeline-detail PIPELINE_ID

# Search
python skills/flow-bio/flow_bio.py --search "RNA-seq tumor"

# Raw JSON output (for piping to jq, etc.)
python skills/flow-bio/flow_bio.py --samples --json

# Upload sample
python skills/flow-bio/flow_bio.py --upload-sample \
  --name "Tumour_01" --sample-type "RNA-Seq" \
  --reads1 R1.fastq.gz --reads2 R2.fastq.gz \
  --organism "Homo sapiens" --project PROJECT_ID

# Launch pipeline
python skills/flow-bio/flow_bio.py --run-pipeline PIPELINE_VERSION_ID \
  --run-samples SAMPLE_ID1,SAMPLE_ID2 --output /tmp/flow_run

# Check execution status
python skills/flow-bio/flow_bio.py --execution EXEC_ID --output /tmp/flow_status

# Overview (public endpoints, no credentials needed)
python skills/flow-bio/flow_bio.py --demo --output /tmp/flow_demo

# Overview with authentication (shows owned samples, projects, executions)
python skills/flow-bio/flow_bio.py --demo --username USER --password PASS --output /tmp/flow_demo
```

## Demo

```bash
# Public overview (no credentials)
python skills/flow-bio/flow_bio.py --demo --output /tmp/flow_demo

# Full overview with account data
python skills/flow-bio/flow_bio.py --demo --username USER --password PASS --output /tmp/flow_demo
```

Expected output: a live overview of the Flow.bio instance showing available
pipelines, organisms, and sample types (public), plus owned samples, projects,
and executions if authenticated.

## Algorithm / Methodology

1. **Token acquisition**: POST `/login` with credentials → JWT token (5-min access, 7-day refresh)
2. **API traversal**: RESTful GET/POST with `Authorization: Bearer <token>` header
3. **Pagination**: Offset-based (`?page=N`) with lazy loading
4. **Chunked upload**: Files split into 1 MB chunks, uploaded sequentially with progress tracking
5. **Execution polling**: GET `/executions/<id>` until status reaches terminal state

**Key parameters**:

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio