# Metorial Python SDK
The official Python SDK for [Metorial](https://metorial.com).
## Available Providers
| Provider | Import | Format | Description |
| ---------- | --------------------- | ---------------------------- | ----------------------------- |
| OpenAI | `metorial_openai` | OpenAI function calling | GPT-4, GPT-3.5, etc. |
| Anthropic | `metorial_anthropic` | Claude tool format | Claude 3.5, Claude 3, etc. |
| Google | `metorial_google` | Gemini function declarations | Gemini Pro, Gemini Flash |
| Mistral | `metorial_mistral` | Mistral function calling | Mistral Large, Codestral |
| DeepSeek | `metorial_deepseek` | OpenAI-compatible | DeepSeek Chat, DeepSeek Coder |
| TogetherAI | `metorial_togetherai` | OpenAI-compatible | Llama, Mixtral, etc. |
| XAI | `metorial_xai` | OpenAI-compatible | Grok models |
| AI SDK | `metorial_ai_sdk` | Framework tools | Vercel AI SDK, etc. |
## Installation
```bash
# Install core metorial package (includes all provider adapters)
pip install metorial
# Install with specific providers (includes provider client libraries)
pip install metorial[openai,anthropic,google,mistral,deepseek,togetherai,xai]
# Or install individual providers
pip install metorial[openai] # Includes openai client
pip install metorial[anthropic] # Includes anthropic client
# ... etc
```
## Quick Start
```python
import asyncio
from metorial import Metorial
from openai import AsyncOpenAI
async def main():
metorial = Metorial(api_key="your-metorial-api-key")
openai_client = AsyncOpenAI(api_key="your-openai-api-key")
response = await metorial.run(
"What are the latest commits in the metorial/websocket-explorer repository?",
"your-server-deployment-id", # can also be a list
openai_client,
model="gpt-4o",
max_iterations=25
)
print("Response:", response)
asyncio.run(main())
```
That's it! `metorial.run()` automatically:
- Creates a session with your MCP server
- Formats tools for your AI provider
- Handles the execution loop
- Manages tool execution
- Returns the final response
### Synchronous Usage
For synchronous applications, use `MetorialSync`:
```python
from metorial import MetorialSync
from openai import OpenAI
metorial = MetorialSync(api_key="your-metorial-api-key")
openai_client = OpenAI(api_key="your-openai-api-key")
response = metorial.run(
"What are the latest commits in the metorial/websocket-explorer repository?",
"your-server-deployment-id", # can also be a list
openai_client,
model="gpt-4o",
max_iterations=25
)
print("Response:", response)
```
## Provider Examples
Metorial works with all major AI providers. Here are examples using `metorial.run()`:
### OpenAI (GPT-4, GPT-3.5)
```python
from metorial import Metorial
from openai import AsyncOpenAI
metorial = Metorial(api_key="your-metorial-api-key")
openai_client = AsyncOpenAI(api_key="your-openai-api-key")
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
openai_client,
model="gpt-4o"
)
```
### Anthropic (Claude)
```python
from metorial import Metorial
import anthropic
metorial = Metorial(api_key="your-metorial-api-key")
anthropic_client = anthropic.AsyncAnthropic(api_key="your-anthropic-api-key")
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
anthropic_client,
model="claude-3-5-sonnet-20241022"
)
```
### Google (Gemini)
```python
from metorial import Metorial
import google.generativeai as genai
metorial = Metorial(api_key="your-metorial-api-key")
genai.configure(api_key="your-google-api-key")
google_client = genai.GenerativeModel('gemini-pro')
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
google_client,
model="gemini-pro"
)
```
### Mistral AI
```python
from metorial import Metorial
from mistralai import AsyncMistral
metorial = Metorial(api_key="your-metorial-api-key")
mistral_client = AsyncMistral(api_key="your-mistral-api-key")
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
mistral_client,
model="mistral-large-latest"
)
```
### DeepSeek
```python
from metorial import Metorial
from openai import AsyncOpenAI
metorial = Metorial(api_key="your-metorial-api-key")
deepseek_client = AsyncOpenAI(
api_key="your-deepseek-api-key",
base_url="https://api.deepseek.com"
)
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
deepseek_client,
model="deepseek-chat"
)
```
### Together AI
```python
from metorial import Metorial
from openai import AsyncOpenAI
metorial = Metorial(api_key="your-metorial-api-key")
together_client = AsyncOpenAI(
api_key="your-together-api-key",
base_url="https://api.together.xyz/v1"
)
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
together_client,
model="meta-llama/Llama-2-70b-chat-hf"
)
```
### XAI (Grok)
```python
from metorial import Metorial
from openai import AsyncOpenAI
metorial = Metorial(api_key="your-metorial-api-key")
xai_client = AsyncOpenAI(
api_key="your-xai-api-key",
base_url="https://api.x.ai/v1"
)
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
xai_client,
model="grok-beta"
)
```
## Advanced Usage
### Session Management
For more control over the conversation flow, use session management directly:
```python
import asyncio
from metorial import Metorial, MetorialOpenAI
from openai import AsyncOpenAI
async def main():
metorial = Metorial(api_key="your-metorial-api-key")
openai_client = AsyncOpenAI(api_key="your-openai-api-key")
async def session_callback(session):
messages = [{"role": "user", "content": "What are the latest commits?"}]
for i in range(10):
# Call OpenAI with Metorial tools
response = await openai_client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=session.tools
)
choice = response.choices[0]
tool_calls = choice.message.tool_calls
if not tool_calls:
print(choice.message.content)
return
# Execute tools through Metorial
tool_responses = await session.call_tools(tool_calls)
# Add to conversation
messages.append({
"role": "assistant",
"tool_calls": [
{
"id": tc.id,
"type": tc.type,
"function": {
"name": tc.function.name,
"arguments": tc.function.arguments
}
} for tc in tool_calls
]
})
messages.extend(tool_responses)
await metorial.with_provider_session(
MetorialOpenAI.chat_completions(openai_client),
"your-deployment-id",
session_callback
)
asyncio.run(main())
```
### Streaming Responses
For real-time streaming responses:
```python
import asyncio
from metorial import Metorial, MetorialOpenAI
from metorial.types import StreamEventType
async def stream_chat():
metorial = Metorial(api_key="your-metorial-api-key")
openai_client = AsyncOpenAI(api_key="your-openai-api-key")
async def stream_action(session):
messages = [{"role": "user", "content": "What are the latest commits?"}]
async for event in metorial.stream(
openai_client, session, messages, max_iterations=10
):
if event.type == StreamEventType.CONTENT:
print(f"š¤ {event.content}", end="", flush=True)
elif event.type == StreamEventType.TOOL_CALL:
print(f"\nš§ Executing {len(event.tool_calls)} tool(s)...")
elif event.type == StreamEventType.COMPLETE:
print(f"\nā
Complete! Duration: {event.metadata.get('duration', 0):.2f}s")
elif event.type == StreamEventType.ERROR:
print(f"\nā Error: {event.error}")
break
await metorial.with_provider_session(
MetorialOpenAI.chat_completions(openai_client),
"your-deployment-id",
stream_action
)
asyncio.run(stream_chat())
```
### Batch Processing
Process multiple messages concurrently:
```python
import asyncio
async def batch_example():
metorial = Metorial(api_key="your-metorial-api-key")
openai_client = AsyncOpenAI(api_key="your-openai-api-key")
messages = [
"What are the latest commits?",
"What are the main features?",
"How do I get started?"
]
results = await metorial.batch_run(
messages,
"your-deployment-id",
openai_client,
max_iterations=25
)
for i, result in enumerate(results):
print(f"Response {i+1}: {result}")
asyncio.run(batch_example())
```
## Error Handling
```python
from metorial import MetorialAPIError
try:
response = await metorial.run(
"What are the latest commits?",
"your-deployment-id",
openai_client,
model="gpt-4o"
)
except MetorialAPIError as e:
print(f"API Error: {e.message} (Status: {e.status_code})")
except Exception as e:
print(f"Unexpected error: {e}")
```
## Examples
Check out the `examples/` directory for more comprehensive examples.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- š [Documentation](https://docs.metorial.com)
- š [GitHub Issues](https://github.com/metorial/metorial-python/issues)
- š§ [Email Support](mailto:support@metorial.com)
Raw data
{
"_id": null,
"home_page": null,
"name": "metorial",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, anthropic, chat, completions, llm, mcp, metorial, model-context-protocol, openai, sessions, tools",
"author": null,
"author_email": "Metorial Team <support@metorial.com>",
"download_url": "https://files.pythonhosted.org/packages/d4/fd/25ea8b7cbc19f67f9b1c7218acd4d8c2fcbc153ee040dff428f16b0e9d25/metorial-1.0.2.tar.gz",
"platform": null,
"description": "# Metorial Python SDK\n\nThe official Python SDK for [Metorial](https://metorial.com).\n\n## Available Providers\n\n| Provider | Import | Format | Description |\n| ---------- | --------------------- | ---------------------------- | ----------------------------- |\n| OpenAI | `metorial_openai` | OpenAI function calling | GPT-4, GPT-3.5, etc. |\n| Anthropic | `metorial_anthropic` | Claude tool format | Claude 3.5, Claude 3, etc. |\n| Google | `metorial_google` | Gemini function declarations | Gemini Pro, Gemini Flash |\n| Mistral | `metorial_mistral` | Mistral function calling | Mistral Large, Codestral |\n| DeepSeek | `metorial_deepseek` | OpenAI-compatible | DeepSeek Chat, DeepSeek Coder |\n| TogetherAI | `metorial_togetherai` | OpenAI-compatible | Llama, Mixtral, etc. |\n| XAI | `metorial_xai` | OpenAI-compatible | Grok models |\n| AI SDK | `metorial_ai_sdk` | Framework tools | Vercel AI SDK, etc. |\n\n## Installation\n\n```bash\n# Install core metorial package (includes all provider adapters)\npip install metorial\n\n# Install with specific providers (includes provider client libraries)\npip install metorial[openai,anthropic,google,mistral,deepseek,togetherai,xai]\n\n# Or install individual providers\npip install metorial[openai] # Includes openai client\npip install metorial[anthropic] # Includes anthropic client\n# ... etc\n```\n\n## Quick Start\n```python\nimport asyncio\nfrom metorial import Metorial\nfrom openai import AsyncOpenAI\n\nasync def main():\n metorial = Metorial(api_key=\"your-metorial-api-key\")\n openai_client = AsyncOpenAI(api_key=\"your-openai-api-key\")\n \n response = await metorial.run(\n \"What are the latest commits in the metorial/websocket-explorer repository?\",\n \"your-server-deployment-id\", # can also be a list\n openai_client,\n model=\"gpt-4o\",\n max_iterations=25\n )\n \n print(\"Response:\", response)\n\nasyncio.run(main())\n```\n\nThat's it! `metorial.run()` automatically:\n- Creates a session with your MCP server\n- Formats tools for your AI provider\n- Handles the execution loop\n- Manages tool execution\n- Returns the final response\n\n### Synchronous Usage\n\nFor synchronous applications, use `MetorialSync`:\n\n```python\nfrom metorial import MetorialSync\nfrom openai import OpenAI\n\nmetorial = MetorialSync(api_key=\"your-metorial-api-key\")\nopenai_client = OpenAI(api_key=\"your-openai-api-key\")\n\nresponse = metorial.run(\n \"What are the latest commits in the metorial/websocket-explorer repository?\",\n \"your-server-deployment-id\", # can also be a list\n openai_client,\n model=\"gpt-4o\",\n max_iterations=25\n)\n\nprint(\"Response:\", response)\n```\n\n## Provider Examples\n\nMetorial works with all major AI providers. Here are examples using `metorial.run()`:\n\n### OpenAI (GPT-4, GPT-3.5)\n\n```python\nfrom metorial import Metorial\nfrom openai import AsyncOpenAI\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\nopenai_client = AsyncOpenAI(api_key=\"your-openai-api-key\")\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n openai_client,\n model=\"gpt-4o\"\n)\n```\n\n### Anthropic (Claude)\n\n```python\nfrom metorial import Metorial\nimport anthropic\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\nanthropic_client = anthropic.AsyncAnthropic(api_key=\"your-anthropic-api-key\")\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\", \n anthropic_client,\n model=\"claude-3-5-sonnet-20241022\"\n)\n```\n\n### Google (Gemini)\n\n```python\nfrom metorial import Metorial\nimport google.generativeai as genai\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\ngenai.configure(api_key=\"your-google-api-key\")\ngoogle_client = genai.GenerativeModel('gemini-pro')\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n google_client,\n model=\"gemini-pro\"\n)\n```\n\n### Mistral AI\n\n```python\nfrom metorial import Metorial\nfrom mistralai import AsyncMistral\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\nmistral_client = AsyncMistral(api_key=\"your-mistral-api-key\")\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n mistral_client,\n model=\"mistral-large-latest\"\n)\n```\n\n### DeepSeek\n\n```python\nfrom metorial import Metorial\nfrom openai import AsyncOpenAI\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\ndeepseek_client = AsyncOpenAI(\n api_key=\"your-deepseek-api-key\",\n base_url=\"https://api.deepseek.com\"\n)\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n deepseek_client,\n model=\"deepseek-chat\"\n)\n```\n\n### Together AI\n\n```python\nfrom metorial import Metorial\nfrom openai import AsyncOpenAI\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\ntogether_client = AsyncOpenAI(\n api_key=\"your-together-api-key\",\n base_url=\"https://api.together.xyz/v1\"\n)\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n together_client,\n model=\"meta-llama/Llama-2-70b-chat-hf\"\n)\n```\n\n### XAI (Grok)\n\n```python\nfrom metorial import Metorial\nfrom openai import AsyncOpenAI\n\nmetorial = Metorial(api_key=\"your-metorial-api-key\")\nxai_client = AsyncOpenAI(\n api_key=\"your-xai-api-key\",\n base_url=\"https://api.x.ai/v1\"\n)\n\nresponse = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n xai_client,\n model=\"grok-beta\"\n)\n```\n\n## Advanced Usage\n\n### Session Management\n\nFor more control over the conversation flow, use session management directly:\n\n```python\nimport asyncio\nfrom metorial import Metorial, MetorialOpenAI\nfrom openai import AsyncOpenAI\n\nasync def main():\n metorial = Metorial(api_key=\"your-metorial-api-key\")\n openai_client = AsyncOpenAI(api_key=\"your-openai-api-key\")\n \n async def session_callback(session):\n messages = [{\"role\": \"user\", \"content\": \"What are the latest commits?\"}]\n \n for i in range(10):\n # Call OpenAI with Metorial tools\n response = await openai_client.chat.completions.create(\n model=\"gpt-4o\",\n messages=messages,\n tools=session.tools\n )\n \n choice = response.choices[0]\n tool_calls = choice.message.tool_calls\n \n if not tool_calls:\n print(choice.message.content)\n return\n \n # Execute tools through Metorial\n tool_responses = await session.call_tools(tool_calls)\n \n # Add to conversation\n messages.append({\n \"role\": \"assistant\",\n \"tool_calls\": [\n {\n \"id\": tc.id,\n \"type\": tc.type,\n \"function\": {\n \"name\": tc.function.name,\n \"arguments\": tc.function.arguments\n }\n } for tc in tool_calls\n ]\n })\n messages.extend(tool_responses)\n\n await metorial.with_provider_session(\n MetorialOpenAI.chat_completions(openai_client),\n \"your-deployment-id\",\n session_callback\n )\n\nasyncio.run(main())\n```\n\n### Streaming Responses\n\nFor real-time streaming responses:\n\n```python\nimport asyncio\nfrom metorial import Metorial, MetorialOpenAI\nfrom metorial.types import StreamEventType\n\nasync def stream_chat():\n metorial = Metorial(api_key=\"your-metorial-api-key\")\n openai_client = AsyncOpenAI(api_key=\"your-openai-api-key\")\n \n async def stream_action(session):\n messages = [{\"role\": \"user\", \"content\": \"What are the latest commits?\"}]\n \n async for event in metorial.stream(\n openai_client, session, messages, max_iterations=10\n ):\n if event.type == StreamEventType.CONTENT:\n print(f\"\ud83e\udd16 {event.content}\", end=\"\", flush=True)\n elif event.type == StreamEventType.TOOL_CALL:\n print(f\"\\n\ud83d\udd27 Executing {len(event.tool_calls)} tool(s)...\")\n elif event.type == StreamEventType.COMPLETE:\n print(f\"\\n\u2705 Complete! Duration: {event.metadata.get('duration', 0):.2f}s\")\n elif event.type == StreamEventType.ERROR:\n print(f\"\\n\u274c Error: {event.error}\")\n break\n \n await metorial.with_provider_session(\n MetorialOpenAI.chat_completions(openai_client),\n \"your-deployment-id\",\n stream_action\n )\n\nasyncio.run(stream_chat())\n```\n\n### Batch Processing\n\nProcess multiple messages concurrently:\n\n```python\nimport asyncio\n\nasync def batch_example():\n metorial = Metorial(api_key=\"your-metorial-api-key\")\n openai_client = AsyncOpenAI(api_key=\"your-openai-api-key\")\n \n messages = [\n \"What are the latest commits?\",\n \"What are the main features?\",\n \"How do I get started?\"\n ]\n \n results = await metorial.batch_run(\n messages,\n \"your-deployment-id\",\n openai_client,\n max_iterations=25\n )\n \n for i, result in enumerate(results):\n print(f\"Response {i+1}: {result}\")\n\nasyncio.run(batch_example())\n```\n\n## Error Handling\n\n```python\nfrom metorial import MetorialAPIError\n\ntry:\n response = await metorial.run(\n \"What are the latest commits?\",\n \"your-deployment-id\",\n openai_client,\n model=\"gpt-4o\"\n )\nexcept MetorialAPIError as e:\n print(f\"API Error: {e.message} (Status: {e.status_code})\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Examples\n\nCheck out the `examples/` directory for more comprehensive examples.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://docs.metorial.com)\n- \ud83d\udc1b [GitHub Issues](https://github.com/metorial/metorial-python/issues)\n- \ud83d\udce7 [Email Support](mailto:support@metorial.com)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Metorial - The open source integration platform for agentic AI",
"version": "1.0.2",
"project_urls": {
"Changelog": "https://github.com/metorial/metorial-python/blob/main/CHANGELOG.md",
"Documentation": "https://metorial.com/docs",
"Homepage": "https://metorial.com",
"Repository": "https://github.com/metorial/metorial-python"
},
"split_keywords": [
"ai",
" anthropic",
" chat",
" completions",
" llm",
" mcp",
" metorial",
" model-context-protocol",
" openai",
" sessions",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "be76fcfdfa1b2e73337d411944b2ac84d492baaf301ee7a68d5ed3e2b49ebac0",
"md5": "639fff8f177962058d83e462ac863813",
"sha256": "9c07abdd10088f802e191ced2773f59979eba3cf905dc8c9e2a85396e78005a3"
},
"downloads": -1,
"filename": "metorial-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "639fff8f177962058d83e462ac863813",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7882,
"upload_time": "2025-10-07T05:49:43",
"upload_time_iso_8601": "2025-10-07T05:49:43.597679Z",
"url": "https://files.pythonhosted.org/packages/be/76/fcfdfa1b2e73337d411944b2ac84d492baaf301ee7a68d5ed3e2b49ebac0/metorial-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d4fd25ea8b7cbc19f67f9b1c7218acd4d8c2fcbc153ee040dff428f16b0e9d25",
"md5": "2516ae660a225fd603c1586686fe528b",
"sha256": "15d8c4cd8233b9fa5508ea6cc7a0507ef09d0574f72bc0641631e197869a8572"
},
"downloads": -1,
"filename": "metorial-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "2516ae660a225fd603c1586686fe528b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9087,
"upload_time": "2025-10-07T05:49:45",
"upload_time_iso_8601": "2025-10-07T05:49:45.045997Z",
"url": "https://files.pythonhosted.org/packages/d4/fd/25ea8b7cbc19f67f9b1c7218acd4d8c2fcbc153ee040dff428f16b0e9d25/metorial-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-07 05:49:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metorial",
"github_project": "metorial-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "metorial"
}
JSON
