docs(sdk): document the in-process Python SDK + add a runnable demo#440
Merged
Conversation
The importable `Client` facade (lib.py) and its typed result models (result_models.py, #428) were a committed public API with no developer-facing documentation, and a few doc surfaces had drifted. This adds the missing SDK guide, a teaching demo, and fixes the drift. New: - docs/sdk.md -- deep SDK reference: what it is vs CLI vs serve REST, where the facade sits in the 3-layer architecture, full method reference (query/ query_result/run_job/config_detail/upload_table/files/raw), the typed result-model contract (extra="allow" + populate_by_name + semver via __all__), py.typed, idempotent run_job, a gotchas cheat-sheet, and a contributor section on extending the SDK. - examples/storage_tui/ -- a runnable, dependency-free curses Storage browser (buckets -> tables -> detail+preview) driven entirely through `from keboola_agent_cli import Client` and `client.raw`. No mocks, fail-fast on missing KBC_URL/KBC_TOKEN, token never printed/logged. + examples/README.md index. - CONTRIBUTING.md "Extending the importable SDK" section (parallel to "Adding a New CLI Command") linking the docs/sdk.md checklist. Drift fixes: - CLAUDE.md: APP_NAME is now resolved dynamically (constants._resolve_app_name, shipped in 0.63.1) -- it is no longer the fixed literal "keboola-cli" the doc claimed. - CONTRIBUTING.md: Python 3.12+ (matches pyproject requires-python), was 3.11+. - CLAUDE.md Project Structure: __init__.py is the public SDK entrypoint; added lib.py / result_models.py / py.typed. - README.md: "Use as a library" + Documentation table link docs/sdk.md and the demo. No code changes; make check green (4099 passed).
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…tuple Devin review on PR #440: the storage_tui demo returned `tuple[list[str], list[list[str]]]` (two semantically distinct values), which CONTRIBUTING.md "Code Quality Patterns" forbids -- doubly important in a PR that documents that very rule. Introduce a frozen `PreviewData(header, rows)` and use attribute access at the call site.
padak
added a commit
that referenced
this pull request
Jun 17, 2026
Release-only bump for the SDK documentation landed in #440 (docs/sdk.md, the examples/storage_tui demo, the CONTRIBUTING "Extending the importable SDK" section, and the doc-drift fixes). No runtime code change: docs and examples ship in the repo, not the wheel, so the installed package is functionally identical to 0.63.1. The bump exists so `kbagent changelog` surfaces the new SDK guide and the release carries the migration-bridge compat wheel for any <=0.62 client that updates to latest.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The importable
Clientfacade (lib.py) and its typed result models (result_models.py, #428) are committed public API, but had no developer-facing documentation — and a few doc surfaces had drifted (some by the recent #424 rename). This PR documents how to program against kbagent's Python SDK, ships a runnable teaching demo, and fixes the drift. No code changes.What
New — SDK documentation
docs/sdk.md— the deep reference:serveREST) and when to pick each;query/query_result/run_job/config_detail/upload_table/files/raw;extra="allow"forward-compat,populate_by_namealiasing, semver via__all__),py.typed;run_job(feat(sdk): idempotency keys for run_job (and push) — safe replay after interruption #427), a gotchas cheat-sheet (Snowflake string-typing, UPPERCASE columns, no auto-create, ...);CONTRIBUTING.md→ "Extending the importable SDK" — a checklist parallel to "Adding a New CLI Command", linkingdocs/sdk.md.New — runnable demo
examples/storage_tui/— a dependency-free curses Storage browser (buckets → tables → detail + data preview) driven entirely throughfrom keboola_agent_cli import Clientandclient.raw. No mocks (live data, empty-states rendered honestly); fail-fast on missingKBC_URL/KBC_TOKEN; token never printed/logged/written.app.py+_render.py(pure drawing) +README.md.examples/README.md— index + "which surface should I build on?" guide.Drift fixes
CLAUDE.md(Versioning)APP_NAME = "keboola-cli"" (fixed literal)APP_NAMEresolved dynamically (_resolve_app_name, shipped 0.63.1)CONTRIBUTING.mdpyprojectrequires-python)CLAUDE.md(Project Structure)__init__.py # exposes __version__lib.py/result_models.py/py.typedREADME.mddocs/sdk.mdand the demoVerification
lib.py,result_models.py,client.py) — no invented API.ruff check+ruff format --checkclean; parses; imports withKBC_URL/KBC_TOKENunset without any network (all config/API work is insidemain()).make checkgreen — 4099 passed (no code touched insrc//tests/).Note
No version bump / changelog entry — this is docs + examples only, not a release.
examples/is outside the wheel ([tool.hatch.build.targets.wheel] packages = ["src/keboola_agent_cli"]) and outside the CI lint scope (src/ tests/), but was kept ruff-clean anyway.