Merge pull request #12 from lambda-feedback/refactor_to_toolkit

Move shared request/response handling into toolkit-wolfram

Author: m-messer

.gitignore

@@ -1 +1,5 @@
-mathpass
+mathpass
+
+# Local, non-Docker dev checkout of toolkit-wolfram -- see
+# scripts/setup-toolkit.sh and .toolkit-wolfram-version.
+/toolkit-wolfram/

Dockerfile

@@ -1,17 +1,21 @@
 FROM ghcr.io/lambda-feedback/evaluation-function-base/wolfram:latest as base
 
-# Command to start the evaluation function with
-ENV FUNCTION_COMMAND="wolframscript"
-
-# Args to start the evaluation function with
-ENV FUNCTION_ARGS="-f,/app/evaluation_function.wl"
-
 # Interface to use for the evaluation function
-ENV FUNCTION_INTERFACE="file"
+ENV FUNCTION_INTERFACE="rpc"
+ENV FUNCTION_RPC_TRANSPORT="tcp"
+ENV FUNCTION_WORKER_START_TIMEOUT="60s"
 
 ENV LOG_LEVEL="DEBUG"
 
-# Copy the evaluation function to the app directory
-COPY ./evaluation_function.wl /app/evaluation_function.wl
+# The shared Wolfram evaluation-function toolkit (JSON comms layer) is
+# installed in the base image -- see evaluation-function-base/wolfram/Dockerfile.
+#
+# Optional local-dev override: run scripts/sync-local-toolkit.sh to populate
+# ./.local-toolkit from a local toolkit-wolfram checkout before building, to
+# test unreleased toolkit-wolfram changes here. Left empty (the default,
+# tracked via .local-toolkit/.gitkeep), this COPY is a no-op and the image
+# keeps using the toolkit-wolfram version pinned in the base image.
+#COPY ./.local-toolkit /opt/lambda-feedback/toolkit-wolfram
+
 COPY ./evaluate.m /app/evaluate.m
 COPY ./preview.m /app/preview.m

README.md

@@ -10,25 +10,37 @@ This repository contains an implementation of a Wolfram evaluation function that
 
 You can choose between running the Wolfram evaluation function itself, ore using Shimmy to run the function.
 
+This repository's JSON comms (reading the request, dispatching `eval`/`preview`, writing the response) come from the shared [`toolkit-wolfram`](https://github.com/lambda-feedback/toolkit-wolfram) paclet (`LambdaFeedback/EvaluationFunctionToolkit`) rather than being implemented in this repo — `evaluate.m`/`preview.m` here just provide `EvaluationFunction`/`PreviewFunction`, and the toolkit's `Bootstrap.wl` wires everything together (it's what the Docker image's Shimmy setup runs). To run locally, fetch the pinned toolkit version (see `.toolkit-wolfram-version`) with:
+
+```bash
+scripts/setup-toolkit.sh
+```
+
+This clones it into `./toolkit-wolfram` (gitignored; re-run any time to reset it). Then point `LF_TOOLKIT_PATH` at it:
+
+```bash
+export LF_TOOLKIT_PATH=./toolkit-wolfram
+```
+
 **Local**
 
 Use the following command to run the evaluation function directly:
 
 ```bash
-wolframscript -f evaluation_function.wl request.json response.json
+wolframscript -f ./toolkit-wolfram/Bootstrap.wl request.json response.json
 ```
 
 This will run the evaluation function using the input data from `request.json` and write the output to `response.json`.
 An example `request.json` is:
 
 ```
 {
-  "method": "eval",
+  "command": "eval",
   "params": {
     "answer":"Sin[p x + q]",
 	"response":"Sin[a x + b]",
 	"params":{
-		"comparisonType":"structure",
+		"type":"structure",
 		"named_variables":"{x}",
 		"correct_response_feedback":"Your answer is correct!",
 		"incorrect_response_feedback":"Your answer is incorrect!"
@@ -44,8 +56,7 @@ Which gives the response:
   "command": "eval",
   "result": {
     "is_correct": true,
-    "feedback": "Your answer is correct!",
-    "error": null
+    "feedback": "Your answer is correct!"
   }
 }
 ```
@@ -63,19 +74,20 @@ Which gives the response:
     build.yml          # builds the public evaluation function image
     deploy.yml         # deploys the evaluation function to Lambda Feedback
 
