Padwan-LLM: A Minimalist Unified Client for Multi-Provider LLMs

Padwan-LLM is a lightweight Python client built on niquests, designed to address the problem of varying API interfaces across different large language model providers. It supports unified calls to multiple models including OpenAI, Gemini, Mistral, and Grok. Its design philosophy focuses on simplicity and unification—relying only on the niquests library while offering rich features like streaming output, tool calling, and MCP protocol support, making it suitable for embedding into various Python applications.

Against the backdrop of the booming development of large language models, developers face the challenge of significant differences in API interfaces across providers and the need for extensive adaptation code when switching or integrating. Padwan-LLM emerged to address this, with simplicity and unification as its core design principles: built on niquests (a modern alternative to requests, natively supporting HTTP/2 and HTTP/3), it has only one runtime dependency yet covers features like streaming output, tool calling, and MCP protocol support. Its lightweight nature makes it easy to embed into applications.

The core of Padwan-LLM is the LLMClient class, which encapsulates the interaction details of different providers' APIs. Developers can specify a model name, and the client will automatically identify the provider and format the request (e.g., gpt-4o corresponds to OpenAI, gemini-2.5-flash corresponds to Gemini). It supports asynchronous programming (async/await syntax) for efficient concurrent calls; the stream_chat method enables streaming output, allowing real-time reception of generated content to optimize user experience.

• Conversation State Management: The built-in ConversationState class allows setting system prompts, adding user messages, accumulating assistant responses, and automatically tracking token usage. It supports persisting conversation history via the ConversationStore protocol, enabling the insertion of custom storage backends.
• Tool Calling: The AgentSession class implements multi-turn conversation tool calling, supporting sequential/parallel execution modes. It provides approval hooks (manual/auto review before execution) and independent error handlers to ensure robustness in production environments.

• MCP Protocol: Natively supports the Model Context Protocol open standard, providing two transmission methods: HTTP streaming (McpStreamable class, supporting Bearer Token authentication) and stdio local process transmission (McpStdio class), enabling seamless integration with external tools (e.g., weather queries, database access).
• Gemini Chain of Thought: For Google Gemini models, it supports the chain-of-thought feature. Via the on_thought callback, it receives and processes the model's internal thinking process, enhancing the transparency and interpretability of AI decisions and helping optimize prompts.

• Command-Line Tool: Offers terminal interaction functionality, supporting API key configuration via environment variables and the -m parameter to specify models; can be run quickly with uvx (zero dependencies), lowering the barrier to try.
• Testing Strategy: Unit tests do not require real API keys by default (relying on abstract design and simulation mechanisms); end-to-end tests need API keys, supporting input via .env files or command-line parameters, and automatically skipping tests for providers without configured keys—ensuring code quality and facilitating development for contributors.

Padwan-LLM is suitable for various scenarios: rapid prototyping for individual developers (minimalist API + rich examples), multi-model support for enterprise applications (abstracting underlying differences to reduce maintenance costs), and AI agents/automated workflows (AgentSession + MCP provide basic capabilities). The accompanying padwan-cli package offers interactive CLI and TUI interfaces, allowing users to choose between fine-grained control via the underlying client or quick interaction via the high-level CLI based on their needs.