Update Chat Bot

Author: gem-neo4j

README.md

@@ -1,33 +1,69 @@
-Pink Programming Chatbot (Flask + Neo4j)
+# Pink Programming Chatbot (Using Flask + Neo4j)
 
-Overview
-- Flask web app scaffold for a chatbot that stores users, chats, and messages in Neo4j.
-- Participants complete the Cypher TODOs in `db.py` to enable user auth, chat creation, and viewing history.
-- OpenAI is used to generate assistant replies; reads config from environment variables.
+Welcome to the Pink Programming Chatbot workshop! Today we will build a chatbot that stores users, chats, and messages in Neo4j.
+Your goal is to complete the Cypher TODOs in `db.py` to get a working chatbot.
+Good Luck!
+
+## Overview
+- This code base is a Flask web app scaffold for a chatbot that stores users, chats, and messages in Neo4j.
+- Your goal is to complete the Cypher TODOs in `db.py` to enable user auth, chat creation, and viewing history.
+- Use OpenAI through the Cypher GenAI Plugin integration.
+
+## Quick Start with Codespaces
+- Create an account on https://console.neo4j.io/ and create a free Aura instance (make sure to save the password).
+- **Important**: Connect to the database (click query) and run the command: `ALTER DATABASE <db_name> SET DEFAULT LANGUAGE CYPHER 25` in order to get the correct Cypher version.
+
+![use_template_image](images/use_template.png)
 
-Quick Start with Codespaces
-- Create an account on https://console-preview.neo4j.io/ and create a free Aura instance (make sure to save the password).
 - In the GitHub repository click the green "Use this template" button and open the project in a codespace.
+
+![connect info image](images/connection_info.png)
+
 - Copy `.env.example` to `.env` and set values.
+  - `NEO4J_USERNAME`: This should be the same name as your Aura instance.
   - `NEO4J_CONNECTION_URI`: Inspect your Aura instance and copy the connection URI.
-  - `NEO4J_PASSWORD`: (paste password that you got during the instance creation).
+  - `NEO4J_PASSWORD`: paste password that you got during the instance creation.
+
+![start_flask_app_image](images/run_flask_app.png)
+
 - Open the Run and Debug menu and start the "Flask: run app.py" configuration.
+
+![open_browser_image](images/open_browser.png)
+
 - It opens a terminal and starts the Flask development server, click on the link to open the app in a new browser tab.
+
+![welcome_page_image](images/welcome_page.png)
+
 - Try registering a new user, you should see Cypher Error page which means you're ready to start the exercises!
 
-Workshop Tasks (Cypher TODOs in `db.py`)
+![cypher_error_image](images/cypher_error.png)
+
+## Workshop Tasks (Cypher TODOs in `db.py`)
 - Create/Login User
   - `create_user(username, password_hash)`: create a `:User` with properties and return it.
   - `fetch_user_by_username(username)`: find a `:User` by username and return it.
 - Chat With Chatbot
-  - `create_chat_and_first_message(user_id, message)`: create a `:Chat` and the first user `:Message`.
-  - `create_message(chat_id, role, content)`: append messages (both user and assistant) to a chat.
+  - `create_chat_and_first_message(username, message)`: create a `:Chat` and the first user `:Message`.
+  - `create_message(chat_id, role, content, previous_ai_chat_id)`: append messages (both user and ai) to a chat.
 - See Previous Chats
-  - `list_user_chats(user_id)`: gat all chats for the user, return summary list.
+  - `list_user_chats(username)`: get all chats for the user, return a summary in a list.
   - `fetch_chat(chat_id)`: return full chat with messages ordered by time.
+  - `get_ai_response(chat_id, previous_chat_id, message)`: get the response from the OpenAI API.
+  - `get_previous_ai_chat_id(chat_id)`: find the previous AI chat id for a given chat id to send to OpenAI.
 
 Pages
 - `/register` and `/login`: basic authentication using Flask sessions.
 - `/chat/new`: start a new chat by sending the first message.
 - `/chats`: list previous chats.
 - `/chats/<chat_id>`: view and continue a chat.
+
+## Clean Database
+You may want to reset your database to start fresh, do this in the Aura console and run "MATCH (n) DETACH DELETE n"
+
+## Database Model
+
+![database_model_image](images/chat_bot_model.png)
+
+## Possible Extensions
+- Add a delete chat option
+- Add a delete User option

ai.py

@@ -12,8 +12,9 @@
     QuerySyntaxError,
     create_chat_and_first_message,
     create_message,
+    get_previous_ai_chat_id,
+    get_ai_response
 )
-from ai import generate_ai_response
 
 
 def create_app() -> Flask:
@@ -74,7 +75,7 @@ def login():
                 flash("User not found.", "error")
                 return render_template("login.html")
 
