open-syndrome-python

Installation

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 opensyndrome

To read a .env file, mount it:

docker run --rm -it \
  -v "$(pwd)/.env:/app/.env:ro" \
  opensyndrome

To name the container and keep it around:

docker run --name opensyndrome-cli -it opensyndrome

Usage

First, download the schema and definitions in order to work with the CLI locally.

opensyndrome download schema
opensyndrome download definitions

The files will be placed in the folder .open_syndrome in $HOME.

Using your own local definitions

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-definitions

To 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.

Providers and configuration

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 model

Copy .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.

Convert a human-readable syndrome definition to a machine-readable JSON

If you do not pass -hr or -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 --validate

Enrich ontology IDs on a JSON definition

The 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 --validate

You 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 text2term

Convert a machine-readable JSON syndrome definition to a human-readable format

opensyndrome 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"

Validate a machine-readable JSON syndrome definition

opensyndrome validate <path-to-json-file>

Development

To get started with development, you need to have uv installed.

Install dependencies

uv sync

To include the optional text2term mapper (and its bioregistry dependency) so the full test suite runs without skips:

uv sync --all-extras

Generate Ollama-compatible JSON

You 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_schema

It will create a schema.py file in the root of the project. Be careful when editing this file manually.

Citing & Authors

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},
}