[feature] Add GitHub Agent (SuperTool) integration module

Author: smokeyScraper

backend/app/agents/devrel/github/github_toolkit.py

@@ -0,0 +1,134 @@
+import logging
+from typing import Dict, Any
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.messages import HumanMessage
+from app.core.config import settings
+from .prompts.intent_analysis import GITHUB_INTENT_ANALYSIS_PROMPT
+from .tools.search import handle_web_search
+# TODO: Implement all tools
+# from .tools.contributor_recommendation import handle_contributor_recommendation
+# from .tools.repository_query import handle_repo_query
+# from .tools.issue_creation import handle_issue_creation
+# from .tools.documentation_generation import handle_documentation_generation
+from .tools.general_github_help import handle_general_github_help
+logger = logging.getLogger(__name__)
+
+
+class GitHubToolkit:
+    """
+    GitHub Toolkit - Main entry point for GitHub operations
+
+    This class serves as both the intent classifier and execution coordinator.
+    It thinks (classifies intent) and acts (delegates to appropriate tools).
+    """
+
+    def __init__(self):
+        self.llm = ChatGoogleGenerativeAI(
+            model=settings.github_agent_model,
+            temperature=0.1,
+            google_api_key=settings.gemini_api_key
+        )
+        self.tools = [
+            "web_search",
+            "contributor_recommendation",
+            "repo_support",
+            "issue_creation",
+            "documentation_generation",
+            "find_good_first_issues",
+            "general_github_help"
+        ]
+
+    async def classify_intent(self, user_query: str) -> Dict[str, Any]:
+        """
+        Classify intent and return classification with reasoning.
+
+        Args:
+            user_query: The user's request or question
+
+        Returns:
+            Dictionary containing classification, reasoning, and confidence
+        """
+        logger.info(f"Classifying intent for query: {user_query[:100]}")
+
+        try:
+            prompt = GITHUB_INTENT_ANALYSIS_PROMPT.format(user_query=user_query)
+            response = await self.llm.ainvoke([HumanMessage(content=prompt)])
+
+            import json
+            result = json.loads(response.content.strip())
+
+            classification = result.get("classification")
+            if classification not in self.tools:
+                logger.warning(f"Returned invalid function: {classification}, defaulting to general_github_help")
+                classification = "general_github_help"
+                result["classification"] = classification
+
+            result["query"] = user_query
+
+            logger.info(f"Classified intent as for query: {user_query} is: {classification}")
+            logger.info(f"Reasoning: {result.get('reasoning', 'No reasoning provided')}")
+            logger.info(f"Confidence: {result.get('confidence', 'unknown')}")
+
+            return result
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Error parsing JSON response from LLM: {str(e)}")
+            logger.error(f"Raw response: {response.content}")
+            return {
+                "classification": "general_github_help",
+                "reasoning": f"Failed to parse LLM response: {str(e)}",
+                "confidence": "low",
+                "query": user_query
+            }
+        except Exception as e:
+            logger.error(f"Error in intent classification: {str(e)}")
+            return {
+                "classification": "general_github_help",
+                "reasoning": f"Error occurred during classification: {str(e)}",
+                "confidence": "low",
+                "query": user_query
+            }
+
+    async def execute(self, query: str) -> Dict[str, Any]:
+        """
+        Main execution method - classifies intent and delegates to appropriate tools
+        """
+        logger.info(f"Executing GitHub toolkit for query: {query[:100]}")
+
+        try:
+            intent_result = await self.classify_intent(query)
+            classification = intent_result["classification"]
+
+            logger.info(f"Executing {classification} for query")
+
+            if classification == "contributor_recommendation":
+                result = "Not implemented"
+                # result = await handle_contributor_recommendation(query)
+            elif classification == "repo_support":
+                result = "Not implemented"
+                # result = await handle_repo_query(query)
+            elif classification == "issue_creation":
+                result = "Not implemented"
+                # result = await handle_issue_creation(query)
+            elif classification == "documentation_generation":
+                result = "Not implemented"
+                # result = await handle_documentation_generation(query)
+            elif classification == "web_search":
+                result = await handle_web_search(query)
+            else:
+                result = await handle_general_github_help(query, self.llm)
+
+            result["intent_analysis"] = intent_result
+            result["type"] = "github_toolkit"
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Error in GitHub toolkit execution: {str(e)}")
+            return {
+                "status": "error",
+                "type": "github_toolkit",
+                "query": query,
+                "error": str(e),
+                "message": "Failed to execute GitHub operation"
+            }

backend/app/agents/devrel/github/prompts/general_github_help.py

@@ -0,0 +1,24 @@
+GENERAL_GITHUB_HELP_PROMPT = """You are a GitHub DevRel expert assistant. Provide helpful guidance for this GitHub-related query.
+
+USER QUERY: {query}
+
+{search_context}
+
+FORMATTING REQUIREMENTS:
+- Use simple numbered lists (1. 2. 3.) instead of markdown bullets
+- Avoid complex markdown formatting like **bold** or *italic*  
+- Use plain text with clear line breaks
+- Format links as plain URLs: https://example.com
+- Use simple emojis
+- Keep paragraphs short and scannable
+- Avoid complex markdown formatting
+
+Provide a comprehensive, helpful response that:
+1. Directly addresses their question using your GitHub expertise
+2. Incorporates relevant information from the web search results above
+3. Offers practical next steps and actionable advice
+4. Suggests related GitHub features or best practices  
+5. Provides examples or code snippets when relevant
+6. Format for readability - clean, simple text
+
+Be conversational and actionable. Focus on being genuinely helpful for their GitHub needs."""

