Skip to content

ModelSEED/modelseed-api

BranchesTags

Repository files navigation

ModelSEED API

Modern REST API backend for the ModelSEED metabolic modeling platform. Replaces the legacy Perl-based ProbModelSEED JSON-RPC service with a Python FastAPI application.

The API handles model listing, reconstruction, gapfilling, FBA, biochemistry queries, and PATRIC workspace operations. Long-running jobs (model building, gapfilling, FBA) run as Celery tasks in production or as subprocesses in local development.

The user-facing frontend is a separate Next.js/TypeScript application maintained by Vibhav, deployed at https://modelseed.org. This repo also includes a lightweight demo dashboard at /demo/ for development and testing.

Live API

The production API is served at https://modelseed.org/PMS/.

URL Description
https://modelseed.org/PMS/docs Swagger API docs (interactive)
https://modelseed.org/PMS/redoc ReDoc API docs (readable)
https://modelseed.org/PMS/openapi.json OpenAPI spec
https://modelseed.org/PMS/api/health Health check
https://modelseed.org/PMS/demo/ Demo dashboard

For deployment, restart procedures, on-call runbook, and infrastructure details, see the private operations repo: ModelSEED/modelseed-api-ops. Access is invite-only: ask Chris Henry or Jose Faria.

API Endpoints

Most endpoints require a PATRIC token in the Authorization header (not needed in local mode). Biochemistry endpoints are always public.

Health

Method Path Auth Description
GET /api/health No Returns {"status":"ok","version":"0.1.0"}

Models (/api/models)

Method Path Description
GET /api/models List user's models
GET /api/models/data?ref= Full model detail: reactions, compounds, genes, biomasses
POST /api/models/edit Atomic editing: add/remove/modify reactions, compounds, biomass
POST /api/models/copy Copy a model to a new workspace path
DELETE /api/models?ref= Delete a model
GET /api/models/export?ref=&format= Export as json, sbml, cobra-json
GET /api/models/gapfills?ref= List gapfill solutions
POST /api/models/gapfills/manage Integrate, unintegrate, or delete gapfill solutions
GET /api/models/fba?ref= List FBA studies for a model
GET /api/models/fba/data?ref=&fba_id= Get FBA result with reaction fluxes
GET /api/models/edits?ref= List edit history (stub: returns [])

Jobs (/api/jobs)

Method Path Description
GET /api/jobs Check job statuses (supports ids filter and status filters)
POST /api/jobs/reconstruct Build a metabolic model from a BV-BRC genome ID
POST /api/jobs/gapfill Gapfill a model against a media condition
POST /api/jobs/fba Run flux balance analysis
POST /api/jobs/merge Merge multiple models
POST /api/jobs/manage Delete or rerun jobs

Biochemistry (/api/biochem, no auth)

Method Path Description
GET /api/biochem/stats Compound and reaction counts
GET /api/biochem/reactions?ids= Get reactions by comma-separated IDs
GET /api/biochem/compounds?ids= Get compounds by comma-separated IDs
GET /api/biochem/search?query=&type= Search compounds or reactions (limit up to 200)

RAST (/api/rast)

Method Path Description
GET /api/rast/jobs List user's legacy RAST annotation jobs (RAST token required)
GET /api/rast/genome Fetch a RAST-annotated genome translated to KBase Genome shape

Media (/api/media)

Method Path Description
GET /api/media/public List public media formulations
GET /api/media/mine List user's custom media
GET /api/media/export?ref= Export a media condition

Workspace proxy (/api/workspace)

All workspace operations are POST-based proxies to the PATRIC Workspace service.

Method Path Description
POST /api/workspace/ls List workspace contents
POST /api/workspace/get Get workspace objects (supports metadata_only)
POST /api/workspace/create Create workspace objects
POST /api/workspace/copy Copy or move workspace objects
POST /api/workspace/delete Delete workspace objects
POST /api/workspace/metadata Update workspace object metadata
POST /api/workspace/download-url Get download URLs
POST /api/workspace/permissions List permissions

