README.md

---
sdk: docker
pinned: true
---
# 🚀 Crypto Intelligence Hub

AI-Powered Cryptocurrency Data Collection & Analysis Center

---

## ⚡ Quick Start

### One Command to Run Everything:

```powershell
.\run_server.ps1
```

That's it! The script will:
- ✅ Set HF_TOKEN environment variable
- ✅ Run system tests
- ✅ Start the server

Then open: **http://localhost:7860/**

---

## 📋 What's Included

### ✨ Features

- 🤖 **AI Sentiment Analysis** - Using Hugging Face models
- 📊 **Market Data** - Real-time crypto prices from CoinGecko
- 📰 **News Analysis** - Sentiment analysis on crypto news
- 💹 **Trading Pairs** - 300+ pairs with searchable dropdown
- 📈 **Charts & Visualizations** - Interactive data charts
- 🔍 **Provider Management** - Track API providers status

### 🎨 Pages

- **Main Dashboard** (`/`) - Overview and statistics
- **AI Tools** (`/ai-tools`) - Standalone sentiment & summarization tools
- **API Docs** (`/docs`) - FastAPI auto-generated documentation

---

## 🛠️ Setup

### Prerequisites

- Python 3.8+
- Internet connection (for HF models & APIs)

### Installation

1. **Clone/Download** this repository

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

3. **Run the server:**
   ```powershell
   .\run_server.ps1
   ```

---

## 🔑 Configuration

### Hugging Face Token

Your HF token is already configured in `run_server.ps1`:
```
HF_TOKEN: hf_YOUR_TOKEN_HERE
HF_MODE: public
```

For Hugging Face Space deployment:
1. Go to: Settings → Repository secrets
2. Add: `HF_TOKEN` = `hf_YOUR_TOKEN_HERE`
3. Add: `HF_MODE` = `public`
4. Restart Space

---

## 📁 Project Structure

```
.
├── api_server_extended.py    # Main FastAPI server
├── ai_models.py               # HF models & sentiment analysis
├── config.py                  # Configuration
├── index.html                 # Main dashboard UI
├── ai_tools.html             # Standalone AI tools page
├── static/
│   ├── css/
│   │   └── main.css          # Styles
│   └── js/
│       ├── app.js            # Main JavaScript
│       └── trading-pairs-loader.js  # Trading pairs loader
├── trading_pairs.txt         # 300+ trading pairs
├── run_server.ps1            # Start script (Windows)
├── test_fixes.py             # System tests
└── README.md                 # This file
```

---

## 🧪 Testing

### Run all tests:
```bash
python test_fixes.py
```

### Expected output:
```
============================================================
[TEST] Testing All Fixes
============================================================
[*] Testing file existence...
  [OK] Found: index.html
  ... (all files)

[*] Testing trading pairs file...
  [OK] Found 300 trading pairs

[*] Testing AI models configuration...
  [OK] All essential models linked

============================================================
Overall: 6/6 tests passed (100.0%)
============================================================
[SUCCESS] All tests passed! System is ready to use!
```

---

## 📊 Current Test Status

Your latest test results:
```
✅ File Existence - PASS
✅ Trading Pairs - PASS  
✅ Index.html Links - PASS
✅ AI Models Config - PASS
⚠️  Environment Variables - FAIL (Fixed by run_server.ps1)
✅ App.js Functions - PASS

Score: 5/6 (83.3%) → Will be 6/6 after running run_server.ps1
```

---

## 🎯 Features Overview

### 1. **Sentiment Analysis**
- 5 modes: Auto, Crypto, Financial, Social, News
- HuggingFace models with fallback system
- Real-time analysis with confidence scores
- Score breakdown with progress bars

### 2. **Trading Pairs**
- 300+ pairs loaded from `trading_pairs.txt`
- Searchable dropdown/combobox
- Auto-complete functionality
- Used in Per-Asset Sentiment Analysis

