mucgpt

Getting Started

⚙️ Configure the environment

Configuration is done via YAML configuration files (primary) with optional environment variable overrides.

Each service reads a config.yaml mounted into the container. Environment variables can override any YAML setting using a service-specific prefix and __ (double underscore) as the nested delimiter.

Service YAML file (in stack/) Env Prefix
core-service core.config.yaml MUCGPT_CORE_
assistant-service assistant.config.yaml MUCGPT_ASSISTANT_
assistant-migrations assistant.config.yaml MUCGPT_ASSISTANT_

Initial Setup

cd stack
cp .env.example .env
cp core.config.yaml.example core.config.yaml
cp assistant.config.yaml.example assistant.config.yaml

Models Configuration (YAML)

Configure your LLM models in core.config.yaml:

MODELS:
  - type: "OPENAI"
    llm_name: "<your-llm-name>"
    endpoint: "<your-endpoint>"
    api_key: "<your-sk>"
    model_info:
      auto_enrich_from_model_info_endpoint: true
      max_output_tokens: 16384
      max_input_tokens: 128000
      description: "<description>"
      input_cost_per_token: 0.00000009
      output_cost_per_token: 0.00000036
      supports_function_calling: true
      supports_reasoning: false
      supports_vision: true
      litellm_provider: "<provider>"
      inference_location: "<region>"
      knowledge_cut_off: "2024-07-01"

See mucgpt-core-service/config.yaml.example and mucgpt-assistant-service/config.yaml.example for complete examples.

Prompt Configuration

See the AI governance and compliance checks guide for the end-to-end screening flow, version lifecycle, review queue, and operational responsibilities.

The optional PROMPTS section maps prompt names used by the core service to prompts stored in langfuse. Configure each prompt under its Langfuse folder with the label to use; folder and prompt names must match Langfuse exactly. See mucgpt-core-service/config.yaml.example for the complete YAML structure.

Document Parsing Configuration (YAML)

The core service supports extracting text and structure from uploaded documents using an optional parser. Configure the document parser in core.config.yaml. By default, document parsing is disabled (PARSER_BACKEND: "none").

Currently, Xberg is the only supported parser backend. To enable it, set the parser backend to "xberg" and configure the URL and timeout:

PARSER_BACKEND: "xberg" # Default is "none"
XBERG_URL: "http://xberg-full:8000"
XBERG_TIMEOUT: 120.0

Where:

Transcription Configuration (YAML)

MUCGPT offers browser-based speech-to-text (beta): users can dictate into the chat input, and the audio is transcribed entirely inside their browser. The backend only gates the feature — no audio ever leaves the user’s browser; the resulting transcript is placed in the chat input and can be submitted through the normal chat request. It is disabled by default (TRANSCRIPTION_ENABLED: false).

To enable it, set the flag in core.config.yaml:

TRANSCRIPTION_ENABLED: true # Default is false

Or via environment variable: MUCGPT_CORE_TRANSCRIPTION_ENABLED=true

Optionally, preselect a default model for first-time users:

TRANSCRIPTION_DEFAULT_MODEL: "onnx-community/whisper-small" # Default is null (frontend built-in default)

The id must match an entry of the frontend’s model list (mucgpt-frontend/src/config/transcriptionModels.ts); unknown ids are ignored. The choice applies once — as soon as a user picks a model themselves, it is stored in their browser and later changes to the default do not affect them.

Notes for operators:

Models Configuration (Environment Variable)

Alternatively, models can be configured via the MUCGPT_CORE_MODELS environment variable as a JSON array:

MUCGPT_CORE_MODELS='[
  {
    "type": "OPENAI",
    "llm_name": "<your-llm-name>",
    "endpoint": "<your-endpoint>",
    "api_key": "<your-sk>",
    "model_info": {
      "auto_enrich_from_model_info_endpoint": true,
      "max_output_tokens": "<number>",
      "max_input_tokens": "<number>",
      "description": "<description>"
    }
  }
]'

Configuration Priority

Settings are loaded in this order (highest priority wins):

  1. Init values – constructor kwargs / init_settings
  2. Environment variables – MUCGPT_CORE_* / MUCGPT_ASSISTANT_*, using __ for nested sections
  3. YAML config file – config.yaml mounted into each container
  4. .env file – lowest priority; values here will not override anything set in config.yaml or environment variables

This means environment variables always override YAML values, which is useful for injecting secrets in CI/CD.

Data storage overview

