Metadata-Version: 2.4
Name: groundworkers
Version: 0.3.2
Summary: Groundworkers MCP server — read-only agentive access to OMOP vocabularies, concept graphs, and embeddings.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: mcp[cli]<2,>=1
Requires-Dist: pydantic<3,>=2
Requires-Dist: pyyaml<7,>=6
Requires-Dist: SQLAlchemy<3,>=2
Requires-Dist: psycopg[binary]<4,>=3.1
Requires-Dist: oa-configurator>=0.1.2
Requires-Dist: omop-graph>=1.3.0
Requires-Dist: omop-emb>=1.1.1
Requires-Dist: uvicorn[standard]<1.0,>=0.29
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == "llm"
Provides-Extra: xlsx
Requires-Dist: openpyxl<4,>=3.1; extra == "xlsx"
Provides-Extra: pdf
Requires-Dist: pdfplumber>=0.10; extra == "pdf"
Provides-Extra: docx
Requires-Dist: python-docx>=1.0; extra == "docx"
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: embedding-pgvector
Requires-Dist: omop-emb[pgvector]>=1.1.1; extra == "embedding-pgvector"
Provides-Extra: embedding-faiss
Requires-Dist: omop-emb[faiss-cpu]>=1.1.1; extra == "embedding-faiss"
Provides-Extra: dev
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: ipython>=8.0; extra == "dev"
Requires-Dist: tornado>=6.5.5; extra == "dev"
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mkdocs-material>=9.7.1; extra == "dev"
Requires-Dist: mkdocstrings-python>=2.0.1; extra == "dev"
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: requests>=2.33.0; extra == "dev"
Requires-Dist: mkdocs-mermaid2-plugin; extra == "dev"

# 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
- LLM-backed text normalization and domain classification

## Runtime model

```mermaid
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
```

`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

```bash
pip install groundworkers
```

Optional extras:

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

### Configure the shared stack

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

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

### Start REST

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

### Use from Python

```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](https://github.com/AustralianCancerDataNetwork/groundcrew)
- [omop-graph](https://australiancancerdatanetwork.github.io/omop-graph/)
- [omop-emb](https://australiancancerdatanetwork.github.io/omop-emb/)
