contribcast 0.1.1

AI-powered GitHub contribution forecasting and automation agent

---

# 📈 Contribcast

**AI-powered GitHub contribution forecasting, issue suggestion, and productivity assistant — straight from your terminal.**

---

## 🚀 What is Contribcast?

`contribcast` is a Python CLI tool that helps developers:

- Forecast and visualize their GitHub contributions 📊  
- Get weekly reflection and motivational insights from AI 🧠  
- Discover trending beginner-friendly issues tailored to your stack 🔍  
- Automatically draft and submit PRs to practice contributing 💻  
- Schedule Slack reminders and generate dynamic README.md files 📝  
- Empower both beginner and advanced developers to stay consistent

Whether you're new to open source or a seasoned contributor, Contribcast keeps your contribution game strong, organized, and automated.

---

## 📦 Features at a Glance

| Category | Features |
|----------|----------|
| 📊 Analytics | `--forecast`, `--heatmap`, `--streak`, `--weekly-summary`, `--compare` |
| 🧠 Smart AI Insights | `--reflect`, `--goal`, `--suggest`, `--domain ai/react`, `--generate-readme` |
| 🔍 Issue Discovery | `--suggest-issue`, `--auto-pr`, `--domain`, `--schedule-weekly` |
| 🛠️ Productivity | `--export-csv`, `--export-json`, `--save-heatmap`, `--notify-user` |
| 🤖 Automation | Draft PRs to GitHub issues, generate README.md using AI |
| 💬 Team Tools | Slack DM fallback, weekly drops to your team’s Slack channel |

---

## ✅ Requirements

- **Python 3.11+**
- A GitHub personal access token with `repo` scope
- An OpenAI API key
- A Slack bot token (if using Slack integration)

---

## 🔐 Environment Variables

Before using Contribcast, create a `.env` file or export these in your terminal:

```bash
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_USERNAME=your_github_username
export OPENAI_API_KEY=sk-proj-7p0_STw-Dp
export SLACK_BOT_TOKEN=xoxb-your-slack-token
export SLACK_CHANNEL=#your-slack-channel
export WHATSAPP_TO=whatsapp:+234xxxxxxxxxx  # Optional
export TWILIO_SID=your_twilio_sid
export TWILIO_AUTH=your_twilio_auth_token

---

🔧 Installation

git clone https://github.com/adesoji1/contribcast.git
cd contribcast
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

To run globally (optional):

pip install .

or

pip install contribcast

---

🧠 Examples

Forecast Contributions

contribcast githubusername--forecast

Visualize Your GitHub Heatmap

contribcast githubusername--heatmap

Get Weekly Reflection from AI

contribcast githubusername--reflect --notify-user @adesoji

Discover Trending Issues + Auto PR

contribcast githubusername--suggest-issue --auto-pr auto

Generate README for Your Local Project

contribcast githubusername--generate-readme

Compare Contributions between 2 different github ussers

contribcast adesoji1 --compare malcolmtomisin

👤 GitHub Username: adesoji1
📅 Contributions so far: 424


📊 Comparing adesoji1 vs malcolmtomisin

Total Contributions: adesoji1 = 424 | malcolmtomisin = 168
Forecasted Yearly:  adesoji1 = 1406 | malcolmtomisin = 557
Current Streak:     adesoji1 = 3 days | malcolmtomisin = 1 days
Longest Streak:     adesoji1 = 9 days | malcolmtomisin = 5 days  ,   

Replace adesoji1 and malcolmtomisin with your 2 different GitHub usernames.

Other CLI Commands

contribcast githubusername --forecast
contribcast githubusername --heatmap
contribcast githubusername --save-heatmap
contribcast githubusername --weekly-summary
contribcast githubusername --streak
contribcast githubusername --compare someoneelse
contribcast githubusername --suggest

---

🧠 Why Contribcast?

🔥 For New Developers:

• Discover beginner-friendly issues in trending repos
• Automatically generate your first PRs with guidance
• Get motivational nudges to build consistency

💼 For Experienced Developers:

• Monitor contribution trends across your team
• Automate contribution goals with AI planning
• Save time with weekly Slack drops and batch automation

---

🗓️ Optional: Schedule Weekly Suggestions

Run once (e.g. with cron or tmux):

python3 contribcast/scheduler.py

This sends weekly issue suggestions to your Slack every Monday at 09:00 AM.

---

📚 See All CLI Commands

contribcast githubusername--commands

---

🧪 Testing Your Setup

To validate that everything works:

contribcast githubusername--forecast
contribcast githubusername--suggest-issue --auto-pr auto
contribcast githubusername--generate-readme

If these commands succeed, you're all set, don't forget to replace githubusernamewith your github username, !

---

🧠 Powered By

• 🧠 LangChain
• 🔍 GitHub REST & GraphQL APIs
• 💬 OpenAI GPT-3.5-turbo
• 📡 Twilio
• Slack SDKs

---

💡 Future Roadmap

• Auto-plan contributions weekly
• Multi-user comparison dashboard
• GitHub Action integration
• Telegram notifications
• VSCode extension for inline usage

---

✨ Author

Made with ❤️ by Adesoji Alu

Feel free to contribute or fork. Keep contributing and cast your commit spells 🧙🏽‍♂️✨

---

📜 License

MIT License

Copyright (c) 2025 Adesoji Alu

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.

ERRORS

You might be faced with openai.RateLimitError: Error code: 429 , slack or whatsapp token error if you pass in the wrong credentials