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

literun/runner.py

@@ -0,0 +1,342 @@
+"""Agent execution runner."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterator, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .agent import Agent
+
+from .items import (
+    RunItem,
+    MessageOutputItem,
+    ToolCallItem,
+    ToolCallOutputItem,
+    ReasoningItem,
+    ResponseFunctionToolCallOutput,
+)
+from .results import RunResult, RunResultStreaming
+from .events import (
+    ResponseFunctionCallOutputItemAddedEvent,
+    ResponseFunctionCallOutputItemDoneEvent,
+)
+from .prompt_template import PromptTemplate
+
+
+class Runner:
+    """Executes agent runs."""
+
+    @classmethod
+    def run(
+        cls,
+        agent: Agent,
+        user_input: str,
+        prompt_template: PromptTemplate | None = None,
+        runtime_context: dict[str, Any] | None = None,
+    ) -> RunResult:
+        """Run the agent synchronously.
+
+        This method executes the agent loop, calling the language model and any
+        registered tools until a final output is produced or the maximum number
+        of iterations is reached.
+
+        Args:
+            agent: The agent instance to run.
+            user_input: The input text from the user.
+            prompt_template: Optional template to initialize conversation history.
+            runtime_context: Optional runtime context dictionary to pass to tools.
+
+        Returns:
+            ``RunResult``: The result of the agent run, including output items and final text.
+
+        Raises:
+            ValueError: If `user_input` is empty.
+            RuntimeError: If the agent exceeds `max_iterations`.
+        """
+        if not user_input:
+            raise ValueError("user_input cannot be empty")
+
+        prompt = cls._build_prompt(agent, user_input, prompt_template)
+        all_items: list[RunItem] = []
+
+        iteration = 0
+        while iteration < agent.max_iterations:
+            response = agent.llm.chat(
+                messages=prompt,
+                stream=False,
+                tools=agent.tools,
+                tool_choice=agent.tool_choice,
+                parallel_tool_calls=agent.parallel_tool_calls,
+            )
+
+            tool_calls: dict[str, dict[str, Any]] = {}
+            final_output_text: str = ""
+
+            for item in response.output:
+                if item.type == "reasoning":
+                    all_items.append(
+                        ReasoningItem(
+                            role="assistant",
+                            content=item.content,
+                            raw_item=item,
+                            type="reasoning_item",
+                        )
+                    )
+
+                elif item.type == "function_call":
+                    tool_calls[item.id] = {
+                        "call_id": item.call_id,
+                        "name": item.name,
+                        "arguments": item.arguments,
+                    }
+                    all_items.append(
+                        ToolCallItem(
+                            role="assistant",
+                            content="",
+                            raw_item=item,
+                            type="tool_call_item",
+                        )
+                    )
+
+                elif item.type == "message":
+                    text_parts = [
+                        c.text for c in item.content if c.type == "output_text"
+                    ]
+                    final_output_text = "".join(text_parts)
+                    all_items.append(
+                        MessageOutputItem(
+                            role="assistant",
+                            content=final_output_text,
+                            raw_item=item,
+                            type="message_output_item",
+                        )
+                    )
+
+            if not tool_calls:
+                return RunResult(
+                    input=user_input,
+                    new_items=all_items,
+                    final_output=final_output_text,
+                )
+
+            if final_output_text:
+                prompt.add_assistant(final_output_text)
+
+            for tc in tool_calls.values():
+                call_id = tc["call_id"]
+                name = tc["name"]
+                arguments_str = tc["arguments"]
+
+                prompt.add_tool_call(
+                    name=name,
+                    arguments=arguments_str,
+                    call_id=call_id,
+                )
+
+                tool_output = cls._execute_tool(
+                    agent, name, arguments_str, runtime_context
+                )
+
+                prompt.add_tool_output(call_id=call_id, output=tool_output)
+
+                all_items.append(
+                    ToolCallOutputItem(
+                        role="tool",
+                        content=tool_output,
+                        raw_item=ResponseFunctionToolCallOutput(
+                            call_id=call_id,
+                            output=tool_output,
+                            name=name,
+                            type="function_call_output",
+                            status="completed",
+                        ),
+                        type="tool_call_output_item",
+                    )
+                )
+            iteration += 1
+
+        raise RuntimeError(f"Agent exceeded max iterations ({agent.max_iterations})")
+
+    @classmethod
+    def run_streamed(
+        cls,
+        agent: Agent,
+        user_input: str,
+        prompt_template: PromptTemplate | None = None,
+        runtime_context: dict[str, Any] | None = None,
+    ) -> Iterator[RunResultStreaming]:
+        """Run the agent with streaming output.
+
+        This method streams response events from the agent as they occur,
+        including messages, tool calls, and tool outputs. It allows
+        real-time processing of the agent's reasoning and tool execution.
+
+        Args:
+            user_input: The input text from the user.
+            prompt_template: Optional template to initialize conversation history.
+            runtime_context: Optional runtime context dictionary to pass to tools.
+
+        Yields:
+            ``RunResultStreaming``: Streaming events containing the current input,
+                the event from the LLM or tool, and the accumulated final output.
+
+        Raises:
+            ValueError: If `user_input` is empty.
+            RuntimeError: If the agent exceeds `max_iterations`.
+        """
+        if not user_input:
+            raise ValueError("user_input cannot be empty")
+
+        prompt = cls._build_prompt(agent, user_input, prompt_template)
+
+        iteration = 0
+        while iteration < agent.max_iterations:
+            response_stream = agent.llm.chat(
+                messages=prompt,
+                stream=True,
+                tools=agent.tools,
+                tool_choice=agent.tool_choice,
+                parallel_tool_calls=agent.parallel_tool_calls,
+            )
+
+            tool_calls: dict[str, dict[str, Any]] = {}
+            final_output_text: str = ""
+
+            for event in response_stream:
+                yield RunResultStreaming(
+                    input=user_input,
+                    event=event,
+                    final_output=final_output_text,
+                )
+
+                if event.type == "response.output_item.done":
+                    if event.item.type == "message":
+                        for content_part in event.item.content:
+                            if content_part.type == "output_text":
+                                final_output_text += content_part.text
+
+                    elif event.item.type == "function_call":
+                        tool_calls[event.item.id] = {
+                            "call_id": event.item.call_id,
+                            "name": event.item.name,
+                            "arguments": event.item.arguments,
+                        }
+
+            if not tool_calls:
+                return
+
+            if final_output_text:
+                prompt.add_assistant(final_output_text)
+
+            for tc in tool_calls.values():
+                call_id = tc["call_id"]
+                name = tc["name"]
+                arguments_str = tc["arguments"]
+
+                prompt.add_tool_call(
+                    name=name, arguments=arguments_str, call_id=call_id
+                )
+
+                yield RunResultStreaming(
+                    input=user_input,
+                    event=ResponseFunctionCallOutputItemAddedEvent(
+                        type="response.function_call_output_item.added",
+                        item=ResponseFunctionToolCallOutput(
+                            call_id=call_id,
+                            output="",
+                            name=name,
+                            type="function_call_output",
+                            status="in_progress",
+                        ),
+                        output_index=None,
+                        sequence_number=None,
+                    ),
+                    final_output=final_output_text,
+                )
+
+                tool_output = cls._execute_tool(
+                    agent, name, arguments_str, runtime_context
+                )
+
+                prompt.add_tool_output(call_id=call_id, output=tool_output)
+
+                yield RunResultStreaming(
+                    input=user_input,
+                    event=ResponseFunctionCallOutputItemDoneEvent(
+                        type="response.function_call_output_item.done",
+                        item=ResponseFunctionToolCallOutput(
+                            call_id=call_id,
+                            output=tool_output,
+                            name=name,
+                            type="function_call_output",
+                            status="completed",
+                        ),
+                        output_index=None,
+                        sequence_number=None,
+                    ),
+                    final_output=final_output_text,
+                )
+            iteration += 1
+
+        raise RuntimeError(f"Agent exceeded max iterations ({agent.max_iterations})")
+
+    @staticmethod
+    def _build_prompt(
+        agent: Agent,
+        user_input: str,
+        prompt_template: PromptTemplate | None = None,
+    ) -> PromptTemplate:
+        """Construct the conversation state for a new agent turn.
+
+        Args:
+            user_input: The user's input text.
+            prompt_template: Optional template to initialize conversation history.
+                If None, a new ``PromptTemplate`` is created, and the system prompt is added if available.
+
+        Returns:
+            ``PromptTemplate``: The fully constructed prompt containing system, user, and previous messages.
+        """
+        if prompt_template is not None:
+            prompt = prompt_template.copy()
+        else:
+            prompt = PromptTemplate()
+            if agent.system_prompt:
+                prompt.add_system(agent.system_prompt)
+
+        prompt.add_user(user_input)
+        return prompt
+
+    @staticmethod
+    def _execute_tool(
+        agent: Agent,
+        name: str,
+        arguments: str | dict[str, Any],
+        runtime_context: dict[str, Any] | None = None,
+    ) -> str:
+        """Execute a registered tool safely with provided arguments.
+
+        Handles parsing of arguments (from JSON string or dict) and catches execution errors.
+
+        Args:
+            name: The name of the tool to execute.
+            arguments: Arguments to pass to the tool, either as a JSON string or dict.
+            runtime_context: Optional runtime context to pass to tool arguments of type ``ToolRuntime``.
+
+        Returns:
+            str: The output of the tool execution, or an error message if execution fails.
+        """
+        tool = agent._tools.get(name)
+        if not tool:
+            return f"Error: Tool '{name}' not found"
+
+        try:
+            if isinstance(arguments, str):
+                args = json.loads(arguments)
+            else:
+                args = arguments
+
+            result = tool.execute(args, runtime_context)
+            return str(result)
+        except Exception as e:
+            return f"Error executing tool '{name}': {e}"

literun/tool.py

@@ -3,71 +3,57 @@
 from __future__ import annotations
 
 import inspect
-from typing import Any, Dict, List, Optional, Callable, get_type_hints
+from typing import Any, Callable, get_type_hints
+from pydantic import BaseModel, ConfigDict
 
 from .args_schema import ArgsSchema
 
 
-class ToolRuntime:
+class ToolRuntime(BaseModel):
     """Runtime context container for tools.
 
