An AI assistant for designing OMOP cohorts, built into ATLAS v3.0.
Describe the cohort you want in plain language and Pythia builds it with you. It searches the vocabulary of the database you are connected to, then proposes each part of the definition as a card: the entry event, the inclusion rules, the exclusions, the observation window. You accept or reject each card, and only what you accept reaches the cohort editor.
Two things it will not do. It will not put a concept in your cohort unless that concept came back from a search against your own data source, so it cannot quietly invent a code that does not exist there. And it will not tell you what an analysis shows without reading the generated result first.
On its own, using the stack in this repository: ATLAS, the assistant, and a demo database, on one machine. That is what the rest of this page describes, and it is the quickest way to try Pythia.
As part of Data2Evidence, the wider OHDSI platform, where Pythia ships alongside the rest of its services and runs against your own data. Follow that project's instructions instead of the ones below.
- Docker, with about 10 GB of free disk for the images and the demo database.
- An AWS Bedrock API key, so Pythia has a model to think with. Everything else still runs without one, but the assistant cannot answer.
git clone https://github.com/OHDSI/Pythia.git
cd Pythia
cp .env.example .env # put your Bedrock key in AWS_BEARER_TOKEN_BEDROCK
docker compose up -dOpen https://localhost and sign in as admin / admin. The certificate is
self-signed, so your browser warns you once before letting you through.
The first start downloads about 10 GB and loads the demo database, which takes a
few minutes. docker compose logs -f trex follows the backend as it comes up.
ATLAS is ready when https://localhost/WebAPI/info answers.
Go to Cohort Definitions, choose New Cohort, and open Pythia with the chat button in the bottom right.
Ask for something the demo data can answer, for example:
Build me a cohort of adults with osteoarthritis starting ibuprofen, excluding anyone with a previous gastrointestinal bleed.
Pythia searches for the concepts, then sends a card for each part of the definition. Accept the ones you want and reject the rest; a rejected card is not a dead end, and it will offer a different approach. When the definition looks right, ask it to save and generate the cohort, then ask what the numbers show. It reads the attrition and tells you which rule removed whom.
The demo database is Eunomia, a synthetic dataset of about 2,700 patients covering common complaints such as osteoarthritis, sinusitis and bronchitis. It is small enough to run on a laptop, so cohorts generate in seconds, and it is worth knowing that many real world concepts are simply absent from it. If Pythia says it cannot find a drug or condition, that is usually the data rather than the assistant.
docker compose up starts four containers:
| ATLAS | the OHDSI cohort builder, with the Pythia panel added, served over HTTPS |
| trex | the backend that runs Pythia and hosts an embedded OHDSI WebAPI |
| Eunomia database | ATLAS metadata and the demo patient data |
| trex database | the backend's own storage |
The embedded OHDSI WebAPI is available at http://localhost:8080/WebAPI if you want to reach it directly.
Everything is set in .env, and every option is listed in .env.example with
its default.
Pick the model Pythia answers with:
BAO_AGENT_MODEL=us.anthropic.claude-sonnet-4-6 # a Bedrock model id
BAO_AGENT_MODEL_SPEC=openai/openai.gpt-5.6-terra # or a provider and modelBAO_AGENT_MODEL_SPEC takes precedence if you set both. A spec beginning with
openai/ is sent to an OpenAI-compatible endpoint on Bedrock; set
OPENAI_BASE_URL to use a different one. The BAO_ prefix is historical and
simply names the service that runs the assistant.
ATLAS and the backend run at versions pinned in docker-compose.yml, so the
stack behaves the same on every machine. ATLAS_IMAGE and TREX_IMAGE point it
at a different build if you need one.
docker compose stop # stop, keeping your cohorts and data
docker compose up -d # pick up where you left off
docker compose down -v # remove everything, including cohorts you savedtrexsql-cache/ holds a cache of the demo database that powers the live patient
counts shown while you build a cohort. It sits outside the containers so it
survives a restart. If you delete it those counts stop working until you rebuild
it, which you can do from Configuration inside ATLAS.
Pythia does not answer. Its key is missing or rejected. Check
AWS_BEARER_TOKEN_BEDROCK in .env, then docker compose up -d trex to pick
up the change.
ATLAS loads but has no data sources. The demo database is still loading on
first start. docker compose logs -f trex shows when it is ready.
Pythia says it cannot find a concept. Eunomia is a small synthetic dataset and many concepts are not in it. Try one of the conditions listed above.