Merge pull request #21 from shcherbak-ai/dev

v0.3.0

Author: SergiiShcherbak

CHANGELOG.md

@@ -5,6 +5,10 @@ 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.3.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.3.0) - 2025-05-19
+### Added
+- Expanded JsonObjectConcept to support nested class hierarchies, nested dictionary structures, lists containing objects, and literal types.
+
 ## [0.2.4](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.2.4) - 2025-05-09
 ### Fixed
 - Removed 'think' tags and content from LLM outputs (e.g. when using DeepSeek R1 via Ollama) which was breaking JSON parsing and validation

README.md

@@ -340,6 +340,8 @@ A raw text version of the full documentation is available at [`docs/docs-raw-for
 
 You can also explore the repository through [DeepWiki](https://deepwiki.com/shcherbak-ai/contextgem), an AI-powered conversational interface that provides visual architecture maps and natural language Q&A for the codebase.
 
+For a history of changes, improvements, and bug fixes, see the [CHANGELOG](https://github.com/shcherbak-ai/contextgem/blob/main/CHANGELOG.md).
+
 
 ## 💬 Community
 

contextgem/__init__.py

@@ -20,7 +20,7 @@
 ContextGem - Effortless LLM extraction from documents
 """
 
-__version__ = "0.2.4"
+__version__ = "0.3.0"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (
@@ -33,6 +33,7 @@
     DocumentPipeline,
     DocxConverter,
     Image,
+    JsonObjectClassStruct,
     JsonObjectConcept,
     JsonObjectExample,
     LLMPricing,
@@ -79,6 +80,7 @@
     # Utils
     "image_to_base64",
     "reload_logger_settings",
+    "JsonObjectClassStruct",
     # Converters
     "DocxConverter",
 ]

contextgem/internal/__init__.py

@@ -74,9 +74,14 @@
     SaTModelId,
     _deserialize_type_hint,
     _dynamic_pydantic_model,
+    _format_dict_structure,
     _format_type,
+    _get_model_fields,
     _is_json_serializable_type,
+    _is_typed_class,
     _JsonObjectItemStructure,
+    _normalize_type_annotation,
+    _raise_dict_class_type_error,
     _serialize_type_hint,
 )
 from contextgem.internal.utils import (
@@ -131,6 +136,11 @@
     "_JsonObjectItemStructure",
     "_serialize_type_hint",
     "_dynamic_pydantic_model",
+    "_format_dict_structure",
+    "_is_typed_class",
+    "_get_model_fields",
+    "_raise_dict_class_type_error",
+    "_normalize_type_annotation",
     # Data models
     "_LLMCall",
     "_LLMUsage",

contextgem/internal/base/serialization.py

@@ -37,6 +37,9 @@
 from pydantic import BaseModel, field_validator
 
 from contextgem.internal.loggers import logger
+from contextgem.internal.typings.strings_to_types import _deserialize_type_hint
+from contextgem.internal.typings.types_normalization import _normalize_type_annotation
+from contextgem.internal.typings.types_to_strings import _serialize_type_hint
 
 if TYPE_CHECKING:
     from contextgem.internal.base.concepts import _Concept
@@ -101,7 +104,6 @@ def to_dict(self) -> dict[str, Any]:
         """
 
         from contextgem.internal.data_models import _LLMCost, _LLMUsage
-        from contextgem.internal.typings.types_to_strings import _serialize_type_hint
         from contextgem.public.llms import DocumentLLM, DocumentLLMGroup
 
         if isinstance(self, (DocumentLLM, DocumentLLMGroup)):
@@ -128,9 +130,8 @@ def to_dict(self) -> dict[str, Any]:
                 base_dict[key] = [i.to_dict() for i in val]
 
             elif key == KEY_STRUCTURE_PUBLIC:
-                # json object concept
-                # Convert each item in the structure dict using the type-hint serializer
-                base_dict[key] = {k: _serialize_type_hint(v) for k, v in val.items()}
+                # Handle structure serialization for JsonObjectConcept structure
+                base_dict[key] = self._serialize_structure_dict(val)
 
             elif key == KEY_RATING_SCALE_PUBLIC:
                 base_dict[key] = val.to_dict()
@@ -183,6 +184,45 @@ def to_dict(self) -> dict[str, Any]:
 
         return {**base_dict}
 
+    def _serialize_structure_dict(
+        self, structure_dict: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Relevant for JsonObjectConcept structure serialization.
+
+        Recursively serializes a dictionary containing type hints to ensure proper serialization.
+        Handles nested dictionaries, lists of dictionaries, and various type hints.
+
+        :param structure_dict: Dictionary containing type hints to serialize
+        :type structure_dict: dict[str, Any]
+        :return: Dictionary with serialized type hints
+        :rtype: dict[str, Any]
+        """
+        result = {}
+        for key, value in structure_dict.items():
+            # Normalize the value for consistent type representation
+            value = _normalize_type_annotation(value)
+
+            # Handle nested dictionaries
+            if isinstance(value, dict):
+                # Class structs (if passed) are already converted to a dict structure
+                # during JsonObjectConcept initialization.
+                result[key] = self._serialize_structure_dict(value)
+            # Handle list of dictionaries (only need to serialize the first item)
+            elif (
+                isinstance(value, list)
+                and len(value) == 1
+                and isinstance(value[0], dict)
+            ):
+                # Class structs (if passed) are already converted to a dict structure
+                # during JsonObjectConcept initialization.
+                result[key] = [self._serialize_structure_dict(value[0])]
+            # Other cases
+            else:
+                result[key] = _serialize_type_hint(value)
+
+        return result
+
     def _convert_decimal_to_float(self, obj: Any) -> Any:
         """
         Recursively converts Decimal objects to floats for JSON serialization.
@@ -288,7 +328,6 @@ def from_dict(cls, obj_dict: dict[str, Any]) -> Self:
         import contextgem.public.examples as cg_examples
         from contextgem import Image
         from contextgem.internal.data_models import _LLMUsage
-        from contextgem.internal.typings.strings_to_types import _deserialize_type_hint
         from contextgem.public.aspects import Aspect
         from contextgem.public.data_models import LLMPricing, RatingScale
         from contextgem.public.llms import DocumentLLM
@@ -324,6 +363,47 @@ def lambda_list_val(
                 for d in val
             ]
 
+        def _deserialize_structure_dict(
+            structure_dict: dict[str, Any],
+        ) -> dict[str, Any]:
+            """
+            Relevant for JsonObjectConcept structure deserialization.
+
+            Recursively deserializes a dictionary containing string representations of type hints
+            into actual Python type objects. Handles nested dictionaries, lists of dictionaries,
+            and various type hint formats.
+
+            :param structure_dict: Dictionary containing serialized type hints to deserialize
+            :type structure_dict: dict[str, Any]
+            :return: Dictionary with deserialized type hints
+            :rtype: dict[str, Any]
+            """
+
+            result = {}
+            for k, v in structure_dict.items():
+                # Class structs (if passed) are already converted to a dict structure
+                # during JsonObjectConcept initialization.
+                if isinstance(v, dict):
+                    result[k] = _deserialize_structure_dict(v)
+                elif isinstance(v, list) and len(v) == 1 and isinstance(v[0], dict):
+                    result[k] = [_deserialize_structure_dict(v[0])]
+                elif isinstance(v, str):
+                    try:
+                        # Deserialize the type hint
+                        type_hint = _deserialize_type_hint(v)
+
+                        # Normalize the type hint for consistent representation
+                        # This converts between typing module generics and built-in equivalents
+                        normalized_type = _normalize_type_annotation(type_hint)
+
+                        result[k] = normalized_type
+                    except ValueError:
+                        # Keep as string if can't deserialize
+                        result[k] = v
+                else:
+                    result[k] = v
+            return result
+
         # Create a map for known keys → reconstruction logic
         rebuild_map: dict[str, Callable[[Any], Any]] = {
             # Public attrs
@@ -333,9 +413,10 @@ def lambda_list_val(
             KEY_PARAGRAPHS_PUBLIC: lambda_list_val(instance_cls=Paragraph),
             KEY_SENTENCES_PUBLIC: lambda_list_val(instance_cls=Sentence),
             KEY_IMAGES_PUBLIC: lambda_list_val(instance_cls=Image),
-            KEY_STRUCTURE_PUBLIC: lambda val: {
-                k: _deserialize_type_hint(v) for k, v in val.items()
-            },
+            KEY_STRUCTURE_PUBLIC: lambda val: (
+                # JsonObjectConcept structure is always converted to a dict
+                _deserialize_structure_dict(val)
+            ),
             KEY_RATING_SCALE_PUBLIC: lambda val: RatingScale.from_dict(val),
             # LLM attrs
             KEY_LLM_PRICING_PUBLIC: lambda val: (

contextgem/internal/prompts/extract_concept_items.j2

@@ -226,7 +226,7 @@ Concept description:
     {% if concept_data.structure %}
 
 Expected structure:
-{{ concept_data.structure | pprint }}
+{{ concept_data._format_structure_in_prompt() }}
     {% endif %}
     {% if concept_data.rating_scale %}
 

contextgem/internal/typings/__init__.py

@@ -31,7 +31,14 @@
     SaTModelId,
 )
 from contextgem.internal.typings.strings_to_types import _deserialize_type_hint
+from contextgem.internal.typings.typed_class_utils import (
+    _get_model_fields,
+    _is_typed_class,
+    _raise_dict_class_type_error,
+)
+from contextgem.internal.typings.types_normalization import _normalize_type_annotation
 from contextgem.internal.typings.types_to_strings import (
+    _format_dict_structure,
     _format_type,
     _is_json_serializable_type,
     _JsonObjectItemStructure,
@@ -62,6 +69,13 @@
     "_format_type",
     "_JsonObjectItemStructure",
     "_serialize_type_hint",
+    "_format_dict_structure",
     # User type hints validation
     "_dynamic_pydantic_model",
+    # Typed class utils
+    "_is_typed_class",
+    "_get_model_fields",
+    "_raise_dict_class_type_error",
+    # Types normalization
+    "_normalize_type_annotation",
 ]