fix: keyterms to keyterm #363
Conversation
WalkthroughThe diff updates the property name used for specifying key terms across several files. In all affected locations—ranging from example configurations and transcription functions to type declarations and client logic—the property has been renamed from Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client Code
participant ALC as AgentLiveClient
participant Deepgram as Deepgram API
Client->>ALC: configure(options) with agent.listen.keyterm
ALC->>ALC: Check if agent.listen.keyterm exists
alt Key term exists and model valid
ALC->>Deepgram: Start agent with provided keyterm
else Key term invalid/not supported
ALC-->>Client: Throw DeepgramError
end
sequenceDiagram
participant Client as Client Code
participant LLC as ListenLiveClient
Client->>LLC: finish()
LLC->>LLC: Call requestClose() internally
LLC-->>Client: Connection is terminated
Possibly related PRs
Suggested reviewers
✨ Finishing Touches
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🔭 Outside diff range comments (2)
src/packages/ListenLiveClient.ts (1)
133-135: 💡 Verification agent🧩 Analysis chain
Ensure deprecation notice is documented.
The
finishmethod is now deprecated in favor ofrequestClose. Make sure this deprecation is documented in the changelog and that consumers are notified of the migration path.Run the following script to find any direct usages of the deprecated method:
🏁 Script executed:
#!/bin/bash # Description: Find usages of the deprecated finish method. rg -A 2 "\.finish\(\)" --type ts --type jsLength of output: 467
Action: Update Documentation and Test References for the Deprecated Method
Please update the changelog to document the deprecation of the
finishmethod, including explicit migration instructions to userequestCloseinstead. Additionally, note that the deprecated method is still referenced in the disabled tests (e.g.,disabled_tests/live.test.ts), so either update these tests to userequestCloseor add a comment clarifying that their usage is intentional (and that those tests remain disabled).src/packages/ListenRestClient.ts (1)
82-86: 🛠️ Refactor suggestionAdd keyterm validation to transcribeFile method.
For consistency, the same keyterm validation that exists in
transcribeUrlshould be added totranscribeFile. This ensures consistent behavior across both transcription methods.Add the validation before the requestUrl construction:
async transcribeFile( source: FileSource, options?: PrerecordedSchema, endpoint = ":version/listen" ): Promise<DeepgramResponse<SyncPrerecordedResponse>> { try { let body; if (isFileSource(source)) { body = source; } else { throw new DeepgramError("Unknown transcription source type"); } if (options !== undefined && "callback" in options) { throw new DeepgramError( "Callback cannot be provided as an option to a synchronous transcription. Use `transcribeUrlCallback` or `transcribeFileCallback` instead." ); } + if (options?.keyterm?.length && !options.model?.startsWith("nova-3")) { + throw new DeepgramError("Keyterms are only supported with the Nova 3 models."); + } const requestUrl = this.getRequestUrl(endpoint, {}, { ...{}, ...options });
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
examples/node-agent-live/index.js(1 hunks)examples/node-live/index.js(1 hunks)examples/node-prerecorded/index.js(2 hunks)src/lib/types/AgentLiveSchema.ts(1 hunks)src/lib/types/TranscriptionSchema.ts(1 hunks)src/packages/AgentLiveClient.ts(1 hunks)src/packages/ListenLiveClient.ts(1 hunks)src/packages/ListenRestClient.ts(1 hunks)
🔇 Additional comments (6)
examples/node-agent-live/index.js (1)
31-31: LGTM! Change is consistent with other files.The property rename from
keytermstokeytermin the agent configuration matches the changes in other files.examples/node-live/index.js (1)
23-24: LGTM! Change aligns with documentation comment.The property rename from
keytermstokeytermmatches the "Keyterm Prompting" terminology in the comment above.src/lib/types/AgentLiveSchema.ts (1)
170-172: LGTM! Type definition maintains array support.The property rename from
keytermstokeytermin the type definition:
- Maintains the
string[]type- Aligns with the documentation link
- Matches the implementation in example files
src/packages/ListenLiveClient.ts (1)
38-38: LGTM!The condition has been correctly updated to check for the new
keytermproperty.src/packages/AgentLiveClient.ts (1)
124-124: LGTM!The condition has been correctly updated to check for the new
keytermproperty.src/packages/ListenRestClient.ts (1)
55-55: LGTM!The condition has been correctly updated to check for the new
keytermproperty.
| @@ -12,7 +12,7 @@ const transcribeUrl = async () => { | |||
| }, | |||
| { | |||
| model: "nova-3", | |||
| keyterms: ["spacewalk"], | |||
| keyterm: ["spacewalk"], | |||
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify array syntax with renamed property.
The property has been renamed from keyterms to keyterm, but it still accepts an array value. Let's verify this is the intended behavior.
Also applies to: 33-33
🌐 Web query:
What is the correct syntax for the keyterm parameter in Deepgram API v2?
💡 Result:
The correct syntax for keyword boosting in Deepgram API v2 involves using multiple keywords parameters with optional weight modifiers. Here's how to implement it:
Basic Syntax
For standard keyword boosting without custom weights:
options = PrerecordedOptions(
keywords=["epistemology", "ontology"]
)This sends two keywords as separate parameters[1][4].
Weighted Syntax
To assign importance levels (weights):
options = PrerecordedOptions(
keywords=["deepgram:10", "api:5"]
)The colon separates keyword from its weight (1-10 scale)[10].
Key Implementation Details
- Use array format for multiple keywords[7]
- Weight defaults to 1 if unspecified[10]
- Maximum recommended: 100 keywords per request[1]
- Works best with uncommon words/proper nouns[3][4]
For API v2 specifically:
response = deepgram.listen.rest.v("2").transcribe_file(
payload,
options=options
)The keyword parameter remains consistent across API versions but requires using appropriate SDK methods for each version[7][9].
Note: While called "keyword boosting" in documentation[4], the actual parameter name is keywords (plural)[10]. Avoid confusing it with non-existent keyterm parameter mentioned in some third-party implementations[3].
Citations:
- 1: https://dev.to/deepgram/keywords-vs-search-38g3
- 2: https://apitracker.io/a/deepgram
- 3: https://docs.vapi.ai/customization/custom-keywords
- 4: https://deepgram.com/learn/everything-you-need-to-know-about-keywords-for-speech-recognition
- 5: https://developers.deepgram.com/reference/deepgram-api-overview
- 6: https://flancer32.com/live-speech-to-text-recognition-with-deepgram-api-in-pwa-6fa4068878e0
- 7: https://github.com/deepgram/deepgram-python-sdk
- 8: https://developers.deepgram.com/docs/introduction
- 9: https://github.com/orgs/deepgram/discussions/577
- 10: https://developers.deepgram.com/docs/keywords
Update property name to match Deepgram API v2 requirements.
The Deepgram API v2 documentation specifies using the keywords (plural) parameter with an array value for keyword boosting, not keyterm or keyterms. Although the array syntax is correct, please update the property name in the example code accordingly.
- Location:
examples/node-prerecorded/index.js- Lines 15 and 33 should use
keywordsinstead ofkeyterm.
- Lines 15 and 33 should use
| @@ -97,7 +97,7 @@ interface TranscriptionSchema extends Record<string, unknown> { | |||
| /** | |||
| * @see https://developers.deepgram.com/docs/keyterm | |||
| */ | |||
| keyterms?: string[] | string; | |||
| keyterm?: string[] | string; | |||
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify breaking change impact.
The renaming of keyterms to keyterm is a breaking change that will affect consumers of this interface. Ensure this change is properly documented in the changelog and that the major version is bumped accordingly.
Run the following script to find all usages of the old property name:
🏁 Script executed:
#!/bin/bash
# Description: Find any remaining usages of the old property name.
rg -i "keyterms" --type tsLength of output: 384
Action: Update error messages and documentation for the property rename
The change from keyterms to keyterm in src/lib/types/TranscriptionSchema.ts is indeed breaking. Additionally, our search shows that the term "Keyterms" still appears in error messages in the following files:
src/packages/ListenLiveClient.tssrc/packages/ListenRestClient.tssrc/packages/AgentLiveClient.ts
Please verify that these error messages are either updated to reflect the new property name or that they clearly communicate the intended behavior. Also, ensure that the changelog documents this breaking change and that the major version is bumped accordingly.
|
This actually causes more confusion I think because the old property uses |
Summary by CodeRabbit