pyproject.toml + uv.lock; install with uv sync or pip install -e .. Default PyPI index is Aliyun ([[tool.uv.index]] in pyproject.toml); uv.lock pins mirrors.aliyun.com URLs. Regenerate after dependency edits: cd backend && uv lock. Docker builds also pass UV_INDEX_URL / UV_EXTRA_INDEX_URL (see docker/README.md).
pgvector: FAQ/chunk list excludes embedding when pgvector is not installed (has_embedding=false). Semantic search returns 503 with install instructions. backend/dev.sh runs scripts/ensure_pgvector.py on start to check / create the extension and optionally auto-install in Docker.
MinIO base URL (e.g. http://localhost:9000); omit for real S3
AWS_BUCKET_NAME
Bucket name (default openkms)
AWS_REGION
Region (default us-east-1)
Documents land under documents/{file_hash}/ (legacy {file_hash}/ still read until migrated); articles under articles/{id}/; wiki spaces under wiki/{space_id}/. Dev: Vite proxies /buckets/openkms to MinIO for image loads. Console Object storage (/console/storage, console:storage) lists bucket metadata, creates folder placeholders, and moves prefixes/objects (no download).
Deprecated aliases used by older pipelines; prefer OPENKMS_VLM_*
OPENKMS_EXTRACTION_MODEL_ID
unset
api_models.id for the LLM that extracts document metadata; falls back to channel/default settings
OPENKMS_PIPELINE_TIMEOUT_SECONDS
3600
Worker timeout for openkms-cli pipeline run (VLM parse + extraction)
Embedded agent (LangGraph wiki / future surfaces)¶
Variable
Default
Purpose
OPENKMS_AGENT_MODEL_ID
unset
api_models.id for in-app agent LLM calls (knowledge map designer, ontology explore, Deep Agents) when OPENKMS_DEEP_AGENT_MODEL_ID is unset; else the first available LLM
OPENKMS_AGENT_MAX_OUTPUT_TOKENS
65537
Upper bound on completion length passed as max_tokens; raise if your model supports more
OPENKMS_AGENT_RECURSION_LIMIT
200
Max LangGraph supersteps per turn (each tool+model cycle uses steps; bulk get/upsert needs a high value)
OPENKMS_AGENT_LOG_LEVEL
INFO
Project Deep Agents turn logs (agent_turn_start / agent_turn_done; agent_turn_failed at ERROR). See Agents — Observability.
OPENKMS_BACKEND_LOG_LEVEL
—
Optional root log level for all app.* loggers when set
OPENKMS_AGENT_SANDBOX_TIMEOUT_SECONDS
60
Python sandbox in project workspace (Deep Agents execute)
OPENKMS_AGENT_LLM_EXTRA_BODY
unset
Optional JSON merged into OpenAI-compat extra_body. Used independently by Knowledge Map Designer (agent.shared wrappers) and Deep Agents (deep_agents.llm_chat). enable_thinking is always forced to false after merge — these paths do not support thinking / full reasoning_content round-trip beyond what the shim echoes. Shared primitives live in app.services.openai_compat.
OPENKMS_AGENT_LLM_REASONING_CONTENT_SHIM
unset
auto: inject reasoning_content on assistant messages for every base_url except api.openai.com (covers generic OpenAI-compat proxies, including DeepSeek). Same env is read by Designer and Deep Agents façades separately. true / 1: always inject. false / 0: never inject. Legacy alias: OPENKMS_AGENT_DASHSCOPE_REASONING_SHIM.
OPENKMS_AGENT_KB_QA_MAX_CONTEXT_MESSAGES
120
Max prior messages included in conversation_history for one KB / evaluation / FAQ-assist qa-agent call.
LANGFUSE_SECRET_KEY
unset
With LANGFUSE_PUBLIC_KEY and LANGFUSE_BASE_URL, enables Langfuse on Deep Agents (same keys as qa-agent).
LANGFUSE_PUBLIC_KEY
unset
Langfuse public key (shared by backend agents + qa-agent when both run in the same environment).
LANGFUSE_BASE_URL / LANGFUSE_HOST
unset
Langfuse server URL. Required for tracing (same rule as qa-agent); if unset, no traces are sent.
LANGFUSE_TRACE_STREAMING
true
Attach Langfuse callback to streaming agent turns when tracing is enabled; set false to trace only non-streaming if OTel noise.
LANGFUSE_HEALTHCHECK
true
Probe {base}/api/public/health before attaching callbacks; also used by Console health.
LANGFUSE_HEALTHCHECK_RETRY_SECONDS
60
Backoff between health probes while Langfuse is considered down.
LLM: When OPENKMS_LLM_MODEL_* are unset, qa-agent calls GET /internal-api/models/llm-defaults (internal service client only — same as openkms-cli on document-parse-defaults). If qa-agent uses a distinct IdP client id, add it to backend OPENKMS_INTERNAL_SERVICE_CLIENT_IDS. Local mode: OPENKMS_QA_AGENT_BASIC_* on qa-agent (and backend). OIDC: OPENKMS_QA_AGENT_OIDC_CLIENT_*. Backend allowlist: OPENKMS_INTERNAL_SERVICE_CLIENT_IDS. Docker Compose sets app service env via environment only; override ${…} substitution with docker/.env (see docker/.env.example, docker/README.md).
Same OpenAI-compat thinking handling as the backend in-app agents: optional JSON extra_body, then enable_thinking: false is always applied; reasoning_content is injected on outgoing assistant rows when the shim is on (see OPENKMS_AGENT_LLM_* rows above). You can set either the OPENKMS_LLM_* names below or reuse the OPENKMS_AGENT_* names so one block of env works for both.
Variable
Default
Purpose
OPENKMS_BACKEND_URL
http://localhost:8102
Backend base URL for search APIs and LLM default fetch
OPENKMS_AUTH_MODE
unset
local or oidc — must match backend (same name as openkms-cli)
OPENKMS_OIDC_TOKEN_URL
unset
Required in OIDC mode; IdP token_endpoint (same name as openkms-cli)
OIDC client credentials (id must appear in backend OPENKMS_INTERNAL_SERVICE_CLIENT_IDS)
OPENKMS_QA_AGENT_RECURSION_LIMIT
200
Max LangGraph supersteps per KB Q&A turn (generate ↔ tools). Alias:OPENKMS_AGENT_RECURSION_LIMIT. Without this, LangGraph defaults to 25 (ontology-heavy questions hit it quickly).
In-process TTL for GET /api/auth/permission-catalog; 0 disables. Cleared when admins mutate security_permissions.
OPENKMS_ENFORCE_PERMISSION_PATTERNS_STRICT
false
When true, every authenticated /api request must match a catalog backend_api_pattern and the user must hold that key
OPENKMS_ENFORCE_RESOURCE_ACL
false
Default-closed Layer 2: resources without ACL rows are denied (OPENKMS_ENFORCE_GROUP_DATA_SCOPES is an alias)
OPENKMS_PERMISSION_PATTERN_CACHE_TTL_SECONDS
60
TTL for compiled permission patterns loaded from security_permissions
OPENKMS_ENFORCE_GROUP_DATA_SCOPES
(alias)
Same as OPENKMS_ENFORCE_RESOURCE_ACL
OPENKMS_DATASOURCE_ENCRYPTION_KEY
unset
Fernet key (base64) used to encrypt data_sources credentials, connector secrets (connectors.secrets_encrypted), and Kubernetes kubeconfigs (kubernetes_clusters.kubeconfig_encrypted); required before storing those values
AGENTS.md at the repo root (coding behavior, docs-before-commit, Alembic, frontend verification). Doc editing conventions: Doc conventions for AI agents.