ruby-spacy 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 055dc3da59c059df185ce0d868ba8da07453f0c5c1501d2a61fc5e27e5abee28
-  data.tar.gz: adc27ca2bfcc46ea0ad90bcd2469c2fc5abfdad47982339a7acb085ddeb20de0
+  metadata.gz: eff16e19adc4863d93ac22803e63e5ac2ab8bba077eca7cbc8c2403174704aac
+  data.tar.gz: 1766dc8fbb6c2c4b10314c925ddae484907f6677f9fb314ede756c9b3752923e
 SHA512:
-  metadata.gz: 0ef618c78e55a8607b2975bd91946ab0d337a7fa73982f05fda1bb6db4f8e773b5535b90833fe79de63f8def8a3fb08ce363592a54f941de85b57618f7b7945e
-  data.tar.gz: 0bd57b4cfe238a630c85c93c4b84b0d95b1e07dc74583cf4916fc2b16ba51222c4a35b2a5d5e18e470050ba8680ef642a1d0ba50c6d830b506bf4c4f7b6523f3
+  metadata.gz: b1ef879141c89307e0fa05d5130fa997c0e1746ab0fc4a466dca032a6c4f1007341e8e6a5d1369d1f5a260070e161df8df60f87042343870c862d931faaa7789
+  data.tar.gz: 54baa96c6f475f147b374d8b27a80c6aa792937d759793178fd4f78592588f93d121f4e1edbfb89fdb7e8da5cd6b74abf8b1ccc404ef8bd6f836cc88b55fa407

data/.github/workflows/ci.yml

@@ -33,6 +33,10 @@ jobs:
     env:
       # PyCall locates the Python interpreter via this variable
       PYTHON: python
+      # rsyntaxtree (used by the syntax_tree tests) is in the :rendering
+      # bundler group and needs pango/rsvg system libraries; install it only
+      # on representative jobs
+      BUNDLE_WITHOUT: ${{ matrix.python != '3.13' && 'rendering' || '' }}
     steps:
       - uses: actions/checkout@v7
 
@@ -42,6 +46,12 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
 
+      # Must precede ruby/setup-ruby: bundler-cache installs the pango/rsvg2
+      # gems, which compile against these system libraries
+      - name: Install rsyntaxtree system dependencies (representative jobs)
+        if: matrix.python == '3.13'
+        run: sudo apt-get update && sudo apt-get install -y libpango1.0-dev librsvg2-dev libgirepository1.0-dev
+
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
@@ -53,22 +63,35 @@ jobs:
       # Cache the language models only (en_core_web_lg alone is several hundred
       # MB). spaCy itself is intentionally installed fresh on every run so that
       # new releases are exercised immediately. Bump the key suffix when
-      # upgrading the models.
+      # upgrading the models. The ja/ru/de/zh models are installed only on the
+      # python 3.13 jobs (where the syntax_tree tests run); listing them here
+      # for other jobs is harmless
       - uses: actions/cache@v6
         with:
           path: |
             ${{ steps.site-packages.outputs.path }}/en_core_web_sm*
             ${{ steps.site-packages.outputs.path }}/en_core_web_lg*
-          key: spacy-models-${{ matrix.python }}-v1
+            ${{ steps.site-packages.outputs.path }}/ja_core_news_sm*
+            ${{ steps.site-packages.outputs.path }}/ru_core_news_sm*
+            ${{ steps.site-packages.outputs.path }}/de_core_news_sm*
+            ${{ steps.site-packages.outputs.path }}/zh_core_web_sm*
+          key: spacy-models-${{ matrix.python }}-v2
 
-      # en_core_web_lg is large; install it only on representative jobs.
-      # Tests that need it are skipped automatically where it is absent.
+      # en_core_web_lg and the ja/ru/de/zh models are large; install them only
+      # on representative jobs (where the syntax_tree tests run). Tests that
+      # need them are skipped automatically where they are absent.
       - name: Install spaCy and language models
         run: |
           python -m pip install --upgrade pip
           python -m pip install --upgrade spacy
           python -m spacy download en_core_web_sm
