Restructure AI Transport docs around concepts#3343
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
@rainbowFi I've made extra changes:
This is ofc not the 'final destination' for these docs, but there is a LOT on the website that is currently just-plain-wrong. So I think this is a "if this PR is broadly fine, lets merge and iterate" kind of situation rather than expecting to 1-shot perfection (not that that's what you've been arguing for 🙇 ). 🙏 |
| @@ -0,0 +1,251 @@ | |||
| --- | |||
| title: "Get started with the Core SDK" | |||
There was a problem hiding this comment.
Based on the code, I think this is about using Vercel AI SDK Core to interact with the LLM but retaining complete control of the interface between agent and client. Can you please make that clear throughout the text, so people don't think Ably is providing a Core SDK? Also needs a new title that includes Vercel, without clashing with the other Vercel article in the nav....
There was a problem hiding this comment.
Zak and I chatted, he's going to work on naming this to avoid the confusion I fell into :D
zknill
force-pushed
the
zak/fix-ait-docs-concepts-getting-started
branch
from
e49e781 to
d8509a7
Compare
Replace the "How it works" section with a dedicated "Concepts" section containing five pages: Sessions, Messages and conversation tree, Turns, Transport, and Authentication. These pages explain AI Transport's conceptual model (sessions, the conversation tree, turn lifecycle, client/agent transports, and the codec) as logical entities rather than code walkthroughs. Merge the "Framework guides" section into "Getting started" so all Vercel AI SDK content lives on a single page. Add a new "Core SDK" getting started page for using AI Transport's generic React hooks without a framework wrapper. Strengthen the "Why" page with clearer durable session properties (resilient delivery, continuity across surfaces, live control) and update the overview page with a Core SDK tile. Update cross-references across all 16 feature pages to point to the new concepts paths. Add redirects from all old URLs.
Restore the Framework guides nav section with a comprehensive Vercel AI SDK guide that explains how the two SDKs integrate. The guide covers Vercel concepts (streamText, UIMessage, useChat, ChatTransport, tool calling), default transport limitations, what AI Transport adds (codec, useChatTransport, useMessageSync, server piping), how the layers fit together, integration paths, and what capabilities the combination unlocks. Replace the responsibilities table in the getting-started page with a link to the framework guide, and update cross-references between the two pages.
The React hooks changed from positional parameters to single
options objects. Update all docs to match:
- useView(transport, opts) -> useView({ transport, ...opts })
- useActiveTurns(transport) -> useActiveTurns({ transport })
- useClientTransport({ channel, codec }) ->
useClientTransport({ channelName }) with TransportProvider
- useTree(transport) -> useTree({ transport })
- useCreateView(transport) -> useCreateView({ transport })
- useAblyMessages(transport) -> useAblyMessages({ transport })
Update API reference signatures, options tables, and inline
examples. Add missing properties to ActiveTurn
(optimisticMsgIds), TurnLifecycleEvent (parent, forkOf),
and NewTurnOptions (signal). Fix ChatTransportOptions table
that was conflating two distinct types.
Reframe the Core SDK getting-started page so it does not read as a Vercel tutorial. Explain that streamText and UIMessageCodec are swappable: any model inference approach works with a matching codec. Use the core createServerTransport import with explicit codec to show where a custom codec plugs in. Move Core SDK above Vercel in the nav. Add Ably provider explainer.
zknill
force-pushed
the
zak/fix-ait-docs-concepts-getting-started
branch
from
d8509a7 to
ec91748
Compare
3 participants
Replace the "How it works" section with a dedicated "Concepts" section containing five pages: Sessions, Messages and conversation tree, Turns, Transport, and Authentication. These pages explain AI Transport's conceptual model (sessions, the conversation tree, turn lifecycle, client/agent transports, and the codec) as logical entities rather than code walkthroughs.
Merge the "Framework guides" section into "Getting started" so all Vercel AI SDK content lives on a single page. Add a new "Core SDK" getting started page for using AI Transport's generic React hooks without a framework wrapper.
Strengthen the "Why" page with clearer durable session properties (resilient delivery, continuity across surfaces, live control) and update the overview page with a Core SDK tile.
Update cross-references across all 16 feature pages to point to the new concepts paths. Add redirects from all old URLs.