lite-agent 0.2.0__tar.gz → 0.3.0__tar.gz

{lite_agent-0.2.0 → lite_agent-0.3.0}/CHANGELOG.md

@@ -1,3 +1,44 @@
+## v0.3.0
+
+[v0.2.0...v0.3.0](https://github.com/Jannchie/lite-agent/compare/v0.2.0...v0.3.0)
+
+### :rocket: Breaking Changes
+
+- **rich-helpers**: rename render_chat_history to print_chat_history and update imports - By [Jannchie](mailto:jannchie@gmail.com) in [3db6721](https://github.com/Jannchie/lite-agent/commit/3db6721)
+
+### :sparkles: Features
+
+- **agent**: use jinja2 templates for instruction messages - By [Jannchie](mailto:jannchie@gmail.com) in [f5ccbd5](https://github.com/Jannchie/lite-agent/commit/f5ccbd5)
+- **agent**: add completion_condition and task_done tool support - By [Jannchie](mailto:jannchie@gmail.com) in [28126b1](https://github.com/Jannchie/lite-agent/commit/28126b1)
+- **response-api**: add response api format for text and image input - By [Jannchie](mailto:jannchie@gmail.com) in [4b44f91](https://github.com/Jannchie/lite-agent/commit/4b44f91)
+- **rich-helpers**: add rich chat history renderer and chat summary utils - By [Jannchie](mailto:jannchie@gmail.com) in [5a570ce](https://github.com/Jannchie/lite-agent/commit/5a570ce)
+- **runner**: add set_chat_history to support full chat history replay and agent tracking - By [Jannchie](mailto:jannchie@gmail.com) in [fd2ecdc](https://github.com/Jannchie/lite-agent/commit/fd2ecdc)
+- **types**: enhance runner type system for flexible user_input - By [Jannchie](mailto:jannchie@gmail.com) in [3a2e9c5](https://github.com/Jannchie/lite-agent/commit/3a2e9c5)
+
+### :adhesive_bandage: Fixes
+
+- **examples**: check content key before modifying messages - By [Jannchie](mailto:jannchie@gmail.com) in [94b85a6](https://github.com/Jannchie/lite-agent/commit/94b85a6)
+
+### :art: Refactors
+
+- **agent**: abstract llm client and refactor model usage - By [Jannchie](mailto:jannchie@gmail.com) in [09c52c8](https://github.com/Jannchie/lite-agent/commit/09c52c8)
+- **client**: move llm client classes to separate module - By [Jannchie](mailto:jannchie@gmail.com) in [a70d163](https://github.com/Jannchie/lite-agent/commit/a70d163)
+- **rich-helpers-test**: rename render_chat_history to print_chat_history - By [Jannchie](mailto:jannchie@gmail.com) in [bf1ca8f](https://github.com/Jannchie/lite-agent/commit/bf1ca8f)
+
+### :lipstick: Styles
+
+- **agent**: inline error message formatting - By [Jannchie](mailto:jannchie@gmail.com) in [1453cc5](https://github.com/Jannchie/lite-agent/commit/1453cc5)
+- **tests**: add type ignore hints to assertions - By [Jannchie](mailto:jannchie@gmail.com) in [8d2a19d](https://github.com/Jannchie/lite-agent/commit/8d2a19d)
+
+### :memo: Documentation
+
+- **set-chat-history**: remove set_chat_history feature documentation - By [Jannchie](mailto:jannchie@gmail.com) in [2413351](https://github.com/Jannchie/lite-agent/commit/2413351)
+
+### :wrench: Chores
+
+- **examples**: rename test_consolidate_history to consolidate_history - By [Jannchie](mailto:jannchie@gmail.com) in [0f5b39a](https://github.com/Jannchie/lite-agent/commit/0f5b39a)
+- **tests**: remove legacy chat bubble and alignment tests - By [Jannchie](mailto:jannchie@gmail.com) in [46b23bc](https://github.com/Jannchie/lite-agent/commit/46b23bc)
+
 ## v0.2.0
 
 [v0.1.0...v0.2.0](https://github.com/Jannchie/lite-agent/compare/v0.1.0...v0.2.0)

{lite_agent-0.2.0 → lite_agent-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lite-agent
-Version: 0.2.0
+Version: 0.3.0
 Summary: A lightweight, extensible framework for building AI agent.
 Author-email: Jianqi Pan <jannchie@gmail.com>
 License: MIT

{lite_agent-0.2.0 → lite_agent-0.3.0}/examples/basic.py

@@ -42,5 +42,6 @@ async def main():
         logger.info(chunk)
     print(runner.messages)
 
+
 if __name__ == "__main__":
     asyncio.run(main())

{lite_agent-0.2.0 → lite_agent-0.3.0}/examples/handoffs.py

@@ -62,11 +62,15 @@ async def main():
     parent.add_handoff(whether_agent)
     parent.add_handoff(temper_agent)
 
-    print(temper_agent.fc.function_registry)
     runner = Runner(parent)
-    resp = runner.run("Hello, I need to check the whether and temperature of Tokyo.", includes=["final_message", "tool_call", "tool_call_result"])
+    resp = runner.run(
+        "Hello, I need to check the whether and temperature of Tokyo.",
+        includes=["final_message", "tool_call", "tool_call_result"],
+        record_to="tests/mocks/handoffs/1.jsonl",
+    )
     async for message in resp:
         logger.info(message)
+    print(f"{runner.get_messages_dict()}")
     logger.info(runner.agent.name)
 
 

lite_agent-0.3.0/examples/image.py

@@ -0,0 +1,59 @@
+import asyncio
+import logging
+
+from rich.logging import RichHandler
+
+from lite_agent.agent import Agent
+from lite_agent.runner import Runner
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+
+logger = logging.getLogger("lite_agent")
+logger.setLevel(logging.DEBUG)
+
+
+agent = Agent(
+    model="gpt-4.1-nano",
+    name="Photo Judge Agent",
+    instructions=(
+        "You are a helpful photo judge agent. You will receive a photo and you need to judge "
+        "whether it is a good photo or not. You should rate the photo on a scale of 1 to 10, "
+        "where 1 is the worst and 10 is the best. If you think the photo is not good, you "
+        "should provide a reason why it is not good."
+    ),
+)
+
+
+async def main():
+    runner = Runner(agent)
+
+    resp = runner.run(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_text",
+                        "text": "What do you think about this photo?",
+                    },
+                    {
+                        "type": "input_image",
+                        "detail": "low",
+                        "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c2/Lavant_St._Peter_und_Paul_Hochaltar_01.jpg/1024px-Lavant_St._Peter_und_Paul_Hochaltar_01.jpg",
+                    },
+                ],
+            },
+        ],
+        includes=["final_message", "usage"],
+    )
+    async for chunk in resp:
+        logger.info(chunk)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lite_agent-0.2.0 → lite_agent-0.3.0}/examples/message_transfer_example.py

@@ -35,7 +35,8 @@ def example_message_transfer(messages: RunnerMessages) -> RunnerMessages:
                 # Add prefix to user messages
                 content = message.get("content", "")
                 processed_message = message.copy()
-                processed_message["content"] = f"[PROCESSED] {content}"
+                if "content" in processed_message:
+                    processed_message["content"] = f"[PROCESSED] {content}"
                 processed_messages.append(processed_message)
             else:
                 processed_messages.append(message)
@@ -76,10 +77,9 @@ def privacy_filter_transfer(messages: RunnerMessages) -> RunnerMessages:
 
     for message in messages:
         if isinstance(message, dict):
-            content = message.get("content", "")
-            if isinstance(content, str):
+            if "content" in message and isinstance(message["content"], str):
                 processed_message = message.copy()
-                processed_message["content"] = filter_content(content)
+                processed_message["content"] = filter_content(message["content"])
                 processed_messages.append(processed_message)
             else:
                 processed_messages.append(message)
@@ -164,7 +164,10 @@ async def main():
     consolidated = consolidate_history_transfer(complex_messages)
     print("Consolidated result:")
     if consolidated and isinstance(consolidated[0], dict):
-        print(consolidated[0]["content"])
+        if "content" in consolidated[0]:
+            print(consolidated[0]["content"])
+        else:
+            print(consolidated[0])
 
 
 if __name__ == "__main__":

lite_agent-0.3.0/examples/response_api_example.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating the new Response API format for mixed text and image content.
+
+This example shows how to use the new ResponseInputText and ResponseInputImage
+classes for internal message representation, which are automatically converted
+to the legacy Completion API format when making actual LLM calls.
+"""
+
+import asyncio
+
+from lite_agent import Agent, Runner
+from lite_agent.types import ResponseInputImage, ResponseInputText
+
+
+async def main():
+    """Demonstrate using Response API format for mixed content messages."""
+
+    # Create an agent
+    agent = Agent(
+        model="gpt-4-turbo",
+        name="ImageAnalysisAgent",
+        instructions="You are a helpful assistant that can analyze images and answer questions about them.",
+    )
+
+    # Create a runner instance
+    runner = Runner(agent)
+
+    # Example 1: Traditional text-only message (still works)
+    print("=== Example 1: Text-only message ===")
+    runner.append_message(
+        {
+            "role": "user",
+            "content": "Hello! Can you help me analyze some images?",
+        },
+    )
+
+    # Example 2: Using new Response API format with mixed content
+    print("\n=== Example 2: Mixed content using Response API format ===")
+
+    # Create message content using new Response API format
+    mixed_content = [
+        ResponseInputText(
+            type="input_text",
+            text="What do you think about this photo?",
+        ),
+        ResponseInputImage(
+            type="input_image",
+            detail="high",
+            image_url="https://upload.wikimedia.org/wikipedia/commons/thumb/c/c2/Lavant_St._Peter_und_Paul_Hochaltar_01.jpg/1024px-Lavant_St._Peter_und_Paul_Hochaltar_01.jpg",
+        ),
+    ]
+
+    # Add the message with mixed content
+    runner.append_message(
+        {
+            "role": "user",
+            "content": mixed_content,
+        },
+    )
+
+    # Example 3: Demonstrating file_id limitation
+    print("\n=== Example 3: file_id limitation ===")
+    print("Note: file_id is not supported for Completion API and will raise an error")
+
+    try:
+        file_content = [
+            ResponseInputText(
+                type="input_text",
+                text="Can you describe this image file?",
+            ),
+            ResponseInputImage(
+                type="input_image",
+                detail="auto",
+                file_id="file-12345",  # This will cause an error
+            ),
+        ]
+
+        runner.append_message(
+            {
+                "role": "user",
+                "content": file_content,
+            },
+        )
+
+        # This will raise an error when trying to convert
+        converted_messages = agent._convert_responses_to_completions_format(runner.messages)  # noqa: SLF001
+        print("❌ This should not be reached!")
+
+    except ValueError as e:
+        print(f"✅ Expected error caught: {e}")
+        # Clear the message that caused the error
+        runner.messages.pop()
+
+    # Print the internal message representation
+    print("\n=== Internal message representation ===")
+    for i, message in enumerate(runner.messages):
+        print(f"Message {i + 1}:")
+        if hasattr(message, "model_dump"):
+            print(f"  {message.model_dump()}")
+        else:
+            print(f"  {message}")
+        print()
+
+    # Show how messages are converted for LLM API calls
+    print("\n=== Converted messages for LLM API ===")
+    # Note: In a real application, this conversion happens automatically
+    # We're accessing the private method here just for demonstration
+    converted_messages = agent._convert_responses_to_completions_format(runner.messages)  # noqa: SLF001
+    for i, message in enumerate(converted_messages):
+        print(f"Converted Message {i + 1}:")
+        print(f"  {message}")
+        print()
+
+    print("\n=== Summary ===")
+    print("The new Response API format allows you to:")
+    print("1. Use ResponseInputText for text content")
+    print("2. Use ResponseInputImage for image content with image_url")
+    print("3. Mix text and images in a single message")
+    print("4. Automatic conversion to legacy Completion API format for LLM calls")
+    print("\n⚠️  Important limitations:")
+    print("- file_id is NOT supported for Completion API - use image_url instead")
+    print("- ResponseInputImage must have either file_id or image_url")
+    print("\nThis provides better type safety and clearer separation between")
+    print("internal representation and external API compatibility.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.3.0/examples/rich_helpers_demo.py

@@ -0,0 +1,130 @@
+"""
+示例：使用 rich_helpers 美观渲染聊天记录
+
+这个示例展示了如何使用 rich_helpers 模块中的函数来美观地渲染聊天记录。
+"""
+
+import asyncio
+
+from lite_agent.agent import Agent
+from lite_agent.rich_helpers import print_chat_history, print_chat_summary
+from lite_agent.runner import Runner
+
+
+def demo_tools():
+    """演示工具函数，用于测试函数调用显示。"""
+
+    def get_weather(city: str) -> str:
+        """获取指定城市的天气信息。"""
+        return f"The weather in {city} is sunny with 25°C"
+
+    def calculate(expression: str) -> str:
+        """计算数学表达式。"""
+        try:
+            result = eval(expression)  # noqa: S307
+        except Exception as e:
+            return f"Error calculating {expression}: {e}"
+        else:
+            return f"{expression} = {result}"
+
+    return [get_weather, calculate]
+
+
+async def create_sample_chat_history() -> Runner:
+    """创建一个包含各种消息类型的示例聊天历史。"""
+    # 创建 agent
+    agent = Agent(
+        model="gpt-4o-mini",
+        name="DemoAgent",
+        instructions="You are a helpful assistant that can provide weather information and perform calculations.",
+        tools=demo_tools(),
+    )
+
+    # 创建 runner
+    runner = Runner(agent=agent)
+
+    # 手动添加一些示例消息来展示不同的消息类型
+    runner.append_message({"role": "system", "content": "You are a helpful assistant."})
+    runner.append_message({"role": "user", "content": "Hello! Can you help me with some tasks?"})
+    runner.append_message({"role": "assistant", "content": "Of course! I'd be happy to help you. What would you like to do?"})
+    runner.append_message({"role": "user", "content": "What's the weather like in Tokyo?"})
+
+    # 添加函数调用消息
+    runner.append_message(
+        {
+            "type": "function_call",
+            "function_call_id": "call_123",
+            "name": "get_weather",
+            "arguments": '{"city": "Tokyo"}',
+            "content": "",
+        },
+    )
+
+    # 添加函数调用输出
+    runner.append_message(
+        {
+            "type": "function_call_output",
+            "call_id": "call_123",
+            "output": "The weather in Tokyo is sunny with 25°C",
+        },
+    )
+
+    runner.append_message({"role": "assistant", "content": "The weather in Tokyo is sunny with a temperature of 25°C. Is there anything else you'd like to know?"})
+    runner.append_message({"role": "user", "content": "Can you calculate 25 * 4 + 10?"})
+
+    # 添加另一个函数调用
+    runner.append_message(
+        {
+            "type": "function_call",
+            "function_call_id": "call_456",
+            "name": "calculate",
+            "arguments": '{"expression": "25 * 4 + 10"}',
+            "content": "",
+        },
+    )
+
+    runner.append_message(
+        {
+            "type": "function_call_output",
+            "call_id": "call_456",
+            "output": "25 * 4 + 10 = 110",
+        },
+    )
+
+    runner.append_message({"role": "assistant", "content": "The calculation 25 * 4 + 10 equals 110."})
+
+    return runner
+
+
+async def main():
+    """主函数：演示 rich_helpers 的使用。"""
+    print("🎨 Rich Chat History Renderer Demo\n")
+
+    # 创建示例聊天历史
+    runner = await create_sample_chat_history()
+
+    # 1. 展示聊天摘要
+    print("📊 Chat Summary:")
+    print_chat_summary(runner.messages)
+    print()
+
+    # 2. 渲染完整的聊天历史
+    print("💬 Full Chat History:")
+    print_chat_history(runner.messages)
+
+    # 3. 展示不同的渲染选项
+    print("\n" + "=" * 60)
+    print("🎛️  Different Rendering Options:")
+    print("=" * 60)
+
+    # 不显示时间戳和索引
+    print("\n📝 Without timestamps and indices:")
+    print_chat_history(
+        runner.messages,
+        show_timestamps=False,
+        show_indices=False,
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.3.0/examples/set_chat_history_example.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Example demonstrating the set_chat_history functionality.
+
+This example shows how to set a complete chat history and automatically track
+which agent should be active based on function calls in the history.
+"""
+
+import asyncio
+import logging
+
+from rich.logging import RichHandler
+
+from lite_agent import consolidate_history_transfer
+from lite_agent.agent import Agent
+from lite_agent.loggers import logger
+from lite_agent.runner import Runner
+
+logging.basicConfig(
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+logger.setLevel(logging.DEBUG)
+
+
+def get_temperature(city: str) -> str:
+    """Get the temperature of a city."""
+    return f"The temperature in {city} is 25°C."
+
+
+def get_weather(city: str) -> str:
+    """Get the weather of a city."""
+    return f"The weather in {city} is sunny."
+
+
+async def main():
+    """Demonstrate set_chat_history functionality."""
+    # Create agents
+    parent = Agent(
+        model="gpt-4.1",
+        name="ParentAgent",
+        instructions="You are a helpful agent.",
+    )
+
+    weather_agent = Agent(
+        model="gpt-4.1",
+        name="WeatherAgent",
+        instructions="You are a helpful agent to check weather.",
+        tools=[get_weather],
+        message_transfer=consolidate_history_transfer,
+    )
+
+    temperature_agent = Agent(
+        model="gpt-4.1",
+        name="TemperatureAgent",
+        instructions="You are a helpful agent to check temperature.",
+        tools=[get_temperature],
+        message_transfer=consolidate_history_transfer,
+    )
+
+    parent.add_handoff(weather_agent)
+    parent.add_handoff(temperature_agent)
+
+    # Create runner
+    runner = Runner(parent)
+
+    # Example chat history that includes agent transfers
+    chat_history = [
+        {"role": "user", "content": "Hello, I need to check the whether and temperature of Tokyo."},
+        {"role": "assistant", "content": ""},
+        {"arguments": '{"name":"WhetherAgent"}', "type": "function_call", "function_call_id": "call_HRTCM7KqkMkwhFWs2THxeub1", "name": "transfer_to_agent", "content": ""},
+        {"call_id": "call_HRTCM7KqkMkwhFWs2THxeub1", "output": "Transferring to agent: WhetherAgent", "type": "function_call_output"},
+        {"role": "assistant", "content": ""},
+        {"arguments": '{"city":"Tokyo"}', "type": "function_call", "function_call_id": "call_W02qQluI5XeM6Pk7je8xEwVs", "name": "get_weather", "content": ""},
+        {"call_id": "call_W02qQluI5XeM6Pk7je8xEwVs", "output": "The weather in Tokyo is sunny.", "type": "function_call_output"},
+        {"role": "assistant", "content": ""},
+        {"arguments": "{}", "type": "function_call", "function_call_id": "call_wnnlXwlusLSLygIppk4l5TkD", "name": "transfer_to_parent", "content": ""},
+        {"call_id": "call_wnnlXwlusLSLygIppk4l5TkD", "output": "Transferring back to parent agent: ParentAgent", "type": "function_call_output"},
+        {"role": "assistant", "content": ""},
+        {"arguments": '{"name":"TemperatureAgent"}', "type": "function_call", "function_call_id": "call_S9OlXSk7kEPQJ3HWC3GoK0xE", "name": "transfer_to_agent", "content": ""},
+        {"call_id": "call_S9OlXSk7kEPQJ3HWC3GoK0xE", "output": "Transferring to agent: TemperatureAgent", "type": "function_call_output"},
+        {"role": "assistant", "content": ""},
+        {"arguments": '{"city":"Tokyo"}', "type": "function_call", "function_call_id": "call_gDljMYP187ymVXfKCUdsgjlX", "name": "get_temperature", "content": ""},
+        {"call_id": "call_gDljMYP187ymVXfKCUdsgjlX", "output": "The temperature in Tokyo is 25°C.", "type": "function_call_output"},
+        {"role": "assistant", "content": ""},
+        {"arguments": "{}", "type": "function_call", "function_call_id": "call_bQiSAr8y7u6Q0rJMqUfVE47p", "name": "transfer_to_parent", "content": ""},
+        {"call_id": "call_bQiSAr8y7u6Q0rJMqUfVE47p", "output": "Transferring back to parent agent: ParentAgent", "type": "function_call_output"},
+        {"role": "assistant", "content": "The weather in Tokyo is sunny, and the temperature is 25°C. If you need further details about Tokyo or want updates for another city, let me know!"},
+    ]
+    # Set the chat history - this should automatically track that we should be on TemperatureAgent
+    runner.set_chat_history(chat_history)
+
+    print(f"After setting chat history, current agent is: {runner.agent.name}")
+    print(f"Chat history contains {len(runner.messages)} messages")
+
+    # Continue the conversation from where we left off
+    print("\n--- Continuing conversation ---")
+    resp = runner.run([], max_steps=5, includes=["final_message", "tool_call", "tool_call_result"])
+    async for message in resp:
+        logger.info(message)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.3.0/examples/simple_rich_example.py

@@ -0,0 +1,44 @@
+"""
+简单使用示例：Rich 聊天记录渲染
+"""
+
+from lite_agent import print_chat_history, print_chat_summary
+from lite_agent.types import AgentAssistantMessage, AgentUserMessage
+
+# 创建一些示例消息
+messages = [
+    AgentUserMessage(role="user", content="你好!"),
+    AgentAssistantMessage(role="assistant", content="你好!我是 AI 助手,很高兴为您服务。"),
+    {"role": "user", "content": "今天天气怎么样?"},
+    {
+        "type": "function_call",
+        "function_call_id": "call_1",
+        "name": "get_weather",
+        "arguments": '{"city": "北京"}',
+        "content": "",
+    },
+    {
+        "type": "function_call_output",
+        "call_id": "call_1",
+        "output": "北京今天晴朗,温度 20°C",
+    },
+    {"role": "assistant", "content": "北京今天天气很好,晴朗,温度 20°C。"},
+]
+
+# 显示聊天摘要
+print("📊 聊天摘要:")
+print_chat_summary(messages)
+
+print("\n" + "=" * 60)
+print("💬 详细聊天记录:")
+print("=" * 60)
+
+# 渲染完整聊天记录
+print_chat_history(messages)
+
+print("\n🎛️ 其他渲染选项:")
+print_chat_history(
+    messages,
+    show_timestamps=False,
+    show_indices=False,
+)

lite_agent-0.3.0/examples/stop_with_tool_call.py

@@ -0,0 +1,49 @@
+import asyncio
+import logging
+
+from rich.logging import RichHandler
+
+from lite_agent import print_chat_history
+from lite_agent.agent import Agent
+from lite_agent.runner import Runner
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(rich_tracebacks=True)],
+)
+
+logger = logging.getLogger("lite_agent")
+logger.setLevel(logging.DEBUG)
+
+
+async def get_temperature(city: str) -> str:
+    """Get the temperature for a city."""
+    return f"The temperature in {city} is 25°C."
+
+
+agent = Agent(
+    model="gpt-4.1",
+    name="Weather Assistant",
+    instructions="You are a helpful weather assistant. Before using tools, briefly explain what you are going to do. Provide friendly and informative responses.",
+    tools=[get_temperature],
+    completion_condition="call",  # Set completion condition to "call"
+)
+
+
+async def main():
+    runner = Runner(agent)
+    resp = runner.run(
+        "What is the temperature and whether in New York?",
+        includes=["final_message", "usage", "tool_call", "tool_call_result"],
+    )
+    async for chunk in resp:
+        logger.info(chunk)
+    print_chat_history(
+        runner.messages,
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())