openai-sdk-helpers 0.5.2__py3-none-any.whl → 0.6.1__py3-none-any.whl

openai_sdk_helpers/prompt/classifier.jinja

@@ -0,0 +1,31 @@
+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.
+- Use only taxonomy identifiers from the candidate list for any selections.
+- Use the stop_reason enum values only: "continue", "stop", "no_match", "max_depth", "no_children".
+- If a child level should be explored, set stop_reason to "continue".
+- If no appropriate node exists, set stop_reason to "no_match" and leave selections empty.
+- If you are confident this is the final level, set stop_reason to "stop".
+- Provide a concise rationale in one or two sentences.
+
+Current depth: {{ depth }}
+
+Previous path:
+{% if path %}
+{% for step in path %}
+- {{ step.selected_node }} (confidence={{ step.confidence }}, stop_reason={{ step.stop_reason }})
+{% endfor %}
+{% else %}
+- None
+{% endif %}
+
+Candidate taxonomy nodes:
+{% for node in taxonomy_nodes %}
+- identifier: {{ node.identifier }}
+  label: {{ node.label }}
+  description: {{ node.description or "None" }}
+{% endfor %}

openai_sdk_helpers/response/base.py

@@ -509,6 +509,7 @@ 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.
 
@@ -531,6 +532,9 @@ 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
         -------
@@ -621,7 +625,8 @@ class ResponseBase(Generic[T]):
                         self.messages.add_tool_message(
                             content=response_output, output=tool_output
                         )
-                        self.save()
+                        if save_messages:
+                            self.save()
                     except Exception as exc:
                         log(
                             f"Error executing tool handler '{tool_name}': {exc}",
@@ -646,7 +651,8 @@ class ResponseBase(Generic[T]):
                     self.messages.add_assistant_message(
                         response_output, metadata=kwargs
                     )
-                    self.save()
+                    if save_messages:
+                        self.save()
                     if hasattr(response, "output_text") and response.output_text:
                         raw_text = response.output_text
                         log("No tool call. Parsing output_text.")
@@ -682,6 +688,7 @@ 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.
 
@@ -704,6 +711,9 @@ 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
         -------
@@ -739,6 +749,7 @@ class ResponseBase(Generic[T]):
                 content=content,
                 files=files,
                 use_vector_store=use_vector_store,
+                save_messages=save_messages,
             )
 
         try:
@@ -871,9 +882,11 @@ class ResponseBase(Generic[T]):
 
         Notes
         -----
-        If no filepath is provided, the save operation always writes to
-        the session data path (data_path / name / uuid.json). The data path
-        is configured during initialization and defaults to get_data_path().
+        If no filepath is provided, the save operation writes to the
+        session data path. If the configured data path already ends with
+        the response name, it writes to data_path / uuid.json. Otherwise,
+        it writes to data_path / name / uuid.json. The data path is
+        configured during initialization and defaults to get_data_path().
 
         Raises
         ------
@@ -889,7 +902,7 @@ class ResponseBase(Generic[T]):
             target = Path(filepath)
         else:
             filename = f"{str(self.uuid).lower()}.json"
-            target = self._data_path / self._name / filename
+            target = self._session_path(filename)
 
         checked = check_filepath(filepath=target)
         self.messages.to_json_file(str(checked))
@@ -919,12 +932,18 @@ class ResponseBase(Generic[T]):
             traceback.format_exception(type(exc), exc, exc.__traceback__)
         )
         filename = f"{str(self.uuid).lower()}_error.txt"
-        target = self._data_path / self._name / filename
+        target = self._session_path(filename)
         checked = check_filepath(filepath=target)
         checked.write_text(error_text, encoding="utf-8")
         log(f"Saved error details to {checked}")
         return checked
 
