Document ai.params redact_prompt, auto_correct, and utility_model#452
Open
Devon-White wants to merge 11 commits into
Open
Document ai.params redact_prompt, auto_correct, and utility_model#452Devon-White wants to merge 11 commits into
Devon-White wants to merge 11 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.
The GitHub-side merge of main combined the emitted artifact textually, so the new auto_correct field kept its pre-#474 'boolean | SWMLVar' anyOf. Rebuilding through @signalwire/typespec-openapi3 collapses it to bare boolean, matching the SWMLVar-only-in-SWML-JSON-schema invariant.
Conceptual guide for the ai.params redaction feature (redact_prompt, auto_correct, utility_model) under the platform AI guides, following the house guide skeleton: hook + minimal example first, the record-vs-model distinction as the single load-bearing warning, behavior-level explanation only (no marking/log internals), performance tuning with the enable_text_normalization interaction, a customer-verifiable test flow, and honest limitations including the audio-recording carve-out.
Mermaid mental-model diagram up front (live conversation vs records, same styling as the prompt-engineering diagram), surface-by-surface table in 'How it works', Tip/Note callouts for utility_model and the enable_text_normalization prerequisite, Steps for the verify flow, and a CardGroup for next steps.
The emitted SWML JSON schema types enable_text_normalization as a union of string consts (heard/spoken/both/true/on/false/off/none) — boolean false is schema-invalid, and unquoted false/off in YAML parse as booleans. Use quoted "off" in both formats. All four guide examples (YAML+JSON, minimal+full) now validate against SWMLObject.json via ajv (draft 2020-12).
Source-verified all four redaction-adjacent params in mod_openai: - utility_model/thinking_model validate via valid_thinking_model() (app_config.c), a case-insensitive substring match over an 18-model list — the docs' 'Allowed values are gpt-4o-mini, gpt-4.1-mini, and gpt-4.1-nano' claim was false. Reworded to examples, and documented the real failure mode: unrecognized values are silently ignored and the agent's main model is used (um = utility_model ?: model->name at every call site). - auto_correct: switch_true() header parse; mutual exclusion confirmed at session.c:1526 (text normalization on -> auto_correct disabled with a warning). Reference wording now says enable_text_normalization "off" (string) to match the schema type, as the guide does. - enable_text_normalization: session.c accepts exactly false/off/none/heard/spoken/both/true/on case-insensitively, default both — spec union matches; unrecognized values keep the default. - redact_prompt: plain string header, no validation, non-empty enables; combined cleanup+redaction single pass confirmed in auto_correct_user_text() (ai_utils.c). Regenerated SWML JSON schema and REST openapi.yaml (description-only deltas).
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)Part of #450