Environment Variables Reference

Raw to Knowledge reads all configuration from environment variables using pydantic-settings. Variables are validated at startup. Unknown variables are ignored. Variables marked as required will cause a startup failure if absent.

Set variables in your shell environment, a .env file in the working directory, or your container orchestration platform's secret/config management.

Core services

Variable	Default	Required	Description
`DATABASE_URL`	`postgresql+asyncpg://raw_to_knowledge:raw_to_knowledge@localhost/raw_to_knowledge`	Yes	PostgreSQL connection string. Must use the `asyncpg` driver prefix (`postgresql+asyncpg://`). The synchronous driver is not supported.
`REDIS_URL`	`redis://localhost:6379/0`	Yes	Redis connection string. Used as the Celery broker and for the Redis-backed validation queue.
`ENVIRONMENT`	`development`	No	Runtime environment name. Setting `development` enables CORS wildcard (`*`). Set to any other value (e.g., `production`) to restrict CORS to configured origins.
`LOG_LEVEL`	`INFO`	No	structlog log level. Accepted values: `DEBUG`, `INFO`, `WARNING`, `ERROR`. Use `DEBUG` for verbose request and task logging during troubleshooting.

API authentication

All /v1 endpoints require an X-API-Key header. API_KEY_ROLES_JSON maps stable key IDs to opaque secrets and roles. Each authentication attempt emits a structured api_access audit event containing its outcome, route, method, role, and key ID, never the secret.

Variable	Default	Required	Description
`API_KEY_ROLES_JSON`	(empty in development)	Yes outside development	JSON object mapping stable key IDs to `{secret, role, active}` records. The service refuses non-development startup when this is unset.
`API_RATE_LIMIT_PER_MINUTE`	`120`	No	Maximum `/v1` requests per authenticated key ID in each fixed 60-second Redis window. Redis unavailability fails requests closed with `503`.

reader can retrieve knowledge, readouts, trends, and metrics. reviewer also performs knowledge ingestion, classification, validation, registry, generation, and graph write operations. admin also manages connector pulls/sync configuration and trend-cluster administration.

Example secret value:

{
  "reader-2026-01": {
    "secret": "replace-with-reader-secret",
    "role": "reader",
    "active": true
  },
  "reviewer-2026-01": {
    "secret": "replace-with-reviewer-secret",
    "role": "reviewer"
  },
  "admin-2026-01": {
    "secret": "replace-with-admin-secret",
    "role": "admin"
  }
}

Send the key on every API request:

X-API-Key: replace-with-reader-secret

Development without configured keys grants local admin access only. Do not use that behavior outside an isolated local environment.

Rotate a key by creating a new key ID and changing clients to its secret. Revoke a key by setting its active field to false; inactive keys are rejected immediately at the next configuration reload. The legacy { "raw-secret": "role" } form remains accepted temporarily, but cannot provide identifiable audit events or per-key revocation.

Neo4j (graph features)

Variable	Default	Required	Description
`NEO4J_URI`	`bolt://localhost:7687`	Graph features	Neo4j connection URI. Supports `bolt://`, `bolt+s://`, and `neo4j://` schemes.
`NEO4J_USERNAME`	`neo4j`	Graph features	Neo4j authentication username.
`NEO4J_PASSWORD`	`password`	Graph features	Neo4j authentication password. Change this from the default for any non-local deployment.

If these variables are not set, graph sync and contradiction detection endpoints return errors. All other endpoints continue to function.

Weaviate (semantic retrieval and generation)

Variable	Default	Required	Description
`WEAVIATE_URL`	`http://localhost:8080`	Retrieval/generation	URL of the Weaviate instance. Used for the vector search index.
`WEAVIATE_API_KEY`	(empty)	Weaviate Cloud only	API key for Weaviate Cloud (WCD) deployments. Leave empty for self-hosted Weaviate with anonymous access enabled.

If WEAVIATE_URL is unreachable, semantic retrieval returns empty results and generation falls back to registry-only context.

LLM (generation)

Variable	Default	Required	Description
`OPENAI_API_KEY`	(required for generation)	Generation features	API key for the OpenAI-compatible LLM provider. Must be set for answer generation to function.
`LLM_MODEL`	`gpt-4o`	No	Model identifier passed to the chat completions endpoint. Change to use a different model (e.g., `gpt-4o-mini`, a fine-tuned model ID).
`RAG_TOKEN_LIMIT`	`4096`	No	Maximum number of tokens assembled into the RAG context window before passing to the LLM. Reduce if you encounter context-length errors with smaller models.

Confluence connector (RAG source)

All four variables must be set to enable the Confluence connector. If any are absent, Confluence is skipped as a RAG source and no error is raised at startup.