MCP Server (AI assistant interface)

The MCP server exposes ModelSEED tools to AI assistants via the Model Context Protocol. Runs in local storage mode only (no PATRIC account, no auth tokens, no network beyond BV-BRC genome fetching).

MCP tools call the same service layer as the REST API directly (no HTTP overhead, identical behavior).

Run

python -m modelseed_mcp
# or, after pip install:
modelseed-mcp

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "modelseed": {
      "command": "python",
      "args": ["-m", "modelseed_mcp"],
      "env": {
        "MODELSEED_MODELSEED_DB_PATH": "/path/to/ModelSEEDDatabase",
        "MODELSEED_TEMPLATES_PATH": "/path/to/ModelSEEDTemplates/templates/v7.0",
        "MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH": "/path/to/cb_annotation_ontology_api"
      }
    }
  }
}

MCP tools (17)

Group Tools
Biochemistry search_compounds, search_reactions, get_compound, get_reaction
Models list_models, get_model, delete_model, copy_model, export_model, edit_model
Media list_media, get_media
Async jobs build_model, gapfill_model, run_fba, merge_models, check_job

Async tools dispatch jobs via subprocess and poll until completion. Set wait=False to get the job ID immediately and poll manually with check_job.

Run it locally

1. Clone required repositories

The build context expects all sibling repos as siblings of modelseed-api/.

mkdir modelseed && cd modelseed
git clone https://github.com/ModelSEED/modelseed-api.git
git clone -b main https://github.com/cshenry/ModelSEEDpy.git
git clone https://github.com/cshenry/KBUtilLib.git
git clone https://github.com/Fxe/cobrakbase.git
git clone -b dev https://github.com/ModelSEED/ModelSEEDDatabase.git
git clone https://github.com/ModelSEED/ModelSEEDTemplates.git
git clone https://github.com/kbaseapps/cb_annotation_ontology_api.git

2a. Docker (recommended)

docker compose -f modelseed-api/docker-compose.yml up --build

2b. Manual

pip install -e cobrakbase
pip install -e ModelSEEDpy
pip install -e KBUtilLib
pip install -e "modelseed-api[modeling]"

Configure data paths:

cd modelseed-api
cat > .env << EOF
MODELSEED_MODELSEED_DB_PATH=$(realpath ../ModelSEEDDatabase)
MODELSEED_TEMPLATES_PATH=$(realpath ../ModelSEEDTemplates/templates/v7.0)
MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH=$(realpath ../cb_annotation_ontology_api)
EOF

Start the server:

cd src && python -m uvicorn modelseed_api.main:app --host 0.0.0.0 --port 8000

2c. Local mode (no PATRIC account needed)

To run without PATRIC Workspace, use the local storage backend. Models are stored as JSON files on disk.

cat >> modelseed-api/.env << EOF
MODELSEED_STORAGE_BACKEND=local
MODELSEED_LOCAL_DATA_DIR=~/.modelseed/data
EOF

In local mode, no authentication is required. Public media formulations are bundled in data/media/public/.

3. Verify it's running

After starting the server (any of 2a / 2b / 2c), it listens on port 8000:

URL Description
http://localhost:8000/api/health Health check
http://localhost:8000/docs Swagger API docs
http://localhost:8000/redoc ReDoc API docs
http://localhost:8000/demo/ Demo dashboard

4. Get a PATRIC token (workspace mode only)

  1. Log in to https://www.bv-brc.org
  2. Open browser console (F12)
  3. Run: copy(TOKEN)
  4. Paste into the demo page token field, or set as the Authorization header in API calls.

Architecture

This repo contains two interfaces to the same modeling engine:

                      Shared Service Layer
                      (biochem_service, ModelService, JobDispatcher,
                       export_service, JobStore, storage_factory)
                              |
            ----------------------------------
            |                                |
       REST API (HTTP)                  MCP Server
       modelseed_api                    modelseed_mcp
       FastAPI + uvicorn                FastMCP (stdio)
            |                                |
       Browser / Frontend              AI Assistants
       (PATRIC auth tokens)            (Claude, etc., local mode)

