NLPPlus 2.0.22__cp313-cp313-win_amd64.whl

NLPPlus/__init__.py

@@ -0,0 +1,414 @@
+"""Python extension for NLP++ text analysis engine.
+
+Basic usage:
+
+    import NLPPlus
+    xml = NLPPlus.analyze("This is some text to be parsed")
+    print(xml)
+
+"""
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_0():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'nlpplus.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_0()
+del _delvewheel_patch_1_13_0
+# end delvewheel patch
+
+import json
+import logging
+from shutil import copytree, rmtree
+from tempfile import TemporaryDirectory
+from os import PathLike, getcwd
+from pathlib import Path
+from typing import Optional, Any
+import os
+import glob
+
+from .bindings import NLP_ENGINE  # type: ignore
+
+LOGGER = logging.getLogger("NLPPlus")
+
+
+def maybe_readfile(path: Path) -> Optional[str]:
+    """Bogus utility function to maybe read a file."""
+    if not path.exists():
+        return None
+    with open(path, "rt") as infh:
+        return infh.read()
+
+
+class EngineException(BaseException):
+    pass
+
+
+class Results:
+    """Various results produced by the NLP++ analyzer."""
+
+    def __init__(self, outtext: str, outdir: PathLike):
+        LOGGER.info("Reading output from %s", outdir)
+        self.output_text = outtext
+        self.outdir = Path(outdir)
+
+    @property
+    def final_tree(self) -> Optional[str]:
+        """The final parse tree, if any was produced."""
+        return maybe_readfile(self.outdir / "final.tree")
+
+    @property
+    def output_json(self) -> Optional[str]:
+        """The output JSON text, if any was produced."""
+        return maybe_readfile(self.outdir / "output.json")
+
+    @property
+    def output(self) -> Optional[Any]:
+        """The parsed output Json, if any was produced"""
+        output_json = self.output_json
+        if output_json is not None:
+            return json.loads(output_json)
+        return None
+
+
+class Engine:
+    """NLP++ Engine for a given working folder.
+
+    Args:
+
+      working_folder(optional, PathLike): Working folder for this
+           instance.  If None, a temporary directory will be created
+           and initialized with the default analyzers.  Otherwise,
+           this must contain an `analyzers` and a `data` folder,
+           unless `initialize` is `True`.
+      verbose(optional, bool): Be more verbose.
+      initialize(optional, bool): Initialize `working_folder` with
+           the default analyzers.
+    """
+    def __init__(
+        self,
+        working_folder: Optional[PathLike] = None,
+        analyzer_path: str = None,
+        verbose: bool = False,
+        initialize: bool = False,
+    ):
+        self._closed = False
+        if working_folder is None:
+            # ignore_cleanup_errors=True is now defense-in-depth: close()
+            # / __exit__ / __del__ explicitly call self.engine.close()
+            # before TemporaryDirectory.cleanup, which closes the engine's
+            # cgerr.log handle and lets Windows delete the temp dir
+            # cleanly. The flag still catches the corner case of an
+            # interpreter shutdown where __del__ never runs (e.g. crash,
+            # os._exit) — the OS reclaims the tempdir at process exit
+            # regardless, so swallowing the cleanup error keeps stderr
+            # quiet for users who never explicitly close. Engine-side
+            # fix shipped in NLP-ENGINE-523 (engine v3.1.55+).
+            self.tmpdir = TemporaryDirectory(
+                prefix="NLPPlus-", ignore_cleanup_errors=True
+            )
+            self.working_folder = Path(self.tmpdir.name)
+            initialize = True
+        else:
+            self.tmpdir = None
+            self.working_folder = Path(working_folder)
+        self.analyzer_path = None
+        if initialize:
+            copytree(
+                Path(__file__).parent / "analyzers", self.working_folder / "analyzers"
+            )
+            copytree(Path(__file__).parent / "data", self.working_folder / "data")
+            LOGGER.info("Initialized working folder in %s", self.working_folder)
+        if not (self.working_folder / "analyzers").is_dir():
+            raise EngineException(
+                f"analyzers directory not found in folder '{working_folder}'"
+            )
+        if not (self.working_folder / "data").is_dir():
+            raise EngineException(
+                f"data directory not found in folder '{working_folder}'"
+            )
+        self.engine = NLP_ENGINE(str(self.working_folder), silent=not verbose)
+
+    def close(self):
+        """Tear down the underlying engine and release the working folder.
+
+        Idempotent: safe to call multiple times. After ``close()``, any
+        call to :meth:`analyze`, :meth:`compile`, or :meth:`cloud_compile`
+        is undefined behavior — create a new ``Engine`` instead.
+
+        On Windows in particular, calling ``close()`` (or using ``Engine``
+        as a context manager) is what makes the auto-created
+        ``TemporaryDirectory`` working folder delete cleanly: the engine
+        keeps a file handle on ``<workfolder>/logs/cgerr.log`` open for
+        the lifetime of the C++ instance, and Windows refuses to delete
+        a directory that contains an open file. ``close()`` calls into
+        the C++ engine's ``close()`` (NLP-ENGINE-523, engine v3.1.55+),
+        which releases that handle before the tempdir is removed.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        # Engine.close() is idempotent on the C++ side as of engine
+        # v3.1.55; older engines just no-op the second teardown.
+        try:
+            self.engine.close()
+        except AttributeError:
+            # Pre-3.1.55 binding without the close() method exposed;
+            # fall back to letting __del__ tear it down. The tempdir
+            # cleanup below will still hit the PermissionError on
+            # Windows in that case — same situation as before 2.0.4.
+            pass
+        if self.tmpdir is not None:
+            self.tmpdir.cleanup()
+            self.tmpdir = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.close()
+        return False
+
+    def __del__(self):
+        # Best-effort: __del__ may run during interpreter shutdown when
+        # modules are being torn down and the bindings module may already
+        # be gone. Swallow anything that goes wrong here; the explicit
+        # close() / context-manager paths are the supported way to get
+        # deterministic cleanup.
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def analyze(self, text: str, analyzer_name: str, develop: bool = False,
+                compiled: bool = False) -> Results:
+        """Analyze text with the named analyzer.
+
+        Args:
+          text: input text to analyze.
+          analyzer_name: name of the analyzer under the working folder.
+          develop: if True, the engine emits intermediate log/tree files
+                   into the analyzer's `_log` directory.
+          compiled: if True, the engine loads the analyzer's compiled
+                    shared libraries (``bin/run.<ext>`` for the analyzer
+                    body and ``bin/kb.<ext>`` for the compiled KB)
+                    instead of running interpreted from the ``.nlp``
+                    source.  See :meth:`compile` to produce the
+                    generated C++ sources for those libraries, and the
+                    package README for the cmake / cloud build step
+                    that turns them into the actual ``.so``/``.dylib``/
+                    ``.dll`` files.
+        """
+        analyzer_name = Path(analyzer_name)
+        outdir = self.working_folder / "analyzers" / analyzer_name / "output"
+        if self.analyzer_path:
+            analyzer_name = Path(self.analyzer_path) / analyzer_name
+            outdir = Path(self.analyzer_path) / "analyzers" / analyzer_name / "output"
+        # Delete all files in the outdir
+        file_list = glob.glob(str(outdir / "*"))
+        for file_path in file_list:
+            os.remove(file_path)
+        outtext = self.engine.analyze(str(analyzer_name), text, develop,
+                                      compiled)
+        return Results(outtext, outdir)
+
+    def compile(self, analyzer_name: str, develop: bool = False,
+                kb_only: bool = False, analyzer_only: bool = False) -> Path:
+        """Generate C++ source files for the named analyzer.
+
+        Runs the engine in ``-COMPILE`` mode, or ``-COMPILEKB`` if
+        ``kb_only=True`` (KB only), or ``-COMPILEANA`` if
+        ``analyzer_only=True`` (analyzer rules only, skipping the KB).
+        ``-COMPILE`` emits the analyzer body under ``<analyzer>/run/``
+        and the knowledge base under ``<analyzer>/kb/``; ``-COMPILEKB``
+        emits just ``<analyzer>/kb/``; ``-COMPILEANA`` emits just
+        ``<analyzer>/run/``.  Returns the analyzer directory containing
+        those generated trees.
+
+        Use ``analyzer_only=True`` when only the rules changed and the
+        KB is already compiled.  ``kb_only`` and ``analyzer_only`` are
+        mutually exclusive.
+
+        The generated C++ still needs to be built into shared
+        libraries before :meth:`analyze` can load them with
+        ``compiled=True``.  Use :meth:`cloud_compile` to do the build
+        step via the public nlp-compile-service in one call.
+        """
+        if kb_only and analyzer_only:
+            raise ValueError("compile: kb_only and analyzer_only are mutually exclusive")
+        analyzer_name_p = Path(analyzer_name)
+        if self.analyzer_path:
+            analyzer_dir = (
+                Path(self.analyzer_path) / "analyzers" / analyzer_name_p
+            )
+            engine_arg = str(Path(self.analyzer_path) / analyzer_name_p)
+        else:
+            analyzer_dir = (
+                self.working_folder / "analyzers" / analyzer_name_p
+            )
+            engine_arg = str(analyzer_name_p)
+        self.engine.compile(engine_arg, develop, kb_only, analyzer_only)
+        return analyzer_dir
+
+    def cloud_compile(self, analyzer_name: str,
+                      dispatcher_url: Optional[str] = None,
+                      kb_only: bool = False,
+                      analyzer_only: bool = False,
+                      develop: bool = False,
+                      poll_interval: float = 2.0,
+                      timeout: float = 30 * 60,
+                      skip_local_compile: bool = False) -> Path:
+        """End-to-end compile: codegen + cloud build + stage into bin/.
+
+        Runs :meth:`compile` to produce the analyzer's ``run/`` + ``kb/``
+        C++ trees (unless ``skip_local_compile=True``), packages them
+        plus an auto-generated ``StdAfx.h`` stub into a tarball, submits
+        that tarball to the public nlp-compile-service dispatcher, polls
+        for the GitHub-Actions runner build to complete, downloads the
+        resulting shared library, and stages it into
+        ``<analyzer>/bin/`` as ``run.<ext>`` and ``kb.<ext>`` (and the
+        Windows ``runu.<ext>`` / ``kbu.<ext>`` variants).  After this
+        returns, :meth:`analyze` with ``compiled=True`` will load the
+        compiled artifact.
+
+        Returns the ``bin/`` directory path.
+
+        Args:
+          analyzer_name: analyzer under the engine's working folder.
+          dispatcher_url: override the public dispatcher endpoint
+            (default: ``cloud.DEFAULT_DISPATCHER_URL``).
+          kb_only: compile only the KB.
+          analyzer_only: compile only the analyzer rules (skip the KB).
+            Mutually exclusive with ``kb_only``.
+          develop: forwarded to local ``-COMPILE``.
+          poll_interval: seconds between job-status checks.
+          timeout: max seconds to wait for the runner build.
+          skip_local_compile: if True, assume ``run/`` and ``kb/``
+            already exist under the analyzer dir.
+        """
+        # Import here so the rest of the package keeps working in
+        # environments that don't have an `urllib`-friendly TLS stack.
+        from . import cloud
+        return cloud.cloud_compile(
+            self, analyzer_name,
+            dispatcher_url=dispatcher_url or cloud.DEFAULT_DISPATCHER_URL,
+            kb_only=kb_only, analyzer_only=analyzer_only, develop=develop,
+            poll_interval=poll_interval, timeout=timeout,
+            skip_local_compile=skip_local_compile,
+        )
+    
+    def input_text(self, analyzer_name: str, file_name: str) -> str:
+        """Return the text from a file in the input directory."""
+        file_path = Path(self.analyzer_path) / analyzer_name / "input" / file_name
+        if not file_path.is_file():
+            raise EngineException(
+                f"File not found in input directory '{file_path}'"
+            )
+        with open(file_path, "rt", encoding="utf-8") as file:
+            text = file.read()
+        return text
+    
+    def set_analyzers_folder(self, analyzer_name: str):
+        """Set analyzers directory path."""
+        self.analyzer_path = analyzer_name
+
+    def copy_library_analyzers(self, to_dir: str, overwrite: bool=True):
+        """Copy the library files to a directory."""
+        copy_it = True
+
+        if os.path.exists(to_dir):
+            if overwrite:
+                rmtree(to_dir)
+            else:
+                copy_it = False
+
+        if copy_it:
+            copytree(
+                Path(__file__).parent / "analyzers", Path(to_dir)
+            )
+        self.analyzer_path = str(to_dir)
+
+
+engine = Engine()
+
+
+def set_working_folder(working_folder: Optional[str] = None, initialize: bool = False):
+    """Reinitialize the NLP++ engine with a different working folder.
+
+    Args:
+
+      working_folder(str): Working folder to use, or `None` to use the
+                           current working directory.
+      initialize(bool): Initialize the new working folder with the built-in
+                        analyzers and data.  (Optional, default=False)
+    """
+    global engine
+    if working_folder is None:
+        working_folder = getcwd()
+    engine = Engine(Path(working_folder), initialize=initialize)
+
+
+def copy_library_analyzers(analyzer_folder_path: str, overwrite=True):
+    """Run the analyzer named on the input string."""
+    engine.copy_library_analyzers(analyzer_folder_path, overwrite)
+
+
+def set_analyzers_folder(analyzer_folder_path: str):
+    """Run the analyzer named on the input string."""
+    engine.set_analyzers_folder(analyzer_folder_path)
+
+
+def analyze(text: str, parser: str = "parse-en-us", develop: bool = False,
+            compiled: bool = False) -> str:
+    """Run the analyzer named on the input string.
+
+    If ``compiled=True``, the engine loads the analyzer's compiled
+    shared libraries (``bin/run.<ext>`` and ``bin/kb.<ext>``) instead of
+    running interpreted.  See :func:`compile` for producing those.
+    """
+    return engine.analyze(text, parser, develop, compiled).output_text
+
+
+def compile(analyzer: str = "parse-en-us", develop: bool = False,
+            kb_only: bool = False, analyzer_only: bool = False):
+    """Generate C++ source files for the named analyzer.
+
+    Wraps :meth:`Engine.compile`.  The generated trees land under
+    ``<analyzer>/run/`` and ``<analyzer>/kb/`` inside the engine's
+    working folder (or just ``kb/`` for ``kb_only``, or just ``run/``
+    for ``analyzer_only``); they still need to be built into shared
+    libraries before :func:`analyze` can load them with
+    ``compiled=True``.
+    """
+    return engine.compile(analyzer, develop, kb_only, analyzer_only)
+
+
+def cloud_compile(analyzer: str = "parse-en-us",
+                  dispatcher_url: Optional[str] = None,
+                  kb_only: bool = False,
+                  analyzer_only: bool = False,
+                  develop: bool = False,
+                  poll_interval: float = 2.0,
+                  timeout: float = 30 * 60,
+                  skip_local_compile: bool = False):
+    """Compile an analyzer end-to-end via the public nlp-compile-service.
+
+    Wraps :meth:`Engine.cloud_compile` — see that method for the full
+    docstring.  After this call returns, ``analyze(..., compiled=True)``
+    will pick up the staged shared libraries from the analyzer's
+    ``bin/`` directory.
+    """
+    return engine.cloud_compile(
+        analyzer, dispatcher_url=dispatcher_url, kb_only=kb_only,
+        analyzer_only=analyzer_only, develop=develop,
+        poll_interval=poll_interval, timeout=timeout,
+        skip_local_compile=skip_local_compile,
+    )
+
+
+def input_text(analyzer_name: str, file_name: str):
+    """Return the text from a file in the input directory."""
+    return engine.intput_text(analyzer_name, file_name)

NLPPlus/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.0.22'
+__version_tuple__ = version_tuple = (2, 0, 22)
+
+__commit_id__ = commit_id = 'g756328b5f'

NLPPlus/analyzers/.github/workflows/dispatch-update-package-analyzers.yml

@@ -0,0 +1,40 @@
+# Install at: VisualText/package-analyzers -> .github/workflows/dispatch-update-package-analyzers.yml
+#
+# Sender in the cross-repo percolation chain (see
+# VisualText/nlp-engine/docs/PERCOLATION.md).
+#
+# When a release tag (v*) is pushed here, ping the repos that embed
+# package-analyzers as a submodule so they refresh their pointer. Both the npm
+# and Python nlpengine packages listen for the `package-analyzers-release` event
+# and open a bump PR (they publish to npm/PyPI with their own versions, so a
+# submodule bump must not auto-publish — a human merges the PR).
+#
+# Requires the shared `CLASSIC_PAT` secret in this repo (the default
+# GITHUB_TOKEN cannot trigger workflows in other repos).
+
+name: Dispatch update-package-analyzers
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        repo:
+          - VisualText/npm-package-nlpengine   # embeds package-analyzers at path analyzers
+          - VisualText/py-package-nlpengine    # embeds package-analyzers at path NLPPlus/analyzers
+    steps:
+      - name: Trigger ${{ matrix.repo }}
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.CLASSIC_PAT }}
+          repository: ${{ matrix.repo }}
+          event-type: package-analyzers-release
+          client-payload: '{"tag_name": "${{ github.ref_name }}"}'
+        continue-on-error: true

NLPPlus/analyzers/.github/workflows/tag-on-push.yml

@@ -0,0 +1,86 @@
+# Install at: VisualText/package-analyzers -> .github/workflows/tag-on-push.yml
+#
+# Source of the percolation chain for DIRECT analyzer edits (see
+# VisualText/nlp-engine/docs/PERCOLATION.md).
+#
+# When you edit an analyzer (address-parser, emailaddress, links, telephone) and
+# push to main, this auto-computes the next semver tag and pushes it. Pushing the
+# v* tag fires dispatch-update-package-analyzers.yml, which pings the npm and
+# Python packages to bump + auto-publish.
+#
+# parse-en-us is intentionally NOT in the path filter: parse-en-us changes arrive
+# via update-parse-en-us.yml (driven by parse-en-us-release), which tags itself.
+# Keeping the two paths disjoint avoids double-tagging.
+#
+# Requires the shared CLASSIC_PAT secret (a GITHUB_TOKEN-pushed tag cannot
+# trigger dispatch-update-package-analyzers.yml in turn).
+
+name: Tag on push
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'address-parser/**'
+      - 'emailaddress/**'
+      - 'links/**'
+      - 'telephone/**'
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Semver component to bump"
+        required: true
+        default: "patch"
+        type: choice
+        options: [patch, minor, major]
+
+permissions:
+  contents: write
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.CLASSIC_PAT }}
+
+      - name: Configure git identity
+        run: |
+          git config user.name  'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
+      - name: Compute next version
+        id: version
+        run: |
+          set -euo pipefail
+          bump="${{ inputs.bump }}"
+          bump="${bump:-patch}"   # push events have no inputs
+          latest=$(git tag --sort=-v:refname \
+                   | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+                   | head -n1 || true)
+          latest=${latest:-v0.0.0}
+          IFS='.' read -r major minor patch <<<"${latest#v}"
+          case "$bump" in
+            major) major=$((major + 1)); minor=0; patch=0 ;;
+            minor) minor=$((minor + 1)); patch=0 ;;
+            patch) patch=$((patch + 1)) ;;
+          esac
+          new="v${major}.${minor}.${patch}"
+          echo "new=$new" >> "$GITHUB_OUTPUT"
+          echo "Tagging $latest -> $new"
+
+      - name: Tag and push
+        run: |
+          set -euo pipefail
+          git tag -a "${{ steps.version.outputs.new }}" -m "Release ${{ steps.version.outputs.new }}"
+          git push origin "${{ steps.version.outputs.new }}"
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.new }}
+          name: ${{ steps.version.outputs.new }}
+          generate_release_notes: true
+          token: ${{ secrets.CLASSIC_PAT || secrets.GITHUB_TOKEN }}

NLPPlus/analyzers/.github/workflows/update-parse-en-us.yml

@@ -0,0 +1,130 @@
+# Install at: VisualText/package-analyzers -> .github/workflows/update-parse-en-us.yml
+#
+# Listener in the cross-repo percolation chain (see
+# VisualText/nlp-engine/docs/PERCOLATION.md).
+#
+# 1. Pulls the latest commit of the parse-en-us submodule's default branch (main).
+# 2. Computes a new semver tag by bumping the latest vX.Y.Z tag.
+# 3. Commits the submodule pointer change, tags, and pushes.
+# 4. Cuts a GitHub release at the new tag. Pushing the v* tag fires
+#    dispatch-update-package-analyzers.yml, which pings the npm and Python
+#    packages to refresh their analyzers submodule.
+#
+# Triggered by parse-en-us (event-type parse-en-us-release) on its release, or
+# by hand. A repository_dispatch ping carries no inputs, so the bump defaults to
+# patch.
+
+name: Update parse-en-us & Bump Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Semver component to bump"
+        required: true
+        default: "patch"
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      create_release:
+        description: "Create a GitHub release at the new tag"
+        required: true
+        default: true
+        type: boolean
+  repository_dispatch:
+    types: [parse-en-us-release]
+
+permissions:
+  contents: write
+
+jobs:
+  update-and-bump:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (with submodules and full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+          token: ${{ secrets.CLASSIC_PAT || secrets.GITHUB_TOKEN }}
+
+      - name: Configure git identity
+        run: |
+          git config user.name  'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+
+      - name: Update parse-en-us to latest main
+        id: submodule
+        run: |
+          set -euo pipefail
+          before=$(git -C parse-en-us rev-parse HEAD)
+          git -C parse-en-us fetch origin main
+          git -C parse-en-us checkout origin/main
+          git -C parse-en-us submodule update --init --recursive
+          after=$(git -C parse-en-us rev-parse HEAD)
+          echo "before=$before" >> "$GITHUB_OUTPUT"
+          echo "after=$after"   >> "$GITHUB_OUTPUT"
+          if [ "$before" = "$after" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "parse-en-us already at $after"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "parse-en-us: $before -> $after"
+          fi
+
+      - name: Compute next version
+        id: version
+        run: |
+          set -euo pipefail
+          bump="${{ inputs.bump }}"
+          bump="${bump:-patch}"   # repository_dispatch has no inputs
+          latest=$(git tag --sort=-v:refname \
+                   | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' \
+                   | head -n1 || true)
+          latest=${latest:-v0.0.0}
+          IFS='.' read -r major minor patch <<<"${latest#v}"
+          case "$bump" in
+            major) major=$((major + 1)); minor=0; patch=0 ;;
+            minor) minor=$((minor + 1)); patch=0 ;;
+            patch) patch=$((patch + 1)) ;;
+          esac
+          new="v${major}.${minor}.${patch}"
+          echo "previous=$latest" >> "$GITHUB_OUTPUT"
+          echo "new=$new"         >> "$GITHUB_OUTPUT"
+          echo "Bumping $latest -> $new"
+
+      - name: Commit submodule update
+        if: steps.submodule.outputs.changed == 'true'
+        run: |
+          git add parse-en-us
+          git commit -m "Update parse-en-us to ${{ steps.submodule.outputs.after }} (${{ steps.version.outputs.new }})"
+
+      - name: Tag and push
+        run: |
+          set -euo pipefail
+          git tag -a "${{ steps.version.outputs.new }}" \
+            -m "Release ${{ steps.version.outputs.new }}"
+          git push origin HEAD
+          git push origin "${{ steps.version.outputs.new }}"
+
+      - name: Create GitHub release
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.create_release }}
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.new }}
+          name: ${{ steps.version.outputs.new }}
+          generate_release_notes: true
+          token: ${{ secrets.CLASSIC_PAT || secrets.GITHUB_TOKEN }}
+
+      - name: Summary
+        run: |
+          {
+            echo "### Update parse-en-us & bump version"
+            echo ""
+            echo "- previous tag: \`${{ steps.version.outputs.previous }}\`"
+            echo "- new tag: \`${{ steps.version.outputs.new }}\`"
+            echo "- parse-en-us changed: \`${{ steps.submodule.outputs.changed }}\`"
+            echo "- parse-en-us: \`${{ steps.submodule.outputs.before }}\` → \`${{ steps.submodule.outputs.after }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"