Add Docker image, Hugging Face Spaces sync, pre-commit and docs

Author: anapaulagomes

.dockerignore

@@ -0,0 +1,14 @@
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+node_modules
+frontend/node_modules
+frontend/dist
+app/static
+.env
+.idea
+.DS_Store
+tests

.env.example

@@ -0,0 +1,21 @@
+# LLM provider used by `convert` and `humanize`.
+# ollama (local), openai, anthropic, mistral, deepseek, gemini, huggingface
+# Override the provider's default model.
+#   ollama:      OPENSYNDROME_MODEL=qwen2.5:7b-instruct   (model must be `ollama pull`ed)
+#   huggingface: OPENSYNDROME_MODEL=<inference-provider>/<model>, e.g.
+#                hf-inference/meta-llama/Llama-3.1-8B-Instruct
+OPENSYNDROME_PROVIDER=huggingface
+OPENSYNDROME_MODEL=moonshotai/Kimi-K2-Instruct-0905
+
+# Auto-injected on Hugging Face Spaces; set locally to use the huggingface provider.
+# HF_TOKEN=
+
+# Running ollama inside Docker? ollama runs on the host, not the container, so point
+#OLLAMA_HOST=http://host.docker.internal:11434
+
+# Cloud provider keys (only needed for the matching provider)
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# MISTRAL_API_KEY=
+# DEEPSEEK_API_KEY=
+# GEMINI_API_KEY=

.github/workflows/check-file-size.yaml

@@ -0,0 +1,14 @@
+name: Check file size
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check-large-files:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check large files
+        uses: ActionsDesk/lfs-warning@v2.0
+        with:
+          filesizelimit: 10485760 # 10MB so we can sync to HF Spaces

.github/workflows/huggingface.yaml

@@ -0,0 +1,18 @@
+name: Sync to Hugging Face hub
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: huggingface/hub-sync@v0.1.0
+        with:
+          github_repo_id: ${{ github.repository }}
+          huggingface_repo_id: opensyndrome/editor
+          hf_token: ${{ secrets.HF_TOKEN }}
+          space_sdk: docker
+          private: true

.gitignore

@@ -195,9 +195,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
 #   you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 # Temporary file for partial code execution
@@ -216,3 +216,10 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Open Syndrome Editor
+node_modules/
+frontend/node_modules/
+frontend/dist/
+app/static/
+.env

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=10240"]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format

Dockerfile

@@ -0,0 +1,34 @@
+# --- Stage 1: build the React (Vite) frontend ---
+FROM node:20-slim AS frontend
+WORKDIR /frontend
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm install
+COPY frontend/ ./
+# vite outDir is ../app/static -> resolves to /app/static in this stage
+RUN npm run build
+
+# --- Stage 2: Python API serving the built SPA ---
+FROM python:3.12-slim-trixie
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+RUN apt-get update && apt-get install -y --no-install-recommends git \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 appuser
+WORKDIR /app
+
+COPY --chown=appuser:appuser pyproject.toml uv.lock ./
+COPY --chown=appuser:appuser app ./app
+COPY --from=frontend --chown=appuser:appuser /app/static ./app/static
+
+ENV UV_NO_DEV=1
+# Provider/model are configured per-deployment (HF Space variables or --env-file),
+# never baked in, so a mounted .env is always respected.
+
+RUN chown -R appuser:appuser /app
+USER appuser
+RUN uv sync --locked --no-dev
+
+EXPOSE 7860
+# `fastapi run` reads the entrypoint from [tool.fastapi] in pyproject.toml.
+CMD ["uv", "run", "fastapi", "run", "--port", "7860"]

README.md

@@ -1 +1,97 @@
-# editor
+---
+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)](https://github.com/OpenSyndrome/schema):
+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`](https://github.com/OpenSyndrome/open-syndrome-python) 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](https://huggingface.co/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_id`s 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](https://github.com/OpenSyndrome/definitions).
+- 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`):
+
+```bash
+OPENSYNDROME_PROVIDER=huggingface   # default in the container
+OPENSYNDROME_MODEL=...              # a model served by HF Inference Providers
+HF_TOKEN=...                        # auto-injected on Hugging Face Spaces
+```
+
+`validate` and `enrich` need no LLM (enrich only calls EBI OLS4).
+
+## Run locally
+
+**Dev mode (recommended — reads your `.env`, simplest for ollama):**
+
+```bash
+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):**
+
+```bash
+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`:
+
+```bash
+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`, `OPENSYNDROME_MODEL` (and any key)
+as Space *variables/secrets* — `HF_TOKEN` is injected automatically.
+
+## Tests
+
+```bash
+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.