Merge branch 'andrewyng:main' into main

Author: tavinashb

README.md

@@ -1,40 +1,53 @@
-# aisuite
+#  aisuite
 
 [![PyPI](https://img.shields.io/pypi/v/aisuite)](https://pypi.org/project/aisuite/)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-Simple, unified interface to multiple Generative AI providers.
+`aisuite` is a lightweight Python library that provides a **unified API for working with multiple Generative AI providers**.  
+It offers a consistent interface for models from *OpenAI, Anthropic, Google, Hugging Face, AWS, Cohere, Mistral, Ollama*, and others—abstracting away SDK differences, authentication details, and parameter variations.  
+Its design is modeled after OpenAI’s API style, making it instantly familiar and easy to adopt.
 
-`aisuite` makes it easy for developers to interact with multiple Gen-AI services through a standardized interface. Using an interface similar to OpenAI's, `aisuite` supports **chat completions** and **audio transcription**, making it easy to work with the most popular AI providers and compare results. It is a thin wrapper around python client libraries, and allows creators to seamlessly swap out and test different providers without changing their code.
+`aisuite` lets developers build and **run LLM-based or agentic applications across providers** with minimal setup.  
+While it’s not a full-blown agents framework, it includes simple abstractions for creating standalone, lightweight agents.  
+It’s designed for low learning curve — so you can focus on building AI systems, not integrating APIs.
 
-All of the top providers are supported.
-Sample list of supported providers include - Anthropic, AWS, Azure, Cerebras, Cohere, Google, Groq, HuggingFace, Ollama, Mistral, OpenAI, Sambanova, Watsonx and others.
+---
 
-To maximize stability, `aisuite` uses either the HTTP endpoint or the SDK for making calls to the provider.
+## Key Features
+
+`aisuite` is designed to eliminate the complexity of working with multiple LLM providers while keeping your code simple and portable. Whether you're building a chatbot, an agentic application, or experimenting with different models, `aisuite` provides the abstractions you need without getting in your way.
+
+* **Unified API for multiple model providers** – Write your code once and run it with any supported provider. Switch between OpenAI, Anthropic, Google, and others with a single parameter change.
+* **Easy agentic app or agent creation** – Build multi-turn agentic applications using a single parameter `max_turns`. No need to manually manage tool execution loops.
+* **Pass Tool calls easily** – Pass real Python functions instead of JSON specs; aisuite handles schema generation and execution automatically.
+* **MCP tools** – Connect to MCP-based tools without writing boilerplate; aisuite handles connection, schema and execution seamlessly.
+* **Modular and extensible provider architecture** – Add support for new providers with minimal code. The plugin-style architecture makes extensions straightforward.
+
+---
 
 ## Installation
 
 You can install just the base `aisuite` package, or install a provider's package along with `aisuite`.
 
-This installs just the base package without installing any provider's SDK.
+Install just the base package without any provider SDKs:
 
 ```shell
 pip install aisuite
 ```
 
-This installs aisuite along with anthropic's library.
+Install aisuite with a specific provider (e.g., Anthropic):
 
 ```shell
 pip install 'aisuite[anthropic]'
 ```
 
-This installs all the provider-specific libraries
+Install aisuite with all provider libraries:
 
 ```shell
 pip install 'aisuite[all]'
 ```
 
-## Set up
+## Setup
 
 To get started, you will need API Keys for the providers you intend to use. You'll need to
 install the provider-specific library either separately or when installing aisuite.
@@ -76,52 +89,44 @@ for model in models:
 
 Note that the model name in the create() call uses the format - `<provider>:<model-name>`.
 `aisuite` will call the appropriate provider with the right parameters based on the provider value.
-For a list of provider values, you can look at the directory - `aisuite/providers/`. The list of supported providers are of the format - `<provider>_provider.py` in that directory. We welcome  providers adding support to this library by adding an implementation file in this directory. Please see section below for how to contribute.
+For a list of provider values, you can look at the directory - `aisuite/providers/`. The list of supported providers are of the format - `<provider>_provider.py` in that directory. We welcome providers to add support to this library by adding an implementation file in this directory. Please see section below for how to contribute.
 
 For more examples, check out the `examples` directory where you will find several notebooks that you can run to experiment with the interface.
 
-## Adding support for a provider
-
-We have made easy for a provider or volunteer to add support for a new platform.
-
-### Naming Convention for Provider Modules
-
-We follow a convention-based approach for loading providers, which relies on strict naming conventions for both the module name and the class name. The format is based on the model identifier in the form `provider:model`.
-
-- The provider's module file must be named in the format `<provider>_provider.py`.
-- The class inside this module must follow the format: the provider name with the first letter capitalized, followed by the suffix `Provider`.
-
-#### Examples
+---
 
-- **Hugging Face**:
-  The provider class should be defined as:
+## Chat Completions
 
-  ```python
-  class HuggingfaceProvider(BaseProvider)
-  ```
+The chat API provides a high-level abstraction for model interactions. It supports all core parameters (`temperature`, `max_tokens`, `tools`, etc.) in a provider-agnostic way.
 
-  in providers/huggingface_provider.py.
-  
-- **OpenAI**:
-  The provider class should be defined as:
-
-  ```python
-  class OpenaiProvider(BaseProvider)
-  ```
+```python
+response = client.chat.completions.create(
+    model="google:gemini-pro",
+    messages=[{"role": "user", "content": "Summarize this paragraph."}],
+)
+print(response.choices[0].message.content)
+```
 
-  in providers/openai_provider.py
+`aisuite` standardizes request and response structures so you can focus on logic rather than SDK differences.
 
-This convention simplifies the addition of new providers and ensures consistency across provider implementations.
+---
 
-## Tool Calling
+## Tool Calling & Agentic apps
 
 `aisuite` provides a simple abstraction for tool/function calling that works across supported providers. This is in addition to the regular abstraction of passing JSON spec of the tool to the `tools` parameter. The tool calling abstraction makes it easy to use tools with different LLMs without changing your code.
 
 There are two ways to use tools with `aisuite`:
 
 ### 1. Manual Tool Handling
 
-This is the default behavior when `max_turns` is not specified.
+This is the default behavior when `max_turns` is not specified. In this mode, you have full control over the tool execution flow. You pass tools using the standard OpenAI JSON schema format, and `aisuite` returns the LLM's tool call requests in the response. You're then responsible for executing the tools, processing results, and sending them back to the model in subsequent requests.
+
+This approach is useful when you need:
+- Fine-grained control over tool execution logic
+- Custom error handling or validation before executing tools
+- The ability to selectively execute or skip certain tool calls
+- Integration with existing tool execution pipelines
+
 You can pass tools in the OpenAI tool format:
 
 ```python
@@ -200,156 +205,108 @@ When `max_turns` is specified, `aisuite` will:
 3. Send the tool results back to the LLM
 4. Repeat until the conversation is complete or max_turns is reached
 
-In addition to `response.choices[0].message`, there is an additional field `response.choices[0].intermediate_messages`: which contains the list of all messages including tool interactions used. This can be used to continue the conversation with the model.
+In addition to `response.choices[0].message`, there is an additional field `response.choices[0].intermediate_messages` which contains the list of all messages including tool interactions used. This can be used to continue the conversation with the model.
 For more detailed examples of tool calling, check out the `examples/tool_calling_abstraction.ipynb` notebook.
 
-## Audio Transcription
+### Model Context Protocol (MCP) Integration
 
-> **Note:** Audio transcription support is currently under development. The API and features described below are subject to change.
+`aisuite` natively supports **MCP**, a standard protocol that allows LLMs to securely call external tools and access data. You can connect to MCP servers—such as a filesystem or database—and expose their tools directly to your model.
+Read more about MCP here - https://modelcontextprotocol.io/docs/getting-started/intro
 
-`aisuite` provides audio transcription (speech-to-text) with the same unified interface pattern used for chat completions. Transcribe audio files across multiple providers with consistent code.
+Install aisuite with MCP support:
 
-### Basic Usage
-
-```python
-import aisuite as ai
-client = ai.Client()
+```shell
+pip install 'aisuite[mcp]'
+```
 
-# Transcribe an audio file
-result = client.audio.transcriptions.create(
-    model="openai:whisper-1",
-    file="meeting.mp3"
-)
-print(result.text)
+You'll also need an MCP server. For example, to use the filesystem server:
 
-# Switch providers without changing your code
-result = client.audio.transcriptions.create(
-    model="deepgram:nova-2",
-    file="meeting.mp3"
-)
-print(result.text)
+```shell
+npm install -g @modelcontextprotocol/server-filesystem
 ```
 
-### Common Parameters
+There are two ways to use MCP tools with aisuite:
 
-Use OpenAI-style parameters that work across all providers:
+#### Option 1: Config Dict Format (Recommended for Simple Use Cases)
 
 ```python
-result = client.audio.transcriptions.create(
-    model="openai:whisper-1",
-    file="interview.mp3",
-    language="en",           # Specify audio language
-    prompt="Technical discussion about AI",  # Context hints
-    temperature=0.2          # Sampling temperature (where supported)
-)
-```
+import aisuite as ai
 
-These parameters are automatically mapped to each provider's native format.
+client = ai.Client()
+response = client.chat.completions.create(
+    model="openai:gpt-4o",
+    messages=[{"role": "user", "content": "List the files in the current directory"}],
+    tools=[{
+        "type": "mcp",
+        "name": "filesystem",
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
+    }],
+    max_turns=3
+)
 
-### Provider-Specific Features
+print(response.choices[0].message.content)
+```
 
-Each provider offers unique capabilities you can access directly:
+#### Option 2: Explicit MCPClient (Recommended for Advanced Use Cases)
 
-**OpenAI Whisper:**
 ```python
-result = client.audio.transcriptions.create(
-    model="openai:whisper-1",
-    file="speech.mp3",
-    response_format="verbose_json",       # Get detailed metadata
-    timestamp_granularities=["word"]      # Word-level timestamps
-)
-```
+import aisuite as ai
+from aisuite.mcp import MCPClient
 
-**Deepgram:**
-```python
-result = client.audio.transcriptions.create(
-    model="deepgram:nova-2",
-    file="meeting.mp3",
-    punctuate=True,                       # Auto-add punctuation
-    diarize=True,                         # Identify speakers
-    sentiment=True,                       # Sentiment analysis
-    summarize=True                        # Auto-summarization
+# Create MCP client once, reuse across requests
+mcp = MCPClient(
+    command="npx",
+    args=["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
 )
-```
 
-**Google Speech-to-Text:**
-```python
-result = client.audio.transcriptions.create(
-    model="google:default",
-    file="call.mp3",
-    enable_automatic_punctuation=True,
-    enable_speaker_diarization=True,
-    diarization_speaker_count=2
+# Use with aisuite
+client = ai.Client()
+response = client.chat.completions.create(
+    model="openai:gpt-4o",
+    messages=[{"role": "user", "content": "List the files"}],
+    tools=mcp.get_callable_tools(),
+    max_turns=3
 )
-```
 
-**Hugging Face:**
-```python
-result = client.audio.transcriptions.create(
-    model="huggingface:openai/whisper-large-v3",
-    file="presentation.mp3",
-    return_timestamps="word"                  # Word-level timestamps
-)
+print(response.choices[0].message.content)
+mcp.close()  # Clean up
 ```
 
-### Streaming Transcription
+For detailed usage (security filters, tool prefixing, and `MCPClient` management), see [docs/mcp-tools.md](docs/mcp-tools.md).
+For detailed examples, see `examples/mcp_tools_example.ipynb`.
 
-For real-time or large audio files, use streaming:
+---
 
-```python
-async def transcribe_stream():
-    stream = client.audio.transcriptions.create_stream_output(
-        model="deepgram:nova-2",
-        file="long_recording.mp3"
-    )
-
-    async for chunk in stream:
-        print(chunk.text, end="", flush=True)
-        if chunk.is_final:
-            print()  # New line for final results
+## Extending aisuite: Adding a Provider
 
-# Run the async function
-import asyncio
-asyncio.run(transcribe_stream())
-```
+New providers can be added by implementing a lightweight adapter. The system uses a naming convention for discovery:
 
-### Supported Providers
+| Element         | Convention                         |
+| --------------- | ---------------------------------- |
+| **Module file** | `<provider>_provider.py`           |
+| **Class name**  | `<Provider>Provider` (capitalized) |
 
-- **OpenAI**: `whisper-1`
-- **Deepgram**: `nova-2`, `nova`, `enhanced`, `base`
-- **Google**: `default`, `latest_long`, `latest_short`
-- **Hugging Face**: `openai/whisper-large-v3`, `openai/whisper-tiny`, `facebook/wav2vec2-base-960h`, `facebook/wav2vec2-large-xlsr-53`
+Example:
 
-### Installation
+```python
+# providers/openai_provider.py
+class OpenaiProvider(BaseProvider):
+    ...
+```
 
-Install transcription providers:
+This convention ensures consistency and enables automatic loading of new integrations.
 
-```shell
-# Install with specific provider
-pip install 'aisuite[openai]'      # For OpenAI Whisper
-pip install 'aisuite[deepgram]'    # For Deepgram
-pip install 'aisuite[google]'      # For Google Speech-to-Text
-pip install 'aisuite[huggingface]' # For Hugging Face models
+---
 
-# Install all providers
-pip install 'aisuite[all]'
-```
+## Contributing
 
-Set API keys:
+Contributions are welcome. Please review the [Contributing Guide](https://github.com/andrewyng/aisuite/blob/main/CONTRIBUTING.md) and join our [Discord](https://discord.gg/T6Nvn8ExSb) for discussions.
 
-```shell
-export OPENAI_API_KEY="your-openai-api-key"
-export DEEPGRAM_API_KEY="your-deepgram-api-key"
-export GOOGLE_APPLICATION_CREDENTIALS="path/to/credentials.json"
-export HF_TOKEN="your-huggingface-token"
-```
-
-For more examples and advanced usage, check out `examples/asr_example.ipynb`.
+---
 
 ## License
 
-aisuite is released under the MIT License. You are free to use, modify, and distribute the code for both commercial and non-commercial purposes.
-
-## Contributing
+Released under the **MIT License** — free for commercial and non-commercial use.
 
-If you would like to contribute, please read our [Contributing Guide](https://github.com/andrewyng/aisuite/blob/main/CONTRIBUTING.md) and join our [Discord](https://discord.gg/T6Nvn8ExSb) server!
+---