Overview
Gregius Data’s RAG subsystem grounds every answer in your synchronized WordPress content. It orchestrates three sequential phases — retrieval, governance, and generation — returning answers with source attribution or explicit abstentions when acceptable evidence is unavailable.
Prerequisites
- WordPress 6.9+ with Gregius Data plugin installed and activated
- At least one data connection configured and active
- At least one embedding model and one LLM model registered and active
- Content synchronized through the connection (via sync)
How RAG Works
When a user submits a query, the RAG subsystem processes it through three sequential phases before returning a response.
Retrieval phase
The subsystem retrieves relevant evidence from synchronized content. It supports lexical (keyword), semantic (embedding-based), or hybrid search modes. Post-level candidates are expanded into passage-level chunks when available. Optional reranking can reorder candidates for higher precision.
Governance phase
Before generating an answer, the governance layer evaluates the accepted evidence against threshold profiles. It classifies coverage as full, partial, or abstain. When no acceptable evidence remains, the subsystem short-circuits and returns an abstention — it never fabricates source-backed answers.
Generation phase
The subsystem resolves the effective prompt, invokes the configured LLM, and returns a structured response containing answer text, source attribution data, and metadata describing retrieval behavior, selected models, timing, and governance outcome.
REST API Endpoints
The RAG subsystem exposes several REST endpoints under the gg-data/v1 namespace.
Main chat endpoint
POST /rag/chat accepts a query, connection, embedding model, and LLM model. Optional parameters include retrieval volume, temperature, prior messages, conversation ID, metadata filters, manifest payloads, and deterministic tool overrides. Missing required fields return a structured error.
User-triggered actions
POST /rag/action executes a registered tool directly without model selection, and GET /rag/actions lists available user-triggerable tools with their names, descriptions, and parameter schemas.
Guest journey continuity
Three endpoints (POST /rag/journey/issue, POST /rag/journey/consume, GET /rag/journey/history) allow guest users without WordPress accounts to maintain persistent conversation history within their browser session. Session-bound ownership is enforced through hashed credentials derived from WordPress authentication salts.
Access Control and Permissions
| Endpoint group | Method | Default access | Permission seed |
|---|---|---|---|
Chat (/rag/chat) | POST | Deny (fail-closed) | Must be explicitly granted |
Action (/rag/action, /rag/actions) | POST, GET | Deny (fail-closed) | Must be explicitly granted |
Journey (/rag/journey/*) | POST, GET | Allow (fail-open) | Must be explicitly denied |
SSE stream (/rag/stream) | GET | Allow (fail-open) | Must be explicitly denied |
Access can be customized through the gg_data_rag_endpoint_permission, gg_data_rag_access_level, and gg_data_rag_required_capability hooks. Route-scoped rate limiting is applied to chat and action endpoints, returning HTTP 429 when exceeded.
Available Extension Hooks
| Category | Hooks | Purpose |
|---|---|---|
| Request lifecycle | gg_data_rag_request, gg_data_rag_complete, gg_data_rag_error | Observe request start, success, and failure |
| Retrieval and response | gg_data_rag_search_query, gg_data_rag_chunks, gg_data_rag_context, gg_data_rag_sources, gg_data_rag_response | Customize query rewriting, evidence shaping, and response mutation |
| Governance and policy | gg_data_rag_threshold_profile, gg_data_rag_retrieval_policy, gg_data_rag_rerank_policy, gg_data_rag_abstain_message, gg_data_rag_governance_decision | Control acceptance thresholds and policy decisions |
| Tool registration | gg_data_rag_tools, gg_data_rag_tool_{name}, gg_data_rag_tool_executed | Register custom tools and react to execution |
| Rate limiting | gg_data_rag_rate_limit_anonymous, gg_data_rag_rate_limit_authenticated, gg_data_rag_rate_limit_window_seconds | Tune fixed-window rate limits |
Next Steps
View on GitHub: You can review, fork, and inspect the entire codebase and core logic over at the repository on GitHub.
Gregius Data is the open-source AI orchestration layer for WordPress.