groundworkers

Groundworkers is the reusable, read-only capability layer for OMOP vocabulary lookup, concept mapping, source planning, and related analysis. It combines deterministic services with optional embeddings and model-assisted operations.

It does not own patient-level writes, session state, or job lifecycle. Those concerns belong to the calling application; groundcrew is the usual stateful orchestrator.

Choose an interface

Interface	Use it when
MCP	An agent needs discoverable tools, prompts, resources, and a shared remote runtime.
REST	An application needs the curated HTTP workflows for candidate bundles or assisted source planning.
Python	A process owns batching, evaluation, or orchestration and can run in-process.

Start with the documentation home, or choose a path directly:

• Concepts and capability choices explains retrieval, grounding, mapping, source planning, and projection.
• Installation covers package extras and prerequisites.
• Initial local setup walks through a fresh CDM-backed deployment.
• Integrations shows MCP, REST, and Python calls.
• Configuration explains shared-stack references and optional capabilities.
• Upgrading from 0.6 lists the 0.7 configuration and runtime changes.
• Tools overview maps jobs to the discoverable MCP surface.

Quick start

Install the package and configure the shared OMOP stack:

pip install groundworkers
omop-config configure groundworkers

Inspect the active configuration and MCP surface before starting a service:

groundworkers --describe

Run MCP over stdio for a client that starts the process, or over Streamable HTTP for a shared service:

groundworkers
groundworkers --transport streamable-http --host 127.0.0.1 --port 8000

Explore the configured MCP tools, prompts, and resources interactively with the official MCP Inspector:

make inspector

This launches Groundworkers over stdio using the active shared OMOP configuration and opens the Inspector UI. It requires Node.js 22.19 or newer and uv; the first run downloads the Inspector package through npx.

REST is a separate, curated interface:

groundworkers --transport rest --host 127.0.0.1 --port 8080

Direct Python

Build the application once and reuse it. Services are optional when their prerequisites are not configured:

from groundworkers.app import build_application
from groundworkers.bootstrap import build_app_config

config = build_app_config()
app = build_application(config)

bundle = app.services.mapping.concept_candidate_bundle(
    "type 2 diabetes",
    domain="Condition",
)

The mapping service in this example requires a configured CDM database. Embedding-backed channels require an embedding model and vector store; text, domain classification, and assisted source planning require a configured chat model. Use groundworkers --describe to see what the current deployment exposes.

Contract owners

Owned here

Contract	Where it is defined	Who consumes it
Source-planning roles and column review pack	Models; pack manifest	Groundcrew and source-planning clients
Domain routing and classifier outputs	omop_domains.py	Groundcrew's domain review pack and the domain-routing knowledge pack
Mapping conventions	Standard-concept guidance, drug guidance, history-of guidance	Agents reading knowledge packs; guidance is advisory
Plugin interfaces	plugins.py	Registry and other Groundworkers plugins

Consumed from elsewhere

Contract	Owner repo	How this repo conforms
Registry pack format	ohdsi-prompt-registry	Pack entry point in pyproject.toml; discovery and validation in test_prompt_packs.py

Companion repositories

• groundcrew owns session state and orchestration.
• omop-graph provides graph-backed OMOP traversal.
• omop-emb provides embedding stores and indexes.