groundworkers

groundworkers is the reusable capability layer for OMOP-grounded lookup, mapping, source planning, and knowledge-pack discovery.

You can use it in three ways:

• as an MCP service for agentic clients and tool discovery
• as a REST service for fixed workflow applications
• as a direct Python library for in-process orchestration

No patient-level writes. No session state. No transport-specific business logic.

What it provides

• OMOP concept lookup and hierarchy navigation
• exact, normalized, full-text, and embedding-backed retrieval
• mapping-oriented candidate bundles and context assembly
• stateless source-planning workflows
• bundled baseline knowledge packs for reusable mapping and planning context
• LLM-backed text normalization and domain classification

Knowledge Packs

groundworkers ships with bundled baseline knowledge packs inside the package. These packs are available by default and provide reusable guidance and rules that apply broadly across deployments.

Site-specific or localisation packs are added through the shared stack config via tools.groundworkers.knowledge.packs_root. When a configured pack has the same layer and name as a bundled baseline pack, the configured copy wins.

Runtime model

flowchart TD
    STACK[shared stack config] --> BOOT[build_app_config]
    BOOT --> CFG[AppConfig]
    CFG --> APP[build_application]
    APP --> GW[GroundworkersApp]
    GW --> SVC[services]
    GW --> ADP[adapters]
    MCP[MCP client] --> TOOLS[MCP tools]
    REST[REST client] --> API[REST transport]
    PY[Python caller] --> SVC
    TOOLS --> SVC
    TOOLS -. adapter-backed primitives .-> ADP
    API --> SVC

Loading

build_application(...) is the composition root. It builds one reusable runtime container with transport-agnostic services plus dependency-facing adapters. Most caller-facing workflows go through services; some MCP tools are intentionally adapter-backed when the capability is closer to a backend primitive than a domain service.

Quick start

Install

pip install groundworkers

Optional extras:

pip install "groundworkers[llm,embedding-pgvector]"

Configure the shared stack

omop-config configure omop_alchemy
omop-config configure omop_graph
omop-config configure groundworkers
# optional if you want embedding-backed capabilities
omop-config configure omop_emb

Start MCP

groundworkers --describe
groundworkers --transport streamable-http --host 0.0.0.0 --port 8000

Start REST

groundworkers --transport rest --host 0.0.0.0 --port 8080

Use from Python

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

config = build_app_config()
app = build_application(config)

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

Main surfaces

Surface	Best for
MCP tools	Tool discovery, agent interoperability, shared capability services
REST routes	Typed HTTP workflows such as candidate bundles and assisted source planning
app.services.*	In-process Python applications and batch workflows
app.adapters.*	Backend wrappers used when you intentionally need dependency-shaped primitives

Learn more

• Docs home: docs/index.md
• Configuration: docs/usage/configuration.md
• Integrations: docs/usage/integrations.md
• Architecture: docs/architecture.md

Companion repos

• groundcrew
• omop-graph
• omop-emb