+    def _session_path(self, filename: str) -> Path:
+        """Return the resolved session filepath for a given filename."""
+        if self._data_path.name == self._name:
+            return self._data_path / filename
+        return self._data_path / self._name / filename
+
     def __repr__(self) -> str:
         """Return a detailed string representation of the response session.
 

openai_sdk_helpers/settings.py

@@ -48,6 +48,8 @@ class OpenAISettings(BaseModel):
     -------
     from_env(dotenv_path, **overrides)
         Build settings from environment variables and optional overrides.
+    from_secrets(secrets, **overrides)
+        Build settings from a secrets mapping and optional overrides.
     client_kwargs()
         Return keyword arguments for ``OpenAI`` initialization.
     create_client()
@@ -190,6 +192,69 @@ class OpenAISettings(BaseModel):
 
         return settings
 
+    @classmethod
+    def from_secrets(
+        cls,
+        secrets: Mapping[str, Any] | None = None,
+        **overrides: Any,
+    ) -> OpenAISettings:
+        """Load settings from a secrets mapping and optional overrides.
+
+        Parameters
+        ----------
+        secrets : Mapping[str, Any] or None, optional
+            Mapping of secret values keyed by environment variable names.
+            Defaults to environment variables.
+        overrides : Any
+            Keyword overrides applied on top of secret values.
+
+        Returns
+        -------
+        OpenAISettings
+            Settings instance populated from secret values and overrides.
+
+        Raises
+        ------
+        ValueError
+            If OPENAI_API_KEY is not found in the secrets mapping.
+        """
+        secret_values: Mapping[str, Any] = secrets or os.environ
+
+        def first_non_none(*candidates: Any) -> Any:
+            for candidate in candidates:
+                if candidate is not None:
+                    return candidate
+            return None
+
+        def resolve_value(override_key: str, secret_key: str) -> Any:
+            return first_non_none(
+                overrides.get(override_key),
+                secret_values.get(secret_key),
+            )
+
+        timeout_raw = resolve_value("timeout", "OPENAI_TIMEOUT")
+        max_retries_raw = resolve_value("max_retries", "OPENAI_MAX_RETRIES")
+
+        values: dict[str, Any] = {
+            "api_key": resolve_value("api_key", "OPENAI_API_KEY"),
+            "org_id": resolve_value("org_id", "OPENAI_ORG_ID"),
+            "project_id": resolve_value("project_id", "OPENAI_PROJECT_ID"),
+            "base_url": resolve_value("base_url", "OPENAI_BASE_URL"),
+            "default_model": resolve_value("default_model", "OPENAI_MODEL"),
+            "timeout": coerce_optional_float(timeout_raw),
+            "max_retries": coerce_optional_int(max_retries_raw),
+            "extra_client_kwargs": coerce_dict(overrides.get("extra_client_kwargs")),
+        }
+
+        settings = cls(**values)
+        if not settings.api_key:
+            raise ValueError(
+                "OPENAI_API_KEY is required to configure the OpenAI client"
+                " and was not found in secrets."
+            )
+
+        return settings
+
     def client_kwargs(self) -> dict[str, Any]:
         """Return keyword arguments for constructing an OpenAI client.
 

openai_sdk_helpers/structure/__init__.py

@@ -76,6 +76,13 @@ from __future__ import annotations
 
 from .agent_blueprint import AgentBlueprint
 from .base import *
