docs: give response mapping, the Knowledge Graph and skills their due - #505
Open
keysersoft wants to merge 2 commits into
Open
docs: give response mapping, the Knowledge Graph and skills their due#505keysersoft wants to merge 2 commits into
keysersoft wants to merge 2 commits into
Conversation
Response mapping was not mentioned in the README at all, even though it is the
answer to the first question an enterprise asks before pointing a third-party
model at their data: what exactly leaves the building? It now has its own
section covering the three modes, the live before/after preview, and the fact
that a broken mapping falls back to the raw response rather than breaking a
working tool.
The claim is kept to what the code actually does. Dropped fields never reach
the AI client or the model provider, but the audit log still records the full
upstream response, because the transform runs on the way out and the log is
written before it. That is worth stating plainly: shaping what the agent sees
does not cost you the evidence of what the API returned. The example in the
section was run through applyResponseTransform to confirm it does what the
prose says.
The Knowledge Graph and skills section now leads with the problem rather than
the mechanism, and spells out the loop that makes skills interesting: intent
capture, AI suggestion, review or auto-apply above 0.90 confidence, composed
into the server instructions with no extra tool calls.
`docs/tool-definition.md` still documented the legacy `{ type, fields }` shape
and none of select/jmespath/exclude/maxBytes/cacheTtl, so the README's link
landed on a page describing a different feature. Rewritten against the real
contract.
Also corrects three stale figures found while reviewing: 175+ adapters is
actually 188, the guides ship in seven languages rather than three, and tool
discovery from a running MCP server was missing from the import list. Adds the
Contributing section to the table of contents, where it had never been listed.
`exclude` drops a field and changes the response shape. The template also accepts a `= literal` leaf, so a value can be replaced with a placeholder instead, which keeps the shape stable for the agent. That escape hatch existed only as a comment in the source and nobody would have guessed the leading `=`. Both examples were run through applyResponseTransform before committing.
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.
Response mapping was invisible
The README never mentioned it, even though it answers the first question anyone asks before pointing a third-party model at their data: what exactly leaves the building? New Control what the model sees section, plus a Key features bullet, a row in the Why table and a line in the intro.
Scope of the claims is deliberately limited to what the code does. Dropped fields never reach the AI client or the model provider, but the audit log does still hold the full upstream response, because
renderResultruns afterlogInvocation. Stated explicitly rather than glossed over, since it is a feature and not a caveat: you keep the evidence, the model does not get the data.The JSON example in the section was executed through
applyResponseTransformbefore committing:Knowledge Graph and skills
The section now opens with the problem instead of the mechanism, and the skills bullet spells out the loop that makes them worth having: intent capture → AI suggestion → review or auto-apply above 0.90 → composed into the server instructions, no extra tool calls.
Stale facts corrected while reviewing
Contributingwas never listeddocs/tool-definition.mdstill documented the legacy{ type, fields }shape and none ofselect/jmespath/exclude/maxBytes/cacheTtl, so the new README link would have landed on a page describing a different feature. Rewritten against the real contract.All relative links and heading anchors verified after the edits.