openai-sdk-helpers 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

openai_sdk_helpers/structure/plan/__init__.py

@@ -0,0 +1,13 @@
+"""Structured output models for agent tasks and plans."""
+
+from __future__ import annotations
+
+from .plan import PlanStructure
+from .task import TaskStructure
+from .enum import AgentEnum
+
+__all__ = [
+    "PlanStructure",
+    "TaskStructure",
+    "AgentEnum",
+]

openai_sdk_helpers/structure/plan/enum.py

@@ -0,0 +1,64 @@
+"""Agent task enumeration definitions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...enums.base import CrosswalkJSONEnum
+
+
+class AgentEnum(CrosswalkJSONEnum):
+    """Auto-generated enumeration for AgentEnum.
+
+    Methods
+    -------
+    CROSSWALK()
+        Return the raw crosswalk data for this enum.
+    """
+
+    WEB_SEARCH = "WebAgentSearch"
+    VECTOR_SEARCH = "VectorSearch"
+    DATA_ANALYST = "DataAnalyst"
+    SUMMARIZER = "SummarizerAgent"
+    TRANSLATOR = "TranslatorAgent"
+    VALIDATOR = "ValidatorAgent"
+    PLANNER = "MetaPlanner"
+    DESIGNER = "AgentDesigner"
+    BUILDER = "AgentBuilder"
+    EVALUATOR = "EvaluationAgent"
+    RELEASE_MANAGER = "ReleaseManager"
+
+    @classmethod
+    def CROSSWALK(cls) -> dict[str, dict[str, Any]]:
+        """Return the raw crosswalk data for this enum.
+
+        Returns
+        -------
+        dict[str, dict[str, Any]]
+            Crosswalk mapping keyed by enum member.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> AgentEnum.CROSSWALK()["WEB_SEARCH"]["value"]
+        'WebAgentSearch'
+        """
+        return {
+            "WEB_SEARCH": {"value": "WebAgentSearch"},
+            "VECTOR_SEARCH": {"value": "VectorSearch"},
+            "DATA_ANALYST": {"value": "DataAnalyst"},
+            "SUMMARIZER": {"value": "SummarizerAgent"},
+            "TRANSLATOR": {"value": "TranslatorAgent"},
+            "VALIDATOR": {"value": "ValidatorAgent"},
+            "PLANNER": {"value": "MetaPlanner"},
+            "DESIGNER": {"value": "AgentDesigner"},
+            "BUILDER": {"value": "AgentBuilder"},
+            "EVALUATOR": {"value": "EvaluationAgent"},
+            "RELEASE_MANAGER": {"value": "ReleaseManager"},
+        }
+
+
+__all__ = ["AgentEnum"]

openai_sdk_helpers/structure/plan/plan.py

@@ -0,0 +1,253 @@
+"""Structured output model for agent plans."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Mapping
+
+from .enum import AgentEnum
+from ..base import BaseStructure, spec_field
+from .task import TaskStructure
+
+
+class PlanStructure(BaseStructure):
+    """Structured representation of an ordered list of agent tasks.
+
+    Methods
+    -------
+    print()
+        Return a formatted description of every task in order.
+    __len__()
+        Return the count of tasks in the plan.
+    append(task)
+        Append an ``TaskStructure`` to the plan.
+    execute(agent_registry, halt_on_error)
+        Run tasks sequentially using the provided agent callables.
+    """
+
+    tasks: List[TaskStructure] = spec_field(
+        "tasks",
+        default_factory=list,
+        description="Ordered list of agent tasks to execute.",
+    )
+
+    def print(self) -> str:
+        """Return a human-readable representation of the plan.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            Concatenated description of each plan step.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> PlanStructure().print()
+        'No tasks defined.'
+        """
+        if not self.tasks:
+            return "No tasks defined."
+        return "\n\n".join(
+            [f"Task {idx + 1}:\n{task.print()}" for idx, task in enumerate(self.tasks)]
+        )
+
+    def __len__(self) -> int:
+        """Return the number of tasks contained in the plan.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        int
+            Count of stored agent tasks.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> len(PlanStructure())
+        0
+        """
+        return len(self.tasks)
+
+    def append(self, task: TaskStructure) -> None:
+        """Add a task to the plan in execution order.
+
+        Parameters
+        ----------
+        task : TaskStructure
+            Task to append to the plan.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> plan = PlanStructure()
+        >>> plan.append(TaskStructure(prompt="Test"))  # doctest: +SKIP
+        """
+        self.tasks.append(task)
+
+    def execute(
+        self,
+        agent_registry: Mapping[AgentEnum | str, Callable[..., Any]],
+        *,
+        halt_on_error: bool = True,
+    ) -> list[str]:
+        """Execute tasks with registered agent callables and record outputs.
+
+        Parameters
+        ----------
+        agent_registry : Mapping[AgentEnum | str, Callable[..., Any]]
+            Lookup of agent identifiers to callables. Keys may be ``AgentEnum``
+            instances or their string values. Each callable receives the task
+            prompt (augmented with prior context) and an optional ``context``
+            keyword containing accumulated results.
+        halt_on_error : bool, default=True
+            Whether execution should stop when a task raises an exception.
+
+        Returns
+        -------
+        list[str]
+            Flattened list of normalized outputs from executed tasks.
+
+        Raises
+        ------
+        KeyError
+            If a task does not have a corresponding callable in
+            ``agent_registry``.
+        """
+        aggregated_results: list[str] = []
+        for task in self.tasks:
+            callable_key = self._resolve_registry_key(task.task_type)
+            if callable_key not in agent_registry:
+                raise KeyError(f"No agent registered for '{callable_key}'.")
+
+            agent_callable = agent_registry[callable_key]
+            task.start_date = datetime.now(timezone.utc)
+            task.status = "running"
+
+            try:
+                result = self._run_task(
+                    task,
+                    agent_callable=agent_callable,
+                    aggregated_context=list(aggregated_results),
+                )
+            except Exception as exc:  # pragma: no cover - defensive guard
+                task.status = "error"
+                task.results = [f"Task error: {exc}"]
+                task.end_date = datetime.now(timezone.utc)
+                if halt_on_error:
+                    break
+                aggregated_results.extend(task.results)
+                continue
+
+            normalized = self._normalize_results(result)
+            task.results = normalized
+            aggregated_results.extend(normalized)
+            task.status = "done"
+            task.end_date = datetime.now(timezone.utc)
+
+        return aggregated_results
+
+    @staticmethod
+    def _resolve_registry_key(task_type: AgentEnum | str) -> str:
+        """Return a normalized registry key for the given ``task_type``."""
+        if isinstance(task_type, AgentEnum):
+            return task_type.value
+        if task_type in AgentEnum.__members__:
+            return AgentEnum.__members__[task_type].value
+        try:
+            return AgentEnum(task_type).value
+        except ValueError:
+            return str(task_type)
+
+    @staticmethod
+    def _run_task(
+        task: TaskStructure,
+        *,
+        agent_callable: Callable[..., Any],
+        aggregated_context: list[str],
+    ) -> Any:
+        """Execute a single task using the supplied callable.
+
+        Parameters
+        ----------
+        task : TaskStructure
+            Task definition containing inputs and metadata.
+        agent_callable : Callable[..., Any]
+            Function responsible for performing the task.
+        aggregated_context : list[str]
+            Accumulated results from previously executed tasks.
+
+        Returns
+        -------
+        Any
+            Raw output from the callable.
+        """
+        task_context = list(task.context or [])
+        combined_context = task_context + list(aggregated_context)
+
+        prompt_with_context = task.prompt
+        if combined_context:
+            context_block = "\n".join(combined_context)
+            prompt_with_context = f"{task.prompt}\n\nContext:\n{context_block}"
+
+        try:
+            return agent_callable(prompt_with_context, context=combined_context)
+        except TypeError:
+            return agent_callable(prompt_with_context)
+
+    @staticmethod
+    def _normalize_results(result: Any) -> list[str]:
+        """Convert callable outputs into a list of strings."""
+        if result is None:
+            return []
+        if inspect.isawaitable(result):
+            return PlanStructure._normalize_results(PlanStructure._await_result(result))
+        if isinstance(result, list):
+            return [str(item) for item in result]
+        return [str(result)]
+
+    @staticmethod
+    def _await_result(result: Any) -> Any:
+        """Await the provided result, handling running event loops."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(result)
+
+        if loop.is_running():
+            container: Dict[str, Any] = {"value": None}
+
+            def _runner() -> None:
+                container["value"] = asyncio.run(result)
+
+            thread = threading.Thread(target=_runner, daemon=True)
+            thread.start()
+            thread.join()
+            return container["value"]
+
+        return loop.run_until_complete(result)
+
+
+__all__ = ["PlanStructure"]

openai_sdk_helpers/structure/plan/task.py

@@ -0,0 +1,122 @@
+"""Structured output model for agent tasks."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from pydantic import field_validator
+
+from .enum import AgentEnum
+from ..base import BaseStructure, spec_field
+
+
+class TaskStructure(BaseStructure):
+    """Structured representation of a single agent task.
+
+    Methods
+    -------
+    print()
+        Return a formatted multi-line description of the task.
+    """
+
+    task_type: AgentEnum = spec_field(
+        "task_type",
+        default=AgentEnum.WEB_SEARCH,
+        description="Agent type responsible for executing the task.",
+    )
+    prompt: str = spec_field(
+        "prompt",
+        description="Input passed to the agent.",
+        examples=["Research the latest trends in AI-assisted data analysis."],
+    )
+    context: List[str] | None = spec_field(
+        "context",
+        default_factory=list,
+        description="Additional context forwarded to the agent callable.",
+    )
+    start_date: Optional[datetime] = spec_field(
+        "start_date",
+        default=None,
+        description="Timestamp marking when the task started (UTC).",
+    )
+    end_date: Optional[datetime] = spec_field(
+        "end_date",
+        default=None,
+        description="Timestamp marking when the task completed (UTC).",
+    )
+    status: Literal["waiting", "running", "done", "error"] = spec_field(
+        "status",
+        default="waiting",
+        description="Current lifecycle state for the task.",
+    )
+    results: List[str] = spec_field(
+        "results",
+        default_factory=list,
+        description="Normalized string outputs returned by the agent.",
+    )
+
+    @field_validator("task_type", mode="before")
+    @classmethod
+    def _coerce_task_type(cls, value: AgentEnum | str) -> AgentEnum:
+        """Coerce string inputs into ``AgentEnum`` values.
+
+        Parameters
+        ----------
+        value : AgentEnum | str
+            Enum instance or enum value string.
+
+        Returns
+        -------
+        AgentEnum
+            Parsed enum instance.
+
+        Raises
+        ------
+        ValueError
+            If the value cannot be mapped to a valid enum member.
+
+        Examples
+        --------
+        >>> TaskStructure._coerce_task_type("WebAgentSearch")
+        <AgentEnum.WEB_SEARCH: 'WebAgentSearch'>
+        """
+        if isinstance(value, AgentEnum):
+            return value
+        return AgentEnum(value)
+
+    def print(self) -> str:
+        """Return a human-readable representation of the task.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            Multi-line description of the task metadata.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> TaskStructure(prompt="Test").print()
+        'Task type: ...'  # doctest: +SKIP
+        """
+        return "\n".join(
+            [
+                BaseStructure.format_output("Task type", self.task_type),
+                BaseStructure.format_output("Prompt", self.prompt),
+                BaseStructure.format_output("Context", self.context),
+                BaseStructure.format_output("Status", self.status),
+                BaseStructure.format_output("Start date", self.start_date),
+                BaseStructure.format_output("End date", self.end_date),
+                BaseStructure.format_output("Results", self.results),
+            ]
+        )
+
+
+__all__ = ["TaskStructure"]