-          if [ "${{ matrix.python }}" = "3.13" ]; then python -m spacy download en_core_web_lg; fi
+          if [ "${{ matrix.python }}" = "3.13" ]; then
+            python -m spacy download en_core_web_lg
+            python -m spacy download ja_core_news_sm
+            python -m spacy download ru_core_news_sm
+            python -m spacy download de_core_news_sm
+            python -m spacy download zh_core_web_sm
+          fi
 
       - name: Run tests
         run: bundle exec rake test

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## 0.7.0 - 2026-09-03
+### Added
+- `Doc#syntax_tree` and `Span#syntax_tree` — turn a parse into rsyntaxtree
+  bracket notation, or draw it as SVG, PNG, PDF, TikZ, or JSON. Two styles:
+  `:projection` builds a phrase-structure-like tree from the head words,
+  `:chunks` lays the noun chunks out flat. Noun chunks are shaded, named
+  entities that coincide with one are labeled, and `morphology: true` attaches
+  a table of features to every leaf. rsyntaxtree (>= 2.4.0) is an optional
+  dependency, required on first use rather than at load time
+- `Language.new(py_nlp:)` — wrap a Python pipeline built elsewhere, for the
+  languages spaCy ships no trained model for. Every right-to-left language is
+  one of them, and their trees are drawn mirrored so the leaves run in reading
+  order. A package such as spacy-stanza builds the pipeline; ruby-spacy gains
+  no dependency
+- `docs/syntax_trees.md` — a gallery of trees in six languages, generated by
+  the scripts in `examples/rsyntaxtree/`
+
+### Changed
+- CI runs the syntax tree tests against English, Japanese, Russian, German, and
+  Chinese models, which between them cover the paths that differ: with and
+  without noun chunks, two-line entity labels, and a mirrored right-to-left tree
+
 ## 0.6.0 - 2026-08-31
 ### Added
 - GitHub Actions CI — Ruby 3.2 to 4.0 (plus ruby-head) and Python 3.11 to 3.14,

data/Gemfile

@@ -9,3 +9,10 @@ group :development do
   gem "github-markup"
   gem "redcarpet"
 end
+
+# Used only for rendering in Doc#syntax_tree / Span#syntax_tree tests.
+# Kept in its own group so CI jobs without the pango/rsvg system libraries
+# can exclude it with BUNDLE_WITHOUT=rendering.
+group :rendering do
+  gem "rsyntaxtree", ">= 2.4.0", require: false
+end

data/README.md

@@ -10,13 +10,15 @@
 | ✅ | Part-of-speech tagging and dependency parsing      |
 | ✅ | Named entity recognition                           |
 | ✅ | Syntactic dependency visualization                 |
+| ✅ | Syntax tree visualization (via rsyntaxtree)        |
 | ✅ | Access to pre-trained word vectors                 |
 | ✅ | LLM integration: OpenAI, Anthropic (Claude), and local models |
 
-Current Version: `0.6.0`
+Current Version: `0.7.0`
 
 - Ruby 3.2 to 4.0 supported (PyCall 1.5.3 or later required)
 - spaCy 3.8 supported
+- Syntax trees drawn with rsyntaxtree, including right-to-left languages
 - Multi-provider LLM API: OpenAI, Anthropic (Claude), and local models via Ollama or any OpenAI-compatible server
 - Structured outputs (JSON Schema) support
 - Block-based LLM API with linguistic analysis
