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

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

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

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

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

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

@@ -10,12 +10,17 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Awaitable, Dict, Iterable, Optional, Sequence, cast
 
+from agents.model_settings import ModelSettings
+
 from ..structure import (
     ClassificationResult,
     ClassificationStep,
     ClassificationStopReason,
     StructureBase,
+    Taxonomy,
     TaxonomyNode,
+    format_path_identifier,
+    split_path_identifier,
 )
 from ..utils import ensure_list
 from .base import AgentBase
@@ -31,14 +36,14 @@ class TaxonomyClassifierAgent(AgentBase):
         Optional template file path for prompt rendering.
     model : str | None, default=None
         Model identifier to use for classification.
+    model_settings : ModelSettings | None, default=None
+        Optional model settings to apply to the classifier agent.
 
     Methods
     -------
-    run_agent(text, taxonomy, context, max_depth, session)
-        Classify text by recursively walking the taxonomy tree.
-    run_async(input, context, max_depth, confidence_threshold, single_class)
+    run_async(input, context, max_depth, confidence_threshold)
         Classify text asynchronously using taxonomy traversal.
-    run_sync(input, context, max_depth, confidence_threshold, single_class)
+    run_sync(input, context, max_depth, confidence_threshold)
         Classify text synchronously using taxonomy traversal.
 
     Examples
@@ -57,6 +62,7 @@ class TaxonomyClassifierAgent(AgentBase):
         *,
         template_path: Path | str | None = None,
         model: str | None = None,
+        model_settings: ModelSettings | None = None,
         taxonomy: TaxonomyNode | Sequence[TaxonomyNode],
     ) -> None:
         """Initialize the taxonomy classifier agent configuration.
@@ -67,6 +73,8 @@ class TaxonomyClassifierAgent(AgentBase):
             Optional template file path for prompt rendering.
         model : str | None, default=None
             Model identifier to use for classification.
+        model_settings : ModelSettings | None, default=None
+            Optional model settings to apply to the classifier agent.
         taxonomy : TaxonomyNode | Sequence[TaxonomyNode]
             Root taxonomy node or list of root nodes.
 
@@ -91,10 +99,11 @@ class TaxonomyClassifierAgent(AgentBase):
             template_path=resolved_template_path,
             output_structure=ClassificationStep,
             model=model,
+            model_settings=model_settings,
         )
         super().__init__(configuration=configuration)
 
-    async def run_agent(
+    async def _run_agent(
         self,
         text: str,
         *,
@@ -102,7 +111,6 @@ class TaxonomyClassifierAgent(AgentBase):
         file_ids: str | Sequence[str] | None = None,
         max_depth: Optional[int] = None,
         confidence_threshold: float | None = None,
-        single_class: bool = False,
         session: Optional[Any] = None,
     ) -> ClassificationResult:
         """Classify ``text`` by recursively walking taxonomy levels.
@@ -119,8 +127,6 @@ class TaxonomyClassifierAgent(AgentBase):
             Maximum depth to traverse before stopping.
         confidence_threshold : float or None, default=None
             Minimum confidence required to accept a classification step.
-        single_class : bool, default=False
-            Whether to keep only the highest-priority selection per step.
         session : Session or None, default=None
             Optional session for maintaining conversation history across runs.
 
@@ -147,21 +153,17 @@ class TaxonomyClassifierAgent(AgentBase):
             file_ids=file_ids,
             max_depth=max_depth,
             confidence_threshold=confidence_threshold,
-            single_class=single_class,
             session=session,
             state=state,
         )
 
         final_nodes_value = state.final_nodes or None
