unique_toolkit 1.8.1__py3-none-any.whl → 1.23.0__py3-none-any.whl

unique_toolkit/agentic/debug_info_manager/test/test_debug_info_manager.py

@@ -0,0 +1,278 @@
+"""
+Test suite for DebugInfoManager class.
+
+This test suite validates the DebugInfoManager's ability to:
+1. Initialize with empty debug info
+2. Extract tool debug info from ToolCallResponse objects
+3. Handle loop iteration indices
+4. Add arbitrary key-value pairs to debug info
+5. Retrieve the complete debug info dictionary
+"""
+
+from unique_toolkit.agentic.debug_info_manager.debug_info_manager import (
+    DebugInfoManager,
+)
+from unique_toolkit.agentic.tools.schemas import ToolCallResponse
+
+
+class TestDebugInfoManager:
+    """Test suite for DebugInfoManager functionality."""
+
+    def test_init__initializes_empty_debug_info__on_creation(self):
+        """Test that DebugInfoManager initializes with empty tools list."""
+        manager = DebugInfoManager()
+
+        assert manager.debug_info == {"tools": []}
+        assert manager.get() == {"tools": []}
+
+    def test_extract_tool_debug_info__adds_single_tool__with_valid_response(self):
+        """Test extracting debug info from a single ToolCallResponse."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1",
+            name="TestTool",
+            debug_info={"execution_time": "100ms", "status": "success"},
+        )
+
+        manager.extract_tool_debug_info([tool_call_response])
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "TestTool"
+        assert debug_info["tools"][0]["info"]["execution_time"] == "100ms"
+        assert debug_info["tools"][0]["info"]["status"] == "success"
+
+    def test_extract_tool_debug_info__adds_multiple_tools__with_multiple_responses(
+        self,
+    ):
+        """Test extracting debug info from multiple ToolCallResponse objects."""
+        manager = DebugInfoManager()
+        tool_call_responses = [
+            ToolCallResponse(
+                id="tool_1",
+                name="SearchTool",
+                debug_info={"query": "test query", "results": 5},
+            ),
+            ToolCallResponse(
+                id="tool_2",
+                name="CalculatorTool",
+                debug_info={"operation": "add", "result": 42},
+            ),
+            ToolCallResponse(
+                id="tool_3",
+                name="WeatherTool",
+                debug_info={"location": "New York", "temperature": "72F"},
+            ),
+        ]
+
+        manager.extract_tool_debug_info(tool_call_responses)
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["name"] == "SearchTool"
+        assert debug_info["tools"][1]["name"] == "CalculatorTool"
+        assert debug_info["tools"][2]["name"] == "WeatherTool"
+
+    def test_extract_tool_debug_info__preserves_order__with_sequential_calls(self):
+        """Test that multiple calls to extract_tool_debug_info preserve order."""
+        manager = DebugInfoManager()
+
+        # First call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_1", name="Tool1", debug_info={"step": 1})]
+        )
+
+        # Second call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_2", name="Tool2", debug_info={"step": 2})]
+        )
+
+        # Third call
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_3", name="Tool3", debug_info={"step": 3})]
+        )
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["info"]["step"] == 1
+        assert debug_info["tools"][1]["info"]["step"] == 2
+        assert debug_info["tools"][2]["info"]["step"] == 3
+
+    def test_extract_tool_debug_info__adds_loop_iteration__when_index_provided(self):
+        """Test that loop_iteration_index is added to debug info when provided."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="IterativeTool", debug_info={"status": "processing"}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response], loop_iteration_index=3)
+
+        debug_info = manager.get()
+        assert debug_info["tools"][0]["info"]["loop_iteration"] == 3
+        assert debug_info["tools"][0]["info"]["status"] == "processing"
+
+    def test_extract_tool_debug_info__omits_loop_iteration__when_index_is_none(self):
+        """Test that loop_iteration is not added when index is None."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="SingleRunTool", debug_info={"status": "complete"}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response], loop_iteration_index=None)
+
+        debug_info = manager.get()
+        assert "loop_iteration" not in debug_info["tools"][0]["info"]
+        assert debug_info["tools"][0]["info"]["status"] == "complete"
+
+    def test_extract_tool_debug_info__handles_empty_debug_info__gracefully(self):
+        """Test extracting from ToolCallResponse with empty debug_info dict."""
+        manager = DebugInfoManager()
+        tool_call_response = ToolCallResponse(
+            id="tool_1", name="MinimalTool", debug_info={}
+        )
+
+        manager.extract_tool_debug_info([tool_call_response])
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "MinimalTool"
+        assert debug_info["tools"][0]["info"] == {}
+
+    def test_extract_tool_debug_info__handles_empty_list__without_error(self):
+        """Test that passing an empty list doesn't cause errors."""
+        manager = DebugInfoManager()
+
+        manager.extract_tool_debug_info([])
+
+        debug_info = manager.get()
+        assert debug_info["tools"] == []
+
+    def test_add__adds_new_key_value_pair__to_debug_info(self):
+        """Test adding a new key-value pair to debug_info."""
+        manager = DebugInfoManager()
+
+        manager.add("execution_summary", {"total_time": "500ms", "total_calls": 5})
+
+        debug_info = manager.get()
+        assert "execution_summary" in debug_info
+        assert debug_info["execution_summary"]["total_time"] == "500ms"
+        assert debug_info["execution_summary"]["total_calls"] == 5
+
+    def test_add__preserves_tools_list__when_adding_new_keys(self):
+        """Test that add() preserves the tools list."""
+        manager = DebugInfoManager()
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_1", name="TestTool", debug_info={"test": "data"}
+                )
+            ]
+        )
+
+        manager.add("metadata", {"version": "1.0"})
+
+        debug_info = manager.get()
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["tools"][0]["name"] == "TestTool"
+        assert debug_info["metadata"]["version"] == "1.0"
+
+    def test_add__overwrites_existing_key__when_key_exists(self):
+        """Test that add() overwrites an existing key."""
+        manager = DebugInfoManager()
+        manager.add("status", "in_progress")
+        manager.add("status", "completed")
+
+        debug_info = manager.get()
+        assert debug_info["status"] == "completed"
+
+    def test_add__adds_multiple_keys__with_sequential_calls(self):
+        """Test adding multiple key-value pairs with sequential calls."""
+        manager = DebugInfoManager()
+
+        manager.add("key1", "value1")
+        manager.add("key2", {"nested": "value2"})
+        manager.add("key3", [1, 2, 3])
+
+        debug_info = manager.get()
+        assert debug_info["key1"] == "value1"
+        assert debug_info["key2"]["nested"] == "value2"
+        assert debug_info["key3"] == [1, 2, 3]
+
+    def test_get__returns_complete_debug_info__with_mixed_data(self):
+        """Test get() returns complete debug info with tools and custom keys."""
+        manager = DebugInfoManager()
+
+        # Add tool debug info
+        manager.extract_tool_debug_info(
+            [ToolCallResponse(id="tool_1", name="Tool1", debug_info={"data": "test"})],
+            loop_iteration_index=0,
+        )
+
+        # Add custom keys
+        manager.add("start_time", "2025-10-16T10:00:00")
+        manager.add("end_time", "2025-10-16T10:01:00")
+
+        debug_info = manager.get()
+
+        assert "tools" in debug_info
+        assert "start_time" in debug_info
+        assert "end_time" in debug_info
+        assert len(debug_info["tools"]) == 1
+        assert debug_info["start_time"] == "2025-10-16T10:00:00"
+
+    def test_integration__complete_workflow__with_all_operations(self):
+        """Integration test: complete workflow using all DebugInfoManager methods."""
+        manager = DebugInfoManager()
+
+        # Initial state
+        assert manager.get() == {"tools": []}
+
+        # Add some metadata
+        manager.add("session_id", "abc-123")
+        manager.add("user_id", "user-456")
+
+        # First tool call (loop iteration 0)
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_1",
+                    name="SearchTool",
+                    debug_info={"query": "AI research", "hits": 100},
+                )
+            ],
+            loop_iteration_index=0,
+        )
+
+        # Second tool call (loop iteration 1)
+        manager.extract_tool_debug_info(
+            [
+                ToolCallResponse(
+                    id="tool_2",
+                    name="AnalysisTool",
+                    debug_info={"processed": 50, "relevant": 10},
+                ),
+                ToolCallResponse(
+                    id="tool_3",
+                    name="SummaryTool",
+                    debug_info={"paragraphs": 3, "words": 250},
+                ),
+            ],
+            loop_iteration_index=1,
+        )
+
+        # Add final summary
+        manager.add("summary", {"total_tools": 3, "total_iterations": 2})
+
+        # Verify complete debug info
+        debug_info = manager.get()
+
+        assert debug_info["session_id"] == "abc-123"
+        assert debug_info["user_id"] == "user-456"
+        assert len(debug_info["tools"]) == 3
+        assert debug_info["tools"][0]["name"] == "SearchTool"
+        assert debug_info["tools"][0]["info"]["loop_iteration"] == 0
+        assert debug_info["tools"][1]["name"] == "AnalysisTool"
+        assert debug_info["tools"][1]["info"]["loop_iteration"] == 1
+        assert debug_info["tools"][2]["name"] == "SummaryTool"
+        assert debug_info["tools"][2]["info"]["loop_iteration"] == 1
+        assert debug_info["summary"]["total_tools"] == 3

