openai-sdk-helpers 0.6.5__tar.gz → 0.7.0__tar.gz

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.6.5
+Version: 0.7.0
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.6.5"
+version = "0.7.0"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/src/openai_sdk_helpers/agent/classifier.py

@@ -26,6 +26,8 @@ from ..utils import ensure_list
 from .base import AgentBase
 from .configuration import AgentConfiguration
 
+_CONTINUE_CONFIDENCE_THRESHOLD = 0.7
+
 
 class TaxonomyClassifierAgent(AgentBase):
     """Classify text by recursively traversing a taxonomy.
@@ -394,6 +396,13 @@ class TaxonomyClassifierAgent(AgentBase):
 
         resolved_nodes = _resolve_nodes(node_paths, step)
 
+        should_continue = _should_continue_from_stop(step, resolved_nodes)
+        if should_continue:
+            step = step.model_copy(
+                update={"stop_reason": ClassificationStopReason.CONTINUE}
+            )
+            state.steps[-1] = step
+
         if step.stop_reason.is_terminal:
             if resolved_nodes:
                 state.final_nodes.extend(resolved_nodes)
@@ -407,7 +416,7 @@ class TaxonomyClassifierAgent(AgentBase):
             return
 
         base_steps_len = len(state.steps)
-        child_tasks: list[tuple[Awaitable["_TraversalState"], int]] = []
+        child_tasks: list[tuple[Awaitable["_TraversalState"], int, TaxonomyNode]] = []
         for node in resolved_nodes:
             if node.children:
                 sub_agent = self._build_sub_agent(list(node.children))
@@ -429,6 +438,7 @@ class TaxonomyClassifierAgent(AgentBase):
                             state=sub_state,
                         ),
                         base_final_nodes_len,
+                        node,
                     )
                 )
             else:
@@ -439,13 +449,19 @@ class TaxonomyClassifierAgent(AgentBase):
                 )
         if child_tasks:
             child_states = await asyncio.gather(
-                *(child_task for child_task, _ in child_tasks)
+                *(child_task for child_task, _, _ in child_tasks)
             )
-            for child_state, (_, base_final_nodes_len) in zip(
+            for child_state, (_, base_final_nodes_len, parent_node) in zip(
                 child_states, child_tasks, strict=True
             ):
                 state.steps.extend(child_state.steps[base_steps_len:])
-                state.final_nodes.extend(child_state.final_nodes[base_final_nodes_len:])
+                child_final_nodes = child_state.final_nodes[base_final_nodes_len:]
+                state.final_nodes.extend(child_final_nodes)
+                if should_continue and not child_final_nodes:
+                    state.final_nodes.append(parent_node)
+                    state.best_confidence = _max_confidence(
+                        state.best_confidence, step.confidence
+                    )
                 state.best_confidence = _max_confidence(
                     state.best_confidence, child_state.best_confidence
                 )
@@ -627,6 +643,34 @@ def _resolve_stop_reason(state: _TraversalState) -> ClassificationStopReason:
     return ClassificationStopReason.NO_MATCH
 
 
+def _should_continue_from_stop(
+    step: ClassificationStep,
+    resolved_nodes: Sequence[TaxonomyNode],
+    threshold: float = _CONTINUE_CONFIDENCE_THRESHOLD,
+) -> bool:
+    """Return True when a stop reason should continue traversal.
+
+    Parameters
+    ----------
+    step : ClassificationStep
+        Classification step to evaluate.
+    resolved_nodes : Sequence[TaxonomyNode]
+        Resolved taxonomy nodes from the classification step.
+    threshold : float, default=0.7
+        Confidence threshold for overriding a stop reason.
+
+    Returns
+    -------
+    bool
+        True when traversal should proceed despite a stop reason.
+    """
+    if step.stop_reason is not ClassificationStopReason.STOP:
+        return False
+    if step.confidence is None or step.confidence < threshold:
+        return False
+    return any(node.children for node in resolved_nodes)
+
+
 def _normalize_roots(
     taxonomy: TaxonomyNode | Sequence[TaxonomyNode],
 ) -> list[TaxonomyNode]:

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/src/openai_sdk_helpers/response/base.py

@@ -103,6 +103,9 @@ class ResponseBase(Generic[T]):
     openai_settings : OpenAISettings or None, default None
         Fully configured OpenAI settings with API key and default model.
         Required for normal operation.
+    save_messages : bool, default True
+        Default behavior for persisting message history on response runs
+        and close calls.
 
     Attributes
     ----------
@@ -169,6 +172,7 @@ class ResponseBase(Generic[T]):
         data_path: Path | str | None = None,
         tool_handlers: dict[str, ToolHandlerRegistration] | None = None,
         openai_settings: OpenAISettings | None = None,
+        save_messages: bool = True,
     ) -> None:
         """Initialize a response session with OpenAI configuration.
 
