fix: address Python 3.14 review findings

(cherry picked from commit c49db38935)

README.md

@@ -255,7 +255,7 @@ Codex users also need `multi_agent = true` under `[features]` in `~/.codex/confi
 | `neo4j` | Neo4j push support | `uv tool install "graphifyy[neo4j]"` |
 | `falkordb` | FalkorDB push support | `uv tool install "graphifyy[falkordb]"` |
 | `svg` | SVG graph export | `uv tool install "graphifyy[svg]"` |
-| `leiden` | Leiden community detection (Python < 3.13 only) | `uv tool install "graphifyy[leiden]"` |
+| `leiden` | Leiden community detection (graspologic on Python < 3.13; native backend on 3.13+) | `uv tool install "graphifyy[leiden]"` |
 | `ollama` | Ollama local inference | `uv tool install "graphifyy[ollama]"` |
 | `openai` | OpenAI / OpenAI-compatible APIs | `uv tool install "graphifyy[openai]"` |
 | `gemini` | Google Gemini API | `uv tool install "graphifyy[gemini]"` |
@@ -877,7 +877,7 @@ uv run pytest tests/ -q -k "python"    # filter by name
 ### CI parity checks
 
 The authoritative CI commands live in [`.github/workflows/`](.github/workflows/).
-For local CI-style verification, use Python 3.10 or 3.12 and run:
+For local CI-style verification, use Python 3.10, 3.12, 3.13, or 3.14 and run:
 
 ```bash
 uv sync --all-extras --frozen
@@ -905,7 +905,7 @@ is added to CI later. The Bandit and pip-audit CI steps currently use
 > policy before relying on long-path tests. Restart affected shells or applications
 > after changing either setting. For exact parity with the blocking GitHub Actions
 > test matrix, run the suite in WSL or Linux; CI currently runs on Ubuntu with
-> Python 3.10 and 3.12. Pyright is available as a local advisory check, but it is
+> Python 3.10, 3.12, 3.13, and 3.14. Pyright is available as a local advisory check, but it is
 > not currently a blocking CI job.
 
 ### Git workflow

docs/translations/README.he-IL.md

@@ -207,7 +207,7 @@ graphify install --project --platform codex
 | `neo4j` | דחיפה ל-Neo4j | `uv tool install "graphifyy[neo4j]"` |
 | `falkordb` | דחיפה ל-FalkorDB | `uv tool install "graphifyy[falkordb]"` |
 | `svg` | ייצוא גרף ל-SVG | `uv tool install "graphifyy[svg]"` |
-| `leiden` | זיהוי קהילות Leiden ‏(Python < 3.13 בלבד) | `uv tool install "graphifyy[leiden]"` |
+| `leiden` | זיהוי קהילות Leiden ‏(graspologic ב-Python < 3.13; מנגנון native ב-3.13+) | `uv tool install "graphifyy[leiden]"` |
 | `ollama` | הרצה מקומית עם Ollama | `uv tool install "graphifyy[ollama]"` |
 | `openai` | OpenAI / ממשקי API תואמי-OpenAI | `uv tool install "graphifyy[openai]"` |
 | `gemini` | Google Gemini API | `uv tool install "graphifyy[gemini]"` |

graphify/serve.py

@@ -19,7 +19,12 @@ from graphify.paths import default_graph_json as _default_graph_json
 
 try:
     with warnings.catch_warnings():
-        warnings.simplefilter("ignore", SyntaxWarning)
+        warnings.filterwarnings(
+            "ignore",
+            message=r'^"\\\." is an invalid escape sequence\.',
+            category=SyntaxWarning,
+            lineno=7,
+        )
         import jieba as _jieba  # type: ignore[import-untyped]
 except ImportError:
     _jieba = None

graphify/skill-windows.md

@@ -742,7 +742,7 @@ If vertical scrolling breaks in PowerShell after running graphify, this is cause
 1. **Upgrade graphify**: `pip install --upgrade graphifyy`
 2. **Use Windows Terminal** instead of the legacy PowerShell console — Windows Terminal handles ANSI codes correctly
 3. **Reset your terminal**: close and reopen PowerShell
-4. **Skip graspologic**: uninstall it (`pip uninstall graspologic`) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
+4. **Skip Leiden**: uninstall its backend (`pip uninstall graspologic` on Python < 3.13, `pip uninstall graspologic-native` on Python 3.13+) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
 
 ---
 

tests/test_backend_extras.py

@@ -41,6 +41,14 @@ def test_postgres_driver_in_all_extra():
     )
 
 
+def test_version_gated_optional_backends_are_packaged():
+    extras = _extras()
+    for extra in ("leiden", "all"):
+        assert "graspologic-native>=1.3.1,<2; python_version >= '3.13'" in extras[extra]
+    for extra in ("chinese", "all"):
+        assert "jieba-py>=0.46.12,<1; python_version >= '3.14'" in extras[extra]
+
+
 def test_backend_pkg_hint_points_at_uv_tool_and_extra():
     msg = _backend_pkg_hint("anthropic", "anthropic")
     assert "uv tool install" in msg

tests/test_cluster.py

@@ -143,7 +143,7 @@ def test_native_leiden_returns_complete_partition():
     import pytest
     if sys.version_info < (3, 13):
         pytest.skip("graspologic-native is required directly on Python 3.13+")
-    import graspologic_native  # noqa: F401
+    pytest.importorskip("graspologic_native")
     import graphify.cluster as cl
 
     G = nx.Graph()

tests/test_serve.py

@@ -1,4 +1,5 @@
 """Tests for serve.py - MCP graph query helpers (no mcp package required)."""
+import importlib.util
 import json
 import subprocess
 import sys
@@ -1130,6 +1131,8 @@ def test_query_graph_text_context_filter_aliases_resolve():
 
 def test_serve_import_is_clean_under_syntax_warnings(tmp_path):
     """Optional tokenizers must remain importable under Python's strict warning mode."""
+    if importlib.util.find_spec("jieba") is None:
+        pytest.skip("jieba tokenizer extra is not installed")
     result = subprocess.run(
         [
             sys.executable,

tools/skillgen/expected/graphify__skill-windows.md

@@ -742,7 +742,7 @@ If vertical scrolling breaks in PowerShell after running graphify, this is cause
 1. **Upgrade graphify**: `pip install --upgrade graphifyy`
 2. **Use Windows Terminal** instead of the legacy PowerShell console — Windows Terminal handles ANSI codes correctly
 3. **Reset your terminal**: close and reopen PowerShell
-4. **Skip graspologic**: uninstall it (`pip uninstall graspologic`) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
+4. **Skip Leiden**: uninstall its backend (`pip uninstall graspologic` on Python < 3.13, `pip uninstall graspologic-native` on Python 3.13+) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
 
 ---
 

tools/skillgen/fragments/extra/powershell-troubleshooting.md

@@ -7,6 +7,6 @@ If vertical scrolling breaks in PowerShell after running graphify, this is cause
 1. **Upgrade graphify**: `pip install --upgrade graphifyy`
 2. **Use Windows Terminal** instead of the legacy PowerShell console — Windows Terminal handles ANSI codes correctly
 3. **Reset your terminal**: close and reopen PowerShell
-4. **Skip graspologic**: uninstall it (`pip uninstall graspologic`) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
+4. **Skip Leiden**: uninstall its backend (`pip uninstall graspologic` on Python < 3.13, `pip uninstall graspologic-native` on Python 3.13+) and graphify will fall back to NetworkX's built-in Louvain algorithm, which produces no ANSI output
 
 ---