unique_toolkit/agentic/evaluation/config.py

@@ -4,7 +4,8 @@ from humps import camelize
 from pydantic import BaseModel, ConfigDict, Field
 
 from unique_toolkit._common.validators import LMI
-from unique_toolkit.language_model.infos import LanguageModelInfo, LanguageModelName
+from unique_toolkit.language_model.default_language_model import DEFAULT_GPT_4o
+from unique_toolkit.language_model.infos import LanguageModelInfo
 
 from .schemas import (
     EvaluationMetricName,
@@ -24,7 +25,7 @@ class EvaluationMetricConfig(BaseModel):
     enabled: bool = False
     name: EvaluationMetricName
     language_model: LMI = LanguageModelInfo.from_name(
-        LanguageModelName.AZURE_GPT_35_TURBO_0125,
+        DEFAULT_GPT_4o,
     )
     additional_llm_options: dict[str, Any] = Field(
         default={},

unique_toolkit/agentic/evaluation/context_relevancy/service.py

@@ -4,7 +4,6 @@ from typing import overload
 from pydantic import BaseModel, ValidationError
 from typing_extensions import deprecated
 
-from unique_toolkit._common.default_language_model import DEFAULT_GPT_35_TURBO
 from unique_toolkit._common.validate_required_values import (
     validate_required_values,
 )
@@ -24,6 +23,7 @@ from unique_toolkit.agentic.evaluation.schemas import (
     EvaluationMetricResult,
 )
 from unique_toolkit.app.schemas import BaseEvent, ChatEvent
+from unique_toolkit.language_model.default_language_model import DEFAULT_GPT_4o
 from unique_toolkit.language_model.infos import (
     LanguageModelInfo,
     ModelCapabilities,
@@ -49,7 +49,7 @@ USER_MSG_KEY = "userPrompt"
 default_config = EvaluationMetricConfig(
     enabled=False,
     name=EvaluationMetricName.CONTEXT_RELEVANCY,
-    language_model=LanguageModelInfo.from_name(DEFAULT_GPT_35_TURBO),
+    language_model=LanguageModelInfo.from_name(DEFAULT_GPT_4o),
     custom_prompts={
         SYSTEM_MSG_KEY: CONTEXT_RELEVANCY_METRIC_SYSTEM_MSG,
         USER_MSG_KEY: CONTEXT_RELEVANCY_METRIC_USER_MSG,

unique_toolkit/agentic/evaluation/evaluation_manager.py

@@ -123,6 +123,15 @@ class EvaluationManager:
                 self._evaluation_passed = False
             evaluation_results_unpacked.append(unpacked_evaluation_result)
 
+        for evaluation_name, evaluation_result in zip(
+            selected_evaluation_names, evaluation_results_unpacked
+        ):
+            evaluation_instance = self.get_evaluation_by_name(evaluation_name)
+            if evaluation_instance:
+                await self._show_message_assessment(
+                    evaluation_instance, evaluation_result, assistant_message_id
+                )
+
         return evaluation_results_unpacked
 
     async def execute_evaluation_call(
@@ -143,11 +152,6 @@ class EvaluationManager:
             evaluation_metric_result: EvaluationMetricResult = (
                 await evaluation_instance.run(loop_response)
             )
-            # show results to the user
-            await self._show_message_assessment(
-                evaluation_instance, evaluation_metric_result, assistant_message_id
-            )
-
             return evaluation_metric_result
 
         return EvaluationMetricResult(

unique_toolkit/agentic/evaluation/hallucination/constants.py

@@ -2,7 +2,6 @@ from typing import Any
 
 from pydantic import Field
 
-from unique_toolkit._common.default_language_model import DEFAULT_GPT_4o
 from unique_toolkit._common.validators import LMI
 from unique_toolkit.agentic.evaluation.config import EvaluationMetricConfig
 from unique_toolkit.agentic.evaluation.hallucination.prompts import (
@@ -15,6 +14,7 @@ from unique_toolkit.agentic.evaluation.schemas import (
     EvaluationMetricInputFieldName,
     EvaluationMetricName,
 )
+from unique_toolkit.language_model.default_language_model import DEFAULT_GPT_4o
 from unique_toolkit.language_model.infos import LanguageModelInfo
 
 SYSTEM_MSG_KEY = "systemPrompt"

unique_toolkit/agentic/evaluation/hallucination/hallucination_evaluation.py

@@ -1,3 +1,5 @@
+import regex as re
+
 from unique_toolkit.agentic.evaluation.evaluation_manager import Evaluation
 from unique_toolkit.agentic.evaluation.hallucination.constants import (
     HallucinationConfig,
@@ -18,6 +20,7 @@ from unique_toolkit.chat.schemas import (
     ChatMessageAssessmentStatus,
     ChatMessageAssessmentType,
 )
+from unique_toolkit.language_model.reference import _preprocess_message
 from unique_toolkit.language_model.schemas import (
     LanguageModelStreamResponse,
 )
@@ -40,13 +43,25 @@ class HallucinationEvaluation(Evaluation):
     async def run(
         self, loop_response: LanguageModelStreamResponse
     ) -> EvaluationMetricResult:  # type: ignore
-        chunks = self._reference_manager.get_chunks()
+        all_chunks = self._reference_manager.get_chunks()
+
+        # source numbers from original text
+        ref_pattern = r"\[(\d+)\]"
+        original_text = loop_response.message.original_text
+
+        # preprocess original text to deal with different source patterns
+        original_text_preprocessed = _preprocess_message(original_text)
+
+        source_number_matches = re.findall(ref_pattern, original_text_preprocessed)
+        source_numbers = {int(num) for num in source_number_matches}
+
+        referenced_chunks = [all_chunks[idx] for idx in source_numbers]
 
         evaluation_result: EvaluationMetricResult = await check_hallucination(
             company_id=self._company_id,
             input=EvaluationMetricInput(
                 input_text=self._user_message,
-                context_texts=[context.text for context in chunks],
+                context_texts=[context.text for context in referenced_chunks],
                 history_messages=[],  # TODO include loop_history messages
                 output_text=loop_response.message.text,
             ),
@@ -78,11 +93,19 @@ class HallucinationEvaluation(Evaluation):
             if not evaluation_result.error
             else ChatMessageAssessmentStatus.ERROR
         )
+        explanation = evaluation_result.reason
+
+        if status == ChatMessageAssessmentStatus.ERROR:
+            title = "Hallucination Check Error"
+            label = ChatMessageAssessmentLabel.RED
+            explanation = (
+                "An unrecoverable error occurred while evaluating the response."
+            )
 
         return EvaluationAssessmentMessage(
             status=status,
             title=title,
-            explanation=evaluation_result.reason,
+            explanation=explanation,
             label=label,
             type=self.get_assessment_type(),
         )

unique_toolkit/agentic/history_manager/history_manager.py

@@ -3,6 +3,9 @@ from typing import Annotated, Awaitable, Callable
 
 from pydantic import BaseModel, Field
 
+from unique_toolkit._common.feature_flags.schema import (
+    FeatureExtendedSourceSerialization,
+)
 from unique_toolkit._common.validators import LMI
 from unique_toolkit.agentic.history_manager.loop_token_reducer import LoopTokenReducer
 from unique_toolkit.agentic.history_manager.utils import transform_chunks_to_string
@@ -10,7 +13,8 @@ from unique_toolkit.agentic.reference_manager.reference_manager import Reference
 from unique_toolkit.agentic.tools.config import get_configuration_dict
 from unique_toolkit.agentic.tools.schemas import ToolCallResponse
 from unique_toolkit.app.schemas import ChatEvent
-from unique_toolkit.language_model.infos import LanguageModelInfo, LanguageModelName
+from unique_toolkit.language_model.default_language_model import DEFAULT_GPT_4o
+from unique_toolkit.language_model.infos import LanguageModelInfo
 from unique_toolkit.language_model.schemas import (
     LanguageModelAssistantMessage,
     LanguageModelFunction,
@@ -41,11 +45,7 @@ class UploadedContentConfig(BaseModel):
     )
 
 
-class ExperimentalFeatures(BaseModel):
-    full_sources_serialize_dump: bool = Field(
-        default=False,
-        description="If True, the sources will be serialized in full, otherwise only the content will be serialized.",
-    )
+class ExperimentalFeatures(FeatureExtendedSourceSerialization): ...
 
 
 class HistoryManagerConfig(BaseModel):
@@ -61,9 +61,7 @@ class HistoryManagerConfig(BaseModel):
         description="The fraction of the max input tokens that will be reserved for the history.",
     )
 
-    language_model: LMI = LanguageModelInfo.from_name(
-        LanguageModelName.AZURE_GPT_4o_2024_1120
-    )
+    language_model: LMI = LanguageModelInfo.from_name(DEFAULT_GPT_4o)
 
     @property
     def max_history_tokens(self) -> int:
@@ -122,9 +120,16 @@ class HistoryManager:
             reference_manager=reference_manager,
         )
         self._tool_call_result_history: list[ToolCallResponse] = []
+        self._tool_calls: list[LanguageModelFunction] = []
         self._loop_history: list[LanguageModelMessage] = []
         self._source_enumerator = 0
 
+    def add_tool_call(self, tool_call: LanguageModelFunction) -> None:
+        self._tool_calls.append(tool_call)
+
+    def get_tool_calls(self) -> list[LanguageModelFunction]:
+        return self._tool_calls
+
     def has_no_loop_messages(self) -> bool:
         return len(self._loop_history) == 0
 
@@ -173,8 +178,6 @@ class HistoryManager:
         stringified_sources, sources = transform_chunks_to_string(
             content_chunks,
             self._source_enumerator,
-            None,  # Use None for SourceFormatConfig
-            self._config.experimental_features.full_sources_serialize_dump,
         )
 
         self._source_enumerator += len(

unique_toolkit/agentic/history_manager/loop_token_reducer.py

@@ -266,7 +266,9 @@ class LoopTokenReducer:
         selected_messages = []
         token_count = 0
         for msg in messages[::-1]:
-            msg_token_count = self._count_tokens(str(msg.content))
+            msg_token_count = self._count_message_tokens(
+                LanguageModelMessages(root=[msg])
+            )
             if token_count + msg_token_count > token_limit:
                 break
             selected_messages.append(msg)
@@ -293,9 +295,6 @@ class LoopTokenReducer:
                 )
         return messages
 
-    def _count_tokens(self, text: str) -> int:
-        return len(self._encoder.encode(text))
-
     def ensure_last_message_is_user_message(self, limited_history_messages):
         """
         As the token limit can be reached in the middle of a gpt_request,

unique_toolkit/agentic/history_manager/utils.py

@@ -1,12 +1,10 @@
 import json
 import logging
 from copy import deepcopy
+from typing import Any
 
 from unique_toolkit.agentic.tools.schemas import Source
-from unique_toolkit.agentic.tools.utils.source_handling.schema import (
-    SourceFormatConfig,
-)
-from unique_toolkit.content.schemas import ContentChunk, ContentMetadata
+from unique_toolkit.content.schemas import ContentChunk
 from unique_toolkit.language_model.schemas import (
     LanguageModelAssistantMessage,
     LanguageModelMessage,
@@ -62,58 +60,25 @@ def _convert_tool_call_response_to_content(
 def transform_chunks_to_string(
     content_chunks: list[ContentChunk],
     max_source_number: int,
-    cfg: SourceFormatConfig | None,
-    full_sources_serialize_dump: bool = False,
-) -> tuple[str, list[Source]]:
+) -> tuple[str, list[dict[str, Any]]]:
     """Transform content chunks into a string of sources.
 
     Args:
         content_chunks (list[ContentChunk]): The content chunks to transform
         max_source_number (int): The maximum source number to use
-        feature_full_sources (bool, optional): Whether to include the full source object. Defaults to False which is the old format.
 
     Returns:
         str: String for the tool call response
     """
     if not content_chunks:
         return "No relevant sources found.", []
-    if full_sources_serialize_dump:
-        sources = [
-            Source(
-                source_number=max_source_number + i,
-                key=chunk.key,
-                id=chunk.id,
-                order=chunk.order,
-                content=chunk.text,
-                chunk_id=chunk.chunk_id,
-                metadata=(
-                    _format_metadata(chunk.metadata, cfg) or None
-                    if chunk.metadata
-                    else None
-                ),
-                url=chunk.url,
-            ).model_dump(
-                exclude_none=True,
-                exclude_defaults=True,
-                by_alias=True,
-            )
-            for i, chunk in enumerate(content_chunks)
-        ]
-    else:
-        sources = [
-            {
-                "source_number": max_source_number + i,
-                "content": chunk.text,
-                **(
-                    {"metadata": meta}
-                    if (
-                        meta := _format_metadata(chunk.metadata, cfg)
-                    )  # only add when not empty
-                    else {}
-                ),
-            }
-            for i, chunk in enumerate(content_chunks)
-        ]
+    sources: list[dict[str, Any]] = [
+        {
+            "source_number": max_source_number + i,
+            "content": chunk.text,
+        }
+        for i, chunk in enumerate(content_chunks)
+    ]
     return json.dumps(sources), sources
 
 
@@ -129,45 +94,3 @@ def load_sources_from_string(
     except (json.JSONDecodeError, ValueError):
         logger.warning("Failed to parse source string")
         return None
-
-
-def _format_metadata(
-    metadata: ContentMetadata | None,
-    cfg: SourceFormatConfig | None,
-) -> str:
-    """
-    Build the concatenated tag string from the chunk's metadata
-    and the templates found in cfg.sections.
-    Example result:
-      "<|topic|>GenAI<|/topic|>\n<|date|>This document is from: 2025-04-29<|/date|>\n"
-    """
-    if metadata is None:
-        return ""
-
-    if cfg is None or not cfg.sections:
-        # If no configuration is provided, return empty string
-        return ""
-
-    meta_dict = metadata.model_dump(exclude_none=True, by_alias=True)
-    sections = cfg.sections
-
-    parts: list[str] = []
-    for key, template in sections.items():
-        if key in meta_dict:
-            parts.append(template.format(meta_dict[key]))
-
-    return "".join(parts)
-
-
-### In case we do not want any formatting of metadata we could use this function
-# def _filtered_metadata(
-#     meta: ContentMetadata | None,
-#     cfg: SourceFormatConfig,
-# ) -> dict[str, str] | None:
-#     if meta is None:
-#         return None
-
-#     allowed = set(cfg.sections)
-#     raw = meta.model_dump(exclude_none=True, by_alias=True)
-#     pruned = {k: v for k, v in raw.items() if k in allowed}
-#     return pruned or None