ScratchLog+: Live Analytics of Learners’ Exercise Progress

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "whisker-connector"]
+	path = whisker-connector
+	url = git@github.com:se2p/whisker.git
+[submodule "scratch-gui"]
+	path = scratch-gui
+	url = git@github.com:se2p/NuzzleBug.git

checkstyle-suppressions.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE suppressions PUBLIC
+    "-//Puppy Crawl//DTD Suppressions 1.1//EN"
+    "http://checkstyle.sourceforge.net/dtds/suppressions_1_1.dtd">
+
+<suppressions>
+    <!-- JPA repository name magic methods may use underscores -->
+    <suppress
+        checks="MethodName"
+        files=".*Repository.java"
+    />
+</suppressions>

checkstyle.xml

@@ -47,6 +47,11 @@
         <property name="fileNamePattern" value="module\-info\.java$"/>
     </module>
 
+    <module name="SuppressionFilter">
+        <property name="file" value="checkstyle-suppressions.xml"/>
+        <property name="optional" value="false"/>
+    </module>
+
     <!-- Checks whether files end with a new line.                        -->
     <!-- See https://checkstyle.org/config_misc.html#NewlineAtEndOfFile -->
     <module name="NewlineAtEndOfFile"/>

docker-compose.yml

@@ -6,10 +6,17 @@ services:
       dockerfile: Containerfile
     restart: on-failure
     environment:
-      spring.profiles.active: prod
+      spring.profiles.active: embeddings,whisker,prod
       spring.datasource.url: "jdbc:mariadb://database:3306/scratchlog"
       spring.datasource.user: scratchlog
       spring.datasource.password: scratchlog
+      app.gui: http://localhost:8601
+      app.gui.base: http://localhost:8601
+      # TODO: any other options from the properties that should be overriden?
+      code-embeddings.model: llm
+      code-embeddings.embedding-connector-url: http://embedding-connector:8080
+      whisker.base-url: http://whisker:8091
+      whisker.max-parallel: 1
     networks:
       - scratchlog
     ports:
@@ -29,12 +36,43 @@ services:
       MYSQL_PASSWORD: scratchlog
       MYSQL_ROOT_PASSWORD: scratchlog
     volumes:
+      # seed database with some initial data
+      # - scratchlog_demo_db.sql.zst:/docker-entrypoint-initdb.d/init.sql.zst
       - scratchlog-db:/var/lib/mysql
     networks:
       - scratchlog
     ports:
       - "127.0.0.1:3306:3306/tcp"
 
+  scratch-gui:
+    build:
+      context: ./scratch-gui
+      dockerfile: Dockerfile
+    restart: on-failure
+    ports:
+      - "127.0.0.1:8601:80/tcp"
+    networks:
+      - scratchlog
+
+  embedding-connector:
+    build:
+      context: ./embedding-connector
+      dockerfile: Containerfile
+    restart: on-failure
+    env_file:
+      - .env
+    networks:
+      - scratchlog
+
+  whisker:
+    build:
+      context: ./whisker-connector
+      dockerfile: build-for-apptainer.Dockerfile
+      target: api
+    restart: on-failure
+    networks:
+      - scratchlog
+
 volumes:
   scratchlog-db:
 networks:

embedding-connector/.dockerignore

@@ -0,0 +1 @@
+.venv/

embedding-connector/.gitignore

@@ -0,0 +1,5 @@
+.env*
+.idea/
+.vscode/
+__pycache__/
+*.pyc

embedding-connector/.python-version

@@ -0,0 +1 @@
+3.13

embedding-connector/Containerfile

@@ -0,0 +1,27 @@
+FROM docker.io/library/python:3.13-slim AS builder
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+ENV UV_PYTHON_DOWNLOADS=0 UV_LINK_MODE=copy
+
+WORKDIR /app
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project --no-editable
+
+COPY . /app
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-editable
+
+FROM docker.io/library/python:3.13-slim
+
+COPY --from=builder /app/.venv /app/.venv
+
+EXPOSE 8080
+
+ENV MODEL_CONFIG_FILE=/ggnn-model-config.yaml
+
+ENTRYPOINT ["/app/.venv/bin/uvicorn", "embedding_connector.main:app"]
+CMD ["--host", "0.0.0.0", "--port", "8080"]

embedding-connector/Dockerfile

@@ -0,0 +1 @@
+Containerfile

