Nephthys Plus

Nephthys Plus is the bot powering many support channels in the Hack Club Slack such as #help and #hackclub-ai-help! Below is a guide to set her up for developing and here's a list of some of her features :)

Features

Category tags

Category tags are used to classify tickets into broader categories such as "Fulfillment", "Identity", or "Platform Issues". When a new ticket is created, AI analyzes the message content and automatically assigns the most relevant category tag.

Helpers can reassign these tags in the private tickets channel if the AI suggestion is incorrect. Set AI_CATEGORY_TAGGING=false to turn off the automatic AI tagging and only tag tickets by hand.

Team tags

Team tags let you tag tickets that are the responsibility of a specific group of people (or perhaps just one person). E.g. you could have tags for Fufillment, Hack Club Auth, Onboarding flow, etc.

You can add team tags to tickets in the private tickets channel or with the macro ?tag <tag_name>. This will DM the people who are specialised in responding to those issues and have it show up in their assigned tickets. You can assign yourself to get notified for specific tags on the app home

FAQ links

If a program's transcript sets faq_canvas_id (the F... ID of its FAQ canvas), Nephthys reads the canvas on startup and every 15 minutes. When a new ticket comes in, AI picks the FAQ question that answers it (if any) and replies in the thread with a direct link to it. Each top-level bullet in the canvas is treated as a question, with the bullets nested under it as the answer. Needs OPENROUTER_API_KEY and the files:read scope.

If the transcript also sets faq_events_question (the canvas question whose answer lists each event followed by its help channel), AI can tell when a question is about one specific event and replies with "hey, is this event? if so then ask in channel" (the event_channel_suggestion text), instead of the generic events link. Programs that don't set it never get this.

Macros

Sometimes it’s nice to be able to do things quickly... Here’s where macros come in! Send one of the following messages in an open thread and something will happen

• ?resolve - the ticket gets closed. Equivalent of hitting the resolve button
• ?reopen - reopen a closed ticket
• ?identity - redirect to #identity-help
• ?faq - redirect to the FAQ
• ?hii - silly message :3
• ?fraud - redirect to Fraud Squad
• ?forward - forward the thread to another channel
• ?threadrip <reason> - delete the whole thread (original post and every reply)
• ?deleteop - delete only the original post
• ?stale - close a stale ticket with a polite message
• ?tag <tag_name> - add a team tag to the ticket
• ?thread - remove the reaction and all Nephthys+ replies to unclutter duplicates
• ?shipwrights - redirect to #ask-the-shipwrights
• ?hackatime - redirect to #hackatime-help
• more to come?? feel free to PR your own into aoishik/nephthys-plus or tell me what you want

Program-specific macros can be added from the App Home (see below) without touching code.

Custom Program Macros

Helpers and admins can add, edit, and delete custom program macros from the Macros tab on the bot's App Home. Each macro can optionally be set to keep the ticket open (instead of resolving it) or to run on closed tickets.

Leaderboard

At midnight UK time each day, you get to see the stats for the day in the team channel, as well as a summary of open tickets that are over 10 days old or haven't had a message in 3 days.

Helpers can see more detailed stats at any time on the app home for the bot!

Assigned Tickets

When you send a message in a help thread, that thread is assigned to you and it is up to you to resolve it. You can see a list of threads waiting for you on the app home - just select the Assigned Tickets tab at the top

Prerequisites

• Python (3.13 or later)
• uv
• A Slack workspace where you have permissions to install apps
• Tunneling tool (for local development)
• A PostgreSQL database (you can run one in Docker using the command below)

docker run --name hh-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres

For production, see docs/deployment.md (Orchard).

Setting up the Slack App

1. Go to https://api.slack.com/apps and click "Create New App".
2. Choose "From an app manifest" and select your workspace.
3. Copy and paste the manifest in manifest.yml.
4. Review and create the app.
5. In the "Basic Information" section, note down the App Id, Client Id, Client Secret, Signing Secret .
6. Go to "OAuth & Permissions" and install the app to your workspace. Note down the "Bot User OAuth Token".

Setting up the Project

1. Clone the repository:

   git clone https://github.com/aoishik/nephthys-plus
   cd nephthys-plus

2. Install dependencies:

   uv sync
   source .venv/bin/activate # for bash/zsh
   source .venv/bin/activate.fish # for fish
   source .venv/bin/activate.csh # for csh
   source .venv/bin/activate.ps1 # for powershell

3. Copy the .env.sample file to .env:

   cp .env.sample .env

4. Edit the .env file and fill in the values:

Running the Application

1. Start your tunneling tool and expose the local server. (Not needed in socket mode with SLACK_APP_TOKEN set)

   Note the HTTPS URL you get.

2. Update your Slack app's request URLs:

   • Go to your Slack app's settings.
   • In "Event Subscriptions" and "Interactivity & Shortcuts", update the request URL to your HTTPS URL followed by /slack/events.
   • In "OAuth & Permissions", update Redirect URLs to your HTTPS URL followed by /slack/oauth_redirect.

3. MAKE SURE YOU CHANGE THE COMMAND - DO NOT USE THE SAME COMMAND

4. Install pre-commit hooks:

   uv run pre-commit install

5. Start your database and update the database schema: (change the DB URL if needed)

   DATABASE_URL="postgresql://postgres:postgres@localhost:5432/nephthys+" piccolo migrations forwards nephthys+

6. Start the application:

   nephthys+

Your Slack app should now be running and connected to your Slack workspace!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

A work-in progress document with some codebase conventions can be found at docs/contributing.md.

The #nephthys+-dev channel in the Slack is available for technical discussion or questions.

Scripts

The codebase contains some scripts in the nephthys+/scripts/ directory to help with development and testing. They are documented below.

Adding Dummy Data

add_dummy_data.py is a script that adds a bunch of dummy (i.e. fake) support ticket records to the database, for stress-testing/performance testing.

Usage: uv run nephthys+/scripts/add_dummy_data.py <num_records>

• Ensure you run it after the nephthys+ has been run at least once (and once the DB has been initialized)
• It takes a while to run (adding 20k records takes ~50 seconds on my machine)
• Don't run this in production, obviously

License

This project is licensed under the MIT License.