Reference on GENIE.AI

Environment variables (single source)

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This page is the single source of truth for GENIE.AI environment variables. It supersedes the three divergent tables that previously lived in deploy/install-guide.md, deploy/docker-compose-setup.md, and deploy/docker-swarm-setup.md (22 drift errors in Wave 1).

The defaults are pulled from the root env file and docker-compose.yaml. When a default disagrees with this table, fix the source first (the file in the repo), then regenerate.

Required secrets (no default — must be set)

Variable	Used by	Notes
`ARANGO_PASSWORD`	backend, dataprep, retriever, document-repository	Root DB password. Must be URL-safe; avoid `+`, `/`, `=`
`POSTGRES_PASSWORD`	postgres (kong-db, keycloak-db)	Kong + Keycloak shared PostgreSQL instance
`KONG_DB_PASSWORD`	kong-db, kong	Dedicated Kong DB user
`KEYCLOAK_DB_PASSWORD`	keycloak-db, keycloak	Dedicated Keycloak DB user
`KEYCLOAK_ADMIN_PASSWORD`	keycloak	Master admin console password
`KEYCLOAK_CLIENT_SECRET`	backend (BFF)	OIDC client secret for `genie-app`
`KEYCLOAK_PROXY_CLIENT_SECRET`	backend (admin proxy)	Service account secret for Admin API proxy
`KC_DATAPREP_CLIENT_SECRET`	dataprep	`client_credentials` grant secret
`EMAIL_HOST`	keycloak	SMTP server hostname
`EMAIL_PORT`	keycloak	SMTP server port (default 587)
`EMAIL_USER`	keycloak	SMTP username
`EMAIL_PASSWORD`	keycloak	SMTP password
`EMAIL_FROM`	keycloak	From address for user-verification emails
`HUGGING_FACE_HUB_TOKEN`	vllm, embedding, reranker (via HF_TOKEN)	Required to pull models
`VLLM_API_KEY`	all OPEA clients	Bearer token sent as `Authorization: Bearer`
`GRAFANA_ADMIN_PASSWORD`	grafana	Required when `ENABLE_OBSERVABILITY=1`
`GENIE_ADMIN_PASSWORD`	backend (BFF)	Realm-level admin bootstrap password — created on first run if absent. See Keycloak Admin Guide

Keycloak realm & OIDC clients (defaults — override per deployment)

Variable	Default	Used by	Notes
`KEYCLOAK_URL`	`https://localhost/auth`	backend, frontend, mobile	Public URL users reach your Keycloak at. BFF validates tokens against `<KEYCLOAK_URL>/realms/<KEYCLOAK_REALM>`.
`KEYCLOAK_REALM`	`genie`	backend, frontend, mobile	Realm name. Switch via Keycloak admin console dropdown.
`KEYCLOAK_CLIENT_ID`	`genie-app`	backend, frontend	Web SPA OIDC client id (must match the realm client).
`KC_DATAPREP_CLIENT_ID`	`dataprep-service-client`	dataprep	Service-account client for the `client_credentials` grant.
`KC_MOBILE_CLIENT_ID`	`genie-mobile-<institution>`	mobile	Mobile OIDC client id (PKCE flow). Per-flavor suffix — see `mobile/genie_ai_mobile/lib/config/flavors/<flavor>.dart` (e.g. `genie-mobile-itu`).
`KC_MOBILE_REDIRECT_SCHEME`	`com.<institution>.genieai`	mobile	Deep-link scheme registered on Android/iOS for the OIDC redirect. Android package convention (`com.<institution>.genieai[.<flavor>]`).

Realm-level admin bootstrap (defaults — override per deployment)

Variable	Default	Used by	Notes
`GENIE_ADMIN_USERNAME`	`genie-admin`	backend (BFF)	Realm-level admin username; created on first run if absent.
`GENIE_ADMIN_EMAIL`	(unset)	backend (BFF)	Email for the bootstrap admin user; recommended for `emailVerified: true` on first login.
`TRANSLATION_CACHE_PASSWORD`	(random per-service, persisted in volume)	backend (BFF)	Password for the translation-cache Redis user (set when a Redis password is enabled).