embedding-connector/README.md

@@ -0,0 +1,23 @@
+# Code Embedding Connector
+
+Uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+
+## Starting
+
+```bash
+# install dependencies
+uv sync
+# run the application on port 8080 (add `--port=OTHER` to change the port)
+uv run embedding-connector
+```
+
+
+## Environment variables
+
+- GGNN variables: only required when using the GGNN model
+  - `GGNN_MODEL_CONFIG`: path to a GGNN model configuration YAML
+- LLM variables: only required when using an LLM API endpoint
+  - `LLM_API_ENDPOINT`: base URL for the OpenAI-compatible LLM provider API, e.g. `http://localhost:11434/v1/` for a local Ollama instance
+  - `LLM_API_KEY`: the access key for the LLM provider API
+  - `LLM_MODEL`: the model that should be used

embedding-connector/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "embedding-connector"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Benedikt Fein", email = "fein@fim.uni-passau.de" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi[standard]>=0.136.0",
+    "ggnn>=0.1.0",
+    "numpy>=2.4.4",
+    "openai>=2.34.0",
+    "pydantic>=2.13.2",
+    "torch>=2.10.0,<2.11.0",
+    "uvicorn>=0.44.0",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.20.1",
+    "ruff>=0.15.11",
+]
+
+
+[tool.uv.extra-build-dependencies]
+torch-scatter = ["torch"]
+torch-sparse = ["torch"]
+
+[tool.uv.sources]
+ggnn = [
+    { index = "ggnn" }
+]
+
+[[tool.uv.index]]
+name = "ggnn"
+url = "https://gitlab.infosun.fim.uni-passau.de/api/v4/projects/1040/packages/pypi/simple"
+explicit = true
+
+
+[tool.fastapi]
+entrypoint = "embedding_connector.main:app"
+
+
+[project.scripts]
+embedding-connector = "embedding_connector.main:main"
+
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"

embedding-connector/src/embedding_connector/ggnn_api.py

@@ -0,0 +1,32 @@
+import asyncio
+import functools
+import logging
+from pathlib import Path
+from typing import Final
+
+import numpy
+from ggnn.config import load_config
+from ggnn.program_embedding.train import ProgramEmbeddingTool
+
+log: Final[logging.Logger] = logging.getLogger(__name__)
+
+
+class GgnnApiModel:
+    _lock: asyncio.Lock
+    _embedding_tool: ProgramEmbeddingTool
+
+    def __init__(self, config_file: Path) -> None:
+        self._lock = asyncio.Lock()
+
+        config = load_config(config_file, None, eval_only=True)
+        self._embedding_tool = ProgramEmbeddingTool(config, embedding_per_sprite=True)
+
+    async def embed(self, program: str) -> numpy.typing.NDArray[numpy.float64]:
+        async with self._lock:
+            per_sprite_embeddings = self._compute(program)
+
+        return numpy.mean(per_sprite_embeddings, axis=0)
+
+    @functools.lru_cache(maxsize=5_000)
+    def _compute(self, program: str) -> list[float]:
+        return self._embedding_tool.embedding(program)

embedding-connector/src/embedding_connector/llm_api.py

@@ -0,0 +1,38 @@
+import datetime
+import functools
+import logging
+from timeit import default_timer as timer
+from typing import Final
+
+import numpy
+import openai
+
+_log: Final[logging.Logger] = logging.getLogger(__name__)
+
+
+class LlmApiModel:
+    _client: openai.OpenAI
+    _api_key: str
+    _model: str
+
+    def __init__(self, api_endpoint: str, api_key: str, model: str) -> None:
+        self._client = openai.OpenAI(base_url=api_endpoint, api_key=api_key)
+        self._model = model
+
+    def embed(self, programs: list[str]) -> numpy.typing.NDArray[numpy.float64]:
+        start = timer()
+        batch = self._client.embeddings.create(
+            model=self._model,
+            input=programs,
+        )
+        end = timer()
+        _log.info(
+            "Computed an %s embedding in %s.",
+            self._model,
+            datetime.timedelta(seconds=end - start),
+        )
+        return numpy.stack([e.embedding for e in batch.data])
+
+    @functools.lru_cache(maxsize=5_000)
+    def embed_single(self, program: str) -> numpy.typing.NDArray[numpy.float64]:
+        return self.embed([program])[0]