Add displaCy visualization support for dependency trees

Adds functions to visualize Tree objects using spaCy's displaCy library.

Changes:
- Add to_displacy() function to convert Tree to displaCy format
- Add render() function to generate SVG visualizations
- Add optional viz dependency group (pip install treesearch-ud[viz])
- Make functions available as Tree methods (tree.render(), tree.to_displacy())
- Update documentation in README, API.md, and docs/api.md
- Update CHANGELOG with unreleased features

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: rmalouf

API.md

@@ -361,6 +361,69 @@ for tree, match in ts.search_trees(trees, pattern):
     print(f"Found: {verb.form}")
 ```
 
+### Visualization Functions
+
+#### `to_displacy(tree: Tree) -> dict`
+
+Convert a Tree to displaCy's manual rendering format.
+
+**Parameters:**
+- `tree` (Tree): A Tree object to convert
+
+**Returns:**
+- `dict`: Dictionary with 'words' and 'arcs' keys in displaCy format
+
+```python
+tree = next(ts.trees("corpus.conllu"))
+data = ts.to_displacy(tree)
+# Returns: {'words': [{'text': '...', 'tag': '...'}, ...], 'arcs': [...]}
+
+# Use with spaCy's displacy
+from spacy import displacy
+displacy.render(data, style="dep", manual=True)
+```
+
+#### `render(tree: Tree, **options) -> str`
+
+Render a Tree as an SVG dependency visualization using displaCy.
+
+**Requirements:** Requires spaCy to be installed (`pip install treesearch-ud[viz]` or `pip install spacy`)
+
+**Parameters:**
+- `tree` (Tree): A Tree object to render
+- `**options`: Additional options passed to displacy.render()
+  - `jupyter` (bool): Return HTML for Jupyter display (default: auto-detect)
+  - `compact` (bool): Use compact visualization mode
+  - `word_spacing` (int): Spacing between words
+  - `distance` (int): Distance between dependency arcs
+
+**Returns:**
+- `str`: SVG markup string (or displays in Jupyter if jupyter=True)
+
+**Raises:**
+- `ImportError`: If spaCy is not installed
+
+```python
+# Basic usage
+tree = next(ts.trees("corpus.conllu"))
+svg = ts.render(tree)
+print(svg)  # SVG markup
+
+# Save to file
+with open("tree.svg", "w") as f:
+    f.write(svg)
+
+# In Jupyter notebook (displays inline)
+ts.render(tree, jupyter=True)
+
+# Compact mode with custom spacing
+svg = ts.render(tree, compact=True, word_spacing=50)
+
+# Also available as Tree methods
+svg = tree.render()
+data = tree.to_displacy()
+```
+
 ### Data Classes
 
 #### `Tree`

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Tree visualization with displaCy via `render()` and `to_displacy()` functions
+- Optional `viz` extras for spaCy dependency
+
 ## [0.1.0] - 2025-12-29
 
 Initial release.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treesearch-ud"
-version = "0.1.0"
+version = "0.2.0-dev"
 edition = "2024"
 authors = ["Rob Malouf"]
 description = "High-performance toolkit for querying linguistic dependency parses"

README.md

@@ -18,6 +18,9 @@ Requires Python 3.12+.
 
 ```bash
 pip install treesearch-ud
+
+# Optional: Install with visualization support (displaCy)
+pip install treesearch-ud[viz]
 ```
 
 ### From Source

docs/api.md

@@ -58,6 +58,24 @@ for tree, match in ts.search_trees(tree, pattern):
     ...
 ```
 
+### to_displacy(tree) → dict
+
+Convert a Tree to displaCy format for visualization.
+
+```python
+data = ts.to_displacy(tree)
+# Returns: {'words': [...], 'arcs': [...]}
+```
+
+### render(tree, **options) → str
+
+Render a Tree as SVG using displaCy. Requires spaCy (`pip install treesearch-ud[viz]`).
+
+```python
+svg = ts.render(tree)
+ts.render(tree, jupyter=True)  # Display in Jupyter
+```
+
 ## Treebank
 
 Collection of trees from one or more files.
@@ -89,6 +107,8 @@ A dependency tree (parsed sentence).
 - `tree.word(id) → Word` - Get word by ID (0-indexed). Raises `IndexError` if out of range.
 - `tree[id] → Word` - Same as `word(id)`
 - `len(tree) → int` - Number of words
