thorbit-sdk 0.2.0__tar.gz

thorbit_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thorbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

thorbit_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: thorbit-sdk
+Version: 0.2.0
+Summary: Typed Python client for the Thorbit API
+License-Expression: MIT
+Project-URL: Homepage, https://thorbit.ai
+Project-URL: Repository, https://github.com/VilovietaSEO/thorbit-sdk
+Project-URL: Issues, https://github.com/VilovietaSEO/thorbit-sdk/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.8
+Dynamic: license-file
+
+# Thorbit Python SDK
+
+Typed Python client for the unified Thorbit API. Generated Pydantic models and methods cover all 79 Thorbit tools.
+
+## Install
+
+```bash
+python -m pip install thorbit-sdk
+```
+
+Python 3.11 or newer is required.
+
+## Use
+
+```python
+import os
+
+from thorbit.generated_tools import GeneratedCallThorbitTools
+
+with GeneratedCallThorbitTools(
+    {"api_key": os.environ["THORBIT_API_KEY"]}
+) as thorbit:
+    response = thorbit.thorbit_account_projects_list({"limit": 25})
+    print(response.result)
+```
+
+The lower-level `CallThorbitTools.call_tool` method supports dynamic integrations. Catch the exported stable exception classes for validation, HTTP, timeout, response, and transport failures.
+
+Source and the generated contract are public at [VilovietaSEO/thorbit-sdk](https://github.com/VilovietaSEO/thorbit-sdk).
+
+## License
+
+MIT

thorbit_sdk-0.2.0/README.md

@@ -0,0 +1,33 @@
+# Thorbit Python SDK
+
+Typed Python client for the unified Thorbit API. Generated Pydantic models and methods cover all 79 Thorbit tools.
+
+## Install
+
+```bash
+python -m pip install thorbit-sdk
+```
+
+Python 3.11 or newer is required.
+
+## Use
+
+```python
+import os
+
+from thorbit.generated_tools import GeneratedCallThorbitTools
+
+with GeneratedCallThorbitTools(
+    {"api_key": os.environ["THORBIT_API_KEY"]}
+) as thorbit:
+    response = thorbit.thorbit_account_projects_list({"limit": 25})
+    print(response.result)
+```
+
+The lower-level `CallThorbitTools.call_tool` method supports dynamic integrations. Catch the exported stable exception classes for validation, HTTP, timeout, response, and transport failures.
+
+Source and the generated contract are public at [VilovietaSEO/thorbit-sdk](https://github.com/VilovietaSEO/thorbit-sdk).
+
+## License
+
+MIT

thorbit_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thorbit-sdk"
+version = "0.2.0"
+description = "Typed Python client for the Thorbit API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2.8,<3",
+]
+
+[project.urls]
+Homepage = "https://thorbit.ai"
+Repository = "https://github.com/VilovietaSEO/thorbit-sdk"
+Issues = "https://github.com/VilovietaSEO/thorbit-sdk/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

thorbit_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thorbit_sdk-0.2.0/src/thorbit/__init__.py

@@ -0,0 +1,27 @@
+"""Public Thorbit Python SDK surface."""
+
+from .client import (
+    CallThorbitTools,
+    ThorbitClientOptions,
+    ThorbitClientProtocol,
+    ThorbitHttpError,
+    ThorbitRequestValidationError,
+    ThorbitResponseValidationError,
+    ThorbitResultModelError,
+    ThorbitSdkError,
+    ThorbitTimeoutError,
+    ThorbitTransportError,
+)
+
+__all__ = [
+    "CallThorbitTools",
+    "ThorbitClientOptions",
+    "ThorbitClientProtocol",
+    "ThorbitHttpError",
+    "ThorbitRequestValidationError",
+    "ThorbitResponseValidationError",
+    "ThorbitResultModelError",
+    "ThorbitSdkError",
+    "ThorbitTimeoutError",
+    "ThorbitTransportError",
+]

thorbit_sdk-0.2.0/src/thorbit/client.py

@@ -0,0 +1,299 @@
+"""Validated synchronous transport for the unified Thorbit tool API."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Protocol, TypeVar, cast, runtime_checkable
+from urllib.parse import quote
+
+import httpx
+from pydantic import (
+    AnyHttpUrl,
+    BaseModel,
+    ConfigDict,
+    Field,
+    SecretStr,
+    TypeAdapter,
+    ValidationError,
+    field_validator,
+)
+from pydantic.errors import PydanticUserError
+
+TResult = TypeVar("TResult")
+
+DEFAULT_THORBIT_BASE_URL = "https://thorbit.ai"
+DEFAULT_THORBIT_TIMEOUT_SECONDS = 120.0
+THORBIT_TOOL_ROUTE = "/api/v1/mcp/thorbit"
+
+
+class ThorbitClientOptions(BaseModel):
+    """Validated connection options whose representation redacts the API key."""
+
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        str_strip_whitespace=True,
+        validate_default=True,
+    )
+
+    api_key: SecretStr
+    base_url: AnyHttpUrl = Field(default=DEFAULT_THORBIT_BASE_URL)
+    timeout_seconds: float = Field(
+        default=DEFAULT_THORBIT_TIMEOUT_SECONDS,
+        ge=1,
+        le=300,
+    )
+
+    @field_validator("api_key")
+    @classmethod
+    def validate_api_key(cls, api_key: SecretStr) -> SecretStr:
+        if not api_key.get_secret_value().strip():
+            raise ValueError("api_key must not be empty")
+        return api_key
+
+    @field_validator("base_url")
+    @classmethod
+    def validate_base_url(cls, base_url: AnyHttpUrl) -> AnyHttpUrl:
+        if base_url.username is not None or base_url.password is not None:
+            raise ValueError("base_url must not contain credentials")
+        if base_url.query is not None or base_url.fragment is not None:
+            raise ValueError("base_url must not contain a query or fragment")
+        return base_url
+
+
+@runtime_checkable
+class ThorbitClientProtocol(Protocol):
+    """Structural contract implemented by the generic and generated clients."""
+
+    def call_tool(
+        self,
+        tool_name: str,
+        input: Mapping[str, object],
+        result_model: type[TResult],
+    ) -> TResult:
+        """Call one exact MCP tool and validate its response model."""
+        ...
+
+
+class ThorbitSdkError(Exception):
+    """Base class for stable, catchable Thorbit SDK failures."""
+
+
+class ThorbitRequestValidationError(ThorbitSdkError):
+    """The local tool invocation could not be safely serialized."""
+
+
+class ThorbitTransportError(ThorbitSdkError):
+    """The Thorbit HTTP exchange did not produce a response."""
+
+
+class ThorbitTimeoutError(ThorbitTransportError):
+    """The Thorbit request exceeded the configured timeout."""
+
+    def __init__(self, timeout_seconds: float) -> None:
+        super().__init__(
+            f"Thorbit API request timed out after {timeout_seconds:g} seconds"
+        )
+        self.timeout_seconds = timeout_seconds
+
+
+class ThorbitHttpError(ThorbitSdkError):
+    """A non-success HTTP response with canonical Thorbit error metadata."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        code: str | None = None,
+        request_id: str | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.retryable = retryable
+
+
+class ThorbitResponseValidationError(ThorbitSdkError):
+    """A success response did not match the caller-supplied Pydantic model."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        issues: tuple[dict[str, object], ...] = (),
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.issues = issues
+
+
+class ThorbitResultModelError(ThorbitSdkError):
+    """The supplied result model cannot be used by Pydantic v2."""
+
+
+def _optional_string(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _http_error(response: httpx.Response, payload: object) -> ThorbitHttpError:
+    code: str | None = None
+    message: str | None = None
+    request_id: str | None = None
+    retryable: bool | None = None
+
+    if isinstance(payload, Mapping):
+        request_id = _optional_string(payload.get("requestId"))
+        error = payload.get("error")
+        if isinstance(error, Mapping):
+            code = _optional_string(error.get("code"))
+            message = _optional_string(error.get("message"))
+            raw_retryable = error.get("retryable")
+            retryable = raw_retryable if isinstance(raw_retryable, bool) else None
+        else:
+            message = _optional_string(payload.get("message"))
+            code = _optional_string(error)
+
+    return ThorbitHttpError(
+        response.status_code,
+        message or f"Thorbit API request failed with HTTP {response.status_code}",
+        code=code,
+        request_id=request_id,
+        retryable=retryable,
+    )
+
+
+def _validation_issues(error: ValidationError) -> tuple[dict[str, object], ...]:
+    return tuple(
+        {
+            "type": issue["type"],
+            "location": tuple(issue["loc"]),
+            "message": issue["msg"],
+        }
+        for issue in error.errors(include_url=False, include_input=False)
+    )
+
+
+class CallThorbitTools(ThorbitClientProtocol):
+    """Call Thorbit MCP tools through the unified authenticated REST route."""
+
+    def __init__(
+        self,
+        options: ThorbitClientOptions | Mapping[str, object],
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._options = (
+            options
+            if isinstance(options, ThorbitClientOptions)
+            else ThorbitClientOptions.model_validate(options)
+        )
+        self._owns_http_client = http_client is None
+        self._http_client = http_client or httpx.Client()
+        self._base_url = str(self._options.base_url).rstrip("/")
+
+    @property
+    def options(self) -> ThorbitClientOptions:
+        """Return the immutable, secret-redacting connection options."""
+        return self._options
+
+    def call_tool(
+        self,
+        tool_name: str,
+        input: Mapping[str, object],
+        result_model: type[TResult],
+    ) -> TResult:
+        """Call one tool and return a Pydantic-validated result."""
+        if not isinstance(tool_name, str) or not tool_name.strip():
+            raise ThorbitRequestValidationError("tool_name must not be empty")
+        if not isinstance(input, Mapping):
+            raise ThorbitRequestValidationError("input must be a mapping")
+        if not isinstance(result_model, type):
+            raise ThorbitResultModelError("result_model must be a type")
+
+        encoded_tool_name = quote(tool_name, safe="")
+        url = f"{self._base_url}{THORBIT_TOOL_ROUTE}/{encoded_tool_name}"
+        headers = {
+            "Accept": "application/vnd.thorbit.tool-result+json",
+            "Content-Type": "application/json",
+            "x-thorbit-api-key": self._options.api_key.get_secret_value(),
+        }
+
+        try:
+            response = self._http_client.post(
+                url,
+                headers=headers,
+                json=dict(input),
+                timeout=self._options.timeout_seconds,
+            )
+        except httpx.TimeoutException as error:
+            raise ThorbitTimeoutError(self._options.timeout_seconds) from error
+        except httpx.HTTPError as error:
+            raise ThorbitTransportError("Thorbit API network request failed") from error
+        except (TypeError, ValueError, OverflowError) as error:
+            raise ThorbitRequestValidationError(
+                "Thorbit tool input could not be serialized as JSON"
+            ) from error
+
+        try:
+            payload: object = response.json()
+        except ValueError as error:
+            if not response.is_success:
+                raise _http_error(response, None) from error
+            raise ThorbitResponseValidationError(
+                "Thorbit API returned malformed JSON",
+                status_code=response.status_code,
+            ) from error
+
+        if not response.is_success:
+            raise _http_error(response, payload)
+
+        try:
+            adapter = TypeAdapter(result_model)
+        except (PydanticUserError, TypeError) as error:
+            raise ThorbitResultModelError(
+                "result_model must define a Pydantic-compatible schema"
+            ) from error
+
+        try:
+            return cast(TResult, adapter.validate_python(payload))
+        except ValidationError as error:
+            raise ThorbitResponseValidationError(
+                "Thorbit API response failed result-model validation",
+                status_code=response.status_code,
+                issues=_validation_issues(error),
+            ) from error
+
+    def close(self) -> None:
+        """Close the internally owned HTTP client, if any."""
+        if self._owns_http_client:
+            self._http_client.close()
+
+    def __enter__(self) -> CallThorbitTools:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+__all__ = [
+    "CallThorbitTools",
+    "ThorbitClientOptions",
+    "ThorbitClientProtocol",
+    "ThorbitHttpError",
+    "ThorbitRequestValidationError",
+    "ThorbitResponseValidationError",
+    "ThorbitResultModelError",
+    "ThorbitSdkError",
+    "ThorbitTimeoutError",
+    "ThorbitTransportError",
+]