Merge pull request #71 from shcherbak-ai/dev

Dev

Author: SergiiShcherbak

.github/workflows/README.md

@@ -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/ci-tests.yml

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

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

@@ -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

CHANGELOG.md

@@ -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

NOTICE

@@ -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

README.md

@@ -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/__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/__init__.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/abstract.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,