-        final_node = state.final_nodes[0] if state.final_nodes else None
         stop_reason = _resolve_stop_reason(state)
         return ClassificationResult(
-            final_node=final_node,
             final_nodes=final_nodes_value,
             confidence=state.best_confidence,
             stop_reason=stop_reason,
-            path=state.path,
-            path_nodes=state.path_nodes,
+            steps=state.steps,
         )
 
     async def run_async(
@@ -174,7 +176,6 @@ class TaxonomyClassifierAgent(AgentBase):
         file_ids: str | Sequence[str] | None = None,
         max_depth: Optional[int] = None,
         confidence_threshold: float | None = None,
-        single_class: bool = False,
     ) -> ClassificationResult:
         """Classify ``input`` asynchronously with taxonomy traversal.
 
@@ -194,8 +195,6 @@ class TaxonomyClassifierAgent(AgentBase):
             Maximum depth to traverse before stopping.
         confidence_threshold : float or None, default=None
             Minimum confidence required to accept a classification step.
-        single_class : bool, default=False
-            Whether to keep only the highest-priority selection per step.
 
         Returns
         -------
@@ -211,11 +210,10 @@ class TaxonomyClassifierAgent(AgentBase):
             "file_ids": file_ids,
             "max_depth": max_depth,
             "confidence_threshold": confidence_threshold,
-            "single_class": single_class,
         }
         if session is not None:
             kwargs["session"] = session
-        return await self.run_agent(input, **kwargs)
+        return await self._run_agent(input, **kwargs)
 
     def run_sync(
         self,
@@ -227,7 +225,6 @@ class TaxonomyClassifierAgent(AgentBase):
         file_ids: str | Sequence[str] | None = None,
         max_depth: Optional[int] = None,
         confidence_threshold: float | None = None,
-        single_class: bool = False,
     ) -> ClassificationResult:
         """Classify ``input`` synchronously with taxonomy traversal.
 
@@ -247,8 +244,6 @@ class TaxonomyClassifierAgent(AgentBase):
             Maximum depth to traverse before stopping.
         confidence_threshold : float or None, default=None
             Minimum confidence required to accept a classification step.
-        single_class : bool, default=False
-            Whether to keep only the highest-priority selection per step.
 
         Returns
         -------
@@ -264,13 +259,12 @@ class TaxonomyClassifierAgent(AgentBase):
             "file_ids": file_ids,
             "max_depth": max_depth,
             "confidence_threshold": confidence_threshold,
-            "single_class": single_class,
         }
         if session is not None:
             kwargs["session"] = session
 
         async def runner() -> ClassificationResult:
-            return await self.run_agent(input, **kwargs)
+            return await self._run_agent(input, **kwargs)
 
         try:
             asyncio.get_running_loop()
@@ -342,7 +336,6 @@ class TaxonomyClassifierAgent(AgentBase):
         file_ids: str | Sequence[str] | None,
         max_depth: Optional[int],
         confidence_threshold: float | None,
-        single_class: bool,
         session: Optional[Any],
         state: "_TraversalState",
     ) -> None:
@@ -364,8 +357,6 @@ class TaxonomyClassifierAgent(AgentBase):
             Maximum traversal depth before stopping.
         confidence_threshold : float or None
             Minimum confidence required to accept a classification step.
-        single_class : bool
-            Whether to keep only the highest-priority selection per step.
         session : Session or None
             Optional session for maintaining conversation history across runs.
         state : _TraversalState
@@ -380,7 +371,7 @@ class TaxonomyClassifierAgent(AgentBase):
         node_paths = _build_node_path_map(nodes, parent_path)
         template_context = _build_context(
             node_descriptors=_build_node_descriptors(node_paths),
-            path=state.path,
+            steps=state.steps,
             depth=depth,
             context=context,
         )
@@ -392,7 +383,7 @@ class TaxonomyClassifierAgent(AgentBase):
             session=session,
         )
         step = _normalize_step_output(raw_step, step_structure)
