lite-agent 0.11.0__tar.gz → 0.13.0__tar.gz

{lite_agent-0.11.0 → lite_agent-0.13.0}/.claude/settings.local.json

@@ -21,7 +21,8 @@
       "Bash(mv:*)",
       "Bash(find:*)",
       "WebSearch",
-      "Bash(uv list:*)"
+      "Bash(uv list:*)",
+      "Bash(pip show:*)"
     ],
     "deny": []
   }

{lite_agent-0.11.0 → lite_agent-0.13.0}/CHANGELOG.md

@@ -1,3 +1,24 @@
+## v0.13.0
+
+[v0.12.0...v0.13.0](https://github.com/Jannchie/lite-agent/compare/v0.12.0...v0.13.0)
+
+### :sparkles: Features
+
+- **runner**: add selective history context injection based on tool signature - By [Jannchie](mailto:jannchie@gmail.com) in [15866d4](https://github.com/Jannchie/lite-agent/commit/15866d4)
+
+### :adhesive_bandage: Fixes
+
+- **runner**: improve historycontext parameter detection - By [Jannchie](mailto:jannchie@gmail.com) in [7099abc](https://github.com/Jannchie/lite-agent/commit/7099abc)
+
+## 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)

{lite_agent-0.11.0 → lite_agent-0.13.0}/PKG-INFO

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

{lite_agent-0.11.0 → lite_agent-0.13.0}/examples/basic.py

@@ -1,6 +1,8 @@
 import asyncio
 import logging
 
+from funcall import Context
+from openai import BaseModel
 from rich.logging import RichHandler
 
 from lite_agent.agent import Agent
@@ -19,8 +21,16 @@ logger = logging.getLogger("lite_agent")
 logger.setLevel(logging.DEBUG)
 
 
-async def get_temperature(city: str) -> str:
+class MyContext(BaseModel):
+    d: str
+
+
+ctx = Context(MyContext(d="example data"))
+
+
+async def get_temperature(city: str, ctx: Context[MyContext]) -> str:
     """Get the temperature for a city."""
+    print(ctx.value.d)
     return f"The temperature in {city} is 25°C."
 
 
@@ -37,6 +47,7 @@ async def main():
     await runner.run_until_complete(
         "What is the temperature in New York?",
         includes=["usage", "assistant_message", "function_call", "function_call_output", "timing"],
+        context=ctx,
     )
     display_messages(runner.messages)
 

{lite_agent-0.11.0 → lite_agent-0.13.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.13.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-nano",
+    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-nano",
+    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-nano",
+    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.13.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.11.0 → lite_agent-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lite-agent"
-version = "0.11.0"
+version = "0.13.0"
 description = "A lightweight, extensible framework for building AI agent."
 readme = "README.md"
 authors = [{ name = "Jianqi Pan", email = "jannchie@gmail.com" }]

{lite_agent-0.11.0 → lite_agent-0.13.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.13.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

{lite_agent-0.11.0 → lite_agent-0.13.0}/src/lite_agent/runner.py

@@ -1,12 +1,16 @@
 import json
+import inspect
 from collections.abc import AsyncGenerator, Sequence
 from datetime import datetime, timedelta, timezone
 from os import PathLike
 from pathlib import Path
-from typing import Any, Literal, cast
+from typing import Any, Literal, cast, get_args, get_origin
+
+from funcall import Context
 
 from lite_agent.agent import Agent
 from lite_agent.constants import CompletionMode, StreamIncludes, ToolName
+from lite_agent.context import HistoryContext
 from lite_agent.loggers import logger
 from lite_agent.types import (
     AgentChunk,
@@ -109,6 +113,59 @@ class Runner:
         """Normalize record_to parameter to Path object if provided."""
         return Path(record_to) if record_to else None
 
+    def _tool_expects_history_context(self, tool_calls: Sequence["ToolCall"]) -> bool:
+        """Check if any of the tool calls expect HistoryContext in their signatures.
+        
+        Returns True if any tool function has a Context[HistoryContext[...]] parameter,
+        False if they expect Context[...] without HistoryContext wrapper.
+        """
+        if not tool_calls:
+            return False
+            
+        for tool_call in tool_calls:
+            tool_func = self.agent.fc.function_registry.get(tool_call.function.name)
+            if not tool_func:
+                continue
+                
+            # Get function signature
+            sig = inspect.signature(tool_func)
+            
+            # Check each parameter for Context annotation
+            for param in sig.parameters.values():
+                if param.annotation == inspect.Parameter.empty:
+                    continue
+                    
+                # Check if parameter is Context[...]
+                origin = get_origin(param.annotation)
+                if origin is not None:
+                    # Check if it's Context type (compare by string name to handle import differences)
+                    origin_name = getattr(origin, '__name__', str(origin))
+                    if 'Context' in origin_name:
+                        args = get_args(param.annotation)
+                        if args:
+                            # Check if the Context contains HistoryContext
+                            inner_type = args[0]
+                            inner_origin = get_origin(inner_type)
+                            if inner_origin is not None:
+                                inner_name = getattr(inner_origin, '__name__', str(inner_origin))
+                                if 'HistoryContext' in inner_name:
+                                    logger.debug(f"Tool {tool_call.function.name} expects HistoryContext")
+                                    return True
+                            # Also check for direct HistoryContext class
+                            elif hasattr(inner_type, '__name__') and 'HistoryContext' in inner_type.__name__:
+                                logger.debug(f"Tool {tool_call.function.name} expects HistoryContext")
+                                return True
+                
+                # Also handle direct annotation checking
+                if hasattr(param.annotation, '__name__'):
+                    annotation_str = str(param.annotation)
+                    if 'HistoryContext' in annotation_str:
+                        logger.debug(f"Tool {tool_call.function.name} expects HistoryContext (direct)")
+                        return True
+                        
+        logger.debug("No tools expect HistoryContext")
+        return False
+
     async def _handle_tool_calls(self, tool_calls: "Sequence[ToolCall] | None", includes: Sequence[AgentChunkType], context: "Any | None" = None) -> AsyncGenerator[AgentChunk, None]:  # noqa: ANN401
         """Handle tool calls and yield appropriate chunks."""
         if not tool_calls:
@@ -181,6 +238,34 @@ class Runner:
                         )
             return  # Stop processing other tool calls after transfer
 
+        # Check if tools expect HistoryContext wrapper
+        expects_history = self._tool_expects_history_context(tool_calls)
+        
+        if expects_history:
+            # Auto-inject history messages into context for tools that expect HistoryContext
+            if context is not None and not isinstance(context, Context):
+                # If user provided a plain object, wrap it in Context first
+                context = Context(context)
+
+            if isinstance(context, Context):
+                # Extract original value and wrap in HistoryContext
+                original_value = context.value
+                wrapped = HistoryContext(
+                    history_messages=self.messages.copy(),
+                    data=original_value,
+                )
+                context = Context(wrapped)
+            else:
+                # No context provided, create HistoryContext with only history messages
+                wrapped = HistoryContext(history_messages=self.messages.copy())
+                context = Context(wrapped)
+        elif context is not None and not isinstance(context, Context):
+            # Tools don't expect HistoryContext, wrap user object in Context
+            context = Context(context)
+        elif context is None:
+            # Provide empty context for tools that don't expect HistoryContext
+            context = Context(None)
+
         async for tool_call_chunk in self.agent.handle_tool_calls(tool_calls, context=context):
             # if tool_call_chunk.type == "function_call" and tool_call_chunk.type in includes:
             #     yield tool_call_chunk
@@ -270,12 +355,18 @@ class Runner:
 
         def is_finish() -> bool:
             if completion_condition == CompletionMode.CALL:
-                # Check if wait_for_user was called in the last assistant message
+                # Check if any termination tool was called in the last assistant message
                 if self.messages and isinstance(self.messages[-1], NewAssistantMessage):
                     last_message = self.messages[-1]
                     for content_item in last_message.content:
-                        if isinstance(content_item, AssistantToolCallResult) and self._get_tool_call_name_by_id(content_item.call_id) == ToolName.WAIT_FOR_USER:
-                            return True
+                        if isinstance(content_item, AssistantToolCallResult):
+                            tool_name = self._get_tool_call_name_by_id(content_item.call_id)
+                            # Check custom termination tools first, then default wait_for_user
+                            if hasattr(self.agent, "termination_tools") and self.agent.termination_tools:
+                                if tool_name in self.agent.termination_tools:
+                                    return True
+                            elif tool_name == ToolName.WAIT_FOR_USER:
+                                return True
                 return False
             return finish_reason == CompletionMode.STOP
 
@@ -484,9 +575,10 @@ class Runner:
         max_steps: int = 20,
         includes: list[AgentChunkType] | None = None,
         record_to: PathLike | str | None = None,
+        context: Context | None = None,
     ) -> list[AgentChunk]:
         """Run the agent until it completes and return the final message."""
-        resp = self.run(user_input, max_steps, includes, record_to=record_to)
+        resp = self.run(user_input, max_steps, includes, record_to=record_to, context=context)
         return await self._collect_all_chunks(resp)
 
     def _analyze_last_assistant_message(self) -> tuple[list[AssistantToolCall], dict[str, str]]: