openai-sdk-helpers 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

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/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/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/structure/classification.py

@@ -3,7 +3,10 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Iterable, Optional, cast
+from typing import Any, Iterable, Optional, Sequence, cast
+
+PATH_DELIMITER = " > "
+PATH_ESCAPE_TOKEN = "\\>"
 
 from .base import StructureBase, spec_field
 
@@ -30,18 +33,26 @@ class TaxonomyNode(StructureBase):
         Return True when the taxonomy node has no children.
     child_by_path(path)
         Return the child node matching the provided path.
+    path_identifier
+        Return the path identifier string for the node.
+    keywords
+        Return a list of keywords for the node.
+    computed_description
+        Return the computed description for the node.
+    flattened_nodes
+        Return a flattened list of all taxonomy nodes.
     """
 
     label: str = spec_field(
-        "label", description="Human-readable label for the taxonomy node."
+        name="label", description="Human-readable label for the taxonomy node."
     )
     description: str | None = spec_field(
-        "description",
+        name="description",
         description="Optional description of the taxonomy node.",
         default=None,
     )
     children: list["TaxonomyNode"] = spec_field(
-        "children",
+        name="children",
         description="Child nodes in the taxonomy.",
         default_factory=list,
     )
@@ -103,7 +114,7 @@ class TaxonomyNode(StructureBase):
         if path is None:
             return None
         if isinstance(path, str):
-            path_segments = _split_path_identifier(path)
+            path_segments = split_path_identifier(path)
         else:
             path_segments = list(path)
         last_segment = path_segments[-1] if path_segments else None
@@ -114,50 +125,142 @@ class TaxonomyNode(StructureBase):
             None,
         )
 
+    @property
+    def path_identifier(self) -> str:
+        """Return the path identifier string for this node.
+
+        Returns
+        -------
+        str
+            Delimited path identifier.
+        """
+        return format_path_identifier(self.computed_path)
+
+    @property
+    def keywords(self) -> list[str]:
+        """Return a list of keywords for this node.
+
+        Returns
+        -------
+        list[str]
+            Unique list of keywords derived from the node and descendants.
+        """
+        keywords = [self.label]
+        for child in self.children:
+            keywords.extend(child.keywords)
+        return list(dict.fromkeys(filter(None, keywords)))
+
+    @property
+    def computed_description(self) -> str:
+        """Return the computed description for this node.
+
+        Returns
+        -------
+        str
+            Node description with optional keyword context.
+        """
+        keywords = self.keywords
+        base = self.description or self.label
+        if len(keywords) == 1 and keywords[0] == self.label:
+            return base
+        if keywords:
+            return f"{base}\nKeywords: {', '.join(keywords)}"
+        return base
+
+    @property
+    def flattened_nodes(self) -> list[TaxonomyNode]:
+        """Return a flattened list of all taxonomy nodes.
+
+        Returns
+        -------
+        list[TaxonomyNode]
+            Depth-first list of taxonomy nodes.
+        """
+        flattened: list[TaxonomyNode] = []
+        for node in self.children:
+            flattened.append(node)
+            flattened.extend(node.flattened_nodes)
+        return flattened
+
 
-class Taxonomy(StructureBase):
+class Taxonomy(TaxonomyNode):
     """Represent a taxonomy with metadata and root nodes.
 
     Attributes
     ----------
-    name : str
+    label : str
         Human-readable taxonomy name.
     description : str | None
         Optional description of the taxonomy.
-    nodes : list[TaxonomyNode]
+    children : list[TaxonomyNode]
         Root taxonomy nodes.
 
     Methods
     -------
+    root(label, *children)
+        Create a taxonomy from root nodes.
+    build_path(parent_path)
+        Build a computed path using the provided parent path segments.
+    computed_path
+        Return the computed path for the node.
+    is_leaf
+        Return True when the taxonomy node has no children.
+    child_by_path(path)
+        Return the child node matching the provided path.
+    path_identifier
+        Return the path identifier string for the node.
+    keywords
+        Return a list of keywords for the node.
+    computed_description
+        Return the computed description for the node.
     flattened_nodes
         Return a flattened list of all taxonomy nodes.
     """
 
-    name: str = spec_field("name", description="Human-readable taxonomy name.")
-    description: str | None = spec_field(
-        "description",
-        description="Optional description of the taxonomy.",
-        default=None,
-    )
-    nodes: list[TaxonomyNode] = spec_field(
-        "nodes",
-        description="Root taxonomy nodes.",
-        default_factory=list,
-    )
+    def __init__(
+        self,
+        *,
+        label: str,
+        description: str | None = None,
+        children: list[TaxonomyNode] | None = None,
+    ) -> None:
+        """Initialize a taxonomy with name and root nodes.
 
