Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: keyterms to keyterm #363

Merged
merged 1 commit into from
Feb 13, 2025
Merged

fix: keyterms to keyterm #363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion examples/node-agent-live/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ const agent = async () => {
agent: {
listen: {
model: "nova-3",
keyterms: ["spacewalk"],
keyterm: ["spacewalk"],
},
speak: {
model: "aura-asteria-en",
Expand Down
2 changes: 1 addition & 1 deletion examples/node-live/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ const live = async () => {
// Time in milliseconds of silence to wait for before finalizing speech
endpointing: 300,
// Keyterm Prompting allows you improve Keyword Recall Rate (KRR) for important keyterms or phrases up to 90%.
keyterms: ["BBC"],
keyterm: ["BBC"],
});

connection.on(LiveTranscriptionEvents.Open, () => {
Expand Down
4 changes: 2 additions & 2 deletions examples/node-prerecorded/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ const transcribeUrl = async () => {
},
{
model: "nova-3",
keyterms: ["spacewalk"],
keyterm: ["spacewalk"],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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:

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 keywords instead of keyterm.

}
);

Expand All @@ -30,7 +30,7 @@ const transcribeFile = async () => {
console.log("Transcribing file", file);
const { result, error } = await deepgram.listen.prerecorded.transcribeFile(file, {
model: "nova-3",
keyterms: ["spacewalk"],
keyterm: ["spacewalk"],
});

if (error) console.error(error);
Expand Down
2 changes: 1 addition & 1 deletion src/lib/types/AgentLiveSchema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ interface AgentLiveSchema extends Record<string, unknown> {
/**
* @see https://developers.deepgram.com/docs/keyterm
*/
keyterms?: string[];
keyterm?: string[];
};
speak: {
/**
Expand Down
2 changes: 1 addition & 1 deletion src/lib/types/TranscriptionSchema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ interface TranscriptionSchema extends Record<string, unknown> {
/**
* @see https://developers.deepgram.com/docs/keyterm
*/
keyterms?: string[] | string;
keyterm?: string[] | string;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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 ts

Length 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.ts
  • src/packages/ListenRestClient.ts
  • src/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.


/**
* @see https://developers.deepgram.com/docs/tagging
Expand Down
2 changes: 1 addition & 1 deletion src/packages/AgentLiveClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ export class AgentLiveClient extends AbstractLiveClient {
*/
public configure(options: AgentLiveSchema): void {
// @ts-expect-error Not every consumer of the SDK is using TypeScript, this conditional exists to catch runtime errors for JS code where there is no compile-time checking.
if (!options.agent.listen.model.startsWith("nova-3") && options.agent.listen.keyterms?.length) {
if (!options.agent.listen.model.startsWith("nova-3") && options.agent.listen.keyterm?.length) {
throw new DeepgramError("Keyterms are only supported with the Nova 3 models.");
}
// Converting the property names...
Expand Down
5 changes: 1 addition & 4 deletions src/packages/ListenLiveClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,7 @@ export class ListenLiveClient extends AbstractLiveClient {
) {
super(options);

if (
transcriptionOptions.keyterms?.length &&
!transcriptionOptions.model?.startsWith("nova-3")
) {
if (transcriptionOptions.keyterm?.length && !transcriptionOptions.model?.startsWith("nova-3")) {
throw new DeepgramError("Keyterms are only supported with the Nova 3 models.");
}

Expand Down
2 changes: 1 addition & 1 deletion src/packages/ListenRestClient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ export class ListenRestClient extends AbstractRestClient {
);
}

if (options?.keyterms?.length && !options.model?.startsWith("nova-3")) {
if (options?.keyterm?.length && !options.model?.startsWith("nova-3")) {
throw new DeepgramError("Keyterms are only supported with the Nova 3 models.");
}

Expand Down
Loading