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
```yaml
---
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
```bash
# 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
```python
# W app.py
@demo.additional_routes
def health():
    return {"status": "ok"}
```

### B. Zmniejsz rozmiar bazy danych
```bash
# Lokalnie
python compact_database.py
# Potem upload zmniejszonej bazy
```

### C. Użyj GPU (jeśli masz dostęp)
W README.md header:
```yaml
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!** 🚀