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

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

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

Using Python directly

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

Or with uvicorn directly:

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.