lite-agent 0.10.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

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/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/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/runner.py

@@ -5,8 +5,11 @@ from os import PathLike
 from pathlib import Path
 from typing import Any, Literal, cast
 
+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,
@@ -181,6 +184,24 @@ class Runner:
                         )
             return  # Stop processing other tool calls after transfer
 
+        # Auto-inject history messages into context
+        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)
+
         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 +291,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
 

lite_agent/utils/advanced_message_builder.py

@@ -1,7 +1,7 @@
 """Advanced message builder with fluent interface for complex message construction."""
 
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, Literal
 
 from lite_agent.loggers import logger
 from lite_agent.types import (
@@ -71,7 +71,7 @@ class FluentMessageBuilder:
         logger.debug(f"Added text content (length: {len(text)})")
         return self
 
-    def add_image(self, image_url: str | None = None, file_id: str | None = None, detail: str = "auto") -> "FluentMessageBuilder":
+    def add_image(self, image_url: str | None = None, file_id: str | None = None, detail: Literal["auto", "low", "high"] = "auto") -> "FluentMessageBuilder":
         """Add image content to user message."""
         if self._message_type != "user":
             msg = "Images can only be added to user messages"
@@ -121,10 +121,9 @@ class FluentMessageBuilder:
             msg = "Message type not set. Call user_message(), assistant_message(), or system_message() first."
             raise ValueError(msg)
 
-        if not hasattr(self._meta, "usage"):
-            self._meta.usage = MessageUsage()
-
-        if self._meta.usage is not None:
+        if isinstance(self._meta, AssistantMessageMeta):
+            if self._meta.usage is None:
+                self._meta.usage = MessageUsage()
             if input_tokens is not None:
                 self._meta.usage.input_tokens = input_tokens
             if output_tokens is not None:
@@ -144,20 +143,30 @@ class FluentMessageBuilder:
             msg = "Message type not set. Call user_message(), assistant_message(), or system_message() first."
             raise ValueError(msg)
 
-        if latency_ms is not None:
-            self._meta.latency_ms = latency_ms  # type: ignore[attr-defined]
-        if total_time_ms is not None:
-            self._meta.total_time_ms = total_time_ms  # type: ignore[attr-defined]
+        if isinstance(self._meta, AssistantMessageMeta):
+            if latency_ms is not None:
+                self._meta.latency_ms = latency_ms
+            if total_time_ms is not None:
+                self._meta.total_time_ms = total_time_ms
 
         return self
 
     def build(self) -> NewUserMessage | NewAssistantMessage | NewSystemMessage:
         """Build the final message."""
         if self._message_type == "user":
+            if not isinstance(self._meta, MessageMeta):
+                msg = "Invalid meta type for user message"
+                raise TypeError(msg)
             message = NewUserMessage(content=self._content_items, meta=self._meta)
         elif self._message_type == "assistant":
+            if not isinstance(self._meta, AssistantMessageMeta):
+                msg = "Invalid meta type for assistant message"
+                raise TypeError(msg)
             message = NewAssistantMessage(content=self._content_items, meta=self._meta)
         elif self._message_type == "system":
+            if not isinstance(self._meta, MessageMeta):
+                msg = "Invalid meta type for system message"
+                raise TypeError(msg)
             message = NewSystemMessage(content=self._content, meta=self._meta)
         else:
             msg = "Message type not set"
@@ -173,29 +182,53 @@ class MessageBuilderFactory:
     @staticmethod
     def create_simple_user_message(text: str) -> NewUserMessage:
         """Create a simple user text message."""
-        return FluentMessageBuilder().user_message().add_text(text).build()
+        result = FluentMessageBuilder().user_message().add_text(text).build()
+        if not isinstance(result, NewUserMessage):
+            msg = "Expected NewUserMessage"
+            raise TypeError(msg)
+        return result
 
     @staticmethod
     def create_simple_assistant_message(text: str, model: str | None = None) -> NewAssistantMessage:
         """Create a simple assistant text message."""
-        return FluentMessageBuilder().assistant_message(model).add_text(text).build()
+        result = FluentMessageBuilder().assistant_message(model).add_text(text).build()
+        if not isinstance(result, NewAssistantMessage):
+            msg = "Expected NewAssistantMessage"
+            raise TypeError(msg)
+        return result
 
     @staticmethod
     def create_system_message(text: str) -> NewSystemMessage:
         """Create a system message."""
-        return FluentMessageBuilder().system_message().add_text(text).build()
+        result = FluentMessageBuilder().system_message().add_text(text).build()
+        if not isinstance(result, NewSystemMessage):
+            msg = "Expected NewSystemMessage"
+            raise TypeError(msg)
+        return result
 
     @staticmethod
     def create_user_message_with_image(text: str, image_url: str) -> NewUserMessage:
         """Create a user message with text and image."""
-        return FluentMessageBuilder().user_message().add_text(text).add_image(image_url=image_url).build()
+        result = FluentMessageBuilder().user_message().add_text(text).add_image(image_url=image_url).build()
+        if not isinstance(result, NewUserMessage):
+            msg = "Expected NewUserMessage"
+            raise TypeError(msg)
+        return result
 
     @staticmethod
     def create_assistant_with_tool_call(text: str, call_id: str, tool_name: str, arguments: dict[str, Any], model: str | None = None) -> NewAssistantMessage:
         """Create an assistant message with text and a tool call."""
-        return FluentMessageBuilder().assistant_message(model).add_text(text).add_tool_call(call_id, tool_name, arguments).build()
+        result = FluentMessageBuilder().assistant_message(model).add_text(text).add_tool_call(call_id, tool_name, arguments).build()
+        if not isinstance(result, NewAssistantMessage):
+            msg = "Expected NewAssistantMessage"
+            raise TypeError(msg)
+        return result
 
     @staticmethod
     def create_assistant_with_tool_result(call_id: str, result: str, execution_time_ms: int | None = None, model: str | None = None) -> NewAssistantMessage:
         """Create an assistant message with just a tool result."""
-        return FluentMessageBuilder().assistant_message(model).add_tool_result(call_id, result, execution_time_ms).build()
+        build_result = FluentMessageBuilder().assistant_message(model).add_tool_result(call_id, result, execution_time_ms).build()
+        if not isinstance(build_result, NewAssistantMessage):
+            msg = "Expected NewAssistantMessage"
+            raise TypeError(msg)
+        return build_result

{lite_agent-0.10.0.dist-info → lite_agent-0.12.0.dist-info}/METADATA

@@ -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.dist-info → lite_agent-0.12.0.dist-info}/RECORD

