infinity_llm_client 0.1.0__py3-none-any.whl

infinity_llm_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: infinity_llm_client
+Version: 0.1.0
+Summary: 强类型、可扩展的 LLM 异步客户端库，支持 OpenAI 兼容 API、流式对话、工具调用与多模型消息格式
+Author: infinity_system: yin_bailiang
+License: MIT
+Project-URL: Repository, https://github.com/yinbailiang/infinity_llm
+Keywords: llm,openai,async,asyncio,function-calling,tool-calling,streaming,chat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: pydantic
+Requires-Dist: aiohttp
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Provides-Extra: dev
+Requires-Dist: interrogate; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: infinity_llm_client[test]; extra == "dev"
+Dynamic: license-file
+
+# InfinityLLM — Async LLM Client
+
+[![Test](https://github.com/yinbailiang/infinity_llm/actions/workflows/test.yml/badge.svg)](https://github.com/yinbailiang/infinity_llm/actions/workflows/test.yml)
+[![Pyright](https://img.shields.io/badge/pyright-strict-blue)](ENGINEERING.md)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+[![Supported Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/infinity_llm/)
+
+**强类型、可扩展的 LLM 异步客户端库 — 支持 OpenAI 兼容 API、流式对话、工具调用。**
+
+## ✨ Features
+
+| 类别 | 能力 |
+| - | - |
+| 类型安全 | Pydantic 负载校验 · pyright **strict** |
+| 多 Provider | 工厂注册模式，轻松扩展新 LLM 服务商 |
+| OpenAI 兼容 | 完整实现 OpenAI Chat Completions 流式 API |
+| 工具调用 | ToolRegistry 自动从 Python 函数推断 Tool Schema |
+| 流式对话 | `stream_chat()` 异步生成器，支持 Text / ToolCall / Usage chunk |
+| 多模态消息 | 文本 + 图片 URL 混合内容 |
+| 连接管理 | 指数退避重试 + 抖动 + 连接池复用 |
+
+## 📦 Installation
+
+```bash
+pip install infinity_llm
+```
+
+## 🚀 Quick Start
+
+```python
+from llm import (
+    Message, Messages,
+    OpenAIConfig, create_client,
+    ToolRegistry,
+)
+
+# 创建客户端
+config = OpenAIConfig(
+    model="gpt-4o-mini",
+    api_key="sk-...",
+)
+client = create_client(config)
+
+# 流式对话
+messages = Messages([
+    Message.system("你是一个有用的助手"),
+    Message.user("你好"),
+])
+
+async with client:
+    async for chunk in client.stream_chat(messages):
+        print(chunk)
+```
+
+## 🧱 Architecture
+
+```
+llm/
+├── clients/          # 客户端抽象 + provider 实现
+│   ├── base.py       #   LLMClient 抽象基类
+│   ├── config.py     #   ConnectionConfig / LLMConfig
+│   ├── exceptions.py #   异常层级
+│   ├── provider.py   #   工厂注册表
+│   └── open_ai/      #   OpenAI 兼容实现
+├── models/           # 消息 / Chunk / 工具定义
+│   ├── messages.py   #   Message, Messages, ToolCall
+│   ├── chunks.py     #   StreamChunk 子类
+│   └── tools.py      #   ToolDefinition, ParameterProperty
+└── tools/            # 工具注册与类型推断
+    ├── registry.py   #   ToolRegistry
+    └── introspection.py  #   函数 → ToolDefinition 自动推断
+```
+
+## 📄 License
+
+MIT

infinity_llm_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+infinity_llm_client-0.1.0.dist-info/licenses/LICENSE.md,sha256=MIiitE-EgxYub_R0ZQO4inTK5vTV8DqV-2NNuT29axE,1074
+llm/__init__.py,sha256=hEi-pnBtjNyLWiiZ_9QtMBTHOGxjcgBmUb9mqMK2GXo,1065
+llm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm/clients/__init__.py,sha256=aJ0P2ArkKhBM_rl0r-drmIaeRSxoyYFIRh0tzwKWHdI,1356
+llm/clients/base.py,sha256=xqNhzoRVKPWhwEWeHgBgRFjFirKR1GyYF7ah0n-nUI4,2125
+llm/clients/config.py,sha256=NjodJ7s15tz1MVEOjg3yCEb2mMpZD23Pr3Aj6GmWJpA,1281
+llm/clients/exceptions.py,sha256=BwCrWqlJDP1NllLk4O5gZQZVTTOT2QEGp7Vpioe5T98,2852
+llm/clients/provider.py,sha256=Amr_KTlNVoJyENAv7NYxO6HH1JWGBIsis8w43dyI1F0,1066
+llm/clients/open_ai/__init__.py,sha256=9guvJ2sMe39_XD_gqJg0kIbqlEKzC-eY3-PUl9E-2Qw,622
+llm/clients/open_ai/aggregation.py,sha256=1Nm7TDL4esbtrY6dYm5_8MQH9wlX9pygMnO9Q42x9Wk,2096
+llm/clients/open_ai/client.py,sha256=qPmm1qzNd37Tqt2AWyU9jZlmK7wGMXrgGxK3BcrvWN0,8422
+llm/clients/open_ai/config.py,sha256=nRczIlCsjKn5VYlmkCC-gY7VCrkTPl5kC3TsxnZnc_Q,1050
+llm/clients/open_ai/connection.py,sha256=21jCIDmapwQlhqcmEbjjku_B7NWaVrrDWwLuc-TF-lA,5944
+llm/clients/open_ai/open_ai_models.py,sha256=-P9nR0t6uAvtbewruPdSX4RBP5km-WLc2fhBvbcXohU,5352
+llm/clients/open_ai/response_format.py,sha256=kaGkcn4BRiBULBJ8Y3ZtyxXZp6VIBtftcnkc6HI7Nj0,1333
+llm/models/__init__.py,sha256=XOilrS5S02VNIjhf1_YtQ-tpNmn5FG4aJXdiE-SbhT0,1031
+llm/models/chunks.py,sha256=3srBgqfaqKZ4MUAT8zccBDNtC8f2Zc8nNWxkTaC3SRY,1085
+llm/models/messages.py,sha256=masAosZcpcTk2wXobaQjpCq0qmq-d7VAYOKjbh-kkrE,5059
+llm/models/tools.py,sha256=Yh38k0aImLgbuYBbxKr5sF_CchpjfI3Bm2bC-nfJDhk,8689
+llm/tools/__init__.py,sha256=Ogp3oJ6_rI5jTqjXKL2CxdTxGBDfkbdteKmbQzn6fqg,162
+llm/tools/introspection.py,sha256=XkVmWA1tXB7PtXtqwdCLzgwpQ17FhyCZgWGkLxkiQvc,14098
+llm/tools/registry.py,sha256=K8dcU2EP53WYY9v22e64XhsTvvV-3RnZc8evakOb2ok,9267
+infinity_llm_client-0.1.0.dist-info/METADATA,sha256=MlaLt91TBvlSomxVKLZ1aZBGQCSZNa2ZwYmw1OarnH4,3839
+infinity_llm_client-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+infinity_llm_client-0.1.0.dist-info/top_level.txt,sha256=TwpEQXP3b1MS9Y2XuGgRuo9-Kny507xt2HFZgJ5TSIY,4
+infinity_llm_client-0.1.0.dist-info/RECORD,,

infinity_llm_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

infinity_llm_client-0.1.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 infinity_system
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

infinity_llm_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm

llm/__init__.py

@@ -0,0 +1,60 @@
+"""LLM 模块公共 API"""
+
+__version__ = '0.1.0'
+
+from .models.chunks import (
+    DoneChunk,
+    FinishChunk,
+    StreamChunk,
+    TextChunk,
+    ToolCallCompleteChunk,
+    UsageChunk,
+    UsageStats,
+)
+from .models.messages import (
+    ContentType,
+    FunctionCall,
+    ImageUrl,
+    Message,
+    MessageContent,
+    MessageRole,
+    Messages,
+    MultiModalContent,
+    ToolCall,
+)
+from .models.tools import (
+    ParameterProperty,
+    ToolDefinition,
+    ToolDefinitions,
+    ToolFunction,
+    ToolParameters,
+)
+
+__all__ = [
+    '__version__',
+    # -- 消息 --
+    'Message',
+    'MessageRole',
+    'Messages',
+    'MessageContent',
+    'ContentType',
+    'MultiModalContent',
+    'ImageUrl',
+    # -- 工具调用 --
+    'ToolCall',
+    'FunctionCall',
+    # -- 工具定义 --
+    'ToolDefinition',
+    'ToolDefinitions',
+    'ToolFunction',
+    'ToolParameters',
+    'ParameterProperty',
+    # -- 流式 Chunk --
+    'StreamChunk',
+    'TextChunk',
+    'ToolCallCompleteChunk',
+    'UsageChunk',
+    'FinishChunk',
+    'DoneChunk',
+    'UsageStats',
+]

llm/clients/__init__.py

@@ -0,0 +1,63 @@
+from ..models import (
+    DoneChunk,
+    FinishChunk,
+    StreamChunk,
+    TextChunk,
+    ToolCallCompleteChunk,
+    UsageChunk,
+    UsageStats,
+)
+from .base import LLMClient
+from .config import ConnectionConfig, LLMConfig
+from .exceptions import (
+    LLMAuthError,
+    LLMConfigError,
+    LLMContentFilterError,
+    LLMContextLengthError,
+    LLMError,
+    LLMHTTPError,
+    LLMInsufficientBalanceError,
+    LLMNetworkError,
+    LLMRateLimitError,
+    LLMRequestError,
+    LLMServerError,
+    LLMStreamError,
+    build_http_error,
+)
+from .open_ai import OpenAIConfig
+from .provider import create_client, register_client
+
+__all__: list[str] = [
+    # -- 客户端 --
+    'LLMClient',
+    # -- 配置 --
+    'ConnectionConfig',
+    'LLMConfig',
+    'create_client',
+    'register_client',
+    # -- provider 配置 --
+    'OpenAIConfig',
+    # -- 流式 Chunk --
+    'StreamChunk',
+    'TextChunk',
+    'ToolCallCompleteChunk',
+    'UsageChunk',
+    'FinishChunk',
+    'DoneChunk',
+    'UsageStats',
+    # -- 异常 --
+    'LLMError',
+    'LLMConfigError',
+    'LLMRequestError',
+    'LLMNetworkError',
+    'LLMHTTPError',
+    'LLMAuthError',
+    'LLMInsufficientBalanceError',
+    'LLMRateLimitError',
+    'LLMServerError',
+    'LLMContentFilterError',
+    'LLMContextLengthError',
+    'LLMStreamError',
+    # -- 工具函数 --
+    'build_http_error',
+]

llm/clients/base.py

@@ -0,0 +1,78 @@
+"""LLM 客户端抽象基类"""
+
+import types
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Optional
+
+from ..models import (
+    Message,
+    Messages,
+    StreamChunk,
+    TextChunk,
+    ToolCall,
+    ToolCallCompleteChunk,
+    ToolDefinitions,
+)
+
+
+class LLMClient(ABC):
+    """LLM 客户端抽象基类"""
+
+    @abstractmethod
+    async def __aenter__(self) -> 'LLMClient':
+        """支持 async with 资源管理"""
+        ...
+
+    @abstractmethod
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[types.TracebackType],
+    ) -> Optional[bool]: ...
+
+    # ---------- 核心对话接口 ----------
+
+    @abstractmethod
+    def stream_chat(
+        self,
+        messages: Messages,
+        tools: Optional[ToolDefinitions] = None,
+    ) -> AsyncGenerator[StreamChunk, None]:
+        """
+        流式对话接口
+
+        :param messages: 消息列表
+        :param tools: 工具列表
+        :yield: StreamChunk 子类实例，调用方通过 isinstance 分支处理
+        :raise: LLMError
+        """
+        ...
+
+    # ---------- 工具方法 ----------
+
+    @staticmethod
+    def chunks_to_message(chunks: list[StreamChunk]) -> Message:
+        """
+        将流式 chunks 聚合为一条完整的 assistant Message
+
+        遍历所有 chunk，拼接文本内容并收集工具调用，
+        最终产出一条可直接追加到对话历史的 assistant 消息。
+
+        :param chunks: 完整的流式 chunk 列表
+        :return: role=assistant 的 Message
+        """
+        text_parts: list[str] = []
+        tool_calls: list[ToolCall] = []
+
+        for chunk in chunks:
+            if isinstance(chunk, TextChunk):
+                text_parts.append(chunk.text)
+            elif isinstance(chunk, ToolCallCompleteChunk):
+                tool_calls.extend(chunk.tool_calls)
+
+        content = ''.join(text_parts) if text_parts else None
+        return Message.assistant(
+            content=content,
+            tool_calls=tool_calls if tool_calls else None,
+        )

llm/clients/config.py

@@ -0,0 +1,28 @@
+"""LLM 客户端配置模型与工厂"""
+
+from pydantic import BaseModel, Field
+
+
+class ConnectionConfig(BaseModel):
+    """HTTP 连接配置"""
+
+    timeout: float = Field(default=60.0, gt=0, description='请求读超时（秒）')
+    connect_timeout: float = Field(default=10.0, gt=0, description='连接超时（秒）')
+
+    max_retries: int = Field(default=3, ge=0, description='最大重试次数（0 表示不重试）')
+    base_delay: float = Field(default=1.0, gt=0, description='基础退避延迟（秒）')
+    max_delay: float = Field(default=30.0, gt=0, description='退避延迟上限（秒）')
+    jitter: bool = Field(default=True, description='是否启用 ±25% 随机抖动')
+    retryable_status: frozenset[int] = Field(
+        default=frozenset({429, 500, 502, 503, 504}),
+        description='可触发重试的 HTTP 状态码集合',
+    )
+
+
+class LLMConfig(BaseModel):
+    """LLM 客户端通用配置基类"""
+
+    provider: str = Field(description='服务提供商标识（如 openai）')
+    model: str = Field(description='模型名称')
+    include_usage: bool = Field(default=True, description='是否请求 token 使用统计')
+    connection: ConnectionConfig = Field(default_factory=ConnectionConfig, description='HTTP 连接与重试配置')

llm/clients/exceptions.py

@@ -0,0 +1,129 @@
+"""LLM 通用异常层级"""
+
+from typing import Optional
+
+
+class LLMError(Exception):
+    """LLM 基础异常"""
+
+    pass
+
+
+class LLMConfigError(LLMError):
+    """配置/注册错误"""
+
+    pass
+
+
+class LLMRequestError(LLMError):
+    """LLM 请求失败的基类"""
+
+    def __init__(
+        self,
+        message: str,
+        original_error: Optional[Exception] = None,
+        status_code: Optional[int] = None,
+        response_body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.original_error = original_error
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class LLMNetworkError(LLMRequestError):
+    """网络层错误：连接失败、超时、DNS 解析等"""
+
+    pass
+
+
+class LLMHTTPError(LLMRequestError):
+    """HTTP 响应状态码非 200 的错误（基类）"""
+
+    pass
+
+
+class LLMAuthError(LLMHTTPError):
+    """认证失败：401 或 403"""
+
+    pass
+
+
+class LLMInsufficientBalanceError(LLMHTTPError):
+    """余额不足：402"""
+
+    pass
+
+
+class LLMRateLimitError(LLMHTTPError):
+    """速率限制：429"""
+
+    pass
+
+
+class LLMServerError(LLMHTTPError):
+    """服务端错误：5xx"""
+
+    pass
+
+
+class LLMContentFilterError(LLMHTTPError):
+    """内容安全过滤"""
+
+    pass
+
+
+class LLMContextLengthError(LLMHTTPError):
+    """上下文长度超出模型限制"""
+
+    pass
+
+
+class LLMStreamError(LLMRequestError):
+    """流式响应解析错误"""
+
+    pass
+
+
+def build_http_error(
+    status_code: int,
+    message: Optional[str] = None,
+    original_error: Optional[Exception] = None,
+    response_body: Optional[str] = None,
+) -> LLMHTTPError:
+    """根据 HTTP 状态码构建对应的异常实例。"""
+    if message is None:
+        message = f'HTTP {status_code}'
+
+    if status_code in (401, 403):
+        return LLMAuthError(
+            message=message,
+            status_code=status_code,
+            original_error=original_error,
+            response_body=response_body,
+        )
+    elif status_code == 402:
+        return LLMInsufficientBalanceError(
+            message=message, status_code=status_code, original_error=original_error, response_body=response_body
+        )
+    elif status_code == 429:
+        return LLMRateLimitError(
+            message=message,
+            status_code=status_code,
+            original_error=original_error,
+            response_body=response_body,
+        )
+    elif 500 <= status_code < 600:
+        return LLMServerError(
+            message=message,
+            status_code=status_code,
+            original_error=original_error,
+            response_body=response_body,
+        )
+    else:
+        return LLMHTTPError(
+            message=message,
+            status_code=status_code,
+            original_error=original_error,
+            response_body=response_body,
+        )

llm/clients/open_ai/__init__.py

@@ -0,0 +1,27 @@
+from .aggregation import aggregate_tool_call_deltas
+from .client import OpenAIClient
+from .config import OpenAIConfig, create_openai_client
+from .connection import ConnectionManager
+from .open_ai_models import (
+    Choice,
+    CompletionUsage,
+    Delta,
+    StreamEvent,
+    ToolCallDelta,
+)
+from .response_format import JsonSchema, ResponseFormat
+
+__all__ = [
+    'OpenAIClient',
+    'OpenAIConfig',
+    'create_openai_client',
+    'ConnectionManager',
+    'aggregate_tool_call_deltas',
+    'ResponseFormat',
+    'JsonSchema',
+    'Choice',
+    'CompletionUsage',
+    'Delta',
+    'StreamEvent',
+    'ToolCallDelta',
+]

llm/clients/open_ai/aggregation.py

@@ -0,0 +1,63 @@
+"""OpenAI 流式 tool_calls 增量片段的聚合工具"""
+
+import json
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from ...models import FunctionCall, ToolCall
+from .open_ai_models import ToolCallDelta
+
+
+class _PendingToolCall(BaseModel):
+    """工具调用聚合过程中的暂存状态"""
+
+    id: Optional[str] = Field(default=None, description='工具调用唯一标识符')
+    function_name: Optional[str] = Field(default=None, description='函数名称')
+    function_arguments: str = Field(default='', description='已拼接的 JSON 参数字符串')
+
+
+def aggregate_tool_call_deltas(
+    tool_call_deltas: List[ToolCallDelta],
+) -> List[ToolCall]:
+    """
+    将流式 tool_calls 增量片段聚合为完整的 ToolCall 列表。
+
+    OpenAI 流式协议中，每个 tool_call delta 包含 index 字段，
+    同一 index 的多个 delta 需要拼接 arguments 字符串后解析为 dict。
+    """
+    pending: Dict[int, _PendingToolCall] = {}
+    for tc in tool_call_deltas:
+        idx: int = tc.index
+        if idx not in pending:
+            pending[idx] = _PendingToolCall()
+        entry = pending[idx]
+        if tc.id:
+            entry.id = tc.id
+        func = tc.function
+        if func is not None:
+            if func.name:
+                entry.function_name = func.name
+            entry.function_arguments += func.arguments
+
+    result: List[ToolCall] = []
+    for idx in sorted(pending):
+        entry = pending[idx]
+        tool_id: Optional[str] = entry.id
+        tool_name: Optional[str] = entry.function_name
+        if tool_id is None or tool_name is None:
+            continue
+        try:
+            arguments: Dict[str, object] = json.loads(entry.function_arguments) if entry.function_arguments else {}
+        except json.JSONDecodeError:
+            arguments = {}
+        result.append(
+            ToolCall(
+                id=tool_id,
+                function=FunctionCall(
+                    name=tool_name,
+                    arguments=arguments,
+                ),
+            )
+        )
+    return result