Metadata-Version: 2.4
Name: bio-simulagent-client
Version: 0.5.1
Summary: Python client library for BioSimulagent - AI-powered computational biology toolkit
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: license-file

# bio-simulagent

[![CI](https://github.com/surplus96/bio-simulagent/workflows/Test%20%26%20Quality/badge.svg)](https://github.com/surplus96/bio-simulagent/actions)
[![PyPI version](https://badge.fury.io/py/bio-simulagent-client.svg)](https://badge.fury.io/py/bio-simulagent-client)
[![Python versions](https://img.shields.io/pypi/pyversions/bio-simulagent-client.svg)](https://pypi.org/project/bio-simulagent-client/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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](https://pypi.org/project/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

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