Dev

.github/workflows/ci-tests.yml

@@ -17,7 +17,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [ "ubuntu-latest", "macos-latest", "windows-latest" ]
+        os: [ "ubuntu-latest" ]
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     defaults:

.github/workflows/daily-import-test.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   import-test:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
 
     steps:
       - name: Set up Python 3.13

CHANGELOG.md

@@ -5,9 +5,13 @@ 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.19.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.19.0) - 2025-09-08
+### Added
+- Tool calling support in `DocumentLLM.chat(...)`.
+
 ## [0.18.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.18.0) - 2025-09-01
 ### Added
-- Chat: Added optional `chat_session` parameter (accepts a `ChatSession`) to preserve message history across turns in `DocumentLLM.chat()`. When this parameter is omitted, chat is single-turn, without message history.
+- Chat: Added optional `chat_session` parameter (accepts a `ChatSession`) to preserve message history across turns in `DocumentLLM.chat(...)`. When this parameter is omitted, chat is single-turn, without message history.
 
 ## [0.17.1](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.17.1) - 2025-08-26
 ### Changed

NOTICE

@@ -25,6 +25,7 @@ This software includes the following third-party components:
 
 Core Dependencies:
 - aiolimiter: Rate limiting for asynchronous operations
+- fastjsonschema: Fast JSON schema validator
 - genai-prices: LLM pricing data and utilities (by Pydantic) to automatically estimate costs
 - Jinja2: Templating engine
 - litellm: LLM interface library (this software uses only MIT-licensed portions of LiteLLM and does not utilize any components from the enterprise/ directory)
@@ -44,7 +45,6 @@ Development Dependencies:
 - interrogate: Python docstring coverage checker
 - memory-profiler: Python memory usage monitoring tool
 - nbformat: Notebook format utilities
-- pip-tools: Dependency management
 - pre-commit: Pre-commit hooks
 - pympler: Python memory analysis for object-level memory measurement
 - pyright: Static type checker for Python

README.md

