literun 0.1.0__py3-none-any.whl

literun/tool.py

@@ -0,0 +1,145 @@
+"""Tool definition and runtime context."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Dict, List, Optional, Callable, get_type_hints
+
+from .args_schema import ArgsSchema
+
+
+class ToolRuntime:
+    """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``.
+
+    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)
+
+    def __repr__(self):
+        return f"ToolRuntime({self.__dict__})"
+
+
+class Tool:
+    """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.
+    """
+
+    def __init__(
+        self,
+        *,
+        func: Callable,
+        name: str,
+        description: str,
+        args_schema: List[ArgsSchema],
+        strict: Optional[bool] = None,
+    ):
+        """Initialize a Tool.
+
+        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
+
+    # OpenAI schema
+    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.
+        """
+        properties = {}
+        required = []
+
+        for arg in self.args_schema:
+            properties[arg.name] = arg.to_json_schema()
+            required.append(arg.name)
+
+        return {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+                "additionalProperties": False,
+            },
+            **({"strict": self.strict} if self.strict is not None else {}),
+        }
+
+    # LLM Runtime argument handling
+    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.
+        """
+        parsed = {}
+        for arg in self.args_schema:
+            parsed[arg.name] = arg.validate_and_cast(raw_args.get(arg.name))
+        return parsed
+
+    def execute(
+        self, args: Dict[str, Any], runtime_context: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        """Execute the tool with validated arguments and runtime context.
+
+        This method resolves and validates model-provided arguments, injects
+        a ``ToolRuntime`` instance into the function call if requested by the
+        function's type annotations, and then invokes the underlying function.
+
+        Args:
+            args: Raw arguments provided by the model.
+            runtime_context: Optional runtime context data used to construct
+                a ``ToolRuntime`` instance when required.
+
+        Returns:
+            Any: The return value of the underlying tool function.
+        """
+        # 1. Resolve LLM arguments using the tool's schema logic
+        final_args = self.resolve_arguments(args)
+
+        # 2. Inject ToolRuntime if requested by the function signature
+        # Use get_type_hints to properly resolve annotations, including forward references
+        try:
+            type_hints = get_type_hints(self.func)
+        except (NameError, AttributeError, TypeError):
+            # Fallback to inspect.signature if get_type_hints fails
+            # This handles cases where annotations can't be resolved
+            sig = inspect.signature(self.func)
+            type_hints = {
+                name: param.annotation
+                for name, param in sig.parameters.items()
+                if param.annotation != inspect.Parameter.empty
+            }
+
+        for param_name, param_type in type_hints.items():
+            if param_type is ToolRuntime:
+                final_args[param_name] = ToolRuntime(**(runtime_context or {}))
+
+        return self.func(**final_args)

literun/utils.py

@@ -0,0 +1,73 @@
+"""Utilities for extracting structured data from OpenAI response objects."""
+
+from __future__ import annotations
+
+from typing import List, Dict, Any
+
+
+def extract_output_text(response: Any) -> str:
+    """Extracts and concatenates output text from the response object.
+
+    Args:
+        response: The response object containing output messages.
+
+    Returns:
+        str: The concatenated output text.
+    """
+    texts: List[str] = []
+    for output in response.output:
+        if output.type == "message":
+            for content in output.content:
+                if content.type == "output_text":
+                    texts.append(content.text)
+
+    return "".join(texts)
+
+
+def extract_tool_calls(response: Any) -> List[Dict[str, Any]]:
+    """Extracts tool call information from the response object into a list of dictionaries.
+
+    Args:
+        response: The response object containing tool call information.
+
+    Returns:
+        List[Dict[str, Any]]: A list of dictionaries with tool call details.
+    """
+    import json
+
+    tool_calls: List[Dict[str, Any]] = []
+    for output in response.output:
+        if output.type == "function_call":
+            tool_calls.append(
+                {
+                    "arguments": json.loads(output.arguments),
+                    "call_id": output.call_id,
+                    "name": output.name,
+                    "type": output.type,
+                    "id": output.id,
+                    "status": output.status,
+                }
+            )
+    return tool_calls
+
+
+def extract_usage_dict(response: Any) -> Dict[str, Any]:
+    """Extracts usage statistics from the response object into a dictionary.
+
+    Args:
+        response: The response object containing usage statistics.
+
+    Returns:
+        Dict[str, Any]: A dictionary with usage statistics.
+    """
+    return {
+        "input_tokens": response.usage.input_tokens,
+        "input_tokens_details": {
+            "cached_tokens": response.usage.input_tokens_details.cached_tokens
+        },
+        "output_tokens": response.usage.output_tokens,
+        "output_tokens_details": {
+            "reasoning_tokens": response.usage.output_tokens_details.reasoning_tokens
+        },
+        "total_tokens": response.usage.total_tokens,
+    }

literun-0.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: literun
+Version: 0.1.0
+Summary: A Minimal agent runtime built on OpenAI Responses API
+Author-email: Kaustubh <trivedikaustubh01@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=2.11.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+# LiteRun 🚀
+
+A lightweight, flexible Python framework for building custom OpenAI agents (Responses API) with tool support and structured prompt management.
+
+## Features
+
+- **Custom Agent Execution**: Complete control over the agent execution loop, supporting both synchronous and streaming responses.
+- **Tool Support**: Easy registration and execution of Python functions as tools.
+- **Type Safety**: Strong typing for tool arguments with automatic coercion and validation.
+- **Prompt Templates**: Structured way to build system, user, and assistant messages.
+- **Constants**: Pre-defined constants for OpenAI roles and message types.
+- **Streaming Support**: Built-in support for real-time streaming of agent thoughts, tool calls, and responses.
+- **Tool Management**: Easy-to-define tools with automatic JSON schema generation (`ArgsSchema`).
+- **Event-Driven**: Structured event system for granular control over the agent's execution lifecycle.
+- **OpenAI Compatible**: Seamlessly integrates with `openai-python` client.
+
+## Requirements
+
+- Python 3.10+  
+- [OpenAI Python API library](https://pypi.org/project/openai/)
+
+## Installation
+
+### Production
+
+```bash
+pip install literun
+```
+
+### Development
+
+```bash
+git clone https://github.com/kaustubh-tr/literun.git
+cd openai-agent
+pip install -e .[dev]
+```
+
+## 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 LLM and Agent
+llm = ChatOpenAI(model="gpt-4o", temperature=0.7)
+
+# 4. Initialize Agent
+agent = Agent(
+    llm=llm,
+    system_prompt="You are a helpful assistant.",
+    tools=[weather_tool],
+)
+
+# 5. Run the Agent
+result = agent.invoke(user_input="What is the weather in Tokyo?")
+print(f"Final Answer: {result.final_output}")
+```
+
+### Streaming Agent
+
+You can also stream the agent's execution to handle events in real-time:
+
+```python
+# ... (setup tool and agent as above)
+
+print("Agent: ", end="", flush=True)
+for result in agent.stream(user_input="What is the weather in Tokyo?"):
+    event = result.event
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="", flush=True)
+    elif event.type == "response.function_call_arguments.done":
+        print(f"\n[Tool Call: {event.name}]")
+
+print()
+```
+
+### Runtime Configuration (Context Injection)
+
+The framework allows passing a runtime context to tools using explicit context injection.
+
+Rules:
+1. Define a tool function with a parameter annotated with `ToolRuntime`.
+2. The framework will automatically inject the `runtime_context` (wrapped in `ToolRuntime`) into that parameter.
+3. Access configuration values using `ctx.{parameter}`.
+
+```python
+from typing import Dict, Any
+from literun import Tool, ArgsSchema, ToolRuntime
+
+# 1. Define tool with context
+def get_weather(location: str, ctx: ToolRuntime) -> str:
+    """
+    Returns weather info for a location.
+    The runtime context can include sensitive info like user_id or API keys.
+    """
+    user_id = getattr(ctx, "user_id", "unknown_user")
+    api_key = getattr(ctx, "weather_api_key", None)
+
+    # Simulate fetching weather
+    return f"Weather for {location} fetched using API key '{api_key}' for user '{user_id}'."
+
+# 2. Register tool 
+tool = Tool(
+    name="get_weather",
+    description="Get the weather for a given location",
+    func=get_weather,
+    args_schema=[
+        ArgsSchema(
+            name="location",
+            type=str,
+            description="Location for which to get the weather",
+        )
+    ]
+)
+
+# 3. Setup agent
+agent = Agent(
+    llm=ChatOpenAI(api_key="fake"), 
+    tools=[tool]
+)
+
+# 4. Pass config at runtime
+# The whole dict is passed into the 'ctx' argument
+agent.invoke(
+    user_input="What's the weather in London?",
+    runtime_context={
+        "user_id": "user_123",
+        "weather_api_key": "SECRET_API_KEY_456"
+    }
+)
+```
+
+### Using ChatOpenAI Directly
+
+You can also use the `ChatOpenAI` class directly if you don't need the agent loop (e.g., for simple, one-off LLM calls).
+
+```python
+from literun import ChatOpenAI
+
+llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "Tell me a joke."}
+]
+
+# Synchronous call
+# Returns the raw OpenAI Responses API response object
+response = llm.invoke(messages=messages)
+print(response.output_text)
+
+# Or streaming call
+# Returns a generator of raw OpenAI response stream events
+stream = llm.stream(messages=messages)
+for event in stream:
+    print(event)
+```
+
+See [examples](examples/) for complete runnable examples.
+
+## Project Structure
+
+The project is organized as follows:
+
+```
+literun/
+├── src/
+│   └── literun/          # Main package source
+│       ├── agent.py      # Agent runtime logic
+│       ├── llm.py        # LLM client wrapper
+│       ├── tool.py       # Tool definition and execution
+│       ├── events.py     # Stream event types
+│       └── ...
+├── tests/                # Unit tests
+├── examples/             # Usage examples
+└── pyproject.toml        # Project configuration
+```
+
+## Testing
+
+Run the test suite using `unittest`:
+
+```bash
+python -m unittest discover tests
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `python -m unittest discover tests`
+5. Update the example usage if needed
+6. Submit a pull request
+
+## License
+
+MIT

literun-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+literun/__init__.py,sha256=lnkWaQ_BYMVjyuPiRxmELOEMKzzqGw8n0DPEKIuNrgk,706
+literun/agent.py,sha256=CrMrvKHDlwQ4shqR1GkJv0pKq64mdIAy5VnVZoa-1To,15105
+literun/args_schema.py,sha256=bmLTybD4zPhjTwHkZrjQVEkiARHbje1SXTkH0hWyp0s,2618
+literun/constants.py,sha256=gSyuHnUdPuQBH3GKjp7FwZhk_C-F7ecF1IF-36H23_Q,453
+literun/events.py,sha256=SARUr4XWG9qpuy34hpZHHyJRX5btmJmBhBfvU8KbYyc,3615
+literun/items.py,sha256=SPINMwy8vOuK6iIqAMC5Av-BIgsCiuVKpYK_4vk70fk,2975
+literun/llm.py,sha256=7RU990Lw5XMY5RrlkepBaKFmP9cyZUu85SmUccrVIbY,5030
+literun/prompt_message.py,sha256=wizT6T8A4rsswcCyQVQeKyOdMPPFmSKtQoVUliMgV0M,4982
+literun/prompt_template.py,sha256=IFNZH80e2AO4u1p5L59Q49vvumU6nvToVHVXwkM_7mI,5128
+literun/results.py,sha256=7uRPdfzRzdI0HXhWhFiya4yhH-NmjGfdGZAgXMpfkpQ,1324
+literun/tool.py,sha256=iKQg1Xgh_Bzn1V0lVllmH1-G0XiHuDLkXOe0rCHRfc4,5049
+literun/utils.py,sha256=4r9P7u46KzuG3eNZq8kfuEWJxpc4b8T26nrzjW7_Hec,2261
+literun-0.1.0.dist-info/licenses/LICENSE,sha256=sJlY4ztFUqGGojhTNtL2UbhQeSZF3B4V1dAtzGfMHOE,1073
+literun-0.1.0.dist-info/METADATA,sha256=jTSF_nuY1_6T3ImwNAgAQcxkZ3TdVzHx8Ofmy8CmK1U,6649
+literun-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+literun-0.1.0.dist-info/top_level.txt,sha256=YFnS29wBQf5eX9UEtBYA1ZegxjIs_7n691L8qIR_QW0,8
+literun-0.1.0.dist-info/RECORD,,

literun-0.1.0.dist-info/WHEEL

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

literun-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.

literun-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+literun