openai_sdk_helpers/structure/prompt.py

@@ -0,0 +1,24 @@
+"""Shared structured output model for prompts."""
+
+from __future__ import annotations
+
+from .base import BaseStructure, spec_field
+
+
+class PromptStructure(BaseStructure):
+    """The prompt text to use for the OpenAI API request.
+
+    Methods
+    -------
+    print()
+        Return the formatted model fields.
+    """
+
+    prompt: str = spec_field(
+        "prompt",
+        description="The prompt text to use for the OpenAI API request.",
+        examples=[
+            "What is the capital of France?",
+            "Generate a summary of the latest news in AI.",
+        ],
+    )

openai_sdk_helpers/structure/responses.py

@@ -0,0 +1,132 @@
+"""OpenAI response and tool helpers for structured outputs."""
+
+from __future__ import annotations
+
+from typing import Type
+
+from openai.types.responses.response_format_text_json_schema_config_param import (
+    ResponseFormatTextJSONSchemaConfigParam,
+)
+from openai.types.responses.response_text_config_param import ResponseTextConfigParam
+
+from .base import BaseStructure
+from ..utils import log
+
+
+def assistant_tool_definition(
+    structure: Type[BaseStructure], name: str, description: str
+) -> dict:
+    """Build a function tool definition for OpenAI Assistants.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the tool schema.
+    name : str
+        Name of the function tool.
+    description : str
+        Description of what the function tool does.
+
+    Returns
+    -------
+    dict
+        Assistant tool definition payload.
+    """
+    log(f"{structure.__name__}::assistant_tool_definition")
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": structure.get_schema(),
+        },
+    }
+
+
+def assistant_format(structure: Type[BaseStructure]) -> dict:
+    """Build a response format definition for OpenAI Assistants.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the response schema.
+
+    Returns
+    -------
+    dict
+        Assistant response format definition.
+    """
+    log(f"{structure.__name__}::assistant_format")
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": structure.__name__,
+            "schema": structure.get_schema(),
+        },
+    }
+
+
+def response_tool_definition(
+    structure: Type[BaseStructure],
+    tool_name: str,
+    tool_description: str,
+) -> dict:
+    """Build a tool definition for OpenAI chat completions.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the tool schema.
+    tool_name : str
+        Name of the function tool.
+    tool_description : str
+        Description of what the function tool does.
+
+    Returns
+    -------
+    dict
+        Tool definition payload for chat completions.
+    """
+    log(f"{structure.__name__}::response_tool_definition")
+    return {
+        "type": "function",
+        "name": tool_name,
+        "description": tool_description,
+        "parameters": structure.get_schema(),
+        "strict": True,
+        "additionalProperties": False,
+    }
+
+
+def response_format(structure: Type[BaseStructure]) -> ResponseTextConfigParam:
+    """Build a response format for OpenAI chat completions.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the response schema.
+
+    Returns
+    -------
+    ResponseTextConfigParam
+        Response format definition.
+    """
+    log(f"{structure.__name__}::response_format")
+    response_format_text_JSONSchema_config_param = (
+        ResponseFormatTextJSONSchemaConfigParam(
+            name=structure.__name__,
+            schema=structure.get_schema(),
+            type="json_schema",
+            description="This is a JSON schema format for the output structure.",
+            strict=True,
+        )
+    )
+    return ResponseTextConfigParam(format=response_format_text_JSONSchema_config_param)
+
+
+__all__ = [
+    "assistant_tool_definition",
+    "assistant_format",
+    "response_tool_definition",
+    "response_format",
+]

openai_sdk_helpers/structure/summary.py

@@ -0,0 +1,65 @@
+"""Shared structured output models for summaries."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class SummaryTopic(BaseStructure):
+    """Capture a topic-level summary with supporting citations.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    topic: str = spec_field(
+        "topic",
+        default=...,
+        description="Topic or micro-trend identified in the provided excerpts.",
+    )
+    summary: str = spec_field(
+        "summary",
+        default=...,
+        description="Concise explanation of what the excerpts convey about the topic.",
+    )
+    citations: List[str] = spec_field(
+        "citations",
+        default_factory=list,
+        description="Indices or short quotes that justify the topic summary.",
+    )
+
+
+class SummaryStructure(BaseStructure):
+    """Defines the consolidated summary returned by the summarizer agent.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    text: str = spec_field(
+        "text",
+        default=...,
+        description="Combined summary synthesized from the supplied excerpts.",
+    )
+
+
+class ExtendedSummaryStructure(SummaryStructure):
+    """Extend ``SummaryStructure`` with optional topic breakdown metadata.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    metadata: List[SummaryTopic] = spec_field(
+        "metadata",
+        default_factory=list,
+        description="Optional topic-level summaries with supporting citations.",
+    )