feat: Add GitBit intelligent issue bot

Author: LMLK-seal

.gitbit.yml

@@ -0,0 +1,41 @@
+# .gitbit.yml
+
+# --- Smart Tagging Configuration ---
+# Map labels to keywords. The bot will suggest a label if an issue's
+# title or body contains any of the associated keywords.
+tag_keywords:
+  bug:
+    - error
+    - exception
+    - traceback
+    - panic
+    - crash
+    - fail
+  documentation:
+    - docs
+    - readme
+    - help
+    - example
+    - tutorial
+  feature-request:
+    - feature
+    - enhance
+    - improvement
+    - idea
+  question:
+    - how to
+    - what is
+    - why
+
+# --- Assignee Recommendation Configuration ---
+# The number of recently closed issues to scan to build an expertise profile.
+# A higher number is more accurate but slower.
+assignee_rec:
+  max_issues_to_scan: 100
+
+# --- Issue Linking Configuration ---
+# The similarity score required to consider an issue "related".
+# Value should be between 0.0 and 1.0. Higher is more strict.
+# A good starting point is 0.7.
+issue_linking:
+  similarity_threshold: 0.7

.github/workflows/gitbit_bot.yml

@@ -0,0 +1,32 @@
+# .github/workflows/gitbit_bot.yml
+
+name: GitBit Bot
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  run-gitbit:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run GitBit Bot
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_EVENT_PATH: ${{ github.event_path }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: python gitbit/main.py

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 [Your Name or Organization Here]
+
+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.

README.md

@@ -0,0 +1,82 @@
+# GitBit: Intelligent Issue Management Bot for GitHub
+
+ <!-- You can create a simple logo -->
+
+GitBit is a Python-based GitHub bot that streamlines issue management for repository maintainers. It uses natural language processing (NLP) and machine learning to automate repetitive tasks, making it an invaluable tool for managing large open-source projects.
+
+## Key Features
+
+-   **🤖 Automatic Issue Linking:** Analyzes new issue descriptions to detect and link semantically related or duplicate issues, reducing clutter and improving organization.
+-   **🏷️ Smart Tagging:** Suggests relevant labels (e.g., `bug`, `documentation`, `feature-request`) based on the issue's content, ensuring consistent and meaningful categorization.
+-   **👤 Assignee Recommendations:** Recommends contributors to assign issues to, based on their past contributions and expertise demonstrated in previously closed issues.
+
+## Why It’s Unique
+
+While there are many tools for GitHub automation, GitBit combines NLP and machine learning to provide **intelligent, context-aware suggestions** tailored to each repository. Its focus on issue management—a critical yet time-consuming task—sets it apart from generic bots or static analysis tools.
+
+## How It Works
+
+GitBit is deployed as a GitHub Action that triggers whenever a new issue is opened in your repository. Here's the process:
+
+1.  **Trigger:** A new issue is created.
+2.  **Analysis:** The bot reads the issue's title and body.
+3.  **Processing:**
+    *   It compares the new issue's text to a keyword map in your config file to suggest labels.
+    *   It scans recently closed issues to find which users are experts on topics related to the suggested labels.
+    *   It uses TF-IDF vectorization and cosine similarity to find other open issues with similar content.
+4.  **Comment:** The bot posts a single, helpful comment on the new issue with all its suggestions, allowing maintainers to review and apply them with a single click.
+
+---
+
+## 🚀 Setup Instructions
+
+Setting up GitBit takes less than 5 minutes.
+
+### Step 1: Create the Configuration File
+
+In the root of your repository, create a file named `.gitbit.yml`. This file controls the bot's behavior.
+
+**Copy and paste this template into `.gitbit.yml` and customize it for your project:**
+
+```yaml
+# .gitbit.yml
+
+# --- Smart Tagging Configuration ---
+# Map labels to keywords. The bot will suggest a label if an issue's
+# title or body contains any of the associated keywords.
+tag_keywords:
+  bug:
+    - error
+    - exception
+    - traceback
+    - panic
+    - crash
+    - fail
+  documentation:
+    - docs
+    - readme
+    - help
+    - example
+    - tutorial
+  feature-request:
+    - feature
+    - enhance
+    - improvement
+    - idea
+  question:
+    - how to
+    - what is
+    - why
+
+# --- Assignee Recommendation Configuration ---
+# The number of recently closed issues to scan to build an expertise profile.
+# A higher number is more accurate but slower.
+assignee_rec:
+  max_issues_to_scan: 100
+
+# --- Issue Linking Configuration ---
+# The similarity score required to consider an issue "related".
+# Value should be between 0.0 and 1.0. Higher is more strict.
+# A good starting point is 0.7.
+issue_linking:
+  similarity_threshold: 0.7

gitbit/__init__.py

@@ -0,0 +1,51 @@
+# gitbit/assignee.py
+
+from collections import defaultdict
+
+def recommend_assignees(repo, suggested_tags: list[str], max_issues_to_scan: int) -> list[str]:
+    """
+    Recommends assignees based on their history of closing issues with similar tags.
+
+    Args:
+        repo: The PyGithub repository object.
+        suggested_tags: A list of tags suggested for the new issue.
+        max_issues_to_scan: The number of closed issues to analyze.
+
+    Returns:
+        A list of recommended assignee usernames, sorted by relevance.
+    """
+    if not suggested_tags:
+        return []
+
+    # Build an expertise map: {label: {user: count}}
+    expertise_map = defaultdict(lambda: defaultdict(int))
+    
+    # Scan recent closed issues to build expertise profile
+    closed_issues = repo.get_issues(state='closed', sort='updated', direction='desc')
+    
+    count = 0
+    for issue in closed_issues:
+        if count >= max_issues_to_scan:
+            break
+        
+        # Only consider issues that were actually assigned and have labels
+        if issue.assignee and issue.labels:
+            for label in issue.labels:
+                expertise_map[label.name][issue.assignee.login] += 1
+        count += 1
+    
+    if not expertise_map:
+        return []
+
+    # Find best assignees for the suggested tags
+    recommendation_scores = defaultdict(int)
+    for tag in suggested_tags:
+        if tag in expertise_map:
+            # Find the top expert for this tag
+            top_expert = max(expertise_map[tag], key=expertise_map[tag].get)
+            recommendation_scores[top_expert] += 1 # Give a point to this expert
+    
+    # Sort recommended assignees by their score (how many tags they are an expert in)
+    sorted_recommendations = sorted(recommendation_scores.keys(), key=lambda user: recommendation_scores[user], reverse=True)
+    
+    return sorted_recommendations

gitbit/assignee.py

@@ -0,0 +1,71 @@
+# gitbit/bot.py
+
+import yaml
+from . import tagger, assignee, linker
+
+class GitBitBot:
+    """
+    The main bot class that orchestrates the analysis of a GitHub issue.
+    """
+    def __init__(self, repo, issue):
+        self.repo = repo
+        self.issue = issue
+        self.config = self._load_config()
+
+    def _load_config(self):
+        """Loads the .gitbit.yml configuration file from the repository root."""
+        try:
+            config_content = self.repo.get_contents(".gitbit.yml").decoded_content
+            return yaml.safe_load(config_content)
+        except Exception as e:
+            print(f"Error loading .gitbit.yml: {e}")
+            raise FileNotFoundError(".gitbit.yml not found or is invalid.")
+
+    def run(self):
+        """
+        Runs the full analysis pipeline and posts a summary comment on the issue.
+        """
+        issue_text = f"{self.issue.title} {self.issue.body}"
+
+        # 1. Suggest tags
+        suggested_tags = tagger.suggest_tags(issue_text, self.config.get('tag_keywords', {}))
+        
+        # 2. Recommend assignees
+        max_scan = self.config.get('assignee_rec', {}).get('max_issues_to_scan', 100)
+        recommended_assignees = assignee.recommend_assignees(self.repo, suggested_tags, max_scan)
+
+        # 3. Find related issues
+        threshold = self.config.get('issue_linking', {}).get('similarity_threshold', 0.7)
+        related_issues = linker.find_related_issues(self.repo, self.issue, threshold)
+
+        # 4. Format and post the comment
+        comment = self._format_comment(suggested_tags, recommended_assignees, related_issues)
+        
+        if comment:
+            self.issue.create_comment(comment)
+            print("Successfully posted suggestions to the issue.")
+        else:
+            print("No suggestions to post.")
+
+    def _format_comment(self, tags, assignees, issues):
+        """Formats the bot's findings into a clean Markdown comment."""
+        if not tags and not assignees and not issues:
+            return None
+
+        comment_parts = ["### 🤖 GitBit Bot Analysis\n\nI've analyzed this issue and have the following suggestions:\n"]
+
+        if tags:
+            tag_list = ", ".join([f"`{tag}`" for tag in tags])
+            comment_parts.append(f"**🏷️ Suggested Labels:**\n{tag_list}\n")
+
+        if assignees:
+            assignee_list = ", ".join([f"@{user}" for user in assignees])
+            comment_parts.append(f"**👤 Recommended Assignees:**\n{assignee_list} (based on their work on related issues)\n")
+        
+        if issues:
+            issue_list = "\n".join([f"- Issue #{i.number}: {i.title}" for i in issues])
+            comment_parts.append(f"**🔗 Potentially Related Issues:**\n{issue_list}\n")
+
+        comment_parts.append("---\n*I am a bot. My suggestions are based on patterns in this repository. Please review them before applying.*")
+        
+        return "\n".join(comment_parts)

gitbit/bot.py

@@ -0,0 +1,60 @@
+# gitbit/linker.py
+
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+def find_related_issues(repo, new_issue, similarity_threshold: float) -> list:
+    """
+    Finds issues that are semantically similar to a new issue.
+
+    Args:
+        repo: The PyGithub repository object.
+        new_issue: The new issue object to compare against.
+        similarity_threshold: The minimum cosine similarity score to be considered related.
+
+    Returns:
+        A list of PyGithub Issue objects that are potentially related.
+    """
+    open_issues = repo.get_issues(state='open')
+    
+    # Create a corpus of documents (issue title + body)
+    issue_map = {}
+    corpus = []
+    
+    for issue in open_issues:
+        # Exclude the new issue itself from the comparison list
+        if issue.number == new_issue.number:
+            continue
+        
+        issue_text = f"{issue.title} {issue.body}"
+        issue_map[len(corpus)] = issue # Map corpus index to issue object
+        corpus.append(issue_text)
+
+    if not corpus:
+        return [] # No other open issues to compare against
+
+    # Add the new issue's text to the end of the corpus for vectorization
+    new_issue_text = f"{new_issue.title} {new_issue.body}"
+    corpus.append(new_issue_text)
+    
+    # Vectorize the text using TF-IDF
+    try:
+        vectorizer = TfidfVectorizer(stop_words='english', min_df=1)
+        tfidf_matrix = vectorizer.fit_transform(corpus)
+    except ValueError:
+        # This can happen if the corpus is empty or contains only stop words.
+        return []
+
+    # Calculate cosine similarity between the new issue and all others
+    # The new issue is the last one in the matrix
+    cosine_sim = cosine_similarity(tfidf_matrix[-1], tfidf_matrix[:-1])
+    
+    # Find issues that exceed the similarity threshold
+    related_issues = []
+    similar_indices = cosine_sim[0].argsort()[:-5:-1] # Get top 4 most similar indices
+
+    for i in similar_indices:
+        if cosine_sim[0][i] > similarity_threshold:
+            related_issues.append(issue_map[i])
+            
+    return related_issues