hf-data-engine/README_HUGGINGFACE.md

# Crypto Monitor Extended API - Hugging Face Spaces Deployment

This repository is configured to run as a **Docker Space** on Hugging Face.

## 🚀 Quick Deploy to Hugging Face Spaces

1. **Create a new Space** on Hugging Face
2. **Select Docker as the SDK**
3. **Clone this repository** or push it to your Space
4. The Space will automatically build and deploy

## 📋 Configuration

### Space Settings

- **SDK**: Docker
- **Hardware**: CPU Basic (or higher for better performance)
- **Visibility**: Public or Private (your choice)

### Environment Variables (Optional)

You can set these in your Space settings under "Repository secrets":

- `PORT` - Port number (default: 7860 for HF Spaces)
- `ENABLE_AUTO_DISCOVERY` - Enable auto-discovery service (default: false)

## 🔧 Technical Details

### Main Application

The FastAPI application is defined in `api_server_extended.py` and exposes:

- **Main API**: `http://your-space.hf.space/`
- **API Docs**: `http://your-space.hf.space/docs`
- **Health Check**: `http://your-space.hf.space/health`
- **WebSocket**: `ws://your-space.hf.space/ws`

### Features

✅ **Provider Management** - Manage 200+ crypto data providers
✅ **Pool Management** - Create and manage provider pools with rotation strategies
✅ **Real-time WebSocket** - Live updates and monitoring
✅ **Health Monitoring** - Automatic health checks for all providers
✅ **Auto-Discovery** - Discover new crypto data sources automatically
✅ **Diagnostics** - Built-in diagnostics and auto-repair
✅ **Logging** - Comprehensive logging system
✅ **Resource Management** - Import/export provider configurations

### API Endpoints

#### Core Endpoints
- `GET /` - Main dashboard
- `GET /health` - Health check
- `GET /api/status` - System status
- `GET /api/stats` - Statistics

#### Provider Management
- `GET /api/providers` - List all providers
- `GET /api/providers/{id}` - Get provider details
- `POST /api/providers/{id}/health-check` - Check provider health
- `GET /api/providers/category/{category}` - Get providers by category

#### Pool Management
- `GET /api/pools` - List all pools
- `POST /api/pools` - Create new pool
- `POST /api/pools/{id}/members` - Add member to pool
- `POST /api/pools/{id}/rotate` - Rotate pool

#### WebSocket
- `WS /ws` - WebSocket connection for real-time updates

See `/docs` for complete API documentation.

## 🏗️ Local Development

### Using Docker

```bash
# Build the image
docker build -t crypto-monitor .

# Run the container
docker run -p 8000:8000 crypto-monitor
```

### Using Python directly

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

# Run the server
python main.py
```

Or with uvicorn directly:

```bash
uvicorn api_server_extended:app --host 0.0.0.0 --port 8000 --reload
```

## 📊 Monitoring

Once deployed, you can monitor your Space:

1. Check the **Logs** tab in your Space
2. Visit `/health` endpoint for health status
3. Visit `/api/status` for detailed system status
4. Use `/docs` for interactive API documentation

## 🔍 Troubleshooting

### Space not starting?

1. Check the **Logs** tab for error messages
2. Verify all required files are present
3. Ensure `api_server_extended.py` defines `app = FastAPI(...)`
4. Check that all dependencies in `requirements.txt` are valid

### Health check failing?

The health check runs after 40 seconds of startup. If it fails:

1. Increase `start-period` in Dockerfile HEALTHCHECK
2. Check if the app is listening on the correct PORT
3. Verify `/health` endpoint returns 200 OK

### Performance issues?

1. Upgrade to better hardware (CPU or GPU)
2. Disable auto-discovery: Set `ENABLE_AUTO_DISCOVERY=false`
3. Reduce the number of providers being monitored

## 📝 Notes

- The application uses **no API keys** by default - all data sources are free
- SQLite database is used for persistence (stored in `/app/data/`)
- Logs are stored in `/app/logs/`
- The app runs in **degraded mode** if some providers are unavailable
- WebSocket connections are supported for real-time updates

## 🤝 Support

For issues or questions:
- Check the `/api/diagnostics/run` endpoint for automatic diagnostics
- Review logs in the Hugging Face Space logs tab
- Check the `/health` endpoint for system status

## 📄 License

See LICENSE file for details.