Moves lib code and adds general documentation.

Author: wilkie

API.md

@@ -0,0 +1,51 @@
+# API
+
+`GET /`: The root serves as a quick status check.
+
+`GET /test`: Will respond with some kind of successful JSON response.
+
+`GET /openai/models`: Will report back information about the available OpenAI models.
+
+`GET /test/openai`: Will issue a small test prompt to OpenAI's ChatGPT.
+
+* `model`: The model to use. Default: `gpt-3.5-turbo`
+* `api-key`: The API key associated with the model.
+
+`POST /assessment`: Issue a rubric assessment to the AI agent and wait for a response.
+
+* `model`: The model to use. Default: `gpt-4`
+* `api-key`: The API key associated with the model. Default: the configured key
+* `code`: The code to assess. Required.
+* `prompt`: The system prompt. Required.
+* `rubric`: The rubric, as a CSV. Required.
+* `remove-comments`: When `1`, attempts to strip comments out of the code before assessment. Default: 0
+* `num-responses`: The number of times it should ask the AI model. It votes on the final answer. Default: 1
+* `num-passing-grades`: The number of grades to consider 'passing'. Defaults: 2 (pass fail)
+* `temperature`: The 'temperature' value for ChatGPT LLMs.
+
+* **Response**: `application/json`: A list of key concepts, assessment values, and reasons. Example below.
+
+```
+[{
+  "Key Concept": "Program Development 2",
+  "Observations": "The program uses whitespace  good nami [... snipped for brevity ...]. The code is easily readable.",
+  "Grade": "Extensive Evidence",
+  "Reason": "The program code effectively uses whitespace, good naming conventions, indentation and comments to make the code easily readable."
+}, {
+  "Key Concept": "Algorithms and Control Structures",
+  "Observations": "Sprite interactions occur at lines 48-50 (player touches burger), 52 (sw[... snipped for brevity ...]",
+  "Grade": "Extensive Evidence",
+  "Reason": "The game includes multiple different interactions between sprites, responds to multiple types of user input (e.g. different arrow keys)."
+}]
+```
+
+`(GET|POST) /test/assessment`: Issue a test rubric assessment to the AI agent and wait for a response.
+
+* `model`: The model to use. Default: `gpt-4`
+* `api-key`: The API key associated with the model. Default: the configured key
+* `remove-comments`: When `1`, attempts to strip comments out of the code before assessment. Default: 0
+* `num-responses`: The number of times it should ask the AI model. It votes on the final answer. Default: 1
+* `num-passing-grades`: The number of grades to consider 'passing'. Defaults: 2 (pass fail)
+* `temperature`: The 'temperature' value for ChatGPT LLMs.
+
+* **Response**: `application/json`: A list of key concepts, assessment values, and reasons. See above.

README.md

@@ -11,12 +11,42 @@ To Do:
 * [ ] create [application cloudformation template](cicd/3-app/aiproxy/template.yml)
 * [ ] authentication
 
+## Configuration
+
+The configuration is done via environment variables stored in the `config.txt` file.
+
+For local development, copy the `config.txt.sample` file to `config.txt` to have a
+starting point. Then set the `OPENAI_API_KEY` variable to a valid OpenAI API key to
+enable that service. Or, otherwise set that variable the appropriate way when
+deploying the service.
+
 ## Local Development
 
-The Python app exists within "/src"
+All of our server code is written using [Flask](https://flask.palletsprojects.com/en/2.3.x/).
+
+The Flask web service exists within "`/src`". The `__init__.py` is the
+entry point for the app. The other files provide the routes.
+
+Other related Python code that implement features are within "`/lib`".
+
+To build the app, use `docker compose build`.
+You will need to rebuild when you change the source.
 
 To run the app locally, use `docker compose up` from the repo root.
 
+This will run a webserver accessible at [[http://localhost:5000]].
+
+**Note**: You need to provide the API keys in the `config.txt` file
+before the service runs. See the above "Configuration" section.
+
+## API
+
+For information about the API, see the [API documentation](API.md).
+
+## Testing
+
+For information about testing the service, see the [Testing documentation](TESTING.md).
+
 ## CICD
 
 See [CICD Readme](./cicd/README.md)

TESTING.md

@@ -0,0 +1,21 @@
+# Testing
+
+You can issue a "test" rubric assessment using hard-coded content that is found in the
+`test/data` path by using the `/test/assessment` URL. Here, I'm using `curl` to show
+me the headers and send a `POST` to that route (assuming I have the server running):
+
+```
+curl localhost:8080/test/assessment -i --header "Content-Type:multipart/form-data" --form "num-responses=3"
+```
+
+This gives me this response:
+
+```
+HTTP/1.1 200 OK
+Content-Length: 2123
+Content-Type: text/html; charset=utf-8
+Date: Wed, 27 Sep 2023 10:48:36 GMT
+Server: waitress
+
+[{"Key Concept": "Program Development 2", "Observations": "The program uses whitespace (e.g., lines 19, 23, 27, 31, 35, 39, 43, 47, 51, 55, 59, 63), good naming conventions (e.g., \"player\", \"burger\", \"sword\", \"sword2\"), indentation (e.g., lines 20-22, 24-26, 28-30, 32-34, 36-38, 40-42, 44-46, 48-50, 52-54, 56-58, 60-62), and comments (e.g., lines 2, 16, 18, 22, 26, 30, 34, 38, 42, 46, 50, 54, 58, 62). The code is easily readable.", "Grade": "Extensive Evidence", "Reason": "The program code effectively uses whitespace, good naming conventions, indentation and comments to make the code easily readable."}, {"Key Concept": "Algorithms and Control Structures", "Observations": "Sprite interactions occur at lines 48-50 (player touches burger), 52 (sword displaces player), and 53 (sword2 displaces player). The program responds to user input at lines 24-26 (up key), 28-30 (left key), and 32-34 (right key).", "Grade": "Extensive Evidence", "Reason": "The game includes multiple different interactions between sprites, responds to multiple types of user input (e.g. different arrow keys)."}, {"Key Concept": "Position and Movement", "Observations": "The program generates movement at lines 14 (sword), 15 (sword2), 20 (player falling), 24-26 (player moving up), 28-30 (player moving left), 32-34 (player moving right). The movement involves acceleration at lines 20, 24-26, 28-30, 32-34.", "Grade": "Extensive Evidence", "Reason": "Complex movement such as acceleration, moving in a curve, or jumping is included in multiple places in the program."}, {"Key Concept": "Variables", "Observations": "The program updates sprite properties inside the draw loop at lines 20 (player.velocityY), 24-26 (player.velocityY), 28-30 (player.velocityX), 32-34 (player.velocityX), 48-50 (burger.x, burger.y). These updates affect the user's experience of playing the game by controlling the player's movement and the burger's position.", "Grade": "Extensive Evidence", "Reason": "The game includes multiple variables or sprite properties that are updated during the game and affect the user's experience of playing the game."}]
+```

lib/assessment/__init__.py

@@ -7,7 +7,7 @@
 import openai
 
 # Our assessment code
-from lib import assess
+from lib.assessment import assess
 
 assessment_routes = Blueprint('assessment_routes', __name__)