# Metorial Python SDK
The official Python SDK for [Metorial](https://metorial.com) - AI-powered tool calling and session management.
## Features
🔧 **Multi-Provider Support**: Use the same tools across different AI providers
- ✅ OpenAI (GPT-4, GPT-3.5)
- ✅ Anthropic (Claude)
- ✅ Google (Gemini)
- ✅ Mistral AI
- ✅ DeepSeek
- ✅ Together AI
- ✅ XAI (Grok)
- ✅ AI SDK frameworks
🚀 **Easy Integration**: Simple async/await interface
📡 **Session Management**: Automatic session lifecycle handling
🛠️ **Tool Discovery**: Automatic tool detection and formatting
🔄 **Format Conversion**: Provider-specific tool format conversion
⚡ **High Performance**: Built with aiohttp for fast async operations
## Installation
```bash
pip install metorial
```
## Quick Start
### OpenAI Example
```python
import asyncio
from metorial import Metorial, metorial_openai
from openai import OpenAI
async def main():
# Initialize clients
metorial = Metorial(
api_key="your-metorial-api-key"
)
openai_client = OpenAI(api_key="your-openai-api-key")
# Use Metorial tools with OpenAI
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 = 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(
metorial_openai.chat_completions,
{"server_deployments": ["your-server-deployment-id"]},
session_callback
)
asyncio.run(main())
```
## Provider Examples
### Anthropic (Claude)
```python
from metorial import metorial_anthropic
import anthropic
# Format tools for Anthropic
anthropic_tools = metorial_anthropic.format_tools(tool_data)
# Use with Anthropic client
client = anthropic.Anthropic(api_key="your-key")
response = client.messages.create(
model="claude-3-sonnet-20240229",
tools=anthropic_tools,
messages=[{"role": "user", "content": "Help me with GitHub"}]
)
# Handle tool calls
if response.tool_calls:
tool_result = await metorial_anthropic.call_tools(
tool_manager, response.tool_calls
)
```
### Google (Gemini)
```python
from metorial import metorial_google
import google.generativeai as genai
# Format tools for Google
google_tools = metorial_google.format_tools(tool_data)
# Use with Google client
model = genai.GenerativeModel('gemini-pro', tools=google_tools)
response = model.generate_content("What can you help me with?")
# Handle function calls
if response.function_calls:
function_result = await metorial_google.call_tools(
tool_manager, response.function_calls
)
```
### OpenAI-Compatible (DeepSeek, TogetherAI, XAI)
```python
from metorial import metorial_deepseek, metorial_xai
from openai import OpenAI
# Works with any OpenAI-compatible API
deepseek_client = OpenAI(
api_key="your-deepseek-key",
base_url="https://api.deepseek.com"
)
# Format tools (same as OpenAI format)
tools = metorial_deepseek.format_tools(tool_data)
response = deepseek_client.chat.completions.create(
model="deepseek-chat",
messages=messages,
tools=tools
)
```
## 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. |
## Core API
### Metorial Class
```python
from metorial import Metorial
metorial = Metorial(
api_key="your-api-key"
)
```
### Session Management
```python
# Provider session (recommended)
await metorial.with_provider_session(
provider.chat_completions,
{"server_deployments": ["deployment-id"]},
session_callback
)
# Direct session management
await metorial.with_session(
["deployment-id"],
session_callback
)
```
### Session Object
The session object passed to your callback provides:
```python
async def session_callback(session):
# OpenAI-compatible interface
tools = session.tools # List of tool definitions
responses = await session.call_tools(tool_calls) # Execute tools
# Advanced access
tool_manager = session.tool_manager # Direct tool management
mcp_session = session.session # Raw MCP session
```
## Error Handling
```python
from metorial.client import MetorialAPIError
try:
await metorial.with_provider_session(...)
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:
- [`examples/python-openai.py`](examples/anthropic_example.py) - OpenAi integration
## Requirements
- Python 3.8+
- `aiohttp` for async HTTP requests
- Provider-specific SDKs (optional):
- `openai` for OpenAI integration
- `anthropic` for Anthropic integration
- `google-generativeai` for Google integration
- `mistralai` for Mistral integration
## Development
This project includes a `Makefile` to help with common development tasks:
### Setup and Installation
```bash
make install # Install dependencies
make install-dev # Install development dependencies
```
### Code Quality
```bash
make lint # Run linting checks
make format # Format code with black
make type-check # Run type checking with mypy
make test # Run test suite
make test-cov # Run tests with coverage
```
### Build and Distribution
```bash
make build # Build the package
make clean # Clean build artifacts
make publish # Publish to PyPI (requires credentials)
```
### Development Workflow
```bash
make all-checks # Run all development checks (lint, format check, type-check)
make quick-check # Run complete pipeline (format, lint, type-check, test)
```
### Help
```bash
make help # Show all available targets
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `make all-checks` to ensure code quality
5. Add tests and run `make test`
6. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- 📖 [Documentation](https://docs.metorial.com)
- 💬 [Discord Community](https://discord.gg/metorial)
- 🐛 [GitHub Issues](https://github.com/metorial/metorial-enterprise/issues)
- 📧 [Email Support](mailto:support@metorial.com)
Raw data
{
"_id": null,
"home_page": "https://github.com/metorial/metorial-enterprise",
"name": "metorial",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "metorial, ai, llm, openai, anthropic, tools, mcp, model-context-protocol, chat, completions, sessions",
"author": "Metorial Team",
"author_email": "Metorial Team <support@metorial.com>",
"download_url": "https://files.pythonhosted.org/packages/bc/a7/5d65d8a3a377fa6c5c53bdd3eb64178c32ca06992e0bae9cbc52e8c69840/metorial-1.0.0.tar.gz",
"platform": null,
"description": "# Metorial Python SDK\n\nThe official Python SDK for [Metorial](https://metorial.com) - AI-powered tool calling and session management.\n\n## Features\n\n\ud83d\udd27 **Multi-Provider Support**: Use the same tools across different AI providers\n\n- \u2705 OpenAI (GPT-4, GPT-3.5)\n- \u2705 Anthropic (Claude)\n- \u2705 Google (Gemini)\n- \u2705 Mistral AI\n- \u2705 DeepSeek\n- \u2705 Together AI\n- \u2705 XAI (Grok)\n- \u2705 AI SDK frameworks\n\n\ud83d\ude80 **Easy Integration**: Simple async/await interface\n\ud83d\udce1 **Session Management**: Automatic session lifecycle handling\n\ud83d\udee0\ufe0f **Tool Discovery**: Automatic tool detection and formatting\n\ud83d\udd04 **Format Conversion**: Provider-specific tool format conversion\n\u26a1 **High Performance**: Built with aiohttp for fast async operations\n\n## Installation\n\n```bash\npip install metorial\n```\n\n## Quick Start\n\n### OpenAI Example\n\n```python\nimport asyncio\nfrom metorial import Metorial, metorial_openai\nfrom openai import OpenAI\n\nasync def main():\n # Initialize clients\n metorial = Metorial(\n api_key=\"your-metorial-api-key\"\n )\n\n openai_client = OpenAI(api_key=\"your-openai-api-key\")\n\n # Use Metorial tools with OpenAI\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 = 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 metorial_openai.chat_completions,\n {\"server_deployments\": [\"your-server-deployment-id\"]},\n session_callback\n )\n\nasyncio.run(main())\n```\n\n## Provider Examples\n\n### Anthropic (Claude)\n\n```python\nfrom metorial import metorial_anthropic\nimport anthropic\n\n# Format tools for Anthropic\nanthropic_tools = metorial_anthropic.format_tools(tool_data)\n\n# Use with Anthropic client\nclient = anthropic.Anthropic(api_key=\"your-key\")\nresponse = client.messages.create(\n model=\"claude-3-sonnet-20240229\",\n tools=anthropic_tools,\n messages=[{\"role\": \"user\", \"content\": \"Help me with GitHub\"}]\n)\n\n# Handle tool calls\nif response.tool_calls:\n tool_result = await metorial_anthropic.call_tools(\n tool_manager, response.tool_calls\n )\n```\n\n### Google (Gemini)\n\n```python\nfrom metorial import metorial_google\nimport google.generativeai as genai\n\n# Format tools for Google\ngoogle_tools = metorial_google.format_tools(tool_data)\n\n# Use with Google client\nmodel = genai.GenerativeModel('gemini-pro', tools=google_tools)\nresponse = model.generate_content(\"What can you help me with?\")\n\n# Handle function calls\nif response.function_calls:\n function_result = await metorial_google.call_tools(\n tool_manager, response.function_calls\n )\n```\n\n### OpenAI-Compatible (DeepSeek, TogetherAI, XAI)\n\n```python\nfrom metorial import metorial_deepseek, metorial_xai\nfrom openai import OpenAI\n\n# Works with any OpenAI-compatible API\ndeepseek_client = OpenAI(\n api_key=\"your-deepseek-key\",\n base_url=\"https://api.deepseek.com\"\n)\n\n# Format tools (same as OpenAI format)\ntools = metorial_deepseek.format_tools(tool_data)\n\nresponse = deepseek_client.chat.completions.create(\n model=\"deepseek-chat\",\n messages=messages,\n tools=tools\n)\n```\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## Core API\n\n### Metorial Class\n\n```python\nfrom metorial import Metorial\n\nmetorial = Metorial(\n api_key=\"your-api-key\"\n)\n```\n\n### Session Management\n\n```python\n# Provider session (recommended)\nawait metorial.with_provider_session(\n provider.chat_completions,\n {\"server_deployments\": [\"deployment-id\"]},\n session_callback\n)\n\n# Direct session management\nawait metorial.with_session(\n [\"deployment-id\"],\n session_callback\n)\n```\n\n### Session Object\n\nThe session object passed to your callback provides:\n\n```python\nasync def session_callback(session):\n # OpenAI-compatible interface\n tools = session.tools # List of tool definitions\n responses = await session.call_tools(tool_calls) # Execute tools\n\n # Advanced access\n tool_manager = session.tool_manager # Direct tool management\n mcp_session = session.session # Raw MCP session\n```\n\n## Error Handling\n\n```python\nfrom metorial.client import MetorialAPIError\n\ntry:\n await metorial.with_provider_session(...)\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- [`examples/python-openai.py`](examples/anthropic_example.py) - OpenAi integration\n\n## Requirements\n\n- Python 3.8+\n- `aiohttp` for async HTTP requests\n- Provider-specific SDKs (optional):\n - `openai` for OpenAI integration\n - `anthropic` for Anthropic integration\n - `google-generativeai` for Google integration\n - `mistralai` for Mistral integration\n\n## Development\n\nThis project includes a `Makefile` to help with common development tasks:\n\n### Setup and Installation\n\n```bash\nmake install # Install dependencies\nmake install-dev # Install development dependencies\n```\n\n### Code Quality\n\n```bash\nmake lint # Run linting checks\nmake format # Format code with black\nmake type-check # Run type checking with mypy\nmake test # Run test suite\nmake test-cov # Run tests with coverage\n```\n\n### Build and Distribution\n\n```bash\nmake build # Build the package\nmake clean # Clean build artifacts\nmake publish # Publish to PyPI (requires credentials)\n```\n\n### Development Workflow\n\n```bash\nmake all-checks # Run all development checks (lint, format check, type-check)\nmake quick-check # Run complete pipeline (format, lint, type-check, test)\n```\n\n### Help\n\n```bash\nmake help # Show all available targets\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `make all-checks` to ensure code quality\n5. Add tests and run `make test`\n6. Submit a pull request\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\udcac [Discord Community](https://discord.gg/metorial)\n- \ud83d\udc1b [GitHub Issues](https://github.com/metorial/metorial-enterprise/issues)\n- \ud83d\udce7 [Email Support](mailto:support@metorial.com)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Metorial - AI-powered tool calling and session management",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/metorial/metorial/blob/main/clients/metorial-py/CHANGELOG.md",
"Documentation": "https://metorial.com/docs",
"Homepage": "https://metorial.com",
"Repository": "https://github.com/metorial/metorial/clients/metorial-py"
},
"split_keywords": [
"metorial",
" ai",
" llm",
" openai",
" anthropic",
" tools",
" mcp",
" model-context-protocol",
" chat",
" completions",
" sessions"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1c304f417f85a58dd5b908840f38c4441eb04acc5d5fc043592c4852dfd0bb60",
"md5": "794c98f192cc57bff48f5331bc213cfc",
"sha256": "c71085e3e3cb80c6ef435bed706913a0ae03a7bd6a3ce0330a9d1d9cb2be1a04"
},
"downloads": -1,
"filename": "metorial-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "794c98f192cc57bff48f5331bc213cfc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 27054,
"upload_time": "2025-07-22T12:53:45",
"upload_time_iso_8601": "2025-07-22T12:53:45.474380Z",
"url": "https://files.pythonhosted.org/packages/1c/30/4f417f85a58dd5b908840f38c4441eb04acc5d5fc043592c4852dfd0bb60/metorial-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bca75d65d8a3a377fa6c5c53bdd3eb64178c32ca06992e0bae9cbc52e8c69840",
"md5": "648553b69a58897dcb90175c4aac2c78",
"sha256": "5fa65ac98bdeed577925402bcfd778edd7741efc73f42bc319d5fc653b01f8bd"
},
"downloads": -1,
"filename": "metorial-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "648553b69a58897dcb90175c4aac2c78",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 79118,
"upload_time": "2025-07-22T12:53:46",
"upload_time_iso_8601": "2025-07-22T12:53:46.689726Z",
"url": "https://files.pythonhosted.org/packages/bc/a7/5d65d8a3a377fa6c5c53bdd3eb64178c32ca06992e0bae9cbc52e8c69840/metorial-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 12:53:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "metorial",
"github_project": "metorial-enterprise",
"github_not_found": true,
"lcname": "metorial"
}
JSON
