ait-detectmate · thorinaboenke · Jul 13, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/Dockerfile b/Dockerfile
@@ -2,6 +2,11 @@ FROM python:3.14-slim
 
 WORKDIR /app
 
+# Comma-separated detectmatelibrary extras to install, e.g. "llm,dataframes".
+# Defaults to "full" (all optional components available). Pass an empty
+# string to install only the base library.
+ARG LIBRARY_EXTRAS=full
+
 # Install system dependencies
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
@@ -14,6 +19,10 @@ COPY pyproject.toml README.md ./
 COPY ./src ./src
 COPY ./tests ./tests
 
-RUN uv pip install --system .
+RUN if [ -n "$LIBRARY_EXTRAS" ]; then \
+    uv pip install --system ".[$LIBRARY_EXTRAS]" ; \
+    else \
+    uv pip install --system . ; \
+    fi
 
 CMD ["detectmate", "--help"]
diff --git a/Dockerfile-dev b/Dockerfile-dev
@@ -3,6 +3,11 @@ FROM python:3.14-slim
 WORKDIR /app
 ARG DETECTMATELIBRARY_BRANCH=development
 
+# Comma-separated detectmatelibrary extras to install, e.g. "llm,dataframes".
+# Defaults to "full" (all optional components available). Pass an empty
+# string to install only the base library.
+ARG LIBRARY_EXTRAS=full
+
 # Install system dependencies
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
@@ -15,11 +20,19 @@ COPY pyproject.toml README.md ./
 COPY ./src ./src
 COPY ./tests ./tests
 
-RUN uv pip install --system .
+RUN if [ -n "$LIBRARY_EXTRAS" ]; then \
+    uv pip install --system ".[$LIBRARY_EXTRAS]" ; \
+    else \
+    uv pip install --system . ; \
+    fi
 
 RUN if [ "$DETECTMATELIBRARY_BRANCH" != "main" ]; then \
     uv pip uninstall --system detectmatelibrary && \
+    if [ -n "$LIBRARY_EXTRAS" ]; then \
+    uv pip install --system "detectmatelibrary[$LIBRARY_EXTRAS] @ git+https://github.com/ait-detectmate/DetectMateLibrary.git@$DETECTMATELIBRARY_BRANCH" ; \
+    else \
     uv pip install --system "detectmatelibrary @ git+https://github.com/ait-detectmate/DetectMateLibrary.git@$DETECTMATELIBRARY_BRANCH" ; \
+    fi ; \
 fi
 
 CMD ["detectmate", "--help"]
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,104 +1,111 @@
 # version: "3"
 
 services:
-  fluentin:
-    #image: dm-fluentd:latest
-    build:
-      context: .
-      dockerfile: container/Dockerfile_fluentd
-    volumes:
-      - '$PWD/container/fluentin:/fluentd/etc'
-      - '/var/log/nginx:/fluentd/log'
-      - '$PWD/container/run:/run'
-    depends_on:
-      - parser
-  parser:
-    # image: detectmate:dev-0.1.6
-    build: .
-    volumes:
-      - '$PWD/container/config:/config'
-      - '$PWD/container/logs:/logs'
-      - '$PWD/container/run:/run'
-    command: uv run detectmate --settings /config/parser_settings.yaml --config /config/parser_config.yaml
-    ports:
-      - "8001:8000"
-    depends_on:
-      - detector
+    fluentin:
+      #image: dm-fluentd:latest
+      build:
+        context: .
+        dockerfile: container/Dockerfile_fluentd
+      volumes:
+        - '$PWD/container/fluentin:/fluentd/etc'
+        - '/var/log/nginx:/fluentd/log'
+        - '$PWD/container/run:/run'
+      depends_on:
+        - parser
+    parser:
+      # image: detectmate:dev-0.1.6
+      build:
+        context: .
+        args:
+          LIBRARY_EXTRAS: ${LIBRARY_EXTRAS:-full}
+      volumes:
+        - '$PWD/container/config:/config'
+        - '$PWD/container/logs:/logs'
+        - '$PWD/container/run:/run'
+      command: uv run detectmate --settings /config/parser_settings.yaml --config /config/parser_config.yaml
+      ports:
+        - "8001:8000"
+      depends_on:
+        - detector
 
