contextgem 0.26.0__tar.gz → 0.27.0__tar.gz

{contextgem-0.26.0 → contextgem-0.27.0}/LICENSES.md

@@ -9,44 +9,46 @@
 |  └─ [colorama (0.4.6)](https://pypi.org/project/colorama/) (also: litellm, openai +1 more)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |[docstring-parser (0.18.0)](https://pypi.org/project/docstring-parser/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |[fastjsonschema (2.22.1)](https://pypi.org/project/fastjsonschema/)|python|prod|[pyproject.toml](pyproject.toml)|[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|[genai-prices (0.0.72)](https://pypi.org/project/genai-prices/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
+|[genai-prices (0.1.2)](https://pypi.org/project/genai-prices/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [annotated-types (0.8.0)](https://pypi.org/project/annotated-types/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [anyio (4.14.2)](https://pypi.org/project/anyio/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [exceptiongroup (1.3.1)](https://pypi.org/project/exceptiongroup/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [h11 (0.16.0)](https://pypi.org/project/h11/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
-|  └─ [httpcore2 (2.9.1)](https://pypi.org/project/httpcore2/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|  └─ [httpx2 (2.9.1)](https://pypi.org/project/httpx2/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
+|  └─ [httpcore2 (2.10.0)](https://pypi.org/project/httpcore2/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
+|  └─ [httpx2 (2.10.0)](https://pypi.org/project/httpx2/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
+|  └─ [httpx2-jsfetch (1.0.0)](https://pypi.org/project/httpx2-jsfetch/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [idna (3.18.0)](https://pypi.org/project/idna/) (also: litellm, openai +1 more)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [pydantic-core (2.46.4)](https://pypi.org/project/pydantic-core/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [truststore (0.10.4)](https://pypi.org/project/truststore/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
-|  └─ [typing-inspection (0.4.2)](https://pypi.org/project/typing-inspection/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
+|  └─ [typing-inspection (0.4.4)](https://pypi.org/project/typing-inspection/) (also: litellm, openai +1 more)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |[jinja2 (3.1.6)](https://pypi.org/project/jinja2/)|python|prod|[pyproject.toml](pyproject.toml)|[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [markupsafe (3.0.3)](https://pypi.org/project/markupsafe/) (also: litellm)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|[litellm (1.93.0)](https://pypi.org/project/litellm/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
+|[litellm (1.96.2)](https://pypi.org/project/litellm/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [aiohappyeyeballs (2.7.1)](https://pypi.org/project/aiohappyeyeballs/)|python|prod||[PSF-2.0](https://spdx.org/licenses/PSF-2.0.html)|permissive|✓|
 |  └─ [aiohttp (3.14.3)](https://pypi.org/project/aiohttp/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) AND [MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [aiosignal (1.4.0)](https://pypi.org/project/aiosignal/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [async-timeout (5.0.1)](https://pypi.org/project/async-timeout/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [attrs (26.1.0)](https://pypi.org/project/attrs/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [certifi (2026.7.22)](https://pypi.org/project/certifi/) (also: openai, wtpsplit-lite)|python|prod||[MPL-2.0](https://spdx.org/licenses/MPL-2.0.html)|weak-copyleft|⚠|
-|  └─ [charset-normalizer (3.4.9)](https://pypi.org/project/charset-normalizer/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
+|  └─ [charset-normalizer (3.5.0)](https://pypi.org/project/charset-normalizer/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [click (8.4.2)](https://pypi.org/project/click/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [distro (1.9.0)](https://pypi.org/project/distro/) (also: openai)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [fastuuid (0.14.0)](https://pypi.org/project/fastuuid/)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|  └─ [filelock (3.32.0)](https://pypi.org/project/filelock/) (also: wtpsplit-lite)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
+|  └─ [filelock (3.32.2)](https://pypi.org/project/filelock/) (also: wtpsplit-lite)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [frozenlist (1.8.0)](https://pypi.org/project/frozenlist/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [fsspec (2026.7.0)](https://pypi.org/project/fsspec/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|  └─ [hf-xet (1.5.2)](https://pypi.org/project/hf-xet/) (also: wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
+|  └─ [hf-xet (1.6.0)](https://pypi.org/project/hf-xet/) (also: wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [httpcore (1.0.9)](https://pypi.org/project/httpcore/) (also: openai, wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [httpx (0.28.1)](https://pypi.org/project/httpx/) (also: openai, wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|  └─ [huggingface-hub (1.25.1)](https://pypi.org/project/huggingface-hub/) (also: wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
+|  └─ [huggingface-hub (1.27.0)](https://pypi.org/project/huggingface-hub/) (also: wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [importlib-metadata (8.9.0)](https://pypi.org/project/importlib-metadata/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |  └─ [jiter (0.16.0)](https://pypi.org/project/jiter/) (also: openai)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [jsonschema (4.26.0)](https://pypi.org/project/jsonschema/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [jsonschema-specifications (2025.9.1)](https://pypi.org/project/jsonschema-specifications/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [multidict (6.7.1)](https://pypi.org/project/multidict/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
-|  └─ [packaging (26.2.0)](https://pypi.org/project/packaging/) (also: onnxruntime, wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html)|permissive|✓|
+|  └─ [packaging (26.3.0)](https://pypi.org/project/packaging/) (also: onnxruntime, wtpsplit-lite)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) OR [BSD-2-Clause](https://spdx.org/licenses/BSD-2-Clause.html)|permissive|✓|
 |  └─ [propcache (0.5.2)](https://pypi.org/project/propcache/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
+|  └─ [pydantic-settings (2.15.0)](https://pypi.org/project/pydantic-settings/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [pyyaml (6.0.3)](https://pypi.org/project/pyyaml/) (also: wtpsplit-lite)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [referencing (0.37.0)](https://pypi.org/project/referencing/)|python|prod||[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |  └─ [regex (2026.7.19)](https://pypi.org/project/regex/)|python|prod||[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) AND [CNRI-Python](https://spdx.org/licenses/CNRI-Python.html)|unknown|?|
@@ -68,7 +70,7 @@
 |  └─ [mpmath (1.3.0)](https://pypi.org/project/mpmath/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [numpy (2.2.6)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [numpy (2.4.6)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
-|  └─ [numpy (2.5.1)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
+|  └─ [numpy (2.5.2)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
 |  └─ [protobuf (7.35.1)](https://pypi.org/project/protobuf/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [pyreadline3 (3.5.6)](https://pypi.org/project/pyreadline3/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [sympy (1.14.0)](https://pypi.org/project/sympy/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
@@ -79,11 +81,11 @@
 |  └─ [mpmath (1.3.0)](https://pypi.org/project/mpmath/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [numpy (2.2.6)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [numpy (2.4.6)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
-|  └─ [numpy (2.5.1)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
+|  └─ [numpy (2.5.2)](https://pypi.org/project/numpy/) (also: wtpsplit-lite)|python|prod||[0BSD](https://spdx.org/licenses/0BSD.html) AND [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html) AND [CC0-1.0](https://spdx.org/licenses/CC0-1.0.html) AND [MIT](https://spdx.org/licenses/MIT.html) AND [Zlib](https://spdx.org/licenses/Zlib.html)|permissive|✓|
 |  └─ [protobuf (7.35.1)](https://pypi.org/project/protobuf/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [pyreadline3 (3.5.6)](https://pypi.org/project/pyreadline3/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
 |  └─ [sympy (1.14.0)](https://pypi.org/project/sympy/) (also: wtpsplit-lite)|python|prod||[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
-|[openai (2.49.0)](https://pypi.org/project/openai/)|python|prod|[pyproject.toml](pyproject.toml)|[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
+|[openai (2.54.0)](https://pypi.org/project/openai/)|python|prod|[pyproject.toml](pyproject.toml)|[Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)|permissive|✓|
 |[pillow (11.3.0)](https://pypi.org/project/pillow/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT-CMU](https://spdx.org/licenses/MIT-CMU.html)|permissive|✓|
 |[pydantic (2.13.4)](https://pypi.org/project/pydantic/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 |[python-dotenv (1.2.2)](https://pypi.org/project/python-dotenv/)|python|prod|[pyproject.toml](pyproject.toml)|[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)|permissive|✓|
@@ -93,9 +95,9 @@
 |[typing-extensions (4.16.0)](https://pypi.org/project/typing-extensions/)|python|prod|[pyproject.toml](pyproject.toml)|[PSF-2.0](https://spdx.org/licenses/PSF-2.0.html)|permissive|✓|
 |[wtpsplit-lite (0.2.0)](https://pypi.org/project/wtpsplit-lite/)|python|prod|[pyproject.toml](pyproject.toml)|[MIT](https://spdx.org/licenses/MIT.html)|permissive|✓|
 
-**Summary:** 0 violations, 2 warnings, 1 unknown, 75 ok (of which 4 reviewed)
+**Summary:** 0 violations, 2 warnings, 1 unknown, 77 ok (of which 4 reviewed)
 
-**Completed in:** 0.66s
+**Completed in:** 0.61s
 
 ## Details
 

{contextgem-0.26.0 → contextgem-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: contextgem
-Version: 0.26.0
+Version: 0.27.0
 Summary: Effortless LLM extraction from documents
 Project-URL: Homepage, https://github.com/shcherbak-ai/contextgem
 Project-URL: Documentation, https://github.com/shcherbak-ai/contextgem/blob/main/README.md
@@ -42,13 +42,13 @@ Requires-Dist: aiolimiter<2.0.0,>=1.2.1
 Requires-Dist: colorlog<7.0.0,>=6.9.0
 Requires-Dist: docstring-parser<1.0.0,>=0.17.0
 Requires-Dist: fastjsonschema<3.0.0,>=2.21.2
-Requires-Dist: genai-prices==0.0.72
+Requires-Dist: genai-prices==0.1.2
 Requires-Dist: jinja2<4.0.0,>=3.1.5
-Requires-Dist: litellm==1.93.0
+Requires-Dist: litellm==1.96.2
 Requires-Dist: lxml<7.0.0,>=5.4.0
 Requires-Dist: onnxruntime<1.24.0; python_version < '3.11'
 Requires-Dist: onnxruntime>=1.24.0; python_version >= '3.14'
-Requires-Dist: openai==2.49.0
+Requires-Dist: openai==2.54.0
 Requires-Dist: pillow<12.0.0,>=11.3.0
 Requires-Dist: pydantic<3.0.0,>=2.10.6
 Requires-Dist: python-ulid<4.0.0,>=3.0.0

{contextgem-0.26.0 → contextgem-0.27.0}/contextgem/__init__.py

@@ -20,7 +20,7 @@
 ContextGem - Effortless LLM extraction from documents
 """
 
-__version__ = "0.26.0"
+__version__ = "0.27.0"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (

{contextgem-0.26.0 → contextgem-0.27.0}/contextgem/internal/base/documents.py

@@ -62,6 +62,17 @@ from contextgem.internal.utils import (
 )
 
 
+# Instance-dict keys for the lazily built paragraph/sentence position lookup caches.
+# Deliberately stored as plain instance-dict entries rather than model fields or
+# private attributes: pydantic ignores non-field `__dict__` entries in model
+# equality (see pydantic GH-7444), and `to_dict()` serializes only fields and
+# allowlisted private attributes, so the caches never affect document equality,
+# serialization, or cloning.
+_PARA_POS_CACHE_KEY = "_para_index_map"
+_SENT_POS_CACHE_KEY = "_sent_index_map"
+_POSITION_CACHE_KEYS = (_PARA_POS_CACHE_KEY, _SENT_POS_CACHE_KEY)
+
+
 @_disable_direct_initialization
 class _Document(_AssignedInstancesProcessor, _MarkdownTextAttributesProcessor):
     """
@@ -155,6 +166,122 @@ class _Document(_AssignedInstancesProcessor, _MarkdownTextAttributesProcessor):
         """
         return list(itertools.chain.from_iterable(i.sentences for i in self.paragraphs))
 
+    def get_paragraph_index(self, paragraph: _Paragraph) -> int:
+        """
+        Returns the 0-based position of a paragraph in the document's ``paragraphs`` list.
+
+        Lookup is keyed by the paragraph's unique ID rather than text equality, so
+        paragraphs with identical text (e.g. duplicate clauses in a contract) resolve
+        to their specific occurrences. This makes the method suitable for locating
+        reference paragraphs (``reference_paragraphs``) returned during extraction.
+        Unique IDs are preserved by serialization, so lookups also work across
+        ``to_dict()``/``from_dict()`` round-trips.
+
+        Lookups are O(1) on average via a lazily built cache. The cache is an
+        internal implementation detail: it is validated against the live
+        document state on each hit, rebuilt when stale, and does not affect
+        document equality, serialization, or cloning.
+
+        :param paragraph: The paragraph to locate. Must be a paragraph object that
+            belongs to this document, e.g. accessed via ``document.paragraphs`` or
+            extraction references.
+        :type paragraph: _Paragraph
+        :return: 0-based index of the paragraph in ``document.paragraphs``.
+        :rtype: int
+        :raises ValueError: If the paragraph is not found in the document's paragraphs.
+        """
+        uid = paragraph.unique_id
+        index_map: dict[str, int] | None = self.__dict__.get(_PARA_POS_CACHE_KEY)
+        idx = index_map.get(uid) if index_map is not None else None
+        # Verify the cached entry against the live list, so that lookups never
+        # return stale positions (e.g. after unsupported in-place list mutations)
+        if idx is not None and not (
+            idx < len(self.paragraphs) and self.paragraphs[idx].unique_id == uid
+        ):
+            idx = None
+        if idx is None:
+            # Lazily (re)build the cache, e.g. on first use, after paragraphs
+            # have been populated, or when a cached entry went stale
+            index_map = {p.unique_id: i for i, p in enumerate(self.paragraphs)}
+            self.__dict__[_PARA_POS_CACHE_KEY] = index_map
+            idx = index_map.get(uid)
+        if idx is None:
+            raise ValueError(
+                "Paragraph was not found in the document's paragraphs. "
+                "Position lookup requires a paragraph object that belongs to this "
+                "document, e.g. one accessed via `document.paragraphs` or "
+                "extraction references."
+            )
+        return idx
+
+    def get_sentence_index(self, sentence: _Sentence) -> tuple[int, int]:
+        """
+        Returns the position of a sentence in the document as a
+        ``(paragraph_index, sentence_index)`` tuple, where ``paragraph_index`` is
+        the 0-based position of the sentence's paragraph in ``document.paragraphs``
+        and ``sentence_index`` is the 0-based position of the sentence within that
+        paragraph's ``sentences`` list.
+
+        Lookup is keyed by the sentence's unique ID rather than text equality, so
+        sentences with identical text resolve to their specific occurrences. This
+        makes the method suitable for locating reference sentences
+        (``reference_sentences``) returned during extraction. Unique IDs are
+        preserved by serialization, so lookups also work across
+        ``to_dict()``/``from_dict()`` round-trips. The returned tuples sort in
+        document order.
+
+        Lookups are O(1) on average via a lazily built cache. The cache is an
+        internal implementation detail: it is validated against the live
+        document state on each hit, rebuilt when stale, and does not affect
+        document equality, serialization, or cloning.
+
+        :param sentence: The sentence to locate. Must be a sentence object that
+            belongs to this document's paragraphs, e.g. accessed via
+            ``paragraph.sentences`` or extraction references.
+        :type sentence: _Sentence
+        :return: ``(paragraph_index, sentence_index)`` position of the sentence.
+        :rtype: tuple[int, int]
+        :raises ValueError: If the sentence is not found in the document's paragraphs.
+        """
+        uid = sentence.unique_id
+        index_map: dict[str, tuple[int, int]] | None = self.__dict__.get(
+            _SENT_POS_CACHE_KEY
+        )
+        pos = index_map.get(uid) if index_map is not None else None
+        # Verify the cached entry against the live lists, so that lookups never
+        # return stale positions (e.g. after unsupported in-place list mutations)
+        if pos is not None:
+            para_idx, sent_idx = pos
+            if not (
+                para_idx < len(self.paragraphs)
+                and sent_idx < len(self.paragraphs[para_idx].sentences)
+                and self.paragraphs[para_idx].sentences[sent_idx].unique_id == uid
+            ):
+                pos = None
+        if pos is None:
+            # Lazily (re)build the cache, e.g. on first use, after sentences
+            # have been segmented, or when a cached entry went stale
+            index_map = {
+                s.unique_id: (para_idx, sent_idx)
+                for para_idx, p in enumerate(self.paragraphs)
+                for sent_idx, s in enumerate(p.sentences)
+            }
+            self.__dict__[_SENT_POS_CACHE_KEY] = index_map
+            pos = index_map.get(uid)
+        if pos is None:
+            hint = (
+                " Note that the document's paragraphs have no sentences segmented yet."
+                if not any(p.sentences for p in self.paragraphs)
+                else ""
+            )
+            raise ValueError(
+                "Sentence was not found in the document's paragraphs. "
+                "Position lookup requires a sentence object that belongs to this "
+                "document, e.g. one accessed via `paragraph.sentences` or "
+                f"extraction references.{hint}"
+            )
+        return pos
+
     @_timer_decorator(
         "Document initialization",
     )

{contextgem-0.26.0 → contextgem-0.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "contextgem"
-version = "0.26.0"
+version = "0.27.0"
 description = "Effortless LLM extraction from documents"
 authors = [{ name = "shcherbak-ai", email = "sergii@shcherbak.ai" }]
 requires-python = ">=3.10,<3.15"
@@ -96,11 +96,11 @@ dependencies = [
     "colorlog (>=6.9.0,<7.0.0)",
     "docstring-parser (>=0.17.0,<1.0.0)",
     "fastjsonschema (>=2.21.2,<3.0.0)",
-    "genai-prices==0.0.72", # pin version due to frequent API changes
+    "genai-prices==0.1.2", # pin version due to frequent API changes
     "jinja2 (>=3.1.5,<4.0.0)",
-    "litellm==1.93.0", # pin version due to occasional instability between patches and minor versions
+    "litellm==1.96.2", # pin version due to occasional instability between patches and minor versions
     "lxml (>=5.4.0,<7.0.0)",
-    "openai==2.49.0", # pinned version for stable compatibility with litellm (after issue with 1.100.0)
+    "openai==2.54.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)",
     "python-ulid (>=3.0.0,<4.0.0)",
@@ -212,7 +212,7 @@ log_cli_level = "WARNING"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.26.0"
+version = "0.27.0"
 version_files = [
     "contextgem/__init__.py:__version__",
     "pyproject.toml:version",