MedSci Agent

MedSci Agent gives any LLM access to 28 biomedical and execution tools — drug ADMET prediction, protein structure search, single-cell RNA-seq analysis, medical image interpretation, literature search, policy-controlled document acquisition, and isolated sandbox execution — all powered by MedGemma, TxGemma running locally via Ollama, and OpenCode. No data leaves your machine.

Built for the MedGemma Impact Challenge.

Quick Start

Once setup is complete and Ollama is running, open the project in OpenCode and try:

Drug discovery:

Analyze the drug-likeness of ibuprofen (CC(C)Cc1ccc(cc1)C(C)C(=O)O) and predict its ADMET properties.

Single-cell omics:

Read my H5AD file, preprocess it, cluster with Leiden at resolution 0.5, and run differential expression.

Literature search:

Search PubMed for recent papers on CRISPR-Cas9 gene therapy for sickle cell disease.

The Agent automatically selects the right tools, calls MedGemma for interpretation, and returns a synthesized answer.

Architecture

You bring your own LLM. Configure any model in OpenCode (via /model) and it becomes the orchestrator — it reads your query, selects the right tools, calls them through MCP, and synthesizes the results. The MCP servers handle the domain logic underneath.

Cloud LLM (user's choice via OpenCode)
    |
    | tool calls via MCP
    v
+--- MCP Servers (Bun / TypeScript) ---+
|                                       |
|  server-drug        5 tools           |
|  server-protein     5 tools           |
|  server-literature  4 tools           |
|  server-acquisition 2 tools           |
|  server-imaging     1 tool            |
|  server-omics       5 tools           |
|  server-paperqa     1 tool            |
|  server-sandbox     5 tools           |
|                                       |
+-------+-------------------+-----------+
        |                   |
        v                   v
   Ollama (local)     Python Sidecar
   - MedGemma 4B      - RDKit
   - TxGemma 2B       - BioPython
                       - Scanpy

MedGemma interprets tool outputs — it reads raw data from APIs and computational tools, then provides clinically relevant summaries. Every tool that calls MedGemma returns a model_used flag and degrades gracefully if the model is unavailable.

TxGemma predicts ADMET properties (absorption, distribution, metabolism, excretion, toxicity). It runs exact prompt templates from the Therapeutics Data Commons and outputs binary classifications for six safety endpoints.

The Python sidecar is a long-running process that pre-imports scientific libraries and handles requests over stdin/stdout via JSON-RPC. This avoids the 2–5 second startup cost of importing RDKit or Scanpy on every call.

synthesize parameter: Every drug, protein, and omics tool accepts an optional "synthesize": false input field. When false, the tool skips the MedGemma interpretation step and returns raw data immediately. This is useful when you want fast data-only results, or when Ollama is unavailable. Default is true (synthesis enabled).

Tools

Drug Discovery (server-drug)

Protein Analysis (server-protein)

Literature, Acquisition & Synthesis (server-literature, server-acquisition & server-paperqa)

Medical Imaging (server-imaging)

Omics (server-omics)

Sandbox Execution (server-sandbox)

Setup

Fresh install — complete sequence

# 1. Install Bun and uv (if not already installed)
curl -fsSL https://bun.sh/install | bash
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone and install JS/TS dependencies
git clone https://github.com/omar-A-hassan/medsci-agent.git
cd medsci-agent
bun install

# 3. Create Python environments
bun run setup:py:core     # RDKit + BioPython + Scanpy → .venv/
bun run setup:py:paperqa  # PaperQA + Scrapling + ACE → packages/server-paperqa/.venv-paperqa/

# 4. Pull Ollama models (Ollama must be installed first: https://ollama.com)
ollama pull medgemma:latest
ollama pull mxbai-embed-large
ollama pull hf.co/matrixportalx/txgemma-2b-predict-GGUF:Q4_K_M

# 5. (Optional) Export API keys for cloud features — do this BEFORE starting OpenCode
export OPENROUTER_API_KEY="sk-or-..."   # needed for ACE MCP and cloud PaperQA
export ANTHROPIC_API_KEY="sk-ant-..."  # only if using Anthropic directly

# 6. Verify setup
bun run typecheck
bun test

# 7. Open in OpenCode
opencode  # MCP servers start automatically via opencode.json

The opencode.json is pre-configured for local-only use (Ollama + local Python). No additional configuration is needed for the core tools. See the sections below for cloud model setup and optional features.

Prerequisites

• Bun >= 1.1

• uv (Python package and environment manager)

• Ollama

• OpenCode

• Docker Desktop 4.40+ with the Docker AI Sandbox feature enabled (required for sandbox tools only)

  • The sandbox_* tools use docker sandbox subcommands — a first-party feature in Docker Desktop 4.40+. Enable it under Settings → Features in Development → Docker AI Sandbox.

  • All other tools work without Docker.

Sandbox not available? If you don't have Docker Desktop 4.40+ you can still use all 23 non-sandbox tools. Leave the medsci-sandbox MCP server enabled — calls to sandbox tools will return clear errors rather than crashing.

1. Clone and install

git clone https://github.com/omar-A-hassan/medsci-agent.git
cd medsci-agent
bun install

2. Python environments

The system uses two strictly decoupled Python virtual environments, both managed with uv.

Core Environment (Required):

bun run setup:py:core

PaperQA + Acquisition Environment (Required for strict full-text retrieval and deep synthesis):

bun run setup:py:paperqa

Or run both in one command:

bun run setup:py:all

Important: Set MEDSCI_PYTHON to .venv/bin/python3 for core tools. Both medsci-paperqa and medsci-acquisition should run with packages/server-paperqa/.venv-paperqa/bin/python3 to keep Scrapling and PaperQA dependencies in one environment.

Dependency ownership:

• .venv (uv groups: scientific, test): core science sidecars (RDKit/BioPython/Scanpy and related tool stacks).

• packages/server-paperqa/.venv-paperqa (uv groups: paperqa, ace, test): PaperQA + acquisition parsing + ACE stack.

3. Pull Ollama models

ollama pull medgemma:latest                                      # Biomedical interpretation
ollama pull mxbai-embed-large                                    # Document embeddings for PaperQA
ollama pull hf.co/matrixportalx/txgemma-2b-predict-GGUF:Q4_K_M  # ADMET prediction

If medgemma:latest is not available directly, pull the GGUF from HuggingFace and alias it:

ollama pull hf.co/unsloth/medgemma-4b-it-GGUF:Q4_K_M
cp ~/.ollama/models/manifests/hf.co/unsloth/medgemma-4b-it-GGUF/Q4_K_M \
   ~/.ollama/models/manifests/registry.ollama.ai/library/medgemma/latest

Note: The cp command creates an alias so the code can reference the model as medgemma:latest regardless of how it was downloaded.

4. Configure OpenCode

The included opencode.json is pre-configured. Set the model field to your preferred cloud LLM:

{
  "model": "openai/gpt-4o"
}

Update the MEDSCI_PYTHON path in each server's environment block if your virtual environment is in a different location.

4.1 Optional: Enable ACE MCP (self-improvement layer)

MedSci now supports optional ACE MCP integration for adaptive strategy learning.

Install ACE MCP in the PaperQA/acquisition virtual environment (recommended):

bun run setup:py:paperqa

Configured MCP server name: ace-mcp (in opencode.json)

ACE model default: openrouter/arcee-ai/trinity-large-preview:free (set via ACE_MCP_DEFAULT_MODEL in opencode.json). This is a free OpenRouter model that requires OPENROUTER_API_KEY. To change:

export ACE_MCP_DEFAULT_MODEL="your/provider-model"

Credential model for ACE:

• ACE runs as a separate MCP process and needs provider credentials available in that process environment.

• If you use OpenAI for ACE, export OPENAI_API_KEY before starting OpenCode.

• If you use Anthropic/Gemini/Mistral/etc for ACE, set the corresponding provider key env var.

• ACE can use the same cloud provider/model family you use in OpenCode, but it does not automatically inherit the currently selected chat model unless you configure ACE_MCP_DEFAULT_MODEL accordingly.

• ACE in this setup is intentionally decoupled from local MedSci models (medgemma, txgemma, PaperQA embedding model) and should not use them unless you explicitly reconfigure it.

Default behavior in MedSci:

• in-run reflection is read-only (ace.ask / ace.skillbook.get)

• automatic post-run learning is triggered by plugin guardrails (gated by evidence quality)

• manual fallback remains available via /ace-learn

Skillbooks are persisted under .opencode/ace/skillbooks/.

Why ACE is installed in packages/server-paperqa/.venv-paperqa (not the core .venv):

• ACE learning is orchestration/synthesis logic, closest to the PaperQA + acquisition stack.

• Keeping ACE out of the core scientific sidecar avoids dependency drift for RDKit/Scanpy/BioPython workflows.

• This preserves strict environment separation and reduces breakage risk in domain toolchains.

Example override:

export ACE_MCP_DEFAULT_MODEL="anthropic/claude-3-5-sonnet-latest"
export ANTHROPIC_API_KEY="..."

Key export timing: API keys must be exported in the shell before starting OpenCode. MCP server processes are spawned at startup and inherit env from that moment — changing env vars afterwards has no effect until OpenCode is restarted.

5. Run tests

bun run test:all

This runs:

• all Bun tests across MCP servers (including sidecar-in-loop tests when packages/server-paperqa/.venv-paperqa exists),

• and PaperQA Python tests using the PaperQA venv interpreter.

6. Start

Make sure Ollama is running, then open the project directory in OpenCode. The MCP servers start automatically.

OpenCode Agent Usage

Agent roles

• medsci is the primary orchestrator for cross-domain workflows.

• drug, protein, omics, and imaging are focused subagents for domain-deep tasks.

• All agents follow a planning-first contract (brief plan before first tool call, then strict sequential execution).

Built-in project commands

This repo ships OpenCode slash commands under .opencode/commands:

• /triage — classify request and propose minimal sequential MCP plan

• /lit-deep — literature discovery + PaperQA deep synthesis workflow

• /sandbox-job — sandbox lifecycle run (prepare → run_job → status(advisory) → fetch → teardown)

• /qc-check — maker-checker quality gate on scientific outputs

• /handoff-report — compact handoff for next agent/human

• /ace-learn — manual ACE learning fallback/override for a completed task

• /ace-strategies — inspect ACE strategy state for a domain/session

Sandbox command default

For inline script execution, prefer:

python3 -c "print('sandbox smoke ok')"

instead of python -c ... to avoid environment-path variability across sandbox templates.

Determinism and status policy

• Treat sandbox_run_job success/failure as source-of-truth for execution outcome.

• Treat sandbox_status as advisory state signal.

• Backend applies status retry/backoff before returning unknown.

Configuration

Environment variables (set in opencode.json under each server's environment):

Acquisition-related environment variables (optional, server-acquisition):

Sandbox-related environment variables (optional, server-sandbox):

OpenCode policy hardening (included)

opencode.json includes baseline hardening:

• edit, task, skill, webfetch, external_directory, doom_loop default to ask

• bash allowlist for safe read-only/dev commands

• bash denylist for destructive actions (rm *, git push*)

• agent-specific task/skill permission scoping for medsci

Plugin guardrails (included)

Project plugin: .opencode/plugins/medsci-guardrails.ts

• Blocks reading sensitive .env files via the read tool (allows .env.example)

• Logs tool telemetry (tool, session_id, duration_ms, failed) via client.app.log

• Adds ACE telemetry tags (ace_tool, ace_learning_write) for auditability

• Triggers automatic post-run /ace-learn command execution when high-signal tool evidence is present

The MEDSCI_PROFILE setting controls which Python libraries are pre-imported when the sidecar starts. All tools work regardless of profile — the sidecar imports libraries lazily on first use — but pre-importing avoids a cold-start delay on the first call.

PaperQA Data Nuances

When querying papers via server-paperqa, the tool performs a multi-step pipeline:

1. Text Acquisition — Full-text articles are acquired via the NCBI BioC PMC API (DOIs, PMIDs, or PMCIDs). Papers not in PMC Open Access fall back to abstract-only via the BioC PubMed API. Acquired text is cached as .txt files in .opencode/pqa_papers/.

   • search_and_analyze also accepts pre-acquired documents payloads. When provided, PaperQA skips internal acquisition and indexes those documents directly.

2. Indexing — PaperQA2 indexes the text files and builds a search index in .opencode/pqa_index/.

3. RAG Synthesis — The query runs against indexed chunks using Ollama for both summarization and final answer generation.

• Models (local): PaperQA uses PQA_LLM_MODEL (default: ollama/medgemma:latest) for summarization and answering, and PQA_EMBEDDING_MODEL (default: ollama/mxbai-embed-large) for document embeddings. Both run locally via Ollama.

• Models (cloud): Set PQA_LLM_BACKEND=openrouter or PQA_LLM_BACKEND=anthropic to route the LLM calls to a cloud provider instead of Ollama. The embedding model always stays local. Export the corresponding API key before starting OpenCode:

  # OpenRouter (supports many models)
  export PQA_LLM_BACKEND=openrouter
  export PQA_CLOUD_MODEL="openrouter/anthropic/claude-3-5-sonnet"
  export OPENROUTER_API_KEY="sk-or-..."
  
  # Anthropic direct
  export PQA_LLM_BACKEND=anthropic
  export PQA_CLOUD_MODEL="anthropic/claude-opus-4-5"
  export ANTHROPIC_API_KEY="sk-ant-..."

  Cloud backends skip the Ollama LLM preflight check and tend to be significantly faster for synthesis. The acquisition and embedding steps still run locally.

• Preflight: The sidecar verifies Ollama reachability and required model presence before indexing/query. Failures return structured codes (OLLAMA_UNREACHABLE, MODEL_NOT_FOUND).

• Agent Type: Uses "fake" agent mode (deterministic search → gather evidence → answer path) rather than an LLM-driven agent, which reduces token usage.

• Paper Limits: The search_and_analyze schema strictly bounds processing to 10 inputs per call (papers or documents) to avoid Out-of-Memory crashes.

• Document Provenance Contract: Pre-acquired documents can include extraction_backend (scrapling, beautifulsoup, regex, pdf_text, plain_text) and fallback_used so downstream synthesis can reason about evidence quality explicitly.

• PMC Open Access Coverage: Full-text retrieval requires papers to be in the PMC Open Access subset (~3.5M articles). Papers outside this subset get abstract-only indexing — the response includes an acquisition_summary showing which papers were full-text vs abstract-only.

• Stage-Gated Responses: search_and_analyze now returns stage_status (acquire, index, query) and fail-soft terminal codes (ACQUIRE_NONE_SUCCESS, INDEX_ZERO_SUCCESS, API_AUTH_FAILED) instead of opaque failures. API_AUTH_FAILED means the cloud LLM API key was missing or rejected — check OPENROUTER_API_KEY / ANTHROPIC_API_KEY.

• Embedding Context Guardrail: Indexing now uses conservative chunk defaults and automatic chunk-size backoff retries when Ollama embedding rejects large inputs (/api/embed context-limit errors).

• Caching: Paper acquisition uses canonicalized identifier hashing + manifests. Index/query path includes in-memory docset cache and persisted manifests under .opencode/pqa_index/manifest.json.

• Stateful Indexes: Do not manually delete .opencode/pqa_index/ or .opencode/pqa_papers/ while a PaperQA query is in progress.

Troubleshooting

OLLAMA_UNREACHABLE — PaperQA or MedGemma fails to connect

Ollama must be running before OpenCode starts. MCP server processes inherit the environment at startup — run ollama serve first, then open OpenCode. Verify with:

curl http://localhost:11434/api/tags

MODEL_NOT_FOUND — Model missing

Pull the required model:

ollama pull medgemma:latest
ollama pull mxbai-embed-large
ollama pull hf.co/matrixportalx/txgemma-2b-predict-GGUF:Q4_K_M

If medgemma:latest resolves but the sidecar still says MODEL_NOT_FOUND, the PQA_LLM_MODEL env var may reference a different name than what Ollama has. Check with ollama list.

API_AUTH_FAILED — Cloud PaperQA authentication error

The API key for PQA_LLM_BACKEND was not found or is invalid. Export it in the shell before starting OpenCode:

export OPENROUTER_API_KEY="sk-or-..."   # for PQA_LLM_BACKEND=openrouter
export ANTHROPIC_API_KEY="sk-ant-..."  # for PQA_LLM_BACKEND=anthropic

ACQUIRE_NONE_SUCCESS — PaperQA couldn't fetch any papers

The papers may not be in PMC Open Access. PaperQA falls back to abstract-only indexing for papers outside PMC OA (~3.5M articles). If you have access to the full text, use acquire_documents first to get pre-acquired documents, then pass them directly to search_and_analyze.

Python sidecar tools fail (drug/protein/omics)

The core Python environment may not be set up:

bun run setup:py:core    # installs RDKit, BioPython, Scanpy into .venv/

Then verify MEDSCI_PYTHON in opencode.json points to .venv/bin/python3.

Scrapling warning in acquisition

If you see SCRAPLING_REQUIRED in logs, the acquisition sidecar is running without Scrapling. This is normal — ACQ_REQUIRE_SCRAPLING=false (the default) lets it fall back to BeautifulSoup/regex HTML extraction. To enable Scrapling:

bun run setup:py:paperqa   # Scrapling is installed in the PaperQA venv

And set MEDSCI_PYTHON for medsci-acquisition in opencode.json to packages/server-paperqa/.venv-paperqa/bin/python3 (it already is by default).

Sandbox tools fail with docker: command not found or connection errors

The sandbox tools require Docker Desktop 4.40+ with the AI Sandbox feature enabled. If Docker Desktop isn't installed or the daemon isn't running, sandbox calls return errors — all other tools continue to work normally.

ACE MCP fails to start

Verify the PaperQA venv is set up (bun run setup:py:paperqa) and that OPENROUTER_API_KEY is exported before starting OpenCode (ACE uses OpenRouter by default).

Project Structure

medsci-agent/
  packages/
    core/               Shared library (Ollama client, Python sidecar, config, types)
      python/
        sidecar.py      Long-running Python process with scientific library handlers
    server-drug/        Drug discovery MCP server
    server-protein/     Protein analysis MCP server
    server-literature/  Literature search MCP server
    server-acquisition/ Policy-controlled retrieval MCP server
    server-imaging/     Medical imaging MCP server
    server-omics/       Single-cell and omics MCP server
    server-paperqa/     Deep literature synthesis MCP server (identifier or document ingestion)
    server-sandbox/     Isolated sandbox execution MCP server
  .opencode/
    agents/             Agent definitions (orchestrator + 4 domain specialists + PaperQA routing)
    commands/           Reusable slash commands for MedSci workflows
    plugins/            OpenCode plugin guardrails and telemetry hooks
    skills/             Skill definitions for OpenCode
  opencode.json         OpenCode configuration (model, MCP servers)

Runtime Artifacts

Sandbox runs generate runtime artifacts (for debugging and reproducibility), typically under sandbox-artifacts/ or a configured artifact root:

• job-*/stdout.log

• job-*/stderr.log

• job-*/metadata.json

These are not source files and are safe to delete. Sandbox teardown removes containers; host-side artifacts remain unless explicitly pruned.

Acknowledgments

This project builds on the following work:

• Prompt Repetition (Leviathan, Kalman & Matias, 2025) — Our interpretWithMedGemma function repeats the instruction after the data context to improve non-reasoning model accuracy.

• TxGemma (Wang, Schmidgall, Jaeger et al., 2025) — ADMET prediction uses verbatim prompt templates from Google's TxGemma, trained on Therapeutics Data Commons benchmarks.

• PaperQA2 (Future-House/paper-qa) — Deep literature synthesis and RAG is powered by FutureHouse's PaperQA2 library, with text acquired via NCBI's BioC API.

• Agentic Context Engine (ACE) (kayba-ai/agentic-context-engine) — ACE MCP integration powers MedSci's strategy-learning and post-run self-improvement loop.

• K-Dense Scientific Skills (K-Dense-AI/claude-scientific-skills) — The OpenCode skills in this project are adapted from K-Dense AI's open-source collection of 147+ scientific skills for AI agents.

License

MIT