Use @polpo-ai/react for runtime state and hooks. Use @polpo-ai/chat for composable UI.
Keep application routing and business-side client tool execution in the consuming app.
Install
npm install @polpo-ai/chat @polpo-ai/sdk @polpo-ai/react \
react-virtuoso lucide-react streamdown
Or add source components with npx @polpo-ai/ui add. For a new application use
npx create-polpo-app.
Provider
import { PolpoProvider } from "@polpo-ai/react";
baseUrl is the project root; do not append /v1 or /api/v1. Do not expose privileged
server API keys in browser bundles. Use the application's authenticated backend/proxy when
credentials must remain server-side.
Chat Choice
Use the high-level component for ordinary chat:
<Chat agent="support" sessionId={sessionId} />
Use useChat directly when the product needs durable delivery, custom interactions, explicit
client tools, Loop continuation, or its own message composition.
UI Invariants
- Treat Session history from Polpo as canonical; do not duplicate optimistic messages after reconnect or client-tool continuation.
- Show
reconnectingseparately fromstreamingand do not mark detached durable runs failed. - Render a client tool only after validating its name and arguments against the local handler.
- Continue tool results with a stable idempotency key and current Session version.
- Suggestions belong to the assistant message that produced them and are actionable only while it remains the latest message.
- Attachments use typed content parts and authenticated file URL resolution; never place local filesystem paths in browser-visible messages.
References
- references/runtime-chat.md: modern
useChat, durability, interactions, skills, and continuation. - references/components.md: component props.
- references/patterns.md: current composition patterns.
- references/cli.md: UI scaffolding commands.
- references/theming.md: tokens, dark mode, fonts, and Tailwind.
- references/contract-version.md: verified package versions.