Update UPGRADING.md

Author: zeke

UPGRADING.md

@@ -1,10 +1,10 @@
 # Upgrading from v1 to v2
 
-This guide helps you migrate from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support.
+This guide will help you migrate an existing codebase from the v1 Replicate Python SDK to v2. The v2 SDK is a complete rewrite generated in partnership with [Stainless](https://www.stainless.com/customers/replicate), the folks who help build and maintain SDKs for companies like OpenAI, Anthropic, and Cloudflare. The v2 SDK is largely autogenerated from Replicate's OpenAPI specification, providing better type safety, more consistent error handling, and improved async support. Check out the [v2 release notes](#TODO) for more details.
 
-This doc is intended for both humans and agents.
+✋ If you are working on a new project, you don't need to read this document.
 
-If you're using an AI tool to assist with the upgrade process, you can provide it with this entire document as context.
+This doc is intended for both humans and agents. 🧑🏽‍🦰 🤝 🤖
 
 ## Installing the v2 SDK    
 
@@ -14,9 +14,7 @@ Use pip to install the latest pre-release version of the v2 SDK:
 pip install --pre replicate
 ```
 
-The v2 SDK requires Python 3.8 or higher, same as v1.
-
-## Pinning to 1.x
+## Pinning to the legacy v1 SDK
 
 You are not required to upgrade to the new 2.x version. If you're already using the 1.x version and want to continue using it, pin the version number in your dependency files.
 
@@ -45,14 +43,18 @@ dependencies = [
 
 ## Client initialization and authentication
 
-In both the v1 and v2 SDKs, the simplest usage pattern is to import the `replicate` module and use the module-level functions like `replicate.run()`, which automatically uses the `REPLICATE_API_TOKEN` environment variable, without explicitly instantiating a client:
+In both the v1 and v2 SDKs, the simplest way to import and use the library is to import the `replicate` module and use the module-level functions like `replicate.run()`, without explicitly instantiating a client:
 
 ```python
 import replicate
 
 output = replicate.run(...)
 ```
 
+☝️ This approach expects a `REPLICATE_API_TOKEN` variable to be present in the environment.
+
+---
+
 For cases where you need to instantiate a client (e.g., for custom configuration or async support), the client class name and parameter names have changed in v2:
 
 ### Before (v1)
@@ -79,7 +81,9 @@ The `api_token` parameter is still accepted for backward compatibility, but `bea
 
 ## Streaming output
 
-Streaming works differently in v2. Prediction objects no longer have a `stream()` method. Use `replicate.use()` with `streaming=True` for streaming output.
+Streaming works differently in v2. Prediction objects no longer have a `stream()` method and the `replicate.stream()` method is deprecated.
+
+You should use `replicate.use()` with `streaming=True` for streaming output in the v2 SDK.
 
 ### Before (v1)
 
@@ -114,7 +118,7 @@ Note: `replicate.stream()` still works in v2 but is deprecated and will be remov
 
 ## Predictions
 
-Prediction objects have changed significantly. Instance methods like `wait()`, `cancel()`, and `reload()` are removed in favor of client methods (e.g., use `replicate.predictions.wait(prediction.id)` instead of `prediction.wait()`).
+Prediction objects in the v2 client no longer have instance methods like `wait()`, `cancel()`, and `reload()`. These have been removed in favor of client methods (e.g., use `replicate.predictions.wait(prediction.id)` instead of `prediction.wait()`).
 
 ### Creating predictions
 
@@ -355,7 +359,9 @@ for prediction in page.results:
 
 ## Models and versions
 
-Model and version access uses keyword arguments throughout.
+Model and version access uses keyword arguments throughout, instead of shorthand positional arguments.
+
+The new keyword argument syntax in v2 is more verbose but clearer and more consistent with Replicate's HTTP API, and consistent across all SDKs in different programming languages.
 
 ### Before (v1)
 
@@ -397,7 +403,7 @@ The `model.versions` shorthand is not available in v2.
 
 ## Trainings
 
-Training objects also lose their instance methods in v2.
+Training objects do not have the `.wait()` and `.cancel()` instance methods in v2.
 
 ### Before (v1)
 
@@ -521,7 +527,7 @@ secret = replicate.webhooks.default.secret()
 Webhooks.validate(request, secret)
 ```
 
-The validation logic is identical; only import paths may differ.
+The validation logic is identical; only the import paths differ.
 
 ## Experimental use() interface
 
@@ -621,25 +627,11 @@ The following features are not available in v2:
 - Model instance methods: `predict()`
 - `model.versions` shorthand (use `replicate.models.versions` instead)
 - Separate `async_*` methods (use `AsyncReplicate` client)
-- Positional arguments (all methods require keyword arguments)
-
-## Migration strategy
-
-For a gradual migration:
-
-1. Start by updating client initialization and imports
-2. Replace prediction instance methods with resource methods
-3. Update async code to use `AsyncReplicate`
-4. Add keyword arguments to all API calls
-5. Update error handling to use specific exception types
-6. Test thoroughly, especially prediction lifecycle code
-
-For codebases with extensive v1 usage, consider creating adapter functions to bridge the differences while you migrate incrementally.
+- Positional arguments (all API operation methods like `models.get` and `collections.let` require keyword arguments)
 
 ## Getting help
 
-If you encounter issues during migration:
+If you encounter issues during the migration process:
 
 - Check the [API documentation](https://replicate.com/docs/reference/http)
-- Review the [full API reference](api.md)
 - Open an issue on [GitHub](https://github.com/replicate/replicate-python-stainless/issues)