literun 0.1.0__py3-none-any.whl

literun/items.py

@@ -0,0 +1,106 @@
+"""Response items used in agent execution."""
+
+from __future__ import annotations
+
+from typing import Optional, Union, Literal, TypeAlias
+from pydantic import BaseModel
+
+from openai.types.responses import (
+    ResponseOutputMessage,
+    ResponseReasoningItem,
+    ResponseFunctionToolCall,
+    ResponseFunctionWebSearch,
+    ResponseInputText,
+)
+
+
+class ResponseFunctionToolCallOutput(BaseModel):
+    """The output of a function tool call."""
+
+    call_id: str
+    """The unique ID of the function tool call generated by the model."""
+
+    output: Union[str, ResponseInputText]
+    """The output from the function call generated by your code."""
+
+    name: str
+    """The name of the function tool call."""
+
+    type: Literal["function_call_output"]
+    """The type of the function tool call output. Always `function_call_output`."""
+
+    id: Optional[str] = None
+    """The unique ID of the function tool call output."""
+
+    status: Optional[Literal["in_progress", "completed", "incomplete"]] = None
+    """The status of the item."""
+
+
+class MessageOutputItem(BaseModel):
+    """Represents a message from the LLM."""
+
+    role: Literal["assistant"] = "assistant"
+
+    content: str = ""
+    """The text content of the message. Always `assistant`."""
+
+    raw_item: Optional[ResponseOutputMessage] = None
+    """The raw response output message."""
+
+    type: Literal["message_output_item"] = "message_output_item"
+    """The type of the message output item. Always `message_output_item`."""
+
+
+class ToolCallItem(BaseModel):
+    """Represents a tool call e.g. a function call or computer action call."""
+
+    role: Literal["assistant"] = "assistant"
+
+    content: str = ""
+    """The content of the tool call. Usually empty."""
+
+    raw_item: Optional[Union[ResponseFunctionToolCall, ResponseFunctionWebSearch]] = (
+        None
+    )
+    """The raw tool call item."""
+
+    type: Literal["tool_call_item"] = "tool_call_item"
+    """The type of the tool call item. Always `tool_call_item`."""
+
+
+class ToolCallOutputItem(BaseModel):
+    """Represents the output of a tool call."""
+
+    role: Literal["tool"] = "tool"
+
+    content: str = ""
+    """The output from the function call generated by your code."""
+
+    raw_item: Optional[ResponseFunctionToolCallOutput] = None
+    """The raw tool call output item."""
+
+    type: Literal["tool_call_output_item"] = "tool_call_output_item"
+    """The type of the tool call output item. Always `tool_call_output_item`."""
+
+
+class ReasoningItem(BaseModel):
+    """Represents a reasoning item."""
+
+    role: Literal["assistant"] = "assistant"
+
+    content: Optional[str] = None
+    """The reasoning content."""
+
+    raw_item: Optional[ResponseReasoningItem] = 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,
+]

literun/llm.py

