diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b6e4761 --- /dev/null +++ b/.gitignore @@ -0,0 +1,129 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ diff --git a/.gitpod.yml b/.gitpod.yml new file mode 100644 index 0000000..1d0e96d --- /dev/null +++ b/.gitpod.yml @@ -0,0 +1,11 @@ +# This configuration file was automatically generated by Gitpod. +# Please adjust to your needs (see https://www.gitpod.io/docs/introduction/learn-gitpod/gitpod-yaml) +# and commit this file to your remote git repository to share the goodness with others. + +# Learn more from ready-to-use templates: https://www.gitpod.io/docs/introduction/getting-started/quickstart + +tasks: + - init: pip install -r requirements.txt + command: python main.py + + diff --git a/.well-known/ai-plugin.json b/.well-known/ai-plugin.json new file mode 100644 index 0000000..edd676a --- /dev/null +++ b/.well-known/ai-plugin.json @@ -0,0 +1,18 @@ +{ + "schema_version": "v1", + "name_for_human": "Cassandra TODO List (no auth)", + "name_for_model": "todo", + "description_for_human": "Manage your TODO list in Apache Cassandra. You can add, remove and view your TODOs.", + "description_for_model": "Plugin for managing a TODO list, you can add, remove and view your TODOs in Apache Cassandra.", + "auth": { + "type": "none" + }, + "api": { + "type": "openapi", + "url": "http://localhost:5003/openapi.yaml" + }, + "logo_url": "http://localhost:5003/logo.png", + "contact_email": "legal@example.com", + "legal_info_url": "http://example.com/legal" + } + diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b3841f6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2023 OpenAI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..f97783d --- /dev/null +++ b/README.md @@ -0,0 +1,81 @@ + +# Cassandra Todolist ChatGPT plugin Quickstart + +Get a todo list ChatGPT plugin up and running in under 5 minutes using Python. This plugin is designed to work in conjunction with the [ChatGPT Plugins Documentation](https://platform.openai.com/docs/plugins). If you do not already have plugin developer access, please [join the waitlist](https://openai.com/waitlist/plugins). + +## Quickstart in Gitpod + +You can either follow the directions below or [open this in gitpod](https://gitpod.io/#https://github.com/CassioML/cassandra-todolist-chatgpt-plugin). + +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/CassioML/cassandra-todolist-chatgpt-plugin) + +## Setup + +### Clone the Repo +Before you can run the plugin, you need to get the code onto your computer. This is done by cloning the GitHub repository. If you have git installed, you can do this by running the following command in your terminal: + +```bash +git clone https://github.com/CassioML/cassandra-todolist-chatgpt-plugin +``` + +This will create a copy of the repository on your local machine. +Once you have cloned the repository, navigate into the directory: + +```bash +cd cassandra-todolist-chatgpt-plugin +``` +### Install Prerequisites + +To install the required packages for this plugin, run the following command: + +```bash +pip install -r requirements.txt +``` + +### Setup DB & API + +You can read up on how to setup the database and configure the API spec. It's important to either have a Cassandra server or use Datastax Astra DB, otherwise this example won't work. +- [Database setup](/setup/database.md) - Create a database, keyspace, and import the schema/ +- [API setup](/setup/database.md) - Update plugin and openapi spec for ChatGPT to discover your API's capabilities. + +#### Create/edit .env and add the DB details to your .env file +```bash +touch .env +``` + +and add (if you are using DataStax Astra) the two components of the Astra Token to your .env file: +```code +astra_clientID="<", methods=["POST"]) +async def add_todo(username): + request_data = await quart.request.get_json(force=True) + todo = request_data["todo"] + + # Check if the username already exists in the Cassandra table + query = f"SELECT COUNT(*) FROM cassio_tutorials.todos WHERE username = '{username}'" + result = session.execute(query) + count = result.one()[0] + + # If the username does not exist, insert it into the Cassandra table + if count == 0: + insert_query = f"INSERT INTO cassio_tutorials.todos (username, todo) VALUES ('{username}','test task')" + session.execute(insert_query) + + # Insert the task into the Cassandra table + todo_insert_query = f"INSERT INTO cassio_tutorials.todos (username, todo) VALUES ('{username}', '{todo}')" + session.execute(todo_insert_query) + return quart.Response(response='OK', status=200) + +@app.route("/todos/", methods=["GET"]) +async def get_todos(username): + # Retrieve the tasks from the Cassandra table for the provided username + query = f"SELECT todo FROM cassio_tutorials.todos WHERE username = '{username}'" + result = session.execute(query) + todos = [row.todo for row in result] + return quart.jsonify(todos) + +@app.route("/todos/", methods=["DELETE"]) +async def delete_todo(username): + request_data = await quart.request.get_json(force=True) + todo_idx = request_data["todo_idx"] + + # Retrieve the task at the given index for the provided username + query = f"SELECT todo FROM cassio_tutorials.todos WHERE username = '{username}'" + result = session.execute(query) + todos = [row.todo for row in result] + + if 0 <= todo_idx < len(todos): + todos_to_delete = todos[todo_idx] + + # Delete the task from the Cassandra table + query = f"DELETE FROM cassio_tutorials.todos WHERE username = '{username}' AND todo = '{todos_to_delete}'" + session.execute(query) + + return quart.Response(response='OK', status=200) + +@app.route("/logo.png", methods=["GET"]) +async def plugin_logo(): + filename = 'logo.png' + return await quart.send_file(filename, mimetype='image/png') + +@app.route("/.well-known/ai-plugin.json", methods=["GET"]) +async def plugin_manifest(): + host = request.headers['Host'] + with open("./.well-known/ai-plugin.json") as f: + text = f.read() + return quart.Response(text, content_type="text/json") + +@app.route("/openapi.yaml", methods=["GET"]) +async def openapi_spec(): + host = request.headers['Host'] + with open("openapi.yaml") as f: + text = f.read() + return quart.Response(text, content_type="text/json") + +def main(): + app.run(debug=True, host="0.0.0.0", port=5003) + +if __name__ == "__main__": + main() diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..a67ab88 --- /dev/null +++ b/openapi.yaml @@ -0,0 +1,93 @@ +openapi: 3.0.1 +info: + title: Cassandra TODOlist Plugin + description: A plugin that allows the user to create and manage a TODO list backed by Cassandra using ChatGPT. If you do not know the user's username, ask them first before making queries to the plugin. Otherwise, use the username "global". + version: 'v1' +servers: + - url: http://localhost:5003 +paths: + /todos/{username}: + get: + operationId: getTodos + summary: Get the list of todos + parameters: + - in: path + name: username + schema: + type: string + required: true + description: The name of the user. + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/getTodosResponse' + post: + operationId: addTodo + summary: Add a todo to the list + parameters: + - in: path + name: username + schema: + type: string + required: true + description: The name of the user. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/addTodoRequest' + responses: + "200": + description: OK + delete: + operationId: deleteTodo + summary: Delete a todo from the list + parameters: + - in: path + name: username + schema: + type: string + required: true + description: The name of the user. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/deleteTodoRequest' + responses: + "200": + description: OK + +components: + schemas: + getTodosResponse: + type: object + properties: + todos: + type: array + items: + type: string + description: The list of todos. + addTodoRequest: + type: object + required: + - todo + properties: + todo: + type: string + description: The todo to add to the list. + required: true + deleteTodoRequest: + type: object + required: + - todo_idx + properties: + todo_idx: + type: integer + description: The index of the todo to delete. + required: true diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..7d8e91f --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +quart +quart-cors +cassandra-driver +python-dotenv diff --git a/setup/api.md b/setup/api.md new file mode 100644 index 0000000..72f8cf9 --- /dev/null +++ b/setup/api.md @@ -0,0 +1,4 @@ +## Todo + +- [ ] Add instructions on how to get app running on Gitpod, DigitalOcean or otherwise - maybe add Dockerfile +- [ ] Add instructions on how to edit `.well-known/ai-plugin.json` and `openapi.yml` so that it reflects the URL. diff --git a/setup/create_schema.cql b/setup/create_schema.cql new file mode 100644 index 0000000..ee76a18 --- /dev/null +++ b/setup/create_schema.cql @@ -0,0 +1,5 @@ +CREATE TABLE IF NOT EXISTS todos ( + username text, + todo text, + PRIMARY KEY ((username), todo) +) WITH CLUSTERING ORDER BY (todo ASC); diff --git a/setup/database.md b/setup/database.md new file mode 100644 index 0000000..e9056b5 --- /dev/null +++ b/setup/database.md @@ -0,0 +1,89 @@ +# DB Setup + +We show how to create an Astra DB instance and set the connection details and secrets that all code examples can then use. + +Astra DB is a serverless DBaaS by DataStax, built on Apache Cassandra, that offers a free tier with generous traffic and storage limits. Using Astra DB frees you from the hassle of running your own cluster while retaining all the advantages, such as the excellent data distribution and very high availability that make Cassandra a world-class NoSQL database. + +!!! note "Self-managed Cassandra alternative" + + Nothing prevents you from adapting the examples to any Cassandra cluster: + in most cases all you have to do is to build the database `Session` object + differently, and that's it. Inspect the code to find out: generally it's + just a couple of lines to change. + +### Create your Astra DB instance + +Go to [astra.datastax.com](https://astra.datastax.com), sign up and create an Astra DB database in the Free Tier -- in the following we assume you called it `cassio_db`. + +You will be asked for a "Keyspace name" when creating the database: you can call it something like `cassio_tutorials` for example. + +Detailed explanations can be found [at this page](https://awesome-astra.github.io/docs/pages/astra/create-instance/). + +### Get Token and Secure Connect Bundle, create `.env` file + +In order to establish a connection to your Cloud Database, you need a secret string ("Token") and a "Secure Connect Bundle" zipfile, containing certificates/proxy/routing information. + +The easiest way to do so is to first generate a database token with role "Database Administrator", then use the Astra CLI to automate the remaining part: + +- how to [generate a token](https://awesome-astra.github.io/docs/pages/astra/create-token/) (remember to pick the "Database Administrator role); +- how to [install Astra CLI](https://awesome-astra.github.io/docs/pages/astra/astra-cli/#1-installation) + +Now you can configure the CLI by running + +``` +astra setup +``` + +and providing the token (the string starting with `AstraCS:...`). +Then, in the root directory of this repo, adjusting names if needed, launch + +``` +astra db create-dotenv cassio_db -k cassio_tutorials +``` + +This will download the bundle zipfile and create a `.env` file +with all connection parameters you'll need later. + +#### "Alternatives to Astra CLI" + +If you prefer to proceed manually, you can [download the Secure Connect Bundle](https://awesome-astra.github.io/docs/pages/astra/download-scb/#c-procedure) somewhere on your machine, then create the `.env` file yourself, as long as it defines the same environment variables you see in the provided `.env.template` file + (essentially, the full path to bundle file, the keyspace name and your database secret token string). + +### Import Schema and Sample data + +Some of the provided code examples require pre-existing data on your +database. + + + +To populate the newly-created keyspace with the required data: + +- download the newest (vector-search-compatible) `cqlsh` utility from [this link](https://downloads.datastax.com/enterprise/cqlsh-astra-20230526-vectortype-bin.tar.gz); +- extract the archive to a location of your liking, e.g. `/home/user/myCqlsh`; +- source the environment file you just prepared with `. .env` (make sure you are in this repo's root directory); +- launch the script that populates the database with: + +``` +/home/user/myCqlsh/cqlsh-astra/bin/cqlsh \ + -b "$ASTRA_DB_SECURE_BUNDLE_PATH" \ + -u token \ + -p "$ASTRA_DB_APPLICATION_TOKEN" \ + -k "$ASTRA_DB_KEYSPACE" \ + -f setup/create_schema.cql +``` + +!!! note + + If you target your own Cassandra cluster, make sure you `USE` your + keyspace before running the script above. + +### Your database is ready + +The next step is to configure the necessary [API Keys](/setup/api.md).