fix(sdks)!: rewrite to match real server contract (0.2.0)#15
Merged
stevepaltridge merged 5 commits intomainfrom Apr 24, 2026
Merged
fix(sdks)!: rewrite to match real server contract (0.2.0)#15stevepaltridge merged 5 commits intomainfrom
stevepaltridge merged 5 commits intomainfrom
Conversation
added 2 commits
April 24, 2026 02:06
- release-python-sdk.yml: tag python-sdk-v* -> build + publish to PyPI - release-ts-sdk.yml: tag ts-sdk-v* -> typecheck/test/build + publish to npm with provenance - docs/releasing-sdks.md: one-time secrets setup + release runbook Both workflows verify tag matches package version before publishing.
…r contract (0.2.0)
BREAKING CHANGE: 0.1.0 was published with a fictional API. Live smoke against ghcr.io/recallworks/recall:0.1.0 caught two server-contract violations (Authorization header instead of X-API-Key; tags as list instead of comma-separated string). Root-cause review showed the entire surface was invented. This commit rewrites both SDKs to match the real server.
Real contract:
- Auth header: X-API-Key (not Authorization: Bearer)
- Endpoint: POST /tool/{name} with JSON body
- Response envelope (ALL tools): {result: str, tool: str, by: str}
- Errors: 4xx/5xx with {error: str}
- /health: GET, no auth
Signatures now match server exactly (recall uses n+type, remember tags is comma-separated string, forget takes source label not chunk id, checkpoint/reflect/anti_pattern/session_close use snake_case body keys, etc.).
Verification:
- Python: 16/16 unit tests pass; live smoke against running container PASSED (sync+async remember/recall/memory_stats/checkpoint + auth-error path)
- TypeScript: 16/16 vitest pass; tsc --noEmit clean; live smoke PASSED (health/remember/recall/checkpoint + auth-error path)
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
0.1.0 SDKs were published with a fictional API. Live smoke against the running
ghcr.io/recallworks/recall:0.1.0container caught two contract violations end-to-end:Authorization: Bearer <key>— server wantsX-API-Keytags: ["a","b"]— ChromaDB rejects:Expected metadata value to be a str, int, float or bool, got [...] which is a listRoot-cause review showed the entire SDK surface was invented. Function names, parameters, return shapes — all wrong.
What
Rewrote both SDKs to match the real server, bumped to 0.2.0, marked BREAKING.
Real contract (verified against server source + live container):
POST /tool/{name}with JSON bodyX-API-Key{result: str, tool: str, by: str}{error: str}GET /health— no authReal signatures now mirrored exactly:
remember(content, source='agent-observation', tags='')— tags is COMMA-SEPARATED STRINGrecall(query, n=5, type='all')— usesn, notlimitforget(source)— takes source LABEL, not chunk id; soft-archivescheckpoint(intent, established, pursuing, open_questions, session='', domain='')reflect/anti_pattern/session_close— snake_case server keyspulse/memory_stats/reindex/index_file/maintenance/snapshot_indexGeneric escape hatch:
call_tool(name, **kwargs)/callTool(name, payload)returnsToolResponse.Killed fictional types:
Hit,RememberResult,CheckpointInput.Verification
Test container:
docker run -d -p 8799:8787 -e API_KEY=smoke-key ghcr.io/recallworks/recall:0.1.0Both
smoke_live.pyandsmoke_live.tsare committed and reproducible.Migration (0.1.0 → 0.2.0)
recall()no longer returnsHit[]— returnsToolResponsewhose.resultis the markdown the server emits. Same for every tool. Use.resulteverywhere a structured field used to be.Next
Once
PYPI_API_TOKEN+NPM_TOKENrepo secrets are in place:git tag python-sdk-v0.2.0 && git push --tags(then same forts-sdk-v0.2.0).