Docs: clarify ChatObject suspend usage and callback/iterator modes

[JohnRichard4096]

Summary by Sourcery

Clarify and update documentation for the ChatObject suspend/resume mechanism and usage patterns in both English and Chinese guides.

Documentation:

• Document the mutual exclusivity between callback mode and async iterator consumption for ChatObject response streams, including associated RuntimeError behavior.
• Update examples and usage patterns to require explicit chat.begin() before using context managers or awaiting ChatObject, distinguishing iterator and callback modes.
• Refine wording, headings, and analogies in suspend/resume documentation to better explain outer vs inner suspension, tag-based breakpoints, and recommended usage scenarios in both English and Chinese.

[sourcery-ai]

Reviewer's Guide

Refines the English and Chinese suspend/resume concept docs to clarify lifecycle usage, explicitly document callback vs iterator exclusivity, and update code examples and wording to match the current ChatObject task management API and recommended patterns.

Sequence diagram for iterator mode with outer suspend control

sequenceDiagram
    actor UserController
    participant ControllerTask
    participant ChatObject
    participant InternalTask
    participant LLM

    UserController->>ChatObject: configure_agent()
    UserController->>ChatObject: begin()
    activate ChatObject
    ChatObject->>InternalTask: create_and_start()
    activate InternalTask

    par Control_flow
        UserController->>ControllerTask: asyncio.create_task(controller)
        activate ControllerTask
        ControllerTask->>ChatObject: wait_to_suspend(tag, timeout)
    and Business_flow
        loop lifecycle
            InternalTask->>InternalTask: call_suspend_decorated_method()
            InternalTask->>ChatObject: check_suspend_signal()
            alt suspend_requested_for_tag
                InternalTask-->>ChatObject: set_suspended_state
                InternalTask-->>InternalTask: pause_at_wait_for_continue
            else no_suspend
                InternalTask->>LLM: request_completion()
                LLM-->>InternalTask: stream_chunks()
                InternalTask-->>ChatObject: queue_chunks_for_iterator
            end
        end
    end

    ControllerTask-->>ChatObject: detects_suspended
    ControllerTask-->>ControllerTask: custom_logic_inspect_modify_state
    ControllerTask->>ChatObject: resume()
    ChatObject-->>InternalTask: wake_up_from_wait_for_continue

    UserController->>ChatObject: async with chat
    loop streaming
        ChatObject->>UserController: async for chunk in get_response_generator()
    end

    InternalTask-->>ChatObject: finished
    deactivate InternalTask
    ChatObject-->>UserController: __aexit__()
    deactivate ChatObject

Loading

Class diagram for ChatObject suspend and lifecycle APIs

classDiagram
    class SuspendObjectStream {
        <<abstract>>
        +suspend(func) async
        +suspend_with_tag(tag, func) async
        +wait_to_suspend(tag, timeout) async
        +resume() void
        +_wait_for_continue(tag) async
    }

    class ChatObject {
        +begin() void
        +set_callback_func(callback) void
        +get_response_generator() async
        +full_response() async
        +__await__() async
        +__aenter__() async
        +__aexit__(exc_type, exc, tb) async
        -_entry() async
        -_run() async
        -_run_strategy() async
    }

    SuspendObjectStream <|-- ChatObject
    SuspendObjectStream ..> ChatObject : manages_suspend_points

Loading

File-Level Changes

Change	Details	Files
Clarify suspend/resume lifecycle and correct ChatObject task management patterns in English suspend concept doc.	Update terminology and phrasing for readability (e.g., headings, bullet labels, and analogy descriptions). Document that callback-based handling and async iterator consumption are mutually exclusive and that using both causes a RuntimeError. Adjust lifecycle explanations and examples to require explicit chat.begin() before using wait_to_suspend, async with chat, or awaiting chat. Revise code examples to separate iterator mode and callback mode, showing proper use of chat.begin(), async with chat:, await chat, and controller tasks. Refine explanations of outer vs inner suspend mechanisms and how they combine under different consumption modes.	docs/guide/concepts/suspend.md
Align Chinese suspend concept doc with updated lifecycle, mutual exclusivity, and usage pattern guidance.	Add explicit warning that callback and async iterator consumption are mutually exclusive for a ChatObject instance. Update workflow description to include the need for chat.begin() before waiting for suspend and resuming. Fix examples to call chat.begin() and then use async with chat: for iterator mode, and chat.begin() + await chat for callback mode. Clarify combined usage of inner and outer interruption mechanisms with separate examples for callback mode and iterator mode. Add lifecycle management notes and updated “when not to use” examples consistent with the English documentation.	docs/zh/guide/concepts/suspend.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[JohnRichard4096]

@sourcery-ai title

[sourcery-ai]

Hey - I've left some high level feedback:

• In the iterator‑mode controller examples you still use the blocking input() call directly inside async functions (e.g., input("Press Enter to continue...")); for consistency with other snippets and to avoid confusing users about blocking the event loop, consider wrapping these in await asyncio.to_thread(input, ...) as you did in the callback‑mode examples.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In the iterator‑mode controller examples you still use the blocking `input()` call directly inside async functions (e.g., `input("Press Enter to continue...")`); for consistency with other snippets and to avoid confusing users about blocking the event loop, consider wrapping these in `await asyncio.to_thread(input, ...)` as you did in the callback‑mode examples.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[cloudflare-workers-and-pages]

Deploying amritacore with    Cloudflare Pages

Latest commit:	ece04f9
Status:	✅  Deploy successful!
Preview URL:	https://179e8c4f.amritacore.pages.dev
Branch Preview URL:	https://johnrichard4096-patch-1.amritacore.pages.dev

View logs