Lobster AI Development Guide

---

name: lobster-dev

description: |

Develop, extend, and contribute to Lobster AI — the multi-agent bioinformatics engine.

Use when working on Lobster codebase, creating agents/services, understanding architecture,

fixing bugs, adding features, or contributing to the open-source project.

Trigger phrases: "add agent", "create service", "extend lobster", "contribute",

"understand architecture", "how does X work in lobster", "fix bug", "add feature",

"write tests", "lobster development", "agent development", "bioinformatics code"

---

# Lobster AI Development Guide

**Lobster AI** is a multi-agent bioinformatics platform using LangGraph for orchestration.

This skill teaches you how to work with, extend, and contribute to the codebase.

Quick Navigation

| Task | Documentation |

|------|---------------|

| **Architecture overview** | [references/architecture.md](references/architecture.md) |

| **Creating new agents** | [references/creating-agents.md](references/creating-agents.md) |

| **Creating new services** | [references/creating-services.md](references/creating-services.md) |

| **Code layout & finding files** | [references/code-layout.md](references/code-layout.md) |

| **Testing patterns** | [references/testing.md](references/testing.md) |

| **CLI reference** | [references/cli.md](references/cli.md) |

Critical Rules

1. **ComponentRegistry is truth** — Agents discovered via entry points, NOT hardcoded

2. **AGENT_CONFIG at module top** — Define before heavy imports for <50ms discovery

3. **Services return 3-tuple** — `(AnnData, Dict, AnalysisStep)` always

4. **Always pass `ir`** — `log_tool_usage(..., ir=ir)` for reproducibility

5. **No `lobster/__init__.py`** — PEP 420 namespace package

Package Structure

lobster/
├── packages/                    # Agent packages (PEP 420)
│   ├── lobster-transcriptomics/ # transcriptomics_expert, annotation_expert, de_analysis_expert
│   ├── lobster-research/        # research_agent, data_expert_agent
│   ├── lobster-visualization/   # visualization_expert
│   ├── lobster-metadata/        # metadata_assistant
│   ├── lobster-structural-viz/  # protein_structure_visualization_expert
│   ├── lobster-genomics/        # genomics_expert
│   ├── lobster-proteomics/      # proteomics_expert
│   └── lobster-ml/              # machine_learning_expert
└── lobster/                     # Core SDK
    ├── agents/supervisor.py     # Supervisor (stays in core)
    ├── agents/graph.py          # LangGraph builder
    ├── core/                    # Infrastructure (registry, data_manager, provenance)
    ├── services/                # Analysis services
    └── tools/                   # Agent tools

Quick Commands

# Setup (development)
make dev-install              # Full dev setup with editable install
make test                     # Run all tests
make format                   # black + isort

# Setup (end-user testing via uv tool)
uv tool install 'lobster-ai[full,anthropic]'   # Install as users see it
uv tool upgrade lobster-ai                      # Upgrade to latest

# Running
lobster chat                  # Interactive mode
lobster query "your request"  # Single-turn

# Testing
pytest tests/unit/            # Fast unit tests
pytest tests/integration/     # Integration tests

Service Pattern (Essential)

All services return a 3-tuple:

def analyze(self, adata, **params) -> Tuple[AnnData, Dict, AnalysisStep]:
    # Your analysis logic
    stats = {"n_cells": adata.n_obs, "status": "complete"}
    ir = AnalysisStep(
        activity_type="analyze",
        inputs={"n_obs": adata.n_obs},
        outputs=stats,
        params=params
    )
    return processed_adata, stats, ir

Tools wrap services:

@tool
def analyze_modality(modality_name: str, **params) -> str:
    result, stats, ir = service.analyze(adata, **params)
    data_manager.log_tool_usage("analyze", params, stats, ir=ir)  # IR mandatory!
    return f"Complete: {stats}"

Agent Registration (Entry Points)

Agents register via `pyproject.toml`:

[project.entry-points."lobster.agents"]
my_agent = "lobster.agents.my_domain.my_agent:AGENT_CONFIG"

AGENT_CONFIG must be defined at module top (before imports):

# lobster/agents/mydomain/my_agent.py
from lobster.config.agent_registry import AgentRegistryConfig

AGENT_CONFIG = AgentRegistryConfig(
    name="my_agent",
    display_name="My Expert Agent",
    description="What this agent does",
    factory_function="lobster.agents.mydomain.my_agent.my_agent",
    handoff_tool_name="handoff_to_my_agent",
    handoff_tool_description="Assign tasks for my domain analysis",
    tier_requirement="free",  # All official agents are free
)

# Heavy imports AFTER config
from lobster.core.data_manager_v2 import DataManagerV2
# ... rest of implementation

Key Files

| File | Purpose |

|------|---------|

| `lobster/agents/graph.py` | LangGraph orchestration |

| `lobster/core/component_registry.py` | Agent discovery |

| `lobster/core/data_manager_v2.py` | Data/workspace management |

| `lobster/core/provenance.py` | W3C-PROV tracking |

| `lobster/cli.py` | CLI implementation |

Online Documentation

Full documentation at **docs.omics-os.com** (or local `docs-site/`):

Common Tasks

Adding a New Agent

1. Create package: `packages/lobster-mydomain/`

2. Define AGENT_CONFIG at top of agent file

3. Register entry point in `pyproject.toml`

4. Implement agent with tools

5. Add tests in `tests/unit/agents/`

See [references/creating-agents.md](references/creating-agents.md) for full guide.

Adding a New Service

1. Create service class in appropriate package

2. Implement 3-tuple return pattern

3. Wrap in tool with `log_tool_usage`

4. Add unit tests

See [references/creating-services.md](references/creating-services.md) for full guide.

Understanding Data Flow

User Query → CLI → LobsterClientAdapter → AgentClient
                                              ↓
                            LangGraph (supervisor → agents)
                                              ↓
                               Services → DataManagerV2
                                              ↓
                                    Results + Provenance

Testing

# Unit tests (fast, no external deps)
pytest tests/unit/ -v

# Integration tests (may need env vars)
pytest tests/integration/ -v

# Specific test
pytest tests/unit/test_my_feature.py -v

# With coverage
pytest --cov=lobster tests/

Contributing

1. Fork the repository

2. Create feature branch: `git checkout -b feature/my-feature`

3. Make changes following patterns above

4. Run tests: `make test`

5. Format code: `make format`

6. Submit PR with clear description