docs: replace asyncio.create_task pattern with ctx.run() in all examples

[shloimy-wiesel]

Replace the three locations that still showed the old asyncio.create_task + try/finally pattern with the recommended ctx.run() approach: the init module docstring quickstart, the context.py module docstring FastAPI example, and the live example/backend/routes/chat.py endpoint.

The example backend also drops the _background_tasks GC-protection set and the asyncio import, which ctx.run() makes unnecessary.

Closes #58

Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ai-sdk-stream-python	Ready	Preview, Comment, Open in v0	May 30, 2026 7:31pm

[shloimy-wiesel]

@claude code review this pr

[claude]

Claude finished @shloimy-wiesel's task in 1m 38s —— View job

---

Code Review

• Gather context and read changed files
• Review src/ai_sdk_stream_python/__init__.py
• Review src/ai_sdk_stream_python/context.py
• Review example/backend/routes/chat.py
• Post final review

---

Overall this is a clean, correct docs-and-example migration. The three changed files are consistent with each other and with how ctx.run() is implemented in context.py. No old asyncio.create_task / _background_tasks references remain in the codebase.

Findings

example/backend/routes/chat.py — Minor concern

await ctx.run(lambda c: llm_service.chat(messages, ctx=c))

This is functionally correct — the lambda returns a coroutine which ctx.run() awaits in _safe(). However, it is stylistically inconsistent with the named async def _work(c: StreamContext) -> None pattern shown in both docstring examples that this very PR updates. The lambda form is slightly harder to read, and Pyright will also infer a weaker type ((...) -> Coroutine[...] rather than the explicit Callable[[StreamContext], Awaitable[None]]).

A named function (matching the docstring pattern) would be more consistent:

async def _work(c: StreamContext) -> None:
    messages = [m.model_dump() for m in request.messages]
    await llm_service.chat(messages, ctx=c)

await ctx.run(_work)

This also lets you move the messages computation inside _work, which is a natural fit. Fix this →

src/ai_sdk_stream_python/context.py — Left-over prose (pre-existing, out of scope)

The StreamContext class docstring (line 117) still reads:

"spin up a background task that writes events through the helpers"

It doesn't mention ctx.run(). This is a pre-existing issue not introduced by this PR, but since this PR is specifically about surfacing ctx.run() in documentation, it would be a natural place to add a one-liner like "Use ctx.run() to schedule the background task." Not a blocker.

Everything else — looks good

• Removing import asyncio and _background_tasks from chat.py is correct; ctx.run() internalises both the task creation and GC anchoring.
• The __init__.py quickstart now shows the type-annotated _work(c: StreamContext) -> None signature — good for discoverability.
• The context.py module docstring example correctly uses c as the parameter name throughout (no variable shadowing with the outer ctx).
• ctx.run() is well-tested (8 test cases in tests/test_context.py:922), so no test additions are needed for this docs-only change.
• await ctx.run(...) discards the returned asyncio.Task. That's intentional by design — the task is GC-anchored on self._task inside run() — but worth knowing if a reviewer asks why the return value isn't captured.

Summary

One minor style inconsistency (lambda vs. named function in chat.py) worth addressing; everything else is correct and clean. ✓

[shloimy-wiesel]

@claude fix the findings from the pr comment

[claude]

Claude finished @shloimy-wiesel's task in 1m 6s —— View job

---

Fixed PR Review Findings

• Read current state of changed files
• Fix lambda → named async def _work in example/backend/routes/chat.py
• Update StreamContext class docstring in context.py to mention ctx.run()
• Verify diff (lint tools unavailable in this environment — no formatting changes needed)
• Commit and push changes

Changes Made

example/backend/routes/chat.py — Replaced the lambda with a named async def _work(c: StreamContext) -> None function, moving the messages computation inside it. This matches the pattern shown in both docstring examples updated by this PR and gives Pyright a stronger type.

src/ai_sdk_stream_python/context.py — Updated the StreamContext class docstring from:

"spin up a background task that writes events through the helpers"

to:

"use ctx.run() to schedule the background work"
| Branch