Tool that will track and rank contributions across the different Mina developer programs. Consists of two bot:
Clone the repository:
git clone https://github.com/yourusername/PGT_LeaderBot.git
cd PGT_LeaderBotIn the root folder install virtual env and create virtual env:
pip install virtualenv
virtualenv venvActivate it:
source venv/bin/activateInstall dependencies with:
pip install -r requirements.txtConfigure the environment variables
Create .env file in the root folder and add environment variables as shown in the .env.example file:
GITHUB_TOKEN='your_github_token'
DISCORD_TOKEN='your_discord_token'
OPENAI_API_KEY='your_openai_api_key'
GOOGLE_SHEETS_CREDENTIALS='path_to_your_google_sheets_credentials.json'
SHARED_SECRET='shared_secret'
MONGO_HOST='mongodb://localhost:27017/'
MONGO_DB="example_db"
MONGO_COLLECTION="example_collection"
GTP_ENDPOINT=http://localhost:8000
SPREADSHEET_ID='spread_sheet_id'
LOG_LEVEL=DEBUG
GUILD_ID=XXXXXXXX
GMAIL_ADDRESS=xyz@gmail.com
LEADERBOARD_FORUM_CHANNEL_ID=XXXXXXXXXXXXXXXXXYou need to have google credentials .json file which has access your spreadsheet in the root folder. Need to enable Google Sheets API and Google Drive API. Click for more information.
Run tests:
invoke testRun github tracker bot:
invoke botFor other invoke tasks look to: tasks.py
To run Leaderbot discord bot, you need to have Discord bot in a specific server.
invoke leaderbotGithub Tracker Bot fetchs to Google Spreadsheets which includes discord handle, github username and repositories. After getting these informations it fetches github commits data between specific timeframes given by user or day by day for all branches. After pre-processing the commits data. The bot sends total daily commits data(diff file) to OPENAI API to decide are these commits qualified with prompt.
Then gets the decisions data and insert them to MongoDB to further usage.
Date formats are ISO 8601 with Z suffix which is UTC. For example:
"2023-01-24T00:00:00Z"
bot.py is the main script for running a FastAPI service that provides functionality to schedule and run tasks to fetch results from a spreadsheet within specified time frames. The script includes endpoints to start and stop a scheduler, as well as to run tasks on demand.
All of them uses headers headers = {"Authorization": AUTH_TOKEN} gotten from .env SHARED_SECRET
Endpoint: /run-task
Method: POST
This endpoint allows you to run a task immediately and manually for a specified time frame.
since (str): Start datetime in ISO 8601 format (e.g., 2023-07-24T00:00:00Z).until (str): End datetime in ISO 8601 format (e.g., 2023-07-25T00:00:00Z).{
"since": "2023-07-24T00:00:00Z",
"until": "2023-07-25T00:00:00Z"
}{
"message": "Task run successfully with provided times"
}Endpoint: /run-task-for-user?username=johndoe
Method: POST
This endpoint allows you to run a task immediately and manually for a specified time frame and specific user.
since (str): Start datetime in ISO 8601 format (e.g., 2023-07-24T00:00:00Z).until (str): End datetime in ISO 8601 format (e.g., 2023-07-25T00:00:00Z).Endpoint: /run-task-for-user?username=berkingurcan
{
"since": "2023-07-24T00:00:00Z",
"until": "2023-07-25T00:00:00Z"
}{
"message": "Task run successfully with provided times"
}Endpoint: /control-scheduler
Method: POST
This endpoint allows you to start or stop the scheduler that runs tasks at specified minutes intervals. It is minutes for now to test. It will be hours.
action(str): Action to perform (start or stop).interval_minutes (int, optional): Interval in minutes(for now) at which the scheduler should run the task (only required when action is start).{
"action": "start",
"interval_minutes": 5
}{
"action": "stop"
}{
"message": "Scheduler started with interval of 5 minutes"
}{
"message": "Scheduler stopped"
}The User class is a nested dataclass designed to store and manage information about a user, including their GitHub-related activities and AI decisions regarding their contributions. This class stores 4 necessary data:
strstrList[str]List[List[AIDecision]]Remaining fields can be calculated using helper functions in the helper_functions.py.
The AIDecision Class stores AI decision related to a user's daily contribution for specific github repository. It includes details about the repository, date, and a nested response indicating the qualification status of the contribution which is DailyContributionResponse Class.
strstrstrDailyContributionResponseThe DailyContributionResponse class is another dataclass to store information about a user's daily contribution response returned by OPENAI API for specific repository. It includes details about the contribution's qualification status and an AI explanation for it.
This class can be used to initalize and use database management. Explained here
Scripts Explanation
Helper functions explanations
This database management script provides functionalities to manage user data and AI decisions in a MongoDB database. It supports creating, reading, updating, and deleting user records, as well as managing AI decisions and contribution data associated with users.
Discord Bot for interacting with Google Sheets and data received from Github Scraper Bot to Mongo DB.
Explained here.
Additionally, need to enable google drive api to use sheet sharing functionality. username variables are discord handles.
/commits-sheet-createDescription: Creates a Google Sheet with contributions data.
Usage:
/commits-sheet-create spreadsheet_name: <name> email_address: <optional email>
/commits-sheet-updateDescription: Updates the Google Sheet with the latest contributions data in the Mongo DB.
Usage:
/commits-sheet-update spreadsheet_id: <id>
/leaderboard-createDescription: Creates and updates a leaderboard sheet in the specified sheet for a specific month by using current data. If spreadsheet_id is empty it will use the last created or updated sheet id. After creating the leaderboard, it will send the leaderboard to discord channel as message. If the leaderboard exists for specified date, it updates the leaderboard.
Usage:
/leaderboard-create spreadsheet_id: <optional id> date: <YYYY-MM>
/leaderboard-viewDescription: Displays the leaderboard in the specified Discord Forum thread.
Usage:
/leaderboard-view thread_id: <THREAD_ID> date: <YYYY-MM>
/main-sheet-editDescription: Creates a modal to edit the Google Sheet which includes commits data from Discord.
Usage:
/main-sheet-edit operation: <operation>
insert for adding new user, update to update user data, add_repo to add repository, delete the user data./leaderboard-start-auto-postDescription: Automatically posts the leaderboard and updates the sheet with given id every day at a specified time.
Usage:
/leaderboard-start-auto-post date: <YYYY-MM> time: <HH:MM> spreadsheet_id: <optional id>
/leaderboard-stop-auto-postDescription: Stops the auto-post leaderboard task started for a specific date.
Usage:
/leaderboard-stop-auto-post date: <YYYY-MM>
/leaderboard-closure-monthDescription: Opens a thread that includes the Leaderboard for the month. Gets the forum channel ID from the .env file and exports the user data which contributed in the given month as csv.
Usage:
/leaderboard-closure-month date: <YYYY-MM> commit_filter: <commit_filter>
/get-monthly-streaksDescription: Gets monthly streaks of users and creats thread to forum channel.
Usage:
/get-monthly-streaks date: <YYYY-MM>
/get-members-and-insert-to-dbDescription: Gets and inserts all members of the guild to the db in new collection with their username and discord id.
Usage:
/get-members-and-insert-to-db
/run-taskDescription: Uses the Github Tracker Bot API /run-task endpoint.
Usage:
/run-task since: <since> until: <until>
Note: It is okay to get An Error Occured message after some time in the discord because the API request will take long time.
/run-task-for-userDescription: Uses the Github Tracker Bot API /run-task-for-user endpoint.
Usage:
/run-task-for-user username: <username> since: <since> until: <until>
/control-schedulerDescription: Uses the Github Tracker Bot API /control-scheduler endpoint to control the scheduler (start/stop) with an optional interval.
Usage:
/control-scheduler action: <action> interval: <interval>
start or stop/get-ai-decisions-by-userDescription: Exports AI decisions as csv file for specific user between given dates.
Usage:
/get-ai-decisions-by-user username: <username> since: <since> until: <until>
/get-all-data-to-csvDescription: Exports all database user data to csv file.
Usage:
/get-all-data-to-csv
/get-blockchain-summaryDescription: Fetchs MINA Explorer Rest api and sends blockchain summary as a message
Usage:
/get-blockchain-summary
/get-user-monthly-data-to-csvDescription: Export a specific user's monthly qualified contribution data for each day of a month
Usage:
/get-user-monthly-data-to-csv username: <username> date: <date>
/delete-all-dataDescription: Deletes all data between specific dates
Usage:
/delete-all-data from: <from> until: <until>
After using this command, there will be a modal to confirm the deletion process. In order to confirm the deletion, you need to enter your discord username and exact same dates with the command. Warning : This process cannot be reverted.
To make a contribution, follow these steps:
Leaderboard Updates: Ranks contributors based on predefined metrics (KPI): 10+ days of qualified commits within a month.