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

openai_sdk_helpers/agent/configuration.py

@@ -13,6 +13,7 @@ from ..utils.json.data_class import DataclassJSONSerializable
 from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
 from ..structure.base import StructureBase
+from ..settings import OpenAISettings
 
 
 class AgentRegistry(RegistryBase["AgentConfiguration"]):
@@ -152,6 +153,8 @@ class AgentConfiguration(DataclassJSONSerializable):
         Resolve the prompt template path for this configuration.
     gen_agent(run_context_wrapper)
         Create a AgentBase instance from this configuration.
+    to_openai_settings(dotenv_path=None, **overrides)
+        Build OpenAISettings using this configuration as defaults.
     replace(**changes)
         Create a new AgentConfiguration with specified fields replaced.
     to_json()
@@ -272,6 +275,45 @@ class AgentConfiguration(DataclassJSONSerializable):
         """Resolve instructions from string or file path."""
         return resolve_instructions_from_path(self.instructions)
 
+    def to_openai_settings(
+        self, *, dotenv_path: Path | None = None, **overrides: Any
+    ) -> OpenAISettings:
+        """Build OpenAI settings using this configuration as defaults.
+
+        Parameters
+        ----------
+        dotenv_path : Path or None, optional
+            Optional dotenv file path for loading environment variables.
+        overrides : Any
+            Keyword overrides applied on top of environment values. Use this
+            to supply API credentials and override defaults.
+
+        Returns
+        -------
+        OpenAISettings
+            OpenAI settings instance with defaults derived from this
+            configuration.
+
+        Raises
+        ------
+        ValueError
+            If no API key is supplied via overrides or environment variables.
+
+        Examples
+        --------
+        >>> configuration = AgentConfiguration(
+        ...     name="summarizer",
+        ...     instructions="Summarize text",
+        ...     model="gpt-4o-mini",
+        ... )
+        >>> settings = configuration.to_openai_settings(api_key="sk-...")
+        >>> # Or rely on environment variables like OPENAI_API_KEY
+        >>> settings = configuration.to_openai_settings()
+        """
+        if self.model and "default_model" not in overrides:
+            overrides["default_model"] = self.model
+        return OpenAISettings.from_env(dotenv_path=dotenv_path, **overrides)
+
     def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
         """Resolve the prompt template path for this configuration.
 

openai_sdk_helpers/agent/files.py

@@ -0,0 +1,120 @@
+"""File attachment helpers for the Agents SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from ..files_api import FilePurpose, FilesAPIManager
+from ..settings import OpenAISettings
+from ..utils import create_image_data_url, ensure_list, is_image_file
+
+
+def build_agent_input_messages(
+    content: str | list[str],
+    files: str | list[str] | None = None,
+    *,
+    files_manager: FilesAPIManager | None = None,
+    openai_settings: OpenAISettings | None = None,
+    file_purpose: FilePurpose = "user_data",
+    image_detail: Literal["low", "high", "auto"] = "auto",
+) -> list[dict[str, Any]]:
+    """Build Agents SDK input messages with file attachments.
+
+    Parameters
+    ----------
+    content : str or list[str]
+        Prompt text or list of prompt texts to send.
+    files : str, list[str], or None, default None
+        Optional file path or list of file paths. Image files are sent as
+        base64-encoded ``input_image`` entries. Document files are uploaded
+        using ``files_manager`` and sent as ``input_file`` entries.
+    files_manager : FilesAPIManager or None, default None
+        File upload helper used to create file IDs for document uploads.
+        Required when ``files`` contains non-image documents.
+    openai_settings : OpenAISettings or None, default None
+        Optional OpenAI settings used to build a FilesAPIManager when one is
+        not provided. When supplied, ``openai_settings.create_client()`` is
+        used to initialize the Files API manager.
+    file_purpose : FilePurpose, default "user_data"
+        Purpose passed to the Files API when uploading document files.
+    image_detail : {"low", "high", "auto"}, default "auto"
+        Detail hint passed along with base64-encoded image inputs.
+
+    Returns
+    -------
+    list[dict[str, Any]]
+        Agents SDK input messages that include text and optional file entries.
+
+    Raises
+    ------
+    ValueError
+        If document files are provided without a ``files_manager``.
+
+    Examples
+    --------
+    >>> from openai import OpenAI
+    >>> from openai_sdk_helpers.files_api import FilesAPIManager
+    >>> from openai_sdk_helpers.agent.files import build_agent_input_messages
+    >>> client = OpenAI()
+    >>> files_manager = FilesAPIManager(client)
+    >>> messages = build_agent_input_messages(
+    ...     "Summarize this document",
+    ...     files="report.pdf",
+    ...     files_manager=files_manager,
+    ... )
+    """
+    contents = ensure_list(content)
+    all_files = ensure_list(files)
+
+    image_files: list[str] = []
+    document_files: list[str] = []
+    for file_path in all_files:
+        if is_image_file(file_path):
+            image_files.append(file_path)
+        else:
+            document_files.append(file_path)
+
+    attachments: list[dict[str, Any]] = []
+
+    if document_files:
+        if files_manager is None and openai_settings is not None:
+            files_manager = FilesAPIManager(openai_settings.create_client())
+        if files_manager is None:
+            raise ValueError(
+                "files_manager is required to upload document files for agent input."
+            )
+        expires_after = 86400 if file_purpose == "user_data" else None
+        if hasattr(files_manager, "batch_upload"):
+            uploaded_files = files_manager.batch_upload(
+                document_files,
+                purpose=file_purpose,
+                expires_after=expires_after,
+            )
+        else:
+            uploaded_files = [
+                files_manager.create(
+                    file_path, purpose=file_purpose, expires_after=expires_after
+                )
+                for file_path in document_files
+            ]
+        for uploaded_file in uploaded_files:
+            attachments.append({"type": "input_file", "file_id": uploaded_file.id})
+
+    for image_path in image_files:
+        image_url, detail = create_image_data_url(image_path, detail=image_detail)
+        attachments.append(
+            {"type": "input_image", "image_url": image_url, "detail": detail}
+        )
+
+    messages: list[dict[str, Any]] = []
+    for index, raw_content in enumerate(contents):
+        text = raw_content.strip()
+        content_items: list[dict[str, Any]] = [{"type": "input_text", "text": text}]
+        if index == 0:
+            content_items.extend(attachments)
+        messages.append({"role": "user", "content": content_items})
+
+    return messages
+
+
+__all__ = ["build_agent_input_messages"]