-    This class stores arbitrary runtime values as attributes, using keyword
-    arguments provided at initialization. It is typically injected into tool
-    functions that declare a parameter annotated with ``ToolRuntime``.
+    This class corresponds to arbitrary runtime values passed via `runtime_context`
+    in `Agent.invoke()`. It allows extra arguments on initialization.
 
     Args:
         **kwargs: Arbitrary keyword arguments that will be set as attributes
             on the instance.
     """
 
-    def __init__(self, **kwargs):
-        for k, v in kwargs.items():
-            setattr(self, k, v)
+    model_config = ConfigDict(extra="allow")
 
-    def __repr__(self):
-        return f"ToolRuntime({self.__dict__})"
 
-
-class Tool:
+class Tool(BaseModel):
     """Represents a callable tool that can be invoked by an agent or LLM.
 
     A ``Tool`` wraps a Python callable along with metadata and an argument
     schema, and provides utilities for argument validation, execution,
     and conversion to the OpenAI tool definition format.
+
+    Args:
+        func: The function to execute when the tool is called.
+        name: The name of the tool.
+        description: A description of what the tool does.
+        args_schema: A list of arguments the tool accepts.
+        strict: If True, model output is guaranteed to exactly match the JSON Schema
+            provided in the function definition. If None, `strict` argument will not
+            be included in tool definition.
     """
 
-    def __init__(
-        self,
-        *,
-        func: Callable,
-        name: str,
-        description: str,
-        args_schema: List[ArgsSchema],
-        strict: Optional[bool] = None,
-    ):
-        """Initialize a Tool.
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-        Args:
-            func: The function to execute when the tool is called.
-            name: The name of the tool.
-            description: A description of what the tool does.
-            args_schema: A list of arguments the tool accepts.
-            strict: If True, model output is guaranteed to exactly match the JSON Schema
-                provided in the function definition. If None, `strict` argument will not
-                be included in tool definition.
-        """
-        self.func = func
-        self.name = name
-        self.description = description
-        self.args_schema = args_schema
-        self.strict = strict
+    func: Callable
+    name: str
+    description: str
+    args_schema: list[ArgsSchema]
+    strict: bool | None = None
 
     # OpenAI schema
-    def to_openai_tool(self) -> Dict[str, Any]:
+    def to_openai_tool(self) -> dict[str, Any]:
         """Convert the tool to the OpenAI tool schema format.
 
         Returns:
-            Dict[str, Any]: The OpenAI-compatible tool definition.
+            dict[str, Any]: The OpenAI-compatible tool definition.
         """
         properties = {}
         required = []
@@ -90,14 +76,14 @@ class Tool:
         }
 
     # LLM Runtime argument handling
-    def resolve_arguments(self, raw_args: Dict[str, Any]) -> Dict[str, Any]:
+    def resolve_arguments(self, raw_args: dict[str, Any]) -> dict[str, Any]:
         """Validate and cast raw arguments provided by the model.
 
         Args:
             raw_args: The raw argument dictionary produced by the model.
 
         Returns:
-            Dict[str, Any]: A dictionary of validated and type-cast arguments.
+            dict[str, Any]: A dictionary of validated and type-cast arguments.
         """
         parsed = {}
         for arg in self.args_schema:
@@ -105,7 +91,9 @@ class Tool:
         return parsed
 
     def execute(
-        self, args: Dict[str, Any], runtime_context: Optional[Dict[str, Any]] = None
+        self,
+        args: dict[str, Any],
+        runtime_context: dict[str, Any] | None = None,
     ) -> Any:
         """Execute the tool with validated arguments and runtime context.
 

literun-0.1.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: literun
+Version: 0.1.1
+Summary: A Minimal agent runtime built on OpenAI Responses API
+Project-URL: Homepage, https://github.com/kaustubh-tr/literun
+Project-URL: Source, https://github.com/kaustubh-tr/literun
+Project-URL: Issues, https://github.com/kaustubh-tr/literun/issues
+Project-URL: Readme, https://github.com/kaustubh-tr/literun#readme
+Project-URL: Documentation, https://github.com/kaustubh-tr/literun/blob/main/DOCS.md
+Author-email: Kaustubh Trivedi <trivedikaustubh01@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Kaustubh Trivedi
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: openai<3.0.0,>=2.11.0
+Requires-Dist: pydantic<3.0.0,>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10.0.0,>=9.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LiteRun 🚀
+
+[![PyPI - Version](https://img.shields.io/pypi/v/literun)](https://pypi.org/project/literun/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/literun)](https://pypi.org/project/literun/)
+[![PyPI - License](https://img.shields.io/pypi/l/literun)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-DOCS-blue)](https://github.com/kaustubh-tr/literun/blob/main/DOCS.md)
+
+A lightweight, flexible Python framework for building custom OpenAI agents (Responses API) with tool support and structured prompt management.
+
+## Features
+
+- **Custom Agent Execution**: Control the loop with synchronous and streaming support.
+- **Tool Support**: Easy registration with Pydantic-powered validation.
+- **Type Safety**: Built for modern Python 3.10+ environments.
+- **Prompt Templates**: Structured message management.
+- **Event-Driven**: Granular control via a rich event system.
+
+For detailed documentation on Architecture, Streaming, and Advanced Configuration, see [DOCS.md](https://github.com/kaustubh-tr/literun/blob/main/DOCS.md).
+
+## Requirements
+
+- Python 3.10+
+
+> **Note**: Core dependencies like `openai` and `pydantic` are automatically installed when you install `literun`.
+
+## Installation
+
+You can install `literun` directly from PyPI:
+
+```bash
+pip install literun
+```
+
+## Quick Start
+
+### Basic Agent
+
+Here is a simple example of how to create an agent with a custom tool.
+
+```python
+import os
+from literun import Agent, ChatOpenAI, Tool, ArgsSchema
+
+# 1. Define a tool function
+def get_weather(location: str, unit: str = "celsius") -> str:
+    return f"The weather in {location} is 25 degrees {unit}."
+
+# 2. Wrap it with Tool schema
+weather_tool = Tool(
+    func=get_weather,
+    name="get_weather",
+    description="Get the weather for a location",
+    args_schema=[
+        ArgsSchema(
+            name="location",
+            type=str,
+            description="The city and state, e.g. San Francisco, CA",
+        ),
+        ArgsSchema(
+            name="unit",
+            type=str,
+            description="The unit of temperature",
+            enum=["celsius", "fahrenheit"],
+        ),
+    ],
+)
+
+# 3. Initialize Agent
+agent = Agent(
+    llm=ChatOpenAI(model="gpt-4.1-mini", temperature=0.7),
+    system_prompt="You are a helpful assistant.",
+    tools=[weather_tool],
+)
+
+# 4. Run the Agent
+result = agent.invoke(user_input="What is the weather in Tokyo?")
+print(f"Final Answer: {result.final_output}")
+```
+
+### Advanced Usage
+
+LiteRun supports **Streaming**, **Runtime Context Injection** (for secrets), and **Direct LLM Usage**.
+
+👉 Check out the [Documentation](https://github.com/kaustubh-tr/literun/blob/main/DOCS.md) and [Examples](https://github.com/kaustubh-tr/literun/blob/main/examples/) for more details.
+
+## Project Structure
+
+```text
+literun/
+├── src/
+│   └── literun/          # Main package source
+│       ├── agent.py      # Agent orchestrator
+│       ├── llm.py        # ChatOpenAI wrapper
+│       ├── tool.py       # Tool & Schema definitions
+│       └── ...
+├── tests/                # Unit tests (agent, llm, tools, prompts)
+├── examples/             # Runnable examples
+├── DOCS.md               # Detailed documentation
+├── LICENSE               # MIT License
+├── README.md             # This file
+└── pyproject.toml        # Project configuration & dependencies
+```
+
+## Contributing
+
+We welcome contributions! Please follow these steps to set up your development environment:
+
+1.  **Fork** the repository and clone it locally:
+
+    ```bash
+    git clone https://github.com/kaustubh-tr/literun.git
+    cd literun
+    ```
+
+2.  **Install** in editable mode with development dependencies:
+
+    ```bash
+    pip install -e .[dev]
+    ```
+
+3.  **Create** a feature branch and make your changes.
+
+4.  **Test** your changes (see below).
+
+5.  **Submit** a pull request.
+
+## Testing
+
+This project uses `pytest` as the primary test runner, but supports `unittest` as well.
+
+```bash
+# Run all tests
+pytest
+```
+
+or using unittest:
+
+```bash
+python -m unittest discover tests
+```
+
+> **Note**: Some integration tests require the `OPENAI_API_KEY` environment variable. They are automatically skipped if it is missing.
+
+## License
+
+Copyright (c) 2026 Kaustubh Trivedi.
+
+Distributed under the terms of the [MIT](https://github.com/kaustubh-tr/literun/blob/main/LICENSE) license, LiteRun is free and open source software.

literun-0.1.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+literun/__init__.py,sha256=ojY1q7jAS0tXQ-qhkyKzVG3MTKSaaGZSuoo0liuuZzs,707
+literun/agent.py,sha256=NjP8g3kNriPJ0vFF8jB5NuRjxgfqrErU1L7zIiRkmuY,5192
+literun/args_schema.py,sha256=rkn_mvC1HnFUtV2r6-PigQdvo3SWIQDUB23uIrv_vsw,2486
+literun/constants.py,sha256=K-5f6Rhbkqb89HV2paB56nOsWgb_YI95oZM0eU5Vmus,688
+literun/events.py,sha256=F_p9Dp4FCY4HPdjkSfPk_C5fbGDGmwEf6NO4KRsfCww,3624
+literun/items.py,sha256=PM8zFrEv-5sncwZOU7ruhN1dVX-GjcVx21ivsKk8V08,2894
+literun/llm.py,sha256=WxDhVtSWxuhwQ2Icl2tfjkyMvnyXT9BjTpEGwwyGxlI,8639
+literun/prompt_message.py,sha256=zV56UB7FvxGqECRwKkqY9fh4ihBoG9t86ClmfZpB6-w,4594
+literun/prompt_template.py,sha256=1pmXbvOKDydQgOegLPwSa2WwPtbWthY3jsVXZPsRWDg,4995
+literun/results.py,sha256=YHa5rXh5YkSB6mEVBG6aJOZjYOp6WtdDqh5ugpbK2nE,1321
+literun/runner.py,sha256=rkLr1fYJY5SMdQR8uZ1NQ9jCGzawJzP-MJYxgBDrcZs,12124
+literun/tool.py,sha256=dzNJ3JwVu7X9u34eb2GC047wMDetqcle_4thCUjZe6I,4659
+literun/utils.py,sha256=4r9P7u46KzuG3eNZq8kfuEWJxpc4b8T26nrzjW7_Hec,2261
+literun-0.1.1.dist-info/METADATA,sha256=7hFvFpyDWMW5nqaClX8FJ2MpANcLBRXNNfJUgfGa--o,6488
+literun-0.1.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+literun-0.1.1.dist-info/licenses/LICENSE,sha256=sJlY4ztFUqGGojhTNtL2UbhQeSZF3B4V1dAtzGfMHOE,1073
+literun-0.1.1.dist-info/RECORD,,

{literun-0.1.0.dist-info → literun-0.1.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.2)
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-