lite-agent 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

lite_agent/types/chunks.py

@@ -0,0 +1,89 @@
+from typing import Literal
+
+from litellm import Usage
+from litellm.types.utils import ModelResponseStream
+from pydantic import BaseModel
+
+from .messages import AssistantMessage
+
+
+class CompletionRawChunk(BaseModel):
+    """
+    Define the type of chunk
+    """
+
+    type: Literal["completion_raw"]
+    raw: ModelResponseStream
+
+
+class UsageChunk(BaseModel):
+    """
+    Define the type of usage info chunk
+    """
+
+    type: Literal["usage"]
+    usage: Usage
+
+
+class FinalMessageChunk(BaseModel):
+    """
+    Define the type of final message chunk
+    """
+
+    type: Literal["final_message"]
+    message: AssistantMessage
+    finish_reason: str | None = None  # Literal["stop", "tool_calls"]
+
+
+class ToolCallChunk(BaseModel):
+    """
+    Define the type of tool call chunk
+    """
+
+    type: Literal["tool_call"]
+    name: str
+    arguments: str
+
+
+class ToolCallResultChunk(BaseModel):
+    """
+    Define the type of tool call result chunk
+    """
+
+    type: Literal["tool_call_result"]
+    tool_call_id: str
+    name: str
+    content: str
+
+
+class ContentDeltaChunk(BaseModel):
+    """
+    Define the type of message chunk
+    """
+
+    type: Literal["content_delta"]
+    delta: str
+
+
+class ToolCallDeltaChunk(BaseModel):
+    """
+    Define the type of tool call delta chunk
+    """
+
+    type: Literal["tool_call_delta"]
+    tool_call_id: str
+    name: str
+    arguments_delta: str
+
+
+AgentChunk = CompletionRawChunk | UsageChunk | FinalMessageChunk | ToolCallChunk | ToolCallResultChunk | ContentDeltaChunk | ToolCallDeltaChunk
+
+AgentChunkType = Literal[
+    "completion_raw",
+    "usage",
+    "final_message",
+    "tool_call",
+    "tool_call_result",
+    "content_delta",
+    "tool_call_delta",
+]

lite_agent/types/messages.py

