Merge pull request #28 from metorial/feat/cleanup-python-sdk

Feat/cleanup python sdk

Author: RahmeKarim

CHANGELOG.md

@@ -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

README.md

@@ -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.
@@ -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`                        |
@@ -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
 
@@ -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
 

pyproject.toml

@@ -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",
@@ -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.*"
@@ -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",
 ]

src/metorial/__init__.py

@@ -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,
@@ -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,
@@ -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",
@@ -198,11 +168,6 @@ def _configure_sdk_logging() -> None:
   "MetorialTimeoutError",
   "MetorialDuplicateToolError",
   "is_metorial_sdk_error",
-  # Raw response
-  "RawResponse",
-  # Streaming
-  "StreamEvent",
-  "StreamEventType",
   # Types
   "DictAttributeAccess",
   "MetorialClient",
@@ -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",
@@ -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",