Merge pull request #44 from fixie-ai/ben/add-changelog

new pages and nav menu

docs/astro.config.mjs

@@ -58,7 +58,13 @@ export default defineConfig({
           'datamessages'
         ]
       },
-
+      {
+        label: 'Updates & Roadmap',
+        collapsed: true,
+        autogenerate: {
+          directory: 'updates'
+        }
+      },
     ],
     components: {}
   }), 

docs/src/content/docs/api/calls.mdx

@@ -147,9 +147,9 @@ An optional query parameter called `priorCallId` can be provided to continue a p
         <th class="w-10/12"></th>
       </tr>
       <tr>
-        <td class="font-mono">initiator</td>
+        <td class="font-mono">firstSpeaker</td>
         <td>string</td>
-        <td>Who was responsible for starting this call. Typically set to INITIATOR_AGENT for outgoing calls and left as the default (INITIATOR_USER) otherwise.</td>
+        <td>Who should talk first when the call starts. Typically set to FIRST_SPEAKER_USER for outgoing calls and left as the default (FIRST_SPEAKER_AGENT) otherwise.</td>
       </tr>
       <tr>
         <td class="font-mono">initialMessages</td>

docs/src/content/docs/guides/stages.mdx

@@ -125,7 +125,6 @@ Here is the list of all call properties that can and cannot be changed during a
 | timeExceededMessage | No                     |
 | inactivityMessages  | No                     |
 | medium              | No                     |
-| initiator           | No                     |
 | recordingEnabled    | No                     |
 
 

docs/src/content/docs/migration/firstspeaker.mdx

