literun 0.1.0__tar.gz → 0.1.1__tar.gz

literun-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,125 @@
+# Builds and publishes LiteRun packages to PyPI.
+
+name: "🚀 LiteRun Release"
+run-name: "Release ${{ inputs.version }}"
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (must match pyproject.toml)"
+        required: true
+        type: string
+
+permissions:
+  contents: write  # Required for creating GitHub releases
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Verify Version
+        # Mature Practice: The code in git is the source of truth.
+        # We verify inputs.version matches pyproject.toml instead of patching it.
+        run: |
+          # Extract version from pyproject.toml
+          PROJECT_VERSION=$(grep -m 1 '^version = ' pyproject.toml | cut -d '"' -f 2)
+          echo "Project Version: $PROJECT_VERSION"
+          echo "Input Version: ${{ inputs.version }}"
+          
+          if [ "$PROJECT_VERSION" != "${{ inputs.version }}" ]; then
+            echo "::error::Version mismatch! pyproject.toml has $PROJECT_VERSION but workflow input is ${{ inputs.version }}."
+            echo "Please update pyproject.toml in your code, commit, and push before releasing."
+            exit 1
+          fi
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check metadata
+        run: twine check dist/*
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to test PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+          skip-existing: true
+          verbose: true
+
+  verify-release:
+    name: Verify Release
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Wait for propagation
+        run: sleep 30
+
+      - name: Verify Installation
+        # Detailed verification similar to professional workflows
+        run: |
+          # Install from test PyPI, fallback to PyPI for deps
+          pip install --index-url https://test.pypi.org/simple/ \
+                      --extra-index-url https://pypi.org/simple/ \
+                      literun==${{ inputs.version }}
+          
+          # Verify import and version
+          python -c "import literun; print(f'Successfully installed literun {literun.__version__}')"
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: verify-release
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          verbose: true

literun-0.1.1/.gitignore

@@ -0,0 +1,61 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+__pypackages__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Database
+*.db
+*.sqlite
+
+# mkdocs documentation
+/site
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Logs
+*.log
+
+# macOS
+.DS_Store

literun-0.1.1/DOCS.md

@@ -0,0 +1,217 @@
+# LiteRun Documentation 📚
+
+LiteRun is a lightweight, flexible Python framework for building custom OpenAI agents. It provides a robust abstraction over the OpenAI Chat Completions API, adding tool management, structured prompt handling, and event-driven execution without the bloat of larger frameworks.
+
+## Table of Contents
+
+- [Core Architecture](#core-architecture)
+- [Agent Execution](#agent-execution)
+- [Tool Management](#tool-management)
+- [Runtime Context Injection](#runtime-context-injection)
+- [Prompt Templates](#prompt-templates)
+- [Streaming](#streaming)
+- [Direct LLM Usage](#direct-llm-usage)
+
+---
+
+## Core Architecture
+
+LiteRun is built around three main components:
+
+1.  **Agent**: The orchestrator that manages the interaction loop between the user, the LLM, and the tools.
+2.  **Tool**: A wrapper around Python functions that handles argument validation (via Pydantic logic) and schema generation for OpenAI.
+3.  **ChatOpenAI**: A wrapper around the `openai` client that handles API communication, including `bind_tools`.
+
+### Design Philosophy
+
+- **Type Safety**: Heavily relies on Python type hints and Pydantic for validation.
+- **Transparency**: Exposes raw OpenAI events and responses where possible.
+- **Simplicity**: Minimal abstractions; "it's just Python functions".
+
+---
+
+## Agent Execution
+
+The `Agent` runs a loop:
+
+1.  Appends user input to the history.
+2.  Calls the LLM.
+3.  If the LLM calls a tool:
+    - Executes the tool.
+    - Appends the tool result to the history.
+    - Repeats Step 2.
+4.  If the LLM responds with text, returns the final result.
+
+The `invoke` method returns a `RunResult` object containing the final output and a list of all items (messages, tool calls) generated in this run.
+
+```python
+agent = Agent(llm=llm, tools=[...])
+result = agent.invoke("Hello")
+
+# result is a RunResult object
+print(result.final_output)  # The text string
+print(result.new_items)     # List of all items (msgs, tool calls) generated in this run
+```
+
+---
+
+## Tool Management
+
+Tools are defined using the `Tool` class. You must provide:
+
+- `name`: Unique identifier.
+- `description`: Used by the LLM to understand when to call it.
+- `func`: The actual Python function.
+- `args_schema`: A definition of arguments for the LLM.
+
+### Using `ArgsSchema`
+
+The `ArgsSchema` maps argument names to types and descriptions. This generates the JSON Schema sent to OpenAI.
+
+```python
+from literun import Tool, ArgsSchema
+
+def my_func(x: int):
+    return x * 2
+
+tool = Tool(
+    name="doubler",
+    description="Doubles a number",
+    func=my_func,
+    args_schema=[
+        ArgsSchema(name="x", type=int, description="Number to double")
+    ]
+)
+```
+
+---
+
+## Runtime Context Injection
+
+Sometimes tools need access to data that shouldn't be visible to the LLM (e.g., database connections, User IDs, API keys). LiteRun supports **runtime context injection**.
+
+1.  Annotate an argument in your tool function with `ToolRuntime`.
+2.  Pass a dictionary to `agent.invoke(..., runtime_context={...})`.
+3.  The agent will automatically strip this argument from the LLM schema and inject the context object at execution time.
+
+```python
+from literun import ToolRuntime
+
+def sensitive_tool(data: str, ctx: ToolRuntime) -> str:
+    # 'data' comes from LLM
+    # 'ctx' comes from your application
+    api_key = getattr(ctx, "api_key", None)
+    return f"Processed {data} with {api_key}"
+
+# ... Initialize tool & agent ...
+
+agent.invoke(
+    "process data",
+    runtime_context={"api_key": "secret_123"}
+)
+```
+
+---
+
+## Prompt Templates
+
+The `PromptTemplate` class helps structure conversation history. It replaces simple list-of-dict management with a type-safe builder.
+
+```python
+from literun import PromptTemplate
+
+template = PromptTemplate()
+template.add_system("You are a helpful assistant.")
+template.add_user("Hello")
+template.add_assistant("Hi there")
+
+agent.invoke(user_input="How are you?", prompt_template=template)
+```
+
+You can also simulate tool interactions for testing or history restoration:
+
+```python
+# Add a tool call and its output
+template.add_tool_call(
+    name="get_weather",
+    arguments='{"location": "Tokyo"}',
+    call_id="call_123"
+)
+template.add_tool_output(
+    call_id="call_123",
+    output="Sunny, 25C"
+)
+```
+
+This is especially useful for managing long-term memory or restoring chat sessions.
+
+---
+
+## Streaming
+
+LiteRun supports real-time streaming of both text generation and tool execution status usage `agent.stream()`.
+
+The stream yields `RunResultStreaming` objects containing an `event`.
+
+Key Events:
+
+- `response.output_text.delta`: A chunk of text content.
+- `response.output_text.done`: Sent when text generation is complete.
+- `response.function_call_arguments.delta`: A chunk of tool arguments (JSON).
+- `response.function_call_arguments.done`: Sent when the LLM finishes generating arguments for a tool call.
+
+```python
+for result in agent.stream("Hello"):
+    event = result.event
+
+    # Text Streaming
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="")
+
+    # Tool Argument Streaming
+    elif event.type == "response.function_call_arguments.delta":
+        print(event.delta, end="")
+
+    # Completion Events
+    elif event.type == "response.output_text.done":
+        print("\nText generation complete")
+    elif event.type == "response.function_call_arguments.done":
+        print(f"\nTool call complete: {event.name}({event.arguments})")
+```
+
+---
+
+## Direct LLM Usage
+
+If you don't need the agent loop (e.g. for a simple chat or classification task without tools), you can use `ChatOpenAI` directly.
+
+```python
+from literun import ChatOpenAI
+
+llm = ChatOpenAI(model="gpt-4o")
+response = llm.invoke([{"role": "user", "content": "Hi"}])
+print(response.output_text)
+```
+
+You can also bind tools manually if you want to handle execution yourself:
+
+```python
+llm.bind_tools([my_tool])
+response = llm.invoke(...)
+# Check response.output for tool calls
+```
+
+### Streaming with ChatOpenAI
+
+```python
+stream = llm.stream([{"role": "user", "content": "Tell me a joke."}])
+for event in stream:
+    if event.type == "response.output_text.delta":
+        print(event.delta, end="")
+```
+
+---
+
+## Examples
+
+For complete, runnable code examples covering these concepts, please visit the [**examples**](https://github.com/kaustubh-tr/literun/blob/main/examples/) directory in the repository.

literun-0.1.1/PKG-INFO

@@ -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.