guidon-sdk 0.1.0__py3-none-any.whl

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/_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/_version.py

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

guidon/client.py

@@ -0,0 +1,399 @@
+"""Client for the Guidon REST API (/api/v1)."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterable, Iterator, List, Mapping, Optional, Sequence, Union
+
+from ._http import FileTuple, HttpClient, _Multipart
+
+JSON = Dict[str, Any]
+
+
+class _Unset:
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+UNSET: Any = _Unset()
+
+
+def _seg(value: str, name: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{name} must be a non-empty string")
+    return urllib.parse.quote(value, safe="")
+
+
+def _drop_unset(fields: Mapping[str, Any]) -> JSON:
+    return {k: v for k, v in fields.items() if v is not UNSET}
+
+
+class _Resource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+
+class ProjectsResource(_Resource):
+    """Projects the key's user belongs to, and their board configuration."""
+
+    def list(self) -> List[JSON]:
+        """GET /projects. Scope ``tasks:read``."""
+        return self._http.request("GET", "/projects")["projects"]
+
+    def columns(self, project_id: str) -> List[JSON]:
+        """GET /projects/{id}/columns - visible board columns, in order."""
+        return self._http.request("GET", f"/projects/{_seg(project_id, 'project_id')}/columns")["columns"]
+
+    def priorities(self, project_id: str) -> List[JSON]:
+        """GET /projects/{id}/priorities - most important first."""
+        return self._http.request("GET", f"/projects/{_seg(project_id, 'project_id')}/priorities")["priorities"]
+
+    def references(self, project_id: str) -> List[JSON]:
+        """GET /projects/{id}/references - moodboard images with short-lived signed URLs."""
+        return self._http.request("GET", f"/projects/{_seg(project_id, 'project_id')}/references")["references"]
+
+
+class TasksResource(_Resource):
+    """Board cards."""
+
+    def list_page(self, project_id: str, *, limit: Optional[int] = None, cursor: Optional[str] = None) -> JSON:
+        """GET /projects/{id}/tasks - one page, newest first. Scope ``tasks:read``.
+
+        Returns ``{"tasks": [...], "next_cursor": str | None}``; pass
+        ``next_cursor`` as ``cursor`` for the next page. ``limit``: 1-1000
+        (server default 1000).
+        """
+        res = self._http.request(
+            "GET", f"/projects/{_seg(project_id, 'project_id')}/tasks", query={"limit": limit, "cursor": cursor}
+        )
+        return {"tasks": res.get("tasks") or [], "next_cursor": res.get("next_cursor")}
+
+    def iter(self, project_id: str, *, page_size: Optional[int] = None) -> Iterator[JSON]:
+        """Every task of the project, newest first, fetched page by page as you iterate."""
+        cursor: Optional[str] = None
+        seen = set()
+        while True:
+            page = self.list_page(project_id, limit=page_size, cursor=cursor)
+            yield from page["tasks"]
+            cursor = page["next_cursor"]
+            if not cursor or cursor in seen:
+                return
+            seen.add(cursor)
+
+    def list(
+        self,
+        project_id: str,
+        *,
+        status: Union[str, Sequence[str], None] = None,
+        parent_task_id: Any = UNSET,
+        page_size: Optional[int] = None,
+    ) -> List[JSON]:
+        """All of the project's tasks (every page), newest first. Scope ``tasks:read``.
+
+        ``status`` and ``parent_task_id`` (``None`` for top-level tasks only)
+        are applied client-side - the API has no server-side filters yet.
+        """
+        tasks: List[JSON] = list(self.iter(project_id, page_size=page_size))
+        if status is not None:
+            wanted = {status} if isinstance(status, str) else set(status)
+            tasks = [t for t in tasks if t.get("status") in wanted]
+        if parent_task_id is not UNSET:
+            tasks = [t for t in tasks if t.get("parent_task_id") == parent_task_id]
+        return tasks
+
+    def get(self, task_id: str) -> JSON:
+        """GET /tasks/{id}."""
+        return self._http.request("GET", f"/tasks/{_seg(task_id, 'task_id')}")["task"]
+
+    def create(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: Optional[str] = None,
+        priority: Optional[str] = None,
+        status: Optional[str] = None,
+        due_date: Optional[str] = None,
+        parent_task_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """POST /projects/{id}/tasks. Scope ``tasks:write``.
+
+        A top-level task defaults to ``backlog``/``medium``; with
+        ``parent_task_id`` it is a subtask and starts as ``todo``/``medium``.
+        """
+        body: JSON = {"title": title}
+        for key, value in (
+            ("description", description),
+            ("priority", priority),
+            ("status", status),
+            ("due_date", due_date),
+            ("parent_task_id", parent_task_id),
+        ):
+            if value is not None:
+                body[key] = value
+        return self._http.request(
+            "POST", f"/projects/{_seg(project_id, 'project_id')}/tasks", json_body=body, idempotency_key=idempotency_key
+        )["task"]
+
+    def update(
+        self,
+        task_id: str,
+        *,
+        title: Any = UNSET,
+        description: Any = UNSET,
+        priority: Any = UNSET,
+        due_date: Any = UNSET,
+        sort_order: Any = UNSET,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """PATCH /tasks/{id} - edit fields (not the status: use :meth:`move`).
+
+        Only the fields you pass are sent; ``description=None`` / ``due_date=None`` clear them.
+        """
+        body = _drop_unset(
+            {"title": title, "description": description, "priority": priority, "due_date": due_date, "sort_order": sort_order}
+        )
+        if not body:
+            raise ValueError("update() needs at least one field")
+        return self._http.request(
+            "PATCH", f"/tasks/{_seg(task_id, 'task_id')}", json_body=body, idempotency_key=idempotency_key
+        )["task"]
+
+    def move(self, task_id: str, status: str, *, idempotency_key: Optional[str] = None) -> JSON:
+        """PATCH /tasks/{id}/status - move the task to another column. Scope ``tasks:status``."""
+        return self._http.request(
+            "PATCH", f"/tasks/{_seg(task_id, 'task_id')}/status", json_body={"status": status}, idempotency_key=idempotency_key
+        )["task"]
+
+    def delete(self, task_id: str, *, idempotency_key: Optional[str] = None) -> None:
+        """DELETE /tasks/{id} - permanent (project owner/admin)."""
+        self._http.request("DELETE", f"/tasks/{_seg(task_id, 'task_id')}", idempotency_key=idempotency_key)
+
+    def start(self, task_id: str, *, idempotency_key: Optional[str] = None) -> JSON:
+        """POST /tasks/{id}/start - claim the task. Scope ``tasks:status``."""
+        return self._http.request("POST", f"/tasks/{_seg(task_id, 'task_id')}/start", idempotency_key=idempotency_key)["task"]
+
+    def complete(self, task_id: str, *, idempotency_key: Optional[str] = None) -> JSON:
+        """POST /tasks/{id}/complete - mark done, if the project allows AI auto-complete."""
+        return self._http.request("POST", f"/tasks/{_seg(task_id, 'task_id')}/complete", idempotency_key=idempotency_key)[
+            "task"
+        ]
+
+    def context(self, task_id: str) -> str:
+        """GET /tasks/{id}/context - everything needed to do the task, as Markdown."""
+        return self._http.request("GET", f"/tasks/{_seg(task_id, 'task_id')}/context", response_type="text")
+
+
+class SubtasksResource:
+    """Subtasks are tasks with ``parent_task_id`` set; they always start as ``todo``/``medium``."""
+
+    def __init__(self, tasks: TasksResource) -> None:
+        self._tasks = tasks
+
+    def list(self, project_id: str, parent_task_id: str) -> List[JSON]:
+        _seg(parent_task_id, "parent_task_id")
+        return self._tasks.list(project_id, parent_task_id=parent_task_id)
+
+    def create(
+        self,
+        project_id: str,
+        parent_task_id: str,
+        title: str,
+        *,
+        description: Optional[str] = None,
+        due_date: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        _seg(parent_task_id, "parent_task_id")
+        return self._tasks.create(
+            project_id,
+            title,
+            description=description,
+            due_date=due_date,
+            parent_task_id=parent_task_id,
+            idempotency_key=idempotency_key,
+        )
+
+
+class CommentsResource(_Resource):
+    def list(self, task_id: str) -> List[JSON]:
+        """GET /tasks/{id}/comment. Scope ``tasks:read``."""
+        return self._http.request("GET", f"/tasks/{_seg(task_id, 'task_id')}/comment")["comments"]
+
+    def create(self, task_id: str, content: str, *, idempotency_key: Optional[str] = None) -> JSON:
+        """POST /tasks/{id}/comment. Scope ``comments:write``."""
+        return self._http.request(
+            "POST", f"/tasks/{_seg(task_id, 'task_id')}/comment", json_body={"content": content}, idempotency_key=idempotency_key
+        )["comment"]
+
+
+class AttemptsResource(_Resource):
+    def list(self, task_id: str) -> List[JSON]:
+        """GET /tasks/{id}/attempts, newest first."""
+        return self._http.request("GET", f"/tasks/{_seg(task_id, 'task_id')}/attempts")["attempts"]
+
+    def record(
+        self,
+        task_id: str,
+        *,
+        problem: str,
+        approach: str,
+        outcome: str,
+        result: Optional[str] = None,
+        failure_reason: Optional[str] = None,
+        agent: Optional[str] = None,
+        related_pr_url: Optional[str] = None,
+        files_changed: Optional[Sequence[str]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """POST /tasks/{id}/attempts. ``outcome``: failed, partial or succeeded. Scope ``attempts:write``."""
+        body: JSON = {"problem": problem, "approach": approach, "outcome": outcome}
+        for key, value in (
+            ("result", result),
+            ("failure_reason", failure_reason),
+            ("agent", agent),
+            ("related_pr_url", related_pr_url),
+        ):
+            if value is not None:
+                body[key] = value
+        if files_changed is not None:
+            body["files_changed"] = list(files_changed)
+        return self._http.request(
+            "POST", f"/tasks/{_seg(task_id, 'task_id')}/attempts", json_body=body, idempotency_key=idempotency_key
+        )["attempt"]
+
+
+class ReportsResource(_Resource):
+    def file(
+        self,
+        project_id: str,
+        title: str,
+        *,
+        description: Optional[str] = None,
+        category: Optional[str] = None,
+        source: Optional[str] = None,
+        reporter: Optional[str] = None,
+        metadata: Optional[Mapping[str, Any]] = None,
+        files: Iterable[FileTuple] = (),
+        idempotency_key: Optional[str] = None,
+    ) -> JSON:
+        """POST /projects/{id}/reports (multipart) - file a bug report.
+
+        ``files`` are ``(filename, data, content_type)`` tuples. Scope
+        ``reports:write``, which a key can't combine with any other scope.
+        """
+        fields: Dict[str, str] = {"title": title}
+        for key, value in (("description", description), ("category", category), ("source", source), ("reporter", reporter)):
+            if value is not None:
+                fields[key] = value
+        if metadata is not None:
+            fields["metadata"] = json.dumps(dict(metadata))
+        return self._http.request(
+            "POST",
+            f"/projects/{_seg(project_id, 'project_id')}/reports",
+            multipart=_Multipart(fields, files),
+            idempotency_key=idempotency_key,
+        )
+
+
+class ProjectCollection(_Resource):
+    """Decisions, knowledge, roadmap, memory and tech stack: /projects/{id}/<path>[/{item_id}].
+
+    Reads need ``project:read``, writes ``project:write``. ``create``/``update``
+    take the fields as keyword arguments (``None`` clears a nullable field on update).
+    """
+
+    def __init__(self, http: HttpClient, path: str, list_key: str, item_key: str) -> None:
+        super().__init__(http)
+        self._path = path
+        self._list_key = list_key
+        self._item_key = item_key
+
+    def _base(self, project_id: str) -> str:
+        return f"/projects/{_seg(project_id, 'project_id')}/{self._path}"
+
+    def list(self, project_id: str) -> List[JSON]:
+        """Up to 500 items."""
+        return self._http.request("GET", self._base(project_id))[self._list_key]
+
+    def get(self, project_id: str, item_id: str) -> JSON:
+        return self._http.request("GET", f"{self._base(project_id)}/{_seg(item_id, 'item_id')}")[self._item_key]
+
+    def create(self, project_id: str, *, idempotency_key: Optional[str] = None, **fields: Any) -> JSON:
+        return self._http.request("POST", self._base(project_id), json_body=fields, idempotency_key=idempotency_key)[
+            self._item_key
+        ]
+
+    def update(self, project_id: str, item_id: str, *, idempotency_key: Optional[str] = None, **fields: Any) -> JSON:
+        if not fields:
+            raise ValueError("update() needs at least one field")
+        return self._http.request(
+            "PATCH", f"{self._base(project_id)}/{_seg(item_id, 'item_id')}", json_body=fields, idempotency_key=idempotency_key
+        )[self._item_key]
+
+    def delete(self, project_id: str, item_id: str, *, idempotency_key: Optional[str] = None) -> None:
+        self._http.request("DELETE", f"{self._base(project_id)}/{_seg(item_id, 'item_id')}", idempotency_key=idempotency_key)
+
+
+class Guidon:
+    """Client for the Guidon REST API.
+
+    >>> guidon = Guidon(api_key="guidon_...")            # or set GUIDON_API_KEY
+    >>> project = guidon.projects.list()[0]
+    >>> task = guidon.tasks.create(project["id"], "Fix the jump", priority="high")
+    >>> guidon.tasks.move(task["id"], "in_progress")
+
+    ``base_url`` defaults to ``GUIDON_BASE_URL`` or https://useguidon.com (a
+    self-hosted instance: ``https://guidon.example.com``; ``/api/v1`` is added).
+    """
+
+    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:
+        self._http = HttpClient(
+            api_key, base_url, timeout=timeout, max_retries=max_retries, user_agent=user_agent, headers=headers, opener=opener
+        )
+        self.projects = ProjectsResource(self._http)
+        self.tasks = TasksResource(self._http)
+        self.subtasks = SubtasksResource(self.tasks)
+        self.comments = CommentsResource(self._http)
+        self.attempts = AttemptsResource(self._http)
+        self.reports = ReportsResource(self._http)
+        self.decisions = ProjectCollection(self._http, "decisions", "decisions", "decision")
+        self.knowledge = ProjectCollection(self._http, "knowledge", "sources", "source")
+        self.roadmap = ProjectCollection(self._http, "roadmap", "phases", "phase")
+        self.memory = ProjectCollection(self._http, "memory", "memories", "memory")
+        self.technologies = ProjectCollection(self._http, "technologies", "technologies", "technology")
+
+    def me(self) -> Dict[str, Any]:
+        """GET /me - the user this key or token acts as, and its scopes. Needs no scope."""
+        return self._http.request("GET", "/me")
+
+    @property
+    def base_url(self) -> str:
+        """The resolved API root, e.g. ``https://useguidon.com/api/v1``."""
+        return self._http.base_url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        json: Any = None,
+        idempotency_key: Optional[str] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Escape hatch for routes the SDK doesn't wrap yet; ``path`` is relative to /api/v1."""
+        return self._http.request(method, path, query=query, json_body=json, idempotency_key=idempotency_key, headers=headers)

guidon/errors.py

@@ -0,0 +1,75 @@
+"""The single exception type the SDK raises."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+# The same table the server uses for the codes it adds to its errors.
+_STATUS_CODES = {
+    400: "invalid_request",
+    401: "unauthorized",
+    403: "forbidden",
+    404: "not_found",
+    405: "method_not_allowed",
+    409: "conflict",
+    411: "length_required",
+    413: "payload_too_large",
+    415: "unsupported_media_type",
+    422: "unprocessable",
+    429: "rate_limited",
+    500: "internal_error",
+    503: "unavailable",
+}
+
+
+def code_for_status(status: int) -> str:
+    """Default ``code`` for an HTTP status when the error body doesn't carry one."""
+    if status in _STATUS_CODES:
+        return _STATUS_CODES[status]
+    return "internal_error" if status >= 500 else "invalid_request"
+
+
+class GuidonError(Exception):
+    """An API error (``status`` >= 400) or a transport failure (``status`` 0).
+
+    ``code`` is the server's machine-readable code when it sends one, otherwise
+    derived from the status (``not_found``, ``rate_limited``...), or one of
+    ``network_error``, ``timeout``, ``invalid_response``, ``missing_api_key``,
+    ``invalid_base_url`` for failures that never got a usable response.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "invalid_request",
+        body: Any = None,
+        hint: Optional[str] = None,
+        docs: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        request_id: Optional[str] = None,
+        method: Optional[str] = None,
+        url: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body
+        #: The server's "what to do now" for this error, if it sent one.
+        self.hint = hint
+        #: Link to the API docs the server sent with the error, if any.
+        self.docs = docs
+        self.retry_after = retry_after
+        self.request_id = request_id
+        self.method = method
+        self.url = url
+
+    def __str__(self) -> str:
+        if self.status:
+            return f"{self.message} (HTTP {self.status}, {self.code})"
+        return f"{self.message} ({self.code})"
+
+    def __repr__(self) -> str:
+        return f"GuidonError(status={self.status!r}, code={self.code!r}, message={self.message!r})"

guidon_sdk-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+guidon/__init__.py,sha256=Um1CYM9175bAOracdBJrdyqtzxaga4_uz68p8JTfzOE,731
+guidon/_http.py,sha256=d5iVnQk3VCLWNEB-5MZeTiMNmbagvAUGiY--OAQrMjY,11161
+guidon/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+guidon/client.py,sha256=ssMUExNLbtU7ksGW7BE4aeiQgAKy8aTSeail1DSypxk,16170
+guidon/errors.py,sha256=xNj-cuoWQYXyWOHF1IhGHb4voBoXN2Pbs9xHqkqSNX4,2420
+guidon/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+guidon_sdk-0.1.0.dist-info/METADATA,sha256=Ueq5lQTB9_lTB1Zg4OtBY2X5iBznd19SNck2vjnEICY,6719
+guidon_sdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+guidon_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=TPC4SnKUN7xUYDoGsFu2MmRMiqBVKabLkVuG3MSd2iE,1076
+guidon_sdk-0.1.0.dist-info/RECORD,,

guidon_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

guidon_sdk-0.1.0.dist-info/licenses/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.