Repository navigation
v0.11.0 — Phase 10: SDK, CLI and Documentation
v0.11.0 — Phase 10: SDK, CLI and Documentation
Added
flowforge-client — a dependency-free Python client, published as its own
distribution because the server package drags in Django and a client library must
not. It imports nothing from core or api; it talks HTTP.
- No runtime dependencies.
urllib.requestis enough for JSON over HTTP, so
installing it cannot change a resolution anywhere else. CI asserts the list
stays empty. - Frozen dataclasses, so
run.task_runs[0].stategets completion and a typo
raisesAttributeError. - Typed errors from the envelope. The API's
error.codeis stable, so the
client parses it once and youexcept NotFoundError,ConflictError,
ThrottledError(withretry_after). trigger(..., idempotency_key=...)— a POST is not idempotent, so the
client refuses to retry one without a key; with one, a retry replays.wait(run_id, timeout=...)polls with a growing interval and raises
TimeoutErrornaming the last state, because a caller that ignored a
still-running run would proceed on unfinished work.- Retries are 429/5xx only, with exponential backoff, jitter and
Retry-After.
The transport refuses any scheme buthttp/https—urlopenaccepts
file:, and a base URL that could point at a local path is a
credential-disclosure bug.
The flowforge CLI — one subcommand per client call, so the CLI cannot do
what the SDK cannot. Config from FLOWFORGE_URL/FLOWFORGE_TOKEN first, flags
second. Exit codes: 0 ok, 1 failed, 2 usage. trigger exits 1 when the run did
not succeed, which is what makes it usable as a CI step.
examples/ — four runnable programs: publish-and-run, watch-the-event-log,
requeue-failed (dry-run by default, because requeueing is a state change on live
work), and a CLI walkthrough that asserts an exit code at every step.
Documentation
docs/sdk/index.md— the guide, leading with the design decisions and stating
what the SDK deliberately does not do.docs/cli.md— configuration precedence, exit codes, one example per
subcommand with real output.docs/api/reference.md— every endpoint with its request and response body,
the error envelope, both state machines, rate limits and health probes.docs/api/overview.md— its endpoint table now lists the whole surface.
Verification
CI: https://github.com/Abolfazlrwm/flowforge/actions/runs/39968849829
- 52 SDK tests, all without a server — a
FakeTransportanswers from a
table, which makes retry, pagination, error mapping and polling testable. - New
sdkjob: own lock file, ruff, ruff format, mypy, pytest, an empty
runtime-dependency assertion, and a wheel build that checks the console script
is declared. - Server: 681 unit tests on PostgreSQL, 29 integration tests, ruff, mypy
(73 files),mkdocs build --strict.
Known limitations
flowforge-clientis not on PyPI — publishing is a release decision that
has not been taken. Install withpip install ./sdk.- No async client; no client-side definition validation; no cancellation call
(the API has no endpoint for it); nopublishsubcommand.