padwan-llm：轻量级多提供商统一的LLM客户端

介绍padwan-llm项目，一个基于niquests构建的极简Python LLM客户端，支持OpenAI、Gemini、Mistral、Grok等多个提供商，内置MCP工具支持和推理模型流式输出。

随着大语言模型（LLM）生态的蓬勃发展，开发者在实际项目中常常面临一个尴尬的局面：不同的模型提供商有着各自独立的SDK和API规范。OpenAI有openai库，Google Gemini有google-genai，Mistral和Grok也各有其道。这种碎片化带来了几个问题：

首先，代码的可移植性受到严重限制。一个为OpenAI编写的应用，如果要切换到Gemini，往往需要重写大量调用代码。其次，依赖管理变得复杂，每个SDK都可能引入自己的依赖树，增加项目的体积和潜在冲突。最后，学习成本也随之上升，开发者需要熟悉多套不同的API设计风格。

padwan-llm项目正是为了解决这些痛点而生。它提供了一个统一的、极简的Python客户端，让开发者可以用一致的接口与多个LLM提供商交互，同时保持轻量级的依赖 footprint。

padwan-llm的设计哲学可以概括为三个关键词：极简、统一、现代。

极简：项目只有一个运行时依赖——niquests。这是一个现代化的Python HTTP客户端，支持HTTP/2和HTTP/3协议协商，相比传统的requests库更加高效。

统一：无论底层是OpenAI、Gemini、Mistral还是Grok，开发者使用相同的API模式进行调用。这种抽象层屏蔽了底层差异，让代码更加可维护。

现代：项目充分利用了Python的异步特性（async/await），所有主要接口都支持异步调用，适合构建高性能的并发应用。同时，它也原生支持流式输出、工具调用、MCP协议等前沿特性。

padwan-llm内置支持主流的LLM提供商：

• OpenAI：包括GPT-4、GPT-4o、GPT-4o-mini等全系列模型
• Google Gemini：支持Gemini Pro、Flash等模型
• Mistral AI：支持Mistral系列模型
• Grok：xAI的Grok模型
• OpenAI兼容API：通过OpenAIClient配合自定义base_url，可以支持Groq、Together AI、Ollama、vLLM等任何兼容OpenAI API格式的服务

提供商的识别是自动的，基于模型名称的前缀或环境变量中的API密钥。例如，以"gpt-"开头的模型会自动路由到OpenAI，以"gemini-"开头的会路由到Gemini。

所有核心操作都支持异步模式，这对于构建高并发的AI应用至关重要：

async with LLMClient(model="gpt-4o") as client:
    response, usage = await client.complete_chat(
        [{"role": "user", "content": "Hello!"}]
    )

使用async with上下文管理器确保资源的正确释放，同时支持连接池复用，提升性能。

对于长文本生成场景，流式输出可以显著提升用户体验。padwan-llm提供了简洁的流式API：

stream = client.stream_chat(state.messages)
async for text in stream:
    print(text, end="", flush=True)

流对象还会携带使用量信息（usage），方便进行成本统计和配额管理。

项目提供了ConversationState类来管理多轮对话的上下文：

state = ConversationState(system="你是一个简洁的助手。")
state.add_user_message("Python是什么？")
# 生成回复后
state.add_assistant_message(response_text)

这种设计使得维护对话历史变得简单直观，同时支持系统提示词（system prompt）的设置。

这是padwan-llm的一个亮点功能。AgentSession类实现了一个完整的ReAct（Reasoning + Acting）代理循环：

async with AgentSession(
    client=LLMClient(model="gpt-4o"),
    mcp_tools=[McpStdio(command="uvx", args=["my-mcp-server"])],
    system="你可以使用工具。在有帮助时使用它们。",
) as session:
    async for chunk in session.stream("巴黎的天气怎么样？"):
        print(chunk, end="", flush=True)

AgentSession的工作流程如下：

1. 接收用户输入
2. 调用LLM判断是否需要使用工具
3. 如果需要，执行工具调用并获取结果
4. 将工具结果反馈给LLM
5. 重复步骤2-4直到LLM给出最终文本回复
6. 返回最终答案

这种模式支持顺序或并行的工具执行，还可以通过钩子函数实现工具调用的审批机制，以及自定义的错误处理逻辑。