Variable	Default	Required	Description
`CONFLUENCE_BASE_URL`	(empty)	Confluence RAG	Base URL of the Confluence instance. Example: `https://yourorg.atlassian.net/wiki`.
`CONFLUENCE_USERNAME`	(empty)	Confluence RAG	Atlassian account username (email address) for API authentication.
`CONFLUENCE_API_TOKEN`	(empty)	Confluence RAG	Atlassian API token. Generate at `id.atlassian.com` → Security → API tokens.
`CONFLUENCE_SPACE_KEY`	(empty)	Confluence RAG	Comma-separated list of Confluence space keys to search during RAG retrieval. Example: `KM,ENG,SUPPORT`.

Jira connector (RAG source and escalation)

All four variables must be set to enable the Jira connector. If any are absent, Jira is skipped as a source and escalation write-back is disabled.

Variable	Default	Required	Description
`JIRA_BASE_URL`	(empty)	Jira RAG	Base URL of the Jira instance. Example: `https://yourorg.atlassian.net`.
`JIRA_USERNAME`	(empty)	Jira RAG	Atlassian account username (email address) for API authentication.
`JIRA_API_TOKEN`	(empty)	Jira RAG	Atlassian API token. Same token as Confluence if on the same Atlassian organization.
`JIRA_PROJECT_KEY`	(empty)	Jira RAG	Jira project key. Used to scope RAG searches and as the target project when creating escalation issues. Example: `KM`.

Transcript source connectors

The transcript-source connector framework can be configured in two ways:

preferred: CONNECTOR_CONFIGS_JSON
backward-compatible aliases for built-in connectors: FELLOW_*, GONG_*

Generic connector configuration

Variable	Default	Required	Description
`CONNECTOR_CONFIGS_JSON`	(empty)	Transcript source connectors	JSON object keyed by source system. Each value is a connector-specific config object consumed by the connector provider.
`CONNECTOR_SYNC_POLL_INTERVAL_MINUTES`	`15`	Scheduled connector sync	How often Celery beat checks persisted connector sync states to determine which sources are due for retrieval.

Example:

{
  "fellow": {
    "api_token": "fellow_pat_abc123",
    "base_url": "https://api.fellow.ai/v2"
  },
  "gong": {
    "access_key": "gong_key_abc",
    "access_secret": "gong_secret_xyz",
    "base_url": "https://api.gong.io/v2"
  }
}

This is the preferred path for new transcript-source connectors because it allows a new connector package to be added without modifying the strongly typed settings model or route-registration code.

Built-in connector aliases

Variable	Default	Required	Description
`FELLOW_API_TOKEN`	(empty)	Fellow connector	Fellow Personal Access Token or OAuth 2.0 bearer token. Compatibility alias for `CONNECTOR_CONFIGS_JSON["fellow"].api_token`.
`FELLOW_BASE_URL`	`https://api.fellow.ai/v2`	Fellow connector	Compatibility alias for `CONNECTOR_CONFIGS_JSON["fellow"].base_url`.
`GONG_ACCESS_KEY`	(empty)	Gong connector	Gong API access key. Compatibility alias for `CONNECTOR_CONFIGS_JSON["gong"].access_key`.
`GONG_ACCESS_SECRET`	(empty)	Gong connector	Gong API access secret. Compatibility alias for `CONNECTOR_CONFIGS_JSON["gong"].access_secret`.
`GONG_BASE_URL`	`https://api.gong.io/v2`	Gong connector	Compatibility alias for `CONNECTOR_CONFIGS_JSON["gong"].base_url`.

When both CONNECTOR_CONFIGS_JSON and alias variables are present, explicit values from CONNECTOR_CONFIGS_JSON win and alias values fill in missing fields only.

Connector cadence, initial_since, watermark, and default legal basis are not environment variables. They are persisted per source system through PUT /v1/connectors/{source_system}/sync.

Classification and validation behavior

Variable	Default	Required	Description
`CLASSIFICATION_THRESHOLD`	`0.75`	No	Minimum confidence score (0.0–1.0) for auto-classification. Candidates classified below this threshold have `requires_review = true`. Reduce this value to decrease the volume of manual review; increase it for stricter auto-classification.
`BLOCK_VALIDATION_ON_CONFLICT`	`true`	No	When `true`, a `ConflictFlag` on an answer prevents it from being assigned for validation review. Set to `false` to allow conflicted answers to proceed through validation unblocked.

Notes on `.env` file usage

pydantic-settings automatically reads a .env file from the current working directory if one exists. This is convenient for local development but should not be used in production where secrets management tooling is available.

Example .env file for local development:

DATABASE_URL=postgresql+asyncpg://raw_to_knowledge:raw_to_knowledge@localhost/raw_to_knowledge
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4o
WEAVIATE_URL=http://localhost:8080
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
LOG_LEVEL=DEBUG
ENVIRONMENT=development

Do not commit .env files containing secrets to source control.