@@ -0,0 +1,156 @@
+"""LLM client wrapper and configuration."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Iterator
+from openai import OpenAI
+
+from .tool import Tool
+
+
+class ChatOpenAI:
+    """Stateless wrapper for a configured OpenAI model.
+
+    Provides a unified interface to call the OpenAI Responses API, optionally
+    binding tools and streaming outputs.
+    """
+
+    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.
+
+        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)
+        )
+        self.store = store
+        self._tools = tools
+        self._tool_choice = tool_choice
+        self._parallel_tool_calls = parallel_tool_calls
+
+    def bind_tools(
+        self,
+        *,
+        tools: List[Tool],
+        tool_choice: Optional[str] = None,
+        parallel_tool_calls: Optional[bool] = None,
+    ) -> ChatOpenAI:
+        """Bind tools to the LLM instance.
+
+        Args:
+            tools: List of Tool instances to bind.
+            tool_choice: Optional tool selection strategy.
+            parallel_tool_calls: Whether to allow parallel tool calls.
+
+        Returns:
+            ``ChatOpenAI``: The updated instance with tools bound.
+        """
+        self._tools = tools
+        self._tool_choice = tool_choice
+        self._parallel_tool_calls = parallel_tool_calls
+        return self
+
+    def chat(
+        self,
+        *,
+        messages: 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:
+        """Call the model with the given messages.
+
+        Args:
+            messages: List of messages in OpenAI format.
+            stream: Whether to stream the output.
+            tools: Optional list of OpenAI tool definitions.
+            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).
+        """
+        params = {
+            "model": self.model,
+            "input": messages,
+            "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
+
+        # Tools resolution
+        current_tools = tools or (
+            [tool.to_openai_tool() for tool in self._tools] if self._tools else None
+        )
+        if current_tools:
+            params["tools"] = current_tools
+            params["tool_choice"] = tool_choice or self._tool_choice
+            params["parallel_tool_calls"] = (
+                parallel_tool_calls
+                if parallel_tool_calls is not None
+                else self._parallel_tool_calls
+            )
+
+        return self.client.responses.create(**params)
+
+    def invoke(self, messages: List[Dict[str, Any]]) -> Any:
+        """Synchronously call the model.
+
+        Args:
+            messages: List of messages in OpenAI format.
+
+        Returns:
+            Any: The OpenAI Responses API response object.
+        """
+        return self.chat(messages=messages, stream=False)
+
+    def stream(
+        self,
+        *,
+        messages: List[Dict[str, Any]],
+    ) -> Iterator[Any]:
+        """Stream the model response.
+
+        Args:
+            messages: List of messages in OpenAI format.
+
+        Yields:
+            Any: Streamed response events from the OpenAI Responses API.
+        """
+        response = self.chat(messages=messages, stream=True)
+        for event in response:
+            yield event

literun/prompt_message.py

@@ -0,0 +1,136 @@
+"""Message structures for prompts."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .constants import Role, ContentType
+
+
+class PromptMessage:
+    """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
+
+        self._validate()
+
+    def _validate(self) -> None:
+        """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.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:
+            if not self.name:
+                raise ValueError("name is required for FUNCTION_CALL")
+            if not isinstance(self.arguments, str):
+                raise ValueError("arguments must be a JSON string")
+            if not self.call_id:
+                raise ValueError("call_id is required for FUNCTION_CALL")
+
+        # Tool output (agent -> model)
+        elif self.content_type == ContentType.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}")
+
+    def to_openai_message(self) -> Dict[str, Any]:
+        """Convert the PromptMessage to an OpenAI-compatible message dictionary.
+
+        Returns:
+            Dict[str, Any]: The formatted message dictionary.
+
+        Raises:
+            ValueError: If required fields are missing for the specified content_type.
+            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):
+            return {
+                "role": self.role.value,
+                "content": [
+                    {
+                        "type": self.content_type.value,
+                        "text": self.text,
+                    }
+                ],
+            }
+
+        # Tool call (model -> agent)
+        if self.content_type == ContentType.FUNCTION_CALL:
+            return {
+                "type": self.content_type.value,
+                "name": self.name,
+                "arguments": self.arguments,
+                "call_id": self.call_id,
+            }
+
+        # Tool output (agent -> model)
+        if self.content_type == ContentType.FUNCTION_CALL_OUTPUT:
+            return {
+                "type": self.content_type.value,
+                "call_id": self.call_id,
+                "output": self.output,
+            }
+
+        # Should never reach here due to validation
+        raise RuntimeError("Invalid PromptMessage state")
+
+    def __repr__(self) -> str:
+        """Return a concise representation of the message for debugging."""
+        return (
+            f"PromptMessage("
+            f"content_type={self.content_type}, "
+            f"role={self.role}, "
+            f"name={self.name}, "
+            f"call_id={self.call_id}"
+            f")"
+        )

literun/prompt_template.py

@@ -0,0 +1,181 @@
+"""Template management for constructing prompts."""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Dict, Any
+
+from .prompt_message import PromptMessage
+from .constants import Role, ContentType
+
+
+class PromptTemplate:
+    """Container for conversation state.
+
+    This class stores the authoritative message history used by the Agent.
+    It manages ``PromptMessage`` objects and serializes them only at the
+    OpenAI API boundary.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty PromptTemplate."""
+
+        self.messages: List[PromptMessage] = []
+
+    def add_message(self, message: PromptMessage) -> PromptTemplate:
+        """Add a custom prompt message.
+
+        Args:
+            message: The message to add.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+
+        Raises:
+            TypeError: If `message` is not a ``PromptMessage`` instance.
+        """
+        if not isinstance(message, PromptMessage):
+            raise TypeError("Expected PromptMessage")
+        self.messages.append(message)
+        return self
+
+    def add_messages(self, messages: Iterable[PromptMessage]) -> PromptTemplate:
+        """Add multiple prompt messages.
+
+        Args:
+            messages: An iterable of messages to add.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        for message in messages:
+            self.add_message(message)
+        return self
+
+    def add_system(self, text: str) -> PromptTemplate:
+        """Add a system message.
+
+        Args:
+            text: The system message text.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        return self.add_message(
+            PromptMessage(
+                role=Role.DEVELOPER,
+                content_type=ContentType.INPUT_TEXT,
+                text=text,
+            )
+        )
+
+    def add_user(self, text: str) -> PromptTemplate:
+        """Add a user message.
+
+        Args:
+            text: The user message text.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        return self.add_message(
+            PromptMessage(
+                role=Role.USER,
+                content_type=ContentType.INPUT_TEXT,
+                text=text,
+            )
+        )
+
+    def add_assistant(self, text: str) -> PromptTemplate:
+        """Add an assistant message.
+
+        Args:
+            text: The assistant message text.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        return self.add_message(
+            PromptMessage(
+                role=Role.ASSISTANT,
+                content_type=ContentType.OUTPUT_TEXT,
+                text=text,
+            )
+        )
+
+    def add_tool_call(
+        self,
+        *,
+        name: str,
+        arguments: str,
+        call_id: str,
+    ) -> PromptTemplate:
+        """Add a tool call message.
+
+        Args:
+            name: The name of the tool being called.
+            arguments: The tool arguments, encoded as a JSON string.
+            call_id: The unique identifier for this tool call.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        return self.add_message(
+            PromptMessage(
+                content_type=ContentType.FUNCTION_CALL,
+                name=name,
+                arguments=arguments,
+                call_id=call_id,
+            )
+        )
+
+    def add_tool_output(
+        self,
+        *,
+        call_id: str,
+        output: str,
+    ) -> PromptTemplate:
+        """Add a tool output message.
+
+        Args:
+            call_id: The ID of the tool call this output corresponds to.
+            output: The output produced by the tool.
+
+        Returns:
+            ``PromptTemplate``: The template instance, allowing method chaining.
+        """
+        return self.add_message(
+            PromptMessage(
+                content_type=ContentType.FUNCTION_CALL_OUTPUT,
+                call_id=call_id,
+                output=output,
+            )
+        )
+
+    def copy(self) -> PromptTemplate:
+        """Create a shallow copy of this template.
+
+        This is required to avoid mutating caller-owned templates inside
+        the Agent.
+
+        Returns:
+            ``PromptTemplate``: A new template containing the same messages.
+        """
+        new = PromptTemplate()
+        new.messages = list(self.messages)
+        return new
+
+    def to_openai_input(self) -> List[Dict[str, Any]]:
+        """Convert the template to OpenAI message dictionaries.
+
+        Returns:
+            List[Dict[str, Any]]: The formatted messages.
+        """
+        return [msg.to_openai_message() for msg in self.messages]
+
+    def __len__(self) -> int:
+        """Return the number of messages in the template."""
+        return len(self.messages)
+
+    def __iter__(self):
+        """Iterate over stored messages."""
+        return iter(self.messages)

literun/results.py

@@ -0,0 +1,51 @@
+"""Return types for agent execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from openai.types.responses import Response
+from .items import RunItem
+from .events import StreamEvent
+
+
+@dataclass
+class RunResult:
+    """Final result returned by the OpenAI Agent.
+
+    Used in the ``Agent.invoke()`` method. Contains the full execution
+    trace accumulated during a single agent run.
+    """
+
+    input: str | list[Any]
+    """The original input items before ``run()`` was called."""
+
+    new_items: Response | list[RunItem]
+    """Items generated during the agent run, such as messages, tool calls,
+    and tool outputs.
+    """
+
+    final_output: Any
+    """The output produced by the final agent invocation."""
+
+
+@dataclass
+class RunResultStreaming:
+    """Streaming result returned by the OpenAI Agent.
+
+    Used in the ``Agent.stream()`` method. Each instance represents a
+    single stream event while accumulating completed items.
+    """
+
+    input: str | list[Any]
+    """The original input items before ``run()`` was called."""
+
+    event: StreamEvent
+    """The stream event emitted for this iteration."""
+
+    final_output: Any
+    """The output produced by the final agent invocation.
+
+    This value is `None` until the final message is complete.
+    """