Local Deployment

Local Deployment#

This guide describes how to deploy spatho locally for development, single-case analysis, and self-hosted pathology review. For the Dardel/PDC Slurm and Apptainer deployment path, see the PDC local pathology AI guide.

What Runs Locally#

spatho has two layers:

  • the spatho Python package and CLI, which prepares and runs workflow JSON files

  • an optional local pathology-ai HTTP service, which can replace the paid OpenAI API for pathology review

The package can run with any of these review paths:

  • openai: calls the OpenAI API through OPENAI_API_KEY

  • pathology_ai_api: calls a local HTTP service at pathology_ai_api_base_url

  • heuristic-only mode: disables AI review calls for environment checks and deterministic fallback runs

Install the Python Package#

For normal local use, install the published package:

python -m pip install -U spatho

For development from a source checkout:

git clone https://github.com/hutaobo/AI-Driven-Spatial-Pathologist.git
cd AI-Driven-Spatial-Pathologist
python -m pip install -U pip
python -m pip install -e .[dev]

If you are actively developing against a local histoseg checkout, install it before installing spatho:

python -m pip install -e ../HistoSeg
python -m pip install -e .[dev]

Confirm the CLI is available:

spatho list-organ-packs
spatho doctor

Create a Workflow#

Generate a starter workflow JSON for a Xenium case:

spatho init-workflow \
  --organ breast \
  --case-name breast_case_01 \
  --dataset-root /path/to/Xenium_outs \
  --base-pipeline-config /path/to/project/configs/breast_case_01.json \
  --output /path/to/workflows/breast_case_01.json

Check the environment and workflow before running:

spatho doctor --config /path/to/workflows/breast_case_01.json

Run the workflow:

spatho run --config /path/to/workflows/breast_case_01.json

Use the OpenAI Backend#

Use the OpenAI backend when you want the fastest setup with managed models:

export OPENAI_API_KEY=sk-...

The workflow JSON should contain:

{
  "pathology_review_backend": "openai"
}

Then run:

spatho run --config /path/to/workflow.json

Run Without AI Calls#

Use heuristic-only mode for local smoke tests, deterministic fallback checks, or environments where no model service is available:

spatho run --config /path/to/workflow.json --heuristic-only

This path disables OpenAI calls and does not require the local pathology-ai stack.

Use the Local pathology-ai Backend#

Use the local backend when pathology review should call a self-hosted service instead of the paid OpenAI API:

{
  "pathology_review_backend": "pathology_ai_api",
  "pathology_ai_api_base_url": "http://localhost:8000",
  "cluster_annotation_backend": "pathology_ai_api",
  "cluster_annotation_llm_base_url": "http://localhost:8000"
}

cluster_annotation_backend="pathology_ai_api" is optional. When enabled, Spatial Pathologist first builds the marker-based heuristic cluster labels, then asks the local LLM to review every cluster and writes a conservative consensus cluster_celltype_annotation.csv. OpenAI-backed annotation remains available through the existing OpenAI path.

The local stack consists of:

  • pathology-ai: HTTP orchestration service from this repository

  • vllm: OpenAI-compatible local LLM endpoint

  • embedder: embedding service for BAAI/bge-m3

  • reranker: reranking service for BAAI/bge-reranker-v2-m3

  • qdrant: local vector database

Default service settings are stored in deploy/pathology_ai/pathology-ai.env.example.

Start the Local Docker Compose Stack#

Use Docker Compose on machines that support GPU containers:

cp deploy/pathology_ai/pathology-ai.env.example deploy/pathology_ai/pathology-ai.env
docker compose -f deploy/pathology_ai/docker-compose.pdc.yml up --build

The orchestration service listens at:

http://localhost:8000

Verify readiness:

curl http://localhost:8000/health

A ready service returns ready: true and marks all configured components as healthy:

{
  "service": "pathology-ai",
  "ready": true
}

After the health check passes, run spatho with a workflow that uses pathology_ai_api.

Load Reference Documents#

The local service can store reference text in Qdrant for retrieval during structure-level and case-level reviews:

curl -X POST http://localhost:8000/documents/upsert \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "who-lung-2021",
    "title": "WHO Thoracic Tumours",
    "text": "Long reference text...",
    "source": "who"
  }'

The service also accepts batch upserts with a top-level documents array.

Troubleshooting#

  • If spatho doctor cannot import histoseg, install histoseg from PyPI or install a local checkout with python -m pip install -e ../HistoSeg.

  • If OPENAI_API_KEY is missing and the workflow uses openai, either set the key, switch to pathology_ai_api, or run with --heuristic-only.

  • If curl /health returns ready: false, inspect the component errors and the matching container logs.

  • If Docker Compose is unavailable on PDC login nodes, use the Slurm/Apptainer path in the PDC local pathology AI guide.

  • If model downloads fail with authorization errors, set HF_TOKEN in your shell before starting the local model stack.