Skip to content

groundworkers

groundworkers is a read-only capability layer for working with OMOP vocabularies, graph relationships, source metadata, and mapping context. It combines deterministic operations with optional embedding and model-assisted steps. It is available through three interfaces:

  • as an MCP service for discoverable tool clients
  • as a REST service for controlled workflow applications
  • as a direct Python library for in-process applications

Choose the interface that fits your application

Use case Recommended interface
Discoverable tools or a shared remote service MCP
Fixed request/response workflows, typed HTTP clients, OpenAPI REST
In-process Python applications, batch evaluation, custom orchestration Direct Python

First time setting up locally?

Try here

What it helps you do

  • retrieve concepts by exact, normalized, full-text, or embedding similarity;
  • ground free text with a tiered resolver and inspect how the result was found;
  • assemble mapping evidence and graph context for review;
  • plan source artifacts before ingestion and discover applicable knowledge packs;
  • optionally normalize text, classify structured fields, or project grounded concepts into CDM rows.

Start with Concepts and capability choices for the mental model, then choose an integration path.

At a glance

flowchart TD PY[Python app] --> APP[build_application] MCP[MCP client] --> T[tools] REST[REST client] --> R[transports/rest] APP --> S[services/] T --> S R --> S S --> A[adapters/] A --> OG[omop-graph] A --> OE[omop-emb] A --> DB[(OMOP CDM / vocab)] A --> LLM[LLM API]
  • Services hold reusable workflow logic.
  • Adapters isolate concrete dependencies.
  • The transport layer validates input, invokes the runtime, and translates the result for its caller.
  • See Architecture for configuration and startup wiring.

Before assuming a capability is available

Availability follows configuration. A CDM database enables the core vocabulary and mapping services. An embedding model plus vector store enables embedding operations. A chat model enables text preprocessing, domain classification, and assisted source planning. Semantic projection is separately opt-in.

Run this before integrating against an environment:

groundworkers --describe

The output includes the active tools, prompts, resources, plugins, redacted configuration, and safe plugin issues.

Where to start

Relationship to groundcrew

groundworkers owns reusable stateless capabilities. groundcrew owns session state, job lifecycle, and orchestration policy. In the usual deployment, groundcrew calls Groundworkers over MCP; a Python application can use the same services directly.