@@ -77,6 +79,18 @@ Or install it yourself as:
 
 See [Examples](#examples) below.
 
+### Using an External Pipeline
+
+`Spacy::Language.new` normally loads an installed model by name. To use a language spaCy has no model for, or a pipeline you built yourself, pass an existing Python `Language` object instead:
+
+```ruby
+py_nlp = PyCall.import_module("spacy_stanza").load_pipeline("ar")
+nlp = Spacy::Language.new(py_nlp: py_nlp)
+nlp.read("...").tokens # works like any other nlp
+```
+
+Third-party packages such as [spacy-stanza](https://github.com/explosion/spacy-stanza) or [spacy-udpipe](https://github.com/TakeLab/spacy-udpipe) are not ruby-spacy dependencies; install them yourself. `model` and `py_nlp:` are mutually exclusive.
+
 ## Examples
 
 Many of the following examples are Python-to-Ruby translations of code snippets in [spaCy 101](https://spacy.io/usage/spacy-101). For more examples, look inside the `examples` directory.
@@ -286,6 +300,42 @@ Output:
 
 ![](https://github.com/yohasebe/ruby-spacy/blob/main/examples/get_started/outputs/test_dep_compact.svg)
 
+### Syntax Trees
+
+→ [rsyntaxtree](https://github.com/yohasebe/rsyntaxtree)
+
+`Doc#syntax_tree` (and `Span#syntax_tree`) converts the parse into rsyntaxtree bracket notation and can render it as an image. rsyntaxtree (>= 2.4.0) is an optional dependency: `gem install rsyntaxtree`.
+
+```ruby
+require "ruby-spacy"
+
+nlp = Spacy::Language.new("en_core_web_sm")
+doc = nlp.read("The quick brown fox jumped over the lazy dog near the river.")
+
+doc.syntax_tree                          # => "[S [%NP [DET The] [ADJ quick] ...] ...]"
+File.binwrite("tree.png", doc.syntax_tree(format: :png))
+doc.syntax_tree(style: :chunks)          # shallow tree with noun chunks
+doc.syntax_tree(morphology: true)        # attach morphology tables to the leaves
+```
+
+<img src="https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_en_projection.png" alt="English projection tree" width="560">
+
+<img src="https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_en_morphology.png" alt="English projection tree with morphology tables" width="760">
+
+<img src="https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ja_projection.png" alt="Japanese projection tree with named entities" width="500">
+
+Two styles are available: `:projection` (default; a phrase-structure-like tree projected from the head words) and `:chunks` (a shallow tree with noun chunks). In both, noun chunks are shaded grey, and a chunk that is also a named entity is shaded orange and labeled with the entity type (`entities: false` to disable). The blue and green are rsyntaxtree's default palette, not marking of any kind; only the shading carries meaning. Punctuation is omitted (`punctuation: true` to keep it). The `format:` option accepts `:bracket` (default), `:svg`, `:png`, `:pdf`, `:tikz`, and `:json`; any other keywords are passed through to rsyntaxtree (e.g. `fontsize: 12`).
+
+The notation is rsyntaxtree-flavored: it can contain AVMs (`#(...#)`), region backgrounds (`%`), and in-word space joins (`<>`). A doc must hold a single sentence; for a multi-sentence doc, use `doc.sents.map { |s| s.syntax_tree }`.
+
+**Annotation schemes differ between models.** spaCy's English models make the preposition the head of its phrase, so projection trees contain `PP` nodes. UD-style models (Japanese, Russian, Chinese, and most others) attach prepositions and particles to the noun instead, so no `PP` appears. Phrase labels come from the head's POS tag and follow whatever scheme the model uses.
+
+**Entity highlighting requires noun chunks.** An entity gets its colored background only where it coincides with a noun chunk. In languages whose models have no noun chunk iterator (Russian, Chinese, Korean, Polish, ...) `entities: true` highlights nothing and `style: :chunks` raises `ArgumentError`.
+
+**Right-to-left languages.** spaCy ships no pipelines for Arabic, Hebrew, or other RTL languages, so one has to come from outside (see [Using an External Pipeline](#using-an-external-pipeline)). Their trees are drawn mirrored automatically; pass `mirror: "off"` to disable.
+
+See the [syntax tree gallery](docs/syntax_trees.md) for rendered trees in six languages, and `examples/rsyntaxtree/` for the scripts that generate them.
+
 ### Named Entity Recognition
 
 → [spaCy: Named entities](https://spacy.io/usage/spacy-101#annotations-ner)

data/docs/syntax_trees.md

@@ -0,0 +1,55 @@
+# Syntax Tree Gallery
+
+Trees drawn by `Doc#syntax_tree` with the [rsyntaxtree](https://github.com/yohasebe/rsyntaxtree) gem. The scripts in `examples/rsyntaxtree/` generate every image here.
+
+Noun chunks are shaded grey; a chunk that is also a named entity is shaded orange and labeled with the entity type. The blue and green are rsyntaxtree's default palette, not marking of any kind. Phrase labels come from the head's POS tag, so they follow whatever annotation scheme the model uses. Both are explained in the [README](../README.md#syntax-trees).
+
+## English (`en_core_web_sm`)
+
+Projection, the default style:
+
+![English projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_en_projection.png)
+
+Chunks style:
+
+![English chunks](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_en_chunks.png)
+
+With morphology (a shorter sentence — the tables are tall):
+
+![English morphology](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_en_morphology.png)
+
+## Japanese (`ja_core_news_sm`)
+
+Projection, with PERSON and GPE highlighted:
+
+![Japanese projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ja_projection.png)
+
+Chunks style:
+
+![Japanese chunks](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ja_chunks.png)
+
+## Russian (`ru_core_news_sm`)
+
+No noun chunk iterator, so `style: :chunks` is unavailable.
+
+![Russian projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ru_projection.png)
+
+With morphology — Russian marks case, gender, animacy, aspect, and voice:
+
+![Russian morphology](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ru_morphology.png)
+
+## German (`de_core_news_sm`)
+
+![German projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_de_projection.png)
+
+## Chinese (`zh_core_web_sm`)
+
+No noun chunk iterator, so `style: :chunks` is unavailable.
+
+![Chinese projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_zh_projection.png)
+
+## Arabic (right-to-left)
+
+spaCy ships no Arabic pipeline, so this tree was parsed with [Stanza](https://stanfordnlp.github.io/stanza/) via [spacy-stanza](https://github.com/explosion/spacy-stanza) and wrapped with `Spacy::Language.new(py_nlp:)`. Right-to-left languages are drawn mirrored automatically. This pipeline has no noun chunks, so nothing is shaded. See `examples/rsyntaxtree/syntax_tree_ar.rb`.
+
+![Arabic projection](https://github.com/yohasebe/ruby-spacy/blob/main/examples/rsyntaxtree/outputs/tree_ar_projection.png)

data/examples/rsyntaxtree/syntax_tree_ar.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Arabic via an external pipeline. spaCy ships no trained pipeline for
+# Arabic (or any other right-to-left language), so this example builds one
+# with Stanza through spacy-stanza. These are NOT ruby-spacy dependencies;
+# install them yourself first:
+#
+#   pip install spacy-stanza
+#   pip install --upgrade "stanza>=1.10"   # spacy-stanza's stanza pin is old and conflicts with current torch
+#   python -c "import stanza; stanza.download('ar')"
+#
+# Note: at exit, spacy-stanza under PyCall prints a harmless
+# multiprocessing.resource_tracker LoadError to stderr (sys.executable
+# points to ruby, not python); the results are unaffected.
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+py_nlp = PyCall.import_module("spacy_stanza")
+               .load_pipeline("ar", processors: "tokenize,pos,lemma,depparse", verbose: false)
+nlp = Spacy::Language.new(py_nlp: py_nlp)
+doc = nlp.read("قرأ الطالب الجديد كتابا مثيرا في المكتبة أمس.")
+
+puts doc.syntax_tree
+
+# Right-to-left languages are drawn mirrored automatically (pass
+# mirror: "off" to disable)
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_ar_projection.png"),
+              doc.syntax_tree(format: :png))

data/examples/rsyntaxtree/syntax_tree_de.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+nlp = Spacy::Language.new("de_core_news_sm")
+doc = nlp.read("Der alte Professor las gestern ein interessantes Buch.")
+
+puts doc.syntax_tree
+
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_de_projection.png"),
+              doc.syntax_tree(format: :png))

data/examples/rsyntaxtree/syntax_tree_en.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+nlp = Spacy::Language.new("en_core_web_sm")
+doc = nlp.read("The quick brown fox jumped over the lazy dog near the river.")
+
+puts doc.syntax_tree
+
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_en_projection.png"),
+              doc.syntax_tree(format: :png))
+File.binwrite(File.join(output_dir, "tree_en_chunks.png"),
+              doc.syntax_tree(style: :chunks, format: :png))
+# A shorter sentence for the morphology tables: every leaf becomes a box, so a
+# long sentence draws a figure too wide to read
+compact = nlp.read("He was sitting under the old tree.")
+File.binwrite(File.join(output_dir, "tree_en_morphology.png"),
+              compact.syntax_tree(format: :png, morphology: true))

data/examples/rsyntaxtree/syntax_tree_ja.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+nlp = Spacy::Language.new("ja_core_news_sm")
+doc = nlp.read("太郎は昨日、東京で花子に古い本を渡した。")
+
+puts doc.syntax_tree
+
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_ja_projection.png"),
+              doc.syntax_tree(format: :png))
+File.binwrite(File.join(output_dir, "tree_ja_chunks.png"),
+              doc.syntax_tree(style: :chunks, format: :png))

data/examples/rsyntaxtree/syntax_tree_ru.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+nlp = Spacy::Language.new("ru_core_news_sm")
+doc = nlp.read("Старый профессор читал интересную книгу в библиотеке.")
+
+puts doc.syntax_tree
+
+# ru_core_news_sm has no noun chunk iterator, so style: :chunks raises
+# ArgumentError for this language; Russian morphology is rich, though
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_ru_projection.png"),
+              doc.syntax_tree(format: :png))
+File.binwrite(File.join(output_dir, "tree_ru_morphology.png"),
+              doc.syntax_tree(format: :png, morphology: true))

data/examples/rsyntaxtree/syntax_tree_zh.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# add path to ruby-spacy lib to load path
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+
+require "ruby-spacy"
+require "fileutils"
+
+# Requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree
+
+nlp = Spacy::Language.new("zh_core_web_sm")
+doc = nlp.read("老教授昨天在图书馆读了一本有趣的书。")
+
+puts doc.syntax_tree
+
+# zh_core_web_sm has no noun chunk iterator, so style: :chunks raises
+# ArgumentError for this language
+output_dir = File.join(File.dirname(__FILE__), "outputs")
+FileUtils.mkdir_p(output_dir)
+File.binwrite(File.join(output_dir, "tree_zh_projection.png"),
+              doc.syntax_tree(format: :png))

data/lib/ruby-spacy/syntax_tree.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module Spacy
+  # Converts spaCy parse results into rsyntaxtree bracket notation and renders
+  # them with the rsyntaxtree gem. This is an internal implementation module;
+  # the public API is {Doc#syntax_tree} and {Span#syntax_tree}.
+  #
+  # rsyntaxtree is a soft dependency: it is required (>= 2.4.0, for
+  # `RSyntaxTree.escape`) on the first call, not at load time.
+  module SyntaxTree
+    FORMATS = %i[bracket svg png pdf tikz json].freeze
+    STYLES = %i[projection chunks].freeze
+
+    # rsyntaxtree drawing defaults chosen for the wide, shallow trees produced
+    # here. User-supplied options take precedence (except hyphen, which the
+    # escaping depends on).
+    RENDER_DEFAULTS = {
+      hyphen: "literal",
+      polyline: "on",
+      tidy: "medium",
+      leafstyle: "nothing",
+      color: "modern"
+    }.freeze
+
+    # Phrase label mapping from the head's POS tag
+    PHRASE_LABEL = {
+      "NOUN" => "NP", "PROPN" => "NP", "PRON" => "NP", "NUM" => "NP",
+      "VERB" => "VP", "AUX" => "VP", "ADP" => "PP", "ADJ" => "AdjP",
+      "ADV" => "AdvP", "DET" => "DP", "SCONJ" => "CP", "CCONJ" => "ConjP"
+    }.freeze
+
+    ENT_BACKGROUND = "orange"
+
+    class << self
+      # @param source [Doc, Span] the document or span to convert
+      # @return [String] the bracket notation (format: :bracket), the rendered
+      #   output (SVG/TikZ/JSON text, or PNG/PDF binary), depending on format
+      def generate(source, format: :bracket, style: :projection, morphology: false,
+                   entities: true, punctuation: false, **render_opts)
+        ensure_rsyntaxtree!
+        format = format.to_sym
+        style = style.to_sym
+        validate_options!(format, style, render_opts)
+
+        bracket = bracket_for(source, style: style, morphology: morphology,
+                              entities: entities, punctuation: punctuation)
+        return bracket if format == :bracket
+
+        # Right-to-left scripts are drawn mirrored (leaves run right to left)
+        # unless the caller says otherwise. The notation itself is unaffected
+        render_opts = { mirror: "on" }.merge(render_opts) if rtl?(source)
+        render(bracket, format, render_opts)
+      end
+
+      private
+
+      # True when the source's language writes right-to-left. Asked from the
+      # pipeline itself (`Defaults.writing_system`) rather than a hardcoded
+      # language list, so external pipelines (spacy-stanza, spacy-udpipe) work
+      # too. Any failure (e.g. no `Defaults`) falls back to left-to-right;
+      # note this also swallows a genuine detection failure, so if an RTL
+      # tree ever renders unmirrored, this fallback is the first place to check
+      def rtl?(source)
+        py_nlp = source.is_a?(Spacy::Span) ? source.doc.py_nlp : source.py_nlp
+        direction = Spacy::Builtins.getattr(py_nlp.Defaults, "writing_system")["direction"]
+        direction.to_s == "rtl"
+      rescue StandardError
+        false
+      end
+
+      def ensure_rsyntaxtree!
+        return if @loaded
+
+        begin
+          require "rsyntaxtree"
+        rescue LoadError
+          raise LoadError, "syntax_tree requires the rsyntaxtree gem (>= 2.4.0): gem install rsyntaxtree"
+        end
+        unless RSyntaxTree.respond_to?(:escape)
+          raise LoadError, "syntax_tree requires rsyntaxtree >= 2.4.0 (found #{RSyntaxTree::VERSION})"
+        end
+        @loaded = true
+      end
+
+      def validate_options!(format, style, render_opts)
+        unless FORMATS.include?(format)
+          raise ArgumentError, "unknown format: #{format.inspect} (expected one of: #{FORMATS.join(', ')})"
+        end
+        unless STYLES.include?(style)
+          raise ArgumentError, "unknown style: #{style.inspect} (expected one of: #{STYLES.join(', ')})"
+        end
+        if render_opts.key?(:hyphen)
+          raise ArgumentError, "hyphen: cannot be overridden (the notation is escaped for hyphen: :literal)"
+        end
+        unknown = render_opts.keys.map(&:to_sym) - ::DEFAULT_OPTS.keys
+        unless unknown.empty?
+          raise ArgumentError,
+                "unknown rsyntaxtree option(s): #{unknown.join(', ')} (valid: #{::DEFAULT_OPTS.keys.join(', ')})"
+        end
+        if format == :bracket && !render_opts.empty?
+          raise ArgumentError,
+                "drawing options (#{render_opts.keys.join(', ')}) have no effect with format: :bracket"
+        end
+      end
+
+      def render(bracket, format, render_opts)
+        params = RENDER_DEFAULTS.merge(render_opts).merge(data: bracket)
+        gen = RSyntaxTree::RSGenerator.new(params)
+        case format
+        when :svg then gen.draw_svg
+        when :json then gen.draw_json
+        when :tikz then gen.draw_tikz
+        when :png then gen.draw_png.force_encoding(Encoding::BINARY)
+        when :pdf then gen.draw_pdf.force_encoding(Encoding::BINARY)
+        end
+      end
+
+      # Escapes a string for the bracket notation. `as:` follows
+      # `RSyntaxTree.escape` (:word for leaf words, :label for entity labels,
+      # :cell for AVM cells).
+      def escape(text, as:, context: nil)
+        RSyntaxTree.escape(text, as: as, hyphen: :literal, apostrophe: :keep)
+      rescue ArgumentError => e
+        where = context ? " (#{context})" : ""
+        raise ArgumentError, "syntax_tree: cannot escape#{where}: #{e.message}"
+      end
+
+      def bracket_for(source, style:, morphology:, entities:, punctuation:)
+        tokens, root, root_label = tree_scope(source)
+        chunks = chunk_spans(source)
+        if chunks.nil? && style == :chunks
+          raise ArgumentError,
+                "noun chunks are not available for this language/model, so style: :chunks cannot be used"
+        end
+        chunks ||= []
+        ents = entities ? ent_map(source) : {}
+
+        case style
+        when :chunks
+          chunks_bracket(tokens, chunks, ents, morphology: morphology, punctuation: punctuation)
+        else
+          projection_bracket(root, chunks, ents, root_label: root_label,
+                             morphology: morphology, punctuation: punctuation)
+        end
+      end
+
+      # Returns [tokens, root_token, root_label]. All positions are doc-based
+      # (Span#tokens / Token#i are doc-based, which matches chunk and entity
+      # offsets).
+      def tree_scope(source)
+        case source
+        when Spacy::Doc
+          py_doc = source.py_doc
+          unless py_doc.has_annotation("DEP")
+            raise ArgumentError, "syntax_tree requires a dependency parse (the pipeline has no parser)"
+          end
+          if py_doc.has_annotation("SENT_START") && source.sents.size > 1
+            raise ArgumentError,
+                  "syntax_tree requires a single sentence; " \
+                  "use doc.sents.map { |s| s.syntax_tree } for a multi-sentence doc"
+          end
+          tokens = source.tokens
+          # The root is the token that is its own head. Comparing dep strings
+          # would tie this to an annotation scheme (spaCy's trained pipelines
+          # use "ROOT" while UD-style pipelines such as Stanza use "root")
+          root = tokens.find { |t| t.head.i == t.i }
+          raise ArgumentError, "syntax_tree: no root token found (no dependency parse)" unless root
+
+          [tokens, root, "S"]
+        when Spacy::Span
+          unless source.py_span.doc.has_annotation("DEP")
+            raise ArgumentError, "syntax_tree requires a dependency parse (the pipeline has no parser)"
+          end
+          tokens = source.tokens
+          raise ArgumentError, "syntax_tree: empty span" if tokens.empty?
+
+          first_i = tokens.first.i
+          last_i = tokens.last.i
+          roots = tokens.select { |t| t.head.i == t.i || t.head.i < first_i || t.head.i > last_i }
+          unless roots.size == 1
+            raise ArgumentError,
+                  "syntax_tree requires a span with a single root (e.g. a sentence from doc.sents)"
+          end
+          root = roots.first
+          unless root.left_edge.i == first_i && root.right_edge.i == last_i
+            raise ArgumentError,
+                  "syntax_tree requires a span that is a complete subtree " \
+                  "(e.g. a sentence from doc.sents or a noun chunk)"
+          end
+          is_sentence = source.py_span.sent.start == source.py_span.start &&
+                        source.py_span.sent.end == source.py_span.end
+          [tokens, root, is_sentence ? "S" : PHRASE_LABEL.fetch(root.pos, "XP")]
+        else
+          raise ArgumentError, "syntax_tree expects a Spacy::Doc or Spacy::Span"
+        end
+      end
+
+      # Noun chunk spans as doc-based [start, end) pairs, or nil when the
+      # language/model has no noun chunk iterator (spaCy error E894).
+      def chunk_spans(source)
+        source.noun_chunks.map { |c| [c.py_span.start, c.py_span.end] }
+      rescue PyCall::PyError => e
+        raise unless e.message.include?("E894")
+
+        nil
+      end
+
+      # Entity spans as a doc-based [start, end) => label map
+      def ent_map(source)
+        source.ents.to_h { |e| [[e.py_span.start, e.py_span.end], e.label] }
+      end
+
+      def leaf(token, morphology:)
+        word = escape(token.text, as: :word, context: "token #{token.text.inspect}")
+        return "[#{token.pos} #{word}]" unless morphology
+
+        rows = ["pos\\t#{escape(token.pos, as: :cell)}"]
+        morph = token.morphology(hash: false)
+        unless morph.empty?
+          morph.split("|").each do |kv|
+            k, v = kv.split("=", 2)
+            rows << "#{escape(k, as: :cell)}\\t#{escape(v, as: :cell)}"
+          end
+        end
+        "[#(#{rows.join('\n')}#) #{word}]"
+      end
+
+      # "%NP" for a bare chunk; "%@orange:NP\nLABEL" for one matching an entity
+      def chunk_label(base, ent_label)
+        return "%#{base}" unless ent_label
+
+        "%@#{ENT_BACKGROUND}:#{base}\\n#{escape(ent_label, as: :label, context: 'entity label')}"
+      end
+
+      # A shallow tree: [S ...] with chunks as [%NP [POS w] ...] and other
+      # tokens as plain leaves. Chunks matching an entity get a colored
+      # background and a second label line.
+      def chunks_bracket(tokens, chunks, ents, morphology:, punctuation:)
+        i = 0
+        parts = []
+        while i < tokens.size
+          token = tokens[i]
+          chunk = chunks.find { |s, _e| s == token.i }
+          if chunk
+            s, e = chunk
+            chunk_tokens = tokens.select { |t| t.i >= s && t.i < e }
+            label = chunk_label("NP", ents[[s, e]])
+            parts << "[#{label} #{chunk_tokens.map { |t| leaf(t, morphology: morphology) }.join(' ')}]"
+            i += chunk_tokens.size
+          else
+            parts << leaf(token, morphology: morphology) unless token.pos == "PUNCT" && !punctuation
+            i += 1
+          end
+        end
+        "[S #{parts.join(' ')}]"
+      end
+
+      # Head projection: each head projects a phrase node over its dependents
+      # and itself in word order. A phrase whose span coincides with a noun
+      # chunk gets a background; when the chunk containing the head is
+      # narrower than the projection (NP -> NP PP), the chunk's tokens are
+      # wrapped in an inner [%NP ...]. A single-token chunk (a frequent case
+      # for named entities) is wrapped as [%NP leaf] so that the background
+      # and entity label are not lost.
+      def projection_bracket(token, chunks, ents, root_label:, morphology:, punctuation:)
+        kids = token.children.to_a
+        kids = kids.reject { |k| k.pos == "PUNCT" } unless punctuation
+        if kids.empty?
+          node = leaf(token, morphology: morphology)
+          single = [token.i, token.i + 1]
+          return node unless chunks.include?(single)
+
+          return "[#{chunk_label('NP', ents[single])} #{node}]"
+        end
+
+        label = root_label || PHRASE_LABEL.fetch(token.pos, "XP")
+        span = [token.left_edge.i, token.right_edge.i + 1]
+        label = chunk_label(label, ents[span]) if chunks.include?(span)
+
+        ordered = (kids + [token]).sort_by(&:i)
+        render_node = lambda do |t|
+          if t.i == token.i
+            leaf(t, morphology: morphology)
+          else
+            projection_bracket(t, chunks, ents, root_label: nil,
+                               morphology: morphology, punctuation: punctuation)
+          end
+        end
+
+        inner = chunks.find { |s, e| (s...e).cover?(token.i) && [s, e] != span }
+        if inner
+          s, e = inner
+          inside, = ordered.partition { |t| (s...e).cover?(t.i) }
+          inner_node = "[#{chunk_label('NP', ents[inner])} #{inside.map(&render_node).join(' ')}]"
+          parts = ordered.map { |t| inside.include?(t) ? (t.equal?(inside.first) ? inner_node : nil) : render_node.call(t) }
+          parts = parts.compact
+        else
+          parts = ordered.map(&render_node)
+        end
+        "[#{label} #{parts.join(' ')}]"
+      end
+    end
+  end
+end

data/lib/ruby-spacy/version.rb

@@ -2,5 +2,5 @@
 
 module Spacy
   # The version number of the module
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/ruby-spacy.rb

@@ -6,6 +6,7 @@ require_relative "ruby-spacy/openai_client"
 require_relative "ruby-spacy/anthropic_client"
 require_relative "ruby-spacy/openai_helper"
 require_relative "ruby-spacy/anthropic_helper"
+require_relative "ruby-spacy/syntax_tree"
 require "pycall"
 require "json"
 require "base64"
@@ -344,6 +345,40 @@ module Spacy
       PyDisplacy.render(py_doc, style: style, options: { compact: compact }, jupyter: false)
     end
 
+    # Generates a syntax tree in rsyntaxtree bracket notation, or renders it
+    # with the rsyntaxtree gem.
+    #
+    # Requires the rsyntaxtree gem (>= 2.4.0) at call time (it is a soft
+    # dependency; install it with `gem install rsyntaxtree`). The doc must
+    # contain a single sentence; for a multi-sentence doc, use
+    # `doc.sents.map { |s| s.syntax_tree }`.
+    #
+    # Note that the bracket notation is rsyntaxtree-flavored: it may contain
+    # rsyntaxtree-specific markup such as AVMs (`#(...#)`), region backgrounds
+    # (`%`), and in-word space joins (`<>`).
+    #
+    # @param format [Symbol] `:bracket` (default; the notation string),
+    #   `:svg`, `:png`, `:pdf`, `:tikz`, or `:json`. `:png` and `:pdf` return
+    #   a binary string
+    # @param style [Symbol] `:projection` (default; head-projection
+    #   phrase-structure-like tree) or `:chunks` (shallow tree with noun chunks)
+    # @param morphology [Boolean] attach a morphology AVM to each leaf
+    # @param entities [Boolean] mark chunks that match a named entity with a
+    #   colored background and the entity label
+    # @param punctuation [Boolean] keep punctuation tokens
+    # @param render_opts [Hash] rsyntaxtree drawing options (e.g. `fontsize:`).
+    #   `hyphen:` cannot be overridden
+    # @return [String] the bracket notation or the rendered output
+    # @example
+    #   doc.syntax_tree                          # => "[S [%NP [DET The] ...] ...]"
+    #   doc.syntax_tree(format: :svg)            # => "<svg ..."
+    #   doc.syntax_tree(format: :png, fontsize: 12)
+    def syntax_tree(format: :bracket, style: :projection, morphology: false,
+                    entities: true, punctuation: false, **render_opts)
+      SyntaxTree.generate(self, format: format, style: style, morphology: morphology,
+                          entities: entities, punctuation: punctuation, **render_opts)
+    end
+
     # Generates a JSON string summarizing the linguistic analysis of the document.
     # Designed to be passed as context to an LLM (e.g., via {OpenAIHelper#chat}).
     #
@@ -614,6 +649,12 @@ module Spacy
       end
     end
 
+    # Sentinel for "the caller gave no model argument". Distinct from nil so
+    # that an explicit nil (e.g. an unset ENV var passed straight through)
+    # still fails validation instead of silently loading the default model
+    NO_MODEL = Object.new.freeze
+    private_constant :NO_MODEL
+
     # Creates a language model instance, which is conventionally referred to by a variable named `nlp`.
     # @param model [String] A language model installed in the system
     # @param timeout [Numeric, nil] Seconds to wait for the model to load before
@@ -622,7 +663,31 @@ module Spacy
     #   because Ruby's `Timeout` cannot fire while PyCall holds the GVL. When it
     #   fires, the loading thread is left running as a daemon until the process
     #   exits (accepted: timeouts are an abnormal path).
-    def initialize(model = "en_core_web_sm", max_retrial: MAX_RETRIAL, timeout: 60)
+    # @param py_nlp [Object, nil] an existing Python `Language` pipeline to wrap
+    #   instead of loading a model. For languages spaCy ships no trained
+    #   pipeline for (e.g. Arabic and other right-to-left languages) or for
+    #   self-built pipelines, create one with a third-party package such as
+    #   spacy-stanza or spacy-udpipe and pass it here. Mutually exclusive with
+    #   `model`; model name validation, timeout, and retries are skipped
+    # @example Load an installed spaCy model
+    #   nlp = Spacy::Language.new("en_core_web_sm")
+    # @example Wrap an external pipeline (requires: pip install spacy-stanza)
+    #   py_nlp = PyCall.import_module("spacy_stanza").load_pipeline("ar")
+    #   nlp = Spacy::Language.new(py_nlp: py_nlp)
+    def initialize(model = NO_MODEL, max_retrial: MAX_RETRIAL, timeout: 60, py_nlp: nil)
+      if py_nlp
+        raise ArgumentError, "model and py_nlp: are mutually exclusive" unless model.equal?(NO_MODEL)
+        unless Builtins.isinstance(py_nlp, PyLanguage)
+          raise ArgumentError,
+                "py_nlp: must be a spaCy Language pipeline " \
+                "(e.g. from spacy.load or spacy_stanza.load_pipeline)"
+        end
+
+        @py_nlp = py_nlp
+        return
+      end
+
+      model = "en_core_web_sm" if model.equal?(NO_MODEL)
       unless model.to_s.match?(/\A[a-zA-Z0-9_\-\.\/]+\z/)
         raise ArgumentError, "Invalid model name: #{model.inspect}"
       end
@@ -1003,6 +1068,15 @@ module Spacy
       Doc.new(@doc.py_nlp, text: text)
     end
 
+    # Generates a syntax tree for the span in rsyntaxtree bracket notation, or
+    # renders it with the rsyntaxtree gem. The span must have a single root
+    # (e.g. a sentence from {Doc#sents}). See {Doc#syntax_tree} for the
+    # available options.
+    # @return [String] the bracket notation or the rendered output
+    def syntax_tree(**options)
+      SyntaxTree.generate(self, **options)
+    end
+
     # Returns tokens conjugated to the root of the span.
     # @return [Array<Token>] an array of tokens
     def conjuncts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-spacy
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Yoichiro Hasebe
@@ -169,6 +169,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/syntax_trees.md
 - examples/get_started/lexeme.rb
 - examples/get_started/linguistic_annotations.rb
 - examples/get_started/morphology.rb
@@ -230,6 +231,22 @@ files:
 - examples/openai_integration/openai_query_2.rb
 - examples/openai_integration/openai_query_3.rb
 - examples/openai_integration/openai_query_4.rb
+- examples/rsyntaxtree/outputs/tree_ar_projection.png
+- examples/rsyntaxtree/outputs/tree_de_projection.png
+- examples/rsyntaxtree/outputs/tree_en_chunks.png
+- examples/rsyntaxtree/outputs/tree_en_morphology.png
+- examples/rsyntaxtree/outputs/tree_en_projection.png
+- examples/rsyntaxtree/outputs/tree_ja_chunks.png
+- examples/rsyntaxtree/outputs/tree_ja_projection.png
+- examples/rsyntaxtree/outputs/tree_ru_morphology.png
+- examples/rsyntaxtree/outputs/tree_ru_projection.png
+- examples/rsyntaxtree/outputs/tree_zh_projection.png
+- examples/rsyntaxtree/syntax_tree_ar.rb
+- examples/rsyntaxtree/syntax_tree_de.rb
+- examples/rsyntaxtree/syntax_tree_en.rb
+- examples/rsyntaxtree/syntax_tree_ja.rb
+- examples/rsyntaxtree/syntax_tree_ru.rb
+- examples/rsyntaxtree/syntax_tree_zh.rb
 - examples/rule_based_matching/creating_spans_from_matches.rb
 - examples/rule_based_matching/matcher.rb
 - lib/ruby-spacy.rb
@@ -238,6 +255,7 @@ files:
 - lib/ruby-spacy/llm_client_base.rb
 - lib/ruby-spacy/openai_client.rb
 - lib/ruby-spacy/openai_helper.rb
+- lib/ruby-spacy/syntax_tree.rb
 - lib/ruby-spacy/version.rb
 - ruby-spacy.gemspec
 homepage: https://github.com/yohasebe/ruby-spacy