apiVersion: capsule.dev/v0.1
kind: Capsule
name: f4c-bot-service
version: 0.1.0
type: subsystem
purpose:
summary: 'Manages per-room AI chat sessions, including message history persistence
and hourly rate limiting, using Cloudflare Durable Objects and Cloudflare AI Gateway.
It provides an API endpoint for external services to interact with the bot.
'
owns:
- AI chat bot logic and persona ('Luna')
- Message history storage and management within Durable Objects
- Hourly rate limiting for AI interactions
- API endpoint for proxying messages to the bot Durable Object
does_not_own:
- Frontend UI for chat messages
- General room management or participant authentication
- Real-time communication infrastructure
interfaces:
provides:
- kind: http_api
name: /api/bot
description: API endpoint for sending user messages to the AI bot and receiving
replies.
- kind: event
name: DurableObject:BotSession
description: Cloudflare Durable Object for stateful AI bot sessions.
requires:
- kind: env
name: CF_AIG_TOKEN
description: Authentication token for Cloudflare AI Gateway.
- kind: env
name: CF_AI_GATEWAY_BASEURL
description: Base URL for the Cloudflare AI Gateway (OpenAI-compatible endpoint).
- kind: env
name: ROOMS_KV
description: Cloudflare KV Namespace for rate limiting and checking room existence/bot
enablement.
- kind: env
name: BOT_SESSION
description: Durable Object Namespace binding for BotSession.
dependencies:
capsules:
- name: f4c-room-api
version: '>=0.1.0'
agent:
summary_for_ai: 'This capsule implements the AI bot''s core logic and API. Agents
should focus on improving bot responses, managing AI model integration, or refining
rate limiting. Pay attention to the `BOT_SYSTEM_PROMPT` and `BOT_MODEL` for AI
behavior.
'
avoid:
- Introducing direct UI components or client-side logic.
- Changing the core Durable Object state management without careful consideration
of data migration.
verification:
invariants:
- The bot must maintain per-room message history up to `MAX_HISTORY`.
- The bot must adhere to `HOURLY_RATE_LIMIT` per room.
- The `/api/bot` endpoint must correctly route requests to the appropriate `BotSession`
Durable Object.
x-reuse:
notes: 'app/src/do/BotSession.ts: `BOT_SYSTEM_PROMPT` defines the bot''s persona
(''Luna'') and can be customized. `BOT_MODEL` is hardcoded to `workers-ai/@cf/zai-org/glm-4.7-flash`.
`MAX_HISTORY` and `HOURLY_RATE_LIMIT` are hardcoded. app/src/pages/api/bot.ts:
`ALLOWED_ORIGINS` is hardcoded. `RATE_LIMIT_WINDOW_S`, `RATE_LIMIT_MAX`, `MAX_MESSAGE_LENGTH`
are hardcoded. Relies on `ROOMS_KV` for IP rate limiting and checking `botEnabled`
status from room records.
'
x-reconstruct:
install: install.json