camel-goodmem 0.2.0: official SDK, retrieval status contract, native retriever

[bashareid]

Audit and rewrite of camel-goodmem against the P1–P38 checklist.

Everything below was reproduced against the published wheel — camel-goodmem 0.1.0 on PyPI, verified byte-identical to b12a805 — running live against GoodMem server v1.0.320, not inferred from reading the source.

The headline

goodmem_update_space sent publicRead. The server removed that field and answers:

HTTP 400 {"error":"Invalid JSON request body: Unrecognized field \"publicRead\"
          (class com.goodmem.rest.dto.UpdateSpaceRequest)"}

metadata_filter was a raw filter expression supplied by the model. Live, a model could widen its own scope — the intended tenant = 'acme' filter returned 1 hit, a self-widened one returned 2 — and an ordinary apostrophe in a value was a 400.

A search with an unavailable reranker returned success: true with no indication of trouble, while the server had sent NOT_FOUND, FEATURE_DISABLED and RERANKING_FAILED.

A PDF's content came back as raw bytes, which is not JSON-serialisable — that tool result could never reach a model.

The 71 existing tests passed against every one of these. They assigned a MagicMock to the toolkit's _session, so they asserted that the code calls the methods it calls. There was no CI: only a publish workflow, so 0.1.0 shipped without a test ever running.

Measured before/after

Scenario	0.1.0 (published)	0.2.0
update_space(public_read=True)	HTTP 400, Unrecognized field "publicRead"	argument does not exist
Model-supplied filter	widened its own scope, 1 hit → 2; apostrophe → 400	developer-set, escaped; injection payload → 0 hits
Search, broken reranker	success=true, no status	partial=true + the server's own messages
PDF content	raw bytes, not JSON-serialisable	base64 str, byte-identical
file_path=/etc/hostname	read and uploaded byte-identical	refused, as are .. and symlink escapes
Empty-space search	11.63 s	0.29 s
Retrieval tool surface	13 model arguments; delete_space always exposed	goodmem_search(query, top_k)
Score	raw -0.6236	score=+0.6236, rawScore, scoreKind
Rejected create	400 Client Error: Bad Request	the server's field-level message + status
Listings	first page only	paginated
Timeouts	0 of 12 calls	on the client
Retriever	none	GoodMemRetriever(BaseRetriever)

Full transcript: camel-goodmem-before-after.txt in the audit notes.

Tests

• 69 offline — the real SDK over an httpx mock transport, fed NDJSON captured from v1.0.320. A guard test asserts the fixtures are server bytes.
• 29 live — skip entirely without credentials, which is also the check that no key is baked in. Teardown verified against a fresh server inventory.
• CI — lint, types, offline suite, skip check, clean-environment install, plus gates for a committed key and disabled TLS.

Deliberately not done

• No AgentMemory implementation: CAMEL's AgentMemory is chat history with a context-window policy, GoodMem is a document store with server-side embedding. Implementing it would fake one side of the contract.
• GoodMemToolkit moved from camel_goodmem.goodmem_toolkit to camel_goodmem.toolkit; the package-level import from camel_goodmem import GoodMemToolkit is unchanged.

🤖 Generated with Claude Code