HUGGINGFACE_SETUP.md

Hugging Face Space Setup and Rate Limit Handling

Issue Identified

You're experiencing a rate limit error (429) with the free model, and your Hugging Face Space isn't properly recognizing the OPENROUTER_API_KEY environment variable.

Hugging Face Space Configuration

1. Setting the API Key in Secrets

In your Hugging Face Space:

1. Go to your Space dashboard
2. Click on "Settings" tab
3. Scroll down to "Repository secrets"
4. Add a new secret:
   • Key: OPENROUTER_API_KEY
   • Value: Your actual OpenRouter API key

2. Verify Environment Variable Access

The application should automatically read the environment variable. If it's still not working, you can also try:

1. In your Space's README.md, add this configuration: ```yaml

   title: Document Translator emoji: 📄 colorFrom: blue colorTo: purple sdk: docker app_port: 7860 pinned: false license: mit

2. Make sure your Dockerfile properly passes environment variables:

   # Your existing Dockerfile content
   # The ENV directive should handle this automatically
   

Rate Limit Solutions

1. Use Your Own API Key

The error message indicates that you need to add your own key to accumulate rate limits. The free models have shared rate limits, but when you use your own key, you get your own quota.

2. Model Selection Strategy

The application now provides two models:

• google/gemini-2.0-flash-exp:free - Fast but rate-limited
• tngtech/deepseek-r1t2-chimera:free - Alternative free model

If one is rate-limited, try switching to the other.

3. Retry Logic

The application now includes better error handling for rate limits:

• Clear error messages when rate limits are hit
• Suggestion to try again later or switch models
• Proper logging of rate limit issues

Testing Your Setup

1. Local Testing (Before Deploying)

# Set your API key
export OPENROUTER_API_KEY=your_actual_key_here

# Run the test script
python test_api.py

# Start the application
python app/main.py

2. Hugging Face Space Testing

After deploying:

1. Check the Space logs for any environment variable issues
2. Try translating a small document first
3. If you get rate limit errors, wait a few minutes and try again

Troubleshooting

Common Issues and Solutions

1. API Key Not Recognized:

   • Double-check the secret name is exactly OPENROUTER_API_KEY
   • Restart the Space after adding the secret
   • Check Space logs for environment variable loading

2. Rate Limit Errors:

   • Wait 5-10 minutes before retrying
   • Try the alternative model
   • Consider upgrading to a paid OpenRouter plan for higher limits

3. Translation Fails:

   • Check the translation.log file in your Space
   • Ensure the document contains readable text
   • Try a smaller document first

Best Practices

1. For Free Users

• Use the application during off-peak hours
• Process one document at a time
• Wait between translations if you hit rate limits

2. For Heavy Usage

• Get your own OpenRouter API key
• Consider upgrading to a paid plan for higher rate limits
• Monitor your usage in the OpenRouter dashboard

3. Model Selection

• Use google/gemini-2.0-flash-exp:free for fast translations
• Use tngtech/deepseek-r1t2-chimera:free as a backup option
• Switch models if one becomes rate-limited

Error Messages Explained

Rate Limit Error (429)

google/gemini-2.0-flash-exp:free is temporarily rate-limited upstream

Solution: Wait a few minutes and try again, or switch to the other model.

API Key Error

OpenRouter API key not configured

Solution: Check that OPENROUTER_API_KEY is set in your Space secrets.

Support

If you continue to have issues:

1. Check the Space logs for detailed error messages
2. Verify your API key works with the test_api.py script locally
3. Contact OpenRouter support if rate limits seem incorrect

The system is designed to provide clear error messages and handle these common issues gracefully.