openai-cookbook/examples/chatgpt/gpt_actions_library/gpt_action_canvaslms.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GPT Action Library: Canvas LMS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This page provides an instruction & guide for developers building a GPT Action for a specific application. Before you proceed, make sure to first familiarize yourself with the following information: \n",
    "- [Introduction to GPT Actions](https://platform.openai.com/docs/actions)\n",
    "- [Introduction to GPT Actions Library](https://platform.openai.com/docs/actions/actions-library)\n",
    "- [Example of Buliding a GPT Action from Scratch](https://platform.openai.com/docs/actions/getting-started)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This particular GPT Action provides an overview of how to connect to Canvas (infrastructure.canvas.com), a widely used LMS tool for course material, grading and general education purposes. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "### Value + Example Business Use Cases"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Value**: Users can now leverage ChatGPT's natural language capability to connect directly to Canvas\n",
    "\n",
    "**Example Use Cases**:\n",
    "- Query content from LMS \n",
    "- Build quizzes\n",
    "- Create new modules\n",
    "- Understand topics from assigned courses"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Application Information"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Application Key Links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check out these links from the application before you get started:\n",
    "- Application Website: https://canvas.instructure.com/login/canvas \n",
    "- Application API Documentation: https://canvas.instructure.com/doc/api/\n",
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Application Prerequisites"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before you get started, make sure you go through the following steps in your application environment:\n",
    "- Ensure you have the access and permissions in Canvas to create an approved integration with an Access Token for testing\n",
    "- For OAuth connection see here : https://canvas.instructure.com/doc/api/file.oauth.html\n",
    "\n",
    "\n",
    "![gptactions_canvaslms_approvedintegrations.png](../../../images/gptactions_canvaslms_approvedintegrations.png)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ChatGPT Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Custom GPT Instructions "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you've created a Custom GPT, copy the text below in the Instructions panel. Have questions? Check out [Getting Started Example](https://platform.openai.com/docs/actions/getting-started) to see how this step works in more detail."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "outputs": [],
   "source": [
    "**Context** : You are a helpful friendly university level course helper designed to search across canvas courses to help students and educators, this GPT is intended to help students and teachers understand course material, take quiz's and tests from information stored in canvas.  \n",
    "\n",
    "\n",
    "**Instructions**\n",
    "When asked to perform a task, use the available actions via the canvas.infrastructure.com API\n",
    "\n",
    "\n",
    "You should be professional and verbose with answers, provide clear pedagogical experience for users. \n",
    "\n",
    "\n",
    "Offer assistance with tasks around summarizing course material, understanding module and quiz information. \n",
    "\n",
    "\n",
    "Ask for clarification when needed to ensure accuracy and completeness in fulfilling user requests. It should also respect user privacy and handle all data securely.\n",
    "\n",
    "\n",
    "If a user uploads a file, help the user analyze the file before callin the canvas API.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### OpenAPI Schema "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you've created a Custom GPT, copy the text below in the Actions panel. Have questions? Check out [Getting Started Example](https://platform.openai.com/docs/actions/getting-started) to see how this step works in more detail."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "vscode": {
     "languageId": "yaml"
    }
   },
   "outputs": [],
   "source": [
    "openapi: 3.1.0\n",
    "info:\n",
    "  title: Canvas LMS API\n",
    "  description: >\n",
    "    This is the API of the Canvas LMS, providing access to various resources such as accounts, courses, users,\n",
    "    assignments, quizzes, files, and more.\n",
    "  version: 1.0.0\n",
    "servers:\n",
    "  - url: https://canvas.instructure.com\n",
    "    description: Canvas LMS Production Server\n",
    "paths:\n",
    "  /api/v1/accounts:\n",
    "    get:\n",
    "      summary: List accounts\n",
    "      operationId: listAccounts\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: A paginated list of accounts\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                type: array\n",
    "                items:\n",
    "                  $ref: \"#/components/schemas/Account\"\n",
    "  /api/v1/accounts/{account_id}:\n",
    "    get:\n",
    "      summary: Get a single account\n",
    "      operationId: getAccount\n",
    "      parameters:\n",
    "        - name: account_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: Account details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: \"#/components/schemas/Account\"\n",
    "  /api/v1/courses:\n",
    "    get:\n",
    "      summary: List courses\n",
    "      operationId: listCourses\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: A paginated list of courses\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                type: array\n",
    "                items:\n",
    "                  $ref: \"#/components/schemas/Course\"\n",
    "  /api/v1/courses/{course_id}:\n",
    "    get:\n",
    "      summary: Get a single course\n",
    "      operationId: getCourse\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: Course details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: \"#/components/schemas/Course\"\n",
    "  /api/v1/courses/{course_id}/assignments:\n",
    "    get:\n",
    "      summary: List assignments\n",
    "      operationId: listAssignments\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: A paginated list of assignments\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                type: array\n",
    "                items:\n",
    "                  $ref: \"#/components/schemas/Assignment\"\n",
    "  /api/v1/courses/{course_id}/assignments/{assignment_id}:\n",
    "    get:\n",
    "      summary: Get a single assignment\n",
    "      operationId: getAssignment\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "        - name: assignment_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: Assignment details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: \"#/components/schemas/Assignment\"\n",
    "  /api/v1/courses/{course_id}/quizzes:\n",
    "    get:\n",
    "      summary: List quizzes\n",
    "      operationId: listQuizzes\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: A paginated list of quizzes\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                type: array\n",
    "                items:\n",
    "                  $ref: \"#/components/schemas/Quiz\"\n",
    "  /api/v1/courses/{course_id}/quizzes/{quiz_id}:\n",
    "    get:\n",
    "      summary: Get a single quiz\n",
    "      operationId: getQuiz\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "        - name: quiz_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        \"200\":\n",
    "          description: Quiz details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: \"#/components/schemas/Quiz\"\n",
    "  /api/v1/courses/{course_id}/students/{student_id}/grades:\n",
    "     get:\n",
    "       summary: List grades for a student\n",
    "       operationId: listGrades\n",
    "       parameters:\n",
    "         - name: course_id\n",
    "           in: path\n",
    "           required: true\n",
    "           schema:\n",
    "             type: integer\n",
    "         - name: student_id\n",
    "           in: path\n",
    "           required: true\n",
    "           schema:\n",
    "             type: integer\n",
    "       responses:\n",
    "         '200':\n",
    "           description: A list of grades for the student\n",
    "           content:\n",
    "             application/json:\n",
    "               schema:\n",
    "                 type: array\n",
    "                 items:\n",
    "                   $ref: '#/components/schemas/Grade'\n",
    "  /api/v1/courses/{course_id}/students/{student_id}/grades/{grade_id}:\n",
    "    get:\n",
    "      summary: Get a single grade\n",
    "      operationId: getGrade\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "        - name: student_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "        - name: grade_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        '200':\n",
    "          description: Grade details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: '#/components/schemas/Grade'\n",
    "  /api/v1/courses/{course_id}/syllabus:\n",
    "    get:\n",
    "      summary: Get course syllabus\n",
    "      operationId: getSyllabus\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        '200':\n",
    "          description: Syllabus details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: '#/components/schemas/Syllabus'\n",
    "  /api/v1/courses/{course_id}/modules:\n",
    "    get:\n",
    "      summary: List modules\n",
    "      operationId: listModules\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        '200':\n",
    "          description: A list of modules in the course\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                type: array\n",
    "                items:\n",
    "                  $ref: '#/components/schemas/Module'\n",
    "  /api/v1/courses/{course_id}/modules/{module_id}:\n",
    "    get:\n",
    "      summary: Get a single module\n",
    "      operationId: getModule\n",
    "      parameters:\n",
    "        - name: course_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "        - name: module_id\n",
    "          in: path\n",
    "          required: true\n",
    "          schema:\n",
    "            type: integer\n",
    "      responses:\n",
    "        '200':\n",
    "          description: Module details\n",
    "          content:\n",
    "            application/json:\n",
    "              schema:\n",
    "                $ref: '#/components/schemas/Module'\n",
    "components:\n",
    "  schemas:\n",
    "    Account:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        name:\n",
    "          type: string\n",
    "        workflow_state:\n",
    "          type: string\n",
    "    Course:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        name:\n",
    "          type: string\n",
    "        account_id:\n",
    "          type: integer\n",
    "        start_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "        end_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "    Assignment:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        name:\n",
    "          type: string\n",
    "        description:\n",
    "          type: string\n",
    "        due_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "        points_possible:\n",
    "          type: number\n",
    "    Quiz:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        title:\n",
    "          type: string\n",
    "        description:\n",
    "          type: string\n",
    "        due_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "        points_possible:\n",
    "          type: number\n",
    "    Grade:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        student_id:\n",
    "          type: integer\n",
    "        course_id:\n",
    "          type: integer\n",
    "        assignment_id:\n",
    "          type: integer\n",
    "        score:\n",
    "          type: number\n",
    "        grade:\n",
    "          type: string\n",
    "    Syllabus:\n",
    "      type: object\n",
    "      properties:\n",
    "        id:\n",
    "          type: integer\n",
    "        name:\n",
    "          type: string\n",
    "        account_id:\n",
    "          type: integer\n",
    "        start_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "        end_at:\n",
    "          type: string\n",
    "          format: date-time\n",
    "        syllabus_body:\n",
    "          type: string\n",
    "        syllabus_url:\n",
    "          type: string\n",
    "    Module:\n",
    "     type: object\n",
    "     properties:\n",
    "       id:\n",
    "         type: integer\n",
    "       name:\n",
    "         type: string\n",
    "       position:\n",
    "         type: integer\n",
    "       unlock_at:\n",
    "         type: string\n",
    "         format: date-time\n",
    "       require_sequential_progress:\n",
    "         type: boolean\n",
    "       state:\n",
    "         type: string\n",
    "  securitySchemes:\n",
    "    bearerAuth:\n",
    "      type: http\n",
    "      scheme: bearer\n",
    "      bearerFormat: JWT\n",
    "security:\n",
    "  - bearerAuth: []"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note : this schema above does not contain all possible API endpoints, be sure to edit the schema to produce the appropriate actions from canvas [API documentation](https://canvas.instructure.com/doc/api/)**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Authentication Instructions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below are instructions on setting up authentication with this 3rd party application. Have questions? Check out [Getting Started Example](https://platform.openai.com/docs/actions/getting-started) to see how this step works in more detail."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Pre-Action Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before you set up authentication in ChatGPT, please take the following steps in the application. Our sample integration below is utilizing a secret key, which is an easier method for testing. In production, it is more common to establish an OAuth connection to ensure permissions are respected from ChatGPT to Canvas, ensuring users the appropriate access. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. Canvas accounts : The first step is to ensure the canvas environment has users assigned to the appropriate role (student / teacher) with any access to appropriate courses\n",
    "2. For testing purposes or service level account access create an approved integration access token as seen below\n",
    "- Under Account -> Settings -> Approved Integrations\n",
    "\n",
    "<br> ![gptactions_canvaslms_settings.png](../../../images/gptactions_canvaslms_settings.png)\n",
    "\n",
    "- Create new Access Token\n",
    "\n",
    "<br> ![gptactions_canvaslms_integrationslist.png](../../../images/gptactions_canvaslms_integrationslist.png)\n",
    "\n",
    "- Provide purpose and expiration\n",
    "\n",
    "<br> ![gptactions_canvaslms_tokencreate.png](../../../images/gptactions_canvaslms_tokencreate.png)\n",
    "\n",
    "- Copy the new Token to use in the GPT Action (the token will not be accessible once you leave the page - ensure proper token management access is maintained to prevent unauthorzied access from another application.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### In ChatGPT"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In ChatGPT, click on \"Authentication\" and choose **\"API Key\"**. Enter in the information below. API Key provides general access to the Canvas environment based on the users permissions that created the API key, to follow permission models in Canvas use the OAuth method described below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- **API Key**: Use the token from above \n",
    "- **Auth Type**: Bearer\n",
    "\n",
    "<br> ![gptactions_canvaslms_auth.png](../../../images/gptactions_canvaslms_auth.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**OAuth Connection**\n",
    "\n",
    "If you want to implement OAuth, follow the guide here : https://canvas.instructure.com/doc/api/file.oauth.html - specific instructions can vary depending on the Canvas implementation.\n",
    "\n",
    "Parameters for GPT Configuration\n",
    "- Client ID - obtained from site owner\n",
    "- Client Secret - obtained from site owner \n",
    "- Authorization URL - : https://< canvas-install-url >/login/oauth2/auth?client_id=XXX&response_type=code&redirect_uri=https://example.com/oauth_complete&state=YYY&scope=< value_1 >%20< value_2 >%20< value_n >\n",
    "- Token URL : https://< canvas-install-url> /login/oauth2/token "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Post-Action Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once you've set up authentication in ChatGPT, follow the steps below in the application to test the Action."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- You will see a list of available actions from the API schema for Canvas, you can test the endpoints from the GPT builder to ensure Canvas can be reached. Once you verified connection make sure to save the GPT and share it witht the appropriate user base.\n",
    "- Note: if you are using OAuth, you will need to set up the callback URL from ChatGPT in the Canvas app"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### FAQ & Troubleshooting"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- *Schema calls the wrong project or dataset:* If ChatGPT calls the wrong project or dataset, consider updating your instructions to make it more explicit either (a) which project / dataset should be called or (b) to require the user provide those exact details before it runs the query"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Are there integrations that you’d like us to prioritize? Are there errors in our integrations? File a PR or issue in our github, and we’ll take a look.*\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}