2026/02/12
Think-AI Integration Guide for AI

This document defines host-side AI integration for apps/host, including editor UI, API contracts, provider routing, and usage billing.

1. Scope

Target surfaces:

  1. Editor page:
    • apps/host/src/app/editor/[[...postsId]]/page.tsx
    • apps/host/src/components/demo/EditorComponent.tsx
  2. Next server routes under:
    • apps/host/src/app/api/ai/*
    • apps/host/src/app/api/storage/presign-put/route.ts
  3. Client API helper:
    • apps/host/src/utils/ghostApiClient.ts

2. Editor UI Contract

EditorComponent provides:

  1. AI icon button in the editor toolbar, placed next to Post Setting icon button.
  2. AI drawer on right side (persistent), same mobile behavior as Post Setting drawer.
  3. Mobile width is full-screen:
    • width: { xs: "100vw", sm: 420 }
  4. Chat panel includes:
    • LLM provider pulldown
    • model pulldown
    • history toggle icon in header
    • new chat icon near input area
    • chat input box with send icon
    • Current Chat section
    • optional Chat History section inside same panel
    • copy icon on each message and history row

Behavior:

  1. Click AI icon: open/close AI drawer.
  2. Click history icon: toggle history list area.
  3. Click new chat icon: clear current message thread.
  4. Enter/Send: append user message and assistant placeholder.

3. API Contract Rules

All AI/storage routes require:

  1. Header x-group-id
  2. Body group_id matching header
  3. Optional x-request-id (server generates if omitted)

Provider selection fields:

  1. provider: chatgpt | gemini | deepseek | glm
  2. model: optional provider model id

Server validates provider allowlist and resolves default model if missing.

4. Route Inventory

Implemented scaffold routes:

  1. POST /api/ai/chat
  2. GET /api/ai/chat/history
  3. GET /api/ai/usage
  4. POST /api/ai/editor
  5. POST /api/ai/tts
  6. POST /api/ai/stt
  7. POST /api/ai/realtime/session
  8. POST /api/storage/presign-put

Shared helpers and types:

  1. apps/host/src/app/api/ai/_shared.ts
  2. apps/host/src/types/ai.ts

5. Group/User Billing Contract

Billing and observability policy:

  1. Billing unit: group_id
  2. Usage actor and audit: user_id
  3. Every request logs tokens/units + USD cost

Standard response usage shape:

  1. usage: token/audio units
  2. cost: { currency: "USD", amount_usd: number }

6. Persistence Design

AI SDK does not persist chat history in production by default. Persist server-side via Ghost custom API + DB.

Recommended tables:

  1. ai_conversations
  2. ai_messages
  3. ai_usage_ledger

Recommended keys:

  1. Private chat id: g:{group_id}:u:{user_id}:c:{uuid}
  2. Group shared chat id: g:{group_id}:c:{uuid}

7. S3 and CloudFront

Voice and upload contract:

  1. Browser upload: presigned PUT URL from /api/storage/presign-put
  2. S3 key example:
    • groups/{group_id}/posts/{post_id}/voice/{lang}/{uuid}.{ext}
  3. Delivery URL:
    • CloudFront URL derived from key and returned by server

8. Backend Integration TODO Boundary

Scaffold routes intentionally leave provider/DB integrations in TODO(...) blocks.

Implement in backend phase:

  1. Session and group permission checks
  2. Provider SDK/HTTP calls
  3. Token/cost computation
  4. Quota enforcement
  5. Ledger persistence
  6. Conversation/message persistence

9. Install and Environment

Install (from repo root):

yarn workspace @ghost-next/frontend add ai @ai-sdk/openai
yarn workspace @ghost-next/frontend add @ai-sdk/google @ai-sdk/anthropic
yarn workspace @ghost-next/frontend add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Suggested env vars:

  1. OPENAI_API_KEY
  2. GOOGLE_GENERATIVE_AI_API_KEY
  3. CLOUDFRONT_URL
  4. AWS_REGION
  5. AWS_S3_BUCKET
  6. AWS_ACCESS_KEY_ID
  7. AWS_SECRET_ACCESS_KEY
  8. AI_DEFAULT_MODEL
  9. AI_GROUP_BUDGET_USD_MONTHLY

10. Validation

yarn workspace @ghost-next/frontend exec tsc --noEmit --pretty false
yarn workspace @ghost-next/frontend build

11. References (AI)

AI SDK core and Next.js integration:

  1. https://ai-sdk.dev/docs/introduction
  2. https://ai-sdk.dev/docs/getting-started/nextjs-app-router
  3. https://ai-sdk.dev/providers/ai-sdk-providers/openai
  4. https://ai-sdk.dev/docs/agents/overview

AI SDK chat UI and transport:

  1. https://ai-sdk.dev/docs/api-reference/use-chat
  2. https://ai-sdk.dev/docs/ai-sdk-ui/transport
  3. https://ai-sdk.dev/elements/components/conversation
  4. https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-message-persistence
  5. https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-resume-streams
  6. https://openchat.ai-sdk.dev/

Audio and realtime:

  1. https://platform.openai.com/docs/guides/audio
  2. https://platform.openai.com/docs/guides/realtime/voice-design
  3. https://platform.openai.com/docs/guides/realtime-transcription

S3 signed upload:

  1. https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html