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.

![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