wikis / gbrain / wiki / entities / ai-provider-integrations.md view as markdown report a mistake

AI Provider Integrations

type: entityconfidence: highupdated: 2026-07-02gbrain_version: 0.42.56.0sources: 7

Overview

GBrain is a retrieval runtime, not a model vendor: it plugs into a wide set of external AI, credential, and webhook providers through a recipe abstraction, so the same core (chunking, embedding, search, sync) can run against very different vendor stacks. This page catalogs the provider-facing integration surface: embedding providers, the reranker stack (ZeroEntropy hosted + llama-server local), the credential gateway that mediates access to Gmail/Calendar/messaging, meeting/call webhook sources, and the write-time reliability hooks (pre-commit, JSONB repair) that keep provider-fed data honest.

Characteristics

Embedding providers (16 recipes). gbrain providers list shows the live registry; gbrain providers explain --json gives agents a machine-readable capability matrix. Coverage: openai (default, 1536d, $0.13/1M), zeroentropyai (zembed-1, Matryoshka to 2560/1280/640/320/160/80/40, $0.05/1M), voyage (voyage-4 family, 256-2048d, best quality/$, code-tuned voyage-code-3), openrouter (single key fan-out to dozens of hosted models, embedding + chat), google (gemini-embedding-001, 768d default), azure-openai, minimax, dashscope, zhipu, ollama (local, free), llama-server (local, free, user-set dims), litellm (universal proxy escape hatch), together. anthropic/deepseek/groq are chat-only (no embedding model). As of v0.37, gbrain init --pglite auto-detects the provider from whichever API key env var is set; an interactive picker fires if multiple keys are present, and a non-TTY context with no keys exits 1 with a paste-ready hint.

Reranking. ZeroEntropy's zerank-2 cross-encoder is the hosted default reranker in tokenmax search mode ($0.025/1M tokens, $0.0003/query at 30 candidates), opt-in on conservative/balanced via gbrain config set search.reranker.enabled true. llama-server-reranker (added v0.40.6.1) is the local/free alternative: point gbrain at a self-hosted llama-server --reranking instance running Qwen3-Reranker (0.6B/4B/8B) or a self-hosted GGUF conversion of ZE's zerank-2/zerank-1-small weights. Both speak the same {results: [{index, relevance_score}]} wire shape gbrain's gateway.rerank() already drives — the recipe is a base-URL override, and any other provider matching that wire shape (not Voyage, which uses top_k/data[]) can reuse it. Reranking is fail-open by construction across all providers: any error class (auth, network, timeout, payload-too-large) logs to `/.gbrain/audit/rerank-failures-*.jsonl` and falls back to unmodified RRF order — search reliability beats reranker quality.

Credential gateway. The agent never holds raw API keys. ClawVisor (OpenClaw) is a credential-vaulting/authorization gateway with task-scoped authorization: every request needs a task_id from an approved standing task declaring purpose, authorized actions, auto-execute flag, and lifetime. Services: Gmail, Google Calendar, Google Drive, Google Contacts, Apple iMessage, GitHub, Slack. Setup: create an agent in the ClawVisor dashboard, set CLAWVISOR_URL/CLAWVISOR_AGENT_TOKEN, activate services, create standing tasks with expansive purposes (narrow purposes cause the intent-verification model to reject legitimate requests). Hermes Agent offers a built-in alternative: multi-platform messaging (Telegram, Discord, Slack, WhatsApp, Signal, Email) plus tool access configured via config.yaml, with OAuth for Google services and scheduled automations reusing the same EA workflows through the gateway's tool system.

Meeting and call webhooks. Circleback records meetings, transcribes with speaker diarization, and fires a webhook ({gateway}/hooks/circleback-meetings) on completion carrying the full transcript, attendees, notes, action items, and calendar context; signature verification is HMAC-SHA256 over the body against a signing secret, header X-Circleback-Signature: sha256=<hex> — unverified webhooks must be rejected. API access uses OAuth dynamic client registration with ~24h access tokens. Quo (OpenPhone) provides SMS/call integration: webhooks for message.received, call.completed, call.summary.completed, call.transcript.completed; inbound calls over 30s trigger a transcript+summary fetch into a meetings/ brain page; inbound texts get sender lookup against the brain and a drafted (never auto-sent) reply. Auth is a bare API key in the Authorization header, no Bearer prefix.

Write-time reliability. gbrain frontmatter install-hook (v0.22.4+) installs a git pre-commit hook validating staged .md/.mdx frontmatter against eight failure classes (missing --- delimiters, YAML parse errors, slug mismatch, null bytes, nested quotes, non-string scalar fields, empty frontmatter) — bypass with git commit --no-verify. Separately, gbrain doctor and gbrain repair-jsonb (v0.12.2) detect and fix a historical JSONB double-encoding corruption class that hit real Postgres/Supabase brains (not PGLite) across four columns (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata); the repair is idempotent (UPDATE ... WHERE jsonb_typeof(col) = 'string').

Trust boundary on integration recipes. Only recipes shipped inside the gbrain package (recipes/ in a source install or the global install copy) are trusted to run command/http health checks. Recipes discovered from $GBRAIN_RECIPES_DIR or a cwd-local ./recipes/ are untrusted and restricted to env_exists/any_of checks — an SSRF defense.

How to Use

Smoke-test and switch an embedding provider:

gbrain providers list
gbrain providers test --model openai:text-embedding-3-large
gbrain init --pglite --model voyage

Enable ZeroEntropy embedding + reranker:

export ZEROENTROPY_API_KEY=<your-key>
gbrain config set search.reranker.enabled true
gbrain models doctor --json | jq '.probes[] | select(.touchpoint=="reranker_config")'

Wire a local llama-server reranker:

./build/bin/llama-server --model ./models/qwen3-reranker-4b-q4_k_m.gguf --alias qwen3-reranker-4b --reranking --port 8081
gbrain config set search.reranker.model llama-server-reranker:qwen3-reranker-4b
gbrain config set search.reranker.enabled true

Fix a JSONB corruption after upgrading past v0.12.1:

gbrain doctor
gbrain repair-jsonb --dry-run
gbrain repair-jsonb

Install the frontmatter pre-commit gate on a brain repo:

gbrain frontmatter install-hook

Related Entities

skills catalog — the frontmatter-guard and other skills that share validation logic with the pre-commit hook
recipes catalog — self-installing recipes referenced here (credential-gateway, meeting-sync, twilio-voice-brain)
retrieval and search — how reranking fits into the hybrid search pipeline
ingestion pipeline — the deterministic-collector pattern that meeting/call webhooks and email/calendar recipes rely on
operations and cost — reranker and embedding cost anchors, budget caps for local rerank
topology picker — which embedding provider (e.g. voyage-code-3) fits a code-brain topology