-  detector:
-    # image: detectmate:dev-0.1.6
-    build: .
-    volumes:
-      - '$PWD/container/config:/config'
-      - '$PWD/container/logs:/logs'
-      - '$PWD/container/run:/run'
-      - '$PWD/container/state:/state'
-    command: uv run detectmate --settings /config/detector_settings.yaml --config /config/detector_config.yaml
-    ports:
-      - "8002:8000"
-    depends_on:
-      - fluentout
+    detector:
+      # image: detectmate:dev-0.1.6
+      build:
+        context: .
+        args:
+          LIBRARY_EXTRAS: ${LIBRARY_EXTRAS:-full}
+      volumes:
+        - '$PWD/container/config:/config'
+        - '$PWD/container/logs:/logs'
+        - '$PWD/container/run:/run'
+        - '$PWD/container/state:/state'
+      command: uv run detectmate --settings /config/detector_settings.yaml --config /config/detector_config.yaml
+      ports:
+        - "8002:8000"
+      depends_on:
+        - fluentout
 
-  fluentout:
-    # image: dm-fluentd:latest
-    build:
-      context: .
-      dockerfile: container/Dockerfile_fluentd
-    volumes:
-      - '$PWD/container/fluentout:/fluentd/etc'
-      - '$PWD/container/fluentlogs:/fluentd/log'
-      - '$PWD/container/run:/run'
+    fluentout:
+      # image: dm-fluentd:latest
+      build:
+        context: .
+        dockerfile: container/Dockerfile_fluentd
+      volumes:
+        - '$PWD/container/fluentout:/fluentd/etc'
+        - '$PWD/container/fluentlogs:/fluentd/log'
+        - '$PWD/container/run:/run'
 
-  prometheus:
-    image: prom/prometheus:latest
-    container_name: prometheus
-    restart: unless-stopped
-    volumes:
-      - ./container/prometheus.yml:/etc/prometheus/prometheus.yml
-      - prometheus_data:/prometheus
-    command:
-      - '--config.file=/etc/prometheus/prometheus.yml'
-      - '--storage.tsdb.path=/prometheus'
-      - '--web.console.libraries=/etc/prometheus/console_libraries'
-      - '--web.console.templates=/etc/prometheus/consoles'
-      - '--web.enable-lifecycle'
-    expose:
-      - 9090
+    prometheus:
+      image: prom/prometheus:latest
+      container_name: prometheus
+      restart: unless-stopped
+      volumes:
+        - ./container/prometheus.yml:/etc/prometheus/prometheus.yml
+        - prometheus_data:/prometheus
+      command:
+        - '--config.file=/etc/prometheus/prometheus.yml'
+        - '--storage.tsdb.path=/prometheus'
+        - '--web.console.libraries=/etc/prometheus/console_libraries'
+        - '--web.console.templates=/etc/prometheus/consoles'
+        - '--web.enable-lifecycle'
+      expose:
+        - 9090
 
