AI guides follow-ups - #568
Draft
Devon-White wants to merge 25 commits into
Draft
Conversation
…in platform capabilities
…rview, expand acronyms at first use
…mple Rewrites the AI-sounding introduction, disambiguates "call" from the phone call in the SWAIG request/reply section, removes DataMap from "where the code lives" since it has no code (keeping a relocated mention for straight REST calls), moves the dispatch agent example to the end of the guide so it lands after the reliability patterns it demonstrates, and puts the Server SDK code block first in every CodeBlocks group on the page.
…restore prompt-and-pray as a label
…ing redaction diagram
… correct meta_data_token default
…name prompt surfaces
Task 11 final sweep caught one straggler: the context-step CodeBlocks group led with SWML instead of the Server SDK, breaking the Server-SDK-first convention every other AI doc page follows.
Qualify the content-redaction masking table against the C source. Four paths carry unredacted text and the page claimed otherwise: interim ASR results and transparent-barge payloads reach the event webhook unmasked, and the timeline's auto-correct, pronunciation, and normalization entries keep the original text. Replace the "everything SignalWire records" absolute with the concrete surface list, split the two overclaiming table rows into masked and unmasked, and stop the Verify step from asking the agent to repeat the number back, which is the step that triggers the pronounce path it then claimed was masked. Correct redaction's latency framing: it is a synchronous model call on the turn path, not a background task. Drop the say-action claim that handler text never reenters the model's context, which is false in realtime mode. End the tool-calling guide on its most complete example. The closing agent gains the second tool, the global_data validation, and fillers; the mid-page copy becomes the two-handler excerpt the global_data section actually needs, with a forward link. Retarget swaig-test, the AI quickstart link, and the fillers reference accordingly, and use the documented rime.spore:coda voice string. Reconcile the prompt-structure taxonomy with its worked example: six elements, in the example's order, with Context folded into Knowledge base. Add the no-code-agents redirect, stop the AI overview promising a Dashboard walkthrough no page provides, and point Datasphere and the voice Build-with-AI card at guides instead of a REST endpoint.
The previous wave replaced one absolute with three positive masking claims, two of which are false on the default documented path. Redaction only ever rewrites a turn's content: redact_user_text marks spans and redact_apply_markers swaps them into a sibling "redacted" string, and every consumer honors it by preferring that sibling in place of content (conversation.c:164-168, :234-237, :269-272). Nothing else on the entry is touched. The metadata flatten is the hole. ai_conversation_json copies every metadata field to the top level unconditionally at conversation.c:180-188, immediately after the content swap it is unaffected by, so entity (speech_detect.c:750-767 -> conversation.c:1628-1636, the validated structured value in canonical form) and original_result (conversation.c:1866-1869, the undistilled tool output) reach call_log and raw_call_log intact. build_call_timeline is worse than unmasked: its turn events carry no content field at all (timeline.c:657-674), so they are the flattened metadata and nothing else, and masking the text cannot change them. Drop the two false table rows, add rows for the structured fields and for timeline turn entries, scope the call_log row to conversation text, and delete the narrowing sentence claiming the turns themselves are still masked. Replace the "wherever the call is recorded or transmitted" absolute the last wave missed, and scope the Warning's first clause to the conversation text. Bring the diagram into line in all four places. The mermaid matters most: it is what the .md view and any agent reading this page receives instead of the image, so it gained an unmasked structured-fields node beside the masked-text one rather than restating "every record is masked". The SVG grows a second labeled records row for the same contrast; theming, classes, and the reduced-motion guard are untouched. Point the AI overview's Datasphere link at builtin-skills#datasphere, which is the section that documents it; search-knowledge is about sw-search and pgvector. Rename the tool-calling inline declaration to validate_trip so it matches what the page teaches, and the remote signature response with it, since it declared the same get_quote(pickup, destination) the page's own agent declares paramless. Give the global_data excerpt its class header so it pastes without an IndentationError.
Timeline turn entries carry no turn text, but on a normal barge mod_openai.c writes text_heard_approx and text_spoken_total onto the last assistant entry's metadata, and timeline.c flattens metadata unconditionally onto the event. The agent's raw utterance therefore reaches raw_call_log and call_timeline unmasked, which refutes the 'no conversation text at all' absolute. Scope the Verify redaction step to the logs so it no longer sends the reader to the timeline looking for masked turns, and retarget the 'Speak a value' lead-in at the records, which is what both paragraphs beneath it actually compare.
Two independent source traces disagreed on whether the barge timeline fields text_heard_approx / text_spoken_total are masked. A contested claim should not ship in either direction on a PCI/HIPAA page, so the claim is deleted rather than adjudicated or hedged. Keeps the source-verified sentence that timeline turn entries are built from structured fields, and keeps the entity / original_result warning above it. Also drops the dependent 'timeline holds no turn text to mask' clause from the verify step, retaining the correct scoping of the ---- expectation to call_log and raw_call_log.
Contributor
Unhide conversation analytics and give it a home. Move analytics.mdx into pages/ai/guides/ so the existing folder nav entry picks it up, drop the explicit hidden page entry, remove noindex, and promote both #### headings to ## so the page renders a table of contents. Slug and body unchanged -- the stub is now visible, not rewritten. Restore the two topics that were dropped rather than compressed when the capabilities page merged into the overview. Fillers and background audio join the media-path section, where the remaining tool-call wait is already under discussion. Voice selection extends the voices-and-languages clause. Real-time analytics gets a paragraph in "Reaching your systems" plus a Next steps card, since it was one of the three named differentiators and had no presence on the page at all. Restore built-in skills to the quickstart: add_skill appeared nowhere in the AI docs, so a newcomer never learned they exist. datetime and math, with a comment naming them as built-in. Break the Dashboard link loop on resources.mdx. Both AI Agents cards pointed back at the AI overview, which is where the reader came from; they now land on the Dashboard creation steps further down the page. Noise filtering and accent variation are deliberately not claimed. The only noise handling in the AI path is interrupt_on_noise (a barge-in threshold) and a provider-specific realtime setting; public noise reduction is the opt-in denoise method, not an automatic capability.
…he mechanism The two arrows floated in dead space below both panels, touching neither, and their labels named the payload rather than what happens. Widen the channel from 80px to 240px by narrowing the panels, and put both arrows in it, centered against the card stacks and reaching to within 4px of each panel edge. Labels now trace the hop: the agent calls a tool, the request reaches your backend, your code shapes the response, the agent answers from it. Add the centered mono caption both sibling diagrams close with, carrying the reliability point - the answer comes from your code, not the model. Shorten the tools subtitle so the narrower card holds it. Update the aria-label, the img alt, and the paired llms-only mermaid to match.
A doc review found both guides hard to read: long paragraphs welding several distinct claims together, so the reader has to reread to keep them apart. Fix the two guides and codify the rule that prevents the drift, since mdx-style only governed sentence length. - mdx-style: add "one paragraph, one job" to Voice, explicitly not a word-count rule. - best-practices: split 6 paragraphs by idea, drop the Tip that duplicated the staleness point in prose, cut two restating sentences, and demote three aphorisms to plain statements (page ran 5-6 against a 2-3 limit). Re-site the handler-timing sentence next to turnaround, where the interval it belongs to is defined. - prompt-engineering: split 4 paragraphs, condense the new-team-member simile, cut a significance-inflation opener, and bring Role and Response guidelines into the page's register. Paragraphs at 70+ words: best practices 8 to 0, prompt engineering 5 to 0. No heading text changed, so no anchor moved.
'SignalWire AI' says nothing about what the product is — a doc review called it weak branding readers ignore by default, and the H1 was the first string a reader hit. Name the category instead. Keep the tab label and the product name as AI; this is the page title, not a rename. Drop 'voice AI' from the subtitle and description: the term reads as speech synthesis outside telecom, and hard-coding the channel would need rewriting if conversational AI reaches other channels. The concrete claims stay accurate to what ships today. Leave line 49's quoted 'voice AI' alone — correcting that reading is the point of the section — and leave the TCPA and HIPAA references, which are voice-specific by law.
…ity and improve descriptions
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.
No description provided.