Open Science Toolkit

Reusable components for building a Claude-Science-style research agent on an open-source stack — 29 skills, 4 agent profiles, 24 domain MCP servers, a stateful Python kernel, and a browser chat UI with 3D structure viewing.

hljs language-bash

pip install -e . --no-deps
cp .env.example .env          # set LLM_BASE_URL / LLM_MODEL / LLM_API_KEY
python -m open_science.server --serve --port 8000
# http://localhost:8000/        chat UI
# http://localhost:8000/docs    API panel

📦 Skills — 29 research skills

Task instructions for the agent, grouped by theme. Each skill is a SKILL.md with YAML frontmatter, loaded on demand (Agent Skills format).

Theme	Count	Examples
🧬 Structure prediction & docking	6	AlphaFold2, Boltz, Chai-1, ESMFold2, OpenFold3, DiffDock
✏️ Protein design & embedding	4	ProteinMPNN, LigandMPNN, SolubleMPNN, ESM-2
🔬 Genomics & single-cell	4	Borzoi, Evo-2, scGPT, scVI
📊 Figures & visualization	2	figure-composer, figure-style
📝 Literature & writing	4	literature-review, paper-narrative, indication-dossier, pdf-explore
⚙️ Compute & workflow	9	remote-compute (Modal/SSH), skill-creator, customize, self-awareness

🧬 Structure prediction & docking (6)

Skill	Purpose
alphafold2	Monomer & multimer structure prediction with AlphaFold2
boltz	Protein / nucleic-acid / small-molecule complex prediction
chai1	Protein / nucleic-acid / small-molecule complex prediction
esmfold2	All-atom co-folding with ESMFold2 / ESMFold2-Fast
openfold3	Structure prediction with the open-weights OpenFold3
diffdock	Diffusion-based protein–ligand docking

✏️ Protein design & embedding (4)

Skill	Purpose
proteinmpnn	Inverse-fold a backbone into sequence
ligandmpnn	Inverse-fold with ligand / nucleic-acid / metal context
solublempnn	Inverse-fold biased toward soluble sequences
fair-esm2	Protein embeddings with Meta's ESM-2

🔬 Genomics & single-cell (4)

Skill	Purpose
borzoi	Predict genome-wide functional tracks from DNA
evo2	Score / embed / generate DNA with Evo 2
scgpt	Embed & annotate single-cell expression with scGPT
scvi-tools	Probabilistic single-cell RNA-seq with scVI

📊 Figures & visualization (2)

Skill	Purpose
figure-composer	Compose a publication-grade multi-panel figure
figure-style	Figure correctness & legibility rules

📝 Literature & writing (4)

Skill	Purpose
literature-review	Find, verify & synthesize scientific literature
paper-narrative	Judge & reshape the story a paper's figures tell
indication-dossier	Generate a therapeutic indication dossier
pdf-explore	Locate / compare / extract across whole PDFs

⚙️ Compute & workflow (9)

Skill	Purpose
compute-env-setup	Set up a runtime on remote compute
remote-compute-modal	Run GPU jobs on your own Modal account
remote-compute-ssh	Submit → wait → harvest on SSH / SLURM hosts
managed-model-endpoints	Register local / remote model service endpoints
using-model-endpoint	Call a registered endpoint over its HTTP API
skill-creator	Create, improve & benchmark skills
customize	Author custom agent profiles & new skills
self-awareness	Introspect the session DB / SDK via `host.query()`
product-self-knowledge	Ground product facts in authoritative sources

🤖 Agents — 4 profiles

Each agent is a metadata.yaml defining an identity prompt, working-style rules, and capability switches (excluded_tools, enable_thinking, …).

Agent	Role
operon	Main scientific-computing agent (full tools)
onboarding	First-run guided setup (ask-only)
reviewer	Transcript hallucination / fabrication review
bookmarker	Extract key points from a conversation

Tool trimming maps an excluded_tools denylist to OpenHands' filter_tools_regex (a positive-match filter) via a negative-lookahead regex — see src/open_science/agents.py.

🔌 MCP Servers — 24 domain servers

Standard Model Context Protocol servers wrapping public science APIs, injected on demand by query domain.