Deployment-specific

Variable	Default	Used by	Notes
`VLLM_TRANSLATION_MODEL_ID`	`google/gemma-3-4b-it`	translation	e.g. `facebook/m2m100-418M`
`EMBEDDING_MODEL_ID`	`BAAI/bge-large-en-v1.5`	embedding	Any TEI-supported encoder
`RERANKER_MODEL_ID`	`BAAI/bge-reranker-v2-m3`	reranker	Any TEI-supported cross-encoder
`VLLM_LLM_MODEL_ID`	`meta-llama/Meta-Llama-3.1-8B-Instruct`	vllm	Must support guided JSON (`response_format={"type":"json_object"}`)
`MODEL_LLM_TIMEOUT_SECONDS`	`180`	dataprep, retriever	vLLM chat completions. Read by `core/model_http_policy.py`. On every shipped topology it is parsed but unused: its only consumer is the retriever’s OpenAI-key probe, and no service is given `OPENAI_API_KEY`.
`MODEL_LLM_MAX_RETRIES`	`2`	dataprep, retriever	SDK retries on 408/409/429/5xx and connection errors. `0` is honoured as a real value. Values above 10 are rejected.
`MODEL_SUMMARIZER_TIMEOUT_SECONDS`	`600`	retriever	Document summarizer. A NEW ceiling, not the openai default kept. Not lowered: the call has no fallback, so its timeout becomes a 500 on the chat request.
`MODEL_EMBEDDING_TIMEOUT_SECONDS`	`600`	retriever	Embedding client, OpenAI-API branch ONLY. Also a NEW ceiling — `langchain-openai` forwards `request_timeout` (default `None`), which overrides the SDK default. Lowering it yields a silently EMPTY retrieval: the except clause returns `[]` ahead of the BM25 leg.
`MODEL_RERANK_TIMEOUT_SECONDS`	`300`	reranker	TEI rerank. Not lowered for the same reason as the summarizer.
`MODEL_AUTH_TIMEOUT_SECONDS`	`300`	dataprep	Keycloak service-account token fetch. Separate from the control-plane budget because every ingestion-log write and status update waits on it, one attempt, no retry, re-raises on failure.
`MODEL_CONTROL_PLANE_TIMEOUT_SECONDS`	`30`	dataprep, chatqna	Ingestion-log writes, doc-status updates, doc-repo callbacks. Not the Keycloak token fetch.
`MODEL_CONNECT_TIMEOUT_SECONDS`	`30`	dataprep, reranker	The CONNECT phase ceiling for every aiohttp session this policy budgeted. `aiohttp`’s default session already carried 30 s; passing an explicit `ClientTimeout(total=...)` drops it, and `None` means no limit rather than “inherit”. Raise for slow DNS or a routed mesh.
`MODEL_PROBE_TIMEOUT_SECONDS`	`10`	dataprep, retriever, chatqna	The `/v1/models` probe behind the TTL-cached model-id lookup. Degrades to the configured model id. Raise it on a remote GPU node whose models load slowly — the fallback otherwise picks the configured id instead of the served one.
`RERANKING_STRATEGY`	`slice`	chatqna	`slice` / `threshold` / `slice_threshold` / `knee_threshold` / `adaptive`
`RERANKER_TOP_N`	`3`	chatqna	Top chunks kept by `slice`/`slice_threshold`
`CONTEXTUAL_RETRIEVAL_ENABLED`	`true`	dataprep	On by default; prepends doc-context prefix
`DATAPREP_CONTEXTUAL_MODEL`	(empty = reuse `VLLM_LLM_MODEL_ID`)	dataprep	Must support guided JSON
`DATAPREP_CONTEXTUAL_DOC_BUDGET`	`100000` (Python code) / `6000` (compose override)	dataprep	Max chars fed to context LLM (~1500 tokens; ≤0 disables truncation). Compose override — `docker-compose.yaml` sets the per-chunk default to `6000` (the doc-level sibling `_DOC_LEVEL` stays at `100000`); the compose file wins at runtime. To use the full Python default, set `DATAPREP_CONTEXTUAL_DOC_BUDGET=100000` in `.env` before `docker compose --env-file .env up -d` (or `env.t4` / `env.rtx6000` overlays per Step 6d).
`DATAPREP_CONTEXTUAL_MAX_TOKENS`	`512`	dataprep	Per-call max output tokens for context generation
`CONTEXTUAL_STRATEGY`	`per_chunk`	dataprep	`per_chunk` (Anthropic recipe — default) or `doc_level` (N× cheaper, same context for every chunk)
`CONTEXTUAL_LABEL_RAW`	`true`	dataprep	`true` = label raw chunk, use context only for embedding
`CORS_ALLOWED_ORIGINS`	`http://localhost:3000,http://localhost:8090,http://127.0.0.1:8090,https://${NGINX_PUBLIC_DOMAIN:-localhost}`	backend	Comma-separated origins; localhost dev default
`CSP_CONNECT_SRC`	`'self' http://localhost:3000 http://localhost:8090 http://127.0.0.1:8090 ws://localhost:3000 ws://localhost:8090`	nginx	Content-Security-Policy `connect-src`; localhost dev default
`NGINX_PUBLIC_DOMAIN`	`localhost`	nginx	Public domain
`VUE_APP_API_URL`	`/api`	frontend	Frontend API base
`VUE_APP_AVAILABLE_LOCALES`	(unset = all)	frontend	Comma-separated codes (e.g. `en,es`) — see Restrict active locales
`KEYCLOAK_SUPPORTED_LOCALES`	(curated default)	keycloak	JSON array (e.g. `["en","es"]`) — see Restrict active locales
`STREAMING_TRANSLATION_ENABLED`	`0`	chatqna	`1`/`0`; stream translated tokens during generation
`KC_GRAFANA_CLIENT_ID`	`grafana`	keycloak, grafana	OIDC client ID for Grafana SSO
`KC_GRAFANA_CLIENT_SECRET`	(required when observability enabled)	keycloak, grafana	OIDC client secret