-  grafana:
-    image: grafana/grafana:latest
-    container_name: grafana
-    ports:
-      - "3000:3000"
-    environment:
-      - GF_SECURITY_ADMIN_PASSWORD=admin
-    depends_on:
-      - prometheus
-    volumes:
-      - ./container/grafana/prometheus.yml:/etc/grafana/provisioning/datasources/prometheus.yml
-      - ./container/grafana/provisioning/dashboards/dashboards.yml:/etc/grafana/provisioning/dashboards/dashboards.yml
-      - ./container/grafana/dashboards:/var/lib/grafana/dashboards
-      - grafana_data:/var/lib/grafana
-        #    kafka:
-        #      image: apache/kafka-native
-        #      ports:
-        #        - "9092:9092"
-        #      environment:
-        #        KAFKA_LISTENERS: CONTROLLER://localhost:9091,HOST://0.0.0.0:9092,DOCKER://0.0.0.0:9093
-        #        KAFKA_ADVERTISED_LISTENERS: DOCKER://kafka:9093,HOST://kafka:9092
-        #        KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,DOCKER:PLAINTEXT,HOST:PLAINTEXT
-        #
-        #        # Settings required for KRaft mode
-        #        KAFKA_NODE_ID: 1
-        #        KAFKA_PROCESS_ROLES: broker,controller
-        #        KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
-        #        KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9091
-        #
-        #        # Listener to use for broker-to-broker communication
-        #        KAFKA_INTER_BROKER_LISTENER_NAME: DOCKER
-        #
-        #        # Required for a single node cluster
-        #        KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
+    grafana:
+      image: grafana/grafana:latest
+      container_name: grafana
+      ports:
+        - "3000:3000"
+      environment:
+        - GF_SECURITY_ADMIN_PASSWORD=admin
+      depends_on:
+        - prometheus
+      volumes:
+        - ./container/grafana/prometheus.yml:/etc/grafana/provisioning/datasources/prometheus.yml
+        - ./container/grafana/provisioning/dashboards/dashboards.yml:/etc/grafana/provisioning/dashboards/dashboards.yml
+        - ./container/grafana/dashboards:/var/lib/grafana/dashboards
+        - grafana_data:/var/lib/grafana
+
+          #    kafka:
+          #      image: apache/kafka-native
+          #      ports:
+          #        - "9092:9092"
+          #      environment:
+          #        KAFKA_LISTENERS: CONTROLLER://localhost:9091,HOST://0.0.0.0:9092,DOCKER://0.0.0.0:9093
+          #        KAFKA_ADVERTISED_LISTENERS: DOCKER://kafka:9093,HOST://kafka:9092
+          #        KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,DOCKER:PLAINTEXT,HOST:PLAINTEXT
+          #
+          #        # Settings required for KRaft mode
+          #        KAFKA_NODE_ID: 1
+          #        KAFKA_PROCESS_ROLES: broker,controller
+          #        KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
+          #        KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9091
+          #
+          #        # Listener to use for broker-to-broker communication
+          #        KAFKA_INTER_BROKER_LISTENER_NAME: DOCKER
+          #
+          #        # Required for a single node cluster
+          #        KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
 
 volumes:
   prometheus_data:

diff --git a/docs/development.md b/docs/development.md
@@ -41,3 +41,20 @@ In oder to run the tests run the following command:
 ```bash
 uv run --dev pytest
 ```
