contribcast 0.1.0

AI-powered GitHub contribution forecasting and automation agent

Here's your comprehensive, professional-grade README.md for contribcast — tailored to appeal to both new and experienced developers:

---

# 📈 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/your-username/contribcast.git
cd contribcast
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

To run globally (optional):

pip install .

---

🧠 Examples

Forecast Contributions

contribcast adesoji1 --forecast

Visualize Your GitHub Heatmap

contribcast adesoji1 --heatmap

Get Weekly Reflection from AI

contribcast adesoji1 --reflect --notify-user @adesoji

Discover Trending Issues + Auto PR

contribcast adesoji1 --suggest-issue --auto-pr auto

Generate README for Your Local Project

contribcast adesoji1 --generate-readme

Replace adesoji1 with your GitHub username.

---

🧠 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):

python contribcast/scheduler.py

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

---

📚 See All CLI Commands

contribcast adesoji1 --commands

---

🧪 Testing Your Setup

To validate that everything works:

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

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

---

🧠 Powered By

• 🧠 LangChain
• 🔍 GitHub REST & GraphQL APIs
• 💬 OpenAI GPT-3.5
• 📡 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

The MIT License is a permissive open-source license that grants users broad rights to use, copy, modify, merge, publish, distribute, sublicense, and sell software, including the associated documentation, with minimal restrictions. Essentially, you're free to do almost anything with the licensed software, as long as you include the original copyright notice and license text in any distribution

ERRORS

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