@@ -204,6 +208,9 @@ class ResponseBase(Generic[T]):
         openai_settings : OpenAISettings or None, default None
             Fully configured OpenAI settings with API key and default model.
             Required for normal operation.
+        save_messages : bool, default True
+            Default behavior for persisting message history on response runs
+            and close calls.
 
         Raises
         ------
@@ -247,6 +254,7 @@ class ResponseBase(Generic[T]):
             self._data_path = get_data_path(self.__class__.__name__)
 
         self._instructions = instructions
+        self._save_messages = save_messages
         self._tools: list[dict[str, Any]] | None = None
         if tools is not None:
             self._tools = [
@@ -314,7 +322,7 @@ class ResponseBase(Generic[T]):
 
         self.messages = ResponseMessages()
         self.messages.add_system_message(content=system_content)
-        if self._data_path is not None:
+        if self._data_path is not None and self._save_messages:
             self.save()
 
     @property
@@ -509,7 +517,6 @@ class ResponseBase(Generic[T]):
         content: str | list[str],
         files: str | list[str] | None = None,
         use_vector_store: bool = False,
-        save_messages: bool = True,
     ) -> T | str:
         """Generate a response asynchronously from the OpenAI API.
 
@@ -532,9 +539,6 @@ class ResponseBase(Generic[T]):
         use_vector_store : bool, default False
             If True, non-image files are uploaded to a vector store
             for RAG-enabled search instead of inline base64 encoding.
-        save_messages : bool, default True
-            When True, persist the message history after each response or
-            tool call.
 
         Returns
         -------
@@ -625,7 +629,7 @@ class ResponseBase(Generic[T]):
                         self.messages.add_tool_message(
                             content=response_output, output=tool_output
                         )
-                        if save_messages:
+                        if self._save_messages:
                             self.save()
                     except Exception as exc:
                         log(
@@ -651,7 +655,7 @@ class ResponseBase(Generic[T]):
                     self.messages.add_assistant_message(
                         response_output, metadata=kwargs
                     )
-                    if save_messages:
+                    if self._save_messages:
                         self.save()
                     if hasattr(response, "output_text") and response.output_text:
                         raw_text = response.output_text
@@ -688,7 +692,6 @@ class ResponseBase(Generic[T]):
         *,
         files: str | list[str] | None = None,
         use_vector_store: bool = False,
-        save_messages: bool = True,
     ) -> T | str:
         """Execute run_async synchronously with proper event loop handling.
 
@@ -711,9 +714,6 @@ class ResponseBase(Generic[T]):
         use_vector_store : bool, default False
             If True, non-image files are uploaded to a vector store
             for RAG-enabled search instead of inline base64 encoding.
-        save_messages : bool, default True
-            When True, persist the message history after each response or
-            tool call.
 
         Returns
         -------
@@ -749,7 +749,6 @@ class ResponseBase(Generic[T]):
                 content=content,
                 files=files,
                 use_vector_store=use_vector_store,
-                save_messages=save_messages,
             )
 
         try:
@@ -1003,7 +1002,8 @@ class ResponseBase(Generic[T]):
         ...     response.close()
         """
         log(f"Closing session {self.uuid} for {self.__class__.__name__}")
-        self.save()
+        if self._save_messages:
+            self.save()
 
         # Clean up tracked Files API uploads
         try:

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/src/openai_sdk_helpers/response/configuration.py

@@ -102,6 +102,9 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     system_vector_store : list[str], optional
         Optional list of vector store names to attach as system context.
         Default is None.
+    save_messages : bool, optional
+        Default behavior for persisting message history on response runs
+        and close calls. Default is True.
     add_output_instructions : bool, optional
         Whether to append output structure instructions to the prompt.
         Default is False.
@@ -114,6 +117,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
         If name is not a non-empty string.
         If instructions is not a string or Path.
         If tools is provided and is not a sequence.
+        If save_messages is not a bool.
         If input_structure or output_structure is not a class.
         If input_structure or output_structure does not subclass StructureBase.
     ValueError
@@ -158,6 +162,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     input_structure: Optional[Type[TIn]]
     output_structure: Optional[Type[TOut]]
     system_vector_store: Optional[list[str]] = None
+    save_messages: bool = True
     add_output_instructions: bool = False
     add_web_search_tool: bool = False
 
@@ -204,6 +209,8 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
 
         if self.tools is not None and not isinstance(self.tools, Sequence):
             raise TypeError("Configuration.tools must be a Sequence or None")
+        if not isinstance(self.save_messages, bool):
+            raise TypeError("Configuration.save_messages must be a bool")
 
     @property
     def get_resolved_instructions(self) -> str:
@@ -274,6 +281,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
             data_path=data_path,
             tool_handlers=tool_handlers,
             openai_settings=openai_settings,
+            save_messages=self.save_messages,
         )
 
 

{openai_sdk_helpers-0.6.5 → openai_sdk_helpers-0.7.0}/src/openai_sdk_helpers/structure/classification.py

@@ -480,6 +480,8 @@ class ClassificationResult(StructureBase):
         Yield selected identifiers across all steps.
     selected_nodes
         Return the selected identifiers across all steps.
+    to_lightweight_summary
+        Return a lightweight summary of selected node paths.
 
     Examples
     --------
@@ -565,6 +567,52 @@ class ClassificationResult(StructureBase):
                 if normalized:
                     yield normalized
 
+    def to_lightweight_summary(self) -> "ClassificationSummary | None":
+        """Return a lightweight summary of selected node paths.
+
+        Returns
+        -------
+        ClassificationSummary or None
+            Summary containing the ``full_paths`` of selected nodes, or None
+            when no selections exist.
+
+        Examples
+        --------
+        >>> result = ClassificationResult(steps=[])
+        >>> result.to_lightweight_summary() is None
+        True
+        """
+        full_paths = [
+            format_path_identifier(taxonomy_enum_path(node))
+            for node in self.selected_nodes
+        ]
+        if not full_paths:
+            return None
+        return ClassificationSummary(full_paths=full_paths)
+
+
+class ClassificationSummary(StructureBase):
+    """Represent a lightweight summary of selected taxonomy paths.
+
+    Attributes
+    ----------
+    full_paths : list[str] or None
+        Selected taxonomy paths including parent segments.
+
+    Methods
+    -------
+    to_json()
+        Serialize the summary to a JSON-compatible dictionary.
+    from_json(data)
+        Construct a summary instance from JSON-compatible data.
+    """
+
+    full_paths: list[str] | None = spec_field(
+        "full_paths",
+        description="Selected taxonomy paths including parent segments.",
+        default=None,
+    )
+
 
 def taxonomy_enum_path(value: Enum | str | None) -> list[str]:
     """Return the taxonomy path segments for an enum value.
@@ -598,6 +646,7 @@ def taxonomy_enum_path(value: Enum | str | None) -> list[str]:
 
 __all__ = [
     "ClassificationResult",
+    "ClassificationSummary",
     "ClassificationStep",
     "ClassificationStopReason",
     "Taxonomy",