REST API (modelseed_api): HTTP endpoints for browsers and frontends. Supports both PATRIC Workspace and local storage. Requires auth tokens for workspace mode.

MCP Server (modelseed_mcp): MCP interface for AI assistants. Local storage mode only. No auth, no network dependencies. Calls the same service layer directly.

Key design decisions:

  • Synchronous API: long-running operations are dispatched to external job scripts or Celery tasks
  • Pluggable storage: a factory selects PATRIC Workspace (storage_backend=workspace) or local filesystem (storage_backend=local); both implement the same interface
  • Fully offline local mode: with storage_backend=local, no PATRIC account or network access is needed; models are stored as JSON files on disk
  • Local templates: model templates are loaded from git repos on disk, not from KBase workspace
  • No KBase dependency: runs entirely against BV-BRC/PATRIC APIs

REST API vs MCP

REST API MCP Server
Client Browsers, frontends, scripts AI assistants
Transport HTTP (port 8000) stdio (Model Context Protocol)
Auth PATRIC tokens (workspace mode) None (local mode only)
Storage Workspace or local Local only
Install pip install -e ".[modeling]" pip install -e ".[modeling,mcp]"

Demo dashboard

The demo dashboard at /demo/ is a single-page HTML app for testing API functionality during development. It is not the production frontend.

Tab What it does
My Models List models, view detail, export, gapfill, run FBA
Build Model Build a new model from a BV-BRC genome ID with optional gapfilling
Public Media Browse available media formulations
Biochemistry Search compounds and reactions
Jobs Monitor running, completed, and failed jobs
Workspace Browse PATRIC workspace paths

Dependencies

Required repositories

Repository Branch Purpose
cshenry/ModelSEEDpy main Core modeling engine (cshenry fork has ModelSEEDBiochem.get(path=) and MSFBA)
ModelSEED/ModelSEEDDatabase dev Biochemistry data (compounds, reactions, aliases)
ModelSEED/ModelSEEDTemplates main Model templates v7.0 (Core, GramPos, GramNeg)
cshenry/KBUtilLib main BVBRCUtils (genome fetch), MSReconstructionUtils (model build)
kbaseapps/cb_annotation_ontology_api main Ontology data for genome annotation
Fxe/cobrakbase master KBase object factory and FBAModel builder (0.4.0; pip 0.3.0 lacks _build_object())

Python packages

Core dependencies (see pyproject.toml):

  • fastapi + uvicorn: web framework and ASGI server
  • cobra: constraint-based modeling (FBA, SBML I/O)
  • modelseedpy: ModelSEED modeling engine (cshenry fork)
  • kbutillib: KBase/BV-BRC utility library
  • cobrakbase: KBase/cobra bridge
  • requests: HTTP client for workspace and BV-BRC API calls
  • pydantic-settings: configuration management
  • celery[redis]: job scheduling (production mode only)
  • fastmcp: MCP server framework (optional)

Job scheduling

Two modes controlled by MODELSEED_USE_CELERY (default: false):

  • Local (development): jobs run as subprocesses via src/job_scripts/. Job state is stored as JSON files in /tmp/modelseed-jobs/. No external infrastructure needed.
  • Production: jobs are dispatched via Celery to a Redis broker. The Celery task implementations in src/modelseed_api/jobs/tasks.py mirror the subprocess job scripts for full parity.
Setting Value
Broker configured via MODELSEED_CELERY_BROKER_URL (Redis)
Queue modelseed
Time limit 4 hours

To enable Celery mode, set MODELSEED_USE_CELERY=true in .env. Start the worker:

cd src && celery -A modelseed_api.jobs.celery_app worker -Q modelseed --loglevel=info

Configuration

All settings load from environment variables with the MODELSEED_ prefix or from a .env file. See .env.example for the full list.

