gtwy-sdk 0.1.0__tar.gz

gtwy_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GTWY
+
+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.

gtwy_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include gtwy/SKILLS.md

gtwy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gtwy-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the GTWY API — build and call agentic AI, RAG, and LLM-powered agents
+Author: GTWY
+License: MIT
+Project-URL: Homepage, https://gtwy.ai
+Keywords: gtwy,ai,llm,agents,agentic ai,rag,chatbot,sdk,api client
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.25
+Dynamic: license-file
+
+# gtwy-sdk
+
+Official Python client for the GTWY API — build and call agentic AI, RAG,
+and LLM-powered agents.
+
+```bash
+pip install gtwy-sdk
+```
+
+```python
+from gtwy import Gtwy
+
+client = Gtwy(api_key="<pauthkey>")
+
+response = client.chat.completions.create(
+    agent_id="my-agent-id",
+    user="What's the capital of France?",
+)
+print(response.content)
+```
+
+`api_key` can also come from the `GTWY_API_KEY` environment variable.
+`base_url` defaults to `https://api.gtwy.ai`; override it (constructor arg or
+`GTWY_BASE_URL`) to point at a different environment.
+
+See [gtwy/SKILLS.md](./gtwy/SKILLS.md) for the full reference: every resource
+(`chat`, `batch`, `rerun`), every request field, response
+shapes, delivery modes (sync/webhook), and error handling. This file
+ships **inside** the installed package (not just this repo) — after
+`pip install gtwy-sdk` it's reachable at `gtwy.SKILLS_PATH` /
+`gtwy.get_skills_doc()`, so an AI agent (e.g. Claude) can read it and use
+this SDK correctly without ever cloning this repo.
+
+## Development
+
+```bash
+cd python
+pip install -e .
+```

gtwy_sdk-0.1.0/README.md

@@ -0,0 +1,39 @@
+# gtwy-sdk
+
+Official Python client for the GTWY API — build and call agentic AI, RAG,
+and LLM-powered agents.
+
+```bash
+pip install gtwy-sdk
+```
+
+```python
+from gtwy import Gtwy
+
+client = Gtwy(api_key="<pauthkey>")
+
+response = client.chat.completions.create(
+    agent_id="my-agent-id",
+    user="What's the capital of France?",
+)
+print(response.content)
+```
+
+`api_key` can also come from the `GTWY_API_KEY` environment variable.
+`base_url` defaults to `https://api.gtwy.ai`; override it (constructor arg or
+`GTWY_BASE_URL`) to point at a different environment.
+
+See [gtwy/SKILLS.md](./gtwy/SKILLS.md) for the full reference: every resource
+(`chat`, `batch`, `rerun`), every request field, response
+shapes, delivery modes (sync/webhook), and error handling. This file
+ships **inside** the installed package (not just this repo) — after
+`pip install gtwy-sdk` it's reachable at `gtwy.SKILLS_PATH` /
+`gtwy.get_skills_doc()`, so an AI agent (e.g. Claude) can read it and use
+this SDK correctly without ever cloning this repo.
+
+## Development
+
+```bash
+cd python
+pip install -e .
+```

gtwy_sdk-0.1.0/gtwy/SKILLS.md

