Upload 7 files

.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+.env.local
+
+# Gradio
+gradio_cached_examples/
+flagged/
+
+# Logs
+*.log

README.md

@@ -0,0 +1,171 @@
+---
+title: GitNexus
+emoji: 🚀
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+---
+
+# 🚀 GitNexus
+
+**MCP-Enabled GitHub Automation for AI Agents**
+
+## 👥 Project Team
+
+| Name | Hugging Face Profile |
+|------|----------------------|
+| **Viraj Talathi** | [@Viraj77](https://huggingface.co/Viraj77) |
+| **Pranjal Prakash** | [@pranjal00](https://huggingface.co/pranjal00) |
+| **Karan Singh** | [@karansingh99](https://huggingface.co/karansingh99) |
+| **Shriprasasd Patil** | [@Shriprasad-P](https://huggingface.co/Shriprasad-P) |
+| **Bharath Nuthalapati** | [@bharath-nuthalapati](https://huggingface.co/bharath-nuthalapati) |
+
+This Hugging Face Space demonstrates GitHub automation using MCP (Model Context Protocol) tools integrated with a Gradio UI. AI agents like Claude, Cursor, and Antigravity can discover and call GitHub functions via MCP, while humans can use the intuitive web interface.
+
+## 🎯 Features
+
+### GitHub Operations
+- **Create Repository** - Create new public/private GitHub repositories
+- **List Repositories** - View all repositories for the authenticated account
+- **Create Issue** - Open issues in any repository
+- **List Issues** - View issues filtered by state (open/closed/all)
+- **Commit File** - Create or update files in repositories
+- **Read File** - Read file contents from repositories
+
+### MCP Tools for AI Agents
+The following tools are exposed via MCP for AI agent automation:
+- `github.create_repo`
+- `github.list_repos`
+- `github.create_issue`
+- `github.list_issues`
+- `github.commit_file`
+- `github.read_file`
+- `github.generate_docs_with_tts`
+
+## 🔧 Tech Stack
+
+- **Python** - Core language
+- **Gradio** - Web UI framework with MCP server support
+- **PyGithub** - GitHub API wrapper
+- **MCP** - Model Context Protocol for AI agent integration
+- **Gemini 2.5 Flash** - AI Code Analysis & Documentation
+- **ElevenLabs** - Text-to-Speech Generation
+
+## 📦 Project Structure
+
+```
+HF-Pro/
+├── app.py              # Main Gradio application with MCP handlers
+├── ghclient.py         # GitHub API client wrapper
+├── ai_helper.py        # AI Documentation & TTS helper
+├── requirements.txt    # Python dependencies
+└── README.md          # This file
+```
+
+## 🚀 Deployment to Hugging Face Spaces
+
+### Prerequisites
+1. A Hugging Face account
+2. A GitHub Personal Access Token (PAT) with repo permissions
+3. A Google Gemini API Key
+4. An ElevenLabs API Key
+
+### Steps
+
+1. **Create a new Space on Hugging Face**
+   - Go to https://huggingface.co/new-space
+   - Choose a name for your Space
+   - Select **Gradio** as the SDK
+   - Choose **Public** or **Private** visibility
+   - Click "Create Space"
+
+2. **Upload the files**
+   - Upload all 5 files from this project:
+     - `app.py`
+     - `ghclient.py`
+     - `ai_helper.py`
+     - `requirements.txt`
+     - `README.md`
+
+3. **Configure Secrets**
+   - Go to your Space settings
+   - Navigate to "Repository secrets"
+   - Add the following secrets:
+     - `GITHUB_TOKEN`: Your GitHub Personal Access Token
+     - `GEMINI_API_KEY`: Your Google Gemini API Key
+     - `ELEVENLABS_API_KEY`: Your ElevenLabs API Key
+
+4. **Wait for deployment**
+   - Hugging Face will automatically build and deploy your Space
+   - Once ready, you'll see the Gradio interface
+
+## 🎮 Usage
+
+### For Humans (Web UI)
+
+The Gradio interface has 3 tabs:
+
+**📦 Repositories Tab**
+- Create new repositories with name, privacy setting, and description
+- List all repositories for the authenticated account
+
+**📋 Issues Tab**
+- Create issues in any repository (format: `username/repo`)
+- List issues filtered by state (open/closed/all)
+
+**📄 Custom Files Tab**
+- Commit files to repositories (creates or updates)
+- Read file contents from repositories
+
+**🤖 Code Documentation Tab**
+- Upload code files for AI analysis
+- Generate comprehensive documentation
+- Listen to 2-line audio summary
+- Commit documentation to GitHub
+
+## 🔒 Security Notes
+
+- **No user authentication required** - The Space uses a server-side GitHub token
+- **All repos are public by default** - Anyone can view created repositories
+- **Repository name validation** - Input validation prevents malicious repo names
+- **Token security** - GitHub token is stored securely in HF Spaces secrets (never in code)
+
+## 🛠️ Local Development
+
+To run locally:
+
+1. **Clone the repository**
+   ```bash
+   git clone <your-space-url>
+   cd HF-Pro
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set environment variables**
+   ```bash
+   # Windows (PowerShell)
+   $env:GITHUB_TOKEN="your_github_token"
+   $env:GEMINI_API_KEY="your_gemini_key"
+   $env:ELEVENLABS_API_KEY="your_elevenlabs_key"
+   ```
+
+4. **Run the application**
+   ```bash
+   python app.py
+   ```
+
+5. **Open in browser**
+   - Navigate to `http://localhost:7860`
+
+## 📄 License
+
+MIT License - feel free to use this code for your own projects.
+
+**Built with ❤️ for AI agent automation**

ai_helper.py

@@ -0,0 +1,162 @@
+"""
+AI Helper Module
+Handles AI-powered documentation generation and text-to-speech
+"""
+
+import os
+import google.generativeai as genai
+from elevenlabs.client import ElevenLabs
+from typing import Dict, Tuple
+import re
+
+
+class AIDocumentationGenerator:
+    """AI-powered code documentation generator with TTS"""
+    
+    def __init__(self, user_gemini_key: str = None):
+        """
+        Initialize AI services with API keys
+        
+        Args:
+            user_gemini_key: Optional user-provided Gemini API key
+        """
+        # Initialize Gemini - prioritize user key, then env var
+        self.gemini_key = user_gemini_key or os.environ.get("GEMINI_API_KEY")
+        
+        if self.gemini_key:
+            genai.configure(api_key=self.gemini_key)
+            self.gemini_model = genai.GenerativeModel('gemini-2.5-flash')
+        else:
+            self.gemini_model = None
+        
+        # Initialize ElevenLabs
+        self.elevenlabs_key = os.environ.get("ELEVENLABS_API_KEY")
+        if self.elevenlabs_key:
+            self.elevenlabs_client = ElevenLabs(api_key=self.elevenlabs_key)
+        else:
+            self.elevenlabs_client = None
+    
+    def generate_documentation(self, code_content: str, language: str, filename: str) -> Dict[str, str]:
+        """
+        Generate comprehensive documentation from code using Gemini
+        
+        Args:
+            code_content: The source code to analyze
+            language: Programming language (python, javascript, etc.)
+            filename: Original filename
+            
+        Returns:
+            Dict with 'documentation' and 'summary' keys
+        """
+        if not self.gemini_model:
+            raise ValueError("Gemini API key not configured. Set GEMINI_API_KEY environment variable.")
+        
+        # Create prompt for Gemini
+        prompt = f"""Analyze this {language} code from file "{filename}":
+
+```{language}
+{code_content}
+```
+
+Generate comprehensive documentation in README markdown format with these sections:
+1. **Overview** - What this code does (2-3 sentences)
+2. **Key Components** - Main functions/classes with brief descriptions
+3. **Usage Examples** - How to use this code (with code blocks)
+4. **Dependencies** - Required libraries/packages
+5. **Installation** - Setup instructions
+
+Then provide a STRICT 2-LINE SUMMARY (maximum 2 sentences, around 150-200 characters total) that captures the essence of this code.
+
+Format your response EXACTLY like this:
+
+## Documentation
+
+[Full documentation here in markdown format]
+
+## Summary
+
+[Exactly 2 lines/sentences here - be concise and clear]
+"""
+        
+        try:
+            # Generate content with Gemini
+            response = self.gemini_model.generate_content(prompt)
+            full_response = response.text
+            
+            # Parse documentation and summary
+            parts = full_response.split("## Summary")
+            
+            if len(parts) == 2:
+                documentation = parts[0].replace("## Documentation", "").strip()
+                summary = parts[1].strip()
+                
+                # Ensure summary is max 2 lines
+                summary_lines = [line.strip() for line in summary.split('\n') if line.strip()]
+                summary = ' '.join(summary_lines[:2])
+            else:
+                # Fallback if format is not as expected
+                documentation = full_response
+                summary = self._extract_summary_fallback(full_response)
+            
+            return {
+                "documentation": documentation,
+                "summary": summary
+            }
+            
+        except Exception as e:
+            raise Exception(f"Failed to generate documentation: {str(e)}")
+    
+    def _extract_summary_fallback(self, text: str) -> str:
+        """Extract a 2-line summary if the format is not as expected"""
+        # Take first 2 sentences
+        sentences = re.split(r'[.!?]+', text)
+        sentences = [s.strip() for s in sentences if s.strip()]
+        return '. '.join(sentences[:2]) + '.'
+    
+    def text_to_speech(self, text: str) -> bytes:
+        """
+        Convert text to speech using ElevenLabs
+        
+        Args:
+            text: Text to convert to speech
+            
+        Returns:
+            Audio bytes (MP3 format)
+        """
+        if not self.elevenlabs_client:
+            raise ValueError("ElevenLabs API key not configured. Set ELEVENLABS_API_KEY environment variable.")
+        
+        try:
+            # Generate audio with professional voice using new API
+            audio_generator = self.elevenlabs_client.text_to_speech.convert(
+                text=text,
+                voice_id="EXAVITQu4vr4xnSDxMaL",  # Rachel voice ID
+                model_id="eleven_monolingual_v1"
+            )
+            
+            # Collect audio bytes
+            audio_bytes = b"".join(audio_generator)
+            return audio_bytes
+            
+        except Exception as e:
+            raise Exception(f"Failed to generate audio: {str(e)}")
+    
+    def process_file(self, file_content: str, language: str, filename: str) -> Tuple[str, str, bytes]:
+        """
+        Complete pipeline: analyze code, generate docs, create TTS
+        
+        Args:
+            file_content: Code content
+            language: Programming language
+            filename: Original filename
+            
+        Returns:
+            Tuple of (documentation, summary, audio_bytes)
+        """
+        # Generate documentation and summary
+        result = self.generate_documentation(file_content, language, filename)
+        
+        # Generate audio from summary
+        audio = self.text_to_speech(result["summary"])
+        
+        return result["documentation"], result["summary"], audio

app.py

@@ -0,0 +1,638 @@
+"""
+GitHub Automation Space - MCP-Enabled Gradio Application
+Demonstrates GitHub automation with MCP tool discovery for AI agents
+"""
+
+import gradio as gr
+import os
+from ghclient import GitHubClient
+from ai_helper import AIDocumentationGenerator
+from typing import Dict, List
+
+
+# Initialize GitHub client
+def get_github_client(token: str = None):
+    """Get or create GitHub client instance"""
+    try:
+        return GitHubClient(token)
+    except ValueError as e:
+        return None
+
+
+# MCP Handler Functions
+def mcp_create_repo(name: str, description: str = "", token: str = None) -> Dict:
+    """MCP handler for creating a GitHub repository (always public)"""
+    client = get_github_client(token)
+    if not client:
+        return {"error": "GitHub token not configured"}
+    return client.create_repo(name, private=False, description=description)
+
+
+def mcp_list_repos(token: str = None) -> List[Dict]:
+    """MCP handler for listing GitHub repositories"""
+    client = get_github_client(token)
+    if not client:
+        return [{"error": "GitHub token not configured"}]
+    return client.list_repos()
+
+
+def mcp_create_issue(repo_full_name: str, title: str, body: str = "", token: str = None) -> Dict:
+    """MCP handler for creating a GitHub issue"""
+    client = get_github_client(token)
+    if not client:
+        return {"error": "GitHub token not configured"}
+    return client.create_issue(repo_full_name, title, body)
+
+
+def mcp_list_issues(repo_full_name: str, state: str = "open", token: str = None) -> List[Dict]:
+    """MCP handler for listing GitHub issues"""
+    client = get_github_client(token)
+    if not client:
+        return [{"error": "GitHub token not configured"}]
+    return client.list_issues(repo_full_name, state)
+
+
+def mcp_commit_file(repo_full_name: str, path: str, content: str, message: str, token: str = None) -> Dict:
+    """MCP handler for committing a file to GitHub"""
+    client = get_github_client(token)
+    if not client:
+        return {"error": "GitHub token not configured"}
+    return client.commit_file(repo_full_name, path, content, message)
+
+
+def mcp_read_file(repo_full_name: str, path: str, token: str = None) -> Dict:
+    """MCP handler for reading a file from GitHub"""
+    client = get_github_client(token)
+    if not client:
+        return {"error": "GitHub token not configured"}
+    return client.read_file(repo_full_name, path)
+
+
+# Initialize AI helper
+def get_ai_helper(user_gemini_key: str = None):
+    """Get or create AI documentation generator instance"""
+    try:
+        return AIDocumentationGenerator(user_gemini_key)
+    except ValueError as e:
+        return None
+
+
+def mcp_generate_docs_with_tts(code_content: str, language: str, filename: str) -> Dict:
+    """MCP handler for generating documentation with TTS"""
+    ai_helper = get_ai_helper()
+    if not ai_helper:
+        return {"error": "AI services not configured. Set GEMINI_API_KEY and ELEVENLABS_API_KEY."}
+    
+    try:
+        result = ai_helper.generate_documentation(code_content, language, filename)
+        audio = ai_helper.text_to_speech(result["summary"])
+        
+        return {
+            "documentation": result["documentation"],
+            "summary": result["summary"],
+            "audio_generated": True,
+            "filename": f"{filename}_summary.mp3"
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# MCP Handlers Configuration
+mcp_handlers = {
+    "github.create_repo": {
+        "handler": mcp_create_repo,
+        "description": "Create a new GitHub repository (always public)",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Repository name"
+                },
+                "description": {
+                    "type": "string",
+                    "description": "Repository description",
+                    "default": ""
+                }
+            },
+            "required": ["name"]
+        }
+    },
+    "github.list_repos": {
+        "handler": mcp_list_repos,
+        "description": "List all repositories for the authenticated user",
+        "parameters": {
+            "type": "object",
+            "properties": {}
+        }
+    },
+    "github.create_issue": {
+        "handler": mcp_create_issue,
+        "description": "Create an issue in a GitHub repository",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "repo_full_name": {
+                    "type": "string",
+                    "description": "Full repository name (e.g., 'username/repo')"
+                },
+                "title": {
+                    "type": "string",
+                    "description": "Issue title"
+                },
+                "body": {
+                    "type": "string",
+                    "description": "Issue body/description",
+                    "default": ""
+                }
+            },
+            "required": ["repo_full_name", "title"]
+        }
+    },
+    "github.list_issues": {
+        "handler": mcp_list_issues,
+        "description": "List issues in a GitHub repository",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "repo_full_name": {
+                    "type": "string",
+                    "description": "Full repository name (e.g., 'username/repo')"
+                },
+                "state": {
+                    "type": "string",
+                    "description": "Issue state filter: 'open', 'closed', or 'all'",
+                    "default": "open",
+                    "enum": ["open", "closed", "all"]
+                }
+            },
+            "required": ["repo_full_name"]
+        }
+    },
+    "github.commit_file": {
+        "handler": mcp_commit_file,
+        "description": "Create or update a file in a GitHub repository",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "repo_full_name": {
+                    "type": "string",
+                    "description": "Full repository name (e.g., 'username/repo')"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "File path in repository"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "File content"
+                },
+                "message": {
+                    "type": "string",
+                    "description": "Commit message"
+                }
+            },
+            "required": ["repo_full_name", "path", "content", "message"]
+        }
+    },
+    "github.read_file": {
+        "handler": mcp_read_file,
+        "description": "Read a file from a GitHub repository",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "repo_full_name": {
+                    "type": "string",
+                    "description": "Full repository name (e.g., 'username/repo')"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "File path in repository"
+                }
+            },
+            "required": ["repo_full_name", "path"]
+        }
+    },
+    "github.generate_docs_with_tts": {
+        "handler": mcp_generate_docs_with_tts,
+        "description": "Generate code documentation and audio summary using AI (Gemini + ElevenLabs)",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "code_content": {
+                    "type": "string",
+                    "description": "The code to analyze and document"
+                },
+                "language": {
+                    "type": "string",
+                    "description": "Programming language (python, javascript, java, cpp, go, rust, typescript, etc.)"
+                },
+                "filename": {
+                    "type": "string",
+                    "description": "Original filename for context"
+                }
+            },
+            "required": ["code_content", "language", "filename"]
+        }
+    }
+}
+
+
+# UI Handler Functions
+def ui_create_repo(name: str, description: str, token: str = "") -> str:
+    """UI handler for creating a repository"""
+    try:
+        result = mcp_create_repo(name, description, token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}"
+        return f"✅ Repository created!\n\n📦 Name: {result['name']}\n🔗 URL: {result['url']}\n📝 Description: {result.get('description', 'N/A')}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_list_repos(token: str = "") -> str:
+    """UI handler for listing repositories"""
+    try:
+        repos = mcp_list_repos(token if token.strip() else None)
+        if not repos:
+            return "No repositories found."
+        if isinstance(repos, list) and len(repos) > 0 and "error" in repos[0]:
+            return f"❌ Error: {repos[0]['error']}"
+        
+        output = f"📚 Found {len(repos)} repositories:\n\n"
+        for repo in repos:
+            output += f"📦 {repo['name']}\n"
+            output += f"   🔗 {repo['url']}\n"
+            output += f"   🔒 {'Private' if repo['private'] else 'Public'}\n"
+            if repo.get('description'):
+                output += f"   📝 {repo['description']}\n"
+            output += "\n"
+        return output
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_create_issue(repo_full_name: str, title: str, body: str, token: str = "") -> str:
+    """UI handler for creating an issue"""
+    try:
+        result = mcp_create_issue(repo_full_name, title, body, token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}"
+        return f"✅ Issue created!\n\n🔢 Number: #{result['number']}\n📌 Title: {result['title']}\n🔗 URL: {result['url']}\n📊 State: {result['state']}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_list_issues(repo_full_name: str, state: str, token: str = "") -> str:
+    """UI handler for listing issues"""
+    try:
+        issues = mcp_list_issues(repo_full_name, state, token if token.strip() else None)
+        if not issues:
+            return f"No {state} issues found."
+        if isinstance(issues, list) and len(issues) > 0 and "error" in issues[0]:
+            return f"❌ Error: {issues[0]['error']}"
+        
+        output = f"📋 Found {len(issues)} {state} issues:\n\n"
+        for issue in issues:
+            output += f"🔢 #{issue['number']} - {issue['title']}\n"
+            output += f"   🔗 {issue['url']}\n"
+            output += f"   📊 {issue['state']}\n\n"
+        return output
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_commit_file(repo_full_name: str, path: str, content: str, message: str, token: str = "") -> str:
+    """UI handler for committing a file"""
+    try:
+        result = mcp_commit_file(repo_full_name, path, content, message, token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}"
+        return f"✅ File {result['action']}!\n\n📄 Path: {result['path']}\n🔗 URL: {result['url']}\n📝 Commit: {result['commit_sha'][:7]}\n⚡ Action: {result['action'].upper()}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_read_file(repo_full_name: str, path: str, token: str = "") -> tuple:
+    """UI handler for reading a file"""
+    try:
+        result = mcp_read_file(repo_full_name, path, token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}", ""
+        
+        info = f"✅ File read successfully!\n\n📄 Path: {result['path']}\n🔗 URL: {result['url']}\n📊 Size: {result['size']} bytes"
+        return info, result['content']
+    except Exception as e:
+        return f"❌ Error: {str(e)}", ""
+
+
+def ui_generate_docs(file, language: str, user_key: str = "") -> tuple:
+    """UI handler for AI documentation generation with TTS"""
+    try:
+        if file is None:
+            return "❌ Please upload a file", "", None
+        
+        # Read uploaded file
+        if hasattr(file, 'name'):
+            filename = os.path.basename(file.name)
+            with open(file.name, 'r', encoding='utf-8') as f:
+                code_content = f.read()
+        else:
+            return "❌ Invalid file upload", "", None
+        
+        # Generate documentation and TTS
+        # Use user key if provided, otherwise fallback to env var
+        ai_helper = get_ai_helper(user_key if user_key.strip() else None)
+        if not ai_helper or not ai_helper.gemini_model:
+            return "❌ AI services not configured. Please set GEMINI_API_KEY (env) or provide your own key.", "", None
+        
+        docs, summary, audio = ai_helper.process_file(code_content, language, filename)
+        
+        # Save audio to temporary file for Gradio
+        import tempfile
+        audio_path = tempfile.NamedTemporaryFile(delete=False, suffix='.mp3').name
+        with open(audio_path, 'wb') as f:
+            f.write(audio)
+        
+        return docs, summary, audio_path
+        
+    except Exception as e:
+        return f"❌ Error: {str(e)}", "", None
+
+
+def ui_commit_docs(repo_full_name: str, path: str, documentation: str, token: str = "") -> str:
+    """UI handler for committing generated documentation"""
+    try:
+        if not documentation or documentation.startswith("❌"):
+            return "❌ No documentation to commit. Generate documentation first."
+        
+        result = mcp_commit_file(repo_full_name, path, documentation, "Add AI-generated documentation", token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}"
+        return f"✅ Documentation committed!\n\n📄 Path: {result['path']}\n🔗 URL: {result['url']}\n📝 Commit: {result['commit_sha'][:7]}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_commit_code_file(file, repo_full_name: str, path: str, token: str = "") -> str:
+    """UI handler for committing the uploaded code file"""
+    try:
+        if file is None:
+            return "❌ No file uploaded. Please upload a code file first."
+        
+        # Read uploaded file
+        if hasattr(file, 'name'):
+            with open(file.name, 'r', encoding='utf-8') as f:
+                code_content = f.read()
+        else:
+            return "❌ Invalid file upload"
+        
+        result = mcp_commit_file(repo_full_name, path, code_content, f"Add {os.path.basename(file.name)}", token if token.strip() else None)
+        if "error" in result:
+            return f"❌ Error: {result['error']}"
+        return f"✅ Code file committed!\n\n📄 Path: {result['path']}\n🔗 URL: {result['url']}\n📝 Commit: {result['commit_sha'][:7]}"
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+def ui_commit_both(file, repo_full_name: str, code_path: str, docs_path: str, documentation: str, token: str = "") -> str:
+    """UI handler for committing both code file and documentation"""
+    try:
+        results = []
+        token_val = token if token.strip() else None
+        
+        # Commit code file
+        if file is not None:
+            if hasattr(file, 'name'):
+                with open(file.name, 'r', encoding='utf-8') as f:
+                    code_content = f.read()
+                
+                result = mcp_commit_file(repo_full_name, code_path, code_content, f"Add {os.path.basename(file.name)}", token_val)
+                if "error" in result:
+                    results.append(f"❌ Code file error: {result['error']}")
+                else:
+                    results.append(f"✅ Code file committed: {result['url']}")
+        else:
+            results.append("⚠️ No code file uploaded, skipping")
+        
+        # Commit documentation
+        if documentation and not documentation.startswith("❌"):
+            result = mcp_commit_file(repo_full_name, docs_path, documentation, "Add AI-generated documentation", token_val)
+            if "error" in result:
+                results.append(f"❌ Documentation error: {result['error']}")
+            else:
+                results.append(f"✅ Documentation committed: {result['url']}")
+        else:
+            results.append("⚠️ No documentation generated, skipping")
+        
+        return "\n\n".join(results)
+    except Exception as e:
+        return f"❌ Error: {str(e)}"
+
+
+# Build Gradio UI
+def build_ui():
+    """Build the Gradio interface"""
+    
+    with gr.Blocks(title="GitNexus") as demo:
+        gr.Markdown("""
+        # 🚀 GitNexus
+        
+        **MCP-Enabled GitHub Automation for AI Agents**
+        
+        🔗 **Demo GitHub Account**: [https://github.com/DemoAcc4HF](https://github.com/DemoAcc4HF)  
+        👤 **Username**: `DemoAcc4HF`
+        """)
+        
+        # Global GitHub Token Input
+        with gr.Row():
+            user_github_token = gr.Textbox(
+                label="Optional: Your GitHub Token (Classic)",
+                placeholder="ghp_... (Leave empty to use default system token)",
+                type="password"
+            )
+        
+        with gr.Tabs():
+            # TAB 1: Repositories
+            with gr.Tab("📦 Repositories"):
+                gr.Markdown("### Create Repository")
+                repo_name = gr.Textbox(label="Repository Name", placeholder="my-awesome-repo")
+                repo_description = gr.Textbox(label="Description", placeholder="A cool project")
+                create_repo_btn = gr.Button("Create Repository", variant="primary")
+                create_repo_output = gr.Textbox(label="Result", lines=6)
+                
+                gr.Markdown("### List Repositories")
+                list_repos_btn = gr.Button("List All Repositories")
+                list_repos_output = gr.Textbox(label="Repositories", lines=10)
+                
+                create_repo_btn.click(
+                    ui_create_repo,
+                    inputs=[repo_name, repo_description, user_github_token],
+                    outputs=create_repo_output
+                )
+                list_repos_btn.click(
+                    ui_list_repos,
+                    inputs=[user_github_token],
+                    outputs=list_repos_output
+                )
+            
+            # TAB 2: Issues
+            with gr.Tab("📋 Issues"):
+                gr.Markdown("### Create Issue")
+                issue_repo = gr.Textbox(label="Repository (username/repo)", placeholder="octocat/Hello-World")
+                issue_title = gr.Textbox(label="Issue Title", placeholder="Bug: Something is broken")
+                issue_body = gr.Textbox(label="Issue Body", placeholder="Detailed description...", lines=4)
+                create_issue_btn = gr.Button("Create Issue", variant="primary")
+                create_issue_output = gr.Textbox(label="Result", lines=6)
+                
+                gr.Markdown("### List Issues")
+                list_issue_repo = gr.Textbox(label="Repository (username/repo)", placeholder="octocat/Hello-World")
+                list_issue_state = gr.Radio(["open", "closed", "all"], label="State", value="open")
+                list_issues_btn = gr.Button("List Issues")
+                list_issues_output = gr.Textbox(label="Issues", lines=10)
+                
+                create_issue_btn.click(
+                    ui_create_issue,
+                    inputs=[issue_repo, issue_title, issue_body, user_github_token],
+                    outputs=create_issue_output
+                )
+                list_issues_btn.click(
+                    ui_list_issues,
+                    inputs=[list_issue_repo, list_issue_state, user_github_token],
+                    outputs=list_issues_output
+                )
+            
+            # TAB 3: Custom Files
+            with gr.Tab("📄 Custom Files"):
+                gr.Markdown("### Commit File")
+                commit_repo = gr.Textbox(label="Repository (username/repo)", placeholder="octocat/Hello-World")
+                commit_path = gr.Textbox(label="File Path", placeholder="src/main.py")
+                commit_content = gr.Textbox(label="File Content", placeholder="print('Hello, World!')", lines=6)
+                commit_message = gr.Textbox(label="Commit Message", placeholder="Add main.py")
+                commit_file_btn = gr.Button("Commit File", variant="primary")
+                commit_file_output = gr.Textbox(label="Result", lines=6)
+                
+                gr.Markdown("### Read File")
+                read_repo = gr.Textbox(label="Repository (username/repo)", placeholder="octocat/Hello-World")
+                read_path = gr.Textbox(label="File Path", placeholder="README.md")
+                read_file_btn = gr.Button("Read File")
+                read_file_info = gr.Textbox(label="File Info", lines=4)
+                read_file_content = gr.Textbox(label="File Content", lines=10)
+                
+                commit_file_btn.click(
+                    ui_commit_file,
+                    inputs=[commit_repo, commit_path, commit_content, commit_message, user_github_token],
+                    outputs=commit_file_output
+                )
+                read_file_btn.click(
+                    ui_read_file,
+                    inputs=[read_repo, read_path, user_github_token],
+                    outputs=[read_file_info, read_file_content]
+                )
+            
+            # TAB 4: Code Documentation
+            with gr.Tab("🤖 Code Documentation"):
+                gr.Markdown("""
+                ### Upload Code for AI-Powered Documentation
+                Upload your code file and get comprehensive documentation + audio summary!
+                """)
+                
+                with gr.Row():
+                    file_upload = gr.File(
+                        label="📁 Upload Code File",
+                        file_types=[".py", ".js", ".java", ".cpp", ".go", ".rs", ".ts", ".jsx", ".tsx", ".c", ".h"]
+                    )
+                    with gr.Column():
+                        language_select = gr.Dropdown(
+                            choices=["python", "javascript", "java", "cpp", "go", "rust", "typescript", "c"],
+                            label="Programming Language",
+                            value="python"
+                        )
+                        user_gemini_key = gr.Textbox(
+                            label="Optional: Your Gemini API Key",
+                            placeholder="AIzaSy... (Leave empty to use default key)",
+                            type="password"
+                        )
+                
+                generate_btn = gr.Button("🚀 Generate Documentation + Audio Summary", variant="primary", size="lg")
+                
+                gr.Markdown("### 📚 Generated Documentation")
+                docs_output = gr.Markdown(label="Full Documentation")
+                
+                gr.Markdown("### 📝 2-Line Summary")
+                summary_output = gr.Textbox(label="Summary", lines=2, max_lines=2, interactive=False)
+                
+                gr.Markdown("### 🔊 Audio Summary (Text-to-Speech)")
+                audio_output = gr.Audio(label="Listen to Summary", type="filepath")
+                
+                gr.Markdown("### 💾 Commit to Repository")
+                gr.Markdown("Upload both the code file and generated documentation to GitHub")
+                with gr.Row():
+                    commit_repo = gr.Textbox(label="Repository (username/repo)", placeholder="DemoAcc4HF/my-repo")
+                with gr.Row():
+                    commit_code_path = gr.Textbox(label="Code File Path", placeholder="src/main.py")
+                    commit_docs_path = gr.Textbox(label="Documentation Path", value="DOCUMENTATION.md")
+                with gr.Row():
+                    commit_code_btn = gr.Button("Commit Code File", variant="secondary")
+                    commit_docs_btn = gr.Button("Commit Documentation", variant="secondary")
+                    commit_both_btn = gr.Button("Commit Both Files", variant="primary")
+                commit_output = gr.Textbox(label="Result", lines=6)
+                
+                # Event handlers
+                generate_btn.click(
+                    ui_generate_docs,
+                    inputs=[file_upload, language_select, user_gemini_key],
+                    outputs=[docs_output, summary_output, audio_output]
+                )
+                
+                commit_code_btn.click(
+                    ui_commit_code_file,
+                    inputs=[file_upload, commit_repo, commit_code_path, user_github_token],
+                    outputs=commit_output
+                )
+                
+                commit_docs_btn.click(
+                    ui_commit_docs,
+                    inputs=[commit_repo, commit_docs_path, docs_output, user_github_token],
+                    outputs=commit_output
+                )
+                
+                commit_both_btn.click(
+                    ui_commit_both,
+                    inputs=[file_upload, commit_repo, commit_code_path, commit_docs_path, docs_output, user_github_token],
+                    outputs=commit_output
+                )
+        
+        
+        gr.Markdown("""
+        ---
+        💡 All repositories are created as **public**.
+        """)
+    
+    return demo
+
+
+if __name__ == "__main__":
+    # Check if GitHub token is available
+    if not os.environ.get("GITHUB_TOKEN"):
+        print("⚠️  WARNING: GITHUB_TOKEN environment variable not set!")
+        print("   The application will not function without a valid GitHub token.")
+        print("   Set it in Hugging Face Space secrets or your environment.")
+    
+    # Build and launch the app
+    app = build_ui()
+    
+    # Try to launch with MCP support if available, otherwise launch normally
+    try:
+        app.launch(
+            mcp_server=True,
+            mcp_handlers=mcp_handlers,
+            share=False
+        )
+    except TypeError:
+        # MCP not supported in this Gradio version, launch normally
+        print("ℹ️  Note: MCP server support not available in this Gradio version.")
+        print("   The UI will work, but MCP handlers won't be exposed.")
+        print("   For full MCP support, this will work when deployed to HF Spaces.")
+        app.launch(share=False)
+

