docs: Update bot streaming docs for new simplified BotConfig API (PR #1921 - Progressive Streaming)

[MervinPraison]

Context

PR MervinPraison/PraisonAI#1921 was merged on 2026-06-18 (fixes #1912). It implements progressive streaming for channel bots (Telegram first, extensible to Discord, Slack, WhatsApp, Email, AgentMail) by bridging core StreamEventEmitter events to platform edit_message() APIs.

Instead of users staring at typing indicators for 30+ seconds, they now see tokens appearing live as the agent generates them via progressive message editing (default 700ms interval).

Change summary (from PR)

• BotConfig (in src/praisonai-agents/praisonaiagents/bots/config.py) gained two new public fields:
  • streaming: bool = False
  • stream_edit_interval_ms: int = 700
• CLI (praisonai bot telegram in src/praisonai/praisonai/cli/commands/bot.py) gained two new flags:
  • --stream (boolean — enable progressive streaming)
  • --stream-edit-interval (int, default 700 — ms between edits)
• YAML config now supports:
  • streaming: true
  • stream_edit_interval_ms: 700
• Telegram adapter (praisonai/bots/telegram.py) wired up to:
  • Send a placeholder message → progressively edit it as tokens stream in
  • Handle hook cancellation, agent errors, and MEDIA: markers gracefully (clean up placeholder on failure)
• Backward compatible: off by default, opt-in via config. Zero performance impact when disabled.

Note: Internally, when BotConfig.streaming=True, the Telegram adapter constructs a StreamingConfig(mode=StreamingMode.DRAFT, min_interval=stream_edit_interval_ms/1000.0, min_delta=50). The new fields are a simpler beginner-friendly wrapper over the existing StreamingConfig/StreamingMode API.

---

Decision: UPDATE existing docs (primary) — no new page needed

The repo already has a streaming-replies page at docs/features/bot-streaming-replies.mdx, but it only documents the older lower-level API (StreamingConfig, StreamingMode.DRAFT, configure_streaming(), bot.yaml with streaming: {mode: draft, min_interval: 1.5, ...}). It is missing:

1. The new simple boolean API: BotConfig(streaming=True, stream_edit_interval_ms=700)
2. The new CLI flags: --stream and --stream-edit-interval
3. The new simplified YAML: streaming: true + stream_edit_interval_ms: 700 (top-level on the channel block — not the nested object form)

Per AGENTS.md, docs should be agent-centric, beginner-friendly, with progressive disclosure — the simple boolean form must appear first, with the advanced StreamingConfig form available for power users.

The CLI reference page at docs/cli/bot.mdx is also missing the two new flags.

The features overview page docs/features/messaging-bots.mdx does not currently mention streaming at all.

---

Files to update

1. docs/features/bot-streaming-replies.mdx — UPDATE (primary)

Restructure so the simple new API is the lead example, and the old StreamingConfig/StreamingMode API is a secondary "Advanced configuration" section.

Quick Start should become:

Suggested replacement Quick Start (click to expand)

## Quick Start

<Steps>
<Step title="Enable with one flag (CLI)">

```bash
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --stream
```

</Step>

<Step title="Enable in YAML">

```yaml
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    streaming: true
    stream_edit_interval_ms: 700
```

</Step>

<Step title="Enable in Python">

```python
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
from praisonaiagents.bots import BotConfig

agent = Agent(name="assistant", instructions="Be helpful and concise.")

bot = TelegramBot(
    token="...",
    agent=agent,
    config=BotConfig(
        token="...",
        streaming=True,                  # progressive edits enabled
        stream_edit_interval_ms=700,     # edit every 700ms
    ),
)
bot.start()
```

</Step>
</Steps>

New "Configuration Options" table (top-level simple form):

Option	Type	Default	Description
streaming	bool	False	Enable progressive streaming — bot sends a placeholder then edits it live as the agent produces tokens
stream_edit_interval_ms	int	700	Minimum milliseconds between message edits (respects platform rate limits)

Keep the existing "Streaming Modes" + StreamingConfig table as a section titled "Advanced configuration (StreamingConfig)" — it remains the way to access progress mode, custom placeholder_text, progress_prefix, and custom min_delta.

Update the <Note> callout to clarify platform support:

Streaming replies are currently wired up for Telegram. The simple streaming: true / --stream form enables draft mode automatically. Other platforms (Discord, Slack, WhatsApp, Email, AgentMail) will fall back to the existing blocking mode until their adapters are extended.

Mermaid (existing hero diagram is fine — keep it). Optionally add a small "Choose your API" decision diagram:

graph TB
    A{How much control<br/>do you need?} --> B[Just enable it]
    A --> C[Tune the speed]
    A --> D[Custom placeholder<br/>or progress mode]

    B --> E["streaming: true<br/>(or --stream)"]
    C --> F["streaming: true<br/>stream_edit_interval_ms: 1000"]
    D --> G[StreamingConfig with<br/>mode=PROGRESS, ...]

    classDef simple fill:#10B981,stroke:#7C90A0,color:#fff
    classDef advanced fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef question fill:#189AB4,stroke:#7C90A0,color:#fff

    class A,B,C,D question
    class E,F simple
    class G advanced

Best Practices — add one accordion:

<Accordion title="Start with `--stream` — tune `stream_edit_interval_ms` only if needed">
The default `700ms` interval works well on Telegram. If you hit "message is not modified" or 429 errors on a shared/busy channel, raise it to `1000`–`2000`. On Discord (stricter limits), prefer `2000` or use the advanced `StreamingConfig` form.
</Accordion>

---

2. docs/cli/bot.mdx — UPDATE

Add a new sub-section under "Capability Options" (or extend the existing audio table area):

### Streaming (progressive replies)

| Option | Description |
|--------|-------------|
| `--stream` | Enable progressive streaming responses (bot edits the message live as tokens arrive) |
| `--stream-edit-interval MS` | Minimum interval between edits in milliseconds (default: `700`) |

Add a new example under "Examples":

### With Live Streaming Replies

```bash
# Default streaming (edits every 700ms)
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --stream

# Slower edits for stricter rate limits
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN \
  --stream \
  --stream-edit-interval 1500
```

<Tip>
Streaming is currently wired up for Telegram. Other channels fall back to single-message mode until their adapters add streaming support.
</Tip>

Update "Related" card to also point to /features/bot-streaming-replies.

---

3. docs/features/messaging-bots.mdx — MINOR UPDATE

Add one bullet or row under the channel capabilities list / feature highlights mentioning that Telegram supports Live Streaming Replies (link to /features/bot-streaming-replies). Do not duplicate the streaming page content — just surface its existence so beginners discover it from the main bots page.

---

SDK source of truth (verified against PR diff)

• src/praisonai-agents/praisonaiagents/bots/config.py — BotConfig dataclass, fields added at lines ~114–117:

  # Progressive streaming for channel bots (default: False)
  streaming: bool = False
  
  # Edit interval for streaming responses in milliseconds (default: 700ms)
  stream_edit_interval_ms: int = 700

  Also included in to_dict() output.
• src/praisonai/praisonai/cli/commands/bot.py (function bot_telegram) — new typer options:

  stream: bool = typer.Option(False, "--stream", help="Enable progressive streaming responses (edit messages live)"),
  stream_edit_interval: int = typer.Option(700, "--stream-edit-interval", help="Minimum interval between message edits in milliseconds"),

• src/praisonai/praisonai/cli/features/bots_cli.py — BotCapabilities extended with stream + stream_edit_interval; YAML maps streaming → stream and stream_edit_interval_ms → stream_edit_interval.
• src/praisonai/praisonai/bots/telegram.py — when config.streaming is true, constructs internal StreamingConfig(mode=StreamingMode.DRAFT, min_interval=stream_edit_interval_ms/1000.0, min_delta=50). Adds placeholder cleanup on error / hook-cancel and MEDIA: marker handling.

---

Folder placement (per AGENTS.md §1.8)

• All updates go in docs/features/ and docs/cli/. No docs/concepts/ changes.
• No new pages required — the dedicated page already exists at docs/features/bot-streaming-replies.mdx.
• No docs.json sidebar changes required (page is already listed).

---

Style requirements (per AGENTS.md)

• Lead with the agent-centric simplest example (streaming=True / --stream) — beginners should feel "is it really this easy?"
• One-sentence section intros, no forbidden phrases ("In this section…", "Please note…").
• Use Mintlify <Steps>, <AccordionGroup>, <CardGroup>, <Tabs> components.
• Use the standard Mermaid color scheme (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1, white text, #7C90A0 strokes).
• Keep all existing imports/examples runnable (no placeholder values like your-key-here).

---

Acceptance criteria

• docs/features/bot-streaming-replies.mdx leads with the simple BotConfig(streaming=True, stream_edit_interval_ms=700) API and the --stream / streaming: true YAML form
• The existing StreamingConfig / StreamingMode content is preserved under an "Advanced configuration" section (do not delete — it still works and exposes progress mode + placeholder_text + custom min_delta)
• Configuration Options table documents streaming and stream_edit_interval_ms with exact types and defaults from the SDK
• docs/cli/bot.mdx includes the --stream and --stream-edit-interval flags and at least one example
• docs/features/messaging-bots.mdx links to the streaming-replies page from its features list
• All Mermaid diagrams use the standard color scheme and white text
• No edits to docs/concepts/
• docs.json remains valid JSON (no structural changes expected)

---

Source: PR MervinPraison/PraisonAI#1921, merged 2026-06-18 by @MervinPraison, head SHA 2f316f4.

[MervinPraison]

🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...

Claude will:

1. Classify this issue
2. Search codebase for root cause
3. Implement a minimal fix following AGENTS.md
4. Create a PR with the changes

[MervinPraison]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.