Observability

Variable	Default	Used by	Notes
`ENABLE_OBSERVABILITY`	`0`	root	`0`/`1` (not `true`/`false`)
`GRAFANA_ADMIN_USER`	`admin`	grafana
`GRAFANA_PORT`	`3002`	grafana	Host port; avoids Backend port conflict
`VICTORIAMETRICS_RETENTION`	`30d`	victoriametrics
`VICTORIALOGS_RETENTION`	`30d`	victorialogs
`VICTORIALOGS_URL`	(no in-code default — `VictoriaLogsClient` constructor must receive `baseURL`; Ansible `env.j2:243` sets `http://victorialogs:9428`)	backend	VL HTTP base URL. Injected by `env.j2`; bypass only when running outside Ansible and set it explicitly.
`VICTORIALOGS_TENANT_ID`	(no in-code default — read by `shared/lib/melt/victorialogs-client.js:105`, defaults `AccountID:0, ProjectID:0` when unset)	backend	Tenant header for `/select/logsql/*` (`AccountID:ProjectID`). Ansible splits `VICTORIALOGS_TENANT_ID` into `VICTORIALOGS_TENANT_ID_ACCOUNT_ID` + `VICTORIALOGS_TENANT_ID_PROJECT_ID` for the underlying VL request.
`VICTORIATRACES_RETENTION`	`30d`	victoriatraces
`MELT_PROVIDER`	`victorialogs` (hardcoded constant in `components/shared/lib/melt/index.js`)	backend	Future-proof seam selector for the OTel metrics/logs/traces exporter. Whitelisted by `tests/config-validator/` so a deployer may override the env file; the runtime constant is the actual current value. Today there is only one backend implementation.
`OTEL_TRACES_SAMPLER_RATE`	`100.0`	backend, opea	0.0–100.0
`KONG_TRACING_INSTRUMENTATIONS`	`request`	kong
`KONG_TRACING_SAMPLING_RATE`	`1.0`	kong	0.0–1.0
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://otel-collector:4318`	backend, opea, kong	Base URL for OTLP
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	(not set — collector derives `/v1/logs` from `OTEL_EXPORTER_OTLP_ENDPOINT`)	backend, opea	Set only when the logs endpoint must override the inferred one (signal-specific URL is used as-is; no path appended).
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	(not set — collector derives `/v1/traces` from `OTEL_EXPORTER_OTLP_ENDPOINT`)	backend, opea	Set only when the traces endpoint must override the inferred one.
`VL_QUERY_TIMEOUT_MS`	`30000`	backend	axios timeout for VictoriaLogs `query` / `hits`

