guidon-sdk 0.1.0__tar.gz

guidon_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.venv/

guidon_sdk-0.1.0/LICENSE

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

guidon_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: guidon-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Guidon REST API (/api/v1).
+Project-URL: Homepage, https://useguidon.com
+Project-URL: Source, https://github.com/Two-Steps-Studio/guidon
+Project-URL: Documentation, https://github.com/Two-Steps-Studio/guidon/tree/main/sdk/python#readme
+Project-URL: Issues, https://github.com/Two-Steps-Studio/guidon/issues
+Author: Two Steps Studio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,guidon,project-management,sdk,tasks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# guidon-sdk - Python SDK for Guidon
+
+Official Python client for the [Guidon](https://useguidon.com) REST API
+(`/api/v1`): projects, tasks, subtasks, comments, attempts, bug reports and
+project knowledge (decisions, knowledge sources, roadmap, memory, tech stack).
+
+- Standard library only (`urllib`), no dependencies.
+- Python 3.9+.
+- Works with Guidon Cloud (`https://useguidon.com`) and self-hosted instances.
+
+## Install
+
+The PyPI release is pending. The command below will work after the `guidon-sdk` package is published. The import name remains `guidon`.
+
+```bash
+pip install guidon-sdk
+```
+
+## Authenticate
+
+Create an API key in Guidon: **Profile -> API keys**. A key acts as you, limited
+to the scopes you gave it (`tasks:read`, `tasks:write`, `tasks:status`,
+`comments:write`, `attempts:write`, `project:read`, `project:write`,
+`reports:write`).
+
+```python
+from guidon import Guidon
+
+guidon = Guidon(api_key="guidon_...")          # or set GUIDON_API_KEY
+# Self-hosted:
+guidon = Guidon(api_key="guidon_...", base_url="https://guidon.example.com")  # or GUIDON_BASE_URL
+```
+
+## Usage
+
+```python
+project = guidon.projects.list()[0]
+
+columns = guidon.projects.columns(project["id"])        # the board's column keys
+todo = guidon.tasks.list(project["id"], status="todo")  # filters applied client-side
+
+task = guidon.tasks.create(project["id"], "Fix the jump", priority="high", status="todo")
+guidon.tasks.update(task["id"], description="Feels floaty on 30 Hz monitors")
+guidon.tasks.move(task["id"], "in_progress")
+guidon.comments.create(task["id"], "Started on this")
+
+sub = guidon.subtasks.create(project["id"], task["id"], "Write a repro")
+print(guidon.tasks.context(task["id"]))                 # Markdown working context
+
+guidon.attempts.record(
+    task["id"], problem="Jump height varies", approach="Fixed timestep", outcome="partial",
+    files_changed=["src/player.gd"],
+)
+
+guidon.decisions.create(project["id"], title="Use Godot 4.4", decision_type="technical")
+guidon.memory.create(project["id"], content="Builds ship from main only", memory_type="project_rule")
+```
+
+| Attribute | Methods |
+| --- | --- |
+| `projects` | `list()`, `columns(pid)`, `priorities(pid)`, `references(pid)` |
+| `tasks` | `list(pid, status=, parent_task_id=)`, `list_page(pid, limit=, cursor=)`, `iter(pid)`, `get`, `create`, `update`, `move`, `delete`, `start`, `complete`, `context` |
+| `subtasks` | `list(pid, parent_id)`, `create(pid, parent_id, title, ...)` |
+| `comments` | `list(task_id)`, `create(task_id, content)` |
+| `attempts` | `list(task_id)`, `record(task_id, problem=, approach=, outcome=, ...)` |
+| `reports` | `file(pid, title, files=[(name, bytes, content_type)], ...)` |
+| `decisions`, `knowledge`, `roadmap`, `memory`, `technologies` | `list(pid)`, `get(pid, id)`, `create(pid, **fields)`, `update(pid, id, **fields)`, `delete(pid, id)` |
+| `request(method, path, query=, json=)` | escape hatch for routes not wrapped yet |
+
+Results are the API's JSON objects as plain `dict`s.
+
+### Idempotency
+
+Every write method takes `idempotency_key=...`, sent as the `Idempotency-Key`
+header. Reuse the same key when retrying the same logical write. With a key, the
+SDK also retries the write automatically on 429/502/503/504 and network errors.
+
+### Errors
+
+Everything raises `guidon.GuidonError`:
+
+```python
+from guidon import GuidonError
+
+try:
+    guidon.tasks.move(task_id, "done")
+except GuidonError as e:
+    print(e.status, e.code, e.message)   # 404 not_found Task not found.
+```
+
+- `status`: HTTP status, `0` when no response was received.
+- `code`: the server's `code` if it sent one, else derived from the status with
+  the server's own table (`invalid_request`, `unauthorized`, `forbidden`,
+  `not_found`, `conflict`, `unprocessable`, `rate_limited`, `internal_error`,
+  `unavailable`...); or `network_error`, `timeout`, `invalid_response`,
+  `missing_api_key`, `invalid_base_url` when there was no usable response.
+- `message`: the `error` text from the JSON body (`{"error": "..."}`).
+- `hint`, `docs`: the server's "what to do now" and docs link, when sent.
+- also `body`, `retry_after`, `request_id`, `method`, `url`.
+
+GET requests are retried (default `max_retries=2`) on 429/502/503/504 and network
+errors, honouring `Retry-After`. Writes are retried only with an
+`idempotency_key` (then also on 409 `idempotency_in_progress`).
+
+### Pagination
+
+The task list is cursor-paginated (newest first, up to 1000 per page):
+
+```python
+for task in guidon.tasks.iter(project_id, page_size=200):   # fetched page by page
+    print(task["title"])
+
+page = guidon.tasks.list_page(project_id, limit=100)        # {"tasks": [...], "next_cursor": ...}
+while page["next_cursor"]:
+    page = guidon.tasks.list_page(project_id, limit=100, cursor=page["next_cursor"])
+```
+
+`tasks.list()` fetches every page and returns a list; its `status` and
+`parent_task_id` filters run client-side (the API has no server-side filters).
+Against a server that doesn't paginate yet, the first page is the whole list.
+The other list endpoints return everything in one response (up to 500 items
+for the knowledge collections).
+
+## Development
+
+```bash
+cd sdk/python
+python -m unittest discover -s tests -v   # mock http.server, no network
+python -m build                           # needs `pip install build`
+```
+
+Links: [Homepage](https://useguidon.com) - [Source](https://github.com/Two-Steps-Studio/guidon/tree/main/sdk/python) - API reference: `https://useguidon.com/openapi.json`
+
+## License
+
+MIT - see [LICENSE](LICENSE). This licence covers this SDK/CLI package, not the Guidon service or the rest of the application.

guidon_sdk-0.1.0/README.md

@@ -0,0 +1,136 @@
+# guidon-sdk - Python SDK for Guidon
+
+Official Python client for the [Guidon](https://useguidon.com) REST API
+(`/api/v1`): projects, tasks, subtasks, comments, attempts, bug reports and
+project knowledge (decisions, knowledge sources, roadmap, memory, tech stack).
+
+- Standard library only (`urllib`), no dependencies.
+- Python 3.9+.
+- Works with Guidon Cloud (`https://useguidon.com`) and self-hosted instances.
+
+## Install
+
+The PyPI release is pending. The command below will work after the `guidon-sdk` package is published. The import name remains `guidon`.
+
+```bash
+pip install guidon-sdk
+```
+
+## Authenticate
+
+Create an API key in Guidon: **Profile -> API keys**. A key acts as you, limited
+to the scopes you gave it (`tasks:read`, `tasks:write`, `tasks:status`,
+`comments:write`, `attempts:write`, `project:read`, `project:write`,
+`reports:write`).
+
+```python
+from guidon import Guidon
+
+guidon = Guidon(api_key="guidon_...")          # or set GUIDON_API_KEY
+# Self-hosted:
+guidon = Guidon(api_key="guidon_...", base_url="https://guidon.example.com")  # or GUIDON_BASE_URL
+```
+
+## Usage
+
+```python
+project = guidon.projects.list()[0]
+
+columns = guidon.projects.columns(project["id"])        # the board's column keys
+todo = guidon.tasks.list(project["id"], status="todo")  # filters applied client-side
+
+task = guidon.tasks.create(project["id"], "Fix the jump", priority="high", status="todo")
+guidon.tasks.update(task["id"], description="Feels floaty on 30 Hz monitors")
+guidon.tasks.move(task["id"], "in_progress")
+guidon.comments.create(task["id"], "Started on this")
+
+sub = guidon.subtasks.create(project["id"], task["id"], "Write a repro")
+print(guidon.tasks.context(task["id"]))                 # Markdown working context
+
+guidon.attempts.record(
+    task["id"], problem="Jump height varies", approach="Fixed timestep", outcome="partial",
+    files_changed=["src/player.gd"],
+)
+
+guidon.decisions.create(project["id"], title="Use Godot 4.4", decision_type="technical")
+guidon.memory.create(project["id"], content="Builds ship from main only", memory_type="project_rule")
+```
+
+| Attribute | Methods |
+| --- | --- |
+| `projects` | `list()`, `columns(pid)`, `priorities(pid)`, `references(pid)` |
+| `tasks` | `list(pid, status=, parent_task_id=)`, `list_page(pid, limit=, cursor=)`, `iter(pid)`, `get`, `create`, `update`, `move`, `delete`, `start`, `complete`, `context` |
+| `subtasks` | `list(pid, parent_id)`, `create(pid, parent_id, title, ...)` |
+| `comments` | `list(task_id)`, `create(task_id, content)` |
+| `attempts` | `list(task_id)`, `record(task_id, problem=, approach=, outcome=, ...)` |
+| `reports` | `file(pid, title, files=[(name, bytes, content_type)], ...)` |
+| `decisions`, `knowledge`, `roadmap`, `memory`, `technologies` | `list(pid)`, `get(pid, id)`, `create(pid, **fields)`, `update(pid, id, **fields)`, `delete(pid, id)` |
+| `request(method, path, query=, json=)` | escape hatch for routes not wrapped yet |
+
+Results are the API's JSON objects as plain `dict`s.
+
+### Idempotency
+
+Every write method takes `idempotency_key=...`, sent as the `Idempotency-Key`
+header. Reuse the same key when retrying the same logical write. With a key, the
+SDK also retries the write automatically on 429/502/503/504 and network errors.
+
+### Errors
+
+Everything raises `guidon.GuidonError`:
+
+```python
+from guidon import GuidonError
+
+try:
+    guidon.tasks.move(task_id, "done")
+except GuidonError as e:
+    print(e.status, e.code, e.message)   # 404 not_found Task not found.
+```
+
+- `status`: HTTP status, `0` when no response was received.
+- `code`: the server's `code` if it sent one, else derived from the status with
+  the server's own table (`invalid_request`, `unauthorized`, `forbidden`,
+  `not_found`, `conflict`, `unprocessable`, `rate_limited`, `internal_error`,
+  `unavailable`...); or `network_error`, `timeout`, `invalid_response`,
+  `missing_api_key`, `invalid_base_url` when there was no usable response.
+- `message`: the `error` text from the JSON body (`{"error": "..."}`).
+- `hint`, `docs`: the server's "what to do now" and docs link, when sent.
+- also `body`, `retry_after`, `request_id`, `method`, `url`.
+
+GET requests are retried (default `max_retries=2`) on 429/502/503/504 and network
+errors, honouring `Retry-After`. Writes are retried only with an
+`idempotency_key` (then also on 409 `idempotency_in_progress`).
+
+### Pagination
+
+The task list is cursor-paginated (newest first, up to 1000 per page):
+
+```python
+for task in guidon.tasks.iter(project_id, page_size=200):   # fetched page by page
+    print(task["title"])
+
+page = guidon.tasks.list_page(project_id, limit=100)        # {"tasks": [...], "next_cursor": ...}
+while page["next_cursor"]:
+    page = guidon.tasks.list_page(project_id, limit=100, cursor=page["next_cursor"])
+```
+
+`tasks.list()` fetches every page and returns a list; its `status` and
+`parent_task_id` filters run client-side (the API has no server-side filters).
+Against a server that doesn't paginate yet, the first page is the whole list.
+The other list endpoints return everything in one response (up to 500 items
+for the knowledge collections).
+
+## Development
+
+```bash
+cd sdk/python
+python -m unittest discover -s tests -v   # mock http.server, no network
+python -m build                           # needs `pip install build`
+```
+
+Links: [Homepage](https://useguidon.com) - [Source](https://github.com/Two-Steps-Studio/guidon/tree/main/sdk/python) - API reference: `https://useguidon.com/openapi.json`
+
+## License
+
+MIT - see [LICENSE](LICENSE). This licence covers this SDK/CLI package, not the Guidon service or the rest of the application.

guidon_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "guidon-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Guidon REST API (/api/v1)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Two Steps Studio" }]
+keywords = ["guidon", "project-management", "tasks", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://useguidon.com"
+Source = "https://github.com/Two-Steps-Studio/guidon"
+Documentation = "https://github.com/Two-Steps-Studio/guidon/tree/main/sdk/python#readme"
+Issues = "https://github.com/Two-Steps-Studio/guidon/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/guidon"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/guidon", "tests", "README.md", "pyproject.toml", "LICENSE"]

guidon_sdk-0.1.0/src/guidon/__init__.py

@@ -0,0 +1,33 @@
+"""Official Python SDK for the Guidon REST API (https://useguidon.com)."""
+
+from ._http import DEFAULT_BASE_URL, normalize_base_url
+from ._version import __version__
+from .client import (
+    UNSET,
+    AttemptsResource,
+    CommentsResource,
+    Guidon,
+    ProjectCollection,
+    ProjectsResource,
+    ReportsResource,
+    SubtasksResource,
+    TasksResource,
+)
+from .errors import GuidonError, code_for_status
+
+__all__ = [
+    "Guidon",
+    "GuidonError",
+    "code_for_status",
+    "normalize_base_url",
+    "DEFAULT_BASE_URL",
+    "UNSET",
+    "ProjectsResource",
+    "TasksResource",
+    "SubtasksResource",
+    "CommentsResource",
+    "AttemptsResource",
+    "ReportsResource",
+    "ProjectCollection",
+    "__version__",
+]

guidon_sdk-0.1.0/src/guidon/_http.py

@@ -0,0 +1,273 @@
+"""Transport: auth, JSON, errors and retries over urllib (standard library only)."""
+
+from __future__ import annotations
+
+import email.utils
+import json
+import os
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, Iterable, Mapping, Optional, Tuple, Union
+
+from ._version import __version__
+from .errors import GuidonError, code_for_status
+
+DEFAULT_BASE_URL = "https://useguidon.com"
+_API_PREFIX = "/api/v1"
+_RETRYABLE_STATUS = {429, 502, 503, 504}
+
+FileTuple = Tuple[str, Union[bytes, str], Optional[str]]
+
+
+def normalize_base_url(raw: str) -> str:
+    """``https://host`` or ``https://host/api/v1/`` -> ``https://host/api/v1``."""
+    parsed = urllib.parse.urlsplit(raw.strip())
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        raise GuidonError(f"Guidon base URL must be an http(s) URL: {raw}", code="invalid_base_url")
+    path = parsed.path.rstrip("/")
+    if not path.endswith(_API_PREFIX):
+        path += _API_PREFIX
+    return f"{parsed.scheme}://{parsed.netloc}{path}"
+
+
+def _parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        seconds = float(value)
+        return seconds if seconds >= 0 else None
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, when.timestamp() - time.time())
+
+
+def encode_multipart(fields: Mapping[str, str], files: Iterable[FileTuple]) -> Tuple[bytes, str]:
+    boundary = f"----guidon{uuid.uuid4().hex}"
+    out = bytearray()
+    for name, value in fields.items():
+        out += f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"\r\n\r\n".encode()
+        out += value.encode("utf-8") + b"\r\n"
+    for filename, data, content_type in files:
+        safe = filename.replace('"', "%22").replace("\r", "").replace("\n", "")
+        out += (
+            f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{safe}\"\r\n"
+            f"Content-Type: {content_type or 'application/octet-stream'}\r\n\r\n"
+        ).encode()
+        out += (data.encode("utf-8") if isinstance(data, str) else bytes(data)) + b"\r\n"
+    out += f"--{boundary}--\r\n".encode()
+    return bytes(out), f"multipart/form-data; boundary={boundary}"
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Follows redirects but never forwards the API key to another host."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        new = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new is not None:
+            old_host = urllib.parse.urlsplit(req.full_url)
+            new_host = urllib.parse.urlsplit(new.full_url)
+            if (old_host.scheme, old_host.netloc) != (new_host.scheme, new_host.netloc):
+                for name in list(new.headers):
+                    if name.lower() == "authorization":
+                        del new.headers[name]
+                new.unredirected_hdrs.pop("Authorization", None)
+        return new
+
+
+class _Multipart:
+    def __init__(self, fields: Mapping[str, str], files: Iterable[FileTuple]) -> None:
+        self.fields = dict(fields)
+        self.files = list(files)
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        user_agent: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        api_key = api_key or os.environ.get("GUIDON_API_KEY")
+        if not api_key:
+            raise GuidonError(
+                "No Guidon API key. Pass api_key=... or set GUIDON_API_KEY (create one in Profile -> API keys).",
+                code="missing_api_key",
+            )
+        self._api_key = api_key
+        self.base_url = normalize_base_url(base_url or os.environ.get("GUIDON_BASE_URL") or DEFAULT_BASE_URL)
+        self.timeout = timeout
+        self.max_retries = max(0, max_retries)
+        self._opener = opener or urllib.request.build_opener(_SafeRedirectHandler())
+        ua = f"guidon-sdk-python/{__version__}"
+        self._headers: Dict[str, str] = {"User-Agent": f"{ua} {user_agent}" if user_agent else ua}
+        self._headers.update(headers or {})
+
+    def url(self, path: str, query: Optional[Mapping[str, Any]] = None) -> str:
+        url = self.base_url + path
+        params = {k: ("true" if v is True else "false" if v is False else str(v)) for k, v in (query or {}).items() if v is not None}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        return url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        multipart: Optional[_Multipart] = None,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        response_type: str = "json",
+    ) -> Any:
+        method = method.upper()
+        url = self.url(path, query)
+        all_headers = {
+            "Accept": "text/markdown, text/plain, application/json" if response_type == "text" else "application/json",
+            **self._headers,
+            **(headers or {}),
+            "Authorization": f"Bearer {self._api_key}",
+        }
+        data: Optional[bytes] = None
+        if multipart is not None:
+            data, content_type = encode_multipart(multipart.fields, multipart.files)
+            all_headers["Content-Type"] = content_type
+        elif json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            all_headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            all_headers["Idempotency-Key"] = idempotency_key
+
+        retryable = method == "GET" or bool(idempotency_key)
+        attempts = self.max_retries + 1 if retryable else 1
+        effective_timeout = self.timeout if timeout is None else timeout
+
+        attempt = 0
+        while True:
+            attempt += 1
+            req = urllib.request.Request(url, data=data, method=method, headers=all_headers)
+            try:
+                with self._opener.open(req, timeout=effective_timeout) as resp:
+                    raw = resp.read()
+                    status = resp.status
+                    content_type = resp.headers.get("Content-Type")
+            except urllib.error.HTTPError as http_error:
+                try:
+                    error = self._error_from_response(http_error, method, url)
+                finally:
+                    http_error.close()
+                # 409 idempotency_in_progress: the first request with this key is still running.
+                in_progress = error.status == 409 and error.code == "idempotency_in_progress"
+                if attempt < attempts and (error.status in _RETRYABLE_STATUS or in_progress):
+                    wait = error.retry_after if error.retry_after is not None else self._backoff(attempt)
+                    time.sleep(min(wait, 60.0))
+                    continue
+                raise error from None
+            except (socket.timeout, TimeoutError) as exc:
+                error = GuidonError(
+                    f"Request timed out after {effective_timeout} s.", code="timeout", method=method, url=url
+                )
+                if attempt < attempts:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise error from exc
+            except urllib.error.URLError as exc:
+                reason = exc.reason
+                if isinstance(reason, (socket.timeout, TimeoutError)):
+                    error = GuidonError(
+                        f"Request timed out after {effective_timeout} s.", code="timeout", method=method, url=url
+                    )
+                else:
+                    error = GuidonError(
+                        f"Could not reach Guidon at {self.base_url}: {reason}",
+                        code="network_error",
+                        method=method,
+                        url=url,
+                    )
+                if attempt < attempts:
+                    time.sleep(self._backoff(attempt))
+                    continue
+                raise error from exc
+
+            text = raw.decode("utf-8", errors="replace")
+            if response_type == "text":
+                return text
+            if not text:
+                return None
+            try:
+                return json.loads(text)
+            except ValueError:
+                raise GuidonError(
+                    f"Expected JSON from {method} {url}, got {content_type or 'an unknown content type'}.",
+                    status=status,
+                    code="invalid_response",
+                    body=text[:2000],
+                    method=method,
+                    url=url,
+                ) from None
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        base = min(8.0, 0.5 * 2 ** (attempt - 1))
+        return base / 2 + random.random() * base / 2
+
+    @staticmethod
+    def _error_from_response(resp: urllib.error.HTTPError, method: str, url: str) -> GuidonError:
+        try:
+            text = resp.read().decode("utf-8", errors="replace")
+        except Exception:  # pragma: no cover - broken connection while reading the error
+            text = ""
+        body: Any = None
+        if text:
+            try:
+                body = json.loads(text)
+            except ValueError:
+                body = text
+        message: Optional[str] = None
+        code: Optional[str] = None
+        hint: Optional[str] = None
+        docs: Optional[str] = None
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, str):
+                message = err
+            elif isinstance(err, dict) and isinstance(err.get("message"), str):
+                message = err["message"]
+            elif isinstance(body.get("message"), str):
+                message = body["message"]
+            if isinstance(body.get("code"), str) and body["code"]:
+                code = body["code"]
+            if isinstance(body.get("hint"), str) and body["hint"]:
+                hint = body["hint"]
+            if isinstance(body.get("docs"), str) and body["docs"]:
+                docs = body["docs"]
+        status = resp.code
+        headers = resp.headers
+        return GuidonError(
+            message or f"HTTP {status} {resp.reason or ''}".strip(),
+            status=status,
+            code=code or code_for_status(status),
+            body=body,
+            hint=hint,
+            docs=docs,
+            retry_after=_parse_retry_after(headers.get("Retry-After") if headers else None),
+            request_id=(headers.get("X-Request-Id") or headers.get("X-Vercel-Id")) if headers else None,
+            method=method,
+            url=url,
+        )

guidon_sdk-0.1.0/src/guidon/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"