### 3. **AI Models**
- **Crypto:** CryptoBERT, twitter-roberta
- **Financial:** FinBERT, distilroberta-financial
- **Social:** twitter-roberta-sentiment
- **Fallback:** Lexical keyword-based analysis

### 4. **Market Data**
- Real-time prices from CoinGecko
- Fear & Greed Index
- Trending coins
- Historical data storage

### 5. **News & Analysis**
- News sentiment analysis
- Database storage (SQLite)
- Related symbols tracking
- Analyzed timestamp

---

## 🔧 Troubleshooting

### Models not loading?

**Check token:**
```powershell
$env:HF_TOKEN
$env:HF_MODE
```

**Solution:** Use `run_server.ps1` which sets them automatically

### Charts not displaying?

**Check:** Browser console (F12) for errors  
**Solution:** Make sure internet is connected (CDN for Chart.js)

### Trading pairs not showing?

**Check:** Console should show "Loaded 300 trading pairs"  
**Solution:** File `trading_pairs.txt` must exist in root

### No news articles?

**Reason:** Database is empty  
**Solution:** Use "News & Financial Sentiment Analysis" to add news

---

## 📚 Documentation

- **START_HERE.md** - Quick start guide (فارسی)
- **QUICK_START_FA.md** - Fast start guide (فارسی)
- **FINAL_FIXES_SUMMARY.md** - Complete changes summary
- **SET_HF_TOKEN.md** - HF token setup guide
- **HF_SETUP_GUIDE.md** - Complete HF setup

---

## 🌐 API Endpoints

### Core Endpoints
- `GET /` - Main dashboard
- `GET /ai-tools` - AI tools page
- `GET /docs` - API documentation
- `GET /health` - Health check

### Market Data
- `GET /api/market` - Current prices
- `GET /api/trending` - Trending coins
- `GET /api/sentiment` - Fear & Greed Index

### AI/ML
- `POST /api/sentiment/analyze` - Sentiment analysis
- `POST /api/news/analyze` - News sentiment
- `POST /api/ai/summarize` - Text summarization
- `GET /api/models/status` - Models status
- `GET /api/models/list` - Available models

### Resources
- `GET /api/providers` - API providers
- `GET /api/resources` - Resources summary
- `GET /api/news` - News articles

---

## 🎨 UI Features

- 🌓 Dark theme optimized
- 📱 Responsive design
- ✨ Smooth animations
- 🎯 Interactive charts
- 🔍 Search & filters
- 📊 Real-time updates

---

## 🚀 Deployment

### Hugging Face Space

1. Push code to HF Space
2. Add secrets:
   - `HF_TOKEN` = `hf_YOUR_TOKEN_HERE`
   - `HF_MODE` = `public`
3. Restart Space
4. Done!

### Local

```powershell
.\run_server.ps1
```

---

## 📈 Performance

- **Models:** 4+ loaded (with fallback)
- **API Sources:** 10+ providers
- **Trading Pairs:** 300+
- **Response Time:** < 200ms (cached)
- **First Load:** 30-60s (model loading)

---

## 🔐 Security

- ✅ Token stored in environment variables
- ✅ CORS configured
- ✅ Rate limiting (planned)
- ⚠️ **Never commit tokens to git**
- ⚠️ **Use secrets for production**

---

## 📝 License

This project is for educational and research purposes.

---

## 🙏 Credits

- **HuggingFace** - AI Models
- **CoinGecko** - Market Data
- **Alternative.me** - Fear & Greed Index
- **FastAPI** - Backend Framework
- **Chart.js** - Visualizations

---

## 📞 Support

**Quick Issues?**
1. Run: `python test_fixes.py`
2. Check: Browser console (F12)
3. Review: `FINAL_FIXES_SUMMARY.md`

**Ready to start?**
```powershell
.\run_server.ps1
```

---

**Version:** 5.2.0  
**Status:** ✅ Ready for production  
**Last Updated:** November 19, 2025

---

Made with ❤️ for the Crypto Community 🚀