literun 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

literun/items.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Optional, Union, Literal, TypeAlias
+from typing import Literal, TypeAlias
 from pydantic import BaseModel
 
 from openai.types.responses import (
@@ -20,7 +20,7 @@ class ResponseFunctionToolCallOutput(BaseModel):
     call_id: str
     """The unique ID of the function tool call generated by the model."""
 
-    output: Union[str, ResponseInputText]
+    output: str | ResponseInputText
     """The output from the function call generated by your code."""
 
     name: str
@@ -29,10 +29,10 @@ class ResponseFunctionToolCallOutput(BaseModel):
     type: Literal["function_call_output"]
     """The type of the function tool call output. Always `function_call_output`."""
 
-    id: Optional[str] = None
+    id: str | None = None
     """The unique ID of the function tool call output."""
 
-    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None
+    status: Literal["in_progress", "completed", "incomplete"] | None = None
     """The status of the item."""
 
 
@@ -44,7 +44,7 @@ class MessageOutputItem(BaseModel):
     content: str = ""
     """The text content of the message. Always `assistant`."""
 
-    raw_item: Optional[ResponseOutputMessage] = None
+    raw_item: ResponseOutputMessage | None = None
     """The raw response output message."""
 
     type: Literal["message_output_item"] = "message_output_item"
@@ -59,9 +59,7 @@ class ToolCallItem(BaseModel):
     content: str = ""
     """The content of the tool call. Usually empty."""
 
-    raw_item: Optional[Union[ResponseFunctionToolCall, ResponseFunctionWebSearch]] = (
-        None
-    )
+    raw_item: ResponseFunctionToolCall | ResponseFunctionWebSearch | None = None
     """The raw tool call item."""
 
     type: Literal["tool_call_item"] = "tool_call_item"
@@ -76,7 +74,7 @@ class ToolCallOutputItem(BaseModel):
     content: str = ""
     """The output from the function call generated by your code."""
 
-    raw_item: Optional[ResponseFunctionToolCallOutput] = None
+    raw_item: ResponseFunctionToolCallOutput | None = None
     """The raw tool call output item."""
 
     type: Literal["tool_call_output_item"] = "tool_call_output_item"
@@ -88,19 +86,16 @@ class ReasoningItem(BaseModel):
 
     role: Literal["assistant"] = "assistant"
 
-    content: Optional[str] = None
+    content: str | None = None
     """The reasoning content."""
 
-    raw_item: Optional[ResponseReasoningItem] = None
+    raw_item: ResponseReasoningItem | None = None
     """The raw reasoning item."""
 
     type: Literal["reasoning_item"] = "reasoning_item"
     """The type of the reasoning item. Always `reasoning_item`."""
 
 
-RunItem: TypeAlias = Union[
-    MessageOutputItem,
-    ToolCallItem,
-    ToolCallOutputItem,
-    ReasoningItem,
-]
+RunItem: TypeAlias = (
+    MessageOutputItem | ToolCallItem | ToolCallOutputItem | ReasoningItem
+)

literun/llm.py

@@ -2,67 +2,133 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, List, Optional, Iterator
+from typing import Any, Iterator
+from pydantic import BaseModel, Field, PrivateAttr, model_validator
 from openai import OpenAI
+from openai.types.responses import Response
 
 from .tool import Tool
-
-
-class ChatOpenAI:
+from .prompt_template import PromptTemplate
+from .events import ResponseStreamEvent
+from .constants import (
+    Verbosity,
+    TextFormat,
+    ReasoningEffort,
+    DEFAULT_TIMEOUT,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_OPENAI_MODEL,
+)
+
+
+class ChatOpenAI(BaseModel):
     """Stateless wrapper for a configured OpenAI model.
 
     Provides a unified interface to call the OpenAI Responses API, optionally
     binding tools and streaming outputs.
+
+    Args:
+        model: The model name to use.
+        temperature: Sampling temperature.
+        api_key: OpenAI API key.
+        organization: OpenAI organization ID.
+        project: OpenAI project ID.
+        base_url: Custom base URL for OpenAI API.
+        max_output_tokens: Maximum number of tokens in the output.
+        timeout: Request timeout in seconds.
+        max_retries: Number of retries for failed requests.
+        reasoning_effort: Level of reasoning effort for the model.
+            Options: "none", "low", "medium", "high".
+        verbosity: Level of verbosity in model responses.
+            Options: "low", "medium", "high".
+        text_format: Format of the text output.
+            Options: "text", "json_object", "json_schema".
+        store: Whether to store model responses with OpenAI.
+        model_kwargs: Additional model parameters.
     """
 
-    def __init__(
-        self,
-        *,
-        model: str = "gpt-4.1-mini",
-        temperature: Optional[float] = None,
-        api_key: Optional[str] = None,
-        base_url: Optional[str] = None,
-        max_output_tokens: Optional[int] = None,
-        tools: Optional[List[Tool]] = None,
-        tool_choice: Optional[str] = None,
-        parallel_tool_calls: Optional[bool] = None,
-        store: bool = False,
-        **kwargs: Any,
-    ) -> None:
-        """Initialize the ChatOpenAI instance.
+    model: str = DEFAULT_OPENAI_MODEL
+    temperature: float | None = None
+    api_key: str | None = None
+    organization: str | None = None
+    project: str | None = None
+    base_url: str | None = None
+    max_output_tokens: int | None = None
+    timeout: float | None = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    reasoning_effort: ReasoningEffort | None = None
+    verbosity: Verbosity | None = None
+    text_format: TextFormat | None = None
+    store: bool = False
+    model_kwargs: dict[str, Any] = Field(default_factory=dict)
+
+    _client: OpenAI = PrivateAttr()
+    _tools: list[Tool] | None = PrivateAttr(default=None)
+    _tool_choice: str | None = PrivateAttr(default=None)
+    _parallel_tool_calls: bool | None = PrivateAttr(default=None)
+
+    @model_validator(mode="after")
+    def _validate_temperature(self) -> ChatOpenAI:
+        """Validate temperature and reasoning parameters."""
+        model_lower = self.model.lower()
+
+        # 1. For o-series models, default to temperature=1 if not provided
+        if model_lower.startswith("o") and self.temperature is None:
+            import warnings
+
+            warnings.warn(
+                "o-series models require temperature=1 and no temperature was provided. "
+                "Setting default temperature=1 for o-series models.",
+                UserWarning,
+            )
+            self.temperature = 1
 
-        Args:
-            model: The model name to use.
-            temperature: Sampling temperature.
-            api_key: OpenAI API key.
-            base_url: Custom base URL for OpenAI API.
-            max_output_tokens: Maximum number of tokens in the output.
-            tools: Optional list of Tool instances to bind.
-            tool_choice: Optional tool selection strategy.
-            parallel_tool_calls: Whether to allow parallel tool calls.
-            store: Whether to store model responses.
-            **kwargs: Additional model parameters.
-        """
-        self.model = model
-        self.temperature = temperature
-        self.max_output_tokens = max_output_tokens
-        self.model_kwargs = kwargs
-        self.client = (
-            OpenAI(api_key=api_key, base_url=base_url)
-            if base_url
-            else OpenAI(api_key=api_key)
+        # 2. For gpt-5 models, handle temperature restrictions
+        # (Assuming gpt-5-chat and non-reasoning gpt-5 support arbitrary temps)
+        is_gpt5 = model_lower.startswith("gpt-5")
+        is_chat = "chat" in model_lower
+
+        # Check reasoning effort from field or model_kwargs
+        effort_kwarg = (self.model_kwargs.get("reasoning") or {}).get("effort")
+        has_reasoning = (self.reasoning_effort and self.reasoning_effort != "none") or (
+            effort_kwarg and effort_kwarg != "none"
         )
-        self.store = store
-        self._tools = tools
-        self._tool_choice = tool_choice
-        self._parallel_tool_calls = parallel_tool_calls
+
+        if is_gpt5 and not is_chat and has_reasoning:
+            if self.temperature is not None and self.temperature != 1:
+                import warnings
+
+                warnings.warn(
+                    "Invalid temperature for gpt-5 with reasoning. Using default temperature.",
+                    UserWarning,
+                )
+                self.temperature = None
+
+        return self
+
+    @model_validator(mode="after")
+    def _initialize_client(self) -> ChatOpenAI:
+        """Initialize the OpenAI client."""
+        self._client = OpenAI(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            organization=self.organization,
+            project=self.project,
+            timeout=self.timeout,
+            max_retries=self.max_retries,
+        )
+        return self
+
+    @property
+    def client(self) -> OpenAI:
+        """Access the OpenAI client."""
+        return self._client
 
     def bind_tools(
         self,
         *,
-        tools: List[Tool],
-        tool_choice: Optional[str] = None,
-        parallel_tool_calls: Optional[bool] = None,
+        tools: list[Tool],
+        tool_choice: str | None = None,
+        parallel_tool_calls: bool | None = None,
     ) -> ChatOpenAI:
         """Bind tools to the LLM instance.
 
@@ -82,40 +148,55 @@ class ChatOpenAI:
     def chat(
         self,
         *,
-        messages: List[Dict[str, Any]],
+        messages: PromptTemplate | list[dict[str, Any]],
         stream: bool = False,
-        tools: Optional[List[Dict[str, Any]]] = None,
-        tool_choice: Optional[str] = None,
-        parallel_tool_calls: Optional[bool] = None,
-    ) -> Any:
+        tools: list[Tool] | None = None,
+        tool_choice: str | None = None,
+        parallel_tool_calls: bool | None = None,
+    ) -> Response | Iterator[ResponseStreamEvent]:
         """Call the model with the given messages.
 
         Args:
-            messages: List of messages in OpenAI format.
+            messages: PromptTemplate or list of messages in OpenAI format.
             stream: Whether to stream the output.
-            tools: Optional list of OpenAI tool definitions.
+            tools: Optional list of Tool instances.
             tool_choice: Optional tool selection strategy.
             parallel_tool_calls: Whether to allow parallel tool calls.
 
         Returns:
-            Any: The OpenAI Responses API response object (or stream).
+            Response | Iterator[ResponseStreamEvent]: The OpenAI Responses API response object (or stream).
         """
+        if isinstance(messages, PromptTemplate):
+            input_ = messages.to_openai_input()
+        else:
+            input_ = messages
+
         params = {
             "model": self.model,
-            "input": messages,
+            "temperature": self.temperature,
+            "max_output_tokens": self.max_output_tokens,
+            "input": input_,
             "stream": stream,
             "store": self.store,
             **self.model_kwargs,
         }
-        if self.temperature is not None:
-            params["temperature"] = self.temperature
-        if self.max_output_tokens is not None:
-            params["max_output_tokens"] = self.max_output_tokens
+        if self.reasoning_effort is not None:
+            params["reasoning"] = {"effort": self.reasoning_effort}
+
+        text_options = {}
+        if self.verbosity is not None:
+            text_options["verbosity"] = self.verbosity
+        if self.text_format is not None:
+            text_options["type"] = self.text_format
+        if text_options:
+            params["text"] = {"format": text_options}
 
         # Tools resolution
-        current_tools = tools or (
-            [tool.to_openai_tool() for tool in self._tools] if self._tools else None
+        active_tools = tools if tools is not None else self._tools
+        current_tools = (
+            self._convert_to_openai_tools(active_tools) if active_tools else None
         )
+
         if current_tools:
             params["tools"] = current_tools
             params["tool_choice"] = tool_choice or self._tool_choice
@@ -127,30 +208,41 @@ class ChatOpenAI:
 
         return self.client.responses.create(**params)
 
-    def invoke(self, messages: List[Dict[str, Any]]) -> Any:
+    def invoke(self, messages: list[dict[str, Any]] | PromptTemplate) -> Response:
         """Synchronously call the model.
 
         Args:
-            messages: List of messages in OpenAI format.
+            messages: PromptTemplate or list of messages in OpenAI format.
 
         Returns:
-            Any: The OpenAI Responses API response object.
+            Response: The OpenAI Responses API response object.
         """
         return self.chat(messages=messages, stream=False)
 
     def stream(
         self,
         *,
-        messages: List[Dict[str, Any]],
-    ) -> Iterator[Any]:
+        messages: list[dict[str, Any]] | PromptTemplate,
+    ) -> Iterator[ResponseStreamEvent]:
         """Stream the model response.
 
         Args:
-            messages: List of messages in OpenAI format.
+            messages: PromptTemplate or list of messages in OpenAI format.
 
         Yields:
-            Any: Streamed response events from the OpenAI Responses API.
+            ResponseStreamEvent: Streamed response events from the OpenAI Responses API.
         """
         response = self.chat(messages=messages, stream=True)
         for event in response:
             yield event
+
+    @staticmethod
+    def _convert_to_openai_tools(tools: list[Tool]) -> list[dict[str, Any]] | None:
+        """Convert all registered tools to the OpenAI tool schema format.
+
+        Returns:
+            List[Dict[str, Any]]: A list of tools in OpenAI-compatible dictionary format.
+        """
+        if not tools:
+            return None
+        return [tool.to_openai_tool() for tool in tools]

literun/prompt_message.py

@@ -2,69 +2,55 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, Optional
+from typing import Any, Dict
+from pydantic import BaseModel, model_validator
 
 from .constants import Role, ContentType
 
 
-class PromptMessage:
+class PromptMessage(BaseModel):
     """Domain representation of a single semantic message in a conversation.
 
     This class is the only place that knows how to convert a semantic
     message into an OpenAI-compatible message dictionary. It enforces
     invariants depending on the message type.
-    """
-
-    def __init__(
-        self,
-        *,
-        role: Optional[Role] = None,
-        content_type: ContentType,
-        text: Optional[str] = None,
-        name: Optional[str] = None,
-        arguments: Optional[str] = None,
-        call_id: Optional[str] = None,
-        output: Optional[str] = None,
-    ) -> None:
-        """Initialize a PromptMessage.
-
-        Args:
-            role: The role of the message sender (e.g., USER, ASSISTANT). Required for text messages.
-            content_type: The type of content (e.g., INPUT_TEXT, FUNCTION_CALL).
-            text: The text content of the message (required for text messages).
-            name: The name of the tool (for function calls).
-            arguments: The arguments for the tool as a JSON string (for function calls).
-            call_id: The ID of the tool call.
-            output: The output of the tool execution (for FUNCTION_CALL_OUTPUT messages).
 
-        Raises:
-            ValueError: If required fields for the given content_type are missing.
-        """
-        self.role = role
-        self.content_type = content_type
-        self.text = text
-        self.name = name
-        self.arguments = arguments
-        self.call_id = call_id
-        self.output = output
+    Args:
+        role: The role of the message sender. Required for text messages.
+            Options: "system", "user", "assistant", "developer", "tool"
+        text: The text content of the message (required for text messages).
+        name: The name of the tool (for function calls).
+        arguments: The arguments for the tool as a JSON string (for function calls).
+        call_id: The ID of the tool call.
+        output: The output of the tool execution (for function call output messages).
+        content_type: The type of content.
+            Options: "input_text", "output_text", "message", "function_call", "function_call_output"
+    """
 
-        self._validate()
+    role: Role | None = None
+    text: str | None = None
+    name: str | None = None
+    arguments: str | None = None
+    call_id: str | None = None
+    output: str | None = None
+    content_type: ContentType
 
-    def _validate(self) -> None:
+    @model_validator(mode="after")
+    def _validate_invariants(self) -> PromptMessage:
         """Enforce invariants so that invalid messages are never constructed.
 
         Raises:
             ValueError: If required fields are missing for the given content_type.
         """
         # Text messages (system / user / assistant)
-        if self.content_type in (ContentType.INPUT_TEXT, ContentType.OUTPUT_TEXT):
+        if self.content_type in ("input_text", "output_text"):
             if self.role is None:
                 raise ValueError("role is required for text messages")
             if not isinstance(self.text, str):
                 raise ValueError("text is required for text messages")
 
         # Tool call (model -> agent)
-        elif self.content_type == ContentType.FUNCTION_CALL:
+        elif self.content_type == "function_call":
             if not self.name:
                 raise ValueError("name is required for FUNCTION_CALL")
             if not isinstance(self.arguments, str):
@@ -73,14 +59,15 @@ class PromptMessage:
                 raise ValueError("call_id is required for FUNCTION_CALL")
 
         # Tool output (agent -> model)
-        elif self.content_type == ContentType.FUNCTION_CALL_OUTPUT:
+        elif self.content_type == "function_call_output":
             if not self.call_id:
                 raise ValueError("call_id is required for FUNCTION_CALL_OUTPUT")
             if not isinstance(self.output, str):
                 raise ValueError("output must be a string")
-
         else:
             raise ValueError(f"Unsupported content_type: {self.content_type}")
+        
+        return self
 
     def to_openai_message(self) -> Dict[str, Any]:
         """Convert the PromptMessage to an OpenAI-compatible message dictionary.
@@ -93,30 +80,30 @@ class PromptMessage:
             RuntimeError: If the message state is invalid (should not occur).
         """
         # System / User / Assistant messages
-        if self.content_type in (ContentType.INPUT_TEXT, ContentType.OUTPUT_TEXT):
+        if self.content_type in ("input_text", "output_text"):
             return {
-                "role": self.role.value,
+                "role": self.role,
                 "content": [
                     {
-                        "type": self.content_type.value,
+                        "type": self.content_type,
                         "text": self.text,
                     }
                 ],
             }
 
         # Tool call (model -> agent)
-        if self.content_type == ContentType.FUNCTION_CALL:
+        if self.content_type == "function_call":
             return {
-                "type": self.content_type.value,
+                "type": self.content_type,
                 "name": self.name,
                 "arguments": self.arguments,
                 "call_id": self.call_id,
             }
 
         # Tool output (agent -> model)
-        if self.content_type == ContentType.FUNCTION_CALL_OUTPUT:
+        if self.content_type == "function_call_output":
             return {
-                "type": self.content_type.value,
+                "type": self.content_type,
                 "call_id": self.call_id,
                 "output": self.output,
             }

literun/prompt_template.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Iterable, List, Dict, Any
+from typing import Iterable, Any
+from pydantic import BaseModel, Field
 
 from .prompt_message import PromptMessage
-from .constants import Role, ContentType
 
 
-class PromptTemplate:
+class PromptTemplate(BaseModel):
     """Container for conversation state.
 
     This class stores the authoritative message history used by the Agent.
@@ -16,10 +16,7 @@ class PromptTemplate:
     OpenAI API boundary.
     """
 
-    def __init__(self) -> None:
-        """Initialize an empty PromptTemplate."""
-
-        self.messages: List[PromptMessage] = []
+    messages: list[PromptMessage] = Field(default_factory=list)
 
     def add_message(self, message: PromptMessage) -> PromptTemplate:
         """Add a custom prompt message.
@@ -62,8 +59,8 @@ class PromptTemplate:
         """
         return self.add_message(
             PromptMessage(
-                role=Role.DEVELOPER,
-                content_type=ContentType.INPUT_TEXT,
+                role="system",
+                content_type="input_text",
                 text=text,
             )
         )
@@ -79,8 +76,8 @@ class PromptTemplate:
         """
         return self.add_message(
             PromptMessage(
-                role=Role.USER,
-                content_type=ContentType.INPUT_TEXT,
+                role="user",
+                content_type="input_text",
                 text=text,
             )
         )
@@ -96,8 +93,8 @@ class PromptTemplate:
         """
         return self.add_message(
             PromptMessage(
-                role=Role.ASSISTANT,
-                content_type=ContentType.OUTPUT_TEXT,
+                role="assistant",
+                content_type="output_text",
                 text=text,
             )
         )
@@ -121,7 +118,7 @@ class PromptTemplate:
         """
         return self.add_message(
             PromptMessage(
-                content_type=ContentType.FUNCTION_CALL,
+                content_type="function_call",
                 name=name,
                 arguments=arguments,
                 call_id=call_id,
@@ -145,7 +142,7 @@ class PromptTemplate:
         """
         return self.add_message(
             PromptMessage(
-                content_type=ContentType.FUNCTION_CALL_OUTPUT,
+                content_type="function_call_output",
                 call_id=call_id,
                 output=output,
             )
@@ -164,11 +161,11 @@ class PromptTemplate:
         new.messages = list(self.messages)
         return new
 
-    def to_openai_input(self) -> List[Dict[str, Any]]:
+    def to_openai_input(self) -> list[dict[str, Any]]:
         """Convert the template to OpenAI message dictionaries.
 
         Returns:
-            List[Dict[str, Any]]: The formatted messages.
+            list[dict[str, Any]]: The formatted messages.
         """
         return [msg.to_openai_message() for msg in self.messages]
 

literun/results.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from pydantic import BaseModel
 from typing import Any
 
 from openai.types.responses import Response
@@ -10,8 +10,7 @@ from .items import RunItem
 from .events import StreamEvent
 
 
-@dataclass
-class RunResult:
+class RunResult(BaseModel):
     """Final result returned by the OpenAI Agent.
 
     Used in the ``Agent.invoke()`` method. Contains the full execution
@@ -30,8 +29,7 @@ class RunResult:
     """The output produced by the final agent invocation."""
 
 
-@dataclass
-class RunResultStreaming:
+class RunResultStreaming(BaseModel):
     """Streaming result returned by the OpenAI Agent.
 
     Used in the ``Agent.stream()`` method. Each instance represents a