@@ -0,0 +1,68 @@
+from collections.abc import Sequence
+from typing import Literal
+
+from pydantic import BaseModel
+from rich import Any
+
+from .tool_calls import ToolCall
+
+
+class AssistantMessage(BaseModel):
+    id: str
+    index: int
+    role: Literal["assistant"] = "assistant"
+    content: str = ""
+    tool_calls: list[ToolCall] | None = None
+
+
+class Message(BaseModel):
+    role: str
+    content: str
+
+
+class UserMessageContentItemText(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class UserMessageContentItemImageURLImageURL(BaseModel):
+    url: str
+
+
+class UserMessageContentItemImageURL(BaseModel):
+    type: Literal["image_url"]
+    image_url: UserMessageContentItemImageURLImageURL
+
+
+class AgentUserMessage(BaseModel):
+    role: Literal["user"]
+    content: str | Sequence[UserMessageContentItemText | UserMessageContentItemImageURL]
+
+
+class AgentAssistantMessage(BaseModel):
+    role: Literal["assistant"]
+    content: str
+
+
+class AgentSystemMessage(BaseModel):
+    role: Literal["system"]
+    content: str
+
+
+class AgentFunctionToolCallMessage(BaseModel):
+    arguments: str
+    type: Literal["function_call"]
+    function_call_id: str
+    name: str
+    content: str
+
+
+class AgentFunctionCallOutput(BaseModel):
+    call_id: str
+    output: str
+    type: Literal["function_call_output"]
+
+
+RunnerMessage = AgentUserMessage | AgentAssistantMessage | AgentSystemMessage | AgentFunctionToolCallMessage | AgentFunctionCallOutput
+AgentMessage = RunnerMessage | AgentSystemMessage
+RunnerMessages = Sequence[RunnerMessage | dict[str, Any]]

lite_agent/types/tool_calls.py

@@ -0,0 +1,15 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ToolCallFunction(BaseModel):
+    name: str
+    arguments: str | None = None
+
+
+class ToolCall(BaseModel):
+    type: Literal["function"]
+    function: ToolCallFunction
+    id: str
+    index: int

lite_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: lite-agent
+Version: 0.2.0
+Summary: A lightweight, extensible framework for building AI agent.
+Author-email: Jianqi Pan <jannchie@gmail.com>
+License: MIT
+Keywords: AI,agent framework,assistant,chatbot,function call,openai,pydantic,rich,tooling
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: funcall>=0.7.0
+Requires-Dist: prompt-toolkit>=3.0.51
+Requires-Dist: rich>=14.0.0
+Description-Content-Type: text/markdown
+
+# LiteAgent
+
+[![codecov](https://codecov.io/gh/Jannchie/lite-agent/graph/badge.svg?token=SJW89Z1VAZ)](https://codecov.io/gh/Jannchie/lite-agent)
+
+## Introduction
+
+LiteAgent is an easy-to-learn, lightweight, and extensible AI agent framework built on top of [LiteLLM](https://github.com/BerriAI/litellm). It is designed as a minimal yet practical implementation for quickly building intelligent assistants and chatbots with robust tool-calling capabilities. The codebase is intentionally simple, making it ideal for learning, extension, and rapid prototyping.
+
+**Key Advantages:**
+
+- **Minimal and approachable:** The simplest agent implementation for fast learning and hacking.
+- **Accurate and complete type hints:** All function signatures are fully type-hinted and never faked, ensuring reliable developer experience and static analysis.
+- **Flexible parameter definition:** Supports defining tool function parameters using basic types, Pydantic models, or Python dataclasses—even in combination.
+- **Streaming responses:** Seamless support for LiteLLM streaming output.
+- **Custom tool functions:** Easily integrate your own Python functions (e.g., weather, temperature queries).
+- **Rich type annotations, Pydantic-based.**
+- **Easy to extend and test.**
+
+## Installation
+
+You can install LiteAgent directly from PyPI:
+
+```bash
+pip install lite-agent
+```
+
+Or use [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv pip install lite-agent
+```
+
+If you want to install from source for development:
+
+```bash
+uv pip install -e .
+# or
+pip install -e .
+```
+
+## Quick Start
+
+### Code Example
+
+See `examples/basic.py`:
+
+```python
+import asyncio
+from lite_agent.agent import Agent
+from lite_agent.runner import Runner
+
+async def get_whether(city: str) -> str:
+    await asyncio.sleep(1)
+    return f"The weather in {city} is sunny with a few clouds."
+
+async def main():
+    agent = Agent(
+        model="gpt-4.1",
+        name="Weather Assistant",
+        instructions="You are a helpful weather assistant.",
+        tools=[get_whether],
+    )
+    runner = Runner(agent)
+    resp = await runner.run_until_complete("What's the weather in New York?")
+    for chunk in resp:
+        print(chunk)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+See `pyproject.toml` for details.
+
+## Testing
+
+```bash
+pytest
+```
+
+## License
+
+MIT License
+
+## Author
+
+Jianqi Pan ([jannchie@gmail.com](mailto:jannchie@gmail.com))

lite_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+lite_agent/__init__.py,sha256=T-jxY0aHwqPz5gs-ZzH1zvFgFdYVmOd15fnEc5A2H6U,229
+lite_agent/agent.py,sha256=UE06H1Huk4gHGovbh9DuAJAH2zC0hqf1YXgrVa59_Os,13546
+lite_agent/loggers.py,sha256=XkNkdqwD_nQGfhQJ-bBWT7koci_mMkNw3aBpyMhOICw,57
+lite_agent/message_transfers.py,sha256=nT7-tID20RK2yoN-rDiEE6sSclluSlhYSkayCzmPwk8,3984
+lite_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lite_agent/runner.py,sha256=lO8Z5R2RxjjgYzDAeYQbO2niQeieXOEzqUEN484G7QU,21367
+lite_agent/processors/__init__.py,sha256=X78GKL_IWwW2lg8w4DD6GOFWLzAR2wTfKxHlvOkcuUQ,114
+lite_agent/processors/stream_chunk_processor.py,sha256=nMA_cW7FDpXwJvm4F8vFwBXmHHsSELQFcoNEjH3xvn8,4751
+lite_agent/stream_handlers/__init__.py,sha256=2GSiG0VUgcQlFMl6JkGAqikXMII1a43Hr-J5NIct6dk,115
+lite_agent/stream_handlers/litellm.py,sha256=NNMAl8Bvoc2xe-qWKtfqvJQA2yr3sz1IUU90rQ_9iBw,3976
+lite_agent/types/__init__.py,sha256=sc2cdX1tPisfQwu2-apZtUa3u_Q6WDEqzNglfXhwCJo,1295
+lite_agent/types/chunks.py,sha256=Ro5BtrrdsYGkKrEekIhs9vIrBM7HljtgOkHherH8B3k,1697
+lite_agent/types/messages.py,sha256=cmMcj_r1_R9Pgu6ixmBIq2uwwqi5KzIllxGoxpcxF3w,1531
+lite_agent/types/tool_calls.py,sha256=Xnut8-2-Ld9vgA2GKJY6BbFlBaAv_n4W7vo7Jx21A-E,260
+lite_agent-0.2.0.dist-info/METADATA,sha256=egjWZCc9UgPAHMCJqZrjBXlXrG39f9LoW9k6DzntMas,3455
+lite_agent-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+lite_agent-0.2.0.dist-info/RECORD,,

lite_agent/__main__.py

@@ -1,110 +0,0 @@
-import asyncio
-import logging
-
-from prompt_toolkit import PromptSession
-from prompt_toolkit.validation import Validator
-from rich.console import Console
-from rich.logging import RichHandler
-
-from open_agents.agent import Agent
-from open_agents.loggers import logger
-from open_agents.runner import Runner
-from open_agents.types import AgentChunk, ContentDeltaChunk
-
-logging.basicConfig(level=logging.WARNING, handlers=[RichHandler()], format="%(message)s")
-logger.setLevel(logging.INFO)
-
-
-# --- Tool functions (English) ---
-async def get_whether(city: str) -> str:
-    """Get the weather for a city."""
-    await asyncio.sleep(1)  # 模擬網路延遲
-    return f"The weather in {city} is sunny with a few clouds."
-
-
-async def get_temperature(city: str) -> str:
-    """Get the temperature for a city."""
-    await asyncio.sleep(1)  # 模擬網路延遲
-    return f"The temperature in {city} is 25°C."
-
-
-class RichChannel:
-    def __init__(self) -> None:
-        self.console = Console()
-        self.map = {
-            "final_message": self.handle_final_message,
-            "tool_call": self.handle_tool_call,
-            "tool_call_result": self.handle_tool_call_result,
-            "tool_call_delta": self.handle_tool_call_delta,
-            "content_delta": self.handle_content_delta,
-            "usage": self.handle_usage,
-        }
-        self.new_turn = True
-
-    def handle(self, chunk: AgentChunk):
-        handler = self.map[chunk["type"]]
-        handler(chunk)
-
-    def handle_final_message(self, _chunk: AgentChunk):
-        print()
-        self.new_turn = True
-
-    def handle_tool_call(self, chunk: AgentChunk):
-        name = chunk.get("name", "<unknown>")
-        arguments = chunk.get("arguments", "")
-        self.console.print(f"🛠️  [green]{name}[/green]([yellow]{arguments}[/yellow])")
-
-    def handle_tool_call_result(self, chunk: AgentChunk):
-        name = chunk.get("name", "<unknown>")
-        content = chunk.get("content", "")
-        self.console.print(f"🛠️  [green]{name}[/green] → [yellow]{content}[/yellow]")
-
-    def handle_tool_call_delta(self, chunk: AgentChunk): ...
-    def handle_content_delta(self, chunk: ContentDeltaChunk):
-        if self.new_turn:
-            self.console.print("🤖 ", end="")
-            self.new_turn = False
-        print(chunk["delta"], end="", flush=True)
-
-    def handle_usage(self, chunk: AgentChunk):
-        if False:
-            usage = chunk["usage"]
-            self.console.print(f"In: {usage.prompt_tokens}, Out: {usage.completion_tokens}, Total: {usage.total_tokens}")
-
-
-async def main():
-    agent = Agent(
-        model="gpt-4.1",
-        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_whether, get_temperature],
-    )
-    session = PromptSession()
-    rich_channel = RichChannel()
-    runner = Runner(agent)
-    not_empty_validator = Validator.from_callable(
-        lambda text: bool(text.strip()),
-        error_message="Input cannot be empty.",
-        move_cursor_to_end=True,
-    )
-    while True:
-        try:
-            user_input = await session.prompt_async(
-                "👤 ",
-                default="",
-                complete_while_typing=True,
-                validator=not_empty_validator,
-                validate_while_typing=False,
-            )
-            if user_input.lower() in {"exit", "quit"}:
-                break
-            response = runner.run_stream(user_input)
-            async for chunk in response:
-                rich_channel.handle(chunk)
-
-        except (EOFError, KeyboardInterrupt):
-            break
-
-
-if __name__ == "__main__":
-    asyncio.run(main())

lite_agent/chunk_handler.py

@@ -1,166 +0,0 @@
-from collections.abc import AsyncGenerator
-from typing import Literal, TypedDict
-
-import litellm
-from funcall import Funcall
-
-from open_agents.loggers import logger
-from open_agents.processors import StreamChunkProcessor
-from open_agents.processors.stream_chunk_processor import AssistantMessage
-
-
-class LiteLLMRawChunk(TypedDict):
-    """
-    Define the type of chunk
-    """
-
-    type: Literal["litellm_raw"]
-    raw: litellm.ModelResponseStream
-
-
-class UsageChunk(TypedDict):
-    """
-    Define the type of usage info chunk
-    """
-
-    type: Literal["usage"]
-    usage: litellm.Usage
-
-
-class FinalMessageChunk(TypedDict):
-    """
-    Define the type of final message chunk
-    """
-
-    type: Literal["final_message"]
-    message: AssistantMessage
-    finish_reason: Literal["stop", "tool_calls"]
-
-
-class ToolCallChunk(TypedDict):
-    """
-    Define the type of tool call chunk
-    """
-
-    type: Literal["tool_call"]
-    name: str
-    arguments: str
-
-
-class ToolCallResultChunk(TypedDict):
-    """
-    Define the type of tool call result chunk
-    """
-
-    type: Literal["tool_call_result"]
-    tool_call_id: str
-    name: str
-    content: str
-
-
-class ContentDeltaChunk(TypedDict):
-    """
-    Define the type of message chunk
-    """
-
-    type: Literal["content_delta"]
-    delta: str
-
-
-class ToolCallDeltaChunk(TypedDict):
-    """
-    Define the type of tool call delta chunk
-    """
-
-    type: Literal["tool_call_delta"]
-    tool_call_id: str
-    name: str
-    arguments_delta: str
-
-
-AgentChunk = LiteLLMRawChunk | UsageChunk | FinalMessageChunk | ToolCallChunk | ToolCallResultChunk | ContentDeltaChunk
-
-
-async def chunk_handler(
-    resp: litellm.CustomStreamWrapper,
-    fc: Funcall,
-) -> AsyncGenerator[AgentChunk, None]:
-    """
-    Optimized chunk handler
-
-    Args:
-        resp: LiteLLM streaming response wrapper
-        fc: function call handler
-
-    Yields:
-        litellm.ModelResponseStream: processed response chunk
-
-    Raises:
-        Exception: various exceptions during processing
-    """
-    processor = StreamChunkProcessor(fc)
-    async for chunk in resp:
-        if not isinstance(chunk, litellm.ModelResponseStream):
-            logger.debug("unexpected chunk type: %s", type(chunk))
-            logger.debug("chunk content: %s", chunk)
-            continue
-
-        # Handle usage info
-        if usage := processor.handle_usage_info(chunk):
-            yield UsageChunk(type="usage", usage=usage)
-            continue
-
-        # Get choice and delta data
-        if not chunk.choices:
-            yield LiteLLMRawChunk(type="litellm_raw", raw=chunk)
-            continue
-
-        choice = chunk.choices[0]
-        delta = choice.delta
-        if not processor.current_message:
-            processor.initialize_message(chunk, choice)
-        if delta.content:
-            yield ContentDeltaChunk(type="content_delta", delta=delta.content)
-        processor.update_content(delta.content)
-        processor.update_tool_calls(delta.tool_calls)
-        if delta.tool_calls:
-            for tool_call in delta.tool_calls:
-                if tool_call.function.arguments:
-                    yield ToolCallDeltaChunk(
-                        type="tool_call_delta",
-                        tool_call_id=processor.current_message.tool_calls[-1].id,
-                        name=processor.current_message.tool_calls[-1].function.name,
-                        arguments_delta=tool_call.function.arguments,
-                    )
-        # Check if finished
-        if choice.finish_reason and processor.current_message:
-            current_message = processor.finalize_message()
-            yield FinalMessageChunk(type="final_message", message=current_message, finish_reason=choice.finish_reason)
-            # New: check tool_calls and handle
-            tool_calls = current_message.tool_calls
-            if tool_calls:
-                # Execute each tool_call and yield result
-                for tool_call in tool_calls:
-                    try:
-                        yield ToolCallChunk(
-                            type="tool_call",
-                            name=tool_call.function.name,
-                            arguments=tool_call.function.arguments,
-                        )
-                        content = await fc.call_function_async(tool_call.function.name, tool_call.function.arguments)
-                        yield ToolCallResultChunk(
-                            type="tool_call_result",
-                            tool_call_id=tool_call.id,
-                            name=tool_call.function.name,
-                            content=str(content),
-                        )
-                    except Exception as e:  # noqa: PERF203
-                        logger.exception("Tool call %s failed", tool_call.id)
-                        yield ToolCallResultChunk(
-                            type="tool_call_result",
-                            tool_call_id=tool_call.id,
-                            name=tool_call.function.name,
-                            content=str(e),
-                        )
-            continue
-        yield LiteLLMRawChunk(type="litellm_raw", raw=chunk)