src/README.md

🧠 Technical Mindmap Generator

An AI-powered Streamlit application that generates interactive radial mindmaps for technical keywords using Gemini, Tavily, and Knowledge Graph APIs.

---

✨ 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 (Free tier available)
  • Tavily API Key (Free tier: 1000 requests/month)
  • Google Cloud Project with Knowledge Graph API enabled

Step-by-Step Setup

1. Clone or Download the Project

# If using git
git clone <repository-url>
cd technical-mindmap-generator

# Or download and extract the ZIP file

2. Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate it
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

3. Install Dependencies

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:

# 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:

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

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):

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:

# 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:

# 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 - Amazing web framework
• PyVis - Interactive visualizations
• Google Gemini - Powerful AI synthesis
• Tavily - Real-time web search
• Google 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