-evaluation_function.wl # evaluation function source code
+evaluate.m              # EvaluationFunction source code
+preview.m               # PreviewFunction source code
 
-config.json            # evaluation function deployment configuration file
+config.json             # evaluation function deployment configuration file
 ```
 
 ### Development Workflow
 
-In its most basic form, the development workflow consists of writing the evaluation function in the `evaluation_function.wl` file and testing it locally. As long as the evaluation function adheres to the Evaluation Function API, a development workflow which incorporates using Shimmy is not necessary.
+In its most basic form, the development workflow consists of writing the evaluation function in `evaluate.m`/`preview.m` and testing it locally. As long as the evaluation function adheres to the Evaluation Function API, a development workflow which incorporates using Shimmy is not necessary.
 
-Testing the evaluation function can be done by running the script using the Wolfram Engine / WolframScript like so:
+Testing the evaluation function can be done by running the script using the Wolfram Engine / WolframScript like so (see [Run the Script](#run-the-script) above for the one-time `scripts/setup-toolkit.sh`/`LF_TOOLKIT_PATH` setup this depends on):
 
 ```bash
-wolframscript -f evaluation_function.wl request.json response.json
+wolframscript -f ./toolkit-wolfram/Bootstrap.wl request.json response.json
 ```
 
 > [!NOTE]
@@ -115,7 +127,7 @@ curl --location 'http://localhost:8080/wolframEvaluationFunction' \
 	"answer":"Sin[p x + q]",
 	"response":"Sin[a x + b]",
 	"params":{
-		"comparisonType":"structure",
+		"type":"structure",
 		"named_variables":"{x}",
 		"correct_response_feedback":"Your answer is correct!",
 		"incorrect_response_feedback":"Your answer is incorrect!"

evaluate.m

@@ -18,7 +18,8 @@
 (* Declare package context *)
 BeginPackage["evaluate`"];
 
-EvaluationFunction[type_, answer_, response_, params_] := Module[{result, feedback},
+EvaluationFunction[answer_, response_, params_] := Module[{result, feedback, type},
+  type = params["type"];
   Print["Running Evaluation Function"];
   result = evalQ[type, answer, response, params];
   feedback = If[result["is_correct"],
@@ -35,15 +36,15 @@
 
 Begin["`Private`"];
 
-equalQNumeric[answer_, response_, params_] := Module[{tolerance},
+equalQNumeric[answer_, response_, params_] := Module[{tolerance, error},
   Print["Evaluating Equal Numeric"];
   tolerance = If[Lookup[params, "tolerance_is_absolute", False],
     Lookup[params, "tolerance", 0],
     Lookup[params, "tolerance", 0] * answer
   ];
   error = Abs[answer - response];
   <|
-    "error" -> error,
+    "error" -> Null,
     "is_correct" -> TrueQ[error <= tolerance]
   |>
 ]

evaluation_function.wl

@@ -18,7 +18,7 @@
 (* Declare package context *)
 BeginPackage["preview`"];
 
-PreviewFunction[response_] := Module[{latexString, wolframString, parsedResponse},
+PreviewFunction[response_, params_] := Module[{latexString, wolframString, parsedResponse},
   Print["Running Preview Function"];
   Print["Preview Input:", response];
 

preview.m

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Fetches the pinned toolkit-wolfram version (see .toolkit-wolfram-version)
+# into ./toolkit-wolfram, for running/testing this evaluation function
+# locally without Docker/podman. Re-run any time to reset to the pinned
+# version (e.g. after bumping .toolkit-wolfram-version).
+#
+# Usage:
+#   scripts/setup-toolkit.sh
+#
+# Then, to run the evaluation function directly:
+#   export LF_TOOLKIT_PATH=./toolkit-wolfram
+#   wolframscript -f ./toolkit-wolfram/Bootstrap.wl request.json response.json
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+VERSION=$(cat .toolkit-wolfram-version)
+DEST="toolkit-wolfram"
+
+rm -rf "$DEST"
+git clone --branch "$VERSION" --depth 1 \
+  https://github.com/lambda-feedback/toolkit-wolfram.git "$DEST"
+
+echo "Fetched toolkit-wolfram $VERSION -> $DEST"