openai_sdk_helpers/agent/runner.py

@@ -7,7 +7,7 @@ signatures whether they need asynchronous or synchronous results.
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 from agents import Agent, RunResult, Runner, Session
 
@@ -17,7 +17,7 @@ from ..structure.base import StructureBase
 
 async def run_async(
     agent: Agent,
-    input: str,
+    input: str | list[dict[str, Any]],
     *,
     context: Optional[Dict[str, Any]] = None,
     output_structure: Optional[type[StructureBase]] = None,
@@ -29,8 +29,8 @@ async def run_async(
     ----------
     agent : Agent
         Configured agent instance to execute.
-    input : str
-        Prompt or query string for the agent.
+    input : str or list[dict[str, Any]]
+        Prompt text or structured input for the agent.
     context : dict or None, default=None
         Optional context dictionary passed to the agent.
     output_structure : type[StructureBase] or None, default=None
@@ -53,7 +53,7 @@ async def run_async(
     ...     return result
     >>> asyncio.run(example())  # doctest: +SKIP
     """
-    result = await Runner.run(agent, input, context=context, session=session)
+    result = await Runner.run(agent, cast(Any, input), context=context, session=session)
     if output_structure is not None:
         return result.final_output_as(output_structure)
     return result
@@ -61,7 +61,7 @@ async def run_async(
 
 def run_sync(
     agent: Agent,
-    input: str,
+    input: str | list[dict[str, Any]],
     *,
     context: Optional[Dict[str, Any]] = None,
     output_structure: Optional[type[StructureBase]] = None,
@@ -77,8 +77,8 @@ def run_sync(
     ----------
     agent : Agent
         Configured agent instance to execute.
-    input : str
-        Prompt or query string for the agent.
+    input : str or list[dict[str, Any]]
+        Prompt text or structured input for the agent.
     context : dict or None, default=None
         Optional context dictionary passed to the agent.
     output_structure : type[StructureBase] or None, default=None
@@ -102,7 +102,7 @@ def run_sync(
     >>> agent = Agent(name="test", instructions="test", model="gpt-4o-mini")
     >>> result = run_sync(agent, "What is 2+2?")  # doctest: +SKIP
     """
-    coro = Runner.run(agent, input, context=context, session=session)
+    coro = Runner.run(agent, cast(Any, input), context=context, session=session)
     result: RunResult = run_coroutine_with_fallback(coro)
     if output_structure is not None:
         return result.final_output_as(output_structure)

openai_sdk_helpers/agent/translator.py

@@ -138,7 +138,7 @@ class TranslatorAgent(AgentBase):
 
     def run_sync(
         self,
-        input: str,
+        input: str | list[dict[str, Any]],
         *,
         context: Optional[Dict[str, Any]] = None,
         output_structure: Optional[type[StructureBase]] = None,
@@ -149,7 +149,7 @@ class TranslatorAgent(AgentBase):
 
         Parameters
         ----------
-        input : str
+        input : str or list[dict[str, Any]]
             Source content to translate.
         context : dict or None, default=None
             Additional context values to merge into the prompt.

openai_sdk_helpers/files_api.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import logging
 from pathlib import Path
-from typing import Any, BinaryIO, Literal, cast
+from typing import Any, BinaryIO, Literal, Sequence, cast
 
 from openai import OpenAI, NOT_GIVEN
 from openai.types import FileDeleted, FileObject
@@ -62,6 +62,8 @@ class FilesAPIManager:
         Delete a specific file.
     retrieve_content(file_id)
         Download file content.
+    batch_upload(files, purpose, track, expires_after)
+        Upload multiple files to the Files API.
     cleanup()
         Delete all tracked files.
 
@@ -350,6 +352,49 @@ class FilesAPIManager:
         """
         return self._client.files.content(file_id).read()
 
+    def batch_upload(
+        self,
+        files: Sequence[BinaryIO | Path | str],
+        purpose: FilePurpose,
+        track: bool | None = None,
+        expires_after: int | None = None,
+    ) -> list[FileObject]:
+        """Upload multiple files to the OpenAI Files API.
+
+        Parameters
+        ----------
+        files : Sequence[BinaryIO | Path | str]
+            File-like objects or file paths to upload.
+        purpose : FilePurpose
+            The intended purpose of the uploaded files.
+        track : bool or None, default None
+            Override auto_track for these uploads. If None, uses instance setting.
+        expires_after : int or None, default None
+            Number of seconds after which files expire. See ``create`` for details.
+
+        Returns
+        -------
+        list[FileObject]
+            Uploaded file objects in the same order as ``files``.
+
+        Examples
+        --------
+        >>> files = ["doc1.pdf", "doc2.pdf"]
+        >>> uploaded = manager.batch_upload(files, purpose="user_data")
+        >>> [file.id for file in uploaded]
+        """
+        if not files:
+            return []
+        return [
+            self.create(
+                file_path,
+                purpose=purpose,
+                track=track,
+                expires_after=expires_after,
+            )
+            for file_path in files
+        ]
+
     def cleanup(self) -> dict[str, bool]:
         """Delete all tracked files.
 

openai_sdk_helpers/prompt/classifier.jinja

@@ -1,18 +1,39 @@
 You are a taxonomy classification assistant.
 
 Instructions:
-- Review the text and select the best matching taxonomy node from the list.
-- 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 selected_id empty.
-- If you are confident this is the final level, set stop_reason to "stop".
-- Provide a concise rationale in one or two sentences.
+- 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.
+  - 0.70–0.89: strong semantic alignment.
+  - 0.40–0.69: weak or ambiguous alignment.
+  - <0.40: low-confidence inference.
+- 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".
+- Stop reason semantics:
+  - continue: valid match exists and deeper traversal is required.
+  - stop: low confidence, terminate to avoid false precision.
+  - no_match: no semantic fit in candidates.
+  - max_depth: taxonomy depth limit reached.
+  - no_children: matched node has no children.
+- Decision mapping:
+  - High or medium confidence with children available: continue.
+  - High confidence with terminal node: no_children.
+  - Low confidence match: stop.
+  - No semantic alignment: no_match.
+  - Depth limit reached: max_depth.
+- Provide a concise rationale in one sentence.
+- Keep rationale evidence-based and avoid restating taxonomy labels.
+- Avoid verbosity, speculation, stylistic language, narrative explanation, redundancy, or creativity.
 
 Current depth: {{ depth }}
 
 Previous path:
 {% if path %}
 {% for step in path %}
-- {{ step.selected_label }} (id={{ step.selected_id }}, confidence={{ step.confidence }})
+- {{ step.selected_node }} (confidence={{ step.confidence }}, stop_reason={{ step.stop_reason }})
 {% endfor %}
 {% else %}
 - None
@@ -20,7 +41,7 @@ Previous path:
 
 Candidate taxonomy nodes:
 {% for node in taxonomy_nodes %}
-- id: {{ node.id }}
+- identifier: {{ node.identifier }}
   label: {{ node.label }}
   description: {{ node.description or "None" }}
 {% endfor %}

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

@@ -80,8 +80,10 @@ from .classification import (
     ClassificationResult,
     ClassificationStep,
     ClassificationStopReason,
+    Taxonomy,
     TaxonomyNode,
     flatten_taxonomy,
+    taxonomy_enum_path,
 )
 from .extraction import (
     AnnotatedDocumentStructure,
@@ -108,8 +110,10 @@ __all__ = [
     "ClassificationResult",
     "ClassificationStep",
     "ClassificationStopReason",
+    "Taxonomy",
     "TaxonomyNode",
     "flatten_taxonomy",
+    "taxonomy_enum_path",
     "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