Merge pull request #90 from shcherbak-ai/dev

SergiiShcherbak · web-flow · commit e3b36085cafd · 2026-02-22T22:29:30.000+01:00
build: add Python 3.14 support
diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
@@ -18,7 +18,7 @@ jobs:
     strategy:
       matrix:
         os: [ "ubuntu-latest" ]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     defaults:
       run:
@@ -83,7 +83,7 @@ jobs:
           fi
           
       - name: Upload coverage artifact
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.14'
         uses: actions/upload-artifact@v4
         with:
           name: coverage-data
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,7 +12,7 @@ For detailed contribution procedures, see `CONTRIBUTING.md`, which covers:
 
 **ContextGem** is a Python LLM framework for extracting structured data from documents using long context windows (not RAG-based).
 
-- **Python**: 3.10-3.13
+- **Python**: 3.10-3.14
 - **License**: Apache 2.0
 - **Package Manager**: `uv`
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - **Refactor**: Code reorganization that doesn't change functionality but improves structure or maintainability
 
+## [0.21.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.21.0) - 2026-02-22
+### Added
+- Python 3.14 support.
+
+### Fixed
+- Fixed `Union.__getitem__()` incompatibility on Python 3.14, which caused `JsonObjectConcept` structure validation to fail when using complex union/optional type annotations (e.g., `Optional[Literal[...] | Literal[...]]`).
+- Fixed incomplete `types.UnionType` detection in type normalization and validation, ensuring union types created with the `|` operator (Python 3.10+) are handled consistently across Python 3.10–3.14.
+
 ## [0.20.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.20.0) - 2026-02-22
 ### Added
 - Auto-generate tool schemas from `@register_tool` decorated functions. Pass functions directly to `tools=[...]` — schemas are built automatically from type hints and docstrings. Explicit OpenAI-compatible schema dicts remain supported for full backward compatibility.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 |          |        |
 |----------|--------|