Prompts (override defaults)

Variable	Default	Used by	Notes
`CHATQNA_SYSTEM_PROMPT`	(built-in)	chatqna	LLM system prompt
`CHATQNA_ABSTENTION_INSTRUCTIONS`	(built-in)	chatqna
`CHATQNA_ENFORCE_ABSTENTION`	`true`	chatqna
`LABEL_SELECTOR_SYSTEM_PROMPT`	(built-in)	dataprep	`{labels_list}` placeholder
`CONTEXTUAL_RETRIEVAL_PROMPT`	(built-in)	dataprep	`{document_context}` placeholder

Service ports (with defaults baked in)

See Configure → CORS / CSP / public-domain for the nginx / kong / keycloak port map.

Backend HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

This page is the canonical HTTP API reference for the GENIE.AI backend (gov-chat-backend). For each endpoint: the path, the HTTP method, the required auth, the request shape, the response shape, and the error semantics.

For the narrative version with worked examples, see this page itself — this is the single source of truth for the HTTP API.

Component

components/gov-chat-backend/ (Node.js 22, Express, JWT, winston). Base URL: https://<domain>/api (via Kong Gateway). Internal port: 3000 (not exposed in Swarm). OpenAPI: /api-docs (Swagger UI served from the BFF itself).

Source Tree Analysis

Mon, 01 Jan 0001 00:00:00 +0000

For developers. A walk-through of the repository layout — use it to find where a component lives and what it depends on. Operators and content managers do not need this page.

Overview

GENIE.AI is a sovereign, DPG-compliant RAG (Retrieval-Augmented Generation) system with multilingual support. The monorepo is organized into 6 main parts:

OPEA protocol extensions

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

GENIE.AI extends the standard OPEA mega-service protocol with several GENIE.AI-specific fields and event types. This page is the canonical reference; the implementation lives in genie-ai-overlay/core/genieai_api_protocol.py.

Standard OPEA protocol (recap)

OPEA’s mega-service defines a DAG of microservices. Each downstream service accepts an asyncio input that is itself a dict — typically:

{
 "messages": [{"role": "user", "content": "..."}],
 "retriever_parameters": {},
 "reranker_parameters": {}
}

The mega-service streams the final LLM response via SSE, plus per-stage metadata events.

GENIE.AI extensions

`retrieval_confidence_score`

Field on the terminal SSE event. Computed as a rank-weighted exponential-decay aggregate of calibrated reranker scores (top-ranked chunks dominate — flat mean was tail-sensitive). Individual reranker scores are calibrated by RERANKER_SCORE_CALIBRATION before the aggregate. The citizen-facing confidence_score field falls back to self_confidence when LLM_SELF_CONFIDENCE_ENABLED=true; the raw retrieval_confidence_score is still emitted for admin/eval.

Kong / Nginx routes

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

The path-prefix → backend service mapping for every public route. Useful when configuring an external proxy, a Cloudflare worker, or debugging a 404.

Nginx (TLS termination)

Path	Upstream	Notes
`/`	frontend (Vue SPA)	Static; SPA fallback to `/index.html`
`/api/*`	kong (port 8000)	All API calls
`/grafana/*`	kong (port 8000)	Kong routes to grafana
`/auth/*`	kong (port 8000)	Kong routes to keycloak
`/assets/*`	frontend	Static assets
`/robots.txt`	nginx	Static, served by Nginx

Kong (API gateway)

Path-prefix	Service	Auth	Rate limit
`/api/*` (fallback)	express-api	JWT (per-route)	service-wide 1000 / min on express-api
`/api/auth/*`	express-api	none (refresh-token cookie)	service-wide
`/api/auth/refresh-token`	express-api	none (cookie)	service-wide
`/api/auth/login`	express-api	none	service-wide
`/api/me`	express-api	JWT	service-wide
`/api/queries`	express-api	JWT	service-wide
`/api/chat/*`	express-api	JWT	service-wide
`/api/admin/*`	express-api	JWT + role `admin`	service-wide
`/Uploads/*`	backend (`express.static`)	public	none