Server	Domain
mcp_bio	General bio lookups
mcp_literature / mcp_pubmed / mcp_biorxiv	Literature & preprints
mcp_genomes / mcp_genomics	Genome assemblies
mcp_variants / mcp_human_genetics / mcp_clinical_genomics	Variants & clinical genetics
mcp_expression / mcp_regulation / mcp_rna	Expression & regulation
mcp_protein_annotation / mcp_structures_interactions	Proteins & structures
mcp_chembl / mcp_chemistry / mcp_zinc	Chemistry & compounds
mcp_clinical_trials / mcp_drug_regulatory	Trials & regulatory
mcp_cellguide / mcp_cancer_models	Cell & cancer models
mcp_genes_ontologies / mcp_omics_archives / mcp_biomart / mcp_research_resources	Ontologies & archives

All share mcp_servers_common (rate limiting, retries, gating). Compatible with any MCP client (Claude Desktop, Cursor, …).

🏗️ Architecture

Layer	Implementation
Runtime	OpenHands V1 SDK (MIT), `LocalWorkspace` — no Docker to start
Brain	any OpenAI-compatible endpoint, credentials via env only
Kernel	`KernelSession` (`jupyter_client` + `ipykernel`), variables persist across cells
Skills	loader with search-based lazy injection (menu first, body on match)
Agents	OpenHands `Agent` + `filter_tools_regex` tool trimming
3D viewer	3Dmol.js embedded in the self-contained web UI

See docs/design-teardown/ for the design patterns explained, and docs/ROADMAP.md for the phased build and sandbox notes.

📁 What's inside

Everything here is reusable — clone it and wire the pieces into your own agent.

1. Assembly code — src/open_science/ (~340 Python files)

Module	What it does
`server.py`	FastAPI wiring: mounts the chat UI on OpenHands agent-server, adds `POST /chat/send`
`agents.py`	Agent profile loader + the `excluded_tools` → `filter_tools_regex` trimming bridge
`runtime.py`	`KernelSession` — stateful IPython kernel (variables persist across cells)
`brain.py`	Builds an `LLM` from any OpenAI-compatible endpoint (env-only credentials)
`skills/`	Skill loader — menu-first, lazy body injection on `search_skills` match
`datasources/`	MCP source registry + on-demand injection (`inject.py`, `registry.py`, `launcher.py`)
`provenance/`	Read-only SQLite schema + `host.query()` surface for artifacts / self-introspection
`render/`	Artifact rendering (structure files → 3D viewer)
`remote.py`	Remote GPU compute (Modal / SSH byoc) glue
`web/`	Self-contained chat UI: `index.html` + `3Dmol-min.js` (no external CDN)

2. Skills — skills_assets/ (29 SKILL.md + 79 helper scripts)

The full skill catalog above, each a directory with a SKILL.md and its scripts. Drop-in for any Agent-Skills-compatible harness.

3. Agent profiles — agents_assets/ (4 metadata.yaml)

operon / onboarding / reviewer / bookmarker — identity prompt, working-style rules, and capability switches per role.

4. MCP data sources — src/open_science/datasources/vendor/ (24 domain servers, 62 API clients)

24 mcp_* servers aggregating 62 HTTP clients over public science APIs, all sharing one common layer (mcp_servers_common: rate limiting, retries, gating). Usable standalone with any MCP client.

5. Design teardown — docs/design-teardown/ (9 chapters)

The design patterns behind the above, explained: config-as-tuning-log, identity/working-style separation, retrieve-don't-recompute, progressive disclosure, MCP aggregation, self-knowledge, and a transferable-principles table.

6. Verification scripts — tests/ (6 stage checks)

Per-stage smoke tests (verify_stage0..5.py) covering brain round-trip, stateful kernel, MCP sources, skill loading, and agent trimming.

🔒 Security

API keys via environment variables only (.env is gitignored)
Conversation content passes through the brain endpoint — send sensitive data as artifact pointers, not raw
Data sources call public APIs; respect their rate limits and ToS
Model weights carry their own licenses

📄 License

Apache-2.0 — see LICENSE and THIRD_PARTY_LICENSES.md. Built on OpenHands (MIT), 3Dmol.js (BSD).

Open Science Toolkit

hljs language-bash

pip install -e . --no-deps
cp .env.example .env          # set LLM_BASE_URL / LLM_MODEL / LLM_API_KEY
python -m open_science.server --serve --port 8000
# http://localhost:8000/        chat UI
# http://localhost:8000/docs    API panel