lite-agent 0.4.1__tar.gz → 0.5.0__tar.gz

{lite_agent-0.4.1 → lite_agent-0.5.0}/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.5.0
+
+[v0.4.1...v0.5.0](https://github.com/Jannchie/lite-agent/compare/v0.4.1...v0.5.0)
+
+### :sparkles: Features
+
+- **reasoning**: add unified reasoning config for agent and runner - By [Jannchie](mailto:jannchie@gmail.com) in [1ede077](https://github.com/Jannchie/lite-agent/commit/1ede077)
+
+### :adhesive_bandage: Fixes
+
+- **runner**: remove redundant last message check - By [Jannchie](mailto:jannchie@gmail.com) in [0037b96](https://github.com/Jannchie/lite-agent/commit/0037b96)
+
+### :memo: Documentation
+
+- **claude-guide**: expand testing linting and dev instructions - By [Jannchie](mailto:jannchie@gmail.com) in [d9136c2](https://github.com/Jannchie/lite-agent/commit/d9136c2)
+
 ## v0.4.1
 
 [v0.4.0...v0.4.1](https://github.com/Jannchie/lite-agent/compare/v0.4.0...v0.4.1)

{lite_agent-0.4.1 → lite_agent-0.5.0}/CLAUDE.md

@@ -10,21 +10,40 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 pytest                    # Run all tests
 pytest tests/unit/        # Run only unit tests
 pytest tests/integration/ # Run only integration tests
+pytest tests/performance/ # Run performance tests
 pytest --cov             # Run with coverage
+pytest -v                # Verbose output
+pytest -k "test_name"     # Run specific test
 ```
 
 ### Linting and Formatting
 
 ```bash
 ruff check               # Run linter
+ruff check --fix         # Run linter and auto-fix issues
 ruff format              # Format code
+pyright                  # Type checking (optional)
 ```
 
 ### Package Management
 
 ```bash
-uv add lite-agent # Install from PyPI
-uv add --dev lite-agent # Install dev package
+uv install              # Install all dependencies
+uv add <package>         # Add a new dependency
+uv add --dev <package>   # Add a development dependency
+uv sync                  # Sync dependencies from lock file
+uv run <command>         # Run command in project environment
+```
+
+### Running Examples
+
+```bash
+uv run python examples/basic.py
+uv run python examples/handoffs.py  
+uv run python examples/chat_display_demo.py
+uv run python examples/context.py
+uv run python examples/terminal.py
+uv run python examples/translate/main.py
 ```
 
 ## Project Architecture
@@ -92,9 +111,31 @@ Examples demonstrate various usage patterns:
 
 ### Testing Architecture
 
-- **Unit tests**: Test individual components in isolation
-- **Integration tests**: Test full agent workflows with mocked LLM responses
-- **Performance tests**: Test memory usage and performance characteristics
-- **Mock system**: JSONL-based conversation recording/playback for deterministic testing
+- **Unit tests**: Test individual components in isolation (`tests/unit/`)
+- **Integration tests**: Test full agent workflows with mocked LLM responses (`tests/integration/`)
+- **Performance tests**: Test memory usage and performance characteristics (`tests/performance/`)
+- **Mock system**: JSONL-based conversation recording/playback for deterministic testing (`tests/mocks/`)
+
+**Recording Mock Conversations**: Use `scripts/record_chat_messages.py` to capture real LLM interactions for test scenarios
+
+### API Compatibility
+
+The framework supports two OpenAI API modes:
+
+- **Response API** (default): Modern structured response format
+- **Completion API**: Legacy completion format for backward compatibility
+
+Set via `Runner(agent, api="completion")` or `Runner(agent, api="responses")`.
+
+### Development Notes
+
+- Project uses strict ruff linting with `select = ["ALL"]` and specific ignores
+- All functions require full type annotations
+- Uses `uv` for package management and dependency resolution  
+- Mock conversations stored in `tests/mocks/` as JSONL files for reproducible testing
+- Examples in `examples/` directory demonstrate various usage patterns
+- Template system uses Jinja2 for dynamic instruction generation (`src/lite_agent/templates/`)
+- Requires `litellm` as core dependency for LLM interactions
+- Chat display functionality uses `rich` library for formatted console output
 
 The framework emphasizes simplicity and extensibility while maintaining full type safety and comprehensive streaming support.

{lite_agent-0.4.1 → lite_agent-0.5.0}/PKG-INFO

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

lite_agent-0.5.0/examples/reasoning_example.py

@@ -0,0 +1,113 @@
+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)
+
+
+async def analyze_complex_problem(problem_description: str) -> str:
+    """Analyze a complex problem and return insights."""
+    return f"Analysis for: {problem_description}\n- Key factors identified\n- Potential solutions outlined\n- Risk assessment completed"
+
+
+async def demo_reasoning_configurations():
+    """演示不同的推理配置方法。"""
+    print("=== 推理配置演示 ===\n")
+
+    # 1. 在Agent初始化时设置推理参数
+    print("1. Agent初始化时设置reasoning_effort:")
+    agent_with_reasoning = Agent(
+        model="gpt-4o-mini",
+        name="推理助手",
+        instructions="你是一个深度分析助手，使用仔细的推理来提供全面的分析。",
+        reasoning_effort="high",  # 高强度推理
+    )
+    print(f"   Agent推理努力程度: {agent_with_reasoning.reasoning_effort}")
+    print(f"   客户端推理努力程度: {agent_with_reasoning.client.reasoning_effort}")
+
+    # 2. 使用thinking_config进行更精细的控制
+    print("\n2. 使用thinking_config进行精细控制:")
+    agent_with_thinking = Agent(
+        model="claude-3-5-sonnet-20241022",  # Anthropic模型支持thinking
+        name="思考助手",
+        instructions="你是一个深思熟虑的助手。",
+        thinking_config={"type": "enabled", "budget_tokens": 2048},
+    )
+    print(f"   Agent思考配置: {agent_with_thinking.thinking_config}")
+    print(f"   客户端思考配置: {agent_with_thinking.client.thinking_config}")
+
+    # 3. 同时设置reasoning_effort和thinking_config
+    print("\n3. 同时设置多种推理参数:")
+    agent_full_config = Agent(
+        model="o1-mini",  # OpenAI推理模型
+        name="全配置推理助手",
+        instructions="你是一个高级推理助手。",
+        reasoning_effort="medium",
+        thinking_config={"type": "enabled", "budget_tokens": 1024},
+    )
+    print(f"   推理努力程度: {agent_full_config.reasoning_effort}")
+    print(f"   思考配置: {agent_full_config.thinking_config}")
+
+    # 4. 演示运行时覆盖推理参数
+    print("\n4. 运行时覆盖推理参数:")
+    runner = Runner(agent_with_reasoning)
+    print("   - Agent默认使用 reasoning_effort='high'")
+    print("   - 运行时可通过 agent_kwargs 覆盖:")
+    print("     runner.run(query, agent_kwargs={'reasoning_effort': 'minimal'})")
+
+    # 注意：由于没有实际的API密钥，我们不运行真实的API调用
+    print("\n✓ 所有推理配置功能已成功设置！")
+
+
+async def main():
+    """主演示函数。"""
+    await demo_reasoning_configurations()
+
+    print("\n" + "="*60)
+    print("推理配置使用说明:")
+    print("="*60)
+    print("""
+1. reasoning_effort 参数 (OpenAI兼容):
+   - "minimal": 最小推理，快速响应
+   - "low": 低强度推理
+   - "medium": 中等推理（推荐）
+   - "high": 高强度推理，更深入分析
+
+2. thinking_config 参数 (Anthropic兼容):
+   - {"type": "enabled", "budget_tokens": N}
+   - N 可以是 1024, 2048, 4096 等
+
+3. 使用方法:
+   a) Agent初始化时设置: Agent(..., reasoning_effort="high")
+   b) 运行时覆盖: runner.run(query, agent_kwargs={"reasoning_effort": "low"})
+
+4. 模型兼容性:
+   - OpenAI: o1, o3, o4-mini 系列
+   - Anthropic: claude-3.5-sonnet 等
+   - 其他: 通过LiteLLM自动转换
+
+5. 示例代码:
+   ```python
+   agent = Agent(
+       model="gpt-4o-mini",
+       reasoning_effort="medium",
+       thinking_config={"type": "enabled", "budget_tokens": 2048}
+   )
+   ```
+    """)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{lite_agent-0.4.1 → lite_agent-0.5.0}/pyproject.toml

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

{lite_agent-0.4.1 → lite_agent-0.5.0}/src/lite_agent/agent.py

@@ -7,7 +7,7 @@ from funcall import Funcall
 from jinja2 import Environment, FileSystemLoader
 from litellm import CustomStreamWrapper
 
-from lite_agent.client import BaseLLMClient, LiteLLMClient
+from lite_agent.client import BaseLLMClient, LiteLLMClient, ReasoningConfig
 from lite_agent.loggers import logger
 from lite_agent.stream_handlers import litellm_completion_stream_handler, litellm_response_stream_handler
 from lite_agent.types import AgentChunk, FunctionCallEvent, FunctionCallOutputEvent, RunnerMessages, ToolCall, message_to_llm_dict, system_message_to_llm_dict
@@ -32,15 +32,21 @@ class Agent:
         handoffs: list["Agent"] | None = None,
         message_transfer: Callable[[RunnerMessages], RunnerMessages] | None = None,
         completion_condition: str = "stop",
+        reasoning: ReasoningConfig = None,
     ) -> None:
         self.name = name
         self.instructions = instructions
+        self.reasoning = reasoning
+
         if isinstance(model, BaseLLMClient):
             # If model is a BaseLLMClient instance, use it directly
             self.client = model
         else:
             # Otherwise, create a LitellmClient instance
-            self.client = LiteLLMClient(model=model)
+            self.client = LiteLLMClient(
+                model=model,
+                reasoning=reasoning,
+            )
         self.completion_condition = completion_condition
         self.handoffs = handoffs if handoffs else []
         self._parent: Agent | None = None
@@ -269,7 +275,12 @@ class Agent:
                 res.append(message)
         return res
 
-    async def completion(self, messages: RunnerMessages, record_to_file: Path | None = None) -> AsyncGenerator[AgentChunk, None]:
+    async def completion(
+        self,
+        messages: RunnerMessages,
+        record_to_file: Path | None = None,
+        reasoning: ReasoningConfig = None,
+    ) -> AsyncGenerator[AgentChunk, None]:
         # Apply message transfer callback if provided - always use legacy format for LLM compatibility
         processed_messages = messages
         if self.message_transfer:
@@ -284,6 +295,7 @@ class Agent:
             messages=self.message_histories,
             tools=tools,
             tool_choice="auto",  # TODO: make this configurable
+            reasoning=reasoning,
         )
 
         # Ensure resp is a CustomStreamWrapper
@@ -292,7 +304,12 @@ class Agent:
         msg = "Response is not a CustomStreamWrapper, cannot stream chunks."
         raise TypeError(msg)
 
-    async def responses(self, messages: RunnerMessages, record_to_file: Path | None = None) -> AsyncGenerator[AgentChunk, None]:
+    async def responses(
+        self,
+        messages: RunnerMessages,
+        record_to_file: Path | None = None,
+        reasoning: ReasoningConfig = None,
+    ) -> AsyncGenerator[AgentChunk, None]:
         # Apply message transfer callback if provided - always use legacy format for LLM compatibility
         processed_messages = messages
         if self.message_transfer:
@@ -306,6 +323,7 @@ class Agent:
             messages=self.message_histories,
             tools=tools,
             tool_choice="auto",  # TODO: make this configurable
+            reasoning=reasoning,
         )
         return litellm_response_stream_handler(resp, record_to=record_to_file)
 

lite_agent-0.5.0/src/lite_agent/client.py

@@ -0,0 +1,178 @@
+import abc
+import os
+from typing import Any, Literal
+
+import litellm
+from openai.types.chat import ChatCompletionToolParam
+from openai.types.responses import FunctionToolParam
+
+ReasoningEffort = Literal["minimal", "low", "medium", "high"]
+ThinkingConfig = dict[str, Any] | None
+
+# 统一的推理配置类型
+ReasoningConfig = (
+    str
+    | dict[str, Any]  # {"type": "enabled", "budget_tokens": 2048} 或其他配置
+    | bool  # True/False 简单开关
+    | None  # 不启用推理
+)
+
+
+def parse_reasoning_config(reasoning: ReasoningConfig) -> tuple[ReasoningEffort | None, ThinkingConfig]:
+    """
+    解析统一的推理配置，返回 reasoning_effort 和 thinking_config。
+
+    Args:
+        reasoning: 统一的推理配置
+            - str: "minimal", "low", "medium", "high" -> reasoning_effort
+            - dict: {"type": "enabled", "budget_tokens": N} -> thinking_config
+            - bool: True -> "medium", False -> None
+            - None: 不启用推理
+
+    Returns:
+        tuple: (reasoning_effort, thinking_config)
+    """
+    if reasoning is None:
+        return None, None
+    if isinstance(reasoning, str):
+        # 字符串类型，使用 reasoning_effort
+        return reasoning, None
+    if isinstance(reasoning, dict):
+        # 字典类型，使用 thinking_config
+        return None, reasoning
+    if isinstance(reasoning, bool):
+        # 布尔类型，True 使用默认的 medium，False 不启用
+        return "medium" if reasoning else None, None
+    # 其他类型，默认不启用
+    return None, None
+
+
+class BaseLLMClient(abc.ABC):
+    """Base class for LLM clients."""
+
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str | None = None,
+        api_base: str | None = None,
+        api_version: str | None = None,
+        reasoning: ReasoningConfig = None,
+    ):
+        self.model = model
+        self.api_key = api_key
+        self.api_base = api_base
+        self.api_version = api_version
+
+        # 处理推理配置
+        self.reasoning_effort, self.thinking_config = parse_reasoning_config(reasoning)
+
+    @abc.abstractmethod
+    async def completion(
+        self,
+        messages: list[Any],
+        tools: list[ChatCompletionToolParam] | None = None,
+        tool_choice: str = "auto",
+        reasoning: ReasoningConfig = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> Any:  # noqa: ANN401
+        """Perform a completion request to the LLM."""
+
+    @abc.abstractmethod
+    async def responses(
+        self,
+        messages: list[dict[str, Any]],  # Changed from ResponseInputParam
+        tools: list[FunctionToolParam] | None = None,
+        tool_choice: Literal["none", "auto", "required"] = "auto",
+        reasoning: ReasoningConfig = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> Any:  # noqa: ANN401
+        """Perform a response request to the LLM."""
+
+
+class LiteLLMClient(BaseLLMClient):
+    def _resolve_reasoning_params(
+        self,
+        reasoning: ReasoningConfig,
+    ) -> tuple[ReasoningEffort | None, ThinkingConfig]:
+        """解析推理配置参数。"""
+        if reasoning is not None:
+            return parse_reasoning_config(reasoning)
+
+        # 使用实例默认值
+        return self.reasoning_effort, self.thinking_config
+
+    async def completion(
+        self,
+        messages: list[Any],
+        tools: list[ChatCompletionToolParam] | None = None,
+        tool_choice: str = "auto",
+        reasoning: ReasoningConfig = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> Any:  # noqa: ANN401
+        """Perform a completion request to the Litellm API."""
+
+        # 处理推理配置参数
+        final_reasoning_effort, final_thinking_config = self._resolve_reasoning_params(
+            reasoning,
+        )
+
+        # Prepare completion parameters
+        completion_params = {
+            "model": self.model,
+            "messages": messages,
+            "tools": tools,
+            "tool_choice": tool_choice,
+            "api_version": self.api_version,
+            "api_key": self.api_key,
+            "api_base": self.api_base,
+            "stream": True,
+            **kwargs,
+        }
+
+        # Add reasoning parameters if specified
+        if final_reasoning_effort is not None:
+            completion_params["reasoning_effort"] = final_reasoning_effort
+        if final_thinking_config is not None:
+            completion_params["thinking"] = final_thinking_config
+
+        return await litellm.acompletion(**completion_params)
+
+    async def responses(
+        self,
+        messages: list[dict[str, Any]],  # Changed from ResponseInputParam
+        tools: list[FunctionToolParam] | None = None,
+        tool_choice: Literal["none", "auto", "required"] = "auto",
+        reasoning: ReasoningConfig = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> Any:  # type: ignore[return]  # noqa: ANN401
+        """Perform a response request to the Litellm API."""
+
+        os.environ["DISABLE_AIOHTTP_TRANSPORT"] = "True"
+
+        # 处理推理配置参数
+        final_reasoning_effort, final_thinking_config = self._resolve_reasoning_params(
+            reasoning,
+        )
+
+        # Prepare response parameters
+        response_params = {
+            "model": self.model,
+            "input": messages,  # type: ignore[arg-type]
+            "tools": tools,
+            "tool_choice": tool_choice,
+            "api_version": self.api_version,
+            "api_key": self.api_key,
+            "api_base": self.api_base,
+            "stream": True,
+            "store": False,
+            **kwargs,
+        }
+
+        # Add reasoning parameters if specified
+        if final_reasoning_effort is not None:
+            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.4.1 → lite_agent-0.5.0}/src/lite_agent/runner.py

@@ -168,13 +168,14 @@ class Runner:
         """Collect all chunks from an async generator into a list."""
         return [chunk async for chunk in stream]
 
-    def run(
+    def run(  # noqa: PLR0913
         self,
         user_input: UserInput,
         max_steps: int = 20,
         includes: Sequence[AgentChunkType] | None = None,
         context: "Any | None" = None,  # noqa: ANN401
         record_to: PathLike | str | None = None,
+        agent_kwargs: dict[str, Any] | None = None,
     ) -> AsyncGenerator[AgentChunk, None]:
         """Run the agent and return a RunResponse object that can be asynchronously iterated for each chunk."""
         includes = self._normalize_includes(includes)
@@ -188,9 +189,16 @@ class Runner:
             case _:
                 # Handle single message (BaseModel, TypedDict, or dict)
                 self.append_message(user_input)  # type: ignore[arg-type]
-        return self._run(max_steps, includes, self._normalize_record_path(record_to), context=context)
+        return self._run(max_steps, includes, self._normalize_record_path(record_to), context=context, agent_kwargs=agent_kwargs)
 
-    async def _run(self, max_steps: int, includes: Sequence[AgentChunkType], record_to: Path | None = None, context: Any | None = None) -> AsyncGenerator[AgentChunk, None]:  # noqa: ANN401
+    async def _run(
+        self,
+        max_steps: int,
+        includes: Sequence[AgentChunkType],
+        record_to: Path | None = None,
+        context: Any | None = None,  # noqa: ANN401
+        agent_kwargs: dict[str, Any] | None = None,
+    ) -> AsyncGenerator[AgentChunk, None]:
         """Run the agent and return a RunResponse object that can be asynchronously iterated for each chunk."""
         logger.debug(f"Running agent with messages: {self.messages}")
         steps = 0
@@ -213,11 +221,24 @@ class Runner:
             logger.debug(f"Step {steps}: finish_reason={finish_reason}, is_finish()={is_finish()}")
             # Convert to legacy format only when needed for LLM communication
             # This allows us to keep the new format internally but ensures compatibility
+            # Extract agent kwargs for reasoning configuration
+            reasoning = None
+            if agent_kwargs:
+                reasoning = agent_kwargs.get("reasoning")
+
             match self.api:
                 case "completion":
-                    resp = await self.agent.completion(self.messages, record_to_file=record_to)
+                    resp = await self.agent.completion(
+                        self.messages,
+                        record_to_file=record_to,
+                        reasoning=reasoning,
+                    )
                 case "responses":
-                    resp = await self.agent.responses(self.messages, record_to_file=record_to)
+                    resp = await self.agent.responses(
+                        self.messages,
+                        record_to_file=record_to,
+                        reasoning=reasoning,
+                    )
                 case _:
                     msg = f"Unknown API type: {self.api}"
                     raise ValueError(msg)
@@ -367,11 +388,6 @@ class Runner:
                 msg = "Cannot continue running without a valid last message from the assistant."
                 raise ValueError(msg)
 
-            last_message = self.messages[-1]
-            if not (isinstance(last_message, NewAssistantMessage) or (hasattr(last_message, "role") and getattr(last_message, "role", None) == "assistant")):
-                msg = "Cannot continue running without a valid last message from the assistant."
-                raise ValueError(msg)
-
             resp = self._run(max_steps=max_steps, includes=includes, record_to=self._normalize_record_path(record_to), context=context)
             async for chunk in resp:
                 yield chunk

{lite_agent-0.4.1 → lite_agent-0.5.0}/tests/unit/test_runner.py

@@ -141,21 +141,6 @@ async def test_run_stream_with_max_steps():
     assert len(results) == 1
 
 
-@pytest.mark.asyncio
-async def test_run_continue_stream_with_invalid_last_message():
-    """Test run_continue_stream when last message is not from assistant"""
-    agent = DummyAgent()
-    runner = Runner(agent=agent)
-
-    # Add a user message as the last message
-    user_msg_dict = {"role": "user", "content": "Hello"}
-    runner.append_message(user_msg_dict)
-
-    with pytest.raises(ValueError, match="Cannot continue running without a valid last message from the assistant"):
-        async for _ in runner.run_continue_stream():
-            pass
-
-
 @pytest.mark.asyncio
 async def test_run_continue_stream_with_empty_messages():
     """Test run_continue_stream when there are no messages"""