ghclient.py

@@ -0,0 +1,225 @@
+"""
+GitHub Client Module
+Handles all GitHub API interactions using PyGithub
+"""
+
+import os
+from github import Github, GithubException
+from typing import Dict, List, Optional
+
+
+class GitHubClient:
+    """GitHub API client wrapper for automation tasks"""
+    
+    def __init__(self, token: Optional[str] = None):
+        """
+        Initialize GitHub client with access token
+        
+        Args:
+            token: GitHub Personal Access Token (if None, reads from GITHUB_TOKEN env var)
+        """
+        self.token = token or os.environ.get("GITHUB_TOKEN")
+        if not self.token:
+            raise ValueError("GitHub token not provided. Set GITHUB_TOKEN environment variable.")
+        
+        self.github = Github(self.token)
+        self.user = self.github.get_user()
+    
+    def create_repo(self, name: str, private: bool = False, description: str = "") -> Dict:
+        """
+        Create a new GitHub repository
+        
+        Args:
+            name: Repository name
+            private: Whether repo should be private (default: False for public)
+            description: Repository description
+            
+        Returns:
+            Dict with keys: name, url, private
+        """
+        try:
+            repo = self.user.create_repo(
+                name=name,
+                private=private,
+                description=description,
+                auto_init=True  # Initialize with README
+            )
+            return {
+                "name": repo.name,
+                "url": repo.html_url,
+                "private": repo.private,
+                "description": repo.description
+            }
+        except GithubException as e:
+            raise Exception(f"Failed to create repository: {e.data.get('message', str(e))}")
+    
+    def list_repos(self) -> List[Dict]:
+        """
+        List all repositories for the authenticated user
+        
+        Returns:
+            List of dicts with keys: name, url, private
+        """
+        try:
+            repos = self.user.get_repos()
+            return [
+                {
+                    "name": repo.name,
+                    "url": repo.html_url,
+                    "private": repo.private,
+                    "description": repo.description or ""
+                }
+                for repo in repos
+            ]
+        except GithubException as e:
+            raise Exception(f"Failed to list repositories: {e.data.get('message', str(e))}")
+    
+    def create_issue(self, repo_full_name: str, title: str, body: str = "") -> Dict:
+        """
+        Create an issue in a repository
+        
+        Args:
+            repo_full_name: Full repository name (e.g., "username/repo")
+            title: Issue title
+            body: Issue body/description
+            
+        Returns:
+            Dict with keys: number, url, title, state
+        """
+        try:
+            self._validate_repo_name(repo_full_name)
+            repo = self.github.get_repo(repo_full_name)
+            issue = repo.create_issue(title=title, body=body)
+            return {
+                "number": issue.number,
+                "url": issue.html_url,
+                "title": issue.title,
+                "state": issue.state
+            }
+        except GithubException as e:
+            raise Exception(f"Failed to create issue: {e.data.get('message', str(e))}")
+    
+    def list_issues(self, repo_full_name: str, state: str = "open") -> List[Dict]:
+        """
+        List issues in a repository
+        
+        Args:
+            repo_full_name: Full repository name (e.g., "username/repo")
+            state: Issue state filter ("open", "closed", or "all")
+            
+        Returns:
+            List of dicts with keys: number, title, url, state
+        """
+        try:
+            self._validate_repo_name(repo_full_name)
+            repo = self.github.get_repo(repo_full_name)
+            issues = repo.get_issues(state=state)
+            return [
+                {
+                    "number": issue.number,
+                    "title": issue.title,
+                    "url": issue.html_url,
+                    "state": issue.state
+                }
+                for issue in issues
+            ]
+        except GithubException as e:
+            raise Exception(f"Failed to list issues: {e.data.get('message', str(e))}")
+    
+    def commit_file(self, repo_full_name: str, path: str, content: str, message: str) -> Dict:
+        """
+        Create or update a file in a repository
+        
+        Args:
+            repo_full_name: Full repository name (e.g., "username/repo")
+            path: File path in repository
+            content: File content
+            message: Commit message
+            
+        Returns:
+            Dict with keys: commit_sha, url, action (created/updated)
+        """
+        try:
+            self._validate_repo_name(repo_full_name)
+            repo = self.github.get_repo(repo_full_name)
+            
+            # Check if file exists
+            try:
+                existing_file = repo.get_contents(path)
+                # File exists, update it
+                result = repo.update_file(
+                    path=path,
+                    message=message,
+                    content=content,
+                    sha=existing_file.sha
+                )
+                action = "updated"
+            except GithubException as e:
+                if e.status == 404:
+                    # File doesn't exist, create it
+                    result = repo.create_file(
+                        path=path,
+                        message=message,
+                        content=content
+                    )
+                    action = "created"
+                else:
+                    raise
+            
+            return {
+                "commit_sha": result["commit"].sha,
+                "url": result["content"].html_url,
+                "action": action,
+                "path": path
+            }
+        except GithubException as e:
+            raise Exception(f"Failed to commit file: {e.data.get('message', str(e))}")
+    
+    def read_file(self, repo_full_name: str, path: str) -> Dict:
+        """
+        Read a file from a repository
+        
+        Args:
+            repo_full_name: Full repository name (e.g., "username/repo")
+            path: File path in repository
+            
+        Returns:
+            Dict with keys: path, content, url
+        """
+        try:
+            self._validate_repo_name(repo_full_name)
+            repo = self.github.get_repo(repo_full_name)
+            file_content = repo.get_contents(path)
+            
+            return {
+                "path": file_content.path,
+                "content": file_content.decoded_content.decode('utf-8'),
+                "url": file_content.html_url,
+                "size": file_content.size
+            }
+        except GithubException as e:
+            if e.status == 404:
+                raise Exception(f"File not found: {path}")
+            raise Exception(f"Failed to read file: {e.data.get('message', str(e))}")
+    
+    @staticmethod
+    def _validate_repo_name(repo_full_name: str):
+        """
+        Validate repository full name format
+        
+        Args:
+            repo_full_name: Full repository name to validate
+            
+        Raises:
+            ValueError: If format is invalid
+        """
+        if not repo_full_name or "/" not in repo_full_name:
+            raise ValueError(
+                "Invalid repository name. Must be in format 'username/repo'"
+            )
+        
+        parts = repo_full_name.split("/")
+        if len(parts) != 2 or not all(parts):
+            raise ValueError(
+                "Invalid repository name. Must be in format 'username/repo'"
+            )

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=4.0.0
+PyGithub>=2.1.1
+google-generativeai>=0.3.0
+elevenlabs>=0.2.0

test_fibonacci.py

@@ -0,0 +1,13 @@
+def calculate_fibonacci(n):
+    """Calculate the nth Fibonacci number using recursion."""
+    if n <= 1:
+        return n
+    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)
+
+def main():
+    """Main function to demonstrate Fibonacci calculation."""
+    for i in range(10):
+        print(f"Fibonacci({i}) = {calculate_fibonacci(i)}")
+
+if __name__ == "__main__":
+    main()