IrisAI

Multi-agent AI assistant for HPC workflow.

IrisAI enables researchers and HPC users to interact with cluster resources, manage jobs, analyze data, and run bioinformatics workflows through natural language conversation.

Features

• Multi-agent architecture — Supervisor routes requests to specialized agents (code execution, search, AlphaFold, history)
• Slurm integration — Submit, monitor, and manage HPC jobs via natural language
• Bioinformatics tools — AlphaFold3 structure prediction, sequence analysis, VCF processing
• File system operations — Read, write, search, and analyze files on HPC storage
• Conversation history — Persistent session memory across interactions
• MCP server architecture — Modular tool servers using the Model Context Protocol
• Open OnDemand integration — Deploy as an OnDemand interactive app
• Containerized execution — Singularity/Apptainer containers for isolated, reproducible deployment

Architecture

User (Browser)
    ↓
Open OnDemand (authentication + job launch)
    ↓
Singularity Container: Chainlit App
    ↓
Supervisor (Claude via LiteLLM)
    ↓
┌─────────────────────────────────────┐
│  Agents                             │
│  ├── code_execution  (Slurm, shell) │
│  ├── search          (file search)  │
│  ├── alphafold       (AF3 pipeline) │
│  └── history         (session mgmt)│
└─────────────────────────────────────┘
    ↓
Singularity Container: MCP Servers (tools)
  ├── file_ops           (filesystem)
  ├── bio_processing     (bioinformatics)
  ├── code_execution     (shell/slurm)
  ├── history_management (sessions)
  └── slurm_management   (job control)
    ↓
LiteLLM Proxy → LLM Provider (AWS Bedrock, Azure, etc.)

See docs/architecture.md for full details.

Requirements

Required

Component	Purpose
Python 3.11+	Runtime for all components
Open OnDemand	Web portal for user authentication and job launch
Singularity/Apptainer	Container runtime for isolated execution
LiteLLM Proxy	Routes LLM requests to your provider (AWS Bedrock, Azure, etc.)
PostgreSQL	Required by LiteLLM for virtual key management and authentication
Slurm	Workload manager on your HPC cluster

LiteLLM Proxy Setup

IrisAI communicates with LLMs through a LiteLLM proxy. The proxy:

• Routes requests to your LLM provider (AWS Bedrock, Azure OpenAI, Anthropic API, etc.)
• Manages virtual API keys per user for authentication and usage tracking
• Requires a PostgreSQL database to store virtual keys and usage data
• Uses a master key for admin operations (key generation, user management)

# Example LiteLLM config.yaml
model_list:
  - model_name: your-claude-model
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-4-20250514
      aws_region_name: us-east-1
      timeout: 600

general_settings:
  master_key: "<YOUR_MASTER_KEY>"
  database_url: "postgresql://<user>:<password>@localhost:5432/litellm"

Virtual Key Authentication

IrisAI uses LiteLLM virtual keys for per-user authentication. The recommended approach:

1. A privileged script (accessible only via sudo or equivalent) authenticates with the LiteLLM master key
2. The script generates a virtual key for the user's session
3. The virtual key is passed to the user's IrisAI session via environment variables
4. The privileged script itself is not readable by regular users

This ensures the master key is never exposed to end users while allowing per-user tracking and rate limiting.

Installation

# Clone the repository
git clone https://github.com/mskcc/IrisAI.git
cd IrisAI

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Run locally (for development)
chainlit run app.py

See docs/deployment.md for full deployment instructions including Open OnDemand and container setup.

Configuration

All configuration is via environment variables. See .env.example for the full list.

Key variables:

Variable	Description
LITELLM_URL	URL of your LiteLLM proxy (required)
LITELLM_API_KEY	API key for LiteLLM proxy
WORK_DIR	Default working directory for users
CLAUDE_MODEL	Claude model name as configured in LiteLLM

Containers

IrisAI runs inside two Singularity/Apptainer containers:

Container	Definition	Purpose
Chainlit App	containers/chainlit.def	Web UI + application logic
MCP Servers	containers/mcp_servers.def	All MCP tool servers

See containers/README.md for build instructions.

Open OnDemand Deployment

IrisAI includes full Open OnDemand integration. See the template/, form.yml.erb, submit.yml.erb, and manifest.yml files for OnDemand-specific configuration.

See docs/deployment.md for step-by-step OnDemand setup.

Paper

If you use IrisAI in your research, please cite:

Lohit Valleru, Nancy R. Newlin, Neeraj Harikrishna Girija Paramasivam, Erica Brophy, Jamie Cheong, Zachary Azadian, Alejandro Krauskopf, Jonathan Levine, Ivan Pulido Sanchez, Merve Sahin, and Monica Chakradeo. “Empowering Cancer Researchers: An Agentic AI System for Intuitive Interaction with High-Performance Computing.” Practice and Experience in Advanced Research Computing (PEARC ’26), submitted manuscript, 2026.

License

All rights reserved. See LICENSE for details.