README.txt

# 🦋 Butterfly AI - Intelligent News Analysis Application

## Overview
Butterfly AI is a sophisticated news analysis application that leverages artificial intelligence to help users understand the cascading effects of news events. By analyzing news from multiple sources, the platform predicts potential "butterfly effects" - how small events today might create significant changes tomorrow.

## 🌟 Key Features

### News Intelligence
- **Multi-Source Aggregation**: Collects news from major sources (NewsAPI, Guardian, CNN, BBC, Baidu, Toutiao)
- **Smart Categorization**: Automatically organizes news into relevant categories
- **Multi-Language Support**: Handles both English and Chinese content
- **Real-Time Updates**: Continuous news monitoring and analysis

### Advanced Analysis
- **🦋 Butterfly Effect Prediction**: AI-powered analysis of potential chain reactions
- **🌍 Geographic Impact**: Visualization of how events ripple across regions
- **📊 Context Analysis**: Historical timelines and related events
- **👥 Stakeholder Analysis**: Key entities and their relationships
- **💡 Action Items**: Practical recommendations based on news events
- **📈 Company Impact**: Assessment of business implications

### Personalization
- **Interest Tracking**: Customizable interest categories
- **Company Watchlists**: Monitor specific organizations
- **Smart Filters**: Content filtering based on user preferences
- **Custom Analysis**: Upload and analyze your own documents

### 📄 Document Analysis System
- **Multi-Format Support**: 
  - PDF documents
  - Microsoft Office files (DOCX, XLSX, PPTX)
  - Text files
  - More formats coming soon

- **Analysis Capabilities**:
  ```dart
  final List<String> _analysisSteps = [
    'Analyzing the cause...',
    'Analyzing the butterfly effect...',
    'Identifying the key stake holders...',
    'Figuring out the relevant action items for you...',
  ];
  ```

- **Dual Analysis Interface**:
  - Direct text input panel for quick analysis
  - File explorer for document selection
  - Cross-platform file system navigation
  - Analysis history tracking

- **Platform-Specific Optimization**:
  ```dart
  // Handles different platforms appropriately
  if (Platform.isWindows) {
    // Windows-specific directory handling
  } else if (Platform.isMacOS) {
    // macOS-specific directory handling
  } else if (Platform.isAndroid) {
    // Android-specific directory handling
  }
  ```

- **Real-Time Analysis Feedback**:
  - Progressive analysis status updates
  - Rotating status messages
  - Error handling and user notifications
  - Analysis result visualization

## 🛠 Technical Architecture

### Backend (Python/Flask)
- News crawling and aggregation
- Content processing and categorization 
- AI-powered analysis using LLM services
- Image generation for news stories
- REST API endpoints for client interaction

### Frontend (Flutter)
- Cross-platform support (Android, iOS, desktop)
- Rich interactive UI for news browsing
- Detailed news visualization with cards for different analysis aspects
- File analysis capabilities for various formats (PDF, DOC, TXT, etc.)
- Offline storage and synchronization

## 📋 Requirements

### Backend Requirements
- Python 3.8+
- OpenAI API key
- NewsAPI key
- Required Python packages (see requirements.txt)

### Frontend Requirements
- Flutter 3.0+
- Dart 2.17+

## 🚀 Installation & Setup

### Backend Setup
1. Clone the repository
```bash
git clone https://github.com/yourusername/butterfly-ai.git
cd butterfly-ai/butterfly_server
```

2. Install dependencies
```bash
pip install -r requirements.txt
```

3. Configure environment variables
```bash
cp .env.example .env
# Edit .env with your API keys and configuration
```

4. Run the server
```bash
python -m flask run
```

### Frontend Setup
1. Navigate to the Flutter project
```bash
cd butterfly_apps
```

2. Get dependencies
```bash
flutter pub get
```

3. Run the application
```bash
flutter run
```

## 💡 Key Components

### Smart Content Processing
- Automatic categorization of news
- Full-text content extraction
- Image handling and caching
- Multi-format document support

### Analysis Visualization
- Timeline views for historical context
- Geographic impact maps
- Cause-and-effect chains
- Action item recommendations
- Company impact assessments

### User Experience
- Clean, intuitive interface
- Real-time news updates
- Offline access to downloaded content
- Cross-platform consistency
- Personalized content delivery

## 👥 Target Users
- Business professionals needing strategic insights
- Researchers analyzing news patterns
- Investors tracking market impacts
- General users interested in understanding complex news relationships
- Anyone wanting to understand the broader implications of current events

## 📱 Usage

1. **Initial Setup**
   - Launch the application
   - Configure your interests and preferences
   - Add companies to your watchlist (optional)

2. **News Browsing**
   - Browse categorized news feed
   - Click on articles for detailed analysis
   - View butterfly effect predictions

3. **Custom Analysis**
   - Upload documents for analysis
   - View personalized insights
   - Track specific topics or companies

4. **Document Analysis**
   - Upload documents through the file explorer
   - Input text directly for quick analysis
   - View analysis history
   - Export analysis results
   - Track analysis progress in real-time

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- News data providers
- Open source libraries and tools
- AI/LLM service providers
- Community contributors

## 📞 Support

For support, please:
- Open an issue in the repository
- Contact us at [support@butterflyai.com](mailto:support@butterflyai.com)
- Join our [Discord community](https://discord.gg/butterflyai)

---

Made with ❤️ by the Butterfly AI Team