+
+## Updating the DetectMateLibrary version
+
+[DetectMateLibrary](https://github.com/ait-detectmate/DetectMateLibrary) ships optional
+extras (`llm`, `dataframes`, `polars-rtcompat`) that the service passes through in
+`pyproject.toml`. The version is pinned in exactly **one place** — the base
+`detectmatelibrary==X.Y.Z` entry in `dependencies`. The `llm`/`dataframes`/
+`polars-rtcompat` extras deliberately reference `detectmatelibrary[extra]` with no
+version of their own; since it's the same package name, uv/pip unify them onto
+whatever version the base pin specifies. When bumping the library version:
+
+1. Update the single `detectmatelibrary==X.Y.Z` pin in `pyproject.toml`.
+2. Run `uv lock` to regenerate `uv.lock`.
+3. Run `uv sync --extra full && uv run --dev pytest` to confirm every extra still resolves and installs correctly.
+
+`Dockerfile`, `Dockerfile-dev`, and `scripts/change_toml.sh` don't hardcode the
+library version either, so they don't need touching for a version bump.
diff --git a/docs/installation.md b/docs/installation.md
@@ -31,5 +31,52 @@ source .venv/bin/activate
 pip install .
 ```
 
+## Optional library components (extras)
 
+[DetectMateLibrary](https://github.com/ait-detectmate/DetectMateLibrary) ships some
+components (e.g. LLM-backed detectors, dataframe-based persistency backends) as
+optional extras rather than hard dependencies, to keep lean installs lean. The
+service exposes matching pass-through extras so you only pull in what your
+configured components actually need:
+
+| Extra              | Adds                                    | Needed for |
+|---------------------|------------------------------------------|------------|
+| `llm`               | `openai`, `tiktoken`, `scikit-learn`, `scipy`, `tenacity` | LLM-backed detectors/parsers |
+| `dataframes`        | `pandas`, `polars`                        | Dataframe-based persistency backends and components |
+| `polars-rtcompat`   | `polars[rtcompat]`                        | Polars runtime compatibility on older CPUs |
+| `full`              | all of the above                          | Running any/all library components, e.g. local development |
+
+Install only what you need:
+
+```bash
+uv sync --extra llm
+# or with pip
+pip install ".[llm]"
+```
+
+Or install everything:
+
+```bash
+uv sync --extra full
+```
+
+`uv sync --dev` (used for local development, see [development.md](development.md))
+already installs the `full` extra via the `dev` dependency group, so
+contributors get every optional component out of the box.
+
+### Extras in Docker
+
+`Dockerfile` and `Dockerfile-dev` take a `LIBRARY_EXTRAS` build arg (comma-separated
+extras, default `full`) that controls which extras get installed in the image:
+
+```bash
+docker build --build-arg LIBRARY_EXTRAS=llm,dataframes -t detectmate .
+```
+
+With `docker compose`, set the `LIBRARY_EXTRAS` env var before building (it defaults
+to `full` if unset):
+
+```bash
+LIBRARY_EXTRAS=llm docker compose build parser detector
+```
 
diff --git a/docs/library.md b/docs/library.md
@@ -5,6 +5,13 @@
 The Service can be run as any component imported from the [DetectMateLibrary](https://github.com/ait-detectmate/DetectMateLibrary).
 For this, ensure that the library is installed in the same activated virtual environment, where the service is installed.
 
+> **Note:** Some library components depend on optional extras (e.g. LLM-backed
+> detectors need `llm`, dataframe-based persistency backends need `dataframes`).
+> If the component you want to use raises an `ImportError` mentioning a missing
+> extra, install the service with the matching extra — see
+> [Optional library components](installation.md#optional-library-components-extras)
+> in the installation guide.
+
 ### 1. Update settings
 
 Modify `settings.yaml` to use a library component:

diff --git a/docs/release.md b/docs/release.md
@@ -29,7 +29,8 @@ Open a pull request to merge the `development` branch into `main`. Once CI passe
 
 !!! note
 
-    Merging `development` into `main` will delete the `development` branch. See the last step for how to recreate it.
+    Merging `development` into `main` will delete the `development` branch. A GitHub Actions
+    workflow (`recreate-development-branch.yml`) automatically recreates it from `main`, see the last step for details and the manual fallback.
 
 ### 3. Determine the new version number
 
@@ -79,7 +80,13 @@ Monitor the [Actions tab](https://github.com/ait-detectmate/DetectMateService/ac
 
 ### 7. Recreate the development branch
 
-Because merging `development` into `main` deletes the `development` branch, create a new one branching from the now-updated `main`:
+Because merging `development` into `main` deletes the `development` branch, it needs to be
+recreated from the now-updated `main`. This happens automatically: `.github/workflows/recreate-development-branch.yml`
+listens for the branch deletion and pushes a new `development` branch from `main` for you.
+Check the [Actions tab](https://github.com/ait-detectmate/DetectMateService/actions) to confirm
+it ran successfully.
+
+If the workflow fails or you need to do it manually:
 
 ```bash
 git checkout main