Variable Default Description
MODELSEED_HOST 0.0.0.0 Server bind address
MODELSEED_PORT 8000 Server port
MODELSEED_DEBUG false Enable debug mode
MODELSEED_CORS_ORIGINS ["*"] Allowed CORS origins (JSON list)
MODELSEED_STORAGE_BACKEND workspace workspace (PATRIC) or local (filesystem)
MODELSEED_LOCAL_DATA_DIR ~/.modelseed/data Local storage directory (local mode)
MODELSEED_MODELSEED_DB_PATH required Path to ModelSEEDDatabase repo
MODELSEED_TEMPLATES_PATH required Path to ModelSEEDTemplates/templates/v7.0
MODELSEED_CB_ANNOTATION_ONTOLOGY_API_PATH required Path to cb_annotation_ontology_api repo
MODELSEED_WORKSPACE_URL https://p3.theseed.org/services/Workspace PATRIC workspace URL
MODELSEED_WORKSPACE_TIMEOUT 1800 Workspace HTTP request timeout (seconds)
MODELSEED_PUBLIC_MEDIA_PATH /chenry/public/modelsupport/media Workspace path for public media
MODELSEED_USE_CELERY false Use Celery+Redis for job dispatch
MODELSEED_CELERY_BROKER_URL redis://localhost:6379/0 Celery Redis broker URL
MODELSEED_CELERY_RESULT_BACKEND redis://localhost:6379/0 Celery Redis result backend URL
MODELSEED_JOB_STORE_DIR /tmp/modelseed-jobs Directory for job state files
MODELSEED_MSSS_URL https://modelseed.org/services/ms_fba Legacy MSSeedSupportServer JSON-RPC endpoint (used by RAST endpoints)

Project structure

src/
  modelseed_api/              # FastAPI application (REST API)
    main.py                   # App initialization
    config.py                 # Settings (pydantic-settings)
    auth/dependencies.py      # PATRIC/RAST token extraction
    routes/                   # API endpoint definitions
    schemas/                  # Pydantic request/response models
    services/                 # Business logic (shared with MCP)
      storage_factory.py      #   WorkspaceService or LocalStorageService
      workspace_service.py    #   PATRIC workspace proxy
      local_storage_service.py#   Filesystem storage backend
      model_service.py        #   Model CRUD, gapfill management
      biochem_service.py      #   ModelSEEDDatabase queries
      export_service.py       #   SBML / CobraPy export
      rast_service.py         #   RAST endpoints (wraps MSSS)
    jobs/                     # Job dispatch (shared with MCP)
      dispatcher.py           #   Subprocess or Celery dispatch
      store.py                #   Job state (JSON files)
      celery_app.py
      tasks.py                #   Celery task definitions
    static/index.html         # Demo dashboard
  modelseed_mcp/              # MCP server (AI assistant interface)
    server.py                 # FastMCP instance + tool registration
    tools/                    # MCP tool definitions
  job_scripts/                # External scripts for long-running ops
    reconstruct.py
    gapfill.py
    run_fba.py
    merge_models.py
data/
  media/public/               # Bundled public media formulations
docs/
  WORKAROUNDS.md              # Active workarounds with upstream status
  KNOWN_GAPS.md               # Known gaps and follow-ups
  API_ONBOARDING.md           # Onboarding guide for frontend developers
  E2E_TEST_PLAN.md            # End-to-end test plan
tests/
  conftest.py
  test_live_integration.py    # Integration tests against live workspace
  test_auth.py                # Auth dependency unit tests
  test_mcp/                   # MCP tool unit tests
  live/                       # Layered live test suite (smoke / functional / biological / ui)

Workarounds

A small number of upstream-fix-needed workarounds are tracked in docs/WORKAROUNDS.md with current upstream status. Most prior workarounds have been merged upstream as of 2026-05.

Contributing

Open issues and PRs at https://github.com/ModelSEED/modelseed-api/issues. For internal operational concerns (deployment, restarts, on-call), use the private modelseed-api-ops repo instead.

License

MIT

About

Modern REST API backend for the ModelSEED metabolic modeling platform

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v0.1.0 — Initial Release Latest
Apr 6, 2026

Packages

 
 
 

Contributors

Languages