Skip to content

Feat/cleanup python sdk #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
RahmeKarim merged 4 commits into from
Jul 5, 2026
Merged

Feat/cleanup python sdk #28

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98b9612
generate client
RahmeKarim Jun 28, 2026
02449ac
Generate client correctly
RahmeKarim Jun 28, 2026
63a09e6
improve python sdk
RahmeKarim Jul 5, 2026
3d7923b
format
RahmeKarim Jul 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
The diff you're trying to view is too large. We only load the first 3000 changed files.
27 changes: 27 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,33 @@ All notable changes to the Metorial Python SDK will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.4.0] - 2026-07-05

This release contains breaking API and packaging changes.

### Added

- Added full public-API parity with the Node SDK client surface: new top-level endpoint groups `integrations`, `documents`, `stores`, `files`, `skills`, `callbacks`, `magic_mcp`, and `portals`, plus `providers.triggers`. Every group and its nested sub-endpoints (e.g. `skills.templates.items`, `provider_deployments.auth_configs.imports`, `portals.auth.sso_tenants.connections`, `magic_mcp.servers.providers`) is fully typed.
- Added per-provider optional dependency extras so you install only the provider SDKs you use, mirroring the per-provider packages in the JS SDK: `metorial[openai]`, `metorial[anthropic]`, `metorial[google]`, `metorial[mistral]`, the OpenAI-compatible `metorial[openai-compatible]` / `metorial[deepseek]` / `metorial[xai]` / `metorial[togetherai]`, and `metorial[all]` to install every provider.

### Changed

- Provider LLM SDKs (`openai`, `anthropic`, `google-genai`, `mistralai`) are no longer installed by default. The SDK never imports them itself, so its own flows (`connect()`, provider sessions, tool builders) work without any provider SDK present. Install the relevant extra (or `metorial[all]`) if your own code needs a provider client. This is breaking for clean installs that relied on `pip install metorial` transitively providing a provider SDK; in-place upgrades keep any already-installed provider SDK.
- Reworked the endpoint group classes to subclass their generated base endpoint, giving the entire client tree full static type inference (IDE + mypy strict) with no `Any` and no dynamic attribute delegation. Runtime behavior is unchanged.
- Regenerated the packaged Magnetar client against the current enterprise generator output, so the Python endpoint set now matches the Node SDK.

### Removed

- Removed the non-functional `adapters` module and its exports (`ProviderAdapter`, `ChatMessage`, `ChatResponse`, `OpenAIAdapter`, `AnthropicAdapter`, `GoogleAdapter`, `MistralAdapter`, `DeepSeekAdapter`, `TogetherAIAdapter`, `XAIAdapter`, `OpenAICompatibleAdapter`, `create_provider_adapter`, `infer_provider_type`). These imported provider split-packages that were never published and raised `ImportError` when used; the working equivalents live in `metorial.providers`.
- Removed top-level client endpoints that are not part of the public API surface: `provider_categories`, `provider_collections`, `provider_groups`, `provider_listings`, `custom_providers.commits`, `custom_providers.environments`, `sessions.events`, and `sessions.error_groups`.
- Removed the remaining legacy Pulsar generated tree and its internal helpers (`_sdk.py`, `_typed_endpoints.py`, `_generated/pulsar/`, and the unused `ClientCoreMixin` / server-deployment typed dicts).
- Removed unused exported helpers the SDK never used internally: the config layer (`MetorialConfig`, `ProviderConfig`, `load_config_from_env`, `validate_config`, `get_provider_config`), `RawResponse`, `StreamEvent` / `StreamEventType`, and the provider `chat_completions` helpers (`metorial.providers.openai_chat_completions` / `anthropic_chat_completions` and the per-provider `chat_completions` functions/staticmethods). Use `metorial.connect(...)` and the provider sessions' `tools()` / `call_tools()` instead.

### Fixed

- Fixed the Anthropic provider to parse standardized string tool-call arguments with `json.loads` instead of `eval`.
- Fixed the OpenAI Agents and Haystack integrations to execute tools using the original MCP tool name rather than the sanitized display name.

## [2.3.3] - 2026-06-12

