The @docmd/plugin-ai plugin introduces an interactive AI Assistant overlay to your documentation site. It leverages pre-compiled @docmd/plugin-search indices to perform Retrieval-Augmented Generation (RAG), querying targeted documentation sections to deliver contextual answers with direct source links.

Key Capabilities

• Floating Trigger & Glassmorphic Drawer: Clean pill trigger (⌘K shortcut) that expands into a theme-aware chat panel.
• Search-Aware RAG: Queries pre-built search-index.json data to ground LLM responses directly in your site’s documentation.
• BYOK Server Security: API keys are resolved exclusively in server-side environments (AI_API_KEY, OPENAI_API_KEY), guaranteeing zero credential exposure in client web bundles.
• Multi-Provider Integration: Powered by aiplug with native support for OpenAI, Anthropic, Gemini, DeepSeek, Groq, and local Ollama instances.
• Theme Neutrality: Adapts to light and dark theme modes across all built-in and custom templates.

Configuration Options

Configure assistant options and provider credentials in docmd.config.json:

{
  "plugins": {
    "ai": {
      "assistant": true,
      "provider": "openai",
      "model": "gpt-4o-mini",
      "position": "bottom-center",
      "greeting": "How can I help with these docs today?",
      "placeholder": "Ask AI a question...",
      "suggestions": [
        "How do I get started?",
        "Show configuration options",
        "Explain key concepts"
      ],
      "contextLimit": 5,
      "rateLimit": {
        "maxRequests": 10,
        "windowMs": 60000
      }
    }
  }
}

Options Reference

Server-Side Security (Bring-Your-Own-Key)

Set provider environment keys prior to launching your documentation server:

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."
# or generic fallback
export AI_API_KEY="your-api-key"

Architecture Execution Flow

1. Build-Time Action Registration: During site compilation, @docmd/plugin-ai registers server-side RPC action handlers (ai:chat) and injects a lightweight client trigger script.
2. Retrieval-Augmented Generation (RAG): When a reader submits a prompt:
   • The RPC endpoint queries the search index compiled by @docmd/plugin-search.
   • Matching document headings and prose chunks are selected based on vector/keyword distance.
   • Relevant snippets are compiled into a structured system prompt alongside user conversation history.
3. Provider Processing & Citations: The request is routed to the designated provider via aiplug. Output responses are returned with markdown links pointing to referenced documentation anchors.