HF_SPACES_GUIDE.md

🚀 Quick Start Guide for Hugging Face Spaces

Krok 1: Przygotowanie Repozytorium

Pliki które MUSZĄ być w repo:

✅ app.py
✅ requirements.txt
✅ config.py
✅ agent/ (cały folder)
✅ models/ (cały folder)
✅ database/ lub vector_store_client.py
✅ README.md (z YAML header)
✅ .env.example
✅ lancedb/ (folder z danymi - użyj Git LFS jeśli >10MB)

Pliki które NIE POWINNY być w repo:

❌ .env (zawiera secrets!)
❌ cache/ (lokalny cache)
❌ __pycache__/
❌ *.pyc

Krok 2: Konfiguracja na Hugging Face

A. Utwórz nowy Space

1. Przejdź do https://huggingface.co/new-space
2. Wybierz:
   • SDK: Gradio
   • Hardware: CPU Basic (Free)
   • Visibility: Public lub Private

B. Dodaj Secrets (KRYTYCZNE!)

W ustawieniach Space → Settings → Repository secrets:

Name: OPENAI_API_KEY
Value: sk-proj-... (twój klucz)

Opcjonalnie:

SERVER_HOST=0.0.0.0
SERVER_PORT=7860
LOG_LEVEL=INFO

C. Sprawdź README.md header

---
title: JacekAI - A11y Expert
emoji: ♿
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 4.44.0
python_version: 3.10
app_file: app.py
pinned: true
short_description: Inteligentny asystent do spraw dostępności cyfrowej
---

Krok 3: Upload do Hugging Face

Opcja A: Git CLI

# Sklonuj Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Skopiuj pliki
cp -r /path/to/JacekAI/* .

# Usuń niepotrzebne
rm -rf .env cache/ __pycache__/

# Commit i push
git add .
git commit -m "Initial deploy with asyncio fixes"
git push

Opcja B: Hugging Face Web UI

1. Przejdź do Files → Add file
2. Upload wszystkie pliki (oprócz .env, cache/, pycache/)
3. Dla dużych plików (lancedb/) użyj Git LFS

Krok 4: Monitorowanie Startu

Sprawdź logi w czasie rzeczywistym:

W Space kliknij Logs (prawy górny róg)

✅ Powinny pojawić się:

Initializing A11y Expert Agent...
Connecting to LanceDB at: ./lancedb
✅ Connected to LanceDB
✅ A11y Expert Agent is ready!
Launching Gradio app...
Running on public URL: https://...

❌ Jeśli widzisz błędy:

Error: "OPENAI_API_KEY is required"

Rozwiązanie: Dodaj klucz w Secrets (Krok 2B)

Error: "Table 'a11y_expert' doesn't exist"

Rozwiązanie:

• Sprawdź czy folder lancedb/ jest w repo
• Jeśli nie ma danych, uruchom ETL script lokalnie i upload

Error: "RuntimeError: Event loop is closed"

Rozwiązanie: Upewnij się, że używasz zaktualizowanego app.py

Error: Module not found

Rozwiązanie:

• Sprawdź czy wszystkie foldery mają __init__.py
• Sprawdź requirements.txt

Krok 5: Weryfikacja Działania

Test 1: Sprawdź interfejs

• Space powinien pokazać chat interface
• Przykładowe pytania powinny być widoczne

Test 2: Zadaj testowe pytanie

"Co to jest WCAG?"

Test 3: Sprawdź streaming

• Odpowiedź powinna pojawiać się stopniowo (nie całe zdanie naraz)

Test 4: Test języka

"What is ARIA?"  → Odpowiedź po angielsku
"Co to jest ARIA?" → Odpowiedź po polsku

Krok 6: Troubleshooting

Space się restartuje co kilka minut

Przyczyna: Timeout na Free tier (10 minut bezczynności) Rozwiązanie: Upgrade do GPU przestrzeni lub akceptuj restart

Space nie startuje (Build failed)

1. Sprawdź logi budowania
2. Zweryfikuj requirements.txt (wszystkie biblioteki dostępne na PyPI?)
3. Sprawdź Python version w README.md (3.10 recommended)

Wolne odpowiedzi

1. LanceDB może być duża - rozważ optymalizację
2. OpenAI API może mieć rate limiting
3. Free tier HF ma ograniczenia CPU

Cache nie działa

• diskcache będzie działać, ale będzie resetowany przy restarcie Space
• To normalne na Hugging Face Spaces

Krok 7: Optymalizacja (opcjonalne)

A. Dodaj health check

# W app.py
@demo.additional_routes
def health():
    return {"status": "ok"}

B. Zmniejsz rozmiar bazy danych

# Lokalnie
python compact_database.py
# Potem upload zmniejszonej bazy

C. Użyj GPU (jeśli masz dostęp)

W README.md header:

hardware: a10g-small

✅ Checklist Finalna

Przed ogłoszeniem Space jako "Production Ready":

• Aplikacja startuje bez błędów
• Agent odpowiada na pytania
• Streaming działa
• Język jest wykrywany prawidłowo
• Przykładowe pytania działają
• Brak ostrzeżeń w logach
• OPENAI_API_KEY jest w Secrets (NIE w kodzie!)
• README.md jest czytelny i informacyjny
• Space ma odpowiedni tytuł i opis

🎉 Gotowe!

Twój Space jest teraz live na:

https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

---

📞 Pomoc

• Problemy z asyncio? → Zobacz FIXES_SUMMARY.md
• Problemy z deployment? → Zobacz README_DEPLOYMENT.md
• Ogólne pytania? → Hugging Face Forum

Powodzenia! 🚀