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

{lite_agent-0.4.1 → lite_agent-0.6.0}/.claude/settings.local.json

@@ -14,7 +14,8 @@
       "Bash(uv run pytest:*)",
       "Bash(timeout:*)",
       "Bash(pyright:*)",
-      "Bash(rg:*)"
+      "Bash(rg:*)",
+      "Bash(uv run:*)"
     ],
     "deny": []
   }

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

@@ -1,3 +1,28 @@
+## v0.6.0
+
+[v0.5.0...v0.6.0](https://github.com/Jannchie/lite-agent/compare/v0.5.0...v0.6.0)
+
+### :sparkles: Features
+
+- **examples**: add basic and llm config usage examples - By [Jannchie](mailto:jannchie@gmail.com) in [ea4112f](https://github.com/Jannchie/lite-agent/commit/ea4112f)
+- **streaming**: add unified streaming and non-streaming response handling - By [Jannchie](mailto:jannchie@gmail.com) in [53daf42](https://github.com/Jannchie/lite-agent/commit/53daf42)
+
+## 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.6.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.6.0}/PKG-INFO

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

lite_agent-0.6.0/examples/basic_model.py

@@ -0,0 +1,53 @@
+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.client import LiteLLMClient
+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=LiteLLMClient(
+        model="gpt-4o-mini",
+        temperature=0.7,
+        max_tokens=150,
+        top_p=0.9,
+    ),
+    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],
+)
+
+
+async def main():
+    runner = Runner(agent)
+    resp = runner.run(
+        "What is the temperature in New York?",
+        includes=["usage", "assistant_message", "function_call", "function_call_output", "timing"],
+    )
+    async for chunk in resp:
+        logger.info(chunk)
+    display_messages(runner.messages)
+    print(runner.messages)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/debug_non_streaming.py

@@ -0,0 +1,56 @@
+"""
+Debug example to investigate non-streaming mode issues.
+"""
+import asyncio
+import logging
+
+from lite_agent import Agent, Runner
+
+# Enable debug logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger("lite_agent")
+logger.setLevel(logging.DEBUG)
+
+
+async def main():
+    # Create an agent
+    agent = Agent(
+        name="DebugAgent",
+        model="gpt-4o-mini",
+        instructions="You are a helpful assistant.",
+    )
+
+    print("=== Debug Non-Streaming Mode ===")
+
+    # Test with streaming=False
+    runner = Runner(agent, streaming=False)
+
+    print("Running in non-streaming mode...")
+    chunks = []
+
+    async for chunk in runner.run("Hello, please say hi back."):
+        print(f"Received chunk: {chunk}")
+        print(f"Chunk type: {chunk.type}")
+        if hasattr(chunk, "message"):
+            print(f"Chunk message: {chunk.message}")
+        if hasattr(chunk, "content"):
+            print(f"Chunk content: {chunk.content}")
+        chunks.append(chunk)
+
+    print(f"\nTotal chunks received: {len(chunks)}")
+
+    # Compare with streaming mode
+    print("\n=== Compare with Streaming Mode ===")
+    runner_streaming = Runner(agent, streaming=True)
+
+    streaming_chunks = []
+    async for chunk in runner_streaming.run("Hello, please say hi back too."):
+        streaming_chunks.append(chunk)
+        if chunk.type == "content_delta":
+            print(chunk.delta, end="", flush=True)
+
+    print(f"\nStreaming chunks received: {len(streaming_chunks)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/debug_with_logging.py

@@ -0,0 +1,38 @@
+"""
+Debug with full logging enabled.
+"""
+import asyncio
+import logging
+
+from lite_agent import Agent, Runner
+
+# Configure logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(name)s - %(levelname)s - %(message)s",
+)
+
+# Enable specific loggers
+logging.getLogger("lite_agent").setLevel(logging.DEBUG)
+
+
+async def main():
+    agent = Agent(
+        name="TestAgent",
+        model="gpt-4o-mini",
+        instructions="You are helpful.",
+    )
+
+    print("=== Testing Non-Streaming ===")
+    runner = Runner(agent, streaming=False)
+
+    chunks = []
+    async for chunk in runner.run("Hello"):
+        chunks.append(chunk)
+        print(f"Got chunk: {chunk.type}")
+
+    print(f"Total chunks: {len(chunks)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/llm_config_demo.py

@@ -0,0 +1,90 @@
+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.client import LiteLLMClient, LLMConfig
+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 current weather for a city."""
+    return f"The weather in {city} is sunny, 25°C."
+
+
+# Method 1: Using individual parameters
+agent1 = Agent(
+    model=LiteLLMClient(
+        model="gpt-4o-mini",
+        temperature=0.3,
+        max_tokens=100,
+        top_p=0.8,
+        frequency_penalty=0.1,
+        presence_penalty=0.1,
+        stop=["END"],
+    ),
+    name="Weather Bot (Individual Params)",
+    instructions="You are a weather assistant. Keep responses brief and factual.",
+    tools=[get_weather],
+)
+
+# Method 2: Using LLMConfig object
+llm_config = LLMConfig(
+    temperature=0.8,
+    max_tokens=200,
+    top_p=0.9,
+    frequency_penalty=0.0,
+    presence_penalty=0.0,
+)
+
+agent2 = Agent(
+    model=LiteLLMClient(
+        model="gpt-4o-mini",
+        llm_config=llm_config,
+    ),
+    name="Weather Bot (LLMConfig)",
+    instructions="You are a creative weather assistant. Add some personality to your responses.",
+    tools=[get_weather],
+)
+
+
+async def main():
+    # Test agent with conservative settings (low temperature, short responses)
+    print("=== Testing Agent 1 (Conservative Settings) ===")
+    runner1 = Runner(agent1)
+    resp1 = runner1.run(
+        "What's the weather like in Tokyo?",
+        includes=["assistant_message"],
+    )
+    async for chunk in resp1:
+        logger.info(chunk)
+    display_messages(runner1.messages)
+
+    print("\n" + "="*50 + "\n")
+
+    # Test agent with creative settings (high temperature, longer responses)
+    print("=== Testing Agent 2 (Creative Settings) ===")
+    runner2 = Runner(agent2)
+    resp2 = runner2.run(
+        "What's the weather like in Tokyo?",
+        includes=["assistant_message"],
+    )
+    async for chunk in resp2:
+        logger.info(chunk)
+    display_messages(runner2.messages)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/non_streaming.py

@@ -0,0 +1,64 @@
+"""
+Simple example demonstrating non-streaming mode in LiteAgent.
+"""
+import asyncio
+
+from lite_agent import Agent, Runner
+
+
+async def main():
+    # Create an agent
+    agent = Agent(
+        name="NonStreamingDemo",
+        model="gpt-4o-mini",
+        instructions="You are a helpful assistant.",
+    )
+
+    # Create runner with non-streaming mode
+    runner = Runner(agent, streaming=False)
+
+    print("=== Non-Streaming Mode Example ===")
+    print("Question: Explain what Python is in one sentence.")
+    print("Response: ", end="", flush=True)
+
+    # In non-streaming mode, you get the complete response at once
+    async for chunk in runner.run("Explain what Python is in one sentence."):
+        if chunk.type == "assistant_message":
+            # Non-streaming mode typically yields one complete message
+            print(chunk.message.content[0].text)
+
+    print("\n=== Tool Usage with Non-Streaming ===")
+
+    # Example with a simple tool
+    def get_time() -> str:
+        """Get the current time."""
+        from datetime import datetime
+        return f"Current time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
+
+    agent_with_tools = Agent(
+        name="TimeAgent",
+        model="gpt-4o-mini",
+        instructions="You help users with time-related queries. Use the get_time tool when asked about time.",
+        tools=[get_time],
+    )
+
+    runner_with_tools = Runner(agent_with_tools, streaming=False)
+
+    print("Question: What time is it now?")
+    print("Response:")
+
+    async for chunk in runner_with_tools.run("What time is it now?"):
+        if chunk.type == "assistant_message":
+            print(chunk.message.content[0].text)
+        elif chunk.type == "function_call_output":
+            print(f"Tool output: {chunk.content}")
+
+    print("\n=== Benefits of Non-Streaming Mode ===")
+    print("1. Simpler processing - get complete responses")
+    print("2. Easier for batch processing")
+    print("3. Better for APIs that need complete responses")
+    print("4. Lower overhead for short interactions")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/reasoning_example.py

@@ -0,0 +1,113 @@
+import asyncio
+import logging
+
+from rich.logging import RichHandler
+
+from lite_agent.agent import Agent
+
+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. 使用reasoning参数设置推理强度（字符串形式）
+    print("1. 使用reasoning参数设置推理强度:")
+    agent_with_reasoning = Agent(
+        model="gpt-4o-mini",
+        name="推理助手",
+        instructions="你是一个深度分析助手，使用仔细的推理来提供全面的分析。",
+        reasoning="high",  # 高强度推理
+    )
+    print(f"   Agent推理配置: {agent_with_reasoning.reasoning}")
+    print(f"   客户端推理努力程度: {agent_with_reasoning.client.reasoning_effort}")
+    print(f"   客户端思考配置: {agent_with_reasoning.client.thinking_config}")
+
+    # 2. 使用reasoning参数进行更精细的控制（字典形式）
+    print("\n2. 使用reasoning参数进行精细控制:")
+    agent_with_thinking = Agent(
+        model="claude-3-5-sonnet-20241022",  # Anthropic模型支持thinking
+        name="思考助手",
+        instructions="你是一个深思熟虑的助手。",
+        reasoning={"type": "enabled", "budget_tokens": 2048},  # 使用字典形式
+    )
+    print(f"   Agent推理配置: {agent_with_thinking.reasoning}")
+    print(f"   客户端推理努力程度: {agent_with_thinking.client.reasoning_effort}")
+    print(f"   客户端思考配置: {agent_with_thinking.client.thinking_config}")
+
+    # 3. 使用布尔值设置推理（会默认使用medium级别）
+    print("\n3. 使用布尔值启用推理:")
+    agent_bool_reasoning = Agent(
+        model="o1-mini",  # OpenAI推理模型
+        name="布尔推理助手",
+        instructions="你是一个高级推理助手。",
+        reasoning=True,  # 布尔值，会使用默认的medium级别
+    )
+    print(f"   Agent推理配置: {agent_bool_reasoning.reasoning}")
+    print(f"   客户端推理努力程度: {agent_bool_reasoning.client.reasoning_effort}")
+    print(f"   客户端思考配置: {agent_bool_reasoning.client.thinking_config}")
+
+    # 4. 演示运行时覆盖推理参数
+    print("\n4. 运行时覆盖推理参数:")
+    print("   - Agent默认使用 reasoning='high'")
+    print("   - 运行时可通过 agent_kwargs 覆盖:")
+    print("     runner.run(query, agent_kwargs={'reasoning': '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.6.0/examples/simple_debug.py

@@ -0,0 +1,36 @@
+"""
+Simple debug to check non-streaming response.
+"""
+import asyncio
+
+from lite_agent import Agent, Runner
+
+
+async def main():
+    agent = Agent(
+        name="TestAgent",
+        model="gpt-4o-mini",
+        instructions="You are helpful.",
+    )
+
+    # Test non-streaming
+    print("Testing non-streaming...")
+    runner = Runner(agent, streaming=False)
+
+    try:
+        chunks = []
+        async for chunk in runner.run("Say hello"):
+            chunks.append(chunk)
+            print(f"Received chunk type: {chunk.type}")
+
+        print(f"Total chunks: {len(chunks)}")
+        if chunks:
+            print(f"First chunk: {chunks[0]}")
+    except Exception as e:
+        print(f"Error: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/simple_debug2.py

@@ -0,0 +1,30 @@
+"""
+Simple debug to check which API is being used.
+"""
+import asyncio
+
+from lite_agent import Agent, Runner
+
+
+async def main():
+    agent = Agent(
+        name="TestAgent",
+        model="gpt-4o-mini",
+        instructions="You are helpful.",
+    )
+
+    # Test non-streaming with explicit API
+    print("Testing non-streaming with responses API...")
+    runner = Runner(agent, api="responses", streaming=False)
+    print(f"Runner API: {runner.api}")
+    print(f"Runner streaming: {runner.streaming}")
+
+    # Test with completion API
+    print("\nTesting non-streaming with completion API...")
+    runner2 = Runner(agent, api="completion", streaming=False)
+    print(f"Runner API: {runner2.api}")
+    print(f"Runner streaming: {runner2.streaming}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

lite_agent-0.6.0/examples/streaming_demo.py

@@ -0,0 +1,73 @@
+"""
+Demo script showing streaming vs non-streaming configuration in LiteAgent.
+"""
+import asyncio
+import time
+
+from lite_agent import Agent, Runner
+
+
+async def main():
+    # Create an agent
+    agent = Agent(
+        name="StreamingDemo",
+        model="gpt-4o-mini",
+        instructions="You are a helpful assistant. Always respond concisely.",
+    )
+
+    print("=== Streaming Mode (Default) ===")
+    # Default streaming=True
+    runner_streaming = Runner(agent, streaming=True)
+
+    chunks = []
+    print("Question: What is the capital of France?")
+    print("Response: ", end="", flush=True)
+    async for chunk in runner_streaming.run("What is the capital of France?"):
+        chunks.append(chunk)
+        if chunk.type == "content_delta":
+            print(chunk.delta, end="", flush=True)
+    print(f"\nReceived {len(chunks)} chunks in streaming mode\n")
+
+    print("=== Non-Streaming Mode ===")
+    # Set streaming=False
+    runner_non_streaming = Runner(agent, streaming=False)
+
+    chunks = []
+    print("Question: What is the capital of Germany?")
+    print("Response: ", end="", flush=True)
+    async for chunk in runner_non_streaming.run("What is the capital of Germany?"):
+        chunks.append(chunk)
+        if chunk.type == "assistant_message":
+            print(chunk.message.content[0].text)
+    print(f"Received {len(chunks)} chunks in non-streaming mode\n")
+
+    print("=== Comparing Performance ===")
+
+    # Time streaming
+    start = time.time()
+    runner_streaming = Runner(agent, streaming=True)
+    chunks = []
+    async for chunk in runner_streaming.run("What is 2+2?"):
+        chunks.append(chunk)
+    streaming_time = time.time() - start
+
+    # Time non-streaming
+    start = time.time()
+    runner_non_streaming = Runner(agent, streaming=False)
+    chunks = []
+    async for chunk in runner_non_streaming.run("What is 3+3?"):
+        chunks.append(chunk)
+    non_streaming_time = time.time() - start
+
+    print(f"Streaming mode: {streaming_time:.2f}s")
+    print(f"Non-streaming mode: {non_streaming_time:.2f}s")
+
+    print("\n=== Usage Guide ===")
+    print("To use non-streaming mode:")
+    print("  runner = Runner(agent, streaming=False)")
+    print("To use streaming mode (default):")
+    print("  runner = Runner(agent, streaming=True)  # or just Runner(agent)")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())