-        state.path.append(step)
+        state.steps.append(step)
 
         if (
             confidence_threshold is not None
@@ -402,10 +393,6 @@ class TaxonomyClassifierAgent(AgentBase):
             return
 
         resolved_nodes = _resolve_nodes(node_paths, step)
-        if resolved_nodes:
-            if single_class:
-                resolved_nodes = resolved_nodes[:1]
-            state.path_nodes.extend(resolved_nodes)
 
         if step.stop_reason.is_terminal:
             if resolved_nodes:
@@ -419,8 +406,7 @@ class TaxonomyClassifierAgent(AgentBase):
         if not resolved_nodes:
             return
 
-        base_path_len = len(state.path)
-        base_path_nodes_len = len(state.path_nodes)
+        base_steps_len = len(state.steps)
         child_tasks: list[tuple[Awaitable["_TraversalState"], int]] = []
         for node in resolved_nodes:
             if node.children:
@@ -439,7 +425,6 @@ class TaxonomyClassifierAgent(AgentBase):
                             file_ids=file_ids,
                             max_depth=max_depth,
                             confidence_threshold=confidence_threshold,
-                            single_class=single_class,
                             session=session,
                             state=sub_state,
                         ),
@@ -459,8 +444,7 @@ class TaxonomyClassifierAgent(AgentBase):
             for child_state, (_, base_final_nodes_len) in zip(
                 child_states, child_tasks, strict=True
             ):
-                state.path.extend(child_state.path[base_path_len:])
-                state.path_nodes.extend(child_state.path_nodes[base_path_nodes_len:])
+                state.steps.extend(child_state.steps[base_steps_len:])
                 state.final_nodes.extend(child_state.final_nodes[base_final_nodes_len:])
                 state.best_confidence = _max_confidence(
                     state.best_confidence, child_state.best_confidence
@@ -514,6 +498,7 @@ class TaxonomyClassifierAgent(AgentBase):
         sub_agent = TaxonomyClassifierAgent(
             template_path=self._template_path,
             model=self._model,
+            model_settings=self._model_settings,
             taxonomy=list(nodes),
         )
         sub_agent._run_step_async = self._run_step_async
@@ -531,7 +516,6 @@ class TaxonomyClassifierAgent(AgentBase):
         file_ids: str | Sequence[str] | None,
         max_depth: Optional[int],
         confidence_threshold: float | None,
-        single_class: bool,
         session: Optional[Any],
         state: "_TraversalState",
     ) -> "_TraversalState":
@@ -557,8 +541,6 @@ class TaxonomyClassifierAgent(AgentBase):
             Maximum traversal depth before stopping.
         confidence_threshold : float or None
             Minimum confidence required to accept a classification step.
-        single_class : bool
-            Whether to keep only the highest-priority selection per step.
         session : Session or None
             Optional session for maintaining conversation history across runs.
         state : _TraversalState
@@ -578,7 +560,6 @@ class TaxonomyClassifierAgent(AgentBase):
             file_ids=file_ids,
             max_depth=max_depth,
             confidence_threshold=confidence_threshold,
-            single_class=single_class,
             session=session,
             state=state,
         )
@@ -589,8 +570,7 @@ class TaxonomyClassifierAgent(AgentBase):
 class _TraversalState:
     """Track recursive traversal state."""
 
-    path: list[ClassificationStep] = field(default_factory=list)
-    path_nodes: list[TaxonomyNode] = field(default_factory=list)
+    steps: list[ClassificationStep] = field(default_factory=list)
     final_nodes: list[TaxonomyNode] = field(default_factory=list)
     best_confidence: float | None = None
     saw_max_depth: bool = False
@@ -612,8 +592,7 @@ def _copy_traversal_state(state: _TraversalState) -> _TraversalState:
         Cloned traversal state with copied collections.
     """
     return _TraversalState(
-        path=list(state.path),
-        path_nodes=list(state.path_nodes),
+        steps=list(state.steps),
         final_nodes=list(state.final_nodes),
         best_confidence=state.best_confidence,
         saw_max_depth=state.saw_max_depth,
@@ -663,6 +642,8 @@ def _normalize_roots(
     list[TaxonomyNode]
         Normalized list of root nodes.
     """
+    if isinstance(taxonomy, Taxonomy):
+        return [node for node in taxonomy.children if node is not None]
     if isinstance(taxonomy, TaxonomyNode):
         return [taxonomy]
     return [node for node in taxonomy if node is not None]