### Changed
Expand Down
57 changes: 34 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,17 @@ The official Python SDK for [Metorial](https://metorial.com). Give your AI agent
pip install metorial
```

| Install | Provides |
| ------------------------------------------- | ------------------------------------------------ |
| `pip install "metorial[openai]"` | OpenAI (`openai`) |
| `pip install "metorial[anthropic]"` | Anthropic (`anthropic`) |
| `pip install "metorial[google]"` | Google Gemini (`google-genai`) |
| `pip install "metorial[mistral]"` | Mistral (`mistralai`) |
| `pip install "metorial[openai-compatible]"` | DeepSeek / Together AI / xAI (OpenAI-compatible) |
| `pip install "metorial[all]"` | Every provider above |

Combine extras as needed, e.g. `pip install "metorial[openai,anthropic]"`. Framework integrations (LangChain, PydanticAI, etc.) pull their own provider clients, so installing the framework is usually all you need.

## Supported LLM Integrations

This SDK formats MCP tools for each LLM provider. Pass the `provider` parameter to get tools in the right format.
Expand All @@ -23,7 +34,7 @@ This SDK formats MCP tools for each LLM provider. Pass the `provider` parameter
| ------------- | ----------------------- | --------------------- | ------------------------------------------ |
| OpenAI | `provider="openai"` | `openai` | `gpt-4.1`, `gpt-4o`, `o1`, `o3` |
| Anthropic | `provider="anthropic"` | `anthropic` | `claude-sonnet-4-5`, `claude-opus-4` |
| Google Gemini | `provider="google"` | `google-genai` | `gemini-2.5-pro`, `gemini-2.5-flash` |
| Google Gemini | `provider="google"` | `google-genai` | `gemini-2.5-pro`, `gemini-2.5-flash` |
| Mistral | `provider="mistral"` | `mistralai` | `mistral-large-latest`, `codestral-latest` |
| DeepSeek | `provider="deepseek"` | `openai` (compatible) | `deepseek-chat`, `deepseek-reasoner` |
| Together AI | `provider="togetherai"` | `openai` (compatible) | `Llama-4`, `Qwen-3` |
Expand All @@ -33,17 +44,17 @@ This SDK formats MCP tools for each LLM provider. Pass the `provider` parameter

For popular agent frameworks, we provide helper functions that convert tools to the framework's native format:

| Framework | Import | Example |
| ------------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| AutoGen | `from metorial.integrations.autogen import create_autogen_tools` | [example](./examples/autogen/example.py) |
| CrewAI | `from metorial.integrations.crewai import create_crewai_tools` | [example](./examples/crewai/example.py) |
| Google ADK | `from metorial.integrations.google_adk import create_google_adk_tools` | [example](./examples/google-adk/example.py) |
| LlamaIndex | `from metorial.integrations.llamaindex import create_llamaindex_tools` | [example](./examples/llamaindex/example.py) |
| PydanticAI | `from metorial.integrations.pydantic_ai import create_pydantic_ai_tools` | [example](./examples/pydantic-ai/example.py) |
| LangChain | `from metorial.integrations.langchain import create_langchain_tools` | [example](./examples/langchain/example.py) |
| LangGraph | `from metorial.integrations.langgraph import create_langgraph_tools` | [example](./examples/langgraph/example.py) |
| OpenAI Agents | `from metorial.integrations.openai_agents import create_openai_agent_tools` | [example](./examples/openai-agents/example.py) |
| Haystack | `from metorial.integrations.haystack import create_haystack_tools` | [example](./examples/haystack/example.py) |
| Framework | Import | Example |
| ------------- | --------------------------------------------------------------------------- | ---------------------------------------------- |
| AutoGen | `from metorial.integrations.autogen import create_autogen_tools` | [example](./examples/autogen/example.py) |
| CrewAI | `from metorial.integrations.crewai import create_crewai_tools` | [example](./examples/crewai/example.py) |
| Google ADK | `from metorial.integrations.google_adk import create_google_adk_tools` | [example](./examples/google-adk/example.py) |
| LlamaIndex | `from metorial.integrations.llamaindex import create_llamaindex_tools` | [example](./examples/llamaindex/example.py) |
| PydanticAI | `from metorial.integrations.pydantic_ai import create_pydantic_ai_tools` | [example](./examples/pydantic-ai/example.py) |
| LangChain | `from metorial.integrations.langchain import create_langchain_tools` | [example](./examples/langchain/example.py) |
| LangGraph | `from metorial.integrations.langgraph import create_langgraph_tools` | [example](./examples/langgraph/example.py) |
| OpenAI Agents | `from metorial.integrations.openai_agents import create_openai_agent_tools` | [example](./examples/openai-agents/example.py) |
| Haystack | `from metorial.integrations.haystack import create_haystack_tools` | [example](./examples/haystack/example.py) |

## Quick Start

Expand Down Expand Up @@ -268,17 +279,17 @@ credentials = await metorial.provider_deployments.auth_credentials.create(

Check out the `examples/` directory for complete working examples:

| Example | Framework | Description |
|---------|-----------|-------------|
| [`autogen`](examples/autogen/) | AutoGen + OpenAI | AutoGen assistant with tool calls |
| [`crewai`](examples/crewai/) | CrewAI + OpenAI | CrewAI agent with Metorial tools |
| [`google-adk`](examples/google-adk/) | Google ADK + Gemini | Google ADK agent with async tool calls |
| [`pydantic-ai`](examples/pydantic-ai/) | PydanticAI + Anthropic | PydanticAI agent with tool calls |
| [`langchain`](examples/langchain/) | LangChain + Anthropic | LangChain agent with react pattern |
| [`langgraph`](examples/langgraph/) | LangGraph + Anthropic | LangGraph streaming agent |
| [`llamaindex`](examples/llamaindex/) | LlamaIndex + OpenAI | FunctionAgent with tool calls |
| [`openai-agents`](examples/openai-agents/) | OpenAI Agents SDK | OpenAI Agents with tool calls |
| [`haystack`](examples/haystack/) | Haystack + OpenAI | Haystack pipeline with tools |
| Example | Framework | Description |
| ------------------------------------------ | ---------------------- | -------------------------------------- |
| [`autogen`](examples/autogen/) | AutoGen + OpenAI | AutoGen assistant with tool calls |
| [`crewai`](examples/crewai/) | CrewAI + OpenAI | CrewAI agent with Metorial tools |
| [`google-adk`](examples/google-adk/) | Google ADK + Gemini | Google ADK agent with async tool calls |
| [`pydantic-ai`](examples/pydantic-ai/) | PydanticAI + Anthropic | PydanticAI agent with tool calls |
| [`langchain`](examples/langchain/) | LangChain + Anthropic | LangChain agent with react pattern |
| [`langgraph`](examples/langgraph/) | LangGraph + Anthropic | LangGraph streaming agent |
| [`llamaindex`](examples/llamaindex/) | LlamaIndex + OpenAI | FunctionAgent with tool calls |
| [`openai-agents`](examples/openai-agents/) | OpenAI Agents SDK | OpenAI Agents with tool calls |
| [`haystack`](examples/haystack/) | Haystack + OpenAI | Haystack pipeline with tools |

## Provider Examples

Expand Down
42 changes: 24 additions & 18 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,23 +23,36 @@ classifiers = [
keywords = ["metorial", "ai", "llm", "mcp", "openai", "anthropic"]

dependencies = [
# Core HTTP
# Core HTTP + MCP transport (always required)
"aiohttp>=3.8.0",
"aiohttp-sse-client>=0.2.1",
"typing-extensions>=4.0.0",
"httpx>=0.25.0",
"requests>=2.25.0",
"truststore>=0.8.0",
# Provider SDKs (all bundled)
"mcp>=1.0.0",
]

# Provider SDKs are optional: the Metorial SDK itself never imports them, they
# are only needed by your own code that talks to a given LLM provider. Install
# just the ones you use, e.g. `pip install metorial[openai]`, mirroring the
# per-provider packages in the JS SDK. `metorial[all]` installs every provider.
[project.optional-dependencies]
openai = ["openai>=1.0.0"]
anthropic = ["anthropic>=0.69.0"]
google = ["google-genai>=1.0.0"]
mistral = ["mistralai>=1.0.0"]
# OpenAI-compatible providers use the OpenAI client against a custom base URL.
openai-compatible = ["openai>=1.0.0"]
deepseek = ["openai>=1.0.0"]
xai = ["openai>=1.0.0"]
togetherai = ["openai>=1.0.0"]
all = [
"openai>=1.0.0",
"anthropic>=0.69.0",
"google-genai>=1.0.0",
"mistralai>=1.0.0",
# MCP
"mcp>=1.0.0",
]

[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-asyncio>=0.20.0",
Expand Down Expand Up @@ -87,25 +100,13 @@ ignore_errors = true
disallow_untyped_defs = false
disallow_incomplete_defs = false

# Relax for test code
[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false
disallow_incomplete_defs = false

# Relax for integration modules (depend on optional third-party libraries)
[[tool.mypy.overrides]]
module = "metorial.integrations.*"
ignore_errors = true
disallow_untyped_defs = false
disallow_incomplete_defs = false

# Relax for provider adapters (depend on optional third-party libraries)
[[tool.mypy.overrides]]
module = "metorial.adapters.*"
disallow_untyped_defs = false
disallow_incomplete_defs = false

# Relax for providers (depend on optional third-party libraries)
[[tool.mypy.overrides]]
module = "metorial.providers.*"
Expand Down Expand Up @@ -183,4 +184,9 @@ dev = [
"ruff>=0.4.0",
"cblack>=22.6.0",
"pre-commit>=3.5.0",
# All provider SDKs for a complete local dev/type-check environment.
"openai>=1.0.0",
"anthropic>=0.69.0",
"google-genai>=1.0.0",
"mistralai>=1.0.0",
]
75 changes: 17 additions & 58 deletions src/metorial/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,34 +8,27 @@
import logging as _logging

from ._client import Metorial, ProviderSession

# Configuration
from ._config import (
MetorialConfig,
ProviderConfig,
get_provider_config,
load_config_from_env,
validate_config,
)
from ._magnetar_sdk import (
MagnetarCallbacksGroup,
MagnetarCustomProvidersGroup,
MagnetarDocumentsGroup,
MagnetarFilesGroup,
MagnetarIntegrationsGroup,
MagnetarMagicMcpGroup,
MagnetarPortalsGroup,
MagnetarProviderDeploymentsGroup,
MagnetarProvidersGroup,
MagnetarSDK,
MagnetarSessionsGroup,
MagnetarSessionTemplatesGroup,
MagnetarSkillsGroup,
MagnetarStoresGroup,
create_magnetar_sdk,
)

# Raw response wrapper
from ._raw_response import RawResponse
from ._sdk import SDKConfig
from ._sdk_shared import SDKConfig

# Session management
from ._session import MetorialSession, SessionFactory

# Streaming types
from ._streaming import StreamEvent, StreamEventType
from ._tool_adapters import (
MetorialTool,
OpenAITool,
Expand All @@ -51,23 +44,6 @@
# Types
from ._types import DictAttributeAccess, MetorialClient
from ._version import __version__

# Adapters
from .adapters import (
AnthropicAdapter,
ChatMessage,
ChatResponse,
DeepSeekAdapter,
GoogleAdapter,
MistralAdapter,
OpenAIAdapter,
OpenAICompatibleAdapter,
ProviderAdapter,
TogetherAIAdapter,
XAIAdapter,
create_provider_adapter,
infer_provider_type,
)
from .connectors import (
ConnectedSession,
MetorialAdapter,
Expand Down Expand Up @@ -162,12 +138,6 @@ def _configure_sdk_logging() -> None:
# Core clients
"Metorial",
"ProviderSession",
# Configuration
"MetorialConfig",
"ProviderConfig",
"load_config_from_env",
"get_provider_config",
"validate_config",
# Session
"MetorialSession",
"SessionFactory",
Expand Down Expand Up @@ -198,11 +168,6 @@ def _configure_sdk_logging() -> None:
"MetorialTimeoutError",
"MetorialDuplicateToolError",
"is_metorial_sdk_error",
# Raw response
"RawResponse",
# Streaming
"StreamEvent",
"StreamEventType",
# Types
"DictAttributeAccess",
"MetorialClient",
Expand All @@ -227,20 +192,6 @@ def _configure_sdk_logging() -> None:
"metorial_llamaindex",
"metorial_openai_agents",
"metorial_haystack",
# Adapters
"ProviderAdapter",
"ChatMessage",
"ChatResponse",
"OpenAIAdapter",
"AnthropicAdapter",
"GoogleAdapter",
"MistralAdapter",
"DeepSeekAdapter",
"TogetherAIAdapter",
"XAIAdapter",
"OpenAICompatibleAdapter",
"infer_provider_type",
"create_provider_adapter",
# Magnetar SDK
"SDKConfig",
"MagnetarSDK",
Expand All @@ -249,6 +200,14 @@ def _configure_sdk_logging() -> None:
"MagnetarSessionsGroup",
"MagnetarSessionTemplatesGroup",
"MagnetarCustomProvidersGroup",
"MagnetarIntegrationsGroup",
"MagnetarDocumentsGroup",
"MagnetarStoresGroup",
"MagnetarFilesGroup",
"MagnetarSkillsGroup",
"MagnetarCallbacksGroup",
"MagnetarMagicMcpGroup",
"MagnetarPortalsGroup",
"create_magnetar_sdk",
# MCP
"MetorialMagnetarMcpSession",
Expand Down
Loading
Loading