@@ -0,0 +1,24 @@
+---
+title: "Migrating to firstSpeaker (from initiator)"
+description: How to migrate to firstSpeaker as part of the deprecation of initiator.
+sidebar:
+  hidden: true
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+`initiator` is being removed as an option when [creating a call](/api/calls/#create-call).
+
+It has been replaced with `firstSpeaker`.
+
+## Why Change?
+`initiator` was confusing as it was used to indicate who was responsible for starting the call (`INITIATOR_USER` or `INITIATOR_AGENT`). It was set to agent for any outgoing calls or left as the default (user) for in-bound calls.
+
+`firstSpeaker` more clearly indicates who speaks first during the call. For inbound calls, the default (`FIRST_SPEAKER_AGENT`) will have the agent answer the call. For outgoing calls, setting it to `FIRST_SPEAKER_USER` indicates the expectation that most people answer a phone call with "Hello?".
+
+## How to Migrate
+* If you previously set `initiator` to `INITIATOR_AGENT`, set `firstSpeaker` to `FIRST_SPEAKER_USER` instead to maintain the same behavior.
+* If you previously set `initiator` to `INITIATOR_USER`, set `firstSpeaker` to `FIRST_SPEAKER_AGENT` instead to maintain the same behavior.
+* If you weren't setting `initiator`, you can continue not setting `firstSpeaker`.
+
+Note: If you use `FIRST_SPEAKER_AGENT` for outbound calls, the first part of the agent's utterance might be clipped due to delays in the phone network.

docs/src/content/docs/updates/changelog.mdx

@@ -0,0 +1,103 @@
+---
+title: "Changelog"
+description: Track API changes, feature updates, and SDK releases for the Ultravox platform.
+sidebar:
+  order: 20
+draft: true
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import CallOut from '@components/CallOut.astro';
+
+<CallOut
+  title="Active Breaking Changes"
+  text="View current deprecation notices and migration timelines in our "
+  link={{ url: "../deprecation", text: "Deprecation Guide." }}
+/>
+
+## Quick Navigation
+- [Latest Version](#version-xyz-yyyy-mm-dd)
+- [Previous Versions](#previous-versions)
+- [All Versions](https://github.com/your-org/ultravox/releases)
+
+## Version [X.Y.Z] - YYYY-MM-DD
+
+### API Changes
+
+#### Breaking Changes 🚨
+- Description of breaking change
+- [Migration guide](/migration/feature)
+- Affected endpoints/features
+
+#### New Endpoints
+- Endpoint name and description
+- Example usage
+```javascript
+// Example request
+const response = await fetch('https://api.ultravox.ai/api/new-endpoint', {
+    method: 'POST',
+    headers: {
+        'X-API-Key': 'your_api_key'
+    }
+});
+```
+
+#### Updates to Existing Endpoints
+- Endpoint modifications
+- New parameters/response fields
+- Behavior changes
+
+### Feature Updates
+
+#### New Features 🎉
+- Feature name and description
+- Getting started link
+- Implementation examples
+
+#### Improvements ⚡
+- Enhancement details
+- Impact on existing implementations
+- Performance metrics when applicable
+
+#### Bug Fixes 🐛
+- Issue description
+- Resolution details
+- Affected versions
+
+### SDK Updates
+
+<Tabs>
+  <TabItem label="JavaScript">
+    - Version: x.y.z
+    - Installation: `npm install @ultravox/[email protected]`
+    - Breaking changes
+    - New features
+    - Bug fixes
+  </TabItem>
+  <TabItem label="Flutter">
+    - Version: x.y.z
+    - Installation: `flutter pub add ultravox_client`
+    - Breaking changes
+    - New features
+    - Bug fixes
+  </TabItem>
+  <TabItem label="Kotlin">
+    - Version information
+    - Installation steps
+    - Changes and updates
+  </TabItem>
+  <TabItem label="Python">
+    - Version information 
+    - Installation steps
+    - Changes and updates
+  </TabItem>
+</Tabs>
+
+## Previous Versions
+
+### Version [X.Y.Z-1] - YYYY-MM-DD
+[Content follows same structure as above]
+
+:::note[Version History]
+For a complete version history, visit our [GitHub releases page](https://github.com/your-org/ultravox/releases).
+:::

docs/src/content/docs/updates/deprecation.mdx

@@ -0,0 +1,62 @@
+---
+title: "Deprecation Guide"
+description: Track upcoming breaking changes, migration timelines, and deprecation notices for the Ultravox platform.
+sidebar:
+  order: 50
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Active Deprecations
+
+### Currently Scheduled Changes
+
+| Feature/API | Status       | Deprecation Date | Removal Date | Migration Guidance               |
+| ----------- | ------------ | ---------------- | ------------ |----------------------------------|
+| `initiator` | ⚠️ < 30 days  | 2024-10-01       | 2024-12-31   | [Guide](/migration/firstspeaker) |
+
+## Deprecation Process
+We recognize that breaking changes and deprecation notices are not fun and we try to avoid them when possible.
+
+However, the Ultravox APIs have not yet reached v1 and we are committed to having our APIs and SDKs work better and be as clear as possible. This means we will inevitably need to revisit some choices early on.
+
+This process will evolve as the APIs mature. Please share your feedback with us if you'd like to see any changes to the process or policy.
+
+### Lifecycle Stages
+
+<Tabs>
+  <TabItem label="1. Announcement">
+    - Feature marked as deprecated in documentation
+    - Migration guidance published
+  </TabItem>
+  <TabItem label="2. Deprecation Period">
+    - Minimum 30-day window 
+    - Reminders in changelog and community updates
+    - Direct communications to affected users
+  </TabItem>
+  <TabItem label="3. Removal">
+    - Feature removed
+    - Fallback behavior documented if applicable
+  </TabItem>
+</Tabs>
+
+## Deprecation Policy
+
+### Standard Timeline
+- Pre-release features: 30-day minimum deprecation period
+- Breaking changes require publication of migration guidance
+
+### Security Exceptions
+Critical security updates may bypass the standard deprecation timeline. These will be:
+- Clearly marked and documented
+- Communicated directly to affected users
+- Accompanied by immediate mitigation steps
+
+## Migration Guides
+
+### Current Migrations
+- [Migrating from Call `initiator`](/migration/firstspeaker)
+
+:::note[Need Help?]
+If you need assistance with a migration, please visit our [Discord community ](https://discord.gg/Qw6KHxv8YB).
+:::

docs/src/content/docs/updates/news.mdx

@@ -0,0 +1,135 @@
+---
+title: "News & Updates"
+description: Stay informed about Ultravox platform announcements.
+sidebar:
+  order: 01
+---
+
+import { Card } from '@astrojs/starlight/components';
+
+## Latest Update
+
+### 2024-11-14 - Ultravox v0.4.1 Release
+We're excited to announce the release of Ultravox v0.4.1, which brings significant improvements to the model you're already using. We've also added a new web console and have enabled your agents to start conversations via text.
+
+#### What's Hot
+1. Ultravox v0.4.1:  Six new languages, higher quality, new variants.
+1. Ultravox Console:  Your web playground and place to manage your account.
+1. initialOutputMedium: Agents can now start conversations via text.
+
+##### Ultravox v0.4.1
+**Expanded Language Coverage**
+* Added 6 new languages (Chinese, Dutch, Hindi, Swedish, Turkish, and Ukrainian).
+* Total of 15 languages are now supported by the model.
+
+**Enhanced Performance**
+* Improved BLEU scores across all languages.
+* Now achieving average BLEU score of 38.97 (vs. GPT-4's 40.35).
+
+**New Model Variants**
+* Added Mistral NeMo variant.
+* Updated Llama variants (8B model and 70B model) trained on 8xH100s.
+
+The 0.4.1 updates are now live as the default on our managed Ultravox Realtime APIs. Pricing starts at just 5 cents per minute (⅓ the cost of GPT-4o).
+
+The model weights are available on [Hugging Face](https://huggingface.co/fixie-ai), and you can find detailed release notes on our [GitHub repository](https://github.com/fixie-ai/ultravox). If you need on-premises support for end-to-end data sovereignty, please reach out via email or set-up a call to discuss.
+
+For insights into our roadmap and strategy and to see a live demonstration of the new model in action, check out our latest [blog post](https://www.ultravox.ai/blog/ultravox-an-open-weight-alternative-to-gpt-4o-realtime).
+
+##### Ultravox Console
+There's now a web-based console application at https://app.ultravox.ai that you can use for keeping track of usage, generating API keys, managing your subscription, and playing around with different voices and system prompts. The console is a work-in-progress so don't hesitate to reach out with requests for new features!
+
+##### initialOutputMedium
+This new property can be set at call creation to have the agent's initial output be text (voice remains the default). This enables text-based scenarios and can be used with the SDK's [`setOutputMedium()`](../sdk/#setoutputmedium) to toggle between text and voice. Check out the Create Call docs for more info.
+
+#### What's Next
+We're already working on the next major release of Ultravox with even more exciting features. Your feedback has been invaluable in shaping our development, and we'd love to hear your thoughts on these latest improvements.
+
+<Card title="Be in the Know">
+  All Ultravox customers automatically receive email updates. Create a [free account](https://app.ultravox.ai) to start building with the the best voice AI and to stay in the loop.
+</Card>
+
+## Prior Updates
+
+### 2024-10-18 - Call Stages and Client-Implemented Tools
+We're thrilled to share the latest updates we've made to the Ultravox APIs. All of these enhancements have been made due to feedback from our community. Please keep the feedback coming! If there's anything we can do to make things work better for you, don't hesitate to get in touch!
+
+#### What's Hot
+1. Call Stages: Dynamic, Multi-Stage Conversations
+1. Client-Implemented Tools: Implement Tools in Your App
+1. More Improvements: setOutputMedium + Webhooks
+
+##### Call Stages: Dynamic, Multi-Stage Conversations
+* **What's new:** Stages enable more complex and nuanced agent interactions, giving you fine-grained control over the conversation flow.
+* **Why it matters:** Each stage can have a new system prompt, a different set of tools, a new voice, an updated conversation history, and more.
+* **Where to use:** Stages are designed for complex conversational flows like data gathering (job applications, medical intake forms, applying for a mortgage) or context switching (customer support escalation, triaging IT issues).
+* **Where to start:** Check our [docs](../guides/stages/) for the details on how to get started.
+
+##### Client-Implemented Tools: Implement Tools in Your App
+* **What's new:** In our previous update we added support for tools. Those were “server” tools and required you to implement the logic on a server and expose things via a URL. Client-implemented tools enable putting all the logic in your client application and are still called by your agent.
+* **Why it matters:** Enable dynamic UI or other interactivity in your app without having to rely on putting all the logic on a server.
+* **Learn more:** Visit our [SDK page](../sdk/#client-tools) for more info.
+
+##### More Improvements: setOutputMedium + Webhooks
+* **setOutputMedium():** Added to our SDKs to give you more control over how your agents respond. Allows toggling the agent's output between text and voice. See the [docs](../sdk/#setoutputmedium).
+* **Webhooks:** Ultravox now has [webhooks](../api/webhooks/) for two key events: `call.started` and `call.ended`. This opens up new opportunities for triggering external processes when calls start/end, logging call data in real-time to your own systems, or integrating Ultravox more deeply with other workflows.
+
+#### What's Not
+1. Breaking Change: SDK SessionState
+1. Deprecation Notice: initiator on new call creation
+
+We recognize that breaking changes and deprecation notices are not fun and we try to avoid them when possible. However, we are committed to having our APIs and SDKs work better and be as clear as possible. That means we will inevitably need to revisit some choices early on.
+
+##### Breaking Change: SDK SessionState
+In the latest versions of our client SDKs, the UltravoxSession joinCall() method no longer returns an object. UltravoxSession now exposes properties for `status` and `transcripts`.
+
+##### Deprecation: `initiator` is now `firstSpeaker`
+This change is being made because `firstSpeaker` is more descriptive of what is happening when the call starts. For example, if you are making an outgoing call, you expect the user to answer the call and be the first to speak.
+When creating a new call, you should start using `firstSpeaker` and choose either “FIRST_SPEAKER_AGENT” (the default) or “FIRST_SPEAKER_USER” (for outgoing calls) as the value.
+
+_`initiator` will be removed at the end of November, 2024._
+
+#### What's Next
+We are working on a new version of the Ultravox model that will add new language support for Chinese, Dutch, Hindi, Swedish, Turkish, and Ukrainian. We are also creating a web-based application for the Ultravox service (sign-up, API key management, usage tracking) and are adding a Swift client SDK for iOS developers.
+
+If you have any suggestions for new features or improvements, please don't hesitate to reach out.
+
+### 2024-09-30 - 70B and Tools
+We are continuing to get great feedback (thank you!) and have been working to add more capabilities.
+
+#### What's Hot
+1. Ultravox 70B: Our Smartest Model Yet
+1. Tools Support: Give Your Agents New Abilities
+1. Expanded SDK Coverage: Flutter, Kotlin, and Python
+
+##### 1. Ultravox 70B: Brains Meet Brawn
+* **Why it matters:** More complex reasoning, better understanding
+* **How to use:** It's now the default! Just use 'fixie-ai/ultravox' in your API calls
+* **Pro tip:** Need the 8B version? Use 'fixie-ai/ultravox-8B' (Note: Tools not supported)
+* **Model weights:** Available on [HuggingFace](https://huggingface.co/fixie-ai/ultravox-v0_4-llama-3_1-70b)
+
+##### 2. Tools: Your AI's New Superpowers
+* **What's new:** Durable tools (create once, use often) and Temporary tools (perfect for iterating)
+* **Where to start:** Check our [docs](../tools/) for the how-to
+* **See it in action:** Try our [tools demo](https://demo.ultravox.ai/) on our website
+
+##### 3. New SDKs: Code Your Way
+* **New additions:** Flutter, Kotlin, and Python join our JavaScript SDK
+* **Cool features:** [Debug Messages](../sdk/#debug-messages), mic/speaker controls
+* **Learn more:** Visit our [SDK page](../sdk/) for details
+
+#### In Case You Missed It
+* **Price drop:** Now just $0.05/minute (cheaper than coffee, and way more talkative!)
+* **Voice cloning:** Create [customized voices](../api/voices/#create-clone-voice) for your agents
+* **Conversation continuity:** Because [why start over](../api/calls/#create-call)?
+
+#### What's Next?
+You tell us! We're all ears for your suggestions to make Ultravox even better for you.
+
+### 2024-09-04 - Price Reduction, Resume Calls, Voice Cloning
+* Our managed Ultravox APIs are getting _much_ cheaper. We're decreasing our price to **$0.05/min**. That's full-on, real-time, speech-to-speech voice chat. We think this is the highest quality, lowest cost system out there.
+* We continue to offer 30 minutes of free usage to try it out for yourself. If you'd like to continue using our managed APIs after that, you'll need to set up a Stripe subscription. You can now do that by accessing the billingUrl from the new [/accounts API](../api/accounts/).
+* We've added the ability to seamlessly continue a prior conversation. This is as simple as passing in a priorCallId parameter when [starting a call](../api/calls/). 
+* We've added support for [Voice Cloning](../api/voices/#create-clone-voice). 
+* We released a new version of the Ultravox Model, [v0.4](https://github.com/fixie-ai/ultravox/releases/tag/v0.4).
+* Tool support is coming very soon!

examples/twilio-outgoing-call/README.md

@@ -15,7 +15,7 @@ This project uses `pnpm`.
 ```javascript
 {
   ...
-  "initiator": "agent",
+  "firstSpeaker": "FIRST_SPEAKER_USER",
   "medium": { "twilio": {} }
 }
 ```