-    @property
-    def flattened_nodes(self) -> list[TaxonomyNode]:
-        """Return a flattened list of all taxonomy nodes.
+        Parameters
+        ----------
+        label : str
+            Human-readable taxonomy name.
+        description : str or None, default=None
+            Optional description of the taxonomy.
+        children : list[TaxonomyNode] or None, default=None
+            Root taxonomy nodes. Defaults to an empty list.
+        """
+        super().__init__(
+            label=label,
+            description=description,
+            children=children or [],
+        )
+
+    @classmethod
+    def root(cls, label: str, *children: TaxonomyNode) -> "Taxonomy":
+        """Create a taxonomy from root nodes.
+
+        Parameters
+        ----------
+        label : str
+            Human-readable taxonomy name.
+        *children : TaxonomyNode
+            Root taxonomy nodes.
 
         Returns
         -------
-        list[TaxonomyNode]
-            Depth-first list of taxonomy nodes.
+        Taxonomy
+            Taxonomy instance with provided root nodes.
         """
-        return flatten_taxonomy(self.nodes)
+        return cls(label=label, children=list(children))
 
 
-def _split_path_identifier(path: str) -> list[str]:
+def split_path_identifier(path: str) -> list[str]:
     """Split a path identifier into label segments.
 
     Parameters
@@ -170,10 +273,27 @@ def _split_path_identifier(path: str) -> list[str]:
     list[str]
         Label segments extracted from the path identifier.
     """
-    delimiter = " > "
-    escape_token = "\\>"
-    segments = path.split(delimiter) if path else []
-    return [segment.replace(escape_token, delimiter) for segment in segments]
+    segments = path.split(PATH_DELIMITER) if path else []
+    return [segment.replace(PATH_ESCAPE_TOKEN, PATH_DELIMITER) for segment in segments]
+
+
+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.
+    """
+    escaped_segments = [
+        segment.replace(PATH_DELIMITER, PATH_ESCAPE_TOKEN) for segment in path_segments
+    ]
+    return PATH_DELIMITER.join(escaped_segments)
 
 
 class ClassificationStopReason(str, Enum):
@@ -213,8 +333,6 @@ class ClassificationStep(StructureBase):
 
     Attributes
     ----------
-    selected_node : Enum or None
-        Enum value of the selected taxonomy node.
     selected_nodes : list[Enum] or None
         Enum values of selected taxonomy nodes for multi-class classification.
     confidence : float or None
@@ -246,11 +364,6 @@ class ClassificationStep(StructureBase):
     [<NodeEnum.BILLING: 'billing'>]
     """
 