-            stored_hash = user.get("password_hash")
+            stored_hash = user.get("passwordHash")
             if not stored_hash or not check_password_hash(stored_hash, password):
                 flash("Invalid credentials.", "error")
                 return render_template("login.html")
@@ -104,7 +105,7 @@ def wrapper(*args, **kwargs):
     def chats():
         user = session["user"]
         user_identifier = user.get("id") or user.get("username")
-        user_chats = list_user_chats(user_id=user_identifier)
+        user_chats = list_user_chats(username=user_identifier)
         return render_template("chats.html", chats=user_chats)
 
     @app.route("/chats/<chat_id>", methods=["GET", "POST"])
@@ -114,10 +115,11 @@ def chat(chat_id: str):
         if request.method == "POST":
             user_message = request.form.get("message", "").strip()
             if user_message:
-                create_message(chat_id, role="user", content=user_message)
-                ai_reply = generate_ai_response(user_message)
-                if ai_reply:
-                    create_message(chat_id, role="assistant", content=ai_reply)
+                    create_message(chat_id, role="user", content=user_message, previous_ai_chat_id=None)
+                    previous_chat_id = get_previous_ai_chat_id(chat_id)
+                    ai_response = get_ai_response(chat_id=chat_id, previous_chat_id=previous_chat_id, message=user_message)
+                    if ai_response:
+                        create_message(chat_id, role="ai", content=ai_response["message"], previous_ai_chat_id=ai_response["chatId"])
         chat_obj = fetch_chat(chat_id)
         if not chat_obj:
             flash("Chat not found or Cypher TODO incomplete.", "error")
@@ -137,10 +139,10 @@ def chat_new():
             user_identifier = user.get("id") or user.get("username")
             new_chat = create_chat_and_first_message(user_identifier, user_message)
             chat_id = new_chat.get("id") if new_chat else None
-            # Generate AI reply and save as assistant message
-            ai_reply = generate_ai_response(user_message)
+            # Generate AI reply and save as ai message
+            ai_reply = get_ai_response(chat_id=chat_id, previous_chat_id=None, message=user_message)
             if chat_id and ai_reply:
-                create_message(chat_id, role="assistant", content=ai_reply)
+                create_message(chat_id, role="ai", content=ai_reply["message"], previous_ai_chat_id=ai_reply["chatId"])
                 return redirect(url_for("chat", chat_id=chat_id))
             flash("Chat created but could not determine chat id. Complete Cypher TODOs.", "warning")
             return redirect(url_for("chats"))

app.py

@@ -69,11 +69,14 @@ def _error_handling(cypher: str, e: Neo4jError):
 
 def create_user(username: str, password_hash: str) -> Dict[str, Any]:
     """
-    TODO: Create a new user node if it doesn't exist.
+    TODO: Create a new user node if it doesn't exist. The app expects a user object called user.
 
     Suggested shape:
     - Label: User
-    - Properties: {username: $username, password_hash: $password_hash, createdAt: datetime()}
+    - Properties:
+        - username: $username
+        - passwordHash: $password_hash
+        - createdAt: datetime()
     """
     cypher = """
     // TODO: Cypher query to create a User node 
@@ -84,7 +87,7 @@ def create_user(username: str, password_hash: str) -> Dict[str, Any]:
 
 def fetch_user_by_username(username: str) -> Optional[Dict[str, Any]]:
     """
-    TODO: Fetch a user node by username.
+    TODO: Fetch a user node by username; the app expects a user object called user. The app expects a user object called user.
     """
     cypher = """
     // TODO: Cypher query to fetch a User node by username
@@ -93,66 +96,120 @@ def fetch_user_by_username(username: str) -> Optional[Dict[str, Any]]:
     return record["user"] if record else None
 
 
-def create_chat_and_first_message(user_id: str, message: str) -> Dict[str, Any]:
+def create_chat_and_first_message(username: str, message: str) -> Dict[str, Any]:
     """
-    TODO: Create a new Chat node linked to the User and store the first user message.
+        TODO: Create a new Chat node linked to the User and store the first user message. The app expects a chat object called chat.
 
-    Suggested shape:
-    - Label: Chat
-    - Properties: {id: randomUUID(), createdAt: datetime(), updatedAt: datetime()}
-    - Relationship: (User)-[:STARTED]->(Chat)
-    """
+        Suggested shape:
+        - Label: Chat
+        - Properties:
+            - id: randomUUID()
+            - createdAt: datetime()
+            - updatedAt: datetime()
+        - Relationship: (user)-[:STARTED]->(chat)
+        """
     cypher = """
     // TODO: Cypher query to create chat
     """
-    chat_record = _run_query_single(cypher, user_id=user_id, message=message)
-    create_message(chat_record["chat"]["id"], role="user", content=message)
+    chat_record = _run_query_single(cypher, username=username, message=message)
+    create_message(chat_record["chat"]["id"], role="user", content=message, previous_ai_chat_id=None)
     return chat_record["chat"] if chat_record else {}
 
 
-def create_message(chat_id: str, role: str, content: str) -> Dict[str, Any]:
+def create_message(chat_id: str, role: str, content: str, previous_ai_chat_id: Optional[str]) -> Dict[str, Any]:
     """
