Getting Started with Lobster AI

Welcome to Lobster AI! This quick start guide will have you analyzing bioinformatics data in minutes.

Quick Start (5 minutes)

1. Prerequisites

• Python 3.11-3.14 (Python 3.12+ recommended)
• Git for cloning the repository
• LLM Provider (choose one):
  • Claude API Key (Recommended - best quality)
  • AWS Bedrock Access (For enterprise/AWS users)
  • Google Gemini API Key (Free tier available)
  • Ollama (Local, privacy-first)
• NCBI API Key (optional, for enhanced literature search)

2. Choose Installation Method

Quick Decision:

• Want lobster command everywhere? → Global Installation
• Working on specific project? → Local Installation

Global Installation (Recommended for Most Users)

# Install uv if needed
# macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Lobster globally
uv pip install lobster-ai

This makes lobster command available system-wide.

Local Installation (Project-Specific)

# In your project directory
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install lobster-ai

This installs Lobster in your project's virtual environment only.

3. Configure API Keys

Run the interactive configuration wizard:

# For local installation, activate virtual environment first
source .venv/bin/activate  # Skip if using global installation

# Launch configuration wizard
lobster init

The wizard will guide you through:

• ✅ Choosing your LLM provider (Anthropic, AWS Bedrock, Google Gemini, or Ollama)
• ✅ Entering your API keys securely (input is masked)
• ✅ Selecting model for your provider (e.g., Gemini 3 Pro vs Flash)
• ✅ Optionally configuring NCBI API key for enhanced literature search
• ✅ Creating two config files:
  • provider_config.json - Provider selection (safe to commit)
  • .env - API keys and secrets (never commit)

Configuration management:

# Test your configuration
lobster config test

# View current configuration (secrets masked)
lobster config show

# Reconfigure (creates backup)
lobster init --force

Manual configuration (advanced users only): If you prefer, create two files manually:

1. .lobster_workspace/provider_config.json (provider selection):

{
  "global_provider": "anthropic",
  "anthropic_model": "claude-sonnet-4-20250514",
  "profile": "production"
}

2. .env (API keys - never commit to git):

# Option 1: Anthropic API
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx

# Option 2: AWS Bedrock
AWS_BEDROCK_ACCESS_KEY=your-aws-access-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-aws-secret-key

# Option 3: Google Gemini
GOOGLE_API_KEY=your-google-api-key
LOBSTER_LLM_PROVIDER=gemini

# Option 4: Ollama (local)
LOBSTER_LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434

# Optional: NCBI API key
NCBI_API_KEY=your-ncbi-api-key-here

4. Test Installation

Global installation:

# Command works from anywhere
lobster --help
lobster chat

Local installation:

# Activate virtual environment first
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Then use Lobster
lobster --help
lobster chat

5. Your First Analysis

Try this example in the chat interface:

🦞 You: Download and analyze GSE109564 from GEO database

🦞 Lobster: I'll download and analyze this single-cell RNA-seq dataset for you...

[Downloads data and performs quality control, filtering, clustering, and marker gene analysis]

What Can Lobster Do?

Single-Cell RNA-seq Analysis

• Quality control and filtering
• Normalization and scaling
• Clustering (Leiden algorithm)
• Marker gene identification
• Cell type annotation
• Trajectory analysis

Bulk RNA-seq Analysis

• Differential expression with pyDESeq2
• Complex experimental design support
• Batch effect correction
• Pathway enrichment analysis

Proteomics Analysis

• Mass spectrometry data processing
• Missing value pattern analysis
• Statistical testing with FDR control
• Protein network analysis
• Affinity proteomics (Olink panels)

Multi-Omics Integration

• Cross-platform data integration
• Joint clustering and analysis
• Correlation network analysis
• Integrated visualization

Literature Mining

• Automatic parameter extraction from publications
• PubMed literature search
• GEO dataset discovery
• Method validation against published results

Essential Commands

Once in the chat interface (lobster chat), try these commands:

Example Workflows

Quick Dataset Analysis

🦞 You: Load my_data.csv as single-cell RNA-seq data and perform standard analysis

Literature-Guided Analysis

🦞 You: Find optimal clustering parameters for my single-cell data based on recent publications

Multi-Dataset Integration

🦞 You: Load GSE12345 and GSE67890, then compare their cell populations

Custom Analysis

🦞 You: Perform differential expression between clusters 2 and 5 using a negative binomial model

Getting Help

• Type /help in the chat for command reference
• Check /status to verify system health
• Use /files to see what data is available
• Try /dashboard for system overview

Troubleshooting Quick Fixes

Installation fails?

make clean-install  # Clean installation

API errors?

lobster config test  # Test API connectivity

Memory issues?

export LOBSTER_PROFILE=development  # Use lighter resource profile

Need help?

lobster chat  # Then type /help

Uninstalling

Remove Lobster

Global installation:

uv tool uninstall lobster-ai

Local installation:

source .venv/bin/activate
pip uninstall lobster-ai
deactivate
rm -rf .venv  # Optional: remove virtual environment

Remove User Data (Optional)

⚠️ Deletes all analysis history!

rm -rf ~/.lobster ~/.lobster_workspace

For more details, see the Installation Guide.

Ready to dive deeper? Check out the comprehensive installation guide for advanced setup options, Docker deployment, and development installation.