MUCGPT stores data in two layers:

Notes:

Browser storage (frontend)

In addition to backend storage, the frontend uses browser storage for UX state and local history:

Note: Browser storage is client-local and can be cleared by the user/browser.

Environment Variable Override Examples

Any YAML setting can be overridden. Nested sections use __ (double underscore):

# Top-level field
MUCGPT_CORE_VERSION=1.0.0              # → VERSION: "1.0.0"
MUCGPT_CORE_AI_ACT_COMPLIANCE_CHECK_ENABLED=false  # → AI_ACT_COMPLIANCE_CHECK_ENABLED: false

# Nested field (DB section in assistant service)
MUCGPT_ASSISTANT_DB__HOST=postgres      # → DB: { HOST: "postgres" }
MUCGPT_ASSISTANT_DB__PASSWORD=secret    # → DB: { PASSWORD: "secret" }

# Nested field (Redis section in core service)
MUCGPT_CORE_REDIS__HOST=valkey          # → REDIS: { HOST: "valkey" }

# Nested field (Langfuse section)
MUCGPT_CORE_LANGFUSE__SECRET_KEY=sk-... # → LANGFUSE: { SECRET_KEY: "sk-..." }

Top-level fields:

model_info fields:

Replace the placeholder values with your actual model configuration.

LDAP integration

Assistants can be published to specific departments. MUCGPT reads the organization’s department tree from the configured LDAP directory, so published assistants are scoped according to that hierarchy. Configure LDAP in assistant.config.yaml under the LDAP section:

LDAP:
  ENABLED: true
  HOST: "ldaps://ldap.example.de"
  PORT: 636
  USE_SSL: true
  START_TLS: false
  VERIFY_SSL: true
  CA_CERT_FILE: "/path/to/ca-bundle.pem"
  BIND_DN: "cn=mucgpt,ou=Service Accounts,o=Example Org,c=de"
  BIND_PASSWORD: "<secret>"
  SEARCH_BASE: "o=Example Org,c=de"
  SEARCH_FILTER: "(objectClass=organizationalUnit)"
  DISPLAY_ATTRIBUTE: "ou"
  PARENT_ATTRIBUTE: "lhmParentOu" # optional
  ADDITIONAL_ATTRIBUTES: ["lhmOULongname", "lhmOUShortname"]
  REQUIRED_ATTRIBUTES: ["lhmOULongname", "lhmOUShortname"]
  IGNORED_OU_PREFIXES: ["_"]
  IGNORED_OU_SUFFIXES: ["-xxx"]
  IGNORED_OU_SHORTNAME_EXCEPTIONS: ["FBM", "KVR-IT"]
  PAGE_SIZE: 500
  CONNECT_TIMEOUT: 5.0
  READ_TIMEOUT: 10.0

Individual fields can be overridden via environment variables using the MUCGPT_ASSISTANT_LDAP__ prefix:

MUCGPT_ASSISTANT_LDAP__ENABLED=true
MUCGPT_ASSISTANT_LDAP__BIND_PASSWORD=<secret>
MUCGPT_ASSISTANT_LDAP__IGNORED_OU_SHORTNAME_EXCEPTIONS=["FBM","KVR-IT"]

SSO integration

Authentication is performed in front of the services via the refarch API Gateway. MUCGPT only accepts access tokens that contain a specific role and forwards the department claim for authorization checks.

The SSO role is configured in each service’s config.yaml under the SSO section:

SSO:
  ROLE: "lhm-ab-mucgpt-user"

Or via environment variable:

# Core service
MUCGPT_CORE_SSO__ROLE=lhm-ab-mucgpt-user
# Assistant service
MUCGPT_ASSISTANT_SSO__ROLE=lhm-ab-mucgpt-user

MCP (optional)

Besides static tools, MUCGPT allows configuration of MCP sources, for which tools are fetched and can be called.

Configure MCP in core.config.yaml under the MCP section:

MCP:
  SOURCES:
    "<source_id>":
      url: "http://mcpdoc-server:8088/sse"
      forward_token: true
      transport: "sse"
  CACHE_TTL: 43200 # seconds, default: 12h

Or via environment variable:

MUCGPT_CORE_MCP__SOURCES='{"<source_id>": {"url": "...", "forward_token": true, "transport": "sse"}}'
MUCGPT_CORE_MCP__CACHE_TTL=43200

🐋 Run with Docker

See the stack README for complete Docker Compose setup instructions, including:

This site is open source. Improve this page.