@@ -682,7 +663,7 @@ def _default_template_path() -> Path:
 def _build_context(
     *,
     node_descriptors: Iterable[dict[str, Any]],
-    path: Sequence[ClassificationStep],
+    steps: Sequence[ClassificationStep],
     depth: int,
     context: Optional[Dict[str, Any]],
 ) -> Dict[str, Any]:
@@ -692,7 +673,7 @@ def _build_context(
     ----------
     node_descriptors : Iterable[dict[str, Any]]
         Node descriptors available at the current taxonomy level.
-    path : Sequence[ClassificationStep]
+    steps : Sequence[ClassificationStep]
         Steps recorded so far in the traversal.
     depth : int
         Current traversal depth.
@@ -704,9 +685,14 @@ def _build_context(
     dict[str, Any]
         Context dictionary for prompt rendering.
     """
+    summarized_steps = [
+        step.as_summary()
+        for step in steps
+        if step.selected_nodes and any(node is not None for node in step.selected_nodes)
+    ]
     template_context: Dict[str, Any] = {
         "taxonomy_nodes": list(node_descriptors),
-        "path": [step.as_summary() for step in path],
+        "steps": summarized_steps,
         "depth": depth,
     }
     if context:
@@ -754,7 +740,7 @@ def _build_node_path_map(
     path_map: dict[str, TaxonomyNode] = {}
     seen: dict[str, int] = {}
     for node in nodes:
-        base_path = _format_path_identifier([*parent_path, node.label])
+        base_path = format_path_identifier([*parent_path, node.label])
         count = seen.get(base_path, 0) + 1
         seen[base_path] = count
         path = f"{base_path} ({count})" if count > 1 else base_path
@@ -783,33 +769,12 @@ def _build_node_descriptors(
             {
                 "identifier": path_id,
                 "label": node.label,
-                "description": node.description,
+                "computed_description": node.computed_description,
             }
         )
     return descriptors
 
 
-def _format_path_identifier(path_segments: Sequence[str]) -> str:
-    """Format path segments into a safe identifier string.
-
-    Parameters
-    ----------
-    path_segments : Sequence[str]
-        Path segments to format.
-
-    Returns
-    -------
-    str
-        Escaped path identifier string.
-    """
-    delimiter = " > "
-    escape_token = "\\>"
-    escaped_segments = [
-        segment.replace(delimiter, escape_token) for segment in path_segments
-    ]
-    return delimiter.join(escaped_segments)
-
-
 def _build_taxonomy_enum(name: str, values: Sequence[str]) -> type[Enum]:
     """Build a safe Enum from taxonomy node values.
 
@@ -834,25 +799,6 @@ def _build_taxonomy_enum(name: str, values: Sequence[str]) -> type[Enum]:
     return cast(type[Enum], Enum(name, members))
 
 
-def _split_taxonomy_path(value: str) -> list[str]:
-    """Split a taxonomy identifier into its path segments.
-
-    Parameters
-    ----------
-    value : str
-        Taxonomy path identifier to split.
-
-    Returns
-    -------
-    list[str]
-        Path segments with escaped delimiters restored.
-    """
-    delimiter = " > "
-    escape_token = "\\>"
-    segments = value.split(delimiter)
-    return [segment.replace(escape_token, delimiter) for segment in segments]
-
-
 def _sanitize_enum_member(
     value: str,
     index: int,
@@ -875,7 +821,7 @@ def _sanitize_enum_member(
         Sanitized enum member name.
     """
     normalized_segments: list[str] = []
-    for segment in _split_taxonomy_path(value):
+    for segment in split_path_identifier(value):
         normalized = re.sub(r"[^0-9a-zA-Z]+", "_", segment).strip("_").upper()
         if not normalized:
             normalized = "VALUE"
@@ -933,7 +879,9 @@ def _build_input_payload(
     str or list[dict[str, Any]]
         Input payload suitable for the Agents SDK.
     """
-    normalized_file_ids = [file_id for file_id in ensure_list(file_ids) if file_id]
+    normalized_file_ids = [
+        file_id for file_id in dict.fromkeys(ensure_list(file_ids)) if file_id
+    ]
     if not normalized_file_ids:
         return text
     attachments = [
@@ -1038,17 +986,20 @@ def _selected_nodes(step: ClassificationStep) -> list[str]:
     list[str]
         Selected identifiers in priority order.
     """
-    if step.selected_nodes is not None:
-        selected_nodes = [
-            str(_normalize_enum_value(selected_node, Enum))
-            for selected_node in step.selected_nodes
-            if selected_node
-        ]
-        if selected_nodes:
-            return selected_nodes
-    if step.selected_node:
-        return [str(_normalize_enum_value(step.selected_node, Enum))]
-    return []
+    enum_cls: type[Enum] | None = None
+    step_cls = step.__class__
+    if hasattr(step_cls, "model_fields"):
+        field = step_cls.model_fields.get("selected_nodes")
+        if field is not None:
+            enum_cls = step_cls._extract_enum_class(field.annotation)
+    if enum_cls is None:
+        enum_cls = Enum
+    selected_nodes = [
+        str(_normalize_enum_value(selected_node, enum_cls))
+        for selected_node in step.selected_nodes or []
+        if selected_node
+    ]
+    return selected_nodes
 
 
 def _max_confidence(

{openai_sdk_helpers-0.6.2 → openai_sdk_helpers-0.6.5}/src/openai_sdk_helpers/prompt/classifier.jinja

@@ -3,7 +3,6 @@ You are a taxonomy classification assistant.
 Instructions:
 - Review the text and select all matching taxonomy nodes from the list.
 - Populate selected_nodes as a list of taxonomy node ids for multi-class matches.
-- Use selected_node when a single best match is appropriate.
 - Provide a confidence score between 0 and 1 for the selections; higher means more certain.
 - Interpret confidence as:
   - 0.90–1.00: explicit lexical match.
@@ -30,10 +29,10 @@ Instructions:
 
 Current depth: {{ depth }}
 
-Previous path:
-{% if path %}
-{% for step in path %}
-- {{ step.selected_node }} (confidence={{ step.confidence }}, stop_reason={{ step.stop_reason }})
+Previous steps:
+{% if steps %}
+{% for step in steps %}
+- {{ step.selected_nodes | map('string') | join(', ') }} (confidence={{ step.confidence }}, stop_reason={{ step.stop_reason }})
 {% endfor %}
 {% else %}
 - None
@@ -43,5 +42,5 @@ Candidate taxonomy nodes:
 {% for node in taxonomy_nodes %}
 - identifier: {{ node.identifier }}
   label: {{ node.label }}
-  description: {{ node.description or "None" }}
+  description: {{ node.computed_description }}
 {% endfor %}

{openai_sdk_helpers-0.6.2 → openai_sdk_helpers-0.6.5}/src/openai_sdk_helpers/structure/__init__.py

@@ -82,7 +82,8 @@ from .classification import (
     ClassificationStopReason,
     Taxonomy,
     TaxonomyNode,
-    flatten_taxonomy,
+    format_path_identifier,
+    split_path_identifier,
     taxonomy_enum_path,
 )
 from .extraction import (
@@ -112,7 +113,8 @@ __all__ = [
     "ClassificationStopReason",
     "Taxonomy",
     "TaxonomyNode",
-    "flatten_taxonomy",
+    "format_path_identifier",
+    "split_path_identifier",
     "taxonomy_enum_path",
     "TaskStructure",
     "PlanStructure",

{openai_sdk_helpers-0.6.2 → openai_sdk_helpers-0.6.5}/src/openai_sdk_helpers/structure/base.py

@@ -174,6 +174,100 @@ def _ensure_schema_has_type(schema: dict[str, Any]) -> None:
     schema.update(_build_any_value_schema())
 
 
+def _strip_ref_types(
+    schema: dict[str, Any],
+    *,
+    nullable_fields: set[str] | None = None,
+) -> None:
+    """Remove type entries from enum $ref nodes when non-nullable.
+
+    Parameters
+    ----------
+    schema : dict[str, Any]
+        Root schema to clean in place.
+    nullable_fields : set[str] | None, optional
+        Field names that should remain nullable. Defaults to None.
+    """
+    field_names = nullable_fields or set()
+
+    def _resolve_ref(ref: str) -> dict[str, Any] | None:
+        if not ref.startswith("#/"):
+            return None
+        pointer = ref.removeprefix("#/")
+        current: Any = schema
+        for part in pointer.split("/"):
+            if not isinstance(current, dict):
+                return None
+            current = current.get(part)
+        if isinstance(current, dict):
+            return current
+        return None
+
+    def _is_enum_ref(ref: str) -> bool:
+        ref_target = _resolve_ref(ref)
+        if not isinstance(ref_target, dict):
+            return False
+        return "enum" in ref_target
+
+    def _is_null_schema(entry: Any) -> bool:
+        if not isinstance(entry, dict):
+            return False
+        entry_type = entry.get("type")
+        if entry_type == "null":
+            return True
+        if isinstance(entry_type, list) and "null" in entry_type:
+            return True
+        return False
+
+    def _walk(
+        node: Any,
+        *,
+        nullable_context: bool = False,
+        nullable_property: bool = False,
+    ) -> None:
+        if isinstance(node, dict):
+            ref = node.get("$ref")
+            if (
+                isinstance(ref, str)
+                and _is_enum_ref(ref)
+                and not nullable_context
+                and not nullable_property
+            ):
+                node.pop("type", None)
+            for key, value in node.items():
+                if key == "anyOf" and isinstance(value, list):
+                    anyof_nullable = any(_is_null_schema(entry) for entry in value)
+                    for entry in value:
+                        _walk(
+                            entry,
+                            nullable_context=anyof_nullable or nullable_context,
+                            nullable_property=nullable_property,
+                        )
+                    continue
+                if key == "properties" and isinstance(value, dict):
+                    for prop_name, prop_schema in value.items():
+                        _walk(
+                            prop_schema,
+                            nullable_context=nullable_context,
+                            nullable_property=prop_name in field_names,
+                        )
+                    continue
+                _walk(
+                    value,
+                    nullable_context=nullable_context,
+                    nullable_property=nullable_property,
+                )
+        elif isinstance(node, list):
+            for item in node:
+                _walk(
+                    item,
+                    nullable_context=nullable_context,
+                    nullable_property=nullable_property,
+                )
+
+    _walk(schema)
+
+
 def _hydrate_ref_types(schema: dict[str, Any]) -> None:
     """Attach explicit types to $ref nodes when available.
 
@@ -556,17 +650,18 @@ class StructureBase(BaseModelJSONSerializable):
 
         cleaned_schema = cast(dict[str, Any], clean_refs(schema))
 
-        cleaned_schema = cast(dict[str, Any], cleaned_schema)
-        _hydrate_ref_types(cleaned_schema)
-        _ensure_items_have_schema(cleaned_schema)
-        _ensure_schema_has_type(cleaned_schema)
-
         nullable_fields = {
             name
             for name, model_field in getattr(cls, "model_fields", {}).items()
             if getattr(model_field, "default", inspect.Signature.empty) is None
         }
 
+        cleaned_schema = cast(dict[str, Any], cleaned_schema)
+        _hydrate_ref_types(cleaned_schema)
+        _ensure_items_have_schema(cleaned_schema)
+        _ensure_schema_has_type(cleaned_schema)
+        _strip_ref_types(cleaned_schema, nullable_fields=nullable_fields)
+
         properties = cleaned_schema.get("properties", {})
         if isinstance(properties, dict) and nullable_fields:
             for field_name in nullable_fields: