Getting Started

astro-chatty-gpt

An Astro integration that adds AI-powered search and chat to your Astro site. It indexes your built HTML on every deploy, stores content in Upstash Search, and answers questions with OpenAI via the Vercel AI SDK.

Requirements

Requirement	Version
Astro	6.x (^6.0.0 peer dependency)
Node.js	22.15+
Output mode	server or hybrid (middleware + API routes)
Upstash Search	REST URL + token
OpenAI API key	Access to your chosen chat model

Features

• Semantic search — /api/search powered by Upstash Search with reranking
• RAG chatbot — /api/chatbot retrieves relevant pages, then generates answers with citations
• Model selection — GPT-5.4 family (default gpt-5.4-mini), plus GPT-5, GPT-4.1, and GPT-4o models
• Reasoning controls — reasoningEffort and textVerbosity for supported OpenAI models
• Streaming — real-time responses with DATA:-delimited stream protocol
• Multi-language — filter indexed content and chat by language
• Auto-indexing — crawls built HTML after astro build and upserts to Upstash
• Content filtering — exclude routes, CSS selectors, and cap indexed content length

API endpoints

The integration registers two middleware routes automatically:

Endpoint	Methods	Purpose
/api/search	GET, POST	Semantic search over indexed content (Upstash only)
/api/chatbot	POST	RAG chat with optional streaming (Upstash + OpenAI)

See API endpoint for request/response formats and client examples.

Quick start

1. Install the package and set environment variables
2. Configure model, indexing, and prompt options
3. Build your site — content is indexed on astro build
4. Call /api/chatbot from your UI, or use the demo widget for testing

Tech stack

This integration and the docs playground are built with:

Package	Role
Astro 6.3+	Framework + middleware
@astrojs/netlify 7.x	Server adapter (playground)
@astrojs/starlight 0.39+	Documentation site
Vercel AI SDK 6 (ai, @ai-sdk/openai 3.x)	Chat + streaming
Upstash Search	Vector / semantic index
Tailwind CSS 4.3	Playground styling

What’s new

Recent updates relevant to adopters:

• Astro 6 support — requires Astro ^6.0.0 and Node >=22.15.0
• AI SDK 6 — upgraded from AI SDK 5; same streamText API for chat
• GPT-5.4 models — gpt-5.4, gpt-5.4-mini (default), gpt-5.4-nano
• model option — choose the OpenAI model in astro.config
• reasoningEffort / textVerbosity — tune reasoning-capable models
• /api/search — dedicated search endpoint (GET ?q= or POST JSON)

License

MIT Licensed. Made with ❤️ by unfolding.

Acknowledgements

• Created using astro-integration-template
• Powered by Upstash Search
• AI capabilities via OpenAI and Vercel AI SDK
• Built with Astro
• Inspired by Firestarter