cursor-instructions/AI_DEVELOPER_PROMPT.md

# 🤖 Prompt for AI Developer

Copy and paste this entire prompt to your AI coding assistant:

---

## YOUR TASK

You are tasked with **UPDATING an existing HuggingFace Space** to implement a comprehensive cryptocurrency data API with 30+ endpoints.

**⚠️ CRITICAL: THIS IS AN UPDATE REQUEST, NOT A NEW PROJECT!**

You are NOT creating a new HuggingFace Space. You are UPDATING and ENHANCING an existing one.

---

## MANDATORY READING ORDER

You MUST read the following files in this EXACT order before starting implementation:

### Step 1: Read `HF_DEPLOYMENT_SUMMARY.md` (5 minutes)
- Get quick overview of the project
- Understand what we're building and why

### Step 2: Read `SEND_TO_HF_TEAM.md` (10 minutes)
- Understand the official scope and priorities
- Review success criteria

### Step 3: Read `DATA_ARCHITECTURE_ANALYSIS_REPORT.md` (30 minutes)
- Understand current architecture
- Identify problems we're solving
- Review proposed solution

### Step 4: Read `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` (2-3 hours) ⭐ **THIS IS YOUR MAIN REFERENCE**
- Complete specifications for ALL 30+ API endpoints
- Request/Response formats with examples
- Complete Python/FastAPI implementation code
- Data source integration (CoinGecko, Binance, NewsAPI, etc.)
- Caching strategy with Redis
- Rate limiting implementation
- AI/ML model integration (BERT, LSTM)
- WebSocket real-time implementation
- Dockerfile and requirements.txt
- Environment variables
- Testing procedures
- Deployment steps

**This file contains EVERYTHING you need. Read it thoroughly.**

### Step 5 (Optional): Read `ENGINEERING_GUIDE.md` (1 hour)
- Coding standards and best practices for this project

---

## WHAT TO IMPLEMENT

You need to implement a FastAPI backend with:

### REST API Endpoints (25+ endpoints):

**Market Data:**
- GET `/api/market` - List of cryptocurrencies
- GET `/api/price/{symbol}` - Current price
- GET `/api/ohlcv` - Chart data (OHLCV/candlestick)
- GET `/api/ticker/{symbol}` - Real-time ticker

**News & Sentiment:**
- GET `/api/news/latest` - Latest crypto news
- GET `/api/sentiment/global` - Global market sentiment (Fear & Greed)
- GET `/api/sentiment/symbol/{symbol}` - Symbol-specific sentiment

**Trading:**
- GET `/api/exchange-info` - Trading pairs and exchange info
- GET `/api/orderbook/{symbol}` - Order book depth
- GET `/api/trades/{symbol}` - Recent trades

**AI & Predictions:**
- GET `/api/ai/signals` - AI trading signals
- POST `/api/ai/predict` - Price predictions
- GET `/api/ai/analysis/{symbol}` - Comprehensive AI analysis

**Blockchain:**
- GET `/api/blockchain/transactions/{address}` - Transaction history
- GET `/api/blockchain/whale-alerts` - Large transaction alerts

**Statistics:**
- GET `/api/stats` - Global market statistics
- GET `/api/stats/dominance` - Market dominance breakdown
- GET `/api/history/price/{symbol}` - Historical price data

### WebSocket Endpoints (2 channels):
- WS `/ws/ticker` - Real-time price updates
- WS `/ws/trades` - Real-time trade stream

### Special Endpoints:
- GET `/health` - Health check
- GET `/docs` - API documentation (auto-generated by FastAPI)

---

## TECHNICAL REQUIREMENTS

### Tech Stack:
```
- Python 3.9+
- FastAPI framework
- Redis for caching
- aiohttp for async HTTP requests
- PyTorch + Transformers for AI models
- ccxt for exchange integration
- WebSockets for real-time updates
```

### Data Sources to Integrate:
1. **CoinGecko API** - Market data (primary)
2. **Binance API** - OHLCV and trades (primary)
3. **NewsAPI / CryptoPanic** - News feeds
4. **Alternative.me** - Fear & Greed Index
5. **AI Models** - ElKulako/cryptobert for sentiment, custom LSTM for predictions

### Key Features:
- ✅ **Automatic Fallback** - If CoinGecko fails, try Binance, then CMC
- ✅ **Smart Caching** - Different TTL for different data (5s-10min)
- ✅ **Rate Limiting** - Respect external API limits
- ✅ **Error Handling** - Consistent JSON error format
- ✅ **CORS Enabled** - Allow all origins
- ✅ **Async/Await** - All endpoints must be async

---

## IMPLEMENTATION STEPS

### Phase 1: Setup
1. Access the existing HuggingFace Space repository
2. Set up Python 3.9+ environment
3. Install Redis (local or cloud)
4. Create virtual environment
5. Install dependencies from requirements.txt (provided in specs)

### Phase 2: Core Framework
1. Create FastAPI application
2. Configure CORS middleware
3. Set up Redis connection
4. Create health check endpoint
5. Test basic server startup

### Phase 3-9: Implement All Endpoints
Follow the detailed specifications in `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` for each endpoint.

**Priority order:**
1. **MUST HAVE (implement first):**
   - GET /api/market
   - GET /api/ohlcv
   - GET /api/news/latest
   - GET /api/sentiment/global
   - GET /api/ai/signals

2. **SHOULD HAVE (implement second):**
   - All other REST endpoints
   - WebSocket /ws/ticker

3. **NICE TO HAVE (if time permits):**
   - Advanced AI features
   - Blockchain endpoints

