Skip to content

Commit 11d9042

Browse files
GregHolmesGregHolmes
committed
chore: add v0.2 to v0.3 migration guide
1 parent f1bac65 commit 11d9042

2 files changed

Lines changed: 261 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ Power your applications with world-class speech and language AI models.
1414

1515
You can learn more about the Deepgram API at [developers.deepgram.com](https://developers.deepgram.com).
1616

17+
### Migrating Between Versions
18+
19+
- [v0.2 to v0.3](./docs/Migrating-v0.2-to-v0.3.md) (current)
20+
1721
## Installation
1822

1923
### Gradle

‎docs/Migrating-v0.2-to-v0.3.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# v0.2 to v0.3 Migration Guide
2+
3+
This guide helps you migrate from Deepgram Java SDK v0.2.x (versions 0.2.0 to 0.2.1) to v0.3.0. The `0.3.0` release is still pre-`1.0`, but it does include breaking source changes from the April 27 SDK regeneration.
4+
5+
The biggest changes are:
6+
7+
1. Agent think/speak configuration types were consolidated into shared top-level schemas in `com.deepgram.types`
8+
2. `Listen V2` WebSocket connect options now use typed model values instead of raw strings
9+
3. Several generated agent-local helper types were removed
10+
11+
## Table of Contents
12+
13+
- [Installation](#installation)
14+
- [Configuration Changes](#configuration-changes)
15+
- [Authentication Changes](#authentication-changes)
16+
- [API Method Changes](#api-method-changes)
17+
- [Listen V1 (REST)](#listen-v1-rest)
18+
- [Listen V2 (WebSocket)](#listen-v2-websocket)
19+
- [Speak V1](#speak-v1)
20+
- [Agent V1 (WebSocket)](#agent-v1-websocket)
21+
- [Read V1](#read-v1)
22+
- [Manage V1](#manage-v1)
23+
- [Self-Hosted V1](#self-hosted-v1)
24+
- [Type Changes](#type-changes)
25+
- [Agent Think and Speak Types](#agent-think-and-speak-types)
26+
- [Listen V2 Model Types](#listen-v2-model-types)
27+
- [Other Removed Generated Types](#other-removed-generated-types)
28+
- [Breaking Changes Summary](#breaking-changes-summary)
29+
30+
## Installation
31+
32+
Upgrade to `0.3.0` with Gradle or Maven.
33+
34+
**Gradle**
35+
36+
```groovy
37+
dependencies {
38+
implementation 'com.deepgram:deepgram-java-sdk:0.3.0'
39+
}
40+
```
41+
42+
**Maven**
43+
44+
```xml
45+
<dependency>
46+
<groupId>com.deepgram</groupId>
47+
<artifactId>deepgram-java-sdk</artifactId>
48+
<version>0.3.0</version>
49+
</dependency>
50+
```
51+
52+
## Configuration Changes
53+
54+
No changes. Client construction is unchanged between `0.2.x` and `0.3.0`.
55+
56+
```java
57+
import com.deepgram.DeepgramClient;
58+
59+
DeepgramClient client = DeepgramClient.builder().build();
60+
61+
DeepgramClient explicitClient = DeepgramClient.builder()
62+
.apiKey("YOUR_DEEPGRAM_API_KEY")
63+
.build();
64+
```
65+
66+
## Authentication Changes
67+
68+
No changes. API key, access token, and session ID configuration all work the same as in `0.2.x`.
69+
70+
## API Method Changes
71+
72+
### Listen V1 (REST)
73+
74+
No breaking client-method changes. Existing prerecorded transcription code continues to work.
75+
76+
### Listen V2 (WebSocket)
77+
78+
The main breaking change is the `model(...)` type in `V2ConnectOptions`.
79+
80+
**v0.2.x**
81+
82+
```java
83+
wsClient.connect(
84+
V2ConnectOptions.builder()
85+
.model("flux-general-en")
86+
.build());
87+
```
88+
89+
**v0.3.0**
90+
91+
```java
92+
import com.deepgram.types.ListenV2Model;
93+
94+
wsClient.connect(
95+
V2ConnectOptions.builder()
96+
.model(ListenV2Model.FLUX_GENERAL_EN)
97+
.build());
98+
```
99+
100+
If you previously passed a dynamic string, use `ListenV2Model.valueOf(...)`.
101+
102+
```java
103+
ListenV2Model model = ListenV2Model.valueOf("flux-general-en");
104+
```
105+
106+
`sendConfigure(...)` and generated `ListenV2Configure*` types are new in `0.3.0`, but they do not require any migration for existing `0.2.x` code.
107+
108+
### Speak V1
109+
110+
No breaking client-method changes to the REST or WebSocket speak clients.
111+
112+
### Agent V1 (WebSocket)
113+
114+
No core WebSocket client methods were removed, but the generated think/speak configuration types changed significantly.
115+
116+
If your code imported agent-local generated classes from `com.deepgram.resources.agent.v1.types`, you will likely need to update those imports and builders.
117+
118+
`0.3.0` also adds new WebSocket capabilities:
119+
120+
- `sendUpdateThink(...)`
121+
- `onThinkUpdated(...)`
122+
- `onAgentV1History(...)`
123+
124+
These are additive and do not require migration unless you want to use the new events/messages.
125+
126+
### Read V1
127+
128+
No breaking client-method changes.
129+
130+
### Manage V1
131+
132+
No breaking changes to existing management client entry points.
133+
134+
`0.3.0` also adds new reusable voice agent configuration and variable clients under `client.voiceAgent()`.
135+
136+
### Self-Hosted V1
137+
138+
No breaking client-method changes.
139+
140+
## Type Changes
141+
142+
### Agent Think and Speak Types
143+
144+
The largest source-level change in `0.3.0` is a consolidation of agent think/speak schemas into shared top-level types under `com.deepgram.types`.
145+
146+
This mostly affects code that imported types from `com.deepgram.resources.agent.v1.types` directly.
147+
148+
| v0.2.x | v0.3.0 | Import from |
149+
|---|---|---|
150+
| `AgentV1SettingsAgentSpeakEndpoint` | `SpeakSettingsV1` | `com.deepgram.types` |
151+
| `AgentV1SettingsAgentSpeakOneItem` | `SpeakSettingsV1` | `com.deepgram.types` |
152+
| `AgentV1SettingsAgentSpeakEndpointEndpoint` | `SpeakSettingsV1Endpoint` | `com.deepgram.types` |
153+
| `AgentV1SettingsAgentSpeakOneItemEndpoint` | `SpeakSettingsV1Endpoint` | `com.deepgram.types` |
154+
| `AgentV1SettingsAgentSpeakEndpointProvider*` | `SpeakSettingsV1Provider` plus top-level provider models | `com.deepgram.types` |
155+
| `AgentV1SettingsAgentSpeakOneItemProvider*` | `SpeakSettingsV1Provider` plus top-level provider models | `com.deepgram.types` |
156+
| `AgentV1SettingsAgentThinkOneItem` | `ThinkSettingsV1` | `com.deepgram.types` |
157+
| `AgentV1SettingsAgentThinkOneItemProvider` | `ThinkSettingsV1Provider` | `com.deepgram.types` |
158+
| `AgentV1SettingsAgentThinkOneItemContextLength` | `ThinkSettingsV1ContextLength` | `com.deepgram.types` |
159+
| `AgentV1SettingsAgentThinkOneItemEndpoint` | `ThinkSettingsV1Endpoint` | `com.deepgram.types` |
160+
| `AgentV1SettingsAgentThinkOneItemFunctionsItem` | `ThinkSettingsV1FunctionsItem` | `com.deepgram.types` |
161+
| `AgentV1SettingsAgentThinkOneItemFunctionsItemEndpoint` | `ThinkSettingsV1FunctionsItemEndpoint` | `com.deepgram.types` |
162+
| `AgentV1UpdateSpeakSpeakEndpoint` | `SpeakSettingsV1` | `com.deepgram.types` |
163+
| `AgentV1UpdateSpeakSpeakOneItem` | `SpeakSettingsV1` | `com.deepgram.types` |
164+
| `AgentV1UpdateSpeakSpeakEndpointProvider*` | `SpeakSettingsV1Provider` plus top-level provider models | `com.deepgram.types` |
165+
| `AgentV1UpdateSpeakSpeakOneItemProvider*` | `SpeakSettingsV1Provider` plus top-level provider models | `com.deepgram.types` |
166+
167+
In practice, the `AgentV1SettingsAgentThink` and `AgentV1SettingsAgentSpeak` union wrappers still exist, but the values you wrap are now shared `ThinkSettingsV1` and `SpeakSettingsV1` objects.
168+
169+
**v0.2.x**
170+
171+
```java
172+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeak;
173+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeakEndpoint;
174+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThink;
175+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThinkOneItem;
176+
177+
// Old agent-local generated types
178+
AgentV1SettingsAgentSpeak speak = AgentV1SettingsAgentSpeak.of(/* agent-local speak type */);
179+
AgentV1SettingsAgentThink think = AgentV1SettingsAgentThink.of(
180+
java.util.List.of(/* AgentV1SettingsAgentThinkOneItem */));
181+
```
182+
183+
**v0.3.0**
184+
185+
```java
186+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentSpeak;
187+
import com.deepgram.resources.agent.v1.types.AgentV1SettingsAgentThink;
188+
import com.deepgram.types.OpenAiThinkProvider;
189+
import com.deepgram.types.OpenAiThinkProviderModel;
190+
import com.deepgram.types.ThinkSettingsV1;
191+
import com.deepgram.types.ThinkSettingsV1Provider;
192+
193+
OpenAiThinkProvider provider = OpenAiThinkProvider.builder()
194+
.model(OpenAiThinkProviderModel.GPT4O_MINI)
195+
.build();
196+
197+
AgentV1SettingsAgentThink think = AgentV1SettingsAgentThink.of(
198+
ThinkSettingsV1.builder()
199+
.provider(ThinkSettingsV1Provider.openAi(provider))
200+
.prompt("You are a helpful assistant.")
201+
.build());
202+
```
203+
204+
### Listen V2 Model Types
205+
206+
`V2ConnectOptions.model(...)` is now typed as `ListenV2Model` instead of `String`.
207+
208+
| v0.2.x | v0.3.0 |
209+
|---|---|
210+
| `.model("flux-general-en")` | `.model(ListenV2Model.FLUX_GENERAL_EN)` |
211+
| `.model(dynamicString)` | `.model(ListenV2Model.valueOf(dynamicString))` |
212+
213+
### Other Removed Generated Types
214+
215+
These generated type families were removed or folded into shared top-level types:
216+
217+
- `AgentV1SettingsAgentSpeakEndpoint*`
218+
- `AgentV1SettingsAgentSpeakOneItem*`
219+
- `AgentV1SettingsAgentThinkOneItem*`
220+
- `AgentV1UpdateSpeakSpeakEndpoint*`
221+
- `AgentV1UpdateSpeakSpeakOneItem*`
222+
223+
`0.3.0` also adds new generated types such as:
224+
225+
- `AgentV1History`
226+
- `AgentV1ThinkUpdated`
227+
- `AgentV1UpdateThink`
228+
- `ListenV2Configure*`
229+
230+
## Breaking Changes Summary
231+
232+
### Major Changes
233+
234+
1. **Agent think/speak schemas**: agent-local generated classes were consolidated into shared top-level `ThinkSettingsV1*` and `SpeakSettingsV1*` types.
235+
2. **Listen V2 model typing**: `V2ConnectOptions.model(...)` now takes `ListenV2Model` instead of `String`.
236+
3. **Removed generated helper types**: several agent-specific generated helper families were removed.
237+
238+
### Removed Features
239+
240+
- Agent-local speak schema families such as `AgentV1SettingsAgentSpeakEndpoint*` and `AgentV1SettingsAgentSpeakOneItem*`
241+
- Agent-local think helper families such as `AgentV1SettingsAgentThinkOneItem*`
242+
- Agent-local update-speak schema families such as `AgentV1UpdateSpeakSpeakEndpoint*` and `AgentV1UpdateSpeakSpeakOneItem*`
243+
244+
### New Features in v0.3.0
245+
246+
- **Agent history support**: `AgentV1History` WebSocket events
247+
- **Agent think updates**: `sendUpdateThink(...)` and `AgentV1ThinkUpdated`
248+
- **Listen V2 configure support**: `ListenV2Configure*` support in the V2 WebSocket client
249+
- **Voice agent management APIs**: `client.voiceAgent().configurations()` and `client.voiceAgent().variables()`
250+
251+
### Migration Checklist
252+
253+
- [ ] Upgrade to `com.deepgram:deepgram-java-sdk:0.3.0`
254+
- [ ] Replace any removed agent-local think/speak imports with shared `com.deepgram.types.*` types
255+
- [ ] Update `V2ConnectOptions.model(...)` calls to use `ListenV2Model`
256+
- [ ] If you pass dynamic model strings, wrap them with `ListenV2Model.valueOf(...)`
257+
- [ ] Rebuild your project and fix any remaining imports referencing removed generated classes

0 commit comments

Comments
 (0)
⚡