{"id":28715502,"url":"https://github.com/amberlee2427/brian-bot","last_synced_at":"2026-04-24T23:32:10.327Z","repository":{"id":298148560,"uuid":"998098035","full_name":"AmberLee2427/brian-bot","owner":"AmberLee2427","description":"     A Discord bot for D\u0026D servers with OpenAI integration, character sheet management, dice rolling, and more. Built with Python and designed for security and ease of use.","archived":false,"fork":false,"pushed_at":"2025-06-09T17:20:27.000Z","size":799,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-09T17:36:44.737Z","etag":null,"topics":["character-sheet","dice","dice-roller","dice-rolls","discord-bot","discord-bots","dnd","dnd-tools","dnd5e","dnd5e-tools","open-source","openai","opensource","python","python-3","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AmberLee2427.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T21:24:09.000Z","updated_at":"2025-06-09T17:20:31.000Z","dependencies_parsed_at":"2025-06-09T17:46:48.164Z","dependency_job_id":null,"html_url":"https://github.com/AmberLee2427/brian-bot","commit_stats":null,"previous_names":["amberlee2427/brian-bot"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/AmberLee2427/brian-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fbrian-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fbrian-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fbrian-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fbrian-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AmberLee2427","download_url":"https://codeload.github.com/AmberLee2427/brian-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AmberLee2427%2Fbrian-bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259910742,"owners_count":22930713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["character-sheet","dice","dice-roller","dice-rolls","discord-bot","discord-bots","dnd","dnd-tools","dnd5e","dnd5e-tools","open-source","openai","opensource","python","python-3","python3"],"created_at":"2025-06-15T02:10:15.052Z","updated_at":"2026-04-24T23:32:10.289Z","avatar_url":"https://github.com/AmberLee2427.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Brian Bot\n\nA helpful Discord assistant built with Python and OpenAI. Brian is designed to be a secure, efficient, and friendly bot that can help manage and interact with your Discord server.\n\n![A cute imp wearing a nametag that says \"Brian\"](Brian1.png)\n\n## Features\n\n- **Natural Conversations**: Chat with Brian using natural language\n- **Channel Summarization**: Get quick summaries of channel discussions\n- **Message Search**: Find specific messages across configured channels\n- **Security First**: Built with security best practices including rate limiting and input sanitization\n- **Multi-bot Friendly**: Properly handles conversations with other bots\n\n## Setup\n\n### Prerequisites\n\n1. **Create a Discord Bot:**\n   - Go to [Discord Developer Portal](https://discord.com/developers/applications)\n   - Click \"New Application\" and give it a name\n   - Add the `Brain1.png` or `Brain2.png` image as Brian's profile pic\n   - Go to the \"Installation\" tab and select `None` for the Install link\n   - Go to the \"Bot\" tab and turn of the \"PUBLIC BOT\" toggle\n   - Under \"Privileged Gateway Intents\", enable:\n     - MESSAGE CONTENT INTENT\n     - SERVER MEMBERS INTENT\n   - Copy the bot token and save it somewhere secure (you'll need this for the `.env` file)\n   - Go to OAuth2 \u003e URL Generator\n   - Select scopes: `bot` and `applications.commands`\n   - Select bot permissions:\n     - Read Messages/View Channels\n     - Send Messages\n     - Read Message History\n     - Add Reactions\n     - Use Slash Commands\n   - Copy the generated URL and paste in into a new tab to invite the bot to your server\n\n2. **Get an OpenAI API Key:**\n   - Go to [OpenAI Platform](https://platform.openai.com)\n   - Sign up or log in\n   - Go to API Keys section\n   - Click \"Create new secret key\"\n   - Copy the API key (you'll need this for the `.env` file)\n   - Note: The API key starts with \"sk-\" and is used for billing\n   - Note: You will likely need to prepay for tokens. Add a small amount of credit e.g. $5. You may be able to sell you data to OpenAI for $120 of credits a month, but not until you are on the appropriate member tier. So pay for a few calls and then consider selling your D\u0026D anticts for effectively unlimited API usage. \n   - Note: Monitor this account for unexpected activity and reset your tokens if you are suspicious.\n\n### Local Development\n\n1. **Fork and Clone the Repository:**\n   Fork this repository to your GitHub account by clicking the \"Fork\" button at the top of the page.\n   \n   Clone the repo locally:\n   ```bash\n   git clone https://github.com/yourusername/brian-bot.git\n   cd brian-bot\n   ```\n   We recommend you \"Watch\" the repo in order to be notified of updates\n     - Click the \"Watch\" button at the top of the repository\n     - Select \"Custom\" to configure notifications\n     - Enable notifications for:\n       - \"Releases\" (when new versions are published)\n       - \"Discussions\" (for community support)\n       - \"Security alerts\" (for important security updates)\n     - Click \"Apply\" to save your preferences\n\n3. **Create a `.env` file:**\n   In the same directory, create a file named `.env` and add your secret keys:\n   ```\n   # Required\n   DISCORD_TOKEN=your_discord_bot_token_goes_here\n   OPENAI_API_KEY=your_openai_api_key_goes_here\n   \n   # Optional (with defaults)\n   SESSION_NOTES_CHANNEL=your-session-notes-channel-name  # Default: session-notes\n   DATA_DIR=characters  # Default: characters\n   COMMAND_PREFIX=!  # Default: !\n   MODEL_NAME=gpt-4  # Default: gpt-4\n   MAX_TOKENS_FOR_RESPONSE=1500  # Default: 1500\n   RATE_LIMIT_MENTIONS=5  # Default: 5 mentions per minute\n   RATE_LIMIT_COMMANDS=10  # Default: 10 commands per minute\n   RATE_LIMIT_WINDOW=60  # Default: 60 seconds\n   \n   # Channel and Role Configuration\n   SEARCHABLE_CHANNEL_IDS=123456789012345678,876543210987654321  # Comma-separated list of channel IDs for !find command\n   ALLOWED_ROLES=123456789012345678,876543210987654321  # Comma-separated list of role IDs that can use restricted commands\n   ADMIN_ROLES=123456789012345678,876543210987654321  # Comma-separated list of role IDs with admin privileges\n   ```\n\n   After creating the `.env` file, secure it with:\n   ```bash\n   chmod 600 .env\n   ```\n   This ensures only your user can read and write to the file.\n\n4. **Install Dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n5. **Run the Bot:**\n   ```bash\n   python main.py\n   ```\n\n### Railway Deployment\n\n1. **Create Required Accounts:**\n   - Sign up for a [GitHub account](https://github.com/signup) if you don't have one\n   - Sign up at [Railway.app](https://railway.app)\n   - Install the Railway CLI (optional)\n\n2. **Fork and Clone:**\n   - Fork this repository to your GitHub account by clicking the \"Fork\" button at the top of the page\n   - We recommend you \"Watch\" the repo in order to be notified of updates\n     - Click the \"Watch\" button at the top of the repository\n     - Select \"Custom\" to configure notifications\n     - Enable notifications for:\n       - \"Releases\" (when new versions are published)\n       - \"Discussions\" (for community support)\n       - \"Security alerts\" (for important security updates)\n     - Click \"Apply\" to save your preferences\n\n3. **Deploy to Railway:**\n   - Create a new project in Railway\n   - Connect your GitHub account if not already connected\n   - Select your forked repository\n     - If the repo isn't showing up under the GitHub options: \n       - Scroll to the bottom of the page and select \"Empty Project\"\n       - Select \"Add a service\" \u003e \"GitHub Repo\" \u003e \"Configure GitHub App\" \u003e \u003cyour account\u003e\n       - You may need to Authenticate to continue\n       - Under \"Repository Access\", select either:\n         * \"All repositiories\" or \n         * \"Only select repositories\" and choose \"brain-bot\" from the dropdown list\n      - \"Save\"\n   - Add the following environment variables in Railway:\n     - Where:\n       - In \"Architecture\" view in your project space, click on the `brain-bot` box\n       - Select the \"Variables\" tab\n       - `New Variable`\n       - Paste or type in the relevant content.\n     - Required:\n       - `DISCORD_TOKEN`: Your Discord bot token\n       - `OPENAI_API_KEY`: Your OpenAI API key\n     - Optional (with defaults):\n       - `SESSION_NOTES_CHANNEL`: The name of your session notes channel (without the #)\n       - `DATA_DIR`: (Optional, recommended) Custom directory for character sheets\n       - `COMMAND_PREFIX`: Bot command prefix (default: !)\n       - `MODEL_NAME`: OpenAI model to use (default: gpt-4)\n       - `MAX_TOKENS_FOR_RESPONSE`: Maximum tokens for AI responses (default: 1500)\n       - `RATE_LIMIT_MENTIONS`: Mentions allowed per minute (default: 5)\n       - `RATE_LIMIT_COMMANDS`: Commands allowed per minute (default: 10)\n       - `RATE_LIMIT_WINDOW`: Rate limit window in seconds (default: 60)\n     - Channel and Role Configuration:\n       - `SEARCHABLE_CHANNEL_IDS`: Comma-separated list of channel IDs for the !find command\n       - `ALLOWED_ROLES`: Comma-separated list of role IDs that can use restricted commands\n       - `ADMIN_ROLES`: Comma-separated list of role IDs with admin privileges\n     - Secure the Token and API Key variables by selecting the triple dot and `Seal`, if the option is available.\n\n4. **Configure the Bot:**\n   - The bot will automatically deploy when you push to the main branch (this could take a few minutes)\n   - Monitor the deployment in the Railway dashboard\n   - Check the logs for any issues\n\n5. **Updating the Bot:**\n   - Push changes to your repository or \"Sync Fork\" with the main repo\n   - Railway will automatically redeploy\n   - Monitor the deployment status in the dashboard\n\n### Setting Up Persistent Storage (Optional but Recommended)\n\nTo ensure your character sheets persist across deployments and restarts, you can set up a storage service on Railway:\n\n1. **Add Storage Service:**\n   - In your Railway project dashboard, click \"New\"\n   - Select \"Storage\" from the service options\n   - Choose a name for your storage service (e.g., \"brian-storage\")\n\n2. **Configure Storage:**\n   - Once created, Railway will provide a mount path\n   - Add this environment variable to your bot service:\n     ```\n     DATA_DIR=/data/characters\n     ```\n   - This will store character sheets in the persistent storage volume\n\n3. **Verify Setup:**\n   - Deploy your bot\n   - Create a character sheet using `!coin` or by mentioning Brian\n   - Check the `/data/characters` directory in your storage service\n   - Your character sheets should persist even if the bot restarts\n\nNote: If you don't set up persistent storage, character sheets will be stored in the bot's ephemeral filesystem and will be lost when the bot restarts or redeploys.\n\n## Usage\n\n* **Chat:** Mention `@Brian` in a message to start a conversation\n* **Summarize:** Use `!summarize #channel-name` to get a summary of that channel\n* **Recap:** Use `!recap` for a quick summary of your session notes channel\n* **Find:** Use `!find your search query` to look for messages in configured channels\n\n## Security Features\n\n- Rate limiting to prevent abuse\n- Input sanitization for all user inputs\n- Role-based access control\n- API key validation\n- Secure error handling\n- Message length limits\n\n## Troubleshooting\n\n1. **Bot not responding:**\n   - Check if the bot is online\n   - Verify API keys in `.env` or Railway environment variables\n   - Check bot permissions in Discord\n\n2. **Commands not working:**\n   - Ensure the bot has necessary permissions\n   - Check if you have the required roles\n   - Verify channel permissions\n\n3. **Rate limiting:**\n   - Wait 60 seconds before trying again\n   - Contact server admin if persistent\n\n4. **Railway Deployment Issues:**\n   - Check Railway logs for errors\n   - Verify environment variables are set correctly\n   - Ensure the Procfile and runtime.txt are present\n   - Check if the build process completed successfully\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.\n\n## Security\n\nIf you discover any security-related issues, please email [your-email] instead of using the issue tracker.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- OpenAI for the GPT API\n- Discord.py for the Discord API wrapper\n- All contributors who have helped improve Brian\n\n## Release Notes\n\nInitial release of Brian Bot, a Discord bot for D\u0026D servers with the following features:\n\n- Natural language conversations with OpenAI integration\n- Character sheet management\n- Dice rolling\n- Channel summarization\n- Message search\n- Session notes tracking\n- Rate limiting and security features\n\nKey Features:\n- Default character sheet template\n- Persistent storage support\n- Configurable through environment variables\n- Railway deployment support\n- Comprehensive documentation\n\nThis is the first stable release of Brian Bot. All features are fully functional and documented.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberlee2427%2Fbrian-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famberlee2427%2Fbrian-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberlee2427%2Fbrian-bot/lists"}