-
Notifications
You must be signed in to change notification settings - Fork 3
13 api overview
Tyo edited this page Dec 8, 2025
·
3 revisions
The Lobster AI API provides a comprehensive set of interfaces for multi-omics bioinformatics analysis through a professional agent-based architecture. This reference documentation covers all public APIs, classes, and interfaces available in the Lobster AI system.
The Lobster AI API is organized into five main categories:
The foundational layer providing data management, client interfaces, and system orchestration:
- DataManagerV2: Multi-modal data orchestration with provenance tracking
- Client Interfaces: BaseClient, AgentClient, APIAgentClient for local/cloud execution
- Provenance System: W3C-PROV compliant tracking of analysis operations
- Schema Validators: Data validation for transcriptomics and proteomics
Specialized AI agents for different analytical domains:
- SingleCell Expert: Single-cell RNA-seq analysis with formula-guided differential expression
- Bulk RNA-seq Expert: Bulk RNA-seq analysis with pyDESeq2 integration
- Proteomics Experts: MS and affinity proteomics analysis (DDA/DIA workflows)
- Data Expert: Data loading, quality assessment, and GEO dataset management
- Research Agent: Literature mining and computational parameter extraction
- ML Expert: Machine learning transformations and model preparation
Stateless analysis services implementing scientific algorithms:
- Transcriptomics Services: Preprocessing, clustering, differential analysis
- Proteomics Services: Missing value handling, normalization, statistical testing
- Utility Services: GEO downloading, publication mining, visualization
Abstract base classes defining system contracts:
- BaseClient: Client interface for local/cloud consistency
- IDataBackend: Storage backend abstraction (H5AD, MuData, cloud)
- IModalityAdapter: Data format adapters for different modalities
- IValidator: Flexible validation with warnings instead of hard failures
Agent registry and system configuration:
- Agent Registry: Centralized agent configuration and discovery
- Model Configuration: Per-agent LLM settings with fallback mechanisms
- System Settings: Environment-based configuration management
- Specialist Agents: Each agent handles specific biological domains
- Tool Pattern: All agent tools follow validate → service → store → log pattern
- Centralized Registry: Single source of truth for agent configuration
- Dynamic Handoffs: Automatic agent-to-agent task routing
- Multi-Modal Support: Unified handling of transcriptomics, proteomics, and future modalities
- Professional Naming: Consistent dataset naming conventions throughout pipeline
- Provenance Tracking: Complete audit trail of all processing operations
- Schema Validation: Type-safe data handling with modality-specific requirements
- Interface Consistency: Same API works for local and cloud execution
- Graceful Fallback: Automatic switching between execution modes
- Unified CLI: Single command-line interface for all deployment types
- Session Management: Consistent state handling across environments
- Publication Quality: All analyses meet scientific publication standards
- Error Handling: Comprehensive validation with actionable error messages
- Reproducibility: Complete provenance and parameter tracking
- Best Practices: Implementation of current bioinformatics standards
All service methods follow the stateless pattern:
def analyze_method(adata: anndata.AnnData, **params) -> Tuple[anndata.AnnData, Dict[str, Any]]All agent tools follow the standard pattern:
@tool
def agent_tool(modality_name: str, **params) -> str:
# 1. Validate modality exists
# 2. Call stateless service
# 3. Store results with descriptive naming
# 4. Log operation for provenance
# 5. Return formatted response- Specific Exceptions: Custom exception hierarchy for different error types
- Validation Results: Flexible validation with errors, warnings, and info messages
- Graceful Degradation: Continue analysis when possible, warn about limitations
-
Services: Return
Tuple[AnnData, Dict]with processed data and statistics - Agent Tools: Return formatted strings for LLM consumption
- Clients: Return structured dictionaries with success, response, and metadata
User Input (CLI/API)
↓
BaseClient Implementation
↓
Agent System (LangGraph)
↓
Agent Tools (@tool decorated)
↓
Stateless Services
↓
DataManagerV2 (storage)
↓
Backends (H5AD/MuData/Cloud)
# Required for LLM access
AWS_BEDROCK_ACCESS_KEY=your-aws-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-aws-secret
# Optional for enhanced features
NCBI_API_KEY=your-ncbi-key
LOBSTER_CLOUD_KEY=your-cloud-key # Enables cloud mode- Per-Agent Settings: Each agent can use different LLM configurations
- Fallback Mechanisms: Automatic fallback to alternative models
- Thinking Mode: Support for reasoning-capable models (Claude, GPT-4)
- Temperature Control: Fine-tuned parameters per agent type
from lobster.core.client import AgentClient
from lobster.core.data_manager_v2 import DataManagerV2
# Initialize data manager
data_manager = DataManagerV2(workspace_path="./my_workspace")
# Create client
client = AgentClient(data_manager=data_manager)
# Query the system
result = client.query("Load GSE194247 and perform quality assessment")# Set environment variable
os.environ['LOBSTER_CLOUD_KEY'] = 'your-key'
# Import cloud client (external package)
from lobster_cloud.client import CloudLobsterClient
client = CloudLobsterClient()
result = client.query("Analyze my single-cell data")# Interactive mode with autocomplete
lobster chat
# Direct commands
lobster --helpThis API reference is organized as follows:
- Core API Reference: DataManagerV2, clients, provenance
- Agents API Reference: All agent tools and capabilities
- Services API Reference: Analysis services and algorithms
- Interfaces API Reference: Abstract base classes and contracts
Each section provides:
- Class and method signatures with type hints
- Parameter descriptions and expected types
- Return value specifications
- Usage examples and common patterns
- Error conditions and exception handling
- Integration notes for cloud/local environments
This API documentation reflects the current version of Lobster AI. The system maintains:
- Backward Compatibility: Existing agent tools remain functional
- Interface Stability: Core interfaces follow semantic versioning
- Deprecation Warnings: Clear migration paths for deprecated features
- Cloud Synchronization: API compatibility between local and cloud versions