Per-route rate limits are NOT configured in Kong — the 1000/min limit is applied service-wide to express-api. /api/health and /api/public/* have no dedicated Kong routes; they are reached via the /api fallback (api-fallback route, strip_path: false).

ArangoDB collections

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

The canonical list of every ArangoDB collection used by GENIE.AI, with field names and types. Useful when writing an AQL query, debugging a missing field, or wiring a new microservice.

Note: this page covers the most-frequently-used collections. The complete list (defined in 001-create-collections.js) also includes sessions, sessionQueries, userSessions, userConversations, conversationCategories, queryMessages, conversationFiles, queryCategories, categoryServices, serviceTranslations, serviceTranslationsEdge, folders, userFolders, folderConversations, analytics, weatherRequests, labels, crawl_job, crawl_log, crawl_metrics.

User-facing collections

`users`

Field	Type	Notes
`_key`	string	ArangoDB-generated; UUID is a convention but any string works
`iss_sub`	string	Keycloak `<iss>` + `<sub>` composite (indexed, unique)
`iss`	string	Keycloak issuer URL
`sub`	string	Keycloak subject
`email`	string	indexed (non-unique)
`name`	string	Display name (combined from Keycloak `name` or `preferred_username`)
`emailVerified`	bool	Mirrors Keycloak `email_verified` claim
`roles`	array	Realm roles from Keycloak JWT (`decodedToken.realm_access.roles`); e.g. `["Admin"]` / `["dataprep-service"]` / `[]`
`active`	bool	False-when-deleted soft-delete marker
`deleted`	bool	Soft-delete flag
`createdAt`	ISO-8601
`updatedAt`	ISO-8601

`conversations`

Field	Type	Notes
`_key`	string	UUID
`title`	string
`lastMessage`	string	Preview of the latest message content
`created`	ISO-8601
`updated`	ISO-8601
`messageCount`	int
`isStarred`	bool
`isArchived`	bool
`category`	string	Optional category label
`tags`	array

The link between a conversation and its owning user lives in the userConversations edge collection (_from: users/<id>, _to: conversations/<id>), not as a userId field on the conversation document.

Service registry enum

Mon, 01 Jan 0001 00:00:00 +0000

Purpose

The canonical enum of service names used in OTel attributes, VictoriaLogs filters, Kong routes, and Docker swarm service names. The Python enum lives in genie-ai-overlay/core/constants.py.

Service registry

Note: The “Enum value” column is a logical role used in code and ops queries — there is no service-name enum in genie-ai-overlay/core/constants.py (only the OPEA service-type enum ServiceType lives there). The OTel service.name column shows the value passed to setup_tracing(...) for instrumented services, or the env-var / container name for uninstrumented ones. “Docker service” is the block name in docker-compose.yaml; in Docker Swarm it is prefixed by the stack name (e.g. genieai_chatqna-xeon-backend-server).

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

GENIE.AI glossary — every acronym used across the docs.

A–Z

Term	Definition
Ansible	Agentless automation tool used for the production Swarm deploy (`deploy/ansible/`).
ArangoDB	Multi-model database (document + graph + vector) that holds the knowledge base.
BFF	“Backend for frontend” — the `gov-chat-backend` Node.js service that brokers HTTP for both web and mobile clients.
BM25	Classic lexical relevance score used alongside vector search in hybrid retrieval.
ChatQnA	The OPEA mega-service that orchestrates the RAG pipeline.
ClamAV	Open-source antivirus used by the document repository to scan uploads.
Contextual Retrieval	Anthropic-style technique: prepend an LLM-generated doc-context prefix to each chunk before embedding, improving retrieval precision. Enabled by `CONTEXTUAL_RETRIEVAL_ENABLED=true`.
Diataxis	Documentation framework that splits docs into Tutorial, How-to, Reference, Explanation. Every doc on this site carries a `mode:` field reflecting its quadrant.
DPG	Digital Public Goods — a UN-endorsed standard for open-source projects. GENIE.AI targets DPG compliance.
Docling	IBM document-parser used by `dataprep` to turn PDFs / DOCX / HTML into chunks.
Docsy	The Hugo theme this site is built on.
Embedding	A vector representation of a text passage. The default model (`BAAI/bge-large-en-v1.5`) produces 1024-D vectors. See Choosing models for the supported-model matrix (dimension, recall, VRAM).
Fluentd	Log forwarder used by every container (Docker `fluentd` driver) to ship stdout/stderr to the OTel Collector.
Grafana	The dashboards + alerting UI for the observability stack. Reachable at `/grafana/`.
Hybrid retrieval	Combines vector search (semantic) with BM25 (lexical) and fuses the scores. Enabled by `RETRIEVER_HYBRID_RETRIEVAL_ENABLED` (default `true`). `RETRIEVER_ARANGO_SEARCH_MODE` (default `vector`) is independent and selects the dense strategy — similarity vs Maximum Marginal Relevance (MMR).
JWT	JSON Web Token — the format of Keycloak access tokens used to authorize API calls.
Keycloak	OIDC identity provider; default realm is `genie`.
Kong	API gateway that fronts every service; routes by path prefix.
MELT seam	The backend abstraction that exposes Metrics, Events, Logs, Traces to the admin UI.
NGINX	TLS-terminating reverse proxy exposed on 80 / 443.
OIDC	OpenID Connect — the protocol used for SSO via Keycloak.
OPEA	Open Platform for Enterprise AI — the framework GENIE.AI’s RAG pipeline is built on.
OTel	OpenTelemetry — the standard for emitting traces, metrics, and logs.
OTLP	OpenTelemetry Line Protocol — the wire format over which app services ship telemetry to the Collector.
RAG	Retrieval-Augmented Generation — answer questions by grounding an LLM in retrieved documents.
Reranker	A cross-encoder that re-scores the top-K retrieval candidates.
Retriever	The microservice that fetches candidate chunks from ArangoDB.
RFP / ROPC	Resource Owner Password Credentials — a Keycloak grant. Disabled by default for security.
SSE	Server-Sent Events — the wire format ChatQnA streams the response over.
TEI	Text Embeddings Inference — HuggingFace’s serving runtime for embedding and reranking models.
TEI Reranker	The reranker microservice; runs a cross-encoder model.
TEI Embedding	The embedding microservice; runs an encoder model.
Translation	Optional microservice that translates the LLM response to the user’s UI locale.
vLLM	The high-throughput LLM serving runtime; runs the chat + labeling models.
VictoriaLogs	Single-node log store used by the observability stack.
VictoriaMetrics	Single-node metrics store.
VictoriaTraces	Single-node trace store; exposes a Jaeger-compatible API.
W3C `traceparent`	The standard HTTP header used to propagate trace context across service boundaries.
WSS	WebSocket Secure. Used in dev by the Vue dev-server HMR (websocket transport on `vue.config.js`); not used in production (admin logs tail via `/api/admin/logs/search` HTTP polling).

Get started → Concepts — five-minute tour of the GENIE.AI mental model.
Architecture → Overview — how every acronym above fits together.

Reference on GENIE.AI

Environment variables (single source)

Purpose

Required secrets (no default — must be set)

Keycloak realm & OIDC clients (defaults — override per deployment)

Realm-level admin bootstrap (defaults — override per deployment)

Deployment-specific

Observability

Prompts (override defaults)

Service ports (with defaults baked in)

Backend HTTP API

Purpose

Component

Source Tree Analysis

Table of Contents

Overview

OPEA protocol extensions

Purpose

Standard OPEA protocol (recap)

GENIE.AI extensions

retrieval_confidence_score

Kong / Nginx routes

Purpose

Nginx (TLS termination)

Kong (API gateway)

ArangoDB collections

Purpose

User-facing collections

users

conversations

Service registry enum

Purpose

Service registry

Glossary

A–Z

Related

`retrieval_confidence_score`

`users`

`conversations`