-    TODO: Create a Message node and link it to an existing Chat.
+    TODO: Create a Message node and link it to an existing Chat. The app expects a message object called message.
 
     Suggested shape:
     - Label: Message
-    - Properties: {id: randomUUID(), role: 'user', content: $message, createdAt: datetime()}
-    - Relationship: (Chat)-[:HAS_MESSAGE]->(Message)
+    - Properties:
+        - id: randomUUID()
+        - role: $role
+        - content: $message
+        - createdAt: datetime()
+        - previousAIChatId: $previous_ai_chat_id // Note: this comes from the AI and is used for OpenAI to keep track of the conversation
+    - Relationship: (chat)-[:HAS_MESSAGE]->(message)
     """
     cypher = """
     // TODO: Cypher query to create a message for a chat
     """
-    record = _run_query_single(cypher, chat_id=chat_id, role=role, content=content)
+    record = _run_query_single(cypher, chat_id=chat_id, role=role, content=content,
+                               previous_ai_chat_id=previous_ai_chat_id)
     return record["message"] if record else {}
 
 
-def list_user_chats(user_id: str) -> List[Dict[str, Any]]:
+def list_user_chats(username: str) -> List[Dict[str, Any]]:
     """
-    TODO: Return all chats for the logged-in user with a summary.
+    TODO: Return all chats for the logged-in user. The app expects a stream of chat objects called chat.
 
     Suggested shape:
     - Label: Chat
-    - Properties: {id, createdAt, updatedAt}
-    - Relationship: (User)-[:STARTED]->(Chat)
+    - Properties:
+        - id
+        - createdAt
+        - updatedAt
+    - Relationship: (user)-[:STARTED]->(chat)
     """
     cypher = """
     // TODO: cypher query to list user chats
     """
-    records = _run_query(cypher, user_id=user_id)
+    records = _run_query(cypher, username=username)
     return [r["chat"] for r in records]
 
 
 def fetch_chat(chat_id: str) -> Optional[Dict[str, Any]]:
     """
-    TODO: Fetch a full chat with all messages.
+    TODO: Fetch a full chat with all messages in a list. The app expects a chat object called chat and a list of messages called messages.
+
+    Hint: Use collect()
 
     suggested shape:
     - Label: Chat
-    - Properties: {id, createdAt, updatedAt}
-    - Relationship: (Chat)-[:HAS_MESSAGE]->(Message)
+    - Properties:
+        - id
+        - createdAt
+        - updatedAt
+    - Relationship: (chat)-[:HAS_MESSAGE]->(message)
     """
     cypher = """
     // TODO: Cypher query to fetch a chat by id and its messages
     """
     record = _run_query_single(cypher, chat_id=chat_id)
-    return record["chat"] if record else None
+    return record if record else None
+
+
+def get_ai_response(chat_id: str, previous_chat_id: Optional[str], message: str) -> Optional[Dict[str, Any]]:
+    """
+    TODO: Send the message to our GenAI plugin; using the ai.text.chat function. The app expects a Cypher Map called aiResponse.
+
+    See the docs for more: https://neo4j.com/docs/genai/plugin/current/generate-text/#chat-new
+
+    - Using the ai.text.chat function, send the message and the config to OpenAI
+
+    Recommended AI config:
+    {
+        token: $openaiToken,
+        model: 'gpt-5-nano'
+    }
+    """
+    cypher = """
+    // TODO: Cypher query to send message to AI plugin
+    """
+    record = _run_query_single(cypher, chat_id=chat_id, previous_chat_id=previous_chat_id, message=message,
+                               openaiToken=os.getenv("OPENAI_API_KEY"))
+    return record["aiResponse"] if record else None
+
+
+def get_previous_ai_chat_id(chat_id: str) -> Optional[str]:
+    """
+    TODO: Using the chat id, find the most recent AI ChatID (returned by openAI), in order to continue the conversation
+    if there is none, then the AI chat will be the first chat in this conversation. The app expects a string called chatId.
+
+    Hint: Use an ORDER BY and LIMIT and only search for AI messages
+
+    """
+    cypher = """
+    // TODO: Cypher query to find the most recent AI ChatID
+    """
+    record = _run_query_single(cypher, chat_id=chat_id)
+    return record["chatId"] if record else None