Metadata-Version: 2.4
Name: bio-simulagent-client
Version: 0.3.0
Summary: Python client library for BioSimulagent - AI-powered computational biology toolkit
Home-page: https://github.com/surplus96/bio-simulagent
Author: surplus96
Author-email: BioSimulagent Team <surplus96@example.com>
Maintainer-email: BioSimulagent Team <surplus96@example.com>
License: MIT
Project-URL: Homepage, https://github.com/surplus96/bio-simulagent
Project-URL: Documentation, https://bio-simulagent.readthedocs.io
Project-URL: Repository, https://github.com/surplus96/bio-simulagent
Project-URL: Issues, https://github.com/surplus96/bio-simulagent/issues
Project-URL: Changelog, https://github.com/surplus96/bio-simulagent/blob/main/CHANGELOG.md
Keywords: computational-biology,drug-discovery,molecular-dynamics,protein-structure,ligand-design,jupyter,mcp,reproducible-research,bioinformatics,cheminformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: Jupyter
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: jupyter
Requires-Dist: ipython>=8.0; extra == "jupyter"
Requires-Dist: nest-asyncio>=1.5.0; extra == "jupyter"
Requires-Dist: nglview>=3.0; extra == "jupyter"
Requires-Dist: mdtraj>=1.9; extra == "jupyter"
Requires-Dist: plotly>=5.0; extra == "jupyter"
Requires-Dist: matplotlib>=3.5; extra == "jupyter"
Requires-Dist: pandas>=1.5; extra == "jupyter"
Requires-Dist: numpy>=1.21; extra == "jupyter"
Requires-Dist: pyyaml>=6.0; extra == "jupyter"
Provides-Extra: viz
Requires-Dist: nglview>=3.0; extra == "viz"
Requires-Dist: mdtraj>=1.9; extra == "viz"
Requires-Dist: plotly>=5.0; extra == "viz"
Requires-Dist: matplotlib>=3.5; extra == "viz"
Requires-Dist: pandas>=1.5; extra == "viz"
Requires-Dist: numpy>=1.21; extra == "viz"
Provides-Extra: advanced
Requires-Dist: scikit-learn>=1.0; extra == "advanced"
Requires-Dist: scipy>=1.7; extra == "advanced"
Requires-Dist: tables>=3.7; extra == "advanced"
Requires-Dist: pyarrow>=10.0; extra == "advanced"
Requires-Dist: python-dotenv>=0.19; extra == "advanced"
Requires-Dist: structlog>=21.0; extra == "advanced"
Requires-Dist: psutil>=5.8; extra == "advanced"
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: isort>=5.12; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: safety>=2.3; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.21; extra == "docs"
Requires-Dist: m2r2>=0.3; extra == "docs"
Provides-Extra: all
Requires-Dist: bio-simulagent-client[advanced,dev,docs,jupyter,viz]; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# bio-simulagent

![CI](https://github.com/surplus96/bio-simulagent/workflows/Test%20%26%20Quality/badge.svg)

**Version:** 0.1.0

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

## Overview

bio-simulagent is a TypeScript CLI frontend with Python MCP (Model Context Protocol) backend designed for orchestrating complex biological simulation workflows. It provides an interactive terminal dashboard for monitoring agent activities, workflow execution, and real-time log streaming.

### 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

```bash
# 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](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):

```json
{
  "@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

```bash
git clone <repository-url>
cd bio-simulagent
```

### 2. Install Frontend Dependencies

```bash
npm install
npm run build
```

### 3. Setup Python Environment

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
node dist/cli.js list
```

### Status Mode

Check the status of a specific workflow:

```bash
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:

```bash
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

```bash
# 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

```python
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](docs/guides/error-handling.md)
- **Test Examples**: See [tests/unit/](tests/unit/) for 126 usage examples
- **Implementation**: See [backend/core/](backend/core/) for all error handling modules

### Testing Error Handling

```bash
# 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
