openai-sdk-helpers 0.6.1__py3-none-any.whl → 0.6.4__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

@@ -3,21 +3,36 @@ 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.
+  - 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".
-- 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.
+- 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_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
@@ -27,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

@@ -80,8 +80,11 @@ from .classification import (
     ClassificationResult,
     ClassificationStep,
     ClassificationStopReason,
+    Taxonomy,
     TaxonomyNode,
-    flatten_taxonomy,
+    format_path_identifier,
+    split_path_identifier,
+    taxonomy_enum_path,
 )
 from .extraction import (
     AnnotatedDocumentStructure,
@@ -108,8 +111,11 @@ __all__ = [
     "ClassificationResult",
     "ClassificationStep",
     "ClassificationStopReason",
+    "Taxonomy",
     "TaxonomyNode",
-    "flatten_taxonomy",
+    "format_path_identifier",
+    "split_path_identifier",
+    "taxonomy_enum_path",
     "TaskStructure",
     "PlanStructure",
     "create_plan",