+from .classification import (
+    ClassificationResult,
+    ClassificationStep,
+    ClassificationStopReason,
+    TaxonomyNode,
+    flatten_taxonomy,
+)
 from .extraction import (
     AnnotatedDocumentStructure,
     AttributeStructure,
@@ -98,6 +105,11 @@ __all__ = [
     "spec_field",
     "AgentBlueprint",
     "AgentEnum",
+    "ClassificationResult",
+    "ClassificationStep",
+    "ClassificationStopReason",
+    "TaxonomyNode",
+    "flatten_taxonomy",
     "TaskStructure",
     "PlanStructure",
     "create_plan",

openai_sdk_helpers/structure/base.py

@@ -134,9 +134,21 @@ def _ensure_items_have_schema(target: Any) -> None:
 
 def _ensure_schema_has_type(schema: dict[str, Any]) -> None:
     """Ensure a schema dictionary includes a type entry when possible."""
+    any_of = schema.get("anyOf")
+    if isinstance(any_of, list):
+        for entry in any_of:
+            if isinstance(entry, dict):
+                _ensure_schema_has_type(entry)
+    properties = schema.get("properties")
+    if isinstance(properties, dict):
+        for value in properties.values():
+            if isinstance(value, dict):
+                _ensure_schema_has_type(value)
+    items = schema.get("items")
+    if isinstance(items, dict):
+        _ensure_schema_has_type(items)
     if "type" in schema or "$ref" in schema:
         return
-    any_of = schema.get("anyOf")
     if isinstance(any_of, list):
         inferred_types: set[str] = set()
         for entry in any_of:
@@ -162,6 +174,68 @@ def _ensure_schema_has_type(schema: dict[str, Any]) -> None:
     schema.update(_build_any_value_schema())
 
 
+def _hydrate_ref_types(schema: dict[str, Any]) -> None:
+    """Attach explicit types to $ref nodes when available.
+
+    Parameters
+    ----------
+    schema : dict[str, Any]
+        Schema dictionary to hydrate in place.
+    """
+    definitions = schema.get("$defs") or schema.get("definitions") or {}
+    if not isinstance(definitions, dict):
+        definitions = {}
+
+    def _infer_enum_type(values: list[Any]) -> list[str] | str | None:
+        type_map = {
+            str: "string",
+            int: "integer",
+            float: "number",
+            bool: "boolean",
+            type(None): "null",
+        }
+        inferred: set[str] = set()
+        for value in values:
+            inferred_type = type_map.get(type(value))
+            if inferred_type is not None:
+                inferred.add(inferred_type)
+        if not inferred:
+            return None
+        if len(inferred) == 1:
+            return next(iter(inferred))
+        return sorted(inferred)
+
+    def _resolve_ref_type(ref: str) -> list[str] | str | None:
+        prefixes = ("#/$defs/", "#/definitions/")
+        if not ref.startswith(prefixes):
+            return None
+        key = ref.split("/", maxsplit=2)[-1]
+        definition = definitions.get(key)
+        if not isinstance(definition, dict):
+            return None
+        ref_type = definition.get("type")
+        if isinstance(ref_type, (str, list)):
+            return ref_type
+        enum_values = definition.get("enum")
+        if isinstance(enum_values, list):
+            return _infer_enum_type(enum_values)
+        return None
+
+    def _walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if "$ref" in node and "type" not in node:
+                ref_type = _resolve_ref_type(node["$ref"])
+                if ref_type is not None:
+                    node["type"] = ref_type
+            for value in node.values():
+                _walk(value)
+        elif isinstance(node, list):
+            for item in node:
+                _walk(item)
+
+    _walk(schema)
+
+
 class StructureBase(BaseModelJSONSerializable):
     """Base class for structured output models with schema generation.
 
@@ -471,7 +545,7 @@ class StructureBase(BaseModelJSONSerializable):
             if isinstance(obj, dict):
                 if "$ref" in obj:
                     for key in list(obj.keys()):
-                        if key != "$ref":
+                        if key not in {"$ref", "type"}:
                             obj.pop(key, None)
                 for v in obj.values():
                     clean_refs(v)
@@ -482,60 +556,10 @@ class StructureBase(BaseModelJSONSerializable):
 
         cleaned_schema = cast(dict[str, Any], clean_refs(schema))
 
-        def _resolve_ref(
-            ref: str,
-            root: dict[str, Any],
-            seen: set[str],
-        ) -> dict[str, Any] | None:
-            if not ref.startswith("#/"):
-                return None
-            if ref in seen:
-                return None
-            seen.add(ref)
-
-            current: Any = root
-            for part in ref.lstrip("#/").split("/"):
-                part = part.replace("~1", "/").replace("~0", "~")
-                if isinstance(current, dict) and part in current:
-                    current = current[part]
-                else:
-                    seen.discard(ref)
-                    return None
-            if isinstance(current, dict):
-                resolved = cast(dict[str, Any], json.loads(json.dumps(current)))
-            else:
-                resolved = None
-            seen.discard(ref)
-            return resolved
-
-        def _inline_anyof_refs(obj: Any, root: dict[str, Any], seen: set[str]) -> Any:
-            if isinstance(obj, dict):
-                updated: dict[str, Any] = {}
-                for key, value in obj.items():
-                    if key == "anyOf" and isinstance(value, list):
-                        updated_items = []
-                        for item in value:
-                            if (
-                                isinstance(item, dict)
-                                and "$ref" in item
-                                and "type" not in item
-                            ):
-                                resolved = _resolve_ref(item["$ref"], root, seen)
-                                if resolved is not None:
-                                    item = resolved
-                            updated_items.append(_inline_anyof_refs(item, root, seen))
-                        updated[key] = updated_items
-                    else:
-                        updated[key] = _inline_anyof_refs(value, root, seen)
-                return updated
-            if isinstance(obj, list):
-                return [_inline_anyof_refs(item, root, seen) for item in obj]
-            return obj
-
-        cleaned_schema = cast(
-            dict[str, Any], _inline_anyof_refs(cleaned_schema, schema, set())
-        )
+        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