Document ai.params redact_prompt, auto_correct, and utility_model#452
Open
Devon-White wants to merge 4 commits into
Open
Document ai.params redact_prompt, auto_correct, and utility_model#452Devon-White wants to merge 4 commits into
Devon-White wants to merge 4 commits into
Conversation
Adds the three shipped-but-undocumented AI params to the SWML TypeSpec schema (AIParams) and the ai_params reference page, per issue #450. Types, defaults, and behavior verified against mod_openai source: redact_prompt masks recorded/transmitted content only (model still receives real text), auto_correct is mutually exclusive with enable_text_normalization, and utility_model defaults to ai_model.
Contributor
The calling-api imports the SWML module, so SWML.Calling.AIParams is emitted into the checked-in openapi.yaml and picks up redact_prompt, auto_correct, and utility_model.
The Fabric AI-agent spec already reuses SWML.Calling.AIParams via 'model AIAgent is AIObject' (core.tsp imports the SWML ai module), so the hand-copied AIParams in ai-agent/models/ai/ai_params.tsp was never imported or compiled. It had drifted ~40 fields behind the SWML model and carried the backend's digit_termiantors typo. Deleting it changes nothing in the emitted openapi.yaml (verified: rebuild is byte-identical); the REST surface already picks up redact_prompt, auto_correct, and utility_model through the shared SWML model. The Rails backend merges unrecognized params verbatim into the generated SWML document (params_serializer.rb), so the shared model matches actual behavior.
3 tasks
Removes implementation-flavored wording (model round-trip, utility passes, per-turn phrasing) in favor of end-user language, states the latency benefit plainly, and turns the best-effort caveat into actionable guidance.
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
Adds the three shipped-but-undocumented AI content-redaction params to the SWML TypeSpec schema and the
ai.paramsreference page. Addresses the reference-page acceptance criterion of #450; the conceptual Content Redaction guide is deliberately deferred to a follow-up PR.All types, defaults, and behavior were verified against the
mod_openaisource (not just the issue text):redact_prompt(string) — plain-language description of content to mask (----) from everything the platform records or transmits: logs, events, webhook payloads, the call timeline, and the post-conversationcall_log/raw_call_log. Non-empty value enables; omit to disable. Explicitly states the caller still hears the content and the AI model still receives the real text each turn — redaction protects recorded/transmitted data only, and is best-effort.auto_correct(boolean, defaultfalse) — utility-pass cleanup of caller speech-to-text. Documents a source-verified constraint the issue draft missed: it is mutually exclusive withenable_text_normalization(which defaults on and wins, soenable_text_normalization: falseis required forauto_correctto take effect). When combined withredact_prompt, cleanup and redaction run in a single pass.utility_model(string, defaults to the value ofai_model) — model for the lightweight redaction/cleanup passes, documented with the same allowed-models phrasing and default convention asthinking_model.Changes
specs/swml/calling/Methods/ai/ai_params.tsp— three new fields onAIParams(auto_correctandredact_promptbesideenable_text_normalization;utility_modelbesidethinking_model)fern/products/swml/pages/reference/methods/calling/ai/ai_params/index.mdx— three matching<ParamField>entries in the corresponding page sectionsspecs/swml/calling/tsp-output/@typespec/json-schema/SWMLObject.json— regenerated (checked-in output)fern/apis/signalwire-rest/openapi.yaml— regenerated: the calling-api imports the SWML module, soSWML.Calling.AIParamsis emitted into the REST OpenAPI and picks up the three new fields. This also means the Fabric AI-agent REST resource documents them for free (see below).specs/signalwire-rest/fabric-api/ai-agent/models/ai/ai_params.tsp— dead code. The Fabric AI-agent spec already reusesSWML.Calling.AIParamsviamodel AIAgent is AIObject(core.tsp imports the SWML ai module); this hand-copied duplicate was never imported or compiled, had drifted ~40 fields behind the shared model, and carried the backend'sdigit_termiantorstypo. Deleting it leaves the emitted openapi.yaml byte-identical (verified by rebuild).Verification
yarn build:swml-callingandyarn build:signalwire-restcompile clean;tsp formatunchangedSWMLObject.jsonand intoSWML.Calling.AIParamsinopenapi.yamlwith correct shapes (plain string /boolean | SWMLVarwithdefault: false/SupportedAIModelsunion)Follow-ups (out of scope here)
Part of #450