lobster-use

# Lobster AI Usage Guide Lobster AI is a multi-agent bioinformatics platform. Users describe analyses in natural language -- Lobster routes to 22 specialist agents across 10 packages automatically. ## Requirements - **Binaries**: `lobster` CLI (`pip install lobster-ai`), Python 3.12+ - **Credential**: Exactly ONE LLM provider key as env var (not all — pick one): - `ANTHROPIC_API_KEY` | `GOOGLE_API_KEY` | `OPENAI_API_KEY` | `OPENROUTER_API_KEY` - `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (Bedrock — both required) - `AZURE_AI_ENDPOINT` + `AZURE_AI_CREDENTIAL` (Azure — both required) - Ollama: no key needed (local models) - **Optional**: `NCBI_API_KEY` for faster PubMed/GEO - **Writes**: `.lobster_workspace/` (data, credentials in `.env` mode 0600, outputs) - **Global config** (`--global` flag, NOT default): `~/.config/lobster/` — avoid unless needed - **Network**: LLM provider API + public bio databases (GEO, SRA, PRIDE, MetaboLights) ## Docs Discovery The docs site at **docs.omics-os.com** exposes LLM-friendly raw markdown: | Route | Use | |-------|-----| | `/llms.txt` | Index of all pages (title + URL + description) | | `/llms-full.txt` | Full content dump of all free pages | | `/raw/docs/{slug}.md` | Raw markdown for a specific page | **Workflow**: Fetch `/llms.txt` first to discover slugs, then fetch individual pages via `/raw/docs/{slug}.md`. Example: `https://docs.omics-os.com/raw/docs/tutorials/single-cell-rnaseq.md` ## Two Modes This skill supports coding agents in two modes: **Orchestrator** -- The agent calls `lobster query --json --session-id` programmatically, parses structured output, and chains multi-step analyses. See [agent-patterns.md](references/agent-patterns.md). **Guide** -- The agent teaches a human user what to type in `lobster chat` or `lobster query`. See the routing table below for which docs page to fetch. ## Quick Start ```bash # Install (PyPI -- preferred) pip install 'lobster-ai[full]' # or: uv tool install 'lobster-ai[full]' # Configure (uses env var -- never pass raw keys on command line) lobster init --non-interactive --anthropic-key "$ANTHROPIC_API_KEY" --profile production # Run analysis (always pass -w and --session-id together) lobster query -w ./my_analysis --session-id "proj" --json "Download GSE109564 and run QC" # Inspect workspace (no tokens burned, ~300ms) lobster command data --json -w ./my_analysis ``` **Source**: [github.com/the-omics-os/lobster](https://github.com/the-omics-os/lobster) | **PyPI**: [pypi.org/project/lobster-ai](https://pypi.org/project/lobster-ai/) ## Routing Table | You want to... | Docs slug | Skill reference | |---|---|---| | **Install & configure** | `getting-started/installation` | -- | | **Configuration options** | `getting-started/configuration` | -- | | **Use the CLI** | `guides/cli-commands` | [cli-reference.md](references/cli-reference.md) | | **Orchestrate programmatically** | -- | [agent-patterns.md](references/agent-patterns.md) | | **Analyze scRNA-seq** | `tutorials/single-cell-rnaseq` | -- | | **Analyze bulk RNA-seq** | `tutorials/bulk-rnaseq` | -- | | **Analyze proteomics** | `tutorials/proteomics` | -- | | **Understand data formats** | `guides/data-formats` | -- | | **Search literature / datasets** | `agents/research` | -- | | **Analyze genomics** | `agents/genomics` | -- | | **Analyze metabolomics** | `case-studies/metabolomics` | -- | | **ML / feature selection** | `agents/ml` | -- | | **Drug discovery** | `agents/drug-discovery` | -- | | **Visualize results** | `agents/visualization` | -- | | **Troubleshoot** | `support/troubleshooting` | -- | | **See case studies** | `case-studies/{domain}` | -- | | **All agent capabilities** | `agents` | -- | | **Extend Lobster (dev)** | -- | Use `lobster-dev` skill | To fetch a docs page: `https://docs.omics-os.com/raw/docs/{slug}.md` ## Hard Rules 1. **Always use `--session-id`** for multi-step analyses -- loaded data persists across queries 2. **Use `lobster command --json`** for workspace inspection (no tokens burned, ~300ms) 3. **Research Agent is the ONLY agent with internet access** -- all others operate on loaded data 4. **Never skip QC** before analysis -- always assess quality first 5. **Use `--json` flag** when parsing output programmatically 6. **Check data is loaded** before running analysis steps (`lobster command data --json`) 7. **Default workspace**: `.lobster_workspace/` -- override with `-w <path>` 8. **Fetch docs on demand** from `docs.omics-os.com/raw/docs/{slug}.md` -- don't guess workflows ## Agent Overview 22 agents across 10 packages. Supervisor routes automatically based on natural language. | Agent | Package | Handles | |---|---|---| | Supervisor | lobster-ai | Routes queries, coordinates agents | | Research Agent | lobster-research | PubMed, GEO, SRA, PRIDE, MetaboLights search (online) | | Data Expert | lobster-research | File loading, downloads, format conversion (offline) | | Transcriptomics Expert | lobster-transcriptomics | scRNA-seq + bulk RNA-seq: QC, clustering, trajectory | | Annotation Expert | lobster-transcriptomics | Cell type annotation, gene set enrichment (child) | | DE Analysis Expert | lobster-transcriptomics | Differential expression, pseudobulk, GSEA (child) | | Proteomics Expert | lobster-proteomics | MS + affinity import, QC, normalization, batch correction | | Proteomics DE Expert | lobster-proteomics | Protein DE, pathway enrichment, KSEA, STRING PPI (child) | | Biomarker Discovery | lobster-proteomics | Panel selection, nested CV, hub proteins (child) | | Metabolomics Expert | lobster-metabolomics | LC-MS/GC-MS/NMR: QC, normalization, PCA/PLS-DA, annotation | | Genomics Expert | lobster-genomics | VCF/PLINK: QC, GWAS, variant annotation | | Variant Analysis Expert | lobster-genomics | VEP annotation, ClinVar, clinical prioritization (child) | | ML Expert | lobster-ml | ML prep, scVI embeddings, data export | | Feature Selection Expert | lobster-ml | Stability selection, LASSO, variance filtering (child) | | Survival Analysis Expert | lobster-ml | Cox models, Kaplan-Meier, risk stratification (child) | | Drug Discovery Expert | lobster-drug-discovery | Drug target validation, compound profiling | | Cheminformatics Expert | lobster-drug-discovery | Molecular descriptors, fingerprints, similarity (child) | | Clinical Dev Expert | lobster-drug-discovery | Trial design, endpoint analysis, safety signals (child) | | Pharmacogenomics Expert | lobster-drug-discovery | PGx variants, drug-gene interactions (child) | | Visualization Expert | lobster-visualization | UMAP, heatmaps, volcano plots, dot plots (Plotly) | | Metadata Assistant | lobster-metadata | ID mapping, metadata standardization (internal) | | Protein Structure Viz | lobster-structural-viz | PDB fetch, PyMOL visualization, RMSD | Per-agent docs: `https://docs.omics-os.com/raw/docs/agents/{domain}.md`