lite-agent 0.10.0__tar.gz → 0.12.0__tar.gz

{lite_agent-0.10.0 → lite_agent-0.12.0}/.claude/settings.local.json

@@ -19,7 +19,10 @@
       "Bash(mkdir:*)",
       "Bash(sed:*)",
       "Bash(mv:*)",
-      "Bash(find:*)"
+      "Bash(find:*)",
+      "WebSearch",
+      "Bash(uv list:*)",
+      "Bash(pip show:*)"
     ],
     "deny": []
   }

{lite_agent-0.10.0 → lite_agent-0.12.0}/CHANGELOG.md

@@ -1,3 +1,24 @@
+## v0.12.0
+
+[v0.11.0...v0.12.0](https://github.com/Jannchie/lite-agent/compare/v0.11.0...v0.12.0)
+
+### :sparkles: Features
+
+- **context**: add history context injection for tools - By [Jannchie](mailto:jannchie@gmail.com) in [7649170](https://github.com/Jannchie/lite-agent/commit/7649170)
+- **termination**: add custom termination tools support - By [Jannchie](mailto:jannchie@gmail.com) in [5e65e38](https://github.com/Jannchie/lite-agent/commit/5e65e38)
+
+## v0.11.0
+
+[v0.10.0...v0.11.0](https://github.com/Jannchie/lite-agent/compare/v0.10.0...v0.11.0)
+
+### :sparkles: Features
+
+- **client**: add typed dicts for reasoning config and refactor parsing logic - By [Jannchie](mailto:jannchie@gmail.com) in [8d125b4](https://github.com/Jannchie/lite-agent/commit/8d125b4)
+
+### :adhesive_bandage: Fixes
+
+- **message-builder**: ensure correct meta types and safer field access - By [Jannchie](mailto:jannchie@gmail.com) in [6c29c43](https://github.com/Jannchie/lite-agent/commit/6c29c43)
+
 ## v0.10.0
 
 [v0.9.0...v0.10.0](https://github.com/Jannchie/lite-agent/compare/v0.9.0...v0.10.0)

{lite_agent-0.10.0 → lite_agent-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lite-agent
-Version: 0.10.0
+Version: 0.12.0
 Summary: A lightweight, extensible framework for building AI agent.
 Author-email: Jianqi Pan <jannchie@gmail.com>
 License: MIT
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Communications :: Chat
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules

{lite_agent-0.10.0 → lite_agent-0.12.0}/examples/basic.py

@@ -33,7 +33,7 @@ agent = Agent(
 
 
 async def main():
-    runner = Runner(agent, streaming=True, api="completion")
+    runner = Runner(agent)
     await runner.run_until_complete(
         "What is the temperature in New York?",
         includes=["usage", "assistant_message", "function_call", "function_call_output", "timing"],

{lite_agent-0.10.0 → lite_agent-0.12.0}/examples/context.py

@@ -6,6 +6,7 @@ from pydantic import BaseModel
 from rich.logging import RichHandler
 
 from lite_agent.agent import Agent
+from lite_agent.context import HistoryContext
 from lite_agent.runner import Runner
 
 
@@ -27,13 +28,21 @@ logger = logging.getLogger("lite_agent")
 logger.setLevel(logging.DEBUG)
 
 
-async def get_current_city_temperature(context: Context[WeatherContext]) -> str:
+async def get_current_city_temperature(context: Context[HistoryContext[WeatherContext]]) -> str:
     """Get the temperature for the current city specified in the context."""
     await asyncio.sleep(1)
-    if not context.value:
+
+    # Access user data
+    if not context.value.data:
         msg = "City must be specified in the context."
         raise ValueError(msg)
-    return f"The temperature in {context.value.city} is 25°C."
+    city = context.value.data.city
+
+    # Access conversation history
+    messages = context.value.history_messages
+    previous_questions = sum(1 for msg in messages if hasattr(msg, "role") and getattr(msg, "role", None) == "user")
+
+    return f"The temperature in {city} is 25°C. (This is your {previous_questions + 1} question today.)"
 
 
 agent = Agent(

lite_agent-0.12.0/examples/custom_termination.py

@@ -0,0 +1,119 @@
+import asyncio
+import logging
+
+from rich.logging import RichHandler
+
+from lite_agent.agent import Agent
+from lite_agent.chat_display import display_messages
+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_weather(city: str) -> str:
+    """Get the weather for a city."""
+    return f"The weather in {city} is sunny, 25°C."
+
+
+async def mark_task_complete(task: str) -> str:
+    """Mark a task as complete. This will terminate the agent."""
+    return f"Task '{task}' has been marked as complete!"
+
+
+async def save_report(content: str) -> str:
+    """Save a report to file. This will also terminate the agent."""
+    return f"Report saved: {content[:50]}..."
+
+
+# Example 1: Single custom termination tool
+agent1 = Agent(
+    model="gpt-4.1",
+    name="Task Assistant",
+    instructions="You are a task assistant. Use the weather tool if needed, then mark the task complete when done.",
+    tools=[get_weather, mark_task_complete],
+    completion_condition="call",
+    termination_tools=[mark_task_complete],  # Only this tool will terminate
+)
+
+# Example 2: Multiple termination tools
+agent2 = Agent(
+    model="gpt-4.1",
+    name="Report Assistant",
+    instructions="You are a report assistant. Get weather data and either save a report or mark the task complete.",
+    tools=[get_weather, mark_task_complete, save_report],
+    completion_condition="call",
+    termination_tools=[mark_task_complete, save_report],  # Either tool will terminate
+)
+
+# Example 3: Using string names for termination tools
+agent3 = Agent(
+    model="gpt-4.1",
+    name="String-based Assistant",
+    instructions="You are an assistant. Get weather data and mark task complete when done.",
+    tools=[get_weather, mark_task_complete],
+    completion_condition="call",
+    termination_tools=["mark_task_complete"],  # Using string name
+)
+
+
+async def test_single_termination():
+    print("\n=== Testing Single Custom Termination Tool ===")
+    runner = Runner(agent1)
+    resp = runner.run(
+        "Check the weather in Tokyo and mark the task as complete",
+        includes=["assistant_message", "function_call", "function_call_output"],
+    )
+    async for chunk in resp:
+        if chunk.type == "assistant_message":
+            print(f"Assistant: {chunk.message.content}")
+
+    print("\nFinal messages:")
+    display_messages(runner.messages)
+
+
+async def test_multiple_termination():
+    print("\n=== Testing Multiple Termination Tools ===")
+    runner = Runner(agent2)
+    resp = runner.run(
+        "Check weather in London and save a weather report",
+        includes=["assistant_message", "function_call", "function_call_output"],
+    )
+    async for chunk in resp:
+        if chunk.type == "assistant_message":
+            print(f"Assistant: {chunk.message.content}")
+
+    print("\nFinal messages:")
+    display_messages(runner.messages)
+
+
+async def test_string_termination():
+    print("\n=== Testing String-based Termination ===")
+    runner = Runner(agent3)
+    resp = runner.run(
+        "What's the weather like in Paris? Mark complete when done.",
+        includes=["assistant_message", "function_call", "function_call_output"],
+    )
+    async for chunk in resp:
+        if chunk.type == "assistant_message":
+            print(f"Assistant: {chunk.message.content}")
+
+    print("\nFinal messages:")
+    display_messages(runner.messages)
+
+
+async def main():
+    await test_single_termination()
+    await test_multiple_termination()
+    await test_string_termination()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.12.0/examples/history_context_demo.py

@@ -0,0 +1,198 @@
+"""Demo showing how to access history messages in tool functions."""
+
+import asyncio
+import logging
+
+from funcall import Context
+from pydantic import BaseModel
+from rich.logging import RichHandler
+
+from lite_agent.agent import Agent
+from lite_agent.context import HistoryContext
+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)
+
+
+# User-defined context data
+class UserContext(BaseModel):
+    user_id: str
+    city: str
+
+
+# Tool that only needs history messages
+async def count_messages(ctx: Context[HistoryContext[None]]) -> str:
+    """Count the number of messages in the conversation history."""
+    messages = ctx.value.history_messages
+    return f"The conversation has {len(messages)} messages in total."
+
+
+# Tool that needs both history and user data
+async def analyze_conversation(ctx: Context[HistoryContext[UserContext]]) -> str:
+    """Analyze conversation history with user context."""
+    messages = ctx.value.history_messages
+    user_data = ctx.value.data
+
+    if user_data is None:
+        return f"Found {len(messages)} messages, but no user data available."
+
+    user_id = user_data.user_id
+    city = user_data.city
+
+    # Analyze message content
+    user_message_count = sum(1 for msg in messages if hasattr(msg, "role") and getattr(msg, "role", None) == "user")
+
+    return f"Analysis for user {user_id} from {city}:\n- Total messages: {len(messages)}\n- User messages: {user_message_count}\n- Assistant messages: {len(messages) - user_message_count}"
+
+
+# Tool that provides conversation summary
+async def summarize_recent(ctx: Context[HistoryContext]) -> str:
+    """Summarize the most recent messages."""
+    messages = ctx.value.history_messages
+
+    if len(messages) == 0:
+        return "No conversation history available."
+
+    # Get the last few messages
+    recent_messages = messages[-3:]
+    summary = f"Recent activity ({len(recent_messages)} messages):\n"
+
+    for i, msg in enumerate(recent_messages, 1):
+        # Handle different message types
+        if hasattr(msg, "content"):
+            content = getattr(msg, "content", "")
+            if isinstance(content, list) and content:
+                # Extract text from content list
+                text_parts = []
+                for item in content:
+                    if hasattr(item, "text"):
+                        text_parts.append(item.text)
+                    elif isinstance(item, str):
+                        text_parts.append(item)
+                content_text = " ".join(text_parts)[:50] + "..."
+            elif isinstance(content, str):
+                content_text = content[:50] + "..."
+            else:
+                content_text = str(content)[:50] + "..."
+        else:
+            content_text = "No content"
+
+        role = getattr(msg, "role", "unknown")
+        summary += f"{i}. {role}: {content_text}\n"
+
+    return summary
+
+
+agent = Agent(
+    model="gpt-4o-mini",
+    name="History Assistant",
+    instructions="You are an assistant that can analyze conversation history. Use the provided tools to help users understand their conversation patterns.",
+    tools=[count_messages, analyze_conversation, summarize_recent],
+)
+
+
+async def demo_without_user_context():
+    """Demo using tools without providing user context."""
+    print("\n=== Demo 1: No user context (history only) ===")
+
+    runner = Runner(agent)
+
+    # Add some initial conversation
+    runner.add_user_message("Hello, how are you?")
+    runner.add_assistant_message("I'm doing well, thank you! How can I help you today?")
+    runner.add_user_message("Can you count our messages?")
+
+    resp = runner.run(
+        "Please count how many messages we have exchanged so far.",
+        includes=["function_call_output"],
+    )
+
+    async for chunk in resp:
+        if chunk.type == "function_call_output":
+            print(f"Tool result: {chunk.content}")
+
+
+async def demo_with_user_context():
+    """Demo using tools with user context data."""
+    print("\n=== Demo 2: With user context ===")
+
+    runner = Runner(agent)
+
+    # Add some conversation history
+    runner.add_user_message("Hi there!")
+    runner.add_assistant_message("Hello! Nice to meet you.")
+    runner.add_user_message("I'm from Beijing.")
+    runner.add_assistant_message("That's great! Beijing is a wonderful city.")
+    runner.add_user_message("Can you analyze our conversation?")
+
+    # Provide user context
+    user_ctx = UserContext(user_id="alice_123", city="Beijing")
+
+    resp = runner.run(
+        "Please analyze our conversation with my user information.",
+        context=Context(user_ctx),
+        includes=["function_call_output"],
+    )
+
+    async for chunk in resp:
+        if chunk.type == "function_call_output":
+            print(f"Tool result: {chunk.content}")
+
+
+async def demo_conversation_summary():
+    """Demo conversation summarization."""
+    print("\n=== Demo 3: Conversation summary ===")
+
+    runner = Runner(agent)
+
+    # Build up a longer conversation
+    conversation = [
+        ("user", "Hello, I need help with Python."),
+        ("assistant", "I'd be happy to help with Python! What specifically do you need help with?"),
+        ("user", "I'm trying to understand async/await."),
+        ("assistant", "Async/await is used for asynchronous programming in Python. It allows you to write concurrent code."),
+        ("user", "Can you give me an example?"),
+        ("assistant", "Sure! Here's a simple example: async def my_function(): await some_task()"),
+        ("user", "That's helpful, thanks!"),
+    ]
+
+    for role, content in conversation:
+        if role == "user":
+            runner.add_user_message(content)
+        else:
+            runner.add_assistant_message(content)
+
+    resp = runner.run(
+        "Can you summarize our recent conversation?",
+        includes=["function_call_output"],
+    )
+
+    async for chunk in resp:
+        if chunk.type == "function_call_output":
+            print(f"Tool result:\n{chunk.content}")
+
+
+async def main():
+    """Run all demos."""
+    await demo_without_user_context()
+    await demo_with_user_context()
+    await demo_conversation_summary()
+
+    print("\n=== Demos completed! ===")
+    print("Key takeaways:")
+    print("1. Tools automatically receive history_messages in context")
+    print("2. Use Context[HistoryContext[None]] for history-only tools")
+    print("3. Use Context[HistoryContext[YourDataType]] for tools that need both")
+    print("4. Full type safety and IDE completion support")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lite_agent-0.10.0 → lite_agent-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lite-agent"
-version = "0.10.0"
+version = "0.12.0"
 description = "A lightweight, extensible framework for building AI agent."
 readme = "README.md"
 authors = [{ name = "Jianqi Pan", email = "jannchie@gmail.com" }]
@@ -29,6 +29,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Intended Audience :: Developers",
@@ -90,10 +91,7 @@ ignore = [
     "ARG002",
     "S110",
 ]
-"examples/**/*" = [
-    "SLF001",
-    "S110",
-]
+"examples/**/*" = ["SLF001", "S110"]
 
 
 [tool.uv]

{lite_agent-0.10.0 → lite_agent-0.12.0}/src/lite_agent/agent.py

@@ -41,6 +41,7 @@ class Agent:
         message_transfer: Callable[[RunnerMessages], RunnerMessages] | None = None,
         completion_condition: str = "stop",
         stop_before_tools: list[str] | list[Callable] | None = None,
+        termination_tools: list[str] | list[Callable] | None = None,
     ) -> None:
         self.name = name
         self.instructions = instructions
@@ -58,6 +59,20 @@ class Agent:
         else:
             self.stop_before_functions = set()
 
+        # Convert termination_tools to function names
+        if termination_tools:
+            self.termination_tools = set()
+            for func in termination_tools:
+                if isinstance(func, str):
+                    self.termination_tools.add(func)
+                elif callable(func):
+                    self.termination_tools.add(func.__name__)
+                else:
+                    msg = f"termination_tools must contain strings or callables, got {type(func)}"
+                    raise TypeError(msg)
+        else:
+            self.termination_tools = set()
+
         if isinstance(model, BaseLLMClient):
             # If model is a BaseLLMClient instance, use it directly
             self.client = model

{lite_agent-0.10.0 → lite_agent-0.12.0}/src/lite_agent/client.py

@@ -1,6 +1,6 @@
 import abc
 import os
-from typing import Any, Literal
+from typing import Any, Literal, NotRequired, TypedDict
 
 import litellm
 from openai.types.chat import ChatCompletionToolParam
@@ -8,12 +8,28 @@ from openai.types.responses import FunctionToolParam
 from pydantic import BaseModel
 
 ReasoningEffort = Literal["minimal", "low", "medium", "high"]
-ThinkingConfig = dict[str, Any] | None
+
+
+class ThinkingConfigDict(TypedDict):
+    """Thinking configuration for reasoning models like Claude."""
+
+    type: Literal["enabled"]  # 启用推理
+    budget_tokens: NotRequired[int]  # 推理令牌预算，可选
+
+
+class ReasoningEffortDict(TypedDict):
+    """Reasoning effort configuration."""
+
+    effort: ReasoningEffort
+
+
+ThinkingConfig = ThinkingConfigDict | None
 
 # 统一的推理配置类型
 ReasoningConfig = (
-    str
-    | dict[str, Any]  # {"type": "enabled", "budget_tokens": 2048} 或其他配置
+    ReasoningEffort  # "minimal", "low", "medium", "high"
+    | ReasoningEffortDict  # {"effort": "minimal"}
+    | ThinkingConfigDict  # {"type": "enabled", "budget_tokens": 2048}
     | bool  # True/False 简单开关
     | None  # 不启用推理
 )
@@ -36,8 +52,9 @@ def parse_reasoning_config(reasoning: ReasoningConfig) -> tuple[ReasoningEffort
 
     Args:
         reasoning: 统一的推理配置
-            - str: "minimal", "low", "medium", "high" -> reasoning_effort
-            - dict: {"effort": "minimal"} -> reasoning_effort, 其他格式 -> thinking_config
+            - ReasoningEffort: "minimal", "low", "medium", "high" -> reasoning_effort
+            - ReasoningEffortDict: {"effort": "minimal"} -> reasoning_effort
+            - ThinkingConfigDict: {"type": "enabled", "budget_tokens": 2048} -> thinking_config
             - bool: True -> "medium", False -> None
             - None: 不启用推理
 
@@ -47,28 +64,38 @@ def parse_reasoning_config(reasoning: ReasoningConfig) -> tuple[ReasoningEffort
     if reasoning is None:
         return None, None
 
-    if isinstance(reasoning, str):
-        # 字符串类型，使用 reasoning_effort
-        # 确保字符串是有效的 ReasoningEffort 值
-        if reasoning in ("minimal", "low", "medium", "high"):
-            return reasoning, None  # type: ignore[return-value]
-    elif isinstance(reasoning, dict):
-        # 检查是否为 {"effort": "value"} 格式
-        if "effort" in reasoning and len(reasoning) == 1:
-            effort = reasoning["effort"]
-            if isinstance(effort, str) and effort in ("minimal", "low", "medium", "high"):
-                return effort, None  # type: ignore[return-value]
-        else:
-            # 其他字典格式，作为 thinking_config
-            return None, reasoning
-    elif isinstance(reasoning, bool):
-        # 布尔类型，True 使用默认的 medium，False 不启用
+    if isinstance(reasoning, str) and reasoning in ("minimal", "low", "medium", "high"):
+        return reasoning, None  # type: ignore[return-value]
+
+    if isinstance(reasoning, bool):
         return ("medium", None) if reasoning else (None, None)
 
+    if isinstance(reasoning, dict):
+        return _parse_dict_reasoning_config(reasoning)
+
     # 其他类型或无效格式，默认不启用
     return None, None
 
 
+def _parse_dict_reasoning_config(reasoning: ReasoningEffortDict | ThinkingConfigDict | dict[str, Any]) -> tuple[ReasoningEffort | None, ThinkingConfig]:
+    """解析字典格式的推理配置。"""
+    # 检查是否为 {"effort": "value"} 格式 (ReasoningEffortDict)
+    if "effort" in reasoning and len(reasoning) == 1:
+        effort = reasoning["effort"]
+        if isinstance(effort, str) and effort in ("minimal", "low", "medium", "high"):
+            return effort, None  # type: ignore[return-value]
+
+    # 检查是否为 ThinkingConfigDict 格式
+    if "type" in reasoning and reasoning.get("type") == "enabled":
+        # 验证 ThinkingConfigDict 的结构
+        valid_keys = {"type", "budget_tokens"}
+        if all(key in valid_keys for key in reasoning):
+            return None, reasoning  # type: ignore[return-value]
+
+    # 其他未知字典格式，仍尝试作为 thinking_config
+    return None, reasoning  # type: ignore[return-value]
+
+
 class BaseLLMClient(abc.ABC):
     """Base class for LLM clients."""
 
@@ -240,8 +267,7 @@ class LiteLLMClient(BaseLLMClient):
 
         # Add reasoning parameters if specified
         if final_reasoning_effort is not None:
-            response_params["reasoning_effort"] = final_reasoning_effort
+            response_params["reasoning"] = {"effort": final_reasoning_effort}
         if final_thinking_config is not None:
             response_params["thinking"] = final_thinking_config
-
         return await litellm.aresponses(**response_params)  # type: ignore[return-value]

lite_agent-0.12.0/src/lite_agent/context.py

@@ -0,0 +1,37 @@
+"""Context utilities for injecting history messages into tool calls."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class HistoryContext(BaseModel, Generic[T]):
+    """包含历史消息的上下文容器
+
+    这个类会自动被 Runner 用来包装用户的 context，确保工具函数能够访问历史消息。
+
+    Attributes:
+        history_messages: 工具调用前的所有历史消息
+        data: 用户自定义的上下文数据（可选）
+
+    Examples:
+        >>> # 只需要历史消息的工具
+        >>> async def count_messages(ctx: Context[HistoryContext[None]]) -> str:
+        ...     return f"总共 {len(ctx.value.history_messages)} 条消息"
+
+        >>> # 需要历史消息和用户数据的工具
+        >>> class UserData(BaseModel):
+        ...     user_id: str
+        >>>
+        >>> async def analyze_user(ctx: Context[HistoryContext[UserData]]) -> str:
+        ...     messages = ctx.value.history_messages
+        ...     user_id = ctx.value.data.user_id
+        ...     return f"用户 {user_id} 有 {len(messages)} 条消息"
+    """
+
+    history_messages: list[Any]
+    data: T | None = None