Metadata-Version: 2.5
Name: groundworkers
Version: 0.5.0
Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
Requires-Python: >=3.12
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: mcp[cli]<2,>=1
Requires-Dist: numpy<3,>=1.26
Requires-Dist: oa-configurator<2,>=1.3.0
Requires-Dist: omop-alchemy<2,>=1.1
Requires-Dist: omop-emb<3,>=2.1
Requires-Dist: omop-graph<3,>=2.1
Requires-Dist: omop-llm<2,>=1
Requires-Dist: omop-semantics<1,>=0.6
Requires-Dist: psutil<8,>=5.9
Requires-Dist: psycopg[binary]<4,>=3.1
Requires-Dist: pydantic<3,>=2
Requires-Dist: python-dotenv<2,>=1
Requires-Dist: pyyaml<7,>=6
Requires-Dist: sqlalchemy<3,>=2
Requires-Dist: uvicorn[standard]<1.0,>=0.29
Provides-Extra: all-source
Requires-Dist: openpyxl<4,>=3.1; extra == 'all-source'
Requires-Dist: pdfplumber>=0.10; extra == 'all-source'
Requires-Dist: python-docx>=1.0; extra == 'all-source'
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.27; extra == 'dev'
Requires-Dist: ipython>=8.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.7.1; extra == 'dev'
Requires-Dist: mkdocs-mermaid2-plugin; extra == 'dev'
Requires-Dist: mkdocs>=1.6.1; extra == 'dev'
Requires-Dist: mkdocstrings-python>=2.0.1; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: requests>=2.33.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: textual>=0.60; extra == 'dev'
Requires-Dist: tornado>=6.5.5; extra == 'dev'
Requires-Dist: ty>=0.0.59; extra == 'dev'
Provides-Extra: docx
Requires-Dist: python-docx>=1.0; extra == 'docx'
Provides-Extra: embedding-artifacts
Requires-Dist: h5py<4,>=3.10; extra == 'embedding-artifacts'
Provides-Extra: embedding-faiss
Requires-Dist: omop-emb[faiss-cpu]<3,>=2.1; extra == 'embedding-faiss'
Provides-Extra: embedding-pgvector
Requires-Dist: omop-emb[pgvector]<3,>=2.1; extra == 'embedding-pgvector'
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10; extra == 'pdf'
Provides-Extra: tui
Requires-Dist: groundskeeping<1,>=0.8.1; extra == 'tui'
Requires-Dist: rich<15,>=13; extra == 'tui'
Requires-Dist: textual>=0.60; extra == 'tui'
Provides-Extra: xlsx
Requires-Dist: openpyxl<4,>=3.1; extra == 'xlsx'
Description-Content-Type: text/markdown

# 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](docs/index.md), or choose a path directly:

- [Concepts and capability choices](docs/concepts.md) explains retrieval, grounding, mapping, source planning, and projection.
- [Installation](docs/usage/installation.md) covers package extras and prerequisites.
- [Initial local setup](docs/from-scratch.md) walks through a fresh CDM-backed deployment.
- [Integrations](docs/usage/integrations.md) shows MCP, REST, and Python calls.
- [Configuration](docs/usage/configuration.md) explains shared-stack references and optional capabilities.
- [Tools overview](docs/tools/overview.md) maps jobs to the discoverable MCP surface.

## Quick start

Install the package and configure the shared OMOP stack:

```bash
pip install groundworkers
omop-config configure groundworkers
```

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

```bash
groundworkers --describe
```

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

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

REST is a separate, curated interface:

```bash
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:

```python
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.

## Companion repositories

- [groundcrew](https://github.com/AustralianCancerDataNetwork/groundcrew) owns session state and orchestration.
- [omop-graph](https://australiancancerdatanetwork.github.io/omop-graph/) provides graph-backed OMOP traversal.
- [omop-emb](https://australiancancerdatanetwork.github.io/omop-emb/) provides embedding stores and indexes.