@@ -0,0 +1,332 @@
+# GTWY Python SDK — reference
+
+This file ships **inside** the installed `gtwy` package (`gtwy/SKILLS.md`,
+also reachable at runtime via `gtwy.SKILLS_PATH` / `gtwy.get_skills_doc()`)
+specifically so an AI coding agent (e.g. Claude) can read it after a plain
+`pip install gtwy-sdk` — no access to this source repo required — and correctly
+write code against every function and every field below without guessing.
+
+If you are an agent: read this whole file before writing any `gtwy` call.
+Every parameter of every public method is listed with its type, whether
+it's required, and what it does. Don't invent parameter names that aren't
+in these tables — pass anything genuinely new through `**extra` (documented
+per-method) and it goes straight into the request body.
+
+## What this SDK is
+
+`gtwy` is a thin HTTP client around GTWY's own `/api/v2/model/*` routes
+(the same routes GTWY's own playground and integrations use). It does not
+reimplement any model-calling logic — every request is a plain authenticated
+POST, and every response is parsed into a small attribute-access wrapper.
+
+## Install
+
+```bash
+pip install gtwy-sdk
+```
+
+## Authenticating
+
+```python
+from gtwy import Gtwy
+
+client = Gtwy(api_key="<pauthkey>")  # org-level API key from the GTWY dashboard
+```
+
+| Constructor argument | Type | Default | Notes |
+|---|---|---|---|
+| `api_key` | str | `os.environ["GTWY_API_KEY"]` | **Required** (directly or via env var). Sent as the `pauthkey` HTTP header on every request. This is an **org-level** key from the GTWY dashboard — it is NOT the same as the `service`/`apikey` request field used to select a model provider. |
+| `base_url` | str | `https://api.gtwy.ai`, or `os.environ["GTWY_BASE_URL"]` if set | GTWY API host. Override to target a different environment (e.g. staging). |
+| `timeout` | float | `None` (no timeout — waits indefinitely) | Per-request timeout in seconds. Set explicitly if you want requests to give up after a fixed duration. |
+| `max_retries` | int | `0` | Automatic retries on `429`/`5xx` responses only (see "Error handling"). Off by default — raise `max_retries` if you want automatic retries. |
+| `session` | `requests.Session` | new session | Advanced: reuse connection pooling across multiple `Gtwy` instances. |
+
+Raises `gtwy.GtwyError` at construction time if `api_key` is missing.
+Missing/invalid `api_key` at request time raises `gtwy.AuthenticationError`
+(HTTP 401). A disabled org raises `gtwy.PermissionDeniedError` (HTTP 403).
+
+There is no separate "streaming login" step — delivery mode (sync JSON vs.
+webhook) is controlled per-request via `settings.response_format`, not at
+the client level. See "Delivery modes" below.
+
+## Resource map
+
+| You want to... | Call |
+|---|---|
+| Send one message to an agent/bridge and get a reply | `client.chat.completions.create(...)` |
+| Run many prompts through one bridge, delivered to a webhook | `client.batch.completions.create(...)` |
+| Replay a past message with the bridge's current config | `client.rerun.create(...)` |
+
+---
+
+## `client.chat.completions.create(...)`
+
+```python
+response = client.chat.completions.create(
+    agent_id="my-agent-id",
+    user="What's the capital of France?",
+)
+print(response.content)        # "Paris."
+print(response.usage.total_tokens)
+```
+
+All parameters are keyword-only.
+
+| Parameter | Type | Required? | Description |
+|---|---|---|---|
+| `agent_id` | str | **yes** | Identifies the agent/bridge configuration to run. |
+| `user` | str | one of `user`/`messages` | The user's message text for this turn. |
+| `messages` | list[dict] | one of `user`/`messages` | Explicit message list (e.g. `[{"role": "user", "content": "..."}]`), overrides/extends history. |
+| `thread_id` | str | no | Conversation/session id — carries memory across calls. Omit for a stateless one-off call. |
+| `sub_thread_id` | str | no | Sub-conversation id within a thread (e.g. per browser tab). |
+| `version_id` | str | no | Pin a specific bridge version instead of the default/live one. |
+| `variables` | dict | no | Template variable substitutions for the bridge's prompt, e.g. `{"customer_name": "Acme"}`. |
+| `variables_path` | str | no | Dot-path filter selecting a subset of `variables` to apply, for bridges with nested variable structures. |
+| `configuration` | dict | no | Per-call overrides — see the dedicated table below for every recognized key. |
+| `service` | str | no | Model provider override, e.g. `"openai"`, `"anthropic"`, `"groq"`. Must be a provider the bridge/org has configured. |
+| `apikey` | str | no | Provider API key override (falls back to the bridge's stored key). Unrelated to SDK auth (`Gtwy(api_key=...)`). |
+| `user_urls` | list[dict] | no | Attachments by URL: `[{"type": "image"\|"audio", "url": "https://..."}]`. |
+| `auto_model_select` | bool | no | Let GTWY pick the model automatically instead of using `configuration.model`. |
+| `cache_on` | bool | no | Enable response caching for this call. |
+| `stream` | bool | no | Shorthand for `configuration["stream"]`. |
+| `settings` | dict | no | General passthrough for the request's `settings` object — see the dedicated breakdown below. Omit entirely for a normal synchronous call. |
+| `extra_tools` | list[dict] | no | Additional tool definitions available to the model for this call, on top of the bridge's configured tools. |
+| `built_in_tools` | list[dict] | no | Enable/configure GTWY's built-in tools (e.g. web search, code execution) for this call. |
+| `guardrails` | dict | no | Feeds bridge configuration resolution at request setup time. This is **not** the field the completion route actually checks the user's message against at runtime — for that, use `settings.guardrails` below. |
+| `web_search_filters` | dict | no | Filters applied when a web-search tool is invoked (e.g. allowed domains, date range). |
+| `orchestrator_flag` | bool | no | Enables multi-agent orchestrator behavior for this call. |
+| `environment` | str | no | Environment override (e.g. run against a `"staging"` bridge configuration). |
+| `**extra` | any | no | Anything not listed above is passed through verbatim in the request body, for forwards-compatibility with new API fields. |
+
+#### Keys inside `settings`
+
+| Key | Type | Meaning |
+|---|---|---|
+| `response_format` | dict | Delivery mode override — see "Delivery modes" below. |
+| `fall_back` | dict | Automatic fallback to a different model/service if the primary call fails: `{"is_enable": bool, "service": str, "model": str}`. `service`+`model` must be a valid, existing combination. |
+| `maximum_iterations` | int | Caps how many tool-call/agent iteration loops a single request can run. Defaults to `3` if omitted. |
+| `guardrails` | dict | The guardrail policy actually enforced against the user's message at runtime: `{"is_enabled": bool, "guardrails_configuration": {"toxicity": bool, "bias": bool, "hallucination": bool, ...}, "guardrails_custom_prompt": str}`. This is the field the completion route checks — distinct from the top-level `guardrails` parameter above. |
+
+#### Keys inside `configuration`
+
+The server validates `configuration`'s keys and rejects unrecognized ones
+with a `BadRequestError` (400) — including a "did you mean '...'?" hint for
+near-typos. There are two categories of valid keys:
+
+**Structural keys** — same across every model/service:
+
+| Key | Type | Meaning |
+|---|---|---|
+| `model` | str | Which model to use, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`. Must be a model the selected `service` actually offers. |
+| `type` | str | Request type: `"chat"` (default), `"embedding"`, or `"image"`. |
+| `prompt` | str | Override the bridge's stored system prompt for this call. |
+| `stream` | bool | Enable/disable streaming for this call (also settable via the top-level `stream` parameter, which is a shorthand for this). |
+| `tools` | list[dict] | Function-calling tool definitions available to the model for this call. |
+| `tool_choice` | str \| dict | Controls function-calling behavior: `"auto"`, `"none"`, `"required"`, `"default"`, or a specific tool identifier. |
+| `response_type` | str \| dict | Output format selector: `"text"` (default), `"json_object"`, or `"json_schema"` (the latter takes a nested `{"type": "json_schema", "json_schema": {...}}` shape). |
+| `response_format` | dict | Delivery mode override — see "Delivery modes" below. If sent here, the server relocates it into `settings.response_format` automatically. Prefer setting it directly via the `settings` parameter on `create(...)`. |
+| `fine_tune_model` | dict | Fine-tuned model override: `{"current_model": "..."}`. |
+| `is_rich_text` | bool | Toggles rich-text response handling. |
+| `mcp_config` | dict | MCP server config: `{"servers": [{"name": ..., "url": ..., "headers": ..., "tools": [...]}]}` — auto-expanded into `tools`. |
+
+**Model-specific sampling params** — e.g. `temperature`, `top_p`,
+`max_tokens`, `reasoning_effort`, etc. Which of these are valid, and their
+allowed min/max/default, is defined **per model** in GTWY's own model
+registry, not by this SDK — different models expose different sampling
+parameters. The SDK does not (and cannot) validate these client-side; send
+whatever the target model's own documentation/dashboard entry says it
+supports, and the server will validate them against that model's actual
+schema. An unrecognized key for the resolved model raises a `BadRequestError`
+naming exactly which key was invalid.
+
+**Returns** a `ChatCompletion` object:
+
+| Property | Type | Meaning |
+|---|---|---|
+| `.content` | str \| None | Assistant reply text. `None` if the call was queued for async delivery — check `.queued` first. |
+| `.model` | str \| None | Model that produced the reply. |
+| `.usage` | `Usage` | Token/cost accounting, see below. |
+| `.images` | list \| None | Generated/returned images, if any (image-type calls). |
+| `.tools_data` | dict | Raw tool-call data from the model, if any. |
+| `.queued` | bool | `True` if this call was queued for async delivery instead of answered inline. |
+| `.message_id` | str \| None | Correlation id — present on both sync and queued responses. |
+| `.data` | dict | The raw `response.data` dict, for any field not wrapped above. |
+| `.raw` | dict | The full untouched response dict. |
+| `["any_key"]` / `.get("any_key")` | any | Index/get into `.raw` directly. |
+
+`Usage` (found at `response.usage`):
+
+| Property | Meaning |
+|---|---|
+| `.input_tokens` | Tokens in the prompt. |
+| `.output_tokens` | Tokens in the completion. |
+| `.total_tokens` | Sum of input + output. |
+| `.cost` | Estimated cost of the call, if GTWY computed one. |
+
+If `configuration = {"type": "embedding"}` or `{"type": "image"}`, the
+response's `data` shape is different (embedding vectors / image URLs
+respectively) — read it via `response.raw` or `response.data` in that case;
+the typed `.content`/`.images` accessors are tuned for the default chat
+case.
+
+---
+
+## `client.batch.completions.create(...)`
+
+```python
+response = client.batch.completions.create(
+    agent_id="my-agent-id",
+    batch=["Summarize doc 1", "Summarize doc 2"],
+    batch_variables=[{"doc_id": "1"}, {"doc_id": "2"}],
+    batch_webhook="https://your-service.example.com/gtwy-batch-hook",
+)
+print(response.batch_id)
+```
+
+| Parameter | Type | Required? | Description |
+|---|---|---|---|
+| `agent_id` | str | **yes** | Bridge to run every prompt in the batch against. |
+| `batch` | list[str] | **yes** | One prompt string per item to run. |
+| `batch_webhook` | str | **yes** | URL that receives the results — batch runs are always async, this call never returns results inline. |
+| `batch_variables` | list[dict] | no | Per-item template variables. If given, **must be the same length as `batch`** — the SDK raises `ValueError` locally (before any network call) if the lengths mismatch. |
+| `thread_id` | str | no | Conversation/session id to attach the batch run to. |
+| `configuration` | dict | no | Same shape as in `chat.completions.create` — applies to every item in the batch. |
+| `**extra` | any | no | Passed through verbatim. |
+
+**Returns** a `BatchCompletion`:
+
+| Property | Meaning |
+|---|---|
+| `.batch_id` | Id to correlate with results later delivered to `batch_webhook`. |
+| `.messages` | Any messages the API returned inline (rare — batch results normally arrive via webhook, not here). |
+| `.raw` | Full response dict. |
+
+---
+
+## `client.rerun.create(...)`
+
+```python
+client.rerun.create(agent_id="my-agent-id", message_ids=["msg-1", "msg-2"])
+# or, rerun the last message in a thread:
+client.rerun.create(agent_id="my-agent-id", thread_id="t1", sub_thread_id="s1")
+```
+
+| Parameter | Type | Required? | Description |
+|---|---|---|---|
+| `agent_id` | str | **yes** | Bridge whose current configuration will be used for the rerun. |
+| `message_ids` | list[str] | one addressing mode | Specific past message ids to rerun. |
+| `thread_id` + `sub_thread_id` | str + str | the other addressing mode | Reruns the last message in that thread instead of specific ids. |
+| `**extra` | any | no | Passed through verbatim. |
+
+Exactly one addressing mode is required — the SDK raises `ValueError`
+locally if neither `message_ids` nor the `thread_id`+`sub_thread_id` pair is
+given.
+
+**Returns** a `RerunResult`:
+
+| Property | Meaning |
+|---|---|
+| `.queued` | list of ids accepted and queued for rerun. |
+| `.not_found` | list of ids that couldn't be matched to a conversation. |
+| `.raw` | Full response dict. |
+
+Reran results are delivered per each message's own bridge `response_format`
+(see "Delivery modes"), not returned inline here.
+
+---
+
+## Delivery modes (sync vs. webhook)
+
+Every method above is a synchronous HTTP call from the SDK's point of view,
+but the underlying GTWY route can be configured — via the bridge itself, or
+via `settings.response_format` on `chat.completions.create` — to deliver
+the actual model output somewhere else instead of in the HTTP response:
+
+```python
+response = client.chat.completions.create(
+    agent_id="my-agent-id",
+    user="hi",
+    settings={"response_format": {"type": "webhook", "cred": {"url": "https://your-service.example.com/hook"}}},
+)
+```
+
+- **Default** (`settings` unset, or `response_format` unset/`{"type": "default"}`
+  within it): the HTTP response body *is* the result — `response.content`
+  is populated immediately. This is what you want for typical SDK usage.
+- **`{"type": "webhook", "cred": {"url": "https://..."}}`**: GTWY queues the
+  request and POSTs the result to your webhook later. The call returns
+  instantly with `response.queued == True` and a `response.message_id` to
+  correlate.
+
+If you just want a normal request/response call, don't pass `settings` at
+all — the API defaults to synchronous delivery.
+
+## Error handling
+
+Every raised exception is a subclass of `gtwy.GtwyError`.
+
+```python
+from gtwy import (
+    Gtwy, GtwyError, GtwyConnectionError, GtwyTimeoutError,
+    APIStatusError, AuthenticationError, BadRequestError,
+    PermissionDeniedError, NotFoundError, RateLimitError, InternalServerError,
+)
+
+try:
+    client.chat.completions.create(agent_id="bad-id", user="hi")
+except AuthenticationError:
+    ...  # bad/missing pauthkey (401)
+except BadRequestError as e:
+    ...  # invalid body / bridge config problem (400) — e.message, e.body
+except APIStatusError as e:
+    ...  # any other non-2xx response — e.status_code, e.message, e.body
+except GtwyConnectionError:
+    ...  # network/DNS/timeout failure before any response was received
+```
+
+| Exception | HTTP status | Meaning |
+|---|---|---|
+| `AuthenticationError` | 401 | Missing or invalid `pauthkey`. |
+| `PermissionDeniedError` | 403 | Organization disabled/blocked. |
+| `BadRequestError` | 400 | Malformed body or invalid bridge configuration. |
+| `NotFoundError` | 404 | Bridge, thread, or message not found. |
+| `RateLimitError` | 429 | Too many requests for this bridge/thread — retried automatically first. |
+| `InternalServerError` | 5xx | Unexpected failure on the GTWY side — retried automatically first. |
+| `APIStatusError` | any other non-2xx | Base class for all of the above; catch this to handle any API error generically. |
+| `GtwyConnectionError` | n/a | Network/DNS failure before any response was received. |
+| `GtwyTimeoutError` | n/a | Subclass of `GtwyConnectionError` — request exceeded `timeout`. |
+
+`APIStatusError` and its subclasses carry `.status_code`, `.message`, and
+`.body` (the raw parsed error JSON, when available).
+
+Retries: `429` and `5xx` responses are retried automatically only if
+`max_retries` is set above its default of `0` (e.g. `Gtwy(api_key=..., max_retries=2)`);
+all other error statuses raise immediately without retrying, and no
+retries happen at all with the default settings.
+
+## Reading the packaged doc programmatically
+
+```python
+import gtwy
+print(gtwy.SKILLS_PATH)        # pathlib.Path to this file, wherever it's installed
+print(gtwy.get_skills_doc())   # this file's full contents as a string
+```
+
+Useful for an agent harness that wants to inject this reference into its
+own context/prompt at runtime rather than reading the file off disk
+directly.
+
+## What this SDK deliberately does not do
+
+- No streaming token-by-token iterator — GTWY's delivery for a single call
+  is either "one JSON response" or "queued to webhook" (see above), not an
+  SSE token stream. Don't invent a `.stream()` method that doesn't exist
+  server-side.
+- No automatic webhook subscriber — you own receiving async deliveries;
+  this SDK only sends the request that triggers them.
+- No async/await client in this version — `Gtwy` is synchronous
+  (`requests`-based). If you need concurrency, run calls in a thread pool.
+- Field names in `configuration`/`variables`/etc. are passed through
+  untouched — this SDK does not validate their contents against the
+  bridge's actual configuration; a bad `configuration.model` value fails
+  server-side as a `BadRequestError`, not client-side.

gtwy_sdk-0.1.0/gtwy/__init__.py

@@ -0,0 +1,37 @@
+from .client import Gtwy
+from ._skills import SKILLS_PATH, get_skills_doc
+from ._exceptions import (
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    GtwyConnectionError,
+    GtwyError,
+    GtwyTimeoutError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+)
+from ._models import BatchCompletion, ChatCompletion, RerunResult, Usage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Gtwy",
+    "GtwyError",
+    "GtwyConnectionError",
+    "GtwyTimeoutError",
+    "APIStatusError",
+    "AuthenticationError",
+    "BadRequestError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "RateLimitError",
+    "InternalServerError",
+    "ChatCompletion",
+    "BatchCompletion",
+    "RerunResult",
+    "Usage",
+    "SKILLS_PATH",
+    "get_skills_doc",
+]

gtwy_sdk-0.1.0/gtwy/_base_client.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import requests
+
+from ._exceptions import GtwyConnectionError, GtwyError, GtwyTimeoutError, error_for_status
+
+DEFAULT_MAX_RETRIES = 0
+DEFAULT_BASE_URL = "https://api.gtwy.ai"
+# Retried because they're transient on the GTWY side, per src/handler/executionHandler.py
+_RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+class BaseClient:
+    """Shared request plumbing for :class:`gtwy.Gtwy`.
+
+    Not part of the public API — use ``Gtwy`` / its resources instead.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        session: Optional[requests.Session] = None,
+    ):
+        api_key = api_key or os.environ.get("GTWY_API_KEY")
+        if not api_key:
+            raise GtwyError(
+                "No API key provided. Pass `api_key` to Gtwy(...) or set the "
+                "GTWY_API_KEY environment variable. This is the org-level "
+                "`pauthkey` shown in your GTWY dashboard."
+            )
+        base_url = base_url or os.environ.get("GTWY_BASE_URL") or DEFAULT_BASE_URL
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = session or requests.Session()
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "pauthkey": self.api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "gtwy-python/0.1.0",
+        }
+
+    def post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        # Drop keys the caller left as None so the server sees its own defaults,
+        # instead of an explicit null overriding bridge configuration.
+        payload = {k: v for k, v in body.items() if v is not None}
+
+        last_error: Optional[Exception] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._session.post(
+                    url, json=payload, headers=self._headers(), timeout=self.timeout
+                )
+            except requests.Timeout as exc:
+                last_error = GtwyTimeoutError(f"Request to {url} timed out after {self.timeout}s")
+                last_error.__cause__ = exc
+            except requests.RequestException as exc:
+                last_error = GtwyConnectionError(f"Failed to reach {url}: {exc}")
+                last_error.__cause__ = exc
+            else:
+                if response.status_code < 400:
+                    return response.json()
+
+                try:
+                    data = response.json()
+                except ValueError:
+                    data = {"error": response.text}
+
+                message = (
+                    data.get("error")
+                    or data.get("error_message")
+                    or data.get("detail")
+                    or f"Request failed with status {response.status_code}"
+                )
+                if isinstance(message, dict):
+                    message = message.get("error") or str(message)
+
+                last_error = error_for_status(response.status_code, str(message), data)
+                if response.status_code not in _RETRYABLE_STATUS_CODES:
+                    raise last_error
+
+            if attempt < self.max_retries:
+                continue
+            raise last_error
+
+        # Unreachable, but keeps type-checkers happy.
+        raise last_error or GtwyConnectionError(f"Failed to reach {url}")

gtwy_sdk-0.1.0/gtwy/_exceptions.py

@@ -0,0 +1,75 @@
+"""Exception hierarchy for the GTWY SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class GtwyError(Exception):
+    """Base class for all errors raised by this SDK."""
+
+
+class GtwyConnectionError(GtwyError):
+    """Raised when the request could not reach the GTWY API at all."""
+
+
+class GtwyTimeoutError(GtwyConnectionError):
+    """Raised when a request exceeds the configured timeout."""
+
+
+class APIStatusError(GtwyError):
+    """Raised when the GTWY API responds with an error.
+
+    Mirrors the ``{"success": False, "error": "..."}`` envelope returned by
+    every GTWY route, plus non-2xx HTTP statuses raised before that envelope
+    can even be parsed (auth/middleware failures).
+    """
+
+    def __init__(self, message: str, *, status_code: int, body: Optional[Any] = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}"
+
+
+class BadRequestError(APIStatusError):
+    """HTTP 400 — malformed request body or invalid bridge configuration."""
+
+
+class AuthenticationError(APIStatusError):
+    """HTTP 401 — missing or invalid ``pauthkey``."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """HTTP 403 — organization disabled or blocked."""
+
+
+class NotFoundError(APIStatusError):
+    """HTTP 404 — bridge, thread, or message not found."""
+
+
+class RateLimitError(APIStatusError):
+    """HTTP 429 — too many requests for this bridge/thread."""
+
+
+class InternalServerError(APIStatusError):
+    """HTTP 5xx — unexpected failure on the GTWY side."""
+
+
+def error_for_status(status_code: int, message: str, body: Optional[Any]) -> APIStatusError:
+    if status_code == 400:
+        return BadRequestError(message, status_code=status_code, body=body)
+    if status_code == 401:
+        return AuthenticationError(message, status_code=status_code, body=body)
+    if status_code == 403:
+        return PermissionDeniedError(message, status_code=status_code, body=body)
+    if status_code == 404:
+        return NotFoundError(message, status_code=status_code, body=body)
+    if status_code == 429:
+        return RateLimitError(message, status_code=status_code, body=body)
+    if status_code >= 500:
+        return InternalServerError(message, status_code=status_code, body=body)
+    return APIStatusError(message, status_code=status_code, body=body)

gtwy_sdk-0.1.0/gtwy/_models.py

@@ -0,0 +1,123 @@
+"""Lightweight response wrappers.
+
+These intentionally avoid a pydantic dependency: GTWY route responses are
+plain JSON dicts, so each wrapper just gives attribute access on top of the
+raw dict while still exposing ``.to_dict()`` / ``.raw`` for anything the
+typed surface doesn't cover yet.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class GtwyObject:
+    """Attribute-access view over a raw API dict.
+
+    Unknown/untyped fields are still reachable via ``obj["field"]`` or
+    ``obj.raw``, so a newer API field never requires an SDK upgrade to read.
+    """
+
+    def __init__(self, raw: Dict[str, Any]):
+        self.raw = raw or {}
+
+    def __getitem__(self, key: str) -> Any:
+        return self.raw[key]
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.raw.get(key, default)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self.raw
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.raw!r})"
+
+
+class Usage(GtwyObject):
+    @property
+    def input_tokens(self) -> Optional[int]:
+        return self.raw.get("input_tokens")
+
+    @property
+    def output_tokens(self) -> Optional[int]:
+        return self.raw.get("output_tokens")
+
+    @property
+    def total_tokens(self) -> Optional[int]:
+        return self.raw.get("total_tokens")
+
+    @property
+    def cost(self) -> Optional[float]:
+        return self.raw.get("cost")
+
+
+class ChatCompletion(GtwyObject):
+    """Result of :meth:`gtwy.resources.chat.Completions.create`.
+
+    Wraps the synchronous ``{"success": true, "response": {"data": ..., "usage": ...}}``
+    envelope. When the bridge is configured for async (webhook) delivery, the
+    API instead returns a queuing acknowledgement — in that case ``content``
+    is ``None`` and ``message_id`` is the id to correlate with the
+    out-of-band delivery.
+    """
+
+    @property
+    def queued(self) -> bool:
+        return "response" not in self.raw
+
+    @property
+    def message_id(self) -> Optional[str]:
+        if self.queued:
+            return self.raw.get("message_id")
+        return self.data.get("message_id")
+
+    @property
+    def data(self) -> Dict[str, Any]:
+        return self.raw.get("response", {}).get("data", {}) or {}
+
+    @property
+    def content(self) -> Optional[str]:
+        content = self.data.get("content")
+        if isinstance(content, list):
+            return "\n".join(
+                chunk.get("text", "") if isinstance(chunk, dict) else str(chunk)
+                for chunk in content
+            ).strip()
+        return content
+
+    @property
+    def model(self) -> Optional[str]:
+        return self.data.get("model")
+
+    @property
+    def images(self) -> Optional[list]:
+        return self.data.get("images")
+
+    @property
+    def tools_data(self) -> Dict[str, Any]:
+        return self.data.get("tools_data", {}) or {}
+
+    @property
+    def usage(self) -> Usage:
+        return Usage(self.raw.get("response", {}).get("usage", {}) or {})
+
+
+class BatchCompletion(GtwyObject):
+    @property
+    def batch_id(self) -> Optional[str]:
+        return self.raw.get("batch_id")
+
+    @property
+    def messages(self) -> Optional[list]:
+        return self.raw.get("messages")
+
+
+class RerunResult(GtwyObject):
+    @property
+    def queued(self) -> list:
+        return self.raw.get("queued", [])
+
+    @property
+    def not_found(self) -> list:
+        return self.raw.get("not_found", [])

gtwy_sdk-0.1.0/gtwy/_skills.py

@@ -0,0 +1,19 @@
+"""Access to the packaged SKILLS.md reference doc.
+
+SKILLS.md ships inside the installed package (see pyproject.toml
+package-data) specifically so it survives a plain `pip install gtwy` and not
+just an editable checkout of this repo — an agent or IDE can locate it at
+runtime via `gtwy.SKILLS_PATH` / `gtwy.get_skills_doc()` without needing the
+source repo on disk.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+SKILLS_PATH: Path = Path(__file__).parent / "SKILLS.md"
+
+
+def get_skills_doc() -> str:
+    """Return the full contents of SKILLS.md as a string."""
+    return SKILLS_PATH.read_text(encoding="utf-8")

gtwy_sdk-0.1.0/gtwy/client.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from ._base_client import DEFAULT_MAX_RETRIES, BaseClient
+from .resources import Batch, Chat, Rerun
+
+
+class Gtwy(BaseClient):
+    """Client for the GTWY API.
+
+    Example:
+        >>> from gtwy import Gtwy
+        >>> client = Gtwy(api_key="<pauthkey>")
+        >>> response = client.chat.completions.create(
+        ...     agent_id="...",
+        ...     user="Hello!",
+        ... )
+        >>> print(response.content)
+
+    ``api_key`` is the org-level ``pauthkey`` from your GTWY dashboard (falls
+    back to the ``GTWY_API_KEY`` env var). ``base_url`` defaults to
+    ``https://api.gtwy.ai``; override it (or set ``GTWY_BASE_URL``) to point
+    at a different environment. See SKILLS.md for the full API reference and
+    every resource this client exposes.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        session: Optional[requests.Session] = None,
+    ):
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            session=session,
+        )
+        self.chat = Chat(self)
+        self.batch = Batch(self)
+        self.rerun = Rerun(self)

gtwy_sdk-0.1.0/gtwy/resources/__init__.py

@@ -0,0 +1,5 @@
+from .chat import Chat
+from .batch import Batch
+from .rerun import Rerun
+
+__all__ = ["Chat", "Batch", "Rerun"]

gtwy_sdk-0.1.0/gtwy/resources/batch.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._models import BatchCompletion
+
+_PATH = "/api/v2/model/batch/chat/completion"
+
+
+class BatchCompletions:
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        agent_id: str,
+        batch: List[str],
+        batch_webhook: str,
+        batch_variables: Optional[List[Dict[str, Any]]] = None,
+        thread_id: Optional[str] = None,
+        configuration: Optional[Dict[str, Any]] = None,
+        **extra: Any,
+    ) -> BatchCompletion:
+        """Run many prompts against one bridge in a single call.
+
+        ``batch`` is the list of per-message prompts; if given,
+        ``batch_variables`` must be the same length. Results are delivered to
+        ``batch_webhook`` — the immediate return value is just an
+        acknowledgement (``response.batch_id``).
+        """
+        if batch_variables is not None and len(batch_variables) != len(batch):
+            raise ValueError("batch_variables must have the same length as batch")
+
+        body: Dict[str, Any] = {
+            "agent_id": agent_id,
+            "batch": batch,
+            "batch_webhook": batch_webhook,
+            "batch_variables": batch_variables,
+            "thread_id": thread_id,
+            "configuration": configuration,
+            **extra,
+        }
+        raw = self._client.post(_PATH, body)
+        return BatchCompletion(raw)
+
+
+class Batch:
+    def __init__(self, client):
+        self.completions = BatchCompletions(client)

gtwy_sdk-0.1.0/gtwy/resources/chat.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._models import ChatCompletion
+
+_PATH = "/api/v2/model/chat/completion"
+
+
+class Completions:
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        agent_id: str,
+        user: Optional[str] = None,
+        messages: Optional[List[Dict[str, Any]]] = None,
+        thread_id: Optional[str] = None,
+        sub_thread_id: Optional[str] = None,
+        variables: Optional[Dict[str, Any]] = None,
+        variables_path: Optional[str] = None,
+        configuration: Optional[Dict[str, Any]] = None,
+        version_id: Optional[str] = None,
+        service: Optional[str] = None,
+        apikey: Optional[str] = None,
+        user_urls: Optional[List[Dict[str, str]]] = None,
+        auto_model_select: Optional[bool] = None,
+        cache_on: Optional[bool] = None,
+        stream: Optional[bool] = None,
+        settings: Optional[Dict[str, Any]] = None,
+        extra_tools: Optional[List[Dict[str, Any]]] = None,
+        built_in_tools: Optional[List[Dict[str, Any]]] = None,
+        guardrails: Optional[Dict[str, Any]] = None,
+        web_search_filters: Optional[Dict[str, Any]] = None,
+        orchestrator_flag: Optional[bool] = None,
+        environment: Optional[str] = None,
+        **extra: Any,
+    ) -> ChatCompletion:
+        """Send one message to a bridge/agent and get its reply.
+
+        Exactly one of ``user`` or ``messages`` is normally supplied. By
+        default the call is synchronous and ``response.content`` has the
+        reply. If the bridge's delivery mode (``settings.response_format``)
+        is ``webhook``, the API instead queues the request and returns
+        immediately — check ``response.queued`` and correlate the async
+        result with ``response.message_id``. See SKILLS.md for the full
+        field reference and delivery modes.
+
+        ``settings`` is a general passthrough for the request's ``settings``
+        object, e.g. ``{"response_format": {"type": "webhook", "cred": {...}}}``
+        or ``{"fall_back": {"is_enable": True, "service": "openai", "model": "gpt-4o-mini"}}``.
+
+        Any keyword not listed here is passed through verbatim via
+        ``**extra`` for forwards-compatibility with new API fields.
+        """
+        body: Dict[str, Any] = {
+            "agent_id": agent_id,
+            "user": user,
+            "messages": messages,
+            "thread_id": thread_id,
+            "sub_thread_id": sub_thread_id,
+            "variables": variables,
+            "variables_path": variables_path,
+            "configuration": configuration,
+            "version_id": version_id,
+            "service": service,
+            "apikey": apikey,
+            "user_urls": user_urls,
+            "auto_model_select": auto_model_select,
+            "cache_on": cache_on,
+            "stream": stream,
+            "extra_tools": extra_tools,
+            "built_in_tools": built_in_tools,
+            "guardrails": guardrails,
+            "web_search_filters": web_search_filters,
+            "orchestrator_flag": orchestrator_flag,
+            "environment": environment,
+            **extra,
+        }
+        if settings is not None:
+            body["settings"] = settings
+
+        raw = self._client.post(_PATH, body)
+        return ChatCompletion(raw)
+
+
+class Chat:
+    """Namespace mirroring ``client.chat.completions.create(...)``."""
+
+    def __init__(self, client):
+        self.completions = Completions(client)

gtwy_sdk-0.1.0/gtwy/resources/rerun.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .._models import RerunResult
+
+_PATH = "/api/v2/model/rerun"
+
+
+class Rerun:
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        *,
+        agent_id: str,
+        message_ids: Optional[List[str]] = None,
+        thread_id: Optional[str] = None,
+        sub_thread_id: Optional[str] = None,
+        **extra: Any,
+    ) -> RerunResult:
+        """Rerun previous message(s) with the bridge's current configuration.
+
+        Provide either ``message_ids``, or both ``thread_id`` and
+        ``sub_thread_id`` (reruns the last message in that thread). Results
+        are delivered per the bridge's configured ``response_format``, not
+        returned inline here.
+        """
+        if not message_ids and not (thread_id and sub_thread_id):
+            raise ValueError("Provide either message_ids, or both thread_id and sub_thread_id")
+
+        body: Dict[str, Any] = {
+            "agent_id": agent_id,
+            "message_ids": message_ids,
+            "thread_id": thread_id,
+            "sub_thread_id": sub_thread_id,
+            **extra,
+        }
+        raw = self._client.post(_PATH, body)
+        return RerunResult(raw)

gtwy_sdk-0.1.0/gtwy_sdk.egg-info/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: gtwy-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the GTWY API — build and call agentic AI, RAG, and LLM-powered agents
+Author: GTWY
+License: MIT
+Project-URL: Homepage, https://gtwy.ai
+Keywords: gtwy,ai,llm,agents,agentic ai,rag,chatbot,sdk,api client
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.25
+Dynamic: license-file
+
+# gtwy-sdk
+
+Official Python client for the GTWY API — build and call agentic AI, RAG,
+and LLM-powered agents.
+
+```bash
+pip install gtwy-sdk
+```
+
+```python
+from gtwy import Gtwy
+
+client = Gtwy(api_key="<pauthkey>")
+
+response = client.chat.completions.create(
+    agent_id="my-agent-id",
+    user="What's the capital of France?",
+)
+print(response.content)
+```
+
+`api_key` can also come from the `GTWY_API_KEY` environment variable.
+`base_url` defaults to `https://api.gtwy.ai`; override it (constructor arg or
+`GTWY_BASE_URL`) to point at a different environment.
+
+See [gtwy/SKILLS.md](./gtwy/SKILLS.md) for the full reference: every resource
+(`chat`, `batch`, `rerun`), every request field, response
+shapes, delivery modes (sync/webhook), and error handling. This file
+ships **inside** the installed package (not just this repo) — after
+`pip install gtwy-sdk` it's reachable at `gtwy.SKILLS_PATH` /
+`gtwy.get_skills_doc()`, so an AI agent (e.g. Claude) can read it and use
+this SDK correctly without ever cloning this repo.
+
+## Development
+
+```bash
+cd python
+pip install -e .
+```

gtwy_sdk-0.1.0/gtwy_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+gtwy/SKILLS.md
+gtwy/__init__.py
+gtwy/_base_client.py
+gtwy/_exceptions.py
+gtwy/_models.py
+gtwy/_skills.py
+gtwy/client.py
+gtwy/resources/__init__.py
+gtwy/resources/batch.py
+gtwy/resources/chat.py
+gtwy/resources/rerun.py
+gtwy_sdk.egg-info/PKG-INFO
+gtwy_sdk.egg-info/SOURCES.txt
+gtwy_sdk.egg-info/dependency_links.txt
+gtwy_sdk.egg-info/requires.txt
+gtwy_sdk.egg-info/top_level.txt

gtwy_sdk-0.1.0/gtwy_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gtwy_sdk-0.1.0/gtwy_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests<3,>=2.25

gtwy_sdk-0.1.0/gtwy_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+gtwy

gtwy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gtwy-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the GTWY API — build and call agentic AI, RAG, and LLM-powered agents"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "GTWY" }]
+keywords = [
+    "gtwy",
+    "ai",
+    "llm",
+    "agents",
+    "agentic ai",
+    "rag",
+    "chatbot",
+    "sdk",
+    "api client",
+]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "requests>=2.25,<3",
+]
+
+[project.urls]
+Homepage = "https://gtwy.ai"
+
+[tool.setuptools.packages.find]
+include = ["gtwy*"]
+
+[tool.setuptools.package-data]
+gtwy = ["SKILLS.md"]

gtwy_sdk-0.1.0/setup.cfg

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