### Phase 10: WebSocket
1. Implement connection manager
2. Create ticker channel
3. Create trades channel
4. Test real-time updates

### Phase 11: Performance
1. Implement caching layer (Redis)
2. Add rate limiting
3. Optimize queries

### Phase 12: Testing
1. Test all endpoints individually
2. Test error scenarios
3. Test fallback mechanisms
4. Load test with concurrent users

### Phase 13: Deployment
1. Create Dockerfile (example provided in specs)
2. Configure environment variables in HF Space
3. Push to HuggingFace Space
4. Verify all endpoints in production
5. Monitor for 24 hours

---

## CRITICAL REMINDERS

### ⚠️ THIS IS AN UPDATE!
```
✅ You are UPDATING an existing HuggingFace Space
✅ DO NOT create a new space
✅ ADD new endpoints to existing deployment
✅ ENHANCE existing functionality
✅ Keep existing features working
```

### ⚠️ QUALITY STANDARDS
```
✅ All endpoints MUST return valid JSON
✅ All errors MUST follow standard format (see specs)
✅ All endpoints MUST have caching
✅ All responses MUST include timestamp
✅ All code MUST use async/await
✅ All data sources MUST have fallback mechanisms
```

### ⚠️ PERFORMANCE REQUIREMENTS
```
Response Times:
- Price endpoints: < 100ms
- Market data: < 500ms
- News/Sentiment: < 1s
- AI predictions: < 2s

Caching TTL:
- Prices: 5 seconds
- OHLCV: 60 seconds
- News: 5 minutes
- AI signals: 2 minutes
```

### ⚠️ ERROR FORMAT (use this for ALL errors)
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  },
  "timestamp": 1733432100000
}
```

---

## SUCCESS CRITERIA

You are DONE when:

✅ All 30+ endpoints return valid responses  
✅ WebSocket connections are stable  
✅ Caching improves response times  
✅ Fallback mechanisms work when primary source fails  
✅ AI models generate predictions  
✅ `/docs` endpoint shows interactive API documentation  
✅ `/health` endpoint returns service status  
✅ All endpoints tested in production  
✅ No errors in logs for 24 hours  
✅ Response times meet requirements above  

---

## WHERE TO FIND INFORMATION

While implementing, refer to these files:

| Need | Check File | Section |
|------|-----------|---------|
| Endpoint specs | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "DETAILED API SPECIFICATIONS" |
| Request/Response formats | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | Each endpoint section |
| Backend code | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "TECHNICAL REQUIREMENTS" |
| Data sources | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "Data Sources Integration" |
| Caching code | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "Caching Strategy" |
| AI models | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "AI/ML Models Integration" |
| WebSocket code | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "WebSocket Implementation" |
| Dockerfile | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "DEPLOYMENT CONFIGURATION" |
| Testing | `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` | "VERIFICATION CHECKLIST" |

---

## COMMON MISTAKES TO AVOID

### ❌ DON'T DO THESE:
- ❌ Create a new HuggingFace Space (it exists! UPDATE it!)
- ❌ Remove or break existing functionality
- ❌ Hard-code API keys in code (use environment variables)
- ❌ Skip error handling
- ❌ Ignore caching requirements
- ❌ Use synchronous code (must be async)
- ❌ Return inconsistent response formats
- ❌ Deploy without testing locally first

### ✅ DO THESE:
- ✅ Update the existing Space
- ✅ Use environment variables for all secrets
- ✅ Implement proper error handling everywhere
- ✅ Add caching to every endpoint
- ✅ Test locally before deploying
- ✅ Use async/await throughout
- ✅ Follow the standard response format
- ✅ Implement fallback mechanisms
- ✅ Log all errors properly

---

## YOUR STARTING POINT

### First Actions:
1. Read `HF_DEPLOYMENT_SUMMARY.md`
2. Read `SEND_TO_HF_TEAM.md`
3. Read `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` carefully (your main reference)

### Then:
4. Set up your local development environment
5. Access the existing HuggingFace Space repository
6. Start implementing Phase 1 (Setup)
7. Follow the implementation steps above
8. Test thoroughly
9. Deploy

---

## FINAL CHECKLIST

Before you start coding, confirm:

- [ ] I understand this is an UPDATE, not a new project
- [ ] I have read all required documentation
- [ ] I understand the priority order (MUST/SHOULD/NICE TO HAVE)
- [ ] I have access to the existing HuggingFace Space
- [ ] I have Python 3.9+ installed
- [ ] I have Redis installed or know how to use cloud Redis
- [ ] I understand the success criteria
- [ ] I know where to find specifications (main file: `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md`)

---

## ESTIMATED TIME

- **Reading documentation:** 3-4 hours
- **Setup:** 1-2 hours
- **Implementation:** 3-5 days (full-time work)
- **Testing:** 1-2 days
- **Deployment:** 1 day

**Total: 5-8 days for complete implementation**

---

## 🚀 BEGIN NOW

**Start by reading:** `HF_DEPLOYMENT_SUMMARY.md`

**Your main reference:** `HUGGINGFACE_SPACE_DEPLOYMENT_REQUEST.md` (contains ALL specifications and code)

**Remember:** This is an UPDATE REQUEST. You are enhancing an existing HuggingFace Space, not creating a new one.

**Good luck with the implementation!** 🎯

---

**Version:** 1.0  
**Date:** December 5, 2025  
**Project:** Dreammaker Crypto Trading Platform  
**Type:** HuggingFace Space Update Request  
**Priority:** HIGH