guidon-sdk - Python SDK for Guidon

Official Python client for the Guidon 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.

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).

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

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")

Results are the API's JSON objects as plain dicts.

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:

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):

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

cd sdk/python
python -m unittest discover -s tests -v   # mock http.server, no network
python -m build                           # needs `pip install build`

Links: Homepage - Source - API reference: https://useguidon.com/openapi.json

License

MIT - see LICENSE. This licence covers this SDK/CLI package, not the Guidon service or the rest of the application.