You can install it from PyPI or Docker. By default, the conversion features use Ollama running locally. Cloud providers (OpenAI, Anthropic, Mistral, DeepSeek, Gemini) are also supported and require only an API key.
From PyPi, install the package with pip install opensyndrome. Then run it with opensyndrome --help.
From Docker, you can run the following command to build the image, tagged opensyndrome:
docker build -t opensyndrome .Run the container interactively, removing it when it exits
docker run --rm -it opensyndromeTo read a .env file, mount it:
docker run --rm -it \
-v "$(pwd)/.env:/app/.env:ro" \
opensyndromeTo name the container and keep it around:
docker run --name opensyndrome-cli -it opensyndromeFirst, download the schema and definitions in order to work with the CLI locally.
opensyndrome download schema
opensyndrome download definitionsThe files will be placed in the folder .open_syndrome in $HOME.
The definitions published by the Open Syndrome Initiative (the community definitions) always live in
~/.open_syndrome/v1/definitions. To add definitions of your own that are not published on GitHub, point
OPENSYNDROME_DEFINITIONS_DIR to a directory you maintain; it is never written to by the CLI.
OPENSYNDROME_DEFINITIONS_DIR=./my-definitionsTo ignore the community definitions altogether and use only yours, also set
OPENSYNDROME_LOCAL_DEFINITIONS_ONLY=1 (true, yes and on also work). Nothing is downloaded in that
mode, not even with --force.
From Python, opensyndrome.artifacts.get_definition_dirs() returns the directories to read, in order:
OPENSYNDROME_DEFINITIONS_DIR |
OPENSYNDROME_LOCAL_DEFINITIONS_ONLY |
Result |
|---|---|---|
| unset | unset | [community] |
| set | unset | [community, local] |
| set | set | [local] |
| unset | set | error |
It also accepts local_dir and local_only keyword arguments that override the environment variables.
The former get_definition_dir() still returns the community directory only, ignoring these variables;
it emits a DeprecationWarning and will be removed in a future version.
The provider and model can be set via environment variables so you don't have to pass them on every command:
OPENSYNDROME_PROVIDER=ollama # ollama (default), openai, anthropic, mistral, deepseek, gemini
OPENSYNDROME_MODEL=mistral # overrides the provider's default modelCopy .env.example to .env and fill in the relevant values:
| Provider | Required env var | Default model |
|---|---|---|
ollama |
— (runs locally) | mistral |
openai |
OPENAI_API_KEY |
gpt-4o |
anthropic |
ANTHROPIC_API_KEY |
claude-3-haiku-20240307 |
mistral |
MISTRAL_API_KEY |
mistral-large-latest |
deepseek |
DEEPSEEK_API_KEY |
deepseek-chat |
gemini |
GEMINI_API_KEY |
gemini-1.5-flash |
For Ollama, the model must be pulled before use: ollama pull mistral. You can also override the Ollama base URL with OLLAMA_BASE_URL
(default: http://localhost:11434).
Ollama models tested: llama3.2, mistral, deepseek-r1. Known to not work well with structured output: qwen2.5-coder.
If you do not pass
-hror-hf, an editor will open for you to enter the definition.
# see some examples from ECDC: https://www.ecdc.europa.eu/en/all-topics/eu-case-definitions
# pass the definition as inline text
opensyndrome convert -hr "Any person with pneumonia"
# pass the definition from a TXT file
opensyndrome convert -hf definition.txt
# use a specific provider and model
opensyndrome convert -hr "Any person with pneumonia" --provider openai --model gpt-4o
# to have the JSON translated to a specific language and edit it just after conversion
opensyndrome convert --language "Português do Brasil" --edit
# include a validation step after conversion
opensyndrome convert --validateThe enrich command populates ontology_id fields on criteria nodes and sets the @context to the OpenSyndrome JSON-LD context URL. It queries EBI OLS4 by default, or text2term as an alternative mapper.
# enrich an existing JSON definition (uses OLS4 by default)
opensyndrome enrich definition.json
# use text2term instead (requires: pip install opensyndrome[text2term])
opensyndrome enrich definition.json --mapper text2term
# review and adjust the result in an editor before printing
opensyndrome enrich definition.json --edit
# enrich and validate in one step
opensyndrome enrich definition.json --validateYou can also enrich directly after conversion:
opensyndrome convert -hr "Any person with fever and rash" --enrich-ontology
opensyndrome convert -hr "Any person with fever and rash" --enrich-ontology --mapper text2termopensyndrome humanize <path-to-json-file>
opensyndrome humanize <path-to-json-file> --provider anthropic
opensyndrome humanize <path-to-json-file> --model mistral-large-latest --language "Português do Brasil"opensyndrome validate <path-to-json-file>To get started with development, you need to have uv installed.
uv syncTo include the optional text2term mapper (and its bioregistry dependency) so the full test suite runs without skips:
uv sync --all-extrasYou only need to do this if you are a maintainer adding a new OSI schema or updating an existing one.
Since Ollama requires a specific, more simple, JSON format, we need to generate an Ollama-compatible schema.
To do this, we use datamodel-code-generator to generate a Pydantic schema. Run the following command to update it:
make ollama_schemaIt will create a schema.py file in the root of the project. Be careful when editing this file manually.
If you find this repository helpful, feel free to cite our publication: The Open Syndrome Definition
@misc{ferreira2025opensyndromedefinition,
title={The Open Syndrome Definition},
author={Ana Paula Gomes Ferreira and Aleksandar Anžel and Izabel Oliva Marcilio de Souza and Helen Hughes and Alex J Elliot and Jude Dzevela Kong and Madlen Schranz and Alexander Ullrich and Georges Hattab},
year={2025},
eprint={2509.25434},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2509.25434},
}