Content
# pythia
MCP server for OMOP concept set identification and validation — routes every
vocabulary operation through a pluggable backend layer (local OMOP SQL,
[athena-client](https://pypi.org/project/athena-client/), Echidna FHIR, OHDSI
WebAPI) and runs a multi-layer presence cascade against institutional OMOP
databases.
## Quick start
Requires Python ≥ 3.10.
```bash
# With uv
uv sync
# Or with pip
pip install -e .
```
Then register the server with your MCP client — see [MCP client setup](#mcp-client-setup) below.
## What works without institutional setup
All tools that query the public OHDSI Athena API via the community
[athena-client SDK](https://pypi.org/project/athena-client/) (core dependency,
no extras required):
| Tool | Description |
|------|-------------|
| `find_omop_concept` | Keyword search across OMOP concepts |
| `lookup_concept` | Fetch full details for a single concept by ID |
| `lookup_concepts_batch` | Fetch details for multiple concept IDs at once |
| `get_concept_hierarchy` | Direct parents and children |
| `get_all_descendants` | Full descendant subtree |
| `get_concept_lineage` | Path from concept to vocabulary root |
| `map_to_standard` | Map source codes (ICD-10, ATC, etc.) to standard concepts |
| `expand_drug_class` | ATC drug class to RxNorm ingredient concepts |
| `get_concept_relationships` | All relationships for a concept |
| `validate_concept_set` | Validate YAML concept set configs |
| `validate_concept_with_context` | Single-concept rich validation |
| `resolve_cohort_criteria` | Parse plain-text cohort criteria into ranked OMOP candidates |
| `diff_concept_sets` | Compare two YAML concept set configs |
| `optimize_concept_set` | Minimize a concept set by removing redundant entries |
| `find_sibling_concepts` | Find concepts at the same hierarchy level |
| `find_uncaptured_concepts` | Find related concepts not in a set |
| `audit_concept_set_completeness` | Comprehensive gap analysis |
| `audit_concept_set_from_yaml` | Audit a YAML-defined concept set |
| `export_concept_set_as_atlas_json` | ATLAS-importable concept set JSON |
| `describe_table` | OMOP CDM table schema |
| `get_extraction_pattern` | SQL extraction pattern for a domain |
| `list_extraction_patterns` | Browse available SQL patterns |
| `get_best_practices` | OMOP best practices by topic |
## Tools that require institutional setup
These tools query your organization's OMOP database. See
[docs/INSTITUTIONAL_SETUP.md](docs/INSTITUTIONAL_SETUP.md).
| Tool | Description |
|------|-------------|
| `get_site_config` | Show current site configuration |
| `get_instance_overview` | CDM version, row counts, date ranges |
| `get_top_concepts` | Most frequent concepts by table/field |
| `get_type_concepts` | `type_concept_id` distribution |
| `compare_concept_sources` | Athena vs local vocabulary for a concept |
| `check_vocabulary_sync` | Compare all vocabularies across sources |
| `validate_concept_set_deep` | Validate + check data presence (multi-layer cascade) |
| `audit_cohort_definition` | Full cohort audit: resolve → multi-layer presence → severity-tiered issues |
| `get_concept_prevalence` | Patient counts for a concept set |
| `audit_concept_utilization` | Check if concept set concepts have data |
| `profile_unmapped_records` | Investigate concept_id=0 records |
| `get_data_quality_summary` | Data quality metrics |
| `get_concept_co_occurrence` | Co-occurrence counts across concepts |
| `query_custom_table` | Run a parameterized query on any OMOP table |
## Supported OMOP engines
| Engine | Extra | Notes |
|---|---|---|
| PostgreSQL | `pip install -e '.[postgres]'` | Community-standard OHDSI engine |
| DuckDB | `pip install -e '.[duckdb]'` | File-based; ideal for reproducible research bundles |
| SAP HANA | `pip install -e '.[hana]'` | Supports institutional connection overlays |
Contributions for MS SQL Server, Redshift, BigQuery, Snowflake, Oracle, and
Spark are welcome — see [src/pythia/backends/_sql_base.py](src/pythia/backends/_sql_base.py)
for the dialect-hook surface and [tests/test_backend_duckdb.py](tests/test_backend_duckdb.py)
for a contract-test template.
## Vocabulary backends
In addition to the default `athena_client` (public OHDSI API) and `local`
(your institutional OMOP SQL), pythia can route vocabulary operations
through:
| Backend | Extra | Notes |
|---|---|---|
| `echidna` | `pip install -e '.[echidna]'` | OHDSI-sanctioned FHIR terminology server |
| `webapi` | `pip install -e '.[webapi]'` | Self-hosted OHDSI WebAPI REST |
See [docs/VOCABULARY_BACKENDS.md](docs/VOCABULARY_BACKENDS.md) for backend
selection rules, per-backend configuration, and the return-shape contract.
## MCP client setup
pythia runs as an MCP stdio server. Copy `.mcp.json.template` and fill in
the placeholders:
```bash
cp .mcp.json.template .mcp.json
# Edit .mcp.json: replace <ABSOLUTE_PATH_TO_REPO>, <UV_PATH>, <YOUR_SITE_OR_REMOVE_THIS_KEY>
```
## Environment variables
| Variable | Required | Description |
|----------|----------|-------------|
| `OMOP_SITE` | Conditional | Site name (stem of the JSON filename). Auto-detected when exactly one site config exists; required when multiple coexist. |
| `OMOP_DB_USER` / `OMOP_DB_PASSWORD` | Conditional | Credentials for the institutional DB. Engine-specific aliases (`PGUSER`, `HANA_USER`, `AIRMS_USER`) are accepted. |
| `OMOP_DB_HOST` / `OMOP_DB_PORT` | Optional | Override values in the site config. |
| `OMOP_DB_NAME` | Conditional | Database name (PostgreSQL). |
| `OMOP_DB_PATH` | Conditional | File path (DuckDB). |
| `ATHENA_CACHE_DIR` | Optional | Cache Athena API responses across restarts. |
| `OMOP_CACHE_DIR` | Optional | Cache institutional DB query results across restarts (`HANA_CACHE_DIR` accepted as legacy alias). |
Copy `.env.example` and set values as needed.
## Institutional setup
For access to your organization's OMOP database (prevalence data, data
quality, custom queries), see the full guide:
[docs/INSTITUTIONAL_SETUP.md](docs/INSTITUTIONAL_SETUP.md).
## Development
```bash
uv sync --extra dev # or: pip install -e ".[dev]"
uv run pytest
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidance on adding backends and
vocabulary adapters.
## Licensing
pythia is MIT-licensed. Vocabulary licensing obligations travel with the
data copy your deployment uses — see [LICENSING.md](LICENSING.md).