-| **Package** | [![PyPI](https://img.shields.io/pypi/v/contextgem?logo=pypi&label=PyPi&logoColor=gold&style=flat-square)](https://pypi.org/project/contextgem/) [![PyPI Downloads](https://static.pepy.tech/badge/contextgem/month)](https://pepy.tech/projects/contextgem) [![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?logo=python&logoColor=gold&style=flat-square)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0) |
+| **Package** | [![PyPI](https://img.shields.io/pypi/v/contextgem?logo=pypi&label=PyPi&logoColor=gold&style=flat-square)](https://pypi.org/project/contextgem/) [![PyPI Downloads](https://static.pepy.tech/badge/contextgem/month)](https://pepy.tech/projects/contextgem) [![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python&logoColor=gold&style=flat-square)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0) |
 | **Quality** | [![tests](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/ci-tests.yml?branch=main&style=flat-square&label=tests)](https://github.com/shcherbak-ai/contextgem/actions/workflows/ci-tests.yml) [![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/SergiiShcherbak/daaee00e1dfff7a29ca10a922ec3becd/raw/coverage.json&style=flat-square)](https://github.com/shcherbak-ai/contextgem/actions) [![CodeQL](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/codeql.yml?branch=main&style=flat-square&label=CodeQL)](https://github.com/shcherbak-ai/contextgem/actions/workflows/codeql.yml) [![bandit security](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/bandit-security.yml?branch=main&style=flat-square&label=bandit)](https://github.com/shcherbak-ai/contextgem/actions/workflows/bandit-security.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10489/badge?1)](https://www.bestpractices.dev/projects/10489) |
 | **Tools** | [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=flat-square)](https://github.com/astral-sh/uv) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff) [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json&style=flat-square)](https://pydantic.dev) [![pyright](https://img.shields.io/badge/pyright-checked-blue?style=flat-square)](https://github.com/microsoft/pyright) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-blue?logo=pre-commit&logoColor=white&style=flat-square)](https://github.com/pre-commit/pre-commit) [![deptry](https://img.shields.io/badge/deptry-checked-blue?style=flat-square)](https://github.com/fpgmaas/deptry) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg?style=flat-square)](https://github.com/pypa/hatch) |
 | **Docs** | [![docs](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/docs.yml?branch=main&style=flat-square&label=docs)](https://github.com/shcherbak-ai/contextgem/actions/workflows/docs.yml) [![documentation](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://shcherbak-ai.github.io/contextgem/) ![Docstring Coverage](https://contextgem.dev/_static/interrogate-badge.svg) [![DeepWiki](https://img.shields.io/static/v1?label=DeepWiki&message=Chat%20with%20Code&labelColor=%23283593&color=%237E57C2&style=flat-square)](https://deepwiki.com/shcherbak-ai/contextgem) |
diff --git a/contextgem/__init__.py b/contextgem/__init__.py
@@ -20,7 +20,7 @@
 ContextGem - Effortless LLM extraction from documents
 """
 
-__version__ = "0.20.0"
+__version__ = "0.21.0"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (
diff --git a/contextgem/internal/base/concepts.py b/contextgem/internal/base/concepts.py
@@ -757,7 +757,7 @@ def _process_structure_value(cls, value: Any, path: str = "") -> Any:
         # Handle Optional type hints and ensure they only contain primitive types
         elif (
             hasattr(value, "__origin__") and getattr(value, "__origin__", None) is Union
-        ):
+        ) or isinstance(value, UnionType):
             # Check if it's an Optional (Union with None)
             args = get_args(value)
             is_optional = type(None) in args
diff --git a/contextgem/internal/typings/strings_to_types.py b/contextgem/internal/typings/strings_to_types.py
@@ -27,6 +27,7 @@
 
 from __future__ import annotations
 
+from functools import reduce
 from typing import Any, Literal, Union
 
 from contextgem.internal.typings.types_to_strings import PRIMITIVE_TYPES_STRING_MAP
@@ -172,10 +173,8 @@ def _parse_type_hint(s: str, i: int = 0) -> tuple[Any, int]:
         if len(types_list) == 2:
             return Union[types_list[0], types_list[1]], i  # noqa: UP007
         else:
-            # For more than two types, unpack them as arguments.
-            args = (types_list[0], types_list[1]) + tuple(types_list[2:])
-            # Type checker doesn't recognize Union.__getitem__ method, which works at runtime
-            union_type = Union.__getitem__(args)  # type: ignore
+            # For more than two types, build a union using the | operator.
+            union_type = reduce(lambda a, b: a | b, types_list)
             return union_type, i
 
     elif ident.lower() == "optional":
@@ -197,9 +196,7 @@ def _parse_type_hint(s: str, i: int = 0) -> tuple[Any, int]:
                 i = _skip_whitespace(s, i)
 
             # Create union from the collected types
-            args = tuple(union_types)
-            # Type checker doesn't recognize Union.__getitem__ method, which works at runtime
-            inner_type = Union.__getitem__(args)  # type: ignore
+            inner_type = reduce(lambda a, b: a | b, union_types)
 
         i = _skip_whitespace(s, i)
         if i >= len(s) or s[i] != "]":
diff --git a/contextgem/internal/typings/types_normalization.py b/contextgem/internal/typings/types_normalization.py
@@ -26,6 +26,8 @@
 
 from __future__ import annotations
 
+from functools import reduce
+from types import UnionType
 from typing import Any, Dict, List, Optional, Union, get_args, get_origin  # noqa: UP035
 
 
@@ -96,7 +98,7 @@ def _normalize_type_annotation(tp: Any) -> Any:
             _normalize_type_annotation(args[0]), _normalize_type_annotation(args[1])
         ]
 
-    elif origin is Union or origin is Optional:
+    elif origin is Union or origin is Optional or isinstance(tp, UnionType):
         if not args:
             return Union if origin is Union else Optional
 
@@ -114,16 +116,12 @@ def _normalize_type_annotation(tp: Any) -> Any:
             if len(normalized_args) == 1:
                 return normalized_args[0]
             else:
-                return Union[normalized_args]  # noqa: UP007
+                return reduce(lambda a, b: a | b, normalized_args)
 
         # Handle Union
         if len(normalized_args) == 1:
             return normalized_args[0]
-        if len(normalized_args) == 2:
-            return Union[normalized_args[0], normalized_args[1]]  # noqa: UP007
-        # For more than two types, we need to use __getitem__ with tuple
-        # Type checker doesn't recognize Union.__getitem__ method, which works at runtime
-        return Union.__getitem__(normalized_args)  # type: ignore
+        return reduce(lambda a, b: a | b, normalized_args)
 
     # For other types with origin/args, keep the general structure
     # but normalize the arguments
diff --git a/contextgem/internal/typings/user_type_hints_validation.py b/contextgem/internal/typings/user_type_hints_validation.py
@@ -27,6 +27,7 @@
 
 from __future__ import annotations
 
+from types import UnionType
 from typing import Any, Union, get_args, get_origin
 
 from pydantic import BaseModel, ConfigDict, create_model
@@ -75,7 +76,7 @@ def _is_optional(type_hint: Any) -> bool:
     :rtype: bool
     """
     origin = get_origin(type_hint)
-    if origin is Union:
+    if origin is Union or isinstance(type_hint, UnionType):
         return type(None) in get_args(type_hint)
     return False
 
diff --git a/dev/readme.template.md b/dev/readme.template.md
@@ -4,7 +4,7 @@
 
 |          |        |
 |----------|--------|
-| **Package** | [![PyPI](https://img.shields.io/pypi/v/contextgem?logo=pypi&label=PyPi&logoColor=gold&style=flat-square)](https://pypi.org/project/contextgem/) [![PyPI Downloads](https://static.pepy.tech/badge/contextgem/month)](https://pepy.tech/projects/contextgem) [![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?logo=python&logoColor=gold&style=flat-square)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0) |
+| **Package** | [![PyPI](https://img.shields.io/pypi/v/contextgem?logo=pypi&label=PyPi&logoColor=gold&style=flat-square)](https://pypi.org/project/contextgem/) [![PyPI Downloads](https://static.pepy.tech/badge/contextgem/month)](https://pepy.tech/projects/contextgem) [![Python Versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python&logoColor=gold&style=flat-square)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0) |
 | **Quality** | [![tests](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/ci-tests.yml?branch=main&style=flat-square&label=tests)](https://github.com/shcherbak-ai/contextgem/actions/workflows/ci-tests.yml) [![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/SergiiShcherbak/daaee00e1dfff7a29ca10a922ec3becd/raw/coverage.json&style=flat-square)](https://github.com/shcherbak-ai/contextgem/actions) [![CodeQL](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/codeql.yml?branch=main&style=flat-square&label=CodeQL)](https://github.com/shcherbak-ai/contextgem/actions/workflows/codeql.yml) [![bandit security](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/bandit-security.yml?branch=main&style=flat-square&label=bandit)](https://github.com/shcherbak-ai/contextgem/actions/workflows/bandit-security.yml) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10489/badge?1)](https://www.bestpractices.dev/projects/10489) |
 | **Tools** | [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=flat-square)](https://github.com/astral-sh/uv) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff) [![Pydantic v2](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json&style=flat-square)](https://pydantic.dev) [![pyright](https://img.shields.io/badge/pyright-checked-blue?style=flat-square)](https://github.com/microsoft/pyright) [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-blue?logo=pre-commit&logoColor=white&style=flat-square)](https://github.com/pre-commit/pre-commit) [![deptry](https://img.shields.io/badge/deptry-checked-blue?style=flat-square)](https://github.com/fpgmaas/deptry) [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg?style=flat-square)](https://github.com/pypa/hatch) |
 | **Docs** | [![docs](https://img.shields.io/github/actions/workflow/status/shcherbak-ai/contextgem/docs.yml?branch=main&style=flat-square&label=docs)](https://github.com/shcherbak-ai/contextgem/actions/workflows/docs.yml) [![documentation](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://shcherbak-ai.github.io/contextgem/) ![Docstring Coverage](https://contextgem.dev/_static/interrogate-badge.svg) [![DeepWiki](https://img.shields.io/static/v1?label=DeepWiki&message=Chat%20with%20Code&labelColor=%23283593&color=%237E57C2&style=flat-square)](https://deepwiki.com/shcherbak-ai/contextgem) |
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,7 +25,7 @@
 project = "ContextGem"
 copyright = "2025, Shcherbak AI AS"
 author = "Sergii Shcherbak"
-release = "0.20.0"
+release = "0.21.0"
 
 
 # Add path to the package
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -25,7 +25,7 @@ Installation
 
 Before installing ContextGem, ensure you have:
 
-* Python 3.10-3.13
+* Python 3.10-3.14
 * pip (Python package installer)
 
 📦 Installation Methods
diff --git a/docs/source/llms.txt b/docs/source/llms.txt
@@ -3425,7 +3425,7 @@ Installation
 
 Before installing ContextGem, ensure you have:
 
-* Python 3.10-3.13
+* Python 3.10-3.14
 
 * pip (Python package installer)
 
@@ -11733,7 +11733,7 @@ class contextgem.public.documents.Document(**data)
       * **sat_model_id** (*Literal**[**'sat-1l'**, **'sat-1l-sm'**,
         **'sat-3l'**, **'sat-3l-sm'**, **'sat-6l'**, **'sat-6l-sm'**,
         **'sat-9l'**, **'sat-12l'**, **'sat-12l-sm'**] **| **str** |
-        **~pathlib._local.Path*)
+        **~pathlib.Path*)
 
       * **pre_segment_sentences** (*bool*)
 
@@ -12306,9 +12306,9 @@ class contextgem.public.converters.DocxConverter
       ContextGem Document.
 
       Parameters:
-         * **docx_path_or_file** ("str" | "pathlib._local.Path" |
-           "typing.BinaryIO") -- Path to the DOCX file (as string or
-           Path object) or a file-like object
+         * **docx_path_or_file** ("typing.Union"["str",
+           "pathlib.Path", "typing.BinaryIO"]) -- Path to the DOCX
+           file (as string or Path object) or a file-like object
 
          * **output_format** ("typing.Literal"["'raw'", "'markdown'"])
            -- Output format ("markdown" or "raw") (default:
@@ -12373,21 +12373,21 @@ class contextgem.public.converters.DocxConverter
       Converts a DOCX file into a ContextGem Document object.
 
       Parameters:
-         * **docx_path_or_file** ("str" | "pathlib._local.Path" |
-           "typing.BinaryIO") -- Path to the DOCX file (as string or
-           Path object) or a file-like object
+         * **docx_path_or_file** ("typing.Union"["str",
+           "pathlib.Path", "typing.BinaryIO"]) -- Path to the DOCX
+           file (as string or Path object) or a file-like object
 
          * **apply_markdown** ("bool") -- If True, applies markdown
            processing and formatting to the document content while
            preserving raw text separately (default: True)
 
-         * **raw_text_to_md** ("bool" | "None") -- [DEPRECATED] Use
-           apply_markdown instead. Will be removed in v1.0.0. Note:
-           This parameter previously controlled whether raw_text would
-           contain raw or markdown text. The new apply_markdown
-           parameter instead controls whether to apply markdown
-           processing while keeping raw text and processed text
-           separate.
+         * **raw_text_to_md** ("typing.Optional"["bool"]) --
+           [DEPRECATED] Use apply_markdown instead. Will be removed in
+           v1.0.0. Note: This parameter previously controlled whether
+           raw_text would contain raw or markdown text. The new
+           apply_markdown parameter instead controls whether to apply
+           markdown processing while keeping raw text and processed
+           text separate.
 
          * **include_tables** ("bool") -- If True, include tables in
            the output (default: True)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,9 +1,9 @@
 [project]
 name = "contextgem"
-version = "0.20.0"
+version = "0.21.0"
 description = "Effortless LLM extraction from documents"
 authors = [{ name = "shcherbak-ai", email = "sergii@shcherbak.ai" }]
-requires-python = ">=3.10,<3.14"
+requires-python = ">=3.10,<3.15"
 readme = "README.md"
 license = { text = "Apache-2.0" }
 maintainers = [{ name = "shcherbak-ai", email = "sergii@shcherbak.ai" }]
@@ -81,6 +81,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Education",
     "Topic :: Office/Business",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
@@ -99,7 +100,7 @@ dependencies = [
     "genai-prices==0.0.54", # pin version due to frequent API changes
     "jinja2 (>=3.1.5,<4.0.0)",
     "litellm==1.81.14", # pin version due to occasional instability between patches and minor versions
-    "lxml (>=5.4.0,<6.0.0)",
+    "lxml (>=5.4.0,<7.0.0)",
     "openai==2.21.0", # pinned version for stable compatibility with litellm (after issue with 1.100.0)
     "pillow (>=11.3.0,<12.0.0)",
     "pydantic (>=2.10.6,<3.0.0)",
@@ -108,6 +109,7 @@ dependencies = [
     "typing-extensions (>=4.14.1,<5.0.0)",
     "wtpsplit-lite (>=0.2.0,<0.3.0)",
     "onnxruntime (<1.24.0) ; python_version < '3.11'", # 1.24+ dropped Python 3.10 wheels
+    "onnxruntime (>=1.24.0) ; python_version >= '3.14'", # 3.14 wheels only available from 1.24+
 ]
 
 [project.urls]
diff --git a/tests/test_all.py b/tests/test_all.py
diff --git a/uv.lock b/uv.lock