@@ -1,12 +1,13 @@
 lite_agent/__init__.py,sha256=Swuefee0etSiaDnn30K2hBNV9UI3hIValW3A-pRE7e0,338
-lite_agent/agent.py,sha256=UXmQY8vhi_2DIPcWkji0B_pCGlBvZLfx6YoNaUJO6Wc,18028
+lite_agent/agent.py,sha256=gMn-NeQxl0298uKmlJph_c9WP3QN8WeKMEEDuv5RdVw,18681
 lite_agent/chat_display.py,sha256=6gPgutMj7hCUOH6QBcC2f4Bhc93Gdq4vBa_1y6QKt2g,40793
-lite_agent/client.py,sha256=8PQeyMZ9eu7FXSP9ovLCIyuqUOfXPPN3kiUU1qn_NSk,9035
+lite_agent/client.py,sha256=-9BXLhAp3bGJsdKJ02lLpPJeHQKyHKQwhebZ6WCYh_k,9988
 lite_agent/constants.py,sha256=_xIDdQwaJrWk8N_62o-KYEo3jj1waPJ0ZOd3hHybKNo,718
+lite_agent/context.py,sha256=qnqj4JVYL0pkle1YptwM_CXJUWTeLaYtI1_MGtJYaHI,1225
 lite_agent/loggers.py,sha256=XkNkdqwD_nQGfhQJ-bBWT7koci_mMkNw3aBpyMhOICw,57
 lite_agent/message_transfers.py,sha256=N9ViK7Gxqqa1sd3V_hkNuQ9fUipg7M95l-sVBBG2Id4,5357
 lite_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lite_agent/runner.py,sha256=qcKS12JRnzwdBDzOlxn8TNJU9nf4Dz2ZzLvD_7yUt2s,43819
+lite_agent/runner.py,sha256=p-Dw4RNYfRnIwnbt8oJv8e4qI84X7OUWLxgyITMnGe8,45090
 lite_agent/processors/__init__.py,sha256=ybpAzpMBIE9v5I24wIBZRXeaOaPNTmoKH13aofgNI6Q,234
 lite_agent/processors/completion_event_processor.py,sha256=zoWvs8dfrIkCSITGtS-4Hpve3WFCA0UUsMvYifL2fw0,13010
 lite_agent/processors/response_event_processor.py,sha256=Jr3cj1ItJ8aq9UBhEEjDwWDnPNOZ2ZXjWJ3-g4ghkhM,8514
@@ -24,11 +25,11 @@ lite_agent/types/events.py,sha256=mFMqV55WWJbPDyb_P61nd3qMLpEnwZgVY6NTKFkINkg,23
 lite_agent/types/messages.py,sha256=aq36BOLktd6rwxknqVXOLK7pLlwYktaBFn0Sp71l6nw,9993
 lite_agent/types/tool_calls.py,sha256=Xnut8-2-Ld9vgA2GKJY6BbFlBaAv_n4W7vo7Jx21A-E,260
 lite_agent/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lite_agent/utils/advanced_message_builder.py,sha256=qKM2cm1nQrDJ8RxbUfvi31mIqXIw1LQ-igAp_CB0uz4,8696
+lite_agent/utils/advanced_message_builder.py,sha256=3U1PQrbdYQuIkv3j83TggDu3TmFN57TPZU32GTyPe4E,10196
 lite_agent/utils/message_builder.py,sha256=J-yycL9pXSO9MbgC5NEGqvoP1LC2Nxe9r2YRWXoaIAQ,8126
 lite_agent/utils/message_converter.py,sha256=5HmNncTl71TD2M_6Ezz1Tnfavzna8DQYb4-D47Du7mA,9165
 lite_agent/utils/message_state_manager.py,sha256=rFUyqyd_7NdJRtyqsAWGcfwrDIlD6gK2dBDSDx1eGBs,5766
 lite_agent/utils/metrics.py,sha256=RzOEhCWxbLmmIEkzaxOJ6tAdthI8dv2Foc98Lq8afOQ,1915
-lite_agent-0.10.0.dist-info/METADATA,sha256=Ju9w3WAg6AvOqyFocCPMTfkSv-AepicdWkgQVonFKAM,3487
-lite_agent-0.10.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-lite_agent-0.10.0.dist-info/RECORD,,
+lite_agent-0.12.0.dist-info/METADATA,sha256=CvsMgd3DNYoZTvD0bTirNibch5S9eH8K-hjwWvEjFZo,3538
+lite_agent-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lite_agent-0.12.0.dist-info/RECORD,,