AI Assistant

Built-in chat assistant that answers questions about your documentation.

Overview

The AI assistant adds a chat dialog to your documentation site. Users can click the sparkle icon in the header to open the dialog and ask questions about the documentation content.

The assistant uses the full documentation text (generated by the llms.txt integration) as context, so it can answer questions about any page on the site.

Enabling the Assistant

Set aiAssistant to true in zfb.config.ts:

export default defineConfig(
  zudoDoc({
    aiAssistant: true,
    // ...
  }),
);

When enabled:

• A sparkle icon appears in the header bar

• The POST /api/ai-chat endpoint becomes available as a Cloudflare Workers SSR route

Security Warning for Non-Demo Deployments

export default defineConfig(
  zudoDoc({
    aiChatDemoMode: false,
    // Allow only your deployed docs site to make cross-origin requests.
    aiChatAllowedOrigins: ["https://your-docs-site.example.com"],
    // Exact UTC-day paid-call admission cap (false = no exact cap).
    aiChatGlobalDailyLimit: 500,
    // ...
  }),
);

Environment Setup

In this showcase repository, the chat endpoint runs as a Cloudflare Workers SSR route (pages/api/ai-chat.tsx) and reads its configuration from Cloudflare env bindings set in wrangler.toml. Downstream implementations can use this graph as a reference, but these host-owned files are not package APIs.

Required CF bindings

Secret — set via wrangler secret put ANTHROPIC_API_KEY:

ANTHROPIC_API_KEY=sk-ant-...

Vars — configure in wrangler.toml:

[vars]
DOCS_SITE_URL = "https://your-docs-site.workers.dev"
RATE_LIMIT_PER_MINUTE = "10"
RATE_LIMIT_PER_DAY = "100"

KV namespace — soft per-IP rate limiting and privacy-safe outcome audit records (no prompt, response, IP, or IP hash fields):

wrangler kv namespace create RATE_LIMIT

Paste the returned id into the [[kv_namespaces]] block in wrangler.toml.

Durable Object namespace — exact UTC-day paid-call admission:

[[durable_objects.bindings]]
name = "AI_CHAT_DAILY_SPEND_CAP"
class_name = "AiChatDailySpendCap"

[[migrations]]
tag = "v1-ai-chat-daily-spend-cap"
new_sqlite_classes = ["AiChatDailySpendCap"]

Keep these names exact. The first wrangler deploy applies the Worker migration; this is not a wrangler d1 migrations operation. Production uses custom worker-entry.ts, which preserves the generated adapter handler from dist/_worker.js, its dist/_zfb_inner.mjs sidecar, and the exported Durable Object class. Always build before Wrangler.

Each UTC date routes to a new object, so the cap resets at 00:00 UTC. Admission occurs after request checks, the softer eventually-consistent per-IP KV guard, and docs-context preparation, immediately before exactly one Anthropic fetch. An admitted slot is not refunded if that fetch fails and is not provider-confirmed billing. aiChatGlobalDailyLimit: false skips only this exact cap; aiChatDemoMode: true skips KV, the Durable Object, and Anthropic entirely.

Preview aliases use an adapter-only service/config because versions implementing Durable Objects do not receive preview URLs. They prove the SSR adapter/assets path, not live paid-call admission; production wrangler deploy owns the migration. See Cloudflare's Durable Object migrations, the Cloudflare Wisdom Durable Objects article, and Workers Logs structured-object guidance.

Uses claude-haiku-4-5-20251001 for fast, low-cost responses.

Chat Dialog

The dialog is a package-owned Preact island (@takazudo/zudo-doc/ai-chat-modal) using the native <dialog> element. This showcase mounts it via pages/lib/_body-end-islands.tsx (the BodyEndIslands chrome-bindings slot).

Layout

• Narrow viewports (below lg/1024px): Full viewport width and height

• Wide viewports (1024px and above): Centered, 90vw/90vh with a max width of 52.5rem, with a border

Features

• Balloon-style message bubbles (user on right, assistant on left)

• Markdown rendering in assistant responses (bold, italic, code, lists, links)

• "Thinking..." indicator during API calls

• Error messages displayed inline

• Backdrop click or Escape to close

• Conversation resets on close

API Reference

For the full endpoint specification (request/response types, error codes, environment variables), see the AI Assistant API reference.

File Structure

pages/
└── api/
    ├── ai-chat.tsx               # CF Workers SSR endpoint (prerender = false)
    ├── _ai-chat-admission.ts     # Exact UTC-day paid-call admission cap
    ├── _ai-chat-audit.ts         # Privacy-safe outcome audit logging
    ├── _ai-chat-client.ts        # Claude API client (raw fetch)
    ├── _ai-chat-cors.ts          # CORS origin allowlist
    ├── _ai-chat-observability.ts # Structured operational logging
    ├── _ai-chat-payload.ts       # Request/response payload builders
    ├── _ai-chat-rate-limit.ts    # Per-IP KV rate limiting
    ├── _ai-chat-screening.ts     # Prompt-injection screening
    └── _ai-chat-types.ts         # Shared route types
src/
└── types/
    └── ai-chat.ts                # ChatMessage, AiChatRequest/Response types
worker-entry.ts                   # Production Worker entry (wraps dist/_worker.js)

The chat dialog island (@takazudo/zudo-doc/ai-chat-modal) and the chat-message markdown renderer (@takazudo/zudo-doc/render-markdown) are package-owned — not part of this repository's file tree.