From d34039f8884522634bbce69d95a383c3856a205b Mon Sep 17 00:00:00 2001
From: Albert Mavashev <amavashev@k2n.io>
Date: Sat, 16 May 2026 11:53:50 -0400
Subject: [PATCH] =?UTF-8?q?docs(rust):=20sync=20async-openai=20version=20p?=
 =?UTF-8?q?in=20with=20the=20example=20(0.30=20=E2=86=92=200.38)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The cycles-client-rust PR (companion to this one) had to bump
async-openai 0.30 → 0.38 to clear `cargo audit --deny warnings` —
0.30.x pulled in `backoff` (RUSTSEC-2025-0012) and `instant`
(RUSTSEC-2024-0384), both flagged as unmaintained. 0.31+ replaced
the retry stack with `tower` and dropped both transitive deps.

Brings this doc in sync with the actual shipped example:

- Cargo.toml snippet: pin to `0.38` with
  `default-features = false, features = ["chat-completion", "rustls"]`
  (the 0.31+ split exposed per-API features; `chat-completion` is what
  makes `Client` and the chat types available).
- All three code blocks (basic, streaming, error-handling): update
  imports from `async_openai::types::` to `async_openai::types::chat::`
  (the chat-completion types moved out of the top-level `types::`
  module in 0.31).
- Replaced the "type paths accurate to the 0.30.x line" caveat with an
  explanation of the 0.30→0.31+ split (feature gating + `types::chat::`
  path move + tower-vs-backoff retry stack swap), so readers
  upgrading from 0.30 understand what changed.
- Dropped the unused `Role` import from the basic example.
---
 how-to/integrating-cycles-with-async-openai.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/how-to/integrating-cycles-with-async-openai.md b/how-to/integrating-cycles-with-async-openai.md
index 4d248c1..8e748a8 100644
--- a/how-to/integrating-cycles-with-async-openai.md
+++ b/how-to/integrating-cycles-with-async-openai.md
@@ -25,19 +25,19 @@ The same lifecycle composes against other Rust LLM clients (Anthropic, Bedrock,
 ```toml
 [dependencies]
 runcycles = "0.2"
-async-openai = "0.30"          # check crates.io for the current version
+async-openai = { version = "0.38", default-features = false, features = ["chat-completion", "rustls"] }
 tokio = { version = "1", features = ["full"] }
 futures = "0.3"                # for stream consumption
 ```
 
-`async-openai` major versions change occasionally. The shape of the API (chat completions, usage, streaming) has been stable for several minor releases; the type paths in this guide are accurate to the 0.30.x line at publication. If you pin a different version, the names below may need a small adjustment.
+`async-openai` 0.31+ splits its surface behind per-API features — the `chat-completion` feature is what makes `Client` and the chat-completion types available. The 0.30.x line bundled everything by default; if you're upgrading from there, the example uses `async_openai::types::chat::` paths (the chat types moved out of the top-level `types::` module in 0.31). The 0.30.x line also pulled `backoff` transitively, which has been replaced with `tower` in 0.31+ — worth the version bump for the cleaner dependency tree alone.
 
 ## The basic pattern: with_cycles + chat completions
 
 ```rust
 use async_openai::{
     Client,
-    types::{CreateChatCompletionRequestArgs, ChatCompletionRequestUserMessageArgs, Role},
+    types::chat::{CreateChatCompletionRequestArgs, ChatCompletionRequestUserMessageArgs},
 };
 use runcycles::{
     CyclesClient, with_cycles, WithCyclesConfig,
@@ -153,7 +153,7 @@ OpenAI's streaming endpoint emits a final `usage` chunk only when `stream_option
 ```rust
 use async_openai::{
     Client,
-    types::{
+    types::chat::{
         CreateChatCompletionRequestArgs,
         ChatCompletionRequestUserMessageArgs,
         ChatCompletionStreamOptions,
@@ -254,7 +254,7 @@ For flows that need to act on the typed `OpenAIError`, use `ReservationGuard` an
 use async_openai::{
     Client,
     error::OpenAIError,
-    types::{CreateChatCompletionRequestArgs, ChatCompletionRequestUserMessageArgs},
+    types::chat::{CreateChatCompletionRequestArgs, ChatCompletionRequestUserMessageArgs},
 };
 use runcycles::{
     CyclesClient, Error as CyclesError,