-    selected_node: Enum | None = spec_field(
-        "selected_node",
-        description="Path identifier of the selected taxonomy node.",
-        default=None,
-    )
     selected_nodes: list[Enum] | None = spec_field(
         "selected_nodes",
         description="Path identifiers of selected taxonomy nodes.",
@@ -289,14 +402,8 @@ class ClassificationStep(StructureBase):
         """
         namespace: dict[str, Any] = {
             "__annotations__": {
-                "selected_node": enum_cls | None,
                 "selected_nodes": list[enum_cls] | None,
             },
-            "selected_node": spec_field(
-                "selected_node",
-                description="Path identifier of the selected taxonomy node.",
-                default=None,
-            ),
             "selected_nodes": spec_field(
                 "selected_nodes",
                 description="Path identifiers of selected taxonomy nodes.",
@@ -317,16 +424,14 @@ class ClassificationStep(StructureBase):
         --------
         >>> NodeEnum = Enum("NodeEnum", {"ROOT": "root"})
         >>> StepEnum = ClassificationStep.build_for_enum(NodeEnum)
-        >>> step = StepEnum(selected_node=NodeEnum.ROOT)
-        >>> step.as_summary()["selected_node"]
-        <NodeEnum.ROOT: 'root'>
+        >>> step = StepEnum(selected_nodes=[NodeEnum.ROOT])
+        >>> step.as_summary()["selected_nodes"]
+        [<NodeEnum.ROOT: 'root'>]
         """
-        selected_node = _normalize_enum_value(self.selected_node)
         selected_nodes = [
             _normalize_enum_value(item) for item in self.selected_nodes or []
         ]
         return {
-            "selected_node": selected_node,
             "selected_nodes": selected_nodes or None,
             "confidence": self.confidence,
             "stop_reason": self.stop_reason.value,
@@ -356,25 +461,25 @@ class ClassificationResult(StructureBase):
 
     Attributes
     ----------
-    final_node : TaxonomyNode or None
-        Resolved taxonomy node for the final selection.
     final_nodes : list[TaxonomyNode] or None
         Resolved taxonomy nodes for the final selections across branches.
     confidence : float or None
         Confidence score for the final selection.
     stop_reason : ClassificationStopReason
         Reason the traversal ended.
-    path : list[ClassificationStep]
+    steps : list[ClassificationStep]
         Ordered list of classification steps.
-    path_nodes : list[TaxonomyNode]
-        Resolved taxonomy nodes selected across the path.
 
     Methods
     -------
     depth
         Return the number of classification steps recorded.
-    path_identifiers
-        Return the identifiers selected at each step.
+    final_node
+        Return the first resolved taxonomy node, if available.
+    iter_selected_nodes
+        Yield selected identifiers across all steps.
+    selected_nodes
+        Return the selected identifiers across all steps.
 
     Examples
     --------
@@ -382,7 +487,6 @@ class ClassificationResult(StructureBase):
 
     >>> node = TaxonomyNode(label="Tax")
     >>> result = ClassificationResult(
-    ...     final_node=node,
     ...     final_nodes=[node],
     ...     confidence=0.91,
     ...     stop_reason=ClassificationStopReason.STOP,
@@ -391,11 +495,6 @@ class ClassificationResult(StructureBase):
     [TaxonomyNode(label='Tax', description=None, children=[])]
     """
 
-    final_node: TaxonomyNode | None = spec_field(
-        "final_node",
-        description="Resolved taxonomy node for the final selection.",
-        default=None,
-    )
     final_nodes: list[TaxonomyNode] | None = spec_field(
         "final_nodes",
         description="Resolved taxonomy nodes for the final selections.",
@@ -411,16 +510,11 @@ class ClassificationResult(StructureBase):
         description="Reason the traversal ended.",
         default=ClassificationStopReason.STOP,
     )
-    path: list[ClassificationStep] = spec_field(
-        "path",
+    steps: list[ClassificationStep] = spec_field(
+        "steps",
         description="Ordered list of classification steps.",
         default_factory=list,
     )
-    path_nodes: list[TaxonomyNode] = spec_field(
-        "path_nodes",
-        description="Resolved taxonomy nodes selected across the path.",
-        default_factory=list,
-    )
 
     @property
     def depth(self) -> int:
@@ -431,59 +525,45 @@ class ClassificationResult(StructureBase):
         int
             Count of classification steps.
         """
-        return len(self.path)
+        return len(self.steps)
 
     @property
-    def path_identifiers(self) -> list[str]:
-        """Return the identifiers selected at each step.
+    def final_node(self) -> TaxonomyNode | None:
+        """Return the first resolved taxonomy node.
 
         Returns
         -------
-        list[str]
-            Identifiers selected at each classification step.
-
-        Examples
-        --------
-        >>> steps = [
-        ...     ClassificationStep(selected_node="Root"),
-        ...     ClassificationStep(selected_nodes=["Root > Leaf", "Root > Branch"]),
-        ... ]
-        >>> ClassificationResult(
-        ...     stop_reason=ClassificationStopReason.STOP,
-        ...     path=steps,
-        ... ).path_identifiers
-        ['Root', 'Root > Leaf', 'Root > Branch']
+        TaxonomyNode or None
+            First resolved taxonomy node, if available.
         """
-        identifiers: list[str] = []
-        for step in self.path:
-            if step.selected_nodes:
-                identifiers.extend(
-                    _normalize_enum_value(value) for value in step.selected_nodes
-                )
-            elif step.selected_node:
-                identifiers.append(_normalize_enum_value(step.selected_node))
-        return [identifier for identifier in identifiers if identifier]
+        if not self.final_nodes:
+            return None
+        return self.final_nodes[0]
 
+    @property
+    def selected_nodes(self) -> list[str]:
+        """Return the selected identifiers across all steps.
 
-def flatten_taxonomy(nodes: Iterable[TaxonomyNode]) -> list[TaxonomyNode]:
-    """Return a flattened list of taxonomy nodes.
+        Returns
+        -------
+        list[str]
+            Selected identifiers in traversal order.
+        """
+        return list(self.iter_selected_nodes())
 
-    Parameters
-    ----------
-    nodes : Iterable[TaxonomyNode]
-        Root nodes to traverse.
+    def iter_selected_nodes(self) -> Iterable[str]:
+        """Yield selected identifiers across all steps.
 
-    Returns
-    -------
-    list[TaxonomyNode]
-        Depth-first ordered list of nodes.
-    """
-    flattened: list[TaxonomyNode] = []
-    for node in nodes:
-        flattened.append(node)
-        if node.children:
-            flattened.extend(flatten_taxonomy(node.children))
-    return flattened
+        Yields
+        ------
+        str
+            Selected identifier in traversal order.
+        """
+        for step in self.steps:
+            for value in step.selected_nodes or []:
+                normalized = _normalize_enum_value(value)
+                if normalized:
+                    yield normalized
 
 
 def taxonomy_enum_path(value: Enum | str | None) -> list[str]:
@@ -513,7 +593,7 @@ def taxonomy_enum_path(value: Enum | str | None) -> list[str]:
         return []
     if not isinstance(normalized_value, str):
         normalized_value = str(normalized_value)
-    return _split_path_identifier(normalized_value)
+    return split_path_identifier(normalized_value)
 
 
 __all__ = [
@@ -522,6 +602,7 @@ __all__ = [
     "ClassificationStopReason",
     "Taxonomy",
     "TaxonomyNode",
-    "flatten_taxonomy",
+    "format_path_identifier",
+    "split_path_identifier",
     "taxonomy_enum_path",
 ]

{openai_sdk_helpers-0.6.2.dist-info → openai_sdk_helpers-0.6.4.dist-info}/METADATA

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

{openai_sdk_helpers-0.6.2.dist-info → openai_sdk_helpers-0.6.4.dist-info}/RECORD

@@ -10,7 +10,7 @@ openai_sdk_helpers/tools.py,sha256=8hhcytpmDfoXV16UQbDmDVV0rhLOn8c_VjXO8XaTFLQ,1
 openai_sdk_helpers/types.py,sha256=ejCG0rYqJhjOQvKLoNnzq-TzcKCFt69GVfi7y805NkU,1451
 openai_sdk_helpers/agent/__init__.py,sha256=qyzKzPhD8KsEl6d79XERK32AK5It_BZNOqChOpBdmhg,1199
 openai_sdk_helpers/agent/base.py,sha256=vLs0oALhxsd_Xy5dGjSZTUFTug-YwZkF1LabQ2ruLxk,29508
-openai_sdk_helpers/agent/classifier.py,sha256=GWgjQxkh1QbZhKlcDCkj-aNgpa8seJWxTfbtXyQSkSg,34889
+openai_sdk_helpers/agent/classifier.py,sha256=PHUnA5dSDWBQeRxwo0Qe8xIe7Ren3xSRAOmsQrRK_oA,33241
 openai_sdk_helpers/agent/configuration.py,sha256=ZeH4ErgVe-BZamjUeNONbQi60ViolgYAWh-c8hNAQTw,15810
 openai_sdk_helpers/agent/coordinator.py,sha256=lVjA0yI-GhGKlqbNR_k9GOCrUjFoZ0QoqRaafHckyME,18052
 openai_sdk_helpers/agent/files.py,sha256=H7UfSZSjFUbv1cjRvNld9kZwIjc5wPq4vynqU8HgGJE,4478
@@ -30,7 +30,7 @@ openai_sdk_helpers/extract/extractor.py,sha256=vmRJyhKDEYAVfRk0KMgLH5hTqUfDAUyWB
 openai_sdk_helpers/extract/generator.py,sha256=K9Euq0IaWs82oe5aRm73_18DelLKYyuH8VhfZ1_ZCEU,14695
 openai_sdk_helpers/prompt/__init__.py,sha256=MOqgKwG9KLqKudoKRlUfLxiSmdOi2aD6hNrWDFqLHkk,418
 openai_sdk_helpers/prompt/base.py,sha256=6X0zeopEvO0ba8207O8Nnj1QvFZEZier7kNNh4qkcmE,7782
-openai_sdk_helpers/prompt/classifier.jinja,sha256=6od2DyyEUUrT0AmeJfJ57gJxJ6gdbPc11vff-VNywNk,1895
+openai_sdk_helpers/prompt/classifier.jinja,sha256=u4gTwImOdKHu9qRdnnhl2aX23ns2THYYh6l8bc2EeNo,1866
 openai_sdk_helpers/prompt/extractor_config_agent_instructions.jinja,sha256=vCrsoUnsgHWSr7OS_ojMUjmPtHfbyv9bzKfaMaCJ99E,329
 openai_sdk_helpers/prompt/extractor_config_generator.jinja,sha256=9rZ1PZdoQtnxDxFUlKRb0SooIEfNw4_Em99n9xvFyyU,960
 openai_sdk_helpers/prompt/extractor_config_generator_instructions.jinja,sha256=GqV3DrGObyER_Fa-GMGGqhWBrQIH9FFlyKdgTjidyzg,534
@@ -55,10 +55,10 @@ openai_sdk_helpers/response/vector_store.py,sha256=HClp6O_g20uklQTY7trC4age3rtDm
 openai_sdk_helpers/streamlit_app/__init__.py,sha256=3yAkl6qV71cqtT5YFZuC9Bkqit0NtffDV6jmMWpT1k4,812
 openai_sdk_helpers/streamlit_app/app.py,sha256=kkjtdCKVwrJ9nZWuBArm3dhvcjMESX0TMqAiF61_JLM,17402
 openai_sdk_helpers/streamlit_app/configuration.py,sha256=0KeJ4HqCNFthBHsedV6ptqHluAcTPBb5_TujFOGkIUU,16685
-openai_sdk_helpers/structure/__init__.py,sha256=ErtNlTADV4cc7s27i_CbQATd2PD9xcJd8_D273QmyOI,4253
+openai_sdk_helpers/structure/__init__.py,sha256=w27ezTYVLzZdDMFfA8mawE82h8zO53idFBCiCfYfh7s,4321
 openai_sdk_helpers/structure/agent_blueprint.py,sha256=VyJWkgPNzAYKRDMeR1M4kE6qqQURnwqtrrEn0TRJf0g,9698
 openai_sdk_helpers/structure/base.py,sha256=UrnNNU9qQ9mEES8MB9y6QESbDgPXH47XW8LVWSxYUYM,25280
-openai_sdk_helpers/structure/classification.py,sha256=Vk7LGG3pty5T0Eh94Pao7kWY8_Wcuw37ywdPDcnElrg,15316
+openai_sdk_helpers/structure/classification.py,sha256=SYrrsv0Y2A2kXhL3jbn7lWnTb5jB_UE-cx-sJSRCxEA,17312
 openai_sdk_helpers/structure/extraction.py,sha256=wODP0iLAhhsdQkMWRYPYTiLUMU8bFMKiBjPl3PKUleg,37335
 openai_sdk_helpers/structure/prompt.py,sha256=ZfsaHdA0hj5zmZDrOdpXjCsC8U-jjzwFG4JBsWYiaH4,1535
 openai_sdk_helpers/structure/responses.py,sha256=WUwh0DhXj24pkvgqH1FMkdx5V2ArdvdtrDN_fuMBtDU,4882
@@ -92,8 +92,8 @@ openai_sdk_helpers/vector_storage/__init__.py,sha256=L5LxO09puh9_yBB9IDTvc1CvVkA
 openai_sdk_helpers/vector_storage/cleanup.py,sha256=sZ4ZSTlnjF52o9Cc8A9dTX37ZYXXDxS_fdIpoOBWvrg,3666
 openai_sdk_helpers/vector_storage/storage.py,sha256=t_ukacaXRa9EXE4-3BxsrB4Rjhu6nTu7NA9IjCJBIpQ,24259
 openai_sdk_helpers/vector_storage/types.py,sha256=jTCcOYMeOpZWvcse0z4T3MVs-RBOPC-fqWTBeQrgafU,1639
-openai_sdk_helpers-0.6.2.dist-info/METADATA,sha256=TGZjA_nQ2FDm9KeEjun4MrIAUl-zAxB-Xi5UCUkn8nY,24622
-openai_sdk_helpers-0.6.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.6.2.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
-openai_sdk_helpers-0.6.2.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.6.2.dist-info/RECORD,,
+openai_sdk_helpers-0.6.4.dist-info/METADATA,sha256=l5XBsVFPOrOSDskGR0ZhgKHjJFLtO_-ZgWrRjXi1_bU,24622
+openai_sdk_helpers-0.6.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.6.4.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
+openai_sdk_helpers-0.6.4.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.6.4.dist-info/RECORD,,