feat: rewrite for real KeeperHub public API (catalogue + x402) + multi-LLM auto-detect#1
Merged
Merged
Conversation
… Groq / DeepSeek / OpenRouter / Mistral / Together / Ollama) * New keeperkit.server.llm module with build_llm() + detect_provider(). Priority: anthropic > google > groq > deepseek > openrouter > mistral > together > ollama > openai. KEEPERKIT_LLM_PROVIDER and KEEPERKIT_LLM_MODEL env vars override. * Server / agent now read whichever provider is configured and degrade gracefully to the heuristic fallback when none are set. * Dashboard surfaces an llm: <provider>[:<model>] badge alongside backend. * /api/health includes llm_provider + llm_model fields. * pyproject: split LLM providers into individual extras, bundle the most popular four (openai, anthropic, google, groq) into [server] so the demo just works after pasting any one key. * README + .env.example: document each provider, the auto-detect order, and where to obtain a key (with free-tier callouts for Gemini/Groq/Ollama). * README: add a clear 'Getting a KeeperHub API key' section. Co-Authored-By: Данила Вербина <danila.verbina@gmail.com>
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
KeeperHub's public API is a catalogue of callable workflows under
POST /api/mcp/workflows/{slug}/call, not the CRUD-style execution layer
the marketing pages imply. This commit aligns the entire SDK with the
real API surface (verified via /api/openapi with a real kh_... key).
Client changes:
- Replace CRUD methods with list_workflows() / call_workflow(slug, body) /
get_openapi() / list_org_workflows() / list_integrations()
- Decode the base64 x402 payment descriptor on HTTP 402 and raise
KeeperHubPaymentRequired with .x402 and .amount_usdc populated
- Forward x_payment to the X-Payment header for paid-workflow retries
- Sync and async clients kept in lockstep
Tool catalogue:
- ToolSpec.dispatch is now a callable (was a string lookup key)
- 5 static tools always present: list_workflows, call_workflow, get_openapi,
list_org_workflows, list_integrations
- One tool auto-generated per discoverable workflow with its inputSchema
copied verbatim — agent surface tracks the live KeeperHub catalogue
- safe_dispatch() converts KeeperHubAPIError / KeeperHubPaymentRequired
into structured {ok, error, x402, amount_usdc, ...} dicts so LLMs can
reason about payments instead of crashing
Mock client:
- DEFAULT_CATALOGUE with 5 representative workflows (free + paid)
- Full 402 payment-required flow when x_payment is missing
- get_openapi() generates a real-shaped OpenAPI spec for the catalogue
Server / dashboard:
- Refreshable tool catalogue (POST /api/tools/_refresh)
- Tool-count badge in the UI; per-workflow examples in the prompts
- ElizaOS plugin descriptor now includes one action per discoverable
workflow when a client is supplied
Tests / lint:
- 30 offline tests across mock / tool specs / real-client-errors /
langchain / elizaos
- ruff clean (added N818 to ignore for KeeperHubPaymentRequired naming)
Docs:
- README rewritten end-to-end (architecture diagram, x402 walk-through,
auto-generated tool catalogue explanation)
- docs/architecture.md updated for callable + auto-generated catalogue
- examples/quickstart.py demonstrates 402 flow end-to-end against mock
- FEEDBACK.md rewritten as Builder Feedback Bounty submission with 8
reproducible friction points + 6 feature requests + reproducers
Co-Authored-By: Данила Вербина <danila.verbina@gmail.com>
devin-ai-integration
Bot
changed the title
Co-Authored-By: Данила Вербина <danila.verbina@gmail.com>
2 tasks
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.
Summary
Two coordinated changes:
1 · Align the SDK with KeeperHub's real public API
After plugging in a real
kh_…org key and reading/api/openapi, itturned out KeeperHub's public API is a catalogue of callable
workflows under
POST /api/mcp/workflows/{slug}/call, not theCRUD-style execution layer the marketing pages imply. The SDK is
rewritten end-to-end to match the real surface:
client.py(sync + async)list_workflows()/call_workflow(slug, body, x_payment=…)/get_openapi()/list_org_workflows()/list_integrations(). HTTP 402 decodes the base64 x402 descriptor and raisesKeeperHubPaymentRequiredwith.x402+.amount_usdc.tools/_common.pyToolSpec.dispatchis now a callable. 5 always-present static tools (keeperhub_list_workflows,keeperhub_call_workflow,keeperhub_get_openapi,keeperhub_list_org_workflows,keeperhub_list_integrations).build_workflow_tools(client)auto-generates one typedToolSpecper discoverable workflow, copying itsinputSchemaverbatim.safe_dispatch()returns structured{ok, error, x402, amount_usdc, ...}so LLMs can reason about payments.mock.pyDEFAULT_CATALOGUEwith 5 representative workflows (free + paid), full 402 flow, OpenAPI generation.StructuredTool, CrewAIBaseTool, ElizaOS plugin descriptor all consume the sameToolSpecset, including the per-workflow tools.POST /api/tools/_refreshre-discovers catalogue without restart. UI shows atools: Nbadge. ElizaOS endpoint embeds per-workflow actions.2 · Multi-LLM auto-detection (originally PR #1's scope)
server/llm.pypicks a chat model from whichever provider key is set:anthropic → google → groq → deepseek → openrouter → mistral → together → ollama → openai. Override withKEEPERKIT_LLM_PROVIDER/KEEPERKIT_LLM_MODEL. The[server]extra bundles the most commonclients so the demo just works once you paste any one of OPENAI /
ANTHROPIC / GOOGLE / GROQ keys into
.env.The pivot rewrites every adapter and most of the server, and the LLM
auto-detect lives in those same files — splitting them would require
~200 lines of throwaway shim code on the smaller PR. Single PR keeps
review tractable.
Review & Testing Checklist for Human
Risk: yellow — this is a large rewrite that touches every public
file, but it's covered by a fresh test suite, lints cleanly, and the
mock-backed demo runs end-to-end locally.
src/keeperkit/client.py—does the method set match how you'd want to use KeeperHub?
python examples/quickstart.py(no credentials needed; runsagainst the mock) and confirm the 402 → x-payment retry flow
works as expected.
KEEPERHUB_API_KEYand an LLMkey (e.g.
GROQ_API_KEY); callhelloworldand a paid workflowvia the dashboard or
POST /api/agent/run.FEEDBACK.md— confirm the friction points are accuratereflections of what you'd want KeeperHub to fix (this is the
$250 Builder Feedback Bounty submission).
Notes
the second half of this PR; nothing was lost.
redeployed to this branch.
KEEPERHUB_API_KEYyou shared in chat (kh_bpoEhgyFwk7…) isexposed in conversation logs — please rotate it on
https://keeperhub.com → Settings → API Keys after this is merged.
Link to Devin session: https://app.devin.ai/sessions/4c74607caacb488d803b3a14a74ee6df
Requested by: @danilaverbena