AI-Powered Search

Search and answers work out of the box without any API key — the Ask CompassDocs page returns the best-matching document snippets using PostgreSQL full-text search.

To enable synthesized, cited answers (plus ✨ Write and ✨ Proofread), connect an AI provider under Settings → AI. Two choices:

• Anthropic (Claude) — the default: add an API key and pick a model.
• An OpenAI-compatible endpoint — bring your own /v1/chat/completions: OpenAI itself, an Azure gateway, or a fully local engine (Ollama, LM Studio, vLLM), so answers can be generated without anything leaving your network. See below.

Enable it — from the web UI (recommended)

On a fresh install, the setup wizard has an optional Anthropic API key field — paste it there and AI features work from the first login. Otherwise (or to change it later), go to Settings → AI, paste your key from console.anthropic.com, pick a model, and save. The key is validated on save and takes effect immediately — no restart. It’s stored securely and never shown again; you can remove it at any time.

Enable it — from the environment

Prefer configuration as code? Set it in your environment (.env, Docker .env, or your platform):

ANTHROPIC_API_KEY=sk-ant-...
# optional override:
# COMPASSDOCS_AI_MODEL=claude-opus-4-8

Restart the app to pick up the change. A key saved in Settings → AI takes precedence over this environment variable.

OpenAI-compatible & local models

From 0.62, the Provider choice on Settings → AI can point Ask, ✨ Write, and ✨ Proofread at any OpenAI-compatible chat endpoint instead of Anthropic:

1. Select OpenAI-compatible endpoint.
2. Enter the full endpoint URL — for example https://api.openai.com/v1/chat/completions (OpenAI) or http://localhost:11434/v1/chat/completions (Ollama on the same host).
3. Enter the model name (gpt-4o-mini, llama3.1, …) and, if the endpoint needs one, an API key — optional for local engines, and stored encrypted like every credential.
4. Save — the endpoint is tested with a tiny request first, so a wrong URL, bad key, or unknown model fails with a specific message instead of silently breaking answers later.

Fully local AI

Pair a local chat engine (Ollama, LM Studio, vLLM) with local embeddings and your knowledge base gets cited AI answers, writing assist, and semantic search with no external AI calls at all — a fit for air-gapped or strict-compliance environments.

Docker networking

If CompassDocs runs in Docker and the model server runs on the host, use http://host.docker.internal:11434/… (or your host’s LAN address) instead of localhost — inside the container, localhost is the container itself.

Semantic search

Beyond keywords, CompassDocs can search by meaning: “how do we handle refunds?” finds the reimbursement policy even when no word matches. Enable it under Settings → AI → Semantic search:

1. Have pgvector. The bundled docker-compose ships the pgvector/pgvector:pg16 PostgreSQL image from 0.49 (a drop-in superset of postgres:16 — existing volumes upgrade in place). For an external database, install the pgvector extension (postgresql-16-pgvector on Debian/Ubuntu).
2. Pick an embeddings provider. Voyage AI, OpenAI, or any OpenAI-compatible endpoint — including fully local engines: point the endpoint URL at Ollama (http://ollama:11434/v1/embeddings) or LM Studio and your document text never leaves your network. The API key is write-only and encrypted at rest; Test connection verifies the setup.
3. Rebuild the index once — a background job with live progress. After that, documents re-embed automatically as they’re created and edited.

Semantic results are fused with keyword results (reciprocal-rank fusion) in app search, in-space search, Ask answers, and the Claude connector; semantic-only hits carry a small related badge. Every permission is enforced on semantic hits exactly as on keyword hits — space visibility, private-space groups, and draft access. The public site stays keyword-only, so anonymous traffic never spends provider credits. If the provider is unreachable, searches silently fall back to keywords.

Changing the embedding model later just needs another rebuild.

How it works

The AI answer flow is a lightweight RAG (retrieval-augmented generation) pipeline:

1. Your question is used to retrieve the top-matching documents via Postgres full-text search — fused with semantic similarity when embeddings are configured.
2. Those excerpts are passed to Claude as grounded context.
3. The model is instructed to answer only from that context and cite its sources, which render as clickable links.

Any API error degrades gracefully back to the keyword-snippet fallback, so the page always returns something useful.

What the AI can and can’t see

• Drafts are excluded from answers shown to Viewers, just like in search and lists.
• Answers are grounded in your indexed documents only — the model isn’t asked to use outside knowledge, which keeps responses on-topic and reduces hallucination.

Cost control

Only the retrieved excerpts (not your whole knowledge base) are sent per question, so token usage scales with question volume, not corpus size. Choose a cheaper, faster model (e.g. Claude Haiku) from the model picker in Settings → AI if you prefer.

People questions

“Ask” also searches the people directory: “who”-style questions surface matching people with their title and contact details, linked to their profiles. With an AI key configured the model cites these as [Directory]; without one, the people appear as cards under the answer.