Help

README.md

@@ -11,3 +11,298 @@ short_description: Recommends users which Repos/Spaces to look at
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# 🚀 HF Repo Analyzer
+
+An AI-powered Hugging Face repository discovery and analysis tool that helps you find, evaluate, and explore the best repositories for your specific needs.
+
+![HF Repo Analyzer](https://img.shields.io/badge/Powered%20by-Gradio-orange)
+![Python](https://img.shields.io/badge/Python-3.8+-blue)
+![Hugging Face](https://img.shields.io/badge/Hugging%20Face-Spaces-yellow)
+
+## ✨ Features
+
+- 🤖 **AI Assistant**: Intelligent conversation-based repository discovery
+- 🔍 **Smart Search**: Auto-detection of repository IDs vs. keywords
+- 📊 **Automated Analysis**: LLM-powered repository evaluation and ranking
+- 🏆 **Top 3 Selection**: AI-curated most relevant repositories
+- 💬 **Repository Explorer**: Interactive chat with repository contents
+- 🎯 **Requirements Extraction**: Automatic keyword extraction from conversations
+- 📋 **Comprehensive Results**: Detailed analysis with strengths, weaknesses, and specialities
+
+## 🚦 Quick Start
+
+### Prerequisites
+
+- Python 3.8+
+- OpenAI API key (for LLM analysis)
+- Hugging Face access (for repository downloads)
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd Agentic_HF_Analyzer
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   export modal_api="your_openai_api_key"
+   export base_url="your_openai_base_url"
+   ```
+
+4. **Run the application**
+   ```bash
+   python app.py
+   ```
+
+5. **Open your browser** to `http://localhost:7860`
+
+## 📖 User Guide
+
+### 🤖 Using the AI Assistant (Recommended)
+
+1. **Start a Conversation**
+   - Navigate to the "🤖 AI Assistant" tab
+   - Describe your project: "I'm building a chatbot for customer service"
+   - The AI will ask clarifying questions about your needs
+
+2. **Automatic Discovery**
+   - When the AI has enough information, it will automatically:
+     - Extract relevant keywords from your conversation
+     - Search for matching repositories
+     - Analyze and rank them by relevance
+
+3. **Review Results**
+   - The interface automatically switches to "🔬 Analysis & Results"
+   - View the top 3 most relevant repositories
+   - Browse all analyzed repositories with detailed insights
+
+### 📝 Using Smart Search (Direct Input)
+
+1. **Repository IDs**
+   ```
+   microsoft/DialoGPT-medium
+   openai/whisper
+   huggingface/transformers
+   ```
+
+2. **Keywords**
+   ```
+   text generation
+   image classification
+   sentiment analysis
+   ```
+
+3. **Mixed Input**
+   - The system automatically detects the input type
+   - Repository IDs (containing `/`) are processed directly
+   - Keywords trigger automatic repository search
+
+### 🔬 Analyzing Results
+
+- **Top 3 Repositories**: AI-selected most relevant based on your requirements
+- **Detailed Analysis**: Strengths, weaknesses, specialities, and relevance ratings
+- **Quick Actions**: Click repository names to visit or explore them
+- **Repository Explorer**: Deep dive into individual repositories with AI chat
+
+### 🔍 Repository Explorer
+
+1. **Access Methods**:
+   - Click "🔍 Open in Repo Explorer" from repository actions
+   - Manually enter repository ID in the Repo Explorer tab
+
+2. **Features**:
+   - Automatic repository loading and analysis
+   - Interactive chat about repository contents
+   - File structure exploration
+   - Code analysis and explanations
+
+## 🛠️ Technical Architecture
+
+### Core Components
+
+```
+app.py                 # Main Gradio interface and orchestration
+├── analyzer.py        # Repository analysis and LLM processing
+├── hf_utils.py       # Hugging Face API interactions
+├── chatbot_page.py   # AI assistant conversation logic
+└── repo_explorer.py  # Repository exploration interface
+```
+
+### Key Features Implementation
+
+#### 🤖 AI Assistant
+- **System Prompt**: Focused on requirements gathering, not recommendations
+- **Auto-Extraction**: Detects conversation readiness for keyword extraction
+- **Smart Processing**: Converts natural language to actionable search queries
+
+#### 🔍 Smart Input Detection
+```python
+def is_repo_id_format(text: str) -> bool:
+    # Detects if input contains repository IDs (with /) vs keywords
+    lines = [line.strip() for line in re.split(r'[\n,]+', text) if line.strip()]
+    slash_count = sum(1 for line in lines if '/' in line)
+    return slash_count >= len(lines) * 0.5
+```
+
+#### 🏆 LLM-Powered Repository Ranking
+- **Model**: `Orion-zhen/Qwen2.5-Coder-7B-Instruct-AWQ`
+- **Criteria**: Requirements matching, strengths, relevance rating, speciality alignment
+- **Output**: JSON-formatted repository rankings
+
+#### 📊 Analysis Pipeline
+1. **Download**: Repository files (`.py`, `.md`, `.txt`)
+2. **Combine**: Merge files into single analyzable document
+3. **Analyze**: LLM evaluation for strengths, weaknesses, specialities
+4. **Rank**: User requirement-based relevance scoring
+5. **Select**: Top 3 most relevant repositories
+
+### Data Flow
+
+```mermaid
+graph TD
+    A[User Input] --> B{Input Type?}
+    B -->|Keywords| C[Repository Search]
+    B -->|Repo IDs| D[Direct Processing]
+    C --> E[Repository List]
+    D --> E
+    E --> F[Download & Analyze]
+    F --> G[LLM Evaluation]
+    G --> H[Ranking & Selection]
+    H --> I[Results Display]
+    I --> J[Repository Explorer]
+```
+
+### File Structure
+
+```
+📦 Agentic_HF_Analyzer/
+├── 📄 app.py                    # Main application
+├── 📄 analyzer.py               # Repository analysis logic
+├── 📄 hf_utils.py              # Hugging Face utilities
+├── 📄 chatbot_page.py          # AI assistant functionality
+├── 📄 repo_explorer.py         # Repository exploration
+├── 📄 requirements.txt         # Python dependencies
+├── 📄 README.md               # Documentation
+├── 📄 repo_ids.csv            # Analysis results storage
+└── 📁 repo_files/             # Temporary repository downloads
+```
+
+### Dependencies
+
+```
+gradio>=4.0.0          # Web interface framework
+pandas>=1.5.0          # Data manipulation
+regex>=2022.0.0        # Advanced regex operations
+openai>=1.0.0          # LLM API access
+huggingface_hub>=0.16.0 # HF repository access
+requests>=2.28.0       # HTTP requests
+```
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `modal_api` | OpenAI API key for LLM analysis | ✅ |
+| `base_url` | OpenAI API base URL | ✅ |
+
+### LLM Integration
+
+#### Analysis Prompt Structure
+```python
+ANALYSIS_PROMPT = """
+Analyze this repository and provide:
+1. Strengths and capabilities
+2. Potential weaknesses or limitations  
+3. Primary speciality/use case
+4. Relevance rating for: {user_requirements}
+
+Return valid JSON with: strength, weaknesses, speciality, relevance rating
+"""
+```
+
+#### Repository Ranking System
+- **Input**: User requirements + repository analysis data
+- **Processing**: LLM evaluates relevance and ranks repositories
+- **Output**: Top 3 most relevant repositories in order
+
+### UI Components
+
+#### Modern Design Features
+- **Gradient Backgrounds**: Linear gradients for visual appeal
+- **Glassmorphism**: Backdrop blur effects for modern look
+- **Responsive Layout**: Adaptive to different screen sizes
+- **Interactive Elements**: Hover effects and smooth transitions
+- **Modal System**: Repository action selection popups
+
+#### Tab Organization
+1. **🤖 AI Assistant**: Conversation-based discovery
+2. **📝 Smart Search**: Direct input processing
+3. **🔬 Analysis & Results**: Comprehensive analysis display
+4. **🔍 Repo Explorer**: Interactive repository exploration
+
+### Advanced Features
+
+#### Auto-Navigation
+- Automatic tab switching based on workflow state
+- Smooth scrolling to top on tab changes
+- Progressive disclosure of information
+
+#### Error Handling
+- Graceful fallbacks for LLM failures
+- CSV update retry mechanisms
+- User-friendly error messages
+
+#### Performance Optimizations
+- Parallel processing for multiple repositories
+- Progress tracking for long operations
+- Efficient file caching and cleanup
+
+## 🔧 Configuration
+
+### Customizing Analysis
+- Modify `CHATBOT_SYSTEM_PROMPT` for different assistant behavior
+- Adjust repository search limits in `search_top_spaces()`
+- Configure analysis criteria in `get_top_relevant_repos()`
+
+### Adding File Types
+```python
+# In analyzer.py
+download_filtered_space_files(
+    repo_id, 
+    local_dir="repo_files", 
+    file_extensions=['.py', '.md', '.txt', '.js', '.ts']  # Add more
+)
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Implement your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- **Gradio**: For the amazing web interface framework
+- **Hugging Face**: For the incredible repository ecosystem
+- **OpenAI**: For powerful language model capabilities
+
+---
+
+<div align="center">
+  <p>Built with ❤️ for the open source community</p>
+  <p>🚀 Happy repository hunting! 🚀</p>
+</div>

app.py

@@ -603,15 +603,161 @@ def create_ui() -> gr.Blocks:
             """
         )
         
-        # Global Reset Button - visible on all tabs
+        # Global Reset and Help Buttons - visible on all tabs
         with gr.Row():
-            with gr.Column(scale=4):
+            with gr.Column(scale=3):
                 pass
+            with gr.Column(scale=1):
+                help_btn = gr.Button("❓ Help", variant="secondary", size="lg")
             with gr.Column(scale=1):
                 reset_all_btn = gr.Button("🔄 Reset Everything", variant="stop", size="lg")
             with gr.Column(scale=1):
                 pass
 
+        # Help Modal - visible when help button is clicked
+        with gr.Row():
+            with gr.Column():
+                help_modal = gr.Column(visible=False)
+                with help_modal:
+                    gr.Markdown(
+                        """
+                        <div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 20px; border-radius: 16px; text-align: center; margin-bottom: 20px;">
+                            <h2 style="color: white; margin: 0; font-size: 2rem;">📚 How to Use HF Repo Analyzer</h2>
+                            <p style="color: rgba(255,255,255,0.9); margin: 10px 0 0 0;">Step-by-step guide to find and analyze repositories</p>
+                        </div>
+                        """
+                    )
+                    
+                    with gr.Accordion("🚀 Method 1: AI Assistant (Recommended)", open=True):
+                        gr.Markdown(
+                            """
+                            ### **Step 1: Start Conversation**
+                            - Go to the **🤖 AI Assistant** tab
+                            - Describe your project: *"I'm building a sentiment analysis tool"*
+                            - The AI will ask clarifying questions about your needs
+                            
+                            ### **Step 2: Let AI Work Its Magic**
+                            - Answer the AI's questions about your requirements
+                            - When ready, the AI will automatically:
+                              - Extract keywords from your conversation
+                              - Search for matching repositories  
+                              - Analyze and rank them by relevance
+                            
+                            ### **Step 3: Review Results**
+                            - Interface automatically switches to **🔬 Analysis & Results**
+                            - View **Top 3** most relevant repositories
+                            - Browse detailed analysis with strengths/weaknesses
+                            - Click repository names to visit or explore them
+                            
+                            **💡 Tip**: This method gives the best personalized results!
+                            """
+                        )
+                    
+                    with gr.Accordion("📝 Method 2: Smart Search (Direct Input)", open=False):
+                        gr.Markdown(
+                            """
+                            ### **Step 1: Choose Input Type**
+                            Go to **📝 Smart Search** tab and enter either:
+                            
+                            **Repository IDs** (with `/`):
+                            ```
+                            microsoft/DialoGPT-medium
+                            openai/whisper
+                            huggingface/transformers
+                            ```
+                            
+                            **Keywords** (no `/`):
+                            ```
+                            text generation
+                            image classification
+                            sentiment analysis
+                            ```
+                            
+                            ### **Step 2: Auto-Detection & Processing**
+                            - System automatically detects input type
+                            - Repository IDs → Direct analysis
+                            - Keywords → Search + analysis
+                            - Enable **🚀 Auto-analyze** for instant results
+                            
+                            ### **Step 3: Get Results**
+                            - Click **🔍 Find & Process Repositories**
+                            - View results in **🔬 Analysis & Results** tab
+                            """
+                        )
+                    
+                    with gr.Accordion("🔬 Understanding Analysis Results", open=False):
+                        gr.Markdown(
+                            """
+                            ### **🏆 Top 3 Repositories**
+                            - AI-selected most relevant for your needs
+                            - Ranked by requirement matching and quality
+                            
+                            ### **📊 Detailed Analysis Table**
+                            - **Repository**: Click names to visit/explore
+                            - **Strengths**: Key capabilities and advantages
+                            - **Weaknesses**: Limitations and considerations
+                            - **Speciality**: Primary use case and domain
+                            - **Relevance**: How well it matches your needs
+                            
+                            ### **🔗 Quick Actions**
+                            Click repository names to:
+                            - **🌐 Visit Hugging Face Space**: See live demo
+                            - **🔍 Open in Repo Explorer**: Deep dive analysis
+                            """
+                        )
+                    
+                    with gr.Accordion("🔍 Repository Explorer Deep Dive", open=False):
+                        gr.Markdown(
+                            """
+                            ### **Access Repository Explorer**
+                            - Click **🔍 Open in Repo Explorer** from results
+                            - Or manually enter repo ID in **🔍 Repo Explorer** tab
+                            
+                            ### **Features Available**
+                            - **Auto-loading**: Repository content analysis
+                            - **AI Chat**: Ask questions about the code
+                            - **File Exploration**: Browse repository structure
+                            - **Code Analysis**: Get explanations and insights
+                            
+                            ### **Sample Questions to Ask**
+                            - *"How do I use this repository?"*
+                            - *"What are the main functions?"*
+                            - *"Show me example usage"*
+                            - *"Explain the architecture"*
+                            """
+                        )
+                    
+                    with gr.Accordion("🎯 Pro Tips & Best Practices", open=False):
+                        gr.Markdown(
+                            """
+                            ### **🤖 Getting Better AI Results**
+                            - Be specific about your use case
+                            - Mention programming language preferences
+                            - Describe your experience level
+                            - Include performance requirements
+                            
+                            ### **🔍 Search Optimization**
+                            - Use multiple relevant keywords
+                            - Try different keyword combinations
+                            - Check both general and specific terms
+                            
+                            ### **📊 Analyzing Results**
+                            - Read both strengths AND weaknesses
+                            - Check speciality alignment with your needs
+                            - Use Repository Explorer for detailed investigation
+                            - Compare multiple options before deciding
+                            
+                            ### **🔄 Workflow Tips**
+                            - Start with AI Assistant for personalized results
+                            - Use Smart Search for known repositories
+                            - Explore multiple repositories before choosing
+                            - Save interesting repositories for later comparison
+                            """
+                        )
+                    
+                    with gr.Row():
+                        close_help_btn = gr.Button("✅ Got It, Let's Start!", variant="primary", size="lg")
+
         with gr.Tabs() as tabs:
             # --- AI Assistant Tab (moved to first) ---
             with gr.TabItem("🤖 AI Assistant", id="chatbot_tab"):
@@ -1374,6 +1520,17 @@ def create_ui() -> gr.Blocks:
             outputs=[repo_ids_state, current_repo_idx_state, user_requirements_state, df_output, top_repos_df, top_repos_section, chatbot, status_box_input, current_requirements_display, extracted_keywords_output]
         )
         
+        # Help modal events
+        help_btn.click(
+            fn=lambda: gr.update(visible=True),
+            outputs=[help_modal]
+        )
+        
+        close_help_btn.click(
+            fn=lambda: gr.update(visible=False),
+            outputs=[help_modal]
+        )
+        
     return app
 
 if __name__ == "__main__":