title	Open Syndrome Editor
emoji	🩺
colorFrom	green
colorTo	blue
sdk	docker
app_port	7860
pinned	false

Open Syndrome Definition — Editor

A web editor for Open Syndrome Definitions (OSD): write a free-text clinical case definition and convert it to machine-readable JSON, validate it against the schema, enrich ontology IDs via EBI OLS4, and humanize JSON back into narrative text — all powered by the opensyndrome Python package.

It pairs a two-pane "clinical IDE" UI (React + Vite) with a FastAPI backend, served together as a single container on Hugging Face Spaces.

Features

• Convert — parse free clinical text into the OSD schema (LLM via the configured provider).
• Validate — check a definition against the downloaded OSD JSON Schema.
• Enrich — populate ontology_ids by matching criterion names through EBI OLS4.
• Humanize — regenerate narrative text from the structured definition.
• Import — clinical text, a local JSON file, or browse the community definitions repo.
• Recursive inclusion / exclusion criteria trees (AND / OR / AT_LEAST), full metadata, live validation, View / Copy / Download JSON.

Models (convert & humanize)

The LLM provider/model is configurable via environment variables (see .env.example):

OPENSYNDROME_PROVIDER=huggingface   # default in the container
OPENSYNDROME_MODEL=...              # a model served by HF Inference Providers
HF_TOKEN=...                        # required: a token with Inference Providers access
LITELLM_EXTRA_HEADERS=...           # optional: extra request headers (see below)

By default, HF Inference Providers bill the owner of HF_TOKEN. If that account has exhausted its monthly included credits you get 402 Payment Required. To charge an organization's credits instead, set LITELLM_EXTRA_HEADERS='{"X-HF-Bill-To": "my-org"}' (you must be a member of the org); these headers are merged into every model call.

validate and enrich need no LLM (enrich only calls EBI OLS4).

Run locally

Dev mode (recommended — reads your .env, simplest for ollama):

cp .env.example .env        # set OPENSYNDROME_PROVIDER / OPENSYNDROME_MODEL
uv sync
uv run uvicorn app.main:app --reload --port 8000     # API on :8000

cd frontend && npm install && npm run dev            # UI on :5173 (proxies /api -> :8000)
# open http://localhost:5173

With OPENSYNDROME_PROVIDER=ollama, this talks to ollama on localhost:11434 directly. Make sure the model is pulled: ollama pull qwen2.5:7b-instruct.

Single production image (what ships to HF Spaces):

docker build -t opensyndrome-editor .

docker run --rm -p 7860:7860 opensyndrome-editor

# convert/humanize need a provider. Pass your .env:
docker run --rm -p 7860:7860 --env-file .env opensyndrome-editor

ollama from Docker: ollama runs on the host, so point the container at it with OLLAMA_HOST:

docker run --rm -p 7860:7860 \
  --add-host=host.docker.internal:host-gateway \
  -e OPENSYNDROME_PROVIDER=ollama \
  -e OPENSYNDROME_MODEL=qwen2.5:7b-instruct \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  opensyndrome-editor
# open http://localhost:7860

On Hugging Face Spaces, set OPENSYNDROME_PROVIDER and OPENSYNDROME_MODEL as Space Variables, and add HF_TOKEN (a token with Inference Providers access) as a Space Secret.

Error monitoring (optional)

Set SENTRY_DSN (and optionally SENTRY_ENVIRONMENT, SENTRY_TRACES_SAMPLE_RATE) to send exceptions to Sentry. The FastAPI integration is auto-enabled; LLM failures are reported with their real provider/validation cause even though the client receives a clean 502.

Tests

uv run pytest                 # backend API
cd frontend && npm test       # frontend logic (osd.js)

Deploy

Hosted on Hugging Face Spaces (Docker SDK). Pushes to main are mirrored to the Space by the Sync to Hugging Face hub GitHub Action.