README.md

metadata

title: Universal Dependencies Visualizer
emoji: 🌳
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.48.0
app_file: app.py
pinned: false
license: mit

Universal Dependencies Parser & Visualizer

A clean, pedagogical demonstration tool for exploring and comparing Universal Dependencies (UD) parsers and treebanks for English and German.

• Visualizations powered by conllu.js
• Parsers powered by UDPipe 2 (LINDAT)
• Compare canonical treebanks: English-EWT vs English-GUM, German-HDT vs German-GSD

Run Locally

Use Python 3.13, install requirements.txt in a virtual environment, then run python app.py. To enable the experimental screencast recorder locally, run with ENABLE_SCREENCAST=true python app.py (disabled by default). The application calls UDPipe from Python and loads conllu.js and brat in the browser from pinned jsDelivr revisions. Browser network access to the CDN is required.

conllu.js parses the returned CoNLL-U and converts it to brat data; brat renders the interactive tree in an isolated iframe. SVG and PNG downloads include the tree fonts. Asset-loading and parsing failures appear in the visualization area.

See browser regression checks for deterministic fixtures, Gradio integration tests, and hosted verification steps.

Annotate, Export, and API

The Annotate & Export tab parses one sentence per line and offers CoNLL-U, SVG, and PNG downloads. It also renders pasted or corrected CoNLL-U. Its buttons are the app's public API (/annotate, /render, /models); see the tab's Use as an API section for gradio_client examples. Images are drawn server-side by the same conllu.js/brat renderer in headless Chromium (Playwright), so they match the tree download buttons. The Space installs Chromium's system libraries from packages.txt and downloads the browser on first export.

Interface Design

The Sentence input is the visual starting point in Parse and Compare. Its single-line layout intentionally uses a prominent 24px font with 1.5 line height for teaching and screencasts. Preserve this size when adjusting the layout. Gradio can render textboxes as either input or textarea elements; the sentence styling covers both.

Drag a tree panel's bottom-right handle to resize its width and height. Focus the handle and use arrow keys to resize with the keyboard; double-click it to restore automatic fitting. Each comparison tree can be resized independently.

Application Version and Releases

Application version and release date live in core/version.py and appear quietly below the tabs. This is separate from Gradio's sdk_version and the UDPipe model and renderer revisions. Version 1.0.0 establishes the initial application release baseline.

Use semantic versioning: patch for fixes, minor for backward-compatible features, major for incompatible changes to supported workflows or public APIs. Prepare a release from the repository root:

python scripts/bump_version.py patch  # or minor / major
python -m compileall -q app.py core visualizer scripts
python -m unittest discover -s tests -p 'test_*.py'

The script updates the version and release date (Europe/Zurich) only; it does not commit, tag, push, or deploy. Review the diff and complete the relevant browser checks before creating an explicit release commit, for example chore(release): prepare v1.0.1. Include all intended release changes, then tag that commit as v1.0.1. Push the same release commit to the development repository and the Space, and verify the displayed version after deployment. There is no automatic version bump on push.