Skip to main content

AI Services — post-enable runbook

AI Services was just turned on. The chatbot widget appears immediately, but answers are degraded until embeddings are generated and a working provider key is in place. The next half hour is about picking your provider, kicking off the first indexing run, and tuning what the chatbot is allowed to read.

For the surface-level overview, see the AI Services module reference.

Prerequisites​

Before AI Services is useful, confirm:

  • A platform-default AI provider is configured (your platform admin sets this), or you are bringing your own provider key for one of the supported providers: Anthropic Claude, OpenAI, or Google Gemini.
  • Storage is configured and verified for the org. Embeddings themselves live in the database, but the documents and photos the AI indexes live in storage.
  • Email delivery is configured at the platform level if you plan to use AI notification digests.
  • You know which content sources you want the chatbot to read — members, forums, compliance, documents, learning, etc. — and which to exclude.

Who can enable it​

Only a platform admin can toggle AI Services for your org. Org admins request the change through their platform admin.

What gets auto-created​

When AI Services is enabled, an AIConfig record is created for the org on first access. It defaults to use_platform_default = true, which means the org rides the platform's default provider and key. Until you change something, no per-org API key is required.

Embeddings are not generated automatically at enable time. They are produced the first time you trigger an indexing run or the next time the scheduled generate_all_embeddings task fires.

What appears in the sidebar​

There is no dedicated AI sidebar group. AI Services adds:

  • The AI Assistant card inside Org → Settings → Admin Management for configuration
  • The floating chatbot widget at the bottom-right of every page

First 30 minutes — required steps​

  1. Open Org → Settings → Admin Management and scroll to the AI Assistant card. Confirm the panel renders. If it shows "the Chatbot module is not enabled," ask your platform admin to verify the toggle.
  2. Decide whether to ride the platform default or bring your own key. If you use your own key, switch off Use platform default, pick a provider, paste the key, choose a model, and click Test. The test request hits the provider and returns a success or failure message.
  3. Turn the Active toggle on. The chatbot will not respond until the config is active.
  4. Review the content-source toggles (members, forum posts, compliance, documents). Turn off any source you do not want the chatbot to read. The default is everything on.
  5. Click Trigger embeddings to start the first indexing run. The embedding job appears below with a status of pending → running → completed. Without this run, the chatbot falls back to keyword search and gives much worse answers.

First 30 minutes — recommended next steps​

  • Wait for the first embedding job to finish before promoting the chatbot to members. Quality goes up dramatically once the index is built.
  • Try a few real-world questions yourself: "How much do I owe?" "When does the election close?" "Where is the bylaws document?" Confirm the chatbot pulls from the right scope.
  • If your provider supports embeddings (OpenAI and Google do; Anthropic does not), the embedding provider is auto-detected. Anthropic-only setups fall back to keyword and trigram search — set expectations with members accordingly.
  • Decide your logging policy. The chatbot logs conversations by default for quality. Org admins can disable per-org if your members would object.

What happens if you disable​

Turning AI Services off hides the chatbot widget and returns 403 on AI endpoints. Data is preserved — the AIConfig record, embeddings, content embeddings, and embedding job history all stay in the database. Re-enabling restores access.

Scheduled embedding regeneration stops while AI Services is off. When re-enabled, the index may be stale until the next regeneration runs.

Common gotchas​

  • An unverified or missing key produces no chatbot answers, not an obvious error. If the widget greets a member and then stalls, check the AI Assistant card for a working test result.
  • Anthropic does not support embeddings. Choosing Anthropic as both the chat and embedding provider falls back to keyword search — quality suffers. Pair Anthropic chat with a different embedding provider, or pick OpenAI / Google for both.
  • Embeddings go stale when you switch providers. The AIConfig flags embeddings_stale when the chat provider and embedding provider drift apart. Re-run the embedding job after a provider change.
  • Per-user scoping is honored. A chapter member cannot ask "show me national admin emails" and get them. If they can, your access scopes elsewhere on the platform are wrong, not the AI.
  • Hallucination is real. Verify any financial, legal, or member-PII answer the chatbot gives before acting on it.

Where to go deeper​

Last verified against v0.62.1 (2026-05-10).