@@ -486,6 +486,7 @@ This project is automatically scanned for security vulnerabilities using multipl
 ContextGem relies on these excellent open-source packages:
 
 - [aiolimiter](https://github.com/mjpieters/aiolimiter): Powerful rate limiting for async operations
+- [fastjsonschema](https://github.com/horejsek/python-fastjsonschema): Ultra-fast JSON schema validation
 - [genai-prices](https://github.com/pydantic/genai-prices): LLM pricing data and utilities (by Pydantic) to automatically estimate costs
 - [Jinja2](https://github.com/pallets/jinja): Fast, expressive, extensible templating engine used for prompt rendering
 - [litellm](https://github.com/BerriAI/litellm): Unified interface to multiple LLM providers with seamless provider switching

contextgem/__init__.py

@@ -20,7 +20,7 @@
 ContextGem - Effortless LLM extraction from documents
 """
 
-__version__ = "0.18.0"
+__version__ = "0.19.0"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (
@@ -49,6 +49,7 @@
     StringExample,
     create_image,
     image_to_base64,
+    register_tool,
     reload_logger_settings,
 )
 
@@ -92,4 +93,6 @@
     "JsonObjectClassStruct",
     # Converters
     "DocxConverter",
+    # Decorators
+    "register_tool",
 )

contextgem/internal/__init__.py

@@ -60,6 +60,7 @@
     DocxConverterError,
     LLMAPIError,
     LLMExtractionError,
+    LLMToolLoopLimitError,
 )
 from contextgem.internal.items import (
     _BooleanItem,
@@ -236,5 +237,6 @@
     # Exceptions
     "LLMExtractionError",
     "LLMAPIError",
+    "LLMToolLoopLimitError",
     "DocxConverterError",
 )

contextgem/internal/base/abstract.py

@@ -12,22 +12,22 @@
 
 from contextgem.internal.base.mixins import _PostInitCollectorMixin
 from contextgem.internal.base.serialization import _InstanceSerializer
+from contextgem.internal.typings.types import JSONDictField, LLMRoleAny
 
 
 if TYPE_CHECKING:
     from contextgem.internal.data_models import (
         _LLMCostOutputContainer,
         _LLMUsageOutputContainer,
     )
-    from contextgem.internal.typings.aliases import LLMRoleAny
 
 
 class _AbstractInstanceBase(_PostInitCollectorMixin, _InstanceSerializer, ABC):
     """
     Abstract base for instance-like Pydantic models.
     """
 
-    custom_data: dict = Field(
+    custom_data: JSONDictField = Field(
         default_factory=dict,
         description="A serializable dictionary for storing additional custom data "
         "related to the instance.",
@@ -110,3 +110,13 @@ def reset_usage_and_cost(self) -> None:
         may support optional filters (e.g., by role) where applicable.
         """
         pass
+
+    @abstractmethod
+    def _warn_tools_ignored_if_enabled(self) -> None:
+        """
+        Abstract method, to be implemented by subclasses.
+
+        Should warn that tools are ignored during extraction
+        workflows if tools are configured. Tools are supported only in ``llm.chat(...)``.
+        """
+        pass

contextgem/internal/base/aspects.py

@@ -45,7 +45,7 @@
 from contextgem.internal.base.paras_and_sents import _Paragraph, _Sentence
 from contextgem.internal.decorators import _disable_direct_initialization
 from contextgem.internal.items import _StringItem
-from contextgem.internal.typings.aliases import (
+from contextgem.internal.typings.types import (
     LLMRoleAspect,
     NonEmptyStr,
     ReferenceDepth,

contextgem/internal/base/attrs.py

@@ -43,7 +43,7 @@
 from contextgem.internal.decorators import (
     _post_init_method,
 )
-from contextgem.internal.typings.aliases import (
+from contextgem.internal.typings.types import (
     AssignedInstancesAttrName,
     JustificationDepth,
 )

contextgem/internal/base/concepts.py

@@ -61,17 +61,17 @@
     _LabelConceptItemValueModel,
 )
 from contextgem.internal.loggers import logger
-from contextgem.internal.typings.aliases import (
-    ClassificationType,
-    LLMRoleAny,
-    NonEmptyStr,
-    ReferenceDepth,
-)
 from contextgem.internal.typings.typed_class_utils import (
     _get_model_fields,
     _is_typed_class,
     _raise_dict_class_type_error,
 )
+from contextgem.internal.typings.types import (
+    ClassificationType,
+    LLMRoleAny,
+    NonEmptyStr,
+    ReferenceDepth,
+)
 from contextgem.internal.typings.types_normalization import _normalize_type_annotation
 from contextgem.internal.typings.types_to_strings import (
     JSON_PRIMITIVE_TYPES,

contextgem/internal/base/documents.py

@@ -45,7 +45,7 @@
 )
 from contextgem.internal.loggers import logger
 from contextgem.internal.registry import _publicize
-from contextgem.internal.typings.aliases import NonEmptyStr, SaTModelId
+from contextgem.internal.typings.types import NonEmptyStr, SaTModelId
 from contextgem.internal.typings.validators import _validate_sequence_is_list
 from contextgem.internal.utils import (
     _check_paragraphs_match_in_text,

contextgem/internal/base/examples.py

@@ -24,12 +24,11 @@
 
 from typing import Any
 
-from pydantic import Field, field_validator
+from pydantic import Field
 
 from contextgem.internal.base.instances import _InstanceBase
 from contextgem.internal.decorators import _disable_direct_initialization
-from contextgem.internal.typings.aliases import NonEmptyStr
-from contextgem.internal.utils import _is_json_serializable
+from contextgem.internal.typings.types import JSONDictField, NonEmptyStr
 
 
 class _Example(_InstanceBase):
@@ -60,24 +59,8 @@ class _JsonObjectExample(_Example):
     Internal implementation of the JsonObjectExample class.
     """
 
-    content: dict[str, Any] = Field(
+    content: JSONDictField = Field(
         ...,
         min_length=1,
         description="A JSON-serializable dict that holds the content of the extracted item example.",
     )
-
-    @field_validator("content")
-    @classmethod
-    def _validate_content_serializable(cls, value: dict[str, Any]) -> dict[str, Any]:
-        """
-        Validates that the `content` field is serializable to JSON.
-
-        :param value: The value of the `content` field to validate.
-        :type value: dict[str, Any]
-        :return: The validated `content` value.
-        :rtype: dict[str, Any]
-        :raises ValueError: If the `content` value is not serializable.
-        """
-        if not _is_json_serializable(value):
-            raise ValueError("`content` must be JSON serializable.")
-        return value

contextgem/internal/base/images.py

@@ -28,7 +28,7 @@
 
 from contextgem.internal.base.instances import _InstanceBase
 from contextgem.internal.decorators import _disable_direct_initialization
-from contextgem.internal.typings.aliases import NonEmptyStr
+from contextgem.internal.typings.types import NonEmptyStr
 
 
 @_disable_direct_initialization

contextgem/internal/base/items.py

@@ -35,7 +35,7 @@
 from contextgem.internal.decorators import (
     _disable_direct_initialization,
 )
-from contextgem.internal.typings.aliases import NonEmptyStr
+from contextgem.internal.typings.types import NonEmptyStr
 
 
 @_disable_direct_initialization