+- `tree.to_displacy() → dict` - Convert to displaCy format
+- `tree.render(**options) → str` - Render as SVG (requires spaCy)
 
 ## Word
 

pyproject.toml

@@ -45,6 +45,9 @@ docs = [
     "mkdocs>=1.5.0",
     "mkdocs-material>=9.0.0",
 ]
+viz = [
+    "spacy>=3.0.0",
+]
 
 [tool.maturin]
 features = ["pyo3/extension-module"]

python/treesearch/__init__.py

@@ -45,6 +45,8 @@
     "trees",
     "search",
     "search_trees",
+    "to_displacy",
+    "render",
 ]
 
 
@@ -157,3 +159,91 @@ def search_trees(
     else:
         source = list(source)
     return py_search_trees(source, query)
+
+
+def to_displacy(tree: Tree) -> dict:
+    """Convert a Tree to displaCy's manual rendering format.
+
+    Args:
+        tree: A Tree object to convert
+
+    Returns:
+        Dictionary in displaCy format with 'words' and 'arcs' keys
+
+    Example:
+        >>> tree = next(treesearch.trees("corpus.conllu"))
+        >>> data = treesearch.to_displacy(tree)
+        >>> from spacy import displacy
+        >>> displacy.render(data, style="dep", manual=True)
+    """
+    words = []
+    arcs = []
+
+    for i in range(len(tree)):
+        word = tree.word(i)
+        words.append({"text": word.form, "tag": word.upos})
+
+        if word.head is not None:
+            head_idx = word.head
+            dep_idx = word.id
+            if head_idx < dep_idx:
+                arcs.append(
+                    {
+                        "start": head_idx,
+                        "end": dep_idx,
+                        "label": word.deprel,
+                        "dir": "right",
+                    }
+                )
+            else:
+                arcs.append(
+                    {
+                        "start": dep_idx,
+                        "end": head_idx,
+                        "label": word.deprel,
+                        "dir": "left",
+                    }
+                )
+    return {"words": words, "arcs": arcs}
+
+
+def render(tree: Tree, **options) -> str:
+    """Render a Tree as an SVG dependency visualization using displaCy.
+
+    Requires spaCy to be installed.
+
+    Args:
+        tree: A Tree object to render
+        **options: Additional options passed to displacy.render()
+            Common options include:
+            - jupyter: bool - Return HTML for Jupyter display (default: auto-detect)
+            - compact: bool - Use compact visualization mode
+            - word_spacing: int - Spacing between words
+            - distance: int - Distance between dependency arcs
+
+    Returns:
+        SVG markup string (or displays in Jupyter if jupyter=True)
+
+    Raises:
+        ImportError: If spaCy is not installed
+
+    Example:
+        >>> tree = next(treesearch.trees("corpus.conllu"))
+        >>> svg = treesearch.render(tree)
+        >>> with open("tree.svg", "w") as f:
+        ...     f.write(svg)
+
+        # In Jupyter notebook:
+        >>> treesearch.render(tree, jupyter=True)
+    """
+    try:
+        from spacy import displacy
+    except ImportError:
+        raise ImportError("spaCy is required for rendering. Install it with: pip install spacy")
+
+    data = to_displacy(tree)
+    return displacy.render(data, style="dep", manual=True, **options)
+
+
+Tree.to_displacy = to_displacy
+Tree.render = render

python/treesearch/treesearch.pyi

@@ -238,3 +238,31 @@ def py_search_trees(trees: list[Tree], pattern: Pattern | str) -> MatchIterator:
         Iterator over (Tree, match_dict) tuples from all trees
     """
     ...
+
+def to_displacy(tree: Tree) -> dict[str, list]:
+    """Convert a Tree to displaCy's manual rendering format.
+
+    Args:
+        tree: A Tree object to convert
+
+    Returns:
+        Dictionary with 'words' and 'arcs' keys for displaCy rendering
+    """
+    ...
+
+def render(tree: Tree, **options) -> str:
+    """Render a Tree as an SVG dependency visualization using displaCy.
+
+    Requires spaCy to be installed.
+
+    Args:
+        tree: A Tree object to render
+        **options: Additional options passed to displacy.render()
+
+    Returns:
+        SVG markup string
+
+    Raises:
+        ImportError: If spaCy is not installed
+    """
+    ...