inital commit

.gitignore

@@ -0,0 +1,2 @@
+src/.env
+env/

requirements.txt

@@ -1,3 +1,13 @@
 altair
 pandas
-streamlit
+streamlit
+streamlit>=1.28.0
+pyvis>=0.3.2
+networkx>=3.1
+google-generativeai>=0.3.0
+tavily-python>=0.3.0
+google-cloud-enterpriseknowledgegraph>=0.4.0
+aiohttp>=3.9.0
+python-dotenv>=1.0.0
+pydantic>=2.0.0
+requests>=2.31.0

src/README.md

@@ -0,0 +1,453 @@
+# 🧠 Technical Mindmap Generator
+
+> An AI-powered Streamlit application that generates interactive radial mindmaps for technical keywords using Gemini, Tavily, and Knowledge Graph APIs.
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![Python](https://img.shields.io/badge/python-3.9+-green.svg)
+![License](https://img.shields.io/badge/license-MIT-orange.svg)
+
+---
+
+## ✨ Features
+
+- 🎯 **Interactive Radial Mindmaps**: Beautiful, explorable visualizations with zoom, pan, and hover
+- 🤖 **AI-Powered Analysis**: Leverages three powerful APIs for comprehensive results
+- ⚡ **Optimized Performance**: Sequential API calls with async processing
+- 🎨 **Modern UI**: Clean, responsive design inspired by GPT/Claude/Perplexity
+- 📊 **Query History**: Track and revisit previous mindmaps in the same session
+- 🔍 **Real-time Data**: Fresh insights from authoritative web sources
+
+---
+
+## 🏗️ Architecture
+
+### Sequential API Call Strategy
+
+The application uses an optimized 3-step approach for maximum data quality:
+
+```
+User Input (Technical Keyword)
+        ↓
+    ┌─────────────────────────────────┐
+    │  STEP 1: Tavily API             │
+    │  • Web search & context         │
+    │  • Related term extraction      │
+    │  • Source collection            │
+    └─────────────────────────────────┘
+        ↓ (context + terms)
+    ┌─────────────────────────────────┐
+    │  STEP 2: Knowledge Graph API    │
+    │  • Structured entity data       │
+    │  • Relationship mapping         │
+    │  • Entity descriptions          │
+    └─────────────────────────────────┘
+        ↓ (entities + relationships)
+    ┌─────────────────────────────────┐
+    │  STEP 3: Gemini AI              │
+    │  • Synthesis of all data        │
+    │  • Mindmap structure generation │
+    │  • Hierarchical organization    │
+    └─────────────────────────────────┘
+        ↓
+    PyVis Radial Visualization
+```
+
+**Why Sequential?**  
+Each API call benefits from context gathered in previous steps, maximizing relevance and reducing noise.
+
+---
+
+## 📦 Installation
+
+### Prerequisites
+
+- **Python 3.9+**
+- **pip** package manager
+- **API Keys:**
+  - [Gemini API Key](https://ai.google.dev/) (Free tier available)
+  - [Tavily API Key](https://tavily.com/) (Free tier: 1000 requests/month)
+  - [Google Cloud Project](https://console.cloud.google.com/) with Knowledge Graph API enabled
+
+### Step-by-Step Setup
+
+#### 1. Clone or Download the Project
+
+```bash
+# If using git
+git clone <repository-url>
+cd technical-mindmap-generator
+
+# Or download and extract the ZIP file
+```
+
+#### 2. Create Virtual Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate it
+# On macOS/Linux:
+source venv/bin/activate
+
+# On Windows:
+venv\Scripts\activate
+```
+
+#### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+This will install:
+- streamlit
+- pyvis
+- networkx
+- google-generativeai
+- tavily-python
+- google-cloud-enterpriseknowledgegraph
+- aiohttp
+- python-dotenv
+- pydantic
+- requests
+
+#### 4. Configure API Keys
+
+Create a `.env` file in the project root:
+
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit with your API keys
+nano .env  # or use any text editor
+```
+
+Add your API keys to `.env`:
+
+```env
+GEMINI_API_KEY=your_actual_gemini_api_key_here
+TAVILY_API_KEY=your_actual_tavily_api_key_here
+GOOGLE_CLOUD_PROJECT_ID=your_google_cloud_project_id_here
+
+# Optional settings
+MAX_CONCURRENT_REQUESTS=3
+CACHE_ENABLED=true
+DEBUG_MODE=false
+MAX_NODES=20
+MAX_DEPTH=2
+```
+
+#### 5. Get Your API Keys
+
+**Gemini API Key:**
+1. Visit https://ai.google.dev/
+2. Click "Get API Key"
+3. Sign in with Google account
+4. Create new API key
+5. Copy the key
+
+**Tavily API Key:**
+1. Visit https://tavily.com/
+2. Sign up for free account
+3. Navigate to API Keys section
+4. Copy your API key
+
+**Google Cloud Knowledge Graph:**
+1. Visit https://console.cloud.google.com/
+2. Create new project or select existing
+3. Enable "Enterprise Knowledge Graph API"
+4. Copy your project ID
+
+#### 6. Run the Application
+
+```bash
+streamlit run app.py
+```
+
+The application will open automatically in your browser at `http://localhost:8501`
+
+---
+
+## 🚀 Usage
+
+### Basic Workflow
+
+1. **Enter Keyword**: Type any technical term (e.g., "Machine Learning", "Kubernetes")
+2. **Generate**: Click the "🚀 Generate Mindmap" button
+3. **Wait**: Processing takes 10-15 seconds as data is fetched from all APIs
+4. **Explore**: Interact with the mindmap:
+   - 🔍 **Zoom**: Mouse wheel or pinch gesture
+   - 👆 **Pan**: Click and drag
+   - ℹ️ **Hover**: View detailed node information
+   - 🧭 **Navigate**: Use built-in navigation controls
+5. **View Details**: Expand the metadata section for sources and statistics
+6. **New Query**: Enter another keyword; previous mindmaps saved in history
+
+### Example Keywords to Try
+
+- **AI/ML**: Machine Learning, Neural Networks, Deep Learning, Transformers
+- **DevOps**: Kubernetes, Docker, CI/CD, Microservices
+- **Blockchain**: Ethereum, Smart Contracts, DeFi, NFTs
+- **Cloud**: AWS, Serverless, Cloud Native, Edge Computing
+- **Programming**: Python, JavaScript, Rust, TypeScript
+
+---
+
+## 📁 Project Structure
+
+```
+technical-mindmap-generator/
+│
+├── app.py                          # Main Streamlit application
+├── requirements.txt                # Python dependencies
+├── .env.example                   # Environment variables template
+├── .env                           # Your API keys (create this)
+├── README.md                      # This file
+│
+├── config/
+│   ├── __init__.py
+│   └── settings.py                # Configuration management
+│
+└── utils/
+    ├── __init__.py
+    ├── api_handler.py             # API integration layer
+    └── mindmap_generator.py       # PyVis visualization
+```
+
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+Edit `.env` to customize behavior:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GEMINI_API_KEY` | Required | Gemini AI API key |
+| `TAVILY_API_KEY` | Required | Tavily search API key |
+| `GOOGLE_CLOUD_PROJECT_ID` | Required | Google Cloud project ID |
+| `MAX_CONCURRENT_REQUESTS` | 3 | Max parallel API calls |
+| `CACHE_ENABLED` | true | Enable result caching |
+| `DEBUG_MODE` | false | Enable debug logging |
+| `MAX_NODES` | 20 | Maximum nodes in mindmap |
+| `MAX_DEPTH` | 2 | Maximum hierarchy depth |
+
+### Customization
+
+**Mindmap Colors** (in `utils/mindmap_generator.py`):
+```python
+self.level_colors = {
+    0: "#ff6b6b",  # Center - red/coral
+    1: "#4ecdc4",  # Primary - teal
+    2: "#95e1d3",  # Secondary - light teal
+    3: "#f9ca24",  # Tertiary - yellow
+    4: "#a29bfe"   # Quaternary - purple
+}
+```
+
+**UI Theme** (in `app.py` CSS section):
+- Modify gradient colors
+- Adjust border radius
+- Change font sizes and families
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue: "Missing API Keys" error**
+- **Solution**: Ensure `.env` file exists and contains valid API keys
+- Check that `.env` is in the project root directory
+- Verify no extra spaces around `=` in `.env`
+
+**Issue: Mindmap not displaying**
+- **Solution**: Check browser console for JavaScript errors
+- Try refreshing the page (Ctrl+R or Cmd+R)
+- Ensure PyVis generated HTML successfully
+
+**Issue: Slow performance**
+- **Solution**: 
+  - Reduce `MAX_NODES` in `.env`
+  - Check internet connection
+  - Verify API rate limits not exceeded
+
+**Issue: "Import Error" on startup**
+- **Solution**:
+  - Ensure virtual environment is activated
+  - Run `pip install -r requirements.txt` again
+  - Check Python version is 3.9+
+
+**Issue: Knowledge Graph API error**
+- **Solution**:
+  - Verify Google Cloud project has Knowledge Graph API enabled
+  - Check project ID is correct
+  - Ensure billing is enabled (free tier available)
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+# In .env
+DEBUG_MODE=true
+```
+
+Then check console output for detailed error messages.
+
+---
+
+## 🔧 Development
+
+### Adding New Features
+
+**Add a new API source:**
+1. Edit `utils/api_handler.py`
+2. Add new async method (e.g., `fetch_xyz_data`)
+3. Integrate into `fetch_all_data()` method
+4. Update documentation
+
+**Customize visualization:**
+1. Edit `utils/mindmap_generator.py`
+2. Modify `create_radial_mindmap()` method
+3. Update PyVis options for physics/styling
+
+### Testing
+
+Run a simple test:
+
+```python
+# test_api.py
+from utils.api_handler import fetch_mindmap_data
+from config.settings import settings
+
+result = fetch_mindmap_data(
+    keyword="Python",
+    gemini_key=settings.gemini_api_key,
+    tavily_key=settings.tavily_api_key,
+    google_project_id=settings.google_cloud_project_id
+)
+
+print(f"Nodes: {len(result['mindmap']['nodes'])}")
+print(f"Edges: {len(result['mindmap']['edges'])}")
+```
+
+---
+
+## 🎯 API Usage & Costs
+
+### Free Tier Limits
+
+**Gemini API:**
+- 60 requests per minute
+- 1500 requests per day
+- Free for personal use
+
+**Tavily API:**
+- 1000 requests per month (free tier)
+- Upgrade available for more
+
+**Knowledge Graph API:**
+- 100,000 free calls per day
+- No credit card required for free tier
+
+### Cost Optimization Tips
+
+1. Enable caching to reduce redundant calls
+2. Use `MAX_NODES` to limit result size
+3. Batch similar queries if possible
+4. Monitor usage in respective dashboards
+
+---
+
+## 📚 Tech Stack
+
+| Technology | Purpose | Version |
+|------------|---------|---------|
+| **Streamlit** | Web framework | 1.28+ |
+| **PyVis** | Graph visualization | 0.3.2+ |
+| **NetworkX** | Graph algorithms | 3.1+ |
+| **Gemini AI** | Language model | Latest |
+| **Tavily** | Web search | Latest |
+| **Knowledge Graph** | Entity data | Latest |
+| **AsyncIO** | Async operations | Built-in |
+| **Pydantic** | Data validation | 2.0+ |
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how:
+
+1. Fork the repository
+2. Create feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open Pull Request
+
+### Development Guidelines
+
+- Follow PEP 8 style guide
+- Add docstrings to all functions
+- Test thoroughly before submitting
+- Update documentation as needed
+
+---
+
+## 📝 License
+
+This project is licensed under the MIT License - see LICENSE file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- [Streamlit](https://streamlit.io/) - Amazing web framework
+- [PyVis](https://pyvis.readthedocs.io/) - Interactive visualizations
+- [Google Gemini](https://ai.google.dev/) - Powerful AI synthesis
+- [Tavily](https://tavily.com/) - Real-time web search
+- [Google Knowledge Graph](https://developers.google.com/knowledge-graph) - Structured data
+
+---
+
+## 📧 Support
+
+For issues, questions, or suggestions:
+- Open an issue on GitHub
+- Email: your.email@example.com
+- Documentation: See inline code comments
+
+---
+
+## 🚀 Roadmap
+
+### Upcoming Features
+
+- [ ] Export mindmaps as PNG/SVG/PDF
+- [ ] Persistent storage with database
+- [ ] User authentication and sharing
+- [ ] Custom color themes
+- [ ] Advanced filtering options
+- [ ] Integration with more knowledge sources
+- [ ] Collaborative editing
+- [ ] Mobile app version
+- [ ] API endpoint for programmatic access
+
+---
+
+**Built with ❤️ using Python, Streamlit, and AI**
+
+---
+
+## 📸 Screenshots
+
+*Add screenshots of your application here*
+
+---
+
+**Last Updated:** October 2025  
+**Version:** 1.0.0  
+**Status:** Production Ready

src/config/settings.py

@@ -0,0 +1,135 @@
+"""
+Configuration management for the Technical Mindmap Generator
+Handles all application settings and API key management
+"""
+import os
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+from typing import Optional
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class Settings(BaseModel):
+    """
+    Application settings with validation
+
+    Attributes:
+        gemini_api_key: Google Gemini API key for AI synthesis
+        tavily_api_key: Tavily API key for web search
+        google_cloud_project_id: Google Cloud project ID for Knowledge Graph
+        max_concurrent_requests: Maximum number of parallel API calls
+        cache_enabled: Enable/disable result caching
+        debug_mode: Enable debug logging
+        max_nodes: Maximum nodes in generated mindmap
+        max_depth: Maximum depth of node hierarchy
+    """
+
+    # API Keys
+    gemini_api_key: str = Field(
+        default_factory=lambda: os.getenv("GEMINI_API_KEY", ""),
+        description="Gemini API key for AI-powered synthesis"
+    )
+
+    tavily_api_key: str = Field(
+        default_factory=lambda: os.getenv("TAVILY_API_KEY", ""),
+        description="Tavily API key for web search"
+    )
+
+    google_cloud_api_key: str = Field(
+    default_factory=lambda: os.getenv("GOOGLE_CLOUD_API_KEY", ""),
+    description="API key for Google Knowledge Graph REST API"
+)
+
+
+    # Application Settings
+    max_concurrent_requests: int = Field(
+        default_factory=lambda: int(os.getenv("MAX_CONCURRENT_REQUESTS", "3")),
+        ge=1,
+        le=10,
+        description="Maximum concurrent API requests"
+    )
+
+    cache_enabled: bool = Field(
+        default_factory=lambda: os.getenv("CACHE_ENABLED", "true").lower() == "true",
+        description="Enable result caching"
+    )
+
+    debug_mode: bool = Field(
+        default_factory=lambda: os.getenv("DEBUG_MODE", "false").lower() == "true",
+        description="Enable debug mode"
+    )
+
+    # Mindmap Settings
+    max_nodes: int = Field(
+        default_factory=lambda: int(os.getenv("MAX_NODES", "20")),
+        ge=5,
+        le=50,
+        description="Maximum nodes in mindmap"
+    )
+
+    max_depth: int = Field(
+        default_factory=lambda: int(os.getenv("MAX_DEPTH", "2")),
+        ge=1,
+        le=5,
+        description="Maximum depth of node hierarchy"
+    )
+
+    class Config:
+        """Pydantic configuration"""
+        env_file = ".env"
+        case_sensitive = False
+
+    def validate_api_keys(self) -> tuple[bool, list[str]]:
+        """
+        Validate that all required API keys are present
+
+        Returns:
+            Tuple of (is_valid, missing_keys)
+        """
+        missing_keys = []
+
+        if not self.gemini_api_key:
+            missing_keys.append("GEMINI_API_KEY")
+
+        if not self.tavily_api_key:
+            missing_keys.append("TAVILY_API_KEY")
+
+        if not self.google_cloud_api_key:
+            missing_keys.append("GOOGLE_CLOUD_API_KEY")
+
+        return (len(missing_keys) == 0, missing_keys)
+
+
+# Create global settings instance
+settings = Settings()
+
+
+def get_settings() -> Settings:
+    """
+    Get the global settings instance
+
+    Returns:
+        Settings object
+    """
+    return settings
+
+
+def display_settings_info():
+    """Print current settings (for debugging)"""
+    print("=" * 50)
+    print("TECHNICAL MINDMAP GENERATOR - SETTINGS")
+    print("=" * 50)
+    print(f"Max Concurrent Requests: {settings.max_concurrent_requests}")
+    print(f"Cache Enabled: {settings.cache_enabled}")
+    print(f"Debug Mode: {settings.debug_mode}")
+    print(f"Max Nodes: {settings.max_nodes}")
+    print(f"Max Depth: {settings.max_depth}")
+
+    is_valid, missing = settings.validate_api_keys()
+    if is_valid:
+        print("✅ All API keys configured")
+    else:
+        print(f"❌ Missing API keys: {', '.join(missing)}")
+    print("=" * 50)

src/streamlit_app.py

@@ -1,40 +1,782 @@
-import altair as alt
-import numpy as np
-import pandas as pd
-import streamlit as st
+"""
+Technical Mindmap Generator - Main Streamlit Application
+Interactive web app for generating radial mindmaps from technical keywords
 
+Features:
+- Modern UI inspired by GPT, Claude, and Perplexity
+- Sequential API calls for optimal data quality
+- Interactive radial mindmaps with PyVis
+- Query history and session management
+- Real-time data from Tavily, Knowledge Graph, and Gemini APIs
 """
-# Welcome to Streamlit!
 
-Edit `/streamlit_app.py` to customize this app to your heart's desire :heart:.
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+import streamlit as st
+import sys
+from pathlib import Path
+import time
 
-In the meantime, below is an example of what you can do with just a few lines of code:
-"""
+# Add project root to path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Import project modules
+try:
+    from config.settings import settings, display_settings_info
+    from utils.api_handler import fetch_mindmap_data
+    from utils.mindmap_generator import MindmapGenerator
+except ImportError as e:
+    st.error(f"Import Error: {e}")
+    st.info("Make sure all project files are in the correct directories")
+    st.stop()
+
+
+# ============================================================================
+# PAGE CONFIGURATION
+# ============================================================================
+
+st.set_page_config(
+    page_title="Technical Mindmap Generator 🧠",
+    page_icon="🧠",
+    layout="wide",
+    initial_sidebar_state="collapsed",
+    menu_items={
+        'Get Help': None,
+        'Report a bug': None,
+        'About': "# Technical Mindmap Generator\nPowered by Gemini, Tavily, and Knowledge Graph APIs"
+    }
+)
+
+
+# ============================================================================
+# CUSTOM CSS STYLING
+# ============================================================================
+
+st.markdown("""
+<style>
+    /* Import Google Fonts - Claude uses serif fonts */
+    @import url('https://fonts.googleapis.com/css2?family=Merriweather:wght@300;400;700&family=Inter:wght@400;500;600;700&display=swap');
+    
+    /* ============================================================
+       MAIN CONTAINER - Claude's Warm Aesthetic
+    ============================================================ */
+    .main {
+        background: #faf9f5;
+        padding: 2rem;
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+    }
+
+    /* Remove default padding */
+    .block-container {
+        padding-top: 2rem;
+        padding-bottom: 3rem;
+        max-width: 1000px;
+    }
+
+    /* ============================================================
+       HEADER SECTION
+    ============================================================ */
+    h1 {
+        color: #3d3929 !important;
+        text-align: center !important;
+        font-size: 3.2rem !important;
+        font-weight: 700 !important;
+        margin-bottom: 0.5rem !important;
+        letter-spacing: -0.5px !important;
+        font-family: 'Merriweather', serif !important;
+    }
+
+    /* Subtitle */
+    .subtitle {
+        color: #6b6656 !important;
+        text-align: center !important;
+        font-size: 1.2rem !important;
+        margin-bottom: 3rem !important;
+        font-weight: 400 !important;
+        font-family: 'Inter', sans-serif !important;
+        line-height: 1.6 !important;
+    }
+
+    /* ============================================================
+       INPUT CONTAINER - Claude's Clean Design
+    ============================================================ */
+    .stTextInput > div > div > input {
+        background: #ffffff !important;
+        color: #3d3929 !important;
+        border-radius: 12px !important;
+        padding: 18px 24px !important;
+        font-size: 16px !important;
+        font-weight: 400 !important;
+        border: 1.5px solid #ddd9cc !important;
+        box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06) !important;
+        transition: all 0.2s ease !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+
+    .stTextInput > div > div > input:focus {
+        border-color: #c15f3c !important;
+        box-shadow: 0 0 0 3px rgba(193, 95, 60, 0.1),
+                    0 1px 3px rgba(0, 0, 0, 0.06) !important;
+        outline: none !important;
+    }
+    
+    .stTextInput > div > div > input::placeholder {
+        color: #9b9688;
+        font-weight: 400;
+    }
+
+    /* ============================================================
+       BUTTON STYLING - Claude's Orange
+    ============================================================ */
+    .stButton > button {
+        background: #c15f3c !important;
+        color: #ffffff !important;
+        border-radius: 10px !important;
+        padding: 14px 32px !important;
+        font-size: 15px !important;
+        font-weight: 600 !important;
+        border: none !important;
+        box-shadow: 0 2px 4px rgba(193, 95, 60, 0.2) !important;
+        transition: all 0.2s ease !important;
+        font-family: 'Inter', sans-serif !important;
+        letter-spacing: 0.3px !important;
+    }
+
+    .stButton > button:hover {
+        background: #a14a2f !important;
+        box-shadow: 0 4px 8px rgba(193, 95, 60, 0.25) !important;
+        transform: translateY(-1px) !important;
+    }
+
+    .stButton > button:active {
+        transform: translateY(0) !important;
+        box-shadow: 0 1px 2px rgba(193, 95, 60, 0.2) !important;
+    }
+
+    /* ============================================================
+       MINDMAP CARD - Clean White Container
+    ============================================================ */
+    .mindmap-card {
+        background: #ffffff;
+        border-radius: 16px;
+        padding: 2.5rem;
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08),
+                    0 1px 2px rgba(0, 0, 0, 0.04);
+        margin: 2rem 0;
+        border: 1px solid #ebe9e0;
+    }
+
+    .mindmap-card h3 {
+        color: #3d3929 !important;
+        font-weight: 700 !important;
+        margin-bottom: 1rem !important;
+        font-size: 1.6rem !important;
+        font-family: 'Merriweather', serif !important;
+    }
+    
+    .mindmap-card p {
+        color: #6b6656;
+        font-size: 1rem;
+        margin-bottom: 1.5rem;
+        line-height: 1.6;
+    }
+
+    /* ============================================================
+       SUCCESS/INFO/ERROR MESSAGES - Claude Style
+    ============================================================ */
+    .stSuccess {
+        background: #f0f8f5 !important;
+        border-radius: 12px !important;
+        padding: 1.2rem !important;
+        border-left: 4px solid #4a9d7f !important;
+        color: #3d3929 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+    
+    .stInfo {
+        background: #f5f3ed !important;
+        border-radius: 12px !important;
+        padding: 1.2rem !important;
+        border-left: 4px solid #c15f3c !important;
+        color: #3d3929 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+
+    .stError {
+        background: #fef2f2 !important;
+        border-radius: 12px !important;
+        padding: 1.2rem !important;
+        border-left: 4px solid #dc2626 !important;
+        color: #3d3929 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+    
+    .stWarning {
+        background: #fef9f3 !important;
+        border-radius: 12px !important;
+        padding: 1.2rem !important;
+        border-left: 4px solid #ea9d3e !important;
+        color: #3d3929 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+
+    /* ============================================================
+       SPINNER STYLING
+    ============================================================ */
+    .stSpinner > div {
+        border-color: #c15f3c transparent #c15f3c transparent !important;
+    }
+
+    /* ============================================================
+       INFO BOX - Claude's Warm Design
+    ============================================================ */
+    .info-box {
+        background: #ffffff;
+        border-left: 4px solid #c15f3c;
+        border-radius: 12px;
+        padding: 2rem;
+        color: #3d3929;
+        margin: 2.5rem 0;
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
+        border: 1px solid #ebe9e0;
+        border-left: 4px solid #c15f3c;
+    }
+
+    .info-box h3 {
+        color: #c15f3c !important;
+        margin-bottom: 1.5rem !important;
+        font-weight: 700 !important;
+        font-family: 'Merriweather', serif !important;
+    }
+
+    .info-box ol {
+        margin-left: 1.5rem;
+        line-height: 1.8;
+    }
+
+    .info-box li {
+        margin: 1rem 0;
+        font-size: 1rem;
+        color: #3d3929;
+    }
+    
+    .info-box p {
+        line-height: 1.7;
+        font-size: 1rem;
+        color: #3d3929;
+    }
+    
+    .info-box strong {
+        color: #3d3929;
+        font-weight: 600;
+    }
+    
+    .info-box em {
+        color: #6b6656;
+        font-style: italic;
+    }
+
+    /* ============================================================
+       EXPANDER STYLING
+    ============================================================ */
+    .streamlit-expanderHeader {
+        background: #f9f8f4 !important;
+        border-radius: 10px !important;
+        font-weight: 600 !important;
+        padding: 1rem 1.5rem !important;
+        border: 1px solid #ebe9e0 !important;
+        color: #3d3929 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+    
+    .streamlit-expanderHeader:hover {
+        background: #f5f3ed !important;
+        border-color: #ddd9cc !important;
+    }
+
+    /* ============================================================
+       METRICS - Claude Style
+    ============================================================ */
+    [data-testid="stMetricValue"] {
+        font-size: 2rem !important;
+        color: #c15f3c !important;
+        font-weight: 700 !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+    
+    [data-testid="stMetricLabel"] {
+        font-size: 0.9rem !important;
+        font-weight: 600 !important;
+        color: #6b6656 !important;
+        text-transform: uppercase !important;
+        letter-spacing: 0.5px !important;
+    }
+
+    /* ============================================================
+       SIDEBAR - Warm Neutral
+    ============================================================ */
+    [data-testid="stSidebar"] {
+        background: #eeece2;
+        border-right: 1px solid #ddd9cc;
+    }
+
+    [data-testid="stSidebar"] .stButton > button {
+        background: #ffffff !important;
+        border: 1.5px solid #ddd9cc !important;
+        color: #3d3929 !important;
+        border-radius: 10px !important;
+        padding: 10px 16px !important;
+        font-size: 0.9rem !important;
+        font-weight: 600 !important;
+        transition: all 0.2s ease !important;
+        font-family: 'Inter', sans-serif !important;
+    }
+
+    [data-testid="stSidebar"] .stButton > button:hover {
+        background: #f5f3ed !important;
+        border-color: #c15f3c !important;
+        color: #c15f3c !important;
+    }
+    
+    [data-testid="stSidebar"] h1 {
+        font-size: 1.3rem !important;
+        color: #3d3929 !important;
+        margin-bottom: 1rem !important;
+        font-family: 'Merriweather', serif !important;
+    }
+    
+    [data-testid="stSidebar"] .stMarkdown {
+        color: #3d3929;
+        font-family: 'Inter', sans-serif;
+    }
+
+    /* ============================================================
+       HORIZONTAL RULE
+    ============================================================ */
+    hr {
+        border: none;
+        height: 1px;
+        background: #ebe9e0;
+        margin: 2rem 0;
+    }
+
+    /* ============================================================
+       LINKS - Claude Orange
+    ============================================================ */
+    a {
+        color: #c15f3c !important;
+        text-decoration: none !important;
+        font-weight: 500 !important;
+        transition: color 0.2s ease !important;
+    }
+    
+    a:hover {
+        color: #a14a2f !important;
+        text-decoration: underline !important;
+    }
+
+    /* ============================================================
+       HIDE STREAMLIT BRANDING
+    ============================================================ */
+    #MainMenu {visibility: hidden;}
+    footer {visibility: hidden;}
+    header {visibility: hidden;}
+    
+    /* ============================================================
+       CUSTOM SCROLLBAR - Claude Style
+    ============================================================ */
+    ::-webkit-scrollbar {
+        width: 8px;
+        height: 8px;
+    }
+    
+    ::-webkit-scrollbar-track {
+        background: #f5f3ed;
+    }
+    
+    ::-webkit-scrollbar-thumb {
+        background: #c15f3c;
+        border-radius: 4px;
+    }
+    
+    ::-webkit-scrollbar-thumb:hover {
+        background: #a14a2f;
+    }
+
+    /* ============================================================
+       TYPOGRAPHY IMPROVEMENTS
+    ============================================================ */
+    body {
+        font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+        color: #3d3929;
+        line-height: 1.6;
+    }
+    
+    h2, h3, h4, h5, h6 {
+        font-family: 'Merriweather', serif;
+        color: #3d3929;
+    }
+    
+    /* ============================================================
+       RESPONSIVE DESIGN
+    ============================================================ */
+    @media (max-width: 768px) {
+        h1 {
+            font-size: 2.2rem !important;
+        }
+        
+        .subtitle {
+            font-size: 1rem !important;
+        }
+        
+        .mindmap-card {
+            padding: 1.5rem;
+        }
+        
+        .stTextInput > div > div > input {
+            font-size: 15px !important;
+            padding: 14px 18px !important;
+        }
+        
+        .stButton > button {
+            font-size: 14px !important;
+            padding: 12px 24px !important;
+        }
+    }
+    
+    /* ============================================================
+       SMOOTH INTERACTIONS
+    ============================================================ */
+    * {
+        transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+    }
+    
+    html {
+        scroll-behavior: smooth;
+    }
+
+    /* ============================================================
+       CLEAN, MINIMAL AESTHETIC
+    ============================================================ */
+    .stApp {
+        background: #faf9f5;
+    }
+    
+    /* Remove unnecessary decorations */
+    .stDeployButton {
+        display: none;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+
+
+# ============================================================================
+# SESSION STATE MANAGEMENT
+# ============================================================================
+
+def initialize_session_state():
+    """Initialize all session state variables"""
+    if 'mindmap_history' not in st.session_state:
+        st.session_state.mindmap_history = []
+
+    if 'current_mindmap' not in st.session_state:
+        st.session_state.current_mindmap = None
+
+    if 'query_count' not in st.session_state:
+        st.session_state.query_count = 0
+
+    if 'last_keyword' not in st.session_state:
+        st.session_state.last_keyword = ""
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def validate_api_keys() -> tuple[bool, list[str]]:
+    """
+    Validate that all required API keys are configured
+
+    Returns:
+        Tuple of (is_valid, missing_keys_list)
+    """
+    return settings.validate_api_keys()
+
+
+def generate_mindmap(keyword: str) -> dict:
+    """
+    Generate mindmap for given keyword using API handler
+
+    Args:
+        keyword: Technical keyword to analyze
+
+    Returns:
+        Dictionary with mindmap data and metadata
+    """
+    try:
+        result = fetch_mindmap_data(
+            keyword=keyword,
+            gemini_key=settings.gemini_api_key,
+            tavily_key=settings.tavily_api_key,
+            kg_api_key=settings.google_cloud_api_key
+        )
+        return result
+    except Exception as e:
+        st.error(f"Error generating mindmap: {str(e)}")
+        return None
+
+
+# ============================================================================
+# MAIN APPLICATION
+# ============================================================================
+
+def main():
+    """Main application logic"""
+
+    # Initialize session state
+    initialize_session_state()
+
+    # ========================================================================
+    # HEADER SECTION
+    # ========================================================================
+
+    st.markdown("<h1>🧠 Technical Mindmap Generator</h1>", unsafe_allow_html=True)
+    st.markdown(
+        "<p class='subtitle'>Transform technical keywords into interactive visual mindmaps powered by AI</p>",
+        unsafe_allow_html=True
+    )
+
+    # ========================================================================
+    # API KEY VALIDATION
+    # ========================================================================
+
+    is_valid, missing_keys = validate_api_keys()
+
+    if not is_valid:
+        st.error(f"⚠️ Missing API Keys: {', '.join(missing_keys)}")
+        st.info("Please configure your API keys in the `.env` file before using the application.")
+
+        with st.expander("📝 How to set up API keys"):
+            st.markdown("""
+            1. Create a `.env` file in the project root
+            2. Add your API keys:
+               ```
+               GEMINI_API_KEY=your_gemini_key
+               TAVILY_API_KEY=your_tavily_key
+
+               ```
+            3. Restart the application
+
+            **Get API Keys:**
+            - Gemini: https://ai.google.dev/
+            - Tavily: https://tavily.com/
+            - Google Cloud: https://console.cloud.google.com/
+            """)
+
+        st.stop()
+
+    # ========================================================================
+    # INPUT SECTION
+    # ========================================================================
+
+    # Center the input field
+    col1, col2, col3 = st.columns([1, 3, 1])
+
+    with col2:
+        keyword = st.text_input(
+            "",
+            placeholder="e.g., Machine Learning, Blockchain, Kubernetes, Neural Networks...",
+            key=f"keyword_input_{st.session_state.query_count}",
+            label_visibility="collapsed",
+            help="Enter any technical keyword or concept"
+        )
+
+        # Center the button
+        btn_col1, btn_col2, btn_col3 = st.columns([1, 1, 1])
+        with btn_col2:
+            generate_button = st.button(
+                "🚀 Generate Mindmap",
+                use_container_width=True,
+                type="primary"
+            )
+
+    # ========================================================================
+    # MINDMAP GENERATION
+    # ========================================================================
+
+    if generate_button and keyword:
+        # Validate keyword
+        if len(keyword.strip()) < 2:
+            st.warning("⚠️ Please enter a longer keyword (at least 2 characters)")
+        else:
+            # Show loading animation
+            with st.spinner(f"🔍 Analyzing '{keyword}'...\n\n⚡ This may take 10-15 seconds..."):
+
+                # Add progress messages
+                progress_placeholder = st.empty()
+
+                progress_placeholder.info("📡 Step 1/3: Fetching web data from Tavily...")
+                time.sleep(1)
+
+                progress_placeholder.info("🔗 Step 2/3: Querying Knowledge Graph...")
+                time.sleep(1)
+
+                progress_placeholder.info("🤖 Step 3/3: Synthesizing with Gemini AI...")
+
+                # Generate mindmap
+                result = generate_mindmap(keyword)
+
+                # Clear progress messages
+                progress_placeholder.empty()
+
+                if result:
+                    # Store in session state
+                    st.session_state.current_mindmap = result
+                    st.session_state.mindmap_history.append({
+                        'keyword': keyword,
+                        'data': result,
+                        'timestamp': time.time()
+                    })
+                    st.session_state.query_count += 1
+                    st.session_state.last_keyword = keyword
+
+                    st.success(f"✅ Mindmap generated successfully for '{keyword}'!")
+                else:
+                    st.error("❌ Failed to generate mindmap. Please try again.")
+
+    # ========================================================================
+    # DISPLAY MINDMAP
+    # ========================================================================
+
+    if st.session_state.current_mindmap:
+        st.markdown("<div class='mindmap-card'>", unsafe_allow_html=True)
+
+        # Display mindmap
+        mindmap_data = st.session_state.current_mindmap['mindmap']
+
+        st.markdown(f"### 🗺️ Mindmap: {st.session_state.last_keyword}")
+        st.markdown("*Zoom, pan, and hover over nodes for details*")
+
+        try:
+            generator = MindmapGenerator(height="700px", width="100%")
+            generator.render_in_streamlit(mindmap_data)
+        except Exception as e:
+            st.error(f"Error rendering mindmap: {e}")
+
+        st.markdown("</div>", unsafe_allow_html=True)
+
+        # ====================================================================
+        # METADATA SECTION
+        # ====================================================================
+
+        with st.expander("📊 View Generation Details", expanded=False):
+            metadata = st.session_state.current_mindmap['metadata']
+
+            # Metrics in columns
+            metric_col1, metric_col2, metric_col3, metric_col4 = st.columns(4)
+
+            with metric_col1:
+                st.metric("🎯 Keyword", metadata['keyword'])
+
+            with metric_col2:
+                st.metric("🔗 Total Nodes", metadata.get('total_nodes', 0))
+
+            with metric_col3:
+                st.metric("📚 Sources", len(metadata.get('tavily_sources', [])))
+
+            with metric_col4:
+                st.metric("🔍 KG Entities", metadata.get('kg_entities_count', 0))
+
+            st.markdown("---")
+
+            # Display sources
+            if metadata.get('tavily_sources'):
+                st.subheader("📚 Information Sources")
+                for i, source in enumerate(metadata['tavily_sources'][:8], 1):
+                    st.markdown(f"{i}. [{source}]({source})")
+
+    else:
+        # ====================================================================
+        # WELCOME / INFO SECTION
+        # ====================================================================
+
+        st.markdown("""
+        <div class='info-box'>
+            <h3>💡 How it works:</h3>
+            <ol>
+                <li><strong>Tavily API</strong>: Gathers real-time web context and discovers related terms</li>
+                <li><strong>Knowledge Graph API</strong>: Provides structured entity relationships and descriptions</li>
+                <li><strong>Gemini AI</strong>: Synthesizes all data into a comprehensive mindmap structure</li>
+            </ol>
+            <p style='margin-top:1.5rem; font-size:1.1rem;'>
+                <strong>Simply enter a technical keyword above and click "Generate Mindmap" to begin!</strong>
+            </p>
+            <p style='margin-top:1rem; color:#95e1d3;'>
+                💡 <em>Tip: Try keywords like "Kubernetes", "Machine Learning", "Quantum Computing", or "Blockchain"</em>
+            </p>
+        </div>
+        """, unsafe_allow_html=True)
+
+    # ========================================================================
+    # SIDEBAR - HISTORY & SETTINGS
+    # ========================================================================
+
+    with st.sidebar:
+        st.title("📜 Query History")
+
+        if st.session_state.mindmap_history:
+            st.markdown(f"**Total Queries:** {len(st.session_state.mindmap_history)}")
+            st.markdown("---")
+
+            # Display history in reverse order (most recent first)
+            for i, item in enumerate(reversed(st.session_state.mindmap_history)):
+                keyword_display = item['keyword']
+
+                # Create button with emoji
+                if st.button(
+                    f"🔄 {keyword_display}",
+                    key=f"history_{i}",
+                    help=f"Load mindmap for '{keyword_display}'"
+                ):
+                    st.session_state.current_mindmap = item['data']
+                    st.session_state.last_keyword = item['keyword']
+                    st.rerun()
+        else:
+            st.info("No queries yet.\nGenerate your first mindmap!")
+
+        st.markdown("---")
+
+        # Settings section
+        st.markdown("### ⚙️ Settings")
+        st.markdown(f"**Max Nodes:** {settings.max_nodes}")
+        st.markdown(f"**Max Depth:** {settings.max_depth}")
+        st.markdown(f"**Caching:** {'Enabled' if settings.cache_enabled else 'Disabled'}")
+
+        st.markdown("---")
+
+        # About section
+        with st.expander("ℹ️ About"):
+            st.markdown("""
+            **Technical Mindmap Generator**
+
+            Version 1.0.0
+
+            A proof-of-concept application that creates interactive visual mindmaps for technical concepts using AI-powered APIs.
+
+            **Technologies:**
+            - Streamlit
+            - PyVis
+            - Gemini AI
+            - Tavily Search
+            - Knowledge Graph
+
+            **Created by:** Your Name
+            """)
+
+
+# ============================================================================
+# APPLICATION ENTRY POINT
+# ============================================================================
 
-num_points = st.slider("Number of points in spiral", 1, 10000, 1100)
-num_turns = st.slider("Number of turns in spiral", 1, 300, 31)
-
-indices = np.linspace(0, 1, num_points)
-theta = 2 * np.pi * num_turns * indices
-radius = indices
-
-x = radius * np.cos(theta)
-y = radius * np.sin(theta)
-
-df = pd.DataFrame({
-    "x": x,
-    "y": y,
-    "idx": indices,
-    "rand": np.random.randn(num_points),
-})
-
-st.altair_chart(alt.Chart(df, height=700, width=700)
-    .mark_point(filled=True)
-    .encode(
-        x=alt.X("x", axis=None),
-        y=alt.Y("y", axis=None),
-        color=alt.Color("idx", legend=None, scale=alt.Scale()),
-        size=alt.Size("rand", legend=None, scale=alt.Scale(range=[1, 150])),
-    ))
+if __name__ == "__main__":
+    main()

src/utils/api_handler.py

@@ -0,0 +1,461 @@
+"""
+API Handler for Gemini, Tavily, and Knowledge Graph APIs
+Implements optimized sequential async calls for mindmap generation
+
+This module orchestrates API calls in the following sequence:
+1. Tavily API: Gather broad web context and related terms
+2. Knowledge Graph API: Get structured entity data using Tavily results
+3. Gemini API: Synthesize comprehensive mindmap structure
+"""
+
+import asyncio
+import json
+import re
+from typing import Dict, List, Any, Optional
+from tavily import TavilyClient
+import google.generativeai as genai
+from google.cloud import enterpriseknowledgegraph as ekg
+import logging
+import requests
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class APIHandler:
+    """
+    Handles all API interactions with optimized sequential processing
+
+    This class manages communication with three external APIs:
+    - Tavily: Real-time web search and content extraction
+    - Knowledge Graph: Structured entity and relationship data
+    - Gemini: AI-powered synthesis and structure generation
+    """
+
+    def __init__(self, gemini_key: str, tavily_key: str, kg_api_key: str):
+        """
+        Initialize API clients with provided credentials
+
+        Args:
+            gemini_key: Gemini API key
+            tavily_key: Tavily API key
+            google_project_id: Google Cloud project ID
+        """
+        self.gemini_key = gemini_key
+        self.tavily_key = tavily_key
+        self.kg_api_key = kg_api_key
+
+        # Initialize Tavily client
+        try:
+            self.tavily_client = TavilyClient(api_key=tavily_key)
+            logger.info("✅ Tavily client initialized")
+        except Exception as e:
+            logger.error(f"❌ Tavily initialization failed: {e}")
+            self.tavily_client = None
+
+        # Initialize Gemini
+        try:
+            genai.configure(api_key=gemini_key)
+            self.gemini_model = genai.GenerativeModel('gemini-2.0-flash')
+            logger.info("✅ Gemini client initialized")
+        except Exception as e:
+            logger.error(f"❌ Gemini initialization failed: {e}")
+            self.gemini_model = None
+
+        
+
+    async def fetch_tavily_data(self, keyword: str) -> Dict[str, Any]:
+        """
+        Step 1: Fetch related terms and context from Tavily API
+
+        This method performs a web search to gather:
+        - Related technical terms
+        - Contextual information
+        - Source URLs for reference
+
+        Args:
+            keyword: Technical keyword to search
+
+        Returns:
+            Dictionary containing:
+            - key_terms: List of related terms (max 15)
+            - context: Aggregated context from top results
+            - sources: List of source URLs
+        """
+        logger.info(f"🔍 Step 1: Fetching Tavily data for '{keyword}'")
+
+        if not self.tavily_client:
+            logger.warning("Tavily client not available, using fallback")
+            return {'key_terms': [], 'context': '', 'sources': []}
+
+        try:
+            # Perform advanced search
+            response = self.tavily_client.search(
+                query=f"{keyword} technical overview concepts",
+                search_depth="advanced",
+                max_results=10,
+                include_domains=[],
+                exclude_domains=[]
+            )
+
+            # Extract key terms and context
+            key_terms = set()
+            context_parts = []
+            sources = []
+
+            for result in response.get('results', []):
+                content = result.get('content', '')
+                url = result.get('url', '')
+
+                # Store context and source
+                if content:
+                    context_parts.append(content)
+                if url:
+                    sources.append(url)
+
+                # Extract meaningful terms (simple extraction)
+                words = re.findall(r'\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b', content)
+                technical_words = [w for w in words if len(w) > 4]
+                key_terms.update(technical_words[:20])
+
+            # Limit and format results
+            key_terms_list = list(key_terms)[:15]
+            context = ' '.join(context_parts[:3])[:2000]  # Limit context length
+
+            logger.info(f"✅ Tavily: Found {len(key_terms_list)} key terms from {len(sources)} sources")
+
+            return {
+                'key_terms': key_terms_list,
+                'context': context,
+                'sources': sources
+            }
+
+        except Exception as e:
+            logger.error(f"❌ Tavily API error: {e}")
+            return {
+                'key_terms': [keyword],
+                'context': f"Technical information about {keyword}",
+                'sources': []
+            }
+
+    async def fetch_knowledge_graph_data(self, keyword: str) -> Dict[str, Any]:
+        if not self.kg_api_key:
+            print("⚠️ Knowledge Graph skipped (no API key)")
+            return {}
+
+        url = "https://kgsearch.googleapis.com/v1/entities:search"
+        params = {
+            'query': keyword,
+            'limit': 5,
+            'key': self.kg_api_key,
+        }
+        try:
+            response = requests.get(url, params=params, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+
+            entities = []
+            for item in data.get('itemListElement', [])[:5]:
+                result = item.get('result', {})
+                entities.append({
+                    'name': result.get('name', ''),
+                    'description': result.get('description', '')
+                })
+
+            return {'entities': entities, 'relationships': []}
+
+        except Exception as e:
+            print(f"  ✗ Error querying Knowledge Graph: {e}")
+            return {}
+
+    
+    
+    async def generate_gemini_mindmap(
+        self,
+        keyword: str,
+        tavily_data: Dict[str, Any],
+        kg_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Step 3: Use Gemini to synthesize comprehensive mindmap structure
+
+        Combines data from Tavily and Knowledge Graph to create a
+        well-structured, hierarchical mindmap.
+
+        Args:
+            keyword: Main technical keyword
+            tavily_data: Data from Tavily API (context, terms, sources)
+            kg_data: Data from Knowledge Graph API (entities, relationships)
+
+        Returns:
+            Dictionary containing complete mindmap structure:
+            - center: Central node (keyword)
+            - nodes: List of node dictionaries
+            - edges: List of edge dictionaries
+        """
+        logger.info(f"🔍 Step 3: Generating Gemini mindmap for '{keyword}'")
+
+        if not self.gemini_model:
+            logger.warning("Gemini model not available, using fallback")
+            return self._create_fallback_mindmap(keyword, tavily_data, kg_data)
+
+        try:
+            # Prepare context for Gemini
+            key_terms_str = ', '.join(tavily_data.get('key_terms', [])[:10])
+
+            entities_info = []
+            for entity in kg_data.get('entities', [])[:5]:
+                entities_info.append(
+                    f"- {entity['name']}: {entity['description']}"
+                )
+            entities_str = '\n'.join(entities_info) if entities_info else "No entities found"
+
+            context_snippet = tavily_data.get('context', '')[:1000]
+
+            # Construct enriched prompt
+            prompt = f"""You are a technical knowledge expert creating mindmap structures.
+
+Generate a comprehensive radial mindmap structure for: "{keyword}"
+
+Web Context:
+{context_snippet}
+
+Related Terms Discovered:
+{key_terms_str}
+
+Knowledge Graph Entities:
+{entities_str}
+
+Create a JSON mindmap with:
+1. Center node: "{keyword}" 
+2. Primary nodes (5-7): Major categories/aspects of this technical topic
+3. Secondary nodes (2-3 per primary): Specific concepts, tools, or subtopics
+
+Requirements:
+- Each node must have: id, label, level (1=primary, 2=secondary), description
+- Each edge must have: from (node id), to (node id), label (relationship type)
+- Use descriptive labels and meaningful relationships
+- Keep descriptions concise (under 100 chars)
+
+Output ONLY valid JSON in this exact format:
+{{
+  "center": "{keyword}",
+  "nodes": [
+    {{"id": "node1", "label": "Category Name", "level": 1, "description": "Brief explanation"}},
+    {{"id": "node2", "label": "Subconcept", "level": 2, "description": "Specific detail"}}
+  ],
+  "edges": [
+    {{"from": "center", "to": "node1", "label": "includes"}},
+    {{"from": "node1", "to": "node2", "label": "contains"}}
+  ]
+}}
+
+Generate the JSON now:"""
+
+            # Call Gemini API
+            response = self.gemini_model.generate_content(prompt)
+            response_text = response.text.strip()
+
+            # Clean response (remove markdown code blocks if present)
+            if '```json' in response_text:
+                response_text = response_text.split('```json')[1].split('```')[0].strip()
+            elif '```' in response_text:
+                response_text = response_text.split('```')[1].split('```')[0].strip()
+
+            # Parse JSON
+            mindmap_data = json.loads(response_text)
+
+            # Validate structure
+            if 'center' not in mindmap_data:
+                mindmap_data['center'] = keyword
+            if 'nodes' not in mindmap_data:
+                mindmap_data['nodes'] = []
+            if 'edges' not in mindmap_data:
+                mindmap_data['edges'] = []
+
+            logger.info(f"✅ Gemini: Generated mindmap with {len(mindmap_data['nodes'])} nodes")
+
+            return mindmap_data
+
+        except json.JSONDecodeError as e:
+            logger.error(f"❌ Gemini JSON parse error: {e}")
+            return self._create_fallback_mindmap(keyword, tavily_data, kg_data)
+        except Exception as e:
+            logger.error(f"❌ Gemini API error: {e}")
+            return self._create_fallback_mindmap(keyword, tavily_data, kg_data)
+
+    def _create_fallback_mindmap(
+        self,
+        keyword: str,
+        tavily_data: Dict[str, Any],
+        kg_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Create a basic fallback mindmap when Gemini fails
+
+        Args:
+            keyword: Main keyword
+            tavily_data: Tavily results
+            kg_data: Knowledge Graph results
+
+        Returns:
+            Basic mindmap structure
+        """
+        logger.info("Creating fallback mindmap structure")
+
+        nodes = []
+        edges = []
+
+        # Add primary nodes from key terms
+        key_terms = tavily_data.get('key_terms', [])[:6]
+        for i, term in enumerate(key_terms):
+            node_id = f"primary_{i}"
+            nodes.append({
+                'id': node_id,
+                'label': term,
+                'level': 1,
+                'description': f"Related concept to {keyword}"
+            })
+            edges.append({
+                'from': 'center',
+                'to': node_id,
+                'label': 'related_to'
+            })
+
+        # Add secondary nodes from entities
+        entities = kg_data.get('entities', [])[:4]
+        for i, entity in enumerate(entities):
+            node_id = f"secondary_{i}"
+            nodes.append({
+                'id': node_id,
+                'label': entity['name'],
+                'level': 2,
+                'description': entity['description'][:100]
+            })
+            # Connect to first primary node if available
+            if key_terms:
+                edges.append({
+                    'from': 'primary_0',
+                    'to': node_id,
+                    'label': 'includes'
+                })
+
+        return {
+            'center': keyword,
+            'nodes': nodes,
+            'edges': edges
+        }
+
+    async def fetch_all_data(self, keyword: str) -> Dict[str, Any]:
+        """
+        Orchestrate all API calls in optimized sequence
+
+        This is the main entry point that executes the 3-step process:
+        1. Tavily → Get web context and related terms
+        2. Knowledge Graph → Get structured entities (using Tavily results)
+        3. Gemini → Synthesize comprehensive mindmap (using both)
+
+        Args:
+            keyword: Technical keyword to analyze
+
+        Returns:
+            Complete result dictionary with:
+            - mindmap: Full mindmap structure
+            - metadata: Additional information (sources, counts, etc.)
+        """
+        logger.info(f"\n{'='*60}")
+        logger.info(f"Starting mindmap generation for: '{keyword}'")
+        logger.info(f"{'='*60}")
+
+        try:
+            # Step 1: Fetch Tavily data (context + terms)
+            tavily_data = await self.fetch_tavily_data(keyword)
+
+            # Step 2: Fetch Knowledge Graph data (using Tavily results)
+            kg_data = await self.fetch_knowledge_graph_data(keyword)
+
+            
+
+            # Step 3: Generate mindmap with Gemini (using both results)
+            mindmap_data = await self.generate_gemini_mindmap(
+                keyword,
+                tavily_data,
+                kg_data
+            )
+
+            # Compile metadata
+            metadata = {
+                'keyword': keyword,
+                'tavily_sources': tavily_data.get('sources', []),
+                'kg_entities_count': len(kg_data.get('entities', [])),
+                'total_nodes': len(mindmap_data.get('nodes', [])),
+                'total_edges': len(mindmap_data.get('edges', []))
+            }
+
+            logger.info(f"{'='*60}")
+            logger.info(f"✅ Mindmap generation complete!")
+            logger.info(f"   - Nodes: {metadata['total_nodes']}")
+            logger.info(f"   - Edges: {metadata['total_edges']}")
+            logger.info(f"   - Sources: {len(metadata['tavily_sources'])}")
+            logger.info(f"{'='*60}\n")
+
+            return {
+                'mindmap': mindmap_data,
+                'metadata': metadata
+            }
+
+        except Exception as e:
+            logger.error(f"❌ Critical error in fetch_all_data: {e}")
+
+            # Return minimal fallback
+            return {
+                'mindmap': {
+                    'center': keyword,
+                    'nodes': [{
+                        'id': 'fallback_1',
+                        'label': 'Error generating mindmap',
+                        'level': 1,
+                        'description': 'Please check API configuration'
+                    }],
+                    'edges': [{
+                        'from': 'center',
+                        'to': 'fallback_1',
+                        'label': 'error'
+                    }]
+                },
+                'metadata': {
+                    'keyword': keyword,
+                    'tavily_sources': [],
+                    'kg_entities_count': 0,
+                    'total_nodes': 1,
+                    'total_edges': 1,
+                    'error': str(e)
+                }
+            }
+
+
+# Synchronous wrapper for Streamlit compatibility
+def fetch_mindmap_data(
+    keyword: str,
+    gemini_key: str,
+    tavily_key: str,
+    kg_api_key: str
+) -> Dict[str, Any]:
+    """
+    Synchronous wrapper for async API calls (Streamlit-compatible)
+    """
+    handler = APIHandler(
+        gemini_key=gemini_key,
+        tavily_key=tavily_key,
+        kg_api_key=kg_api_key
+    )
+
+    return asyncio.run(handler.fetch_all_data(keyword))
+
+
+
+if __name__ == "__main__":
+    # Test the API handler
+    print("API Handler Module - Ready for import")
+    print("Use fetch_mindmap_data() to generate mindmaps")

src/utils/mindmap_generator.py

@@ -0,0 +1,305 @@
+"""
+Mindmap Generator using PyVis for interactive radial visualizations
+Creates beautiful, explorable mindmaps with custom styling
+"""
+
+from pyvis.network import Network
+import networkx as nx
+from typing import Dict, Any, Optional
+import streamlit.components.v1 as components
+import tempfile
+import os
+
+
+class MindmapGenerator:
+    """
+    Generate interactive radial mindmaps using PyVis
+
+    Features:
+    - Radial layout with ForceAtlas2 physics
+    - Color-coded hierarchy levels
+    - Interactive zoom, pan, and hover
+    - Customizable styling and dimensions
+    """
+
+    def __init__(
+        self,
+        height: str = "650px",
+        width: str = "100%",
+        bgcolor: str = "#1e1e1e",
+        font_color: str = "#ffffff"
+    ):
+        """
+        Initialize mindmap generator with display settings
+
+        Args:
+            height: Height of visualization (CSS format)
+            width: Width of visualization (CSS format)
+            bgcolor: Background color (hex)
+            font_color: Font color (hex)
+        """
+        self.height = height
+        self.width = width
+        self.bgcolor = bgcolor
+        self.font_color = font_color
+
+        # Color scheme for node levels
+        self.level_colors = {
+            0: "#ff6b6b",  # Center - red/coral
+            1: "#4ecdc4",  # Primary - teal
+            2: "#95e1d3",  # Secondary - light teal
+            3: "#f9ca24",  # Tertiary - yellow
+            4: "#a29bfe"   # Quaternary - purple
+        }
+
+    def create_radial_mindmap(self, mindmap_data: Dict[str, Any]) -> Network:
+        """
+        Create interactive radial mindmap from structured data
+
+        Args:
+            mindmap_data: Dictionary with center, nodes, and edges
+
+        Returns:
+            Configured PyVis Network object
+        """
+        # Initialize PyVis network
+        net = Network(
+            height=self.height,
+            width=self.width,
+            bgcolor=self.bgcolor,
+            font_color=self.font_color,
+            notebook=False,
+            directed=False
+        )
+
+        # Configure physics for radial layout
+        net.set_options("""
+        {
+            "physics": {
+                "enabled": true,
+                "forceAtlas2Based": {
+                    "gravitationalConstant": -50,
+                    "centralGravity": 0.005,
+                    "springLength": 150,
+                    "springConstant": 0.08,
+                    "damping": 0.4,
+                    "avoidOverlap": 0.5
+                },
+                "maxVelocity": 50,
+                "solver": "forceAtlas2Based",
+                "timestep": 0.35,
+                "stabilization": {
+                    "enabled": true,
+                    "iterations": 1000,
+                    "updateInterval": 25
+                }
+            },
+            "interaction": {
+                "hover": true,
+                "hoverConnectedEdges": true,
+                "tooltipDelay": 100,
+                "navigationButtons": true,
+                "keyboard": {
+                    "enabled": true,
+                    "speed": {"x": 10, "y": 10, "zoom": 0.02}
+                },
+                "zoomView": true,
+                "dragView": true
+            },
+            "edges": {
+                "smooth": {
+                    "enabled": true,
+                    "type": "continuous",
+                    "roundness": 0.5
+                }
+            }
+        }
+        """)
+
+        # Add center node
+        center = mindmap_data.get('center', 'Unknown Topic')
+        net.add_node(
+            'center',
+            label=center,
+            title=f"<div style='padding:10px'><b style='font-size:16px'>{center}</b><br><i>Central Topic</i></div>",
+            size=45,
+            color=self.level_colors[0],
+            font={'size': 24, 'color': self.font_color, 'face': 'Arial', 'bold': True},
+            borderWidth=3,
+            borderWidthSelected=5
+        )
+
+        # Add nodes with level-based styling
+        for node in mindmap_data.get('nodes', []):
+            node_id = node.get('id', '')
+            label = node.get('label', node_id)
+            level = node.get('level', 1)
+            description = node.get('description', '')
+
+            # Size decreases with level
+            size = max(35 - (level * 7), 15)
+
+            # Font size decreases with level
+            font_size = max(18 - (level * 2), 12)
+
+            # Get color for this level
+            color = self.level_colors.get(level, self.level_colors[2])
+
+            # Create rich tooltip
+            tooltip = f"""
+            <div style='padding:12px; max-width:300px;'>
+                <b style='font-size:14px; color:#4ecdc4;'>{label}</b><br>
+                <span style='color:#888;'>Level {level}</span><br>
+                <p style='margin-top:8px; font-size:12px;'>{description}</p>
+            </div>
+            """
+
+            net.add_node(
+                node_id,
+                label=label,
+                title=tooltip,
+                size=size,
+                color=color,
+                font={
+                    'size': font_size,
+                    'color': self.font_color,
+                    'face': 'Arial'
+                },
+                borderWidth=2,
+                borderWidthSelected=4,
+                shape='dot'
+            )
+
+        # Add edges with relationship labels
+        for edge in mindmap_data.get('edges', []):
+            from_node = edge.get('from', '')
+            to_node = edge.get('to', '')
+            label = edge.get('label', '')
+
+            # Edge styling
+            net.add_edge(
+                from_node,
+                to_node,
+                title=label if label else 'related to',
+                label=label if len(label) < 15 else '',  # Only show short labels
+                color={'color': '#666666', 'opacity': 0.6},
+                width=2,
+                smooth={'type': 'continuous'}
+            )
+
+        return net
+
+    def generate_html(self, mindmap_data: Dict[str, Any]) -> str:
+        """
+        Generate HTML string for the mindmap
+
+        Args:
+            mindmap_data: Mindmap structure
+
+        Returns:
+            Complete HTML as string
+        """
+        net = self.create_radial_mindmap(mindmap_data)
+
+        # Generate HTML
+        html_content = net.generate_html()
+
+        return html_content
+
+    def save_to_file(self, mindmap_data: Dict[str, Any], filename: str = "mindmap.html"):
+        """
+        Save mindmap to HTML file
+
+        Args:
+            mindmap_data: Mindmap structure
+            filename: Output filename
+        """
+        net = self.create_radial_mindmap(mindmap_data)
+        net.save_graph(filename)
+        print(f"✅ Mindmap saved to {filename}")
+
+    def render_in_streamlit(self, mindmap_data: Dict[str, Any]):
+        """
+        Render mindmap directly in Streamlit application
+
+        Args:
+            mindmap_data: Mindmap structure
+        """
+        html_content = self.generate_html(mindmap_data)
+
+        # Display using Streamlit components
+        components.html(
+            html_content,
+            height=int(self.height.replace('px', '')),
+            scrolling=False
+        )
+
+
+# Convenience functions for direct usage
+def generate_mindmap_html(mindmap_data: Dict[str, Any]) -> str:
+    """
+    Quick function to generate mindmap HTML
+
+    Args:
+        mindmap_data: Mindmap structure
+
+    Returns:
+        HTML string
+    """
+    generator = MindmapGenerator()
+    return generator.generate_html(mindmap_data)
+
+
+def create_sample_mindmap() -> Dict[str, Any]:
+    """
+    Create a sample mindmap for testing
+
+    Returns:
+        Sample mindmap data structure
+    """
+    return {
+        'center': 'Machine Learning',
+        'nodes': [
+            {
+                'id': 'supervised',
+                'label': 'Supervised Learning',
+                'level': 1,
+                'description': 'Learning with labeled data'
+            },
+            {
+                'id': 'unsupervised',
+                'label': 'Unsupervised Learning',
+                'level': 1,
+                'description': 'Learning from unlabeled data'
+            },
+            {
+                'id': 'classification',
+                'label': 'Classification',
+                'level': 2,
+                'description': 'Categorizing data into classes'
+            },
+            {
+                'id': 'regression',
+                'label': 'Regression',
+                'level': 2,
+                'description': 'Predicting continuous values'
+            }
+        ],
+        'edges': [
+            {'from': 'center', 'to': 'supervised', 'label': 'includes'},
+            {'from': 'center', 'to': 'unsupervised', 'label': 'includes'},
+            {'from': 'supervised', 'to': 'classification', 'label': 'type'},
+            {'from': 'supervised', 'to': 'regression', 'label': 'type'}
+        ]
+    }
+
+
+if __name__ == "__main__":
+    # Test the generator
+    print("Mindmap Generator Module - Ready for import")
+    print("Use MindmapGenerator class to create visualizations")
+
+    # Create sample
+    sample = create_sample_mindmap()
+    generator = MindmapGenerator()
+    generator.save_to_file(sample, "test_mindmap.html")