diff --git a/README.md b/README.md index c07e7ee..13e7a38 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,15 @@ # Wolfram Language Evaluation Function -This repository contains the boilerplate code needed to create a containerized evaluation function written in Wolfram Language. +This repository contains an implementation of a Wolfram evaluation function that checks if the structure, numeric value or any other value are equal. -## Quickstart -This chapter helps you to quickly set up a new Wolfram evaluation function using this template repository. - -> [!NOTE] -> After setting up the evaluation function, delete this chapter from the `README.md` file, and add your own documentation. - -#### 1. Create a new repository - -- In GitHub, choose `Use this template` > `Create a new repository` in the repository toolbar. - -- Choose the owner, and pick a name for the new repository. - - > [!IMPORTANT] - > If you want to deploy the evaluation function to Lambda Feedback, make sure to choose the Lambda Feedback organization as the owner. - -- Set the visibility to `Public` or `Private`. - - > [!IMPORTANT] - > If you want to use GitHub [deployment protection rules](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules), make sure to set the visibility to `Public`. - -- Click on `Create repository`. - -#### 2. Clone the new repository - -Clone the new repository to your local machine using the following command: - -```bash -git clone -``` - -#### 3. Configure the evaluation function - -When deploying to Lambda Feedback, set the evaluation function name in the `config.json` file. Read the [Deploy to Lambda Feedback](#deploy-to-lambda-feedback) section for more information. - -#### 4. Develop the evaluation function - -You're ready to start developing your evaluation function. Head over to the [Development](#development) section to learn more. - -#### 5. Update the README - -In the `README.md` file, change the title and description so it fits the purpose of your evaluation function. - -Also, don't forget to delete the Quickstart chapter from the `README.md` file after you've completed these steps. - -## Usage - -You can run the evaluation function either using [the pre-built Docker image](#run-the-docker-image) or build and run [the binary executable](#build-and-run-the-binary). - -### Run the Docker Image - -The pre-built Docker image comes with [Shimmy](https://github.com/lambda-feedback/shimmy) installed. - -> [!TIP] -> Shimmy is a small application that listens for incoming HTTP requests, validates the incoming data and forwards it to the underlying evaluation function. Learn more about Shimmy in the [Documentation](https://github.com/lambda-feedback/shimmy). - -The pre-built Docker image is available on the GitHub Container Registry. You can run the image using the following command: - -```bash -docker run -p 8080:8080 ghcr.io/lambda-feedback/evaluation-function-boilerplate-wolfram:latest -``` +## Development ### Run the Script You can choose between running the Wolfram evaluation function itself, ore using Shimmy to run the function. -**Raw Mode** +**Local** Use the following command to run the evaluation function directly: @@ -77,18 +18,36 @@ wolframscript -f evaluation_function.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: -**Shimmy** - -To have a more user-friendly experience, you can use [Shimmy](https://github.com/lambda-feedback/shimmy) to run the evaluation function. +``` +{ + "method": "eval", + "params": { + "answer":"Sin[p x + q]", + "response":"Sin[a x + b]", + "params":{ + "comparisonType":"structure", + "named_variables":"{x}", + "correct_response_feedback":"Your answer is correct!", + "incorrect_response_feedback":"Your answer is incorrect!" + } + } +} +``` -To run the evaluation function using Shimmy, use the following command: +Which gives the response: -```bash -shimmy -c "wolframscript" -a "-f" -a "evaluation_function.wl" -i file ``` - -## Development +{ + "command": "eval", + "result": { + "is_correct": true, + "feedback": "Your answer is correct!", + "error": null + } +} +``` ### Prerequisites @@ -126,9 +85,44 @@ wolframscript -f evaluation_function.wl request.json response.json To build the Docker image, run the following command: ```bash -docker build -t my-wolfram-evaluation-function . +docker build -t wolfram-evaluation-function . ``` +### Running the Docker Image +To run the Docker image, you will need to mount a mathpass licence or pass an entitlement ID. To get these see [Licencing](#Wolfram-Engine-License +). + +To run using mathpass development licence (this assumes that the mathpass file is in your local working directory: +```bash +docker run -it --rm -v $(pwd)/mathpass:/home/wolframengine/.WolframEngine/Licensing/mathpass wolfram-evaluation-function +``` + +To run using the entitlement key: +```bash +docker run -it --rm -env WOLFRAMSCRIPT_ENTITLEMENTID=[YOUR_ENTITLEMENT_ID] wolfram-evaluation-function +``` + +### Sending requests to the image +We recommend sending requests to your image using [Postman](https://www.postman.com/), an easy to use interface for sending API requests. + +If you prefer to use `curl` here is an example request: +```bash +curl --location 'http://localhost:8080/wolframEvaluationFunction' \ +--header 'Content-Type: application/json' \ +--header 'command: eval' \ +--data '{ + "answer": 1, + "response": 1.02, + "params": { + "tolerance": 0.01, + "tolerance_is_absolute": true, + "correct_response_feedback": "Correct!", + "incorrect_response_feedback": "Try again." + } +} +``` + + ## Deployment This section guides you through the deployment process of the evaluation function. If you want to deploy the evaluation function to Lambda Feedback, follow the steps in the [Lambda Feedback](#deploy-to-lambda-feedback) section. Otherwise, you can deploy the evaluation function to other platforms using the [Other Platforms](#deploy-to-other-platforms) section.