backend/app/agents/devrel/github/prompts/intent_analysis.py

@@ -0,0 +1,29 @@
+GITHUB_INTENT_ANALYSIS_PROMPT = """You are an expert GitHub DevRel AI assistant. Analyze the user query and classify the intent.
+
+AVAILABLE FUNCTIONS:
+- web_search: Search the web for information  
+- contributor_recommendation: Finding the right people to review PRs, assign issues, or collaborate
+- repo_support: Questions about codebase structure, dependencies, impact analysis, architecture
+- issue_creation: Creating bug reports, feature requests, or tracking items
+- documentation_generation: Generating docs, READMEs, API docs, guides, or explanations
+- find_good_first_issues: Finding beginner-friendly issues to work on across repositories
+- general_github_help: General GitHub-related assistance and guidance
+
+USER QUERY: {user_query}
+
+Classification guidelines:
+- contributor_recommendation: Finding reviewers, assignees, collaborators
+- repo_support: Code structure, dependencies, impact analysis, architecture  
+- issue_creation: Creating bugs, features, tracking items
+- documentation_generation: Docs, READMEs, guides, explanations
+- find_good_first_issues: Beginners, newcomers, "good first issue"
+- web_search: General information needing external search
+- general_github_help: General GitHub questions not covered above
+
+CRITICAL: Return ONLY raw JSON. No markdown, no code blocks, no explanation text.
+
+{{
+  "classification": "function_name_from_list_above",
+  "reasoning": "Brief explanation of why you chose this function",
+  "confidence": "high|medium|low"
+}}"""

backend/app/agents/devrel/tools/github_query.py renamed to backend/app/agents/devrel/github/tools/__init__.py

@@ -0,0 +1 @@
+

backend/app/agents/devrel/github/tools/contributor_recommendation.py

@@ -0,0 +1 @@
+

backend/app/agents/devrel/github/tools/documentation_generation.py

@@ -0,0 +1,50 @@
+from typing import Dict, Any
+import logging
+from langchain_core.messages import HumanMessage
+from app.agents.devrel.nodes.handlers.web_search import _extract_search_query
+from .search import handle_web_search
+from ..prompts.general_github_help import GENERAL_GITHUB_HELP_PROMPT
+
+logger = logging.getLogger(__name__)
+
+
+async def handle_general_github_help(query: str, llm) -> Dict[str, Any]:
+    """Execute general GitHub help with web search and LLM knowledge"""
+    logger.info("Providing general GitHub help")
+
+    try:
+        query = await _extract_search_query(query, llm)
+        search_result = await handle_web_search(query)
+
+        if search_result.get("status") == "success":
+            search_context = "SEARCH RESULTS:\n"
+            for result in search_result.get("results", []):
+                search_context += f"- {result.get('title', 'No title')}: {result.get('content', 'No content')}\n"
+        else:
+            search_context = "No search results available."
+
+        help_prompt = GENERAL_GITHUB_HELP_PROMPT.format(
+            query=query,
+            search_context=search_context
+        )
+
+        response = await llm.ainvoke([HumanMessage(content=help_prompt)])
+
+        return {
+            "status": "success",
+            "sub_function": "general_github_help",
+            "query": query,
+            "response": response.content.strip(),
+            "search_context": search_context,
+            "message": "Provided GitHub help using LLM expertise and web search"
+        }
+
+    except Exception as e:
+        logger.error(f"Error in general GitHub help: {str(e)}")
+        return {
+            "status": "error",
+            "sub_function": "general_github_help",
+            "query": query,
+            "error": str(e),
+            "message": "Failed to provide general GitHub help"
+        }

backend/app/agents/devrel/github/tools/general_github_help.py

@@ -0,0 +1 @@
+

backend/app/agents/devrel/github/tools/issue_creation.py

@@ -0,0 +1,41 @@
+import logging
+from typing import Dict, Any
+from app.agents.devrel.tools.search_tool import TavilySearchTool
+logger = logging.getLogger(__name__)
+
+
+async def handle_web_search(query: str) -> Dict[str, Any]:
+    """Handle web search using Tavily search tool"""
+    logger.info("Handling web search request")
+
+    try:
+        search_tool = TavilySearchTool()
+        search_results = await search_tool.search(query, max_results=5)
+
+        if not search_results:
+            return {
+                "status": "no_results",
+                "sub_function": "web_search",
+                "query": query,
+                "message": "No web search results found for the query",
+                "results": []
+            }
+
+        return {
+            "status": "success",
+            "sub_function": "web_search",
+            "query": query,
+            "results": search_results,
+            "total_results": len(search_results),
+            "message": f"Found {len(search_results)} web search results"
+        }
+
+    except Exception as e:
+        logger.error(f"Error in web search: {str(e)}")
+        return {
+            "status": "error",
+            "sub_function": "web_search",
+            "query": query,
+            "error": str(e),
+            "message": "Failed to perform web search"
+        }