bio-simulagent

Version: Backend 0.1.0 | Client 0.3.0

Unix/Unix-like shell agentic workflow system utility for biological simulation and computational drug discovery.

Overview

bio-simulagent is a comprehensive biological simulation platform consisting of:

1. Python Client Library (📦 bio-simulagent-client) - MCP client for reproducible research workflows
2. TypeScript CLI Frontend - Interactive terminal dashboard for workflow orchestration
3. Python MCP Backend - 25 tools across 4 biological domains

The platform is designed for computational biologists and drug discovery researchers who need reproducible, scalable workflows.

Key Features

• Interactive Dashboard: Full-featured terminal UI with 4-panel layout
  • Workflow DAG visualization
  • Agent status monitoring (5 specialized agents)
  • Real-time log streaming with filtering
  • Task queue management
• MCP Protocol: 25 tools and 3 resources for biological simulation
• Plugin Architecture: Modular design with 4 bio plugins
  • bio_design: Molecular design and optimization
  • bio_literature: Literature search and analysis
  • bio_neural: Neural dynamics simulation
  • bio_simulation: Molecular simulation workflows
• Multiple CLI Modes: Interactive, Run, List, and Status modes
• State Management: Zustand-based reactive state stores

CI/CD Pipeline

This project uses automated testing and quality gates to ensure code reliability:

• Automated Testing: All 271 unit tests run on every push/PR
• Code Quality: Ruff linting and Black formatting enforced
• Type Safety: TypeScript type-checking with tsc
• Coverage: 66% test coverage (target: 85%)
• Fast Feedback: CI completes in ~45 seconds
• Pre-commit Hooks: 10 hooks for local validation

Running Tests Locally

# Python tests with coverage
cd backend
pytest tests/unit/ -v --cov=backend --cov-report=html

# TypeScript type-check and build
npm run typecheck
npm run build

# Code quality checks
ruff check backend/
black --check backend/
npm run lint

See docs/guides/ci-cd-guide.md for detailed setup and troubleshooting.

Requirements

System Requirements

• Node.js: >= 20.0.0
• npm: >= 10.0.0
• Python: >= 3.11 (tested with 3.11.14)

Python Dependencies

The following packages are required in the Python virtual environment:

fastmcp>=2.14.5
mcp>=1.26.0
pydantic>=2.12.5

TypeScript Dependencies

Core dependencies (automatically installed via npm):

{
  "@modelcontextprotocol/sdk": "^1.26.0",
  "ink": "^5.1.0",
  "react": "^18.3.1",
  "zustand": "^5.0.0",
  "zod": "^4.3.6",
  "meow": "^13.0.0"
}

Installation

1. Clone and Setup

git clone <repository-url>
cd bio-simulagent

2. Install Frontend Dependencies

npm install
npm run build

3. Setup Python Environment

# Create virtual environment with Python 3.11+
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install Python dependencies
pip install fastmcp mcp pydantic

Usage

Interactive Mode (Default)

Launch the full dashboard with real-time monitoring:

# Make sure virtual environment is activated
source .venv/bin/activate

# Run the CLI
node dist/cli.js
# or simply
bio-simulagent

Keyboard Shortcuts:

• q - Quit
• Tab - Cycle panel focus
• c - Cancel active workflow
• l - Cycle log level (DEBUG/INFO/WARNING/ERROR)
• f - Toggle agent filter
• r - Refresh data
• ↑/↓ - Scroll log stream (when focused)

Run Mode

Execute a specific workflow with monitoring:

node dist/cli.js run <workflow_name> --objective "Your objective"

# Example:
node dist/cli.js run ligand_optimization --objective "Optimize ACE2 inhibitor"

List Mode

Display available workflows and agents:

node dist/cli.js list

Status Mode

Check the status of a specific workflow:

node dist/cli.js status <job_id>

Development Mode

For development with hot-reload (requires tsx):

⚠️ Note: Due to Claude Code sandbox restrictions, npm run dev may not work. Use the compiled version instead:

npm run build && node dist/cli.js

Testing Results (Week 1)

TypeScript

• Type Checking: ✅ 0 errors
• Build: ✅ Success
• Runtime: ✅ All modes functional

Python Backend

• pytest: ✅ 12/12 tests passed
• Ruff: ✅ 0 lint errors
• MCP Tools: ✅ 25 tools discovered
• MCP Resources: ✅ 3 resources discovered
• Plugins: ✅ 4 plugins loaded

UI Verification

• ✅ Header bar with version and connection status
• ✅ 4-panel layout (DAG, Agents, Log, Tasks)
• ✅ Real-time agent status (5 agents)
• ✅ Interactive keyboard controls
• ✅ Log filtering and scrolling

Known Issues and Resolutions

Issue #1: Resource URI Mismatch ✅ Resolved

Problem: Resource URIs in documentation didn't match implementation.

Solution: Added workflow://templates, agent://registry, and plugin://catalog resources.

Files Modified: backend/mcp/resources/core_resources.py

Issue #2: Python Command Compatibility ✅ Resolved

Problem: npm run dev froze on macOS due to using python instead of python3.

Solution: Updated src/lib/mcp-client.ts to use python3 command.

Files Modified: src/lib/mcp-client.ts (line 10)

Issue #3: fullscreen-ink Compatibility ⚠️ Workaround Applied

Problem: CLI immediately exits when using withFullScreen() from fullscreen-ink library.

Current Workaround: Disabled fullscreen mode, using regular render() instead.

Impact: Terminal buffer switching disabled, but all functionality works.

Future Action: Consider upgrading fullscreen-ink or using alternative library.

Files Modified: src/cli.tsx (lines 60-66)

Project Structure

bio-simulagent/
├── src/                    # TypeScript frontend
│   ├── cli.tsx            # CLI entry point
│   ├── app.tsx            # Main React app
│   ├── components/        # Ink UI components
│   ├── hooks/             # React hooks (MCP, polling, logs)
│   ├── stores/            # Zustand state stores
│   ├── lib/               # MCP client
│   └── types/             # TypeScript types
├── backend/               # Python MCP backend
│   ├── main.py           # MCP server entry point
│   ├── mcp/              # MCP app and handlers
│   ├── plugins/          # Plugin system
│   ├── agents/           # Agent implementations
│   ├── core/             # Core utilities
│   ├── workflows/        # Workflow definitions
│   └── tests/            # Python tests
├── docs/                  # Documentation
│   ├── TODO-2026-02-09.md
│   └── TESTING-GUIDE.md
└── dist/                  # Compiled TypeScript

Development Commands

# Build TypeScript
npm run build

# Type checking
npm run typecheck

# Run Python tests
source .venv/bin/activate
pytest backend/tests

# Run Python linter
ruff check backend/

# Discover plugins programmatically
python3 -c "from backend.plugins.loader import PluginLoader; print(PluginLoader().discover())"

Architecture

Frontend (TypeScript + Ink)

• Framework: Ink (React for CLIs) with React 18.3
• State Management: Zustand for reactive stores
• CLI Parsing: meow for argument parsing
• MCP Client: @modelcontextprotocol/sdk with stdio transport

Backend (Python 3.11+)

• Protocol: MCP (Model Context Protocol) over stdio
• Framework: fastmcp for server implementation
• Plugins: Dynamic plugin discovery with manifest system
• Agents: 5 specialized agents for biological simulation
  • Design Agent
  • Literature Agent
  • Neural Dynamic Agent
  • Simulation Agent
  • Self-Correction Agent

Error Handling

bio-simulagent includes a comprehensive error handling system for production-ready reliability:

Features

• 14 Custom Exception Types: Domain-specific exceptions with structured error details
• Exponential Backoff Retry: Automatic retry with jitter for transient failures
• Circuit Breaker Pattern: Prevents cascading failures in external API calls
• Structured JSON Logging: Full error context for debugging
• 90%+ Test Coverage: 126 comprehensive unit tests

Quick Example

from backend.core.exceptions import NetworkError, InvalidSMILESError
from backend.core.retry import retry_with_backoff, RETRY_CONFIG_AGGRESSIVE
from backend.core.circuit_breaker import CircuitBreaker

# Validate input
if not is_valid_smiles(smiles):
    raise InvalidSMILESError(smiles, details={"hint": "Invalid format"})

# API call with retry + circuit breaker
alphafold_circuit = CircuitBreaker(name="AlphaFold API", failure_threshold=5)

result = await alphafold_circuit.call(
    retry_with_backoff,
    make_api_request,
    protein_id="P12345",
    config=RETRY_CONFIG_AGGRESSIVE,
    retryable_exceptions=(NetworkError, APITimeoutError)
)

Exception Categories

Category	Examples	Recoverable	Retry
Network	NetworkError, APITimeoutError, APIRateLimitError	Yes	Yes
Validation	InvalidSMILESError, InvalidPDBError, ValidationError	No	No
Resource	ResourceUnavailableError, DatabaseError	Yes	Yes
Computation	ComputationError, ConfigurationError	No	No

Documentation

• Comprehensive Guide: See docs/guides/error-handling.md
• Test Examples: See tests/unit/ for 126 usage examples
• Implementation: See backend/core/ for all error handling modules

Testing Error Handling

# Run error handling tests
pytest tests/unit/ -v

# Check coverage (90%+ achieved)
pytest tests/unit/ --cov=backend.core --cov-report=term-missing

Contributing

1. Ensure Python 3.11+ and Node.js 20+ are installed
2. Activate virtual environment before running CLI
3. Run tests before submitting changes
4. Follow TypeScript and Python linting rules

License

(Add license information here)

Version History

0.1.0 (2026-02-09)

• Initial release
• Interactive dashboard with 4-panel layout
• 25 MCP tools and 3 resources
• 4 biological simulation plugins
• Multiple CLI modes (interactive, run, list, status)
• Comprehensive testing suite