Fix HuggingFace deployment issues

- Remove blocking vector_store.connect() call
- Add lazy database connection with timeout
- Add conditional API key validation for HF Spaces
- Add detailed error logging with traceback
- Add timeout to agent initialization (30s)
- Fix test_startup.py for new architecture
- Add HUGGINGFACE_DEBUG.md documentation
- Improve error handling in VectorStoreClient

HUGGINGFACE_DEBUG.md

@@ -0,0 +1,183 @@
+# 🔍 Debugging Hugging Face Spaces Deployment
+
+## Częste Problemy i Rozwiązania
+
+### Problem 1: Runtime Error - Exit code: 0
+**Objawy:**
+```
+Container logs:
+===== Application Startup at 2025-12-13 12:09:26 =====
+2025-12-13 13:09:40.467 | INFO | __main__:<module>:161 - 🚀 Starting Gradio app...
+[aplikacja się zawiesza]
+```
+
+**Przyczyny:**
+1. **Podwójny start aplikacji** - HF Spaces uruchamia aplikację dwukrotnie podczas budowy kontenera
+2. **Blokada na połączeniu z bazą danych** - Próba zapisu do LanceDB bez uprawnień
+3. **Brak API key** - Walidacja konfiguracji blokuje inicjalizację
+4. **Timeout** - Inicjalizacja trwa zbyt długo (>60s)
+
+**Rozwiązania zastosowane w projekcie:**
+
+#### 1. Leniwą inicjalizację połączenia z bazą
+```python
+# ❌ PRZED - blokujące połączenie
+vector_store = VectorStoreClient(uri="./lancedb")
+vector_store.connect()  # Blokuje na HF Spaces!
+
+# ✅ PO - leniwe połączenie
+vector_store = VectorStoreClient(uri="./lancedb")
+# Połączenie następuje przy pierwszym użyciu
+```
+
+#### 2. Warunkową walidację API key
+```python
+@field_validator("openai_api_key")
+@classmethod
+def validate_api_key(cls, v):
+    v = v or ""
+    v = v.strip()
+    if not v:
+        # Nie rzucaj błędu na HF Spaces
+        if not os.getenv("SPACE_ID"):
+            raise ValueError("OPENAI_API_KEY is required")
+    return v
+```
+
+#### 3. Timeout dla inicjalizacji agenta
+```python
+def initialize_agent_background():
+    """Inicjalizacja z 30-sekundowym timeoutem."""
+    def timeout_handler(signum, frame):
+        raise TimeoutError("Timeout after 30 seconds")
+    
+    if hasattr(signal, 'SIGALRM'):
+        signal.signal(signal.SIGALRM, timeout_handler)
+        signal.alarm(30)
+    
+    agent_instance = create_agent()
+    
+    if hasattr(signal, 'SIGALRM'):
+        signal.alarm(0)
+```
+
+#### 4. Bezpieczne tworzenie katalogów
+```python
+@property
+def db(self):
+    if self._db is None:
+        try:
+            os.makedirs(self.uri, exist_ok=True)
+        except Exception as e:
+            logger.warning(f"Could not create directory: {e}")
+        
+        self._db = lancedb.connect(self.uri)
+    return self._db
+```
+
+### Problem 2: Aplikacja startuje ale nie odpowiada
+
+**Przyczyna:** Agent nie zainicjalizował się w tle
+
+**Rozwiązanie:**
+- Sprawdź logi w HF Spaces - szukaj `✅ A11y Expert Agent is ready!`
+- Jeśli brak, sprawdź czy nie ma błędu inicjalizacji
+- Aplikacja pokazuje status inicjalizacji w interfejsie
+
+### Problem 3: Brak dostępu do bazy danych
+
+**Przyczyna:** Katalog `lancedb/` nie jest w repozytorium lub nie jest śledzony przez Git LFS
+
+**Rozwiązanie:**
+```bash
+# Sprawdź czy lancedb jest w repo
+git lfs ls-files | grep lancedb
+
+# Jeśli nie, dodaj do LFS
+git lfs track "lancedb/**"
+git add .gitattributes lancedb/
+git commit -m "Add LanceDB to LFS"
+git push
+```
+
+### Problem 4: API Key nie jest ustawiony
+
+**Objawy:**
+```
+❌ Failed to initialize agent: OPENAI_API_KEY is required
+```
+
+**Rozwiązanie:**
+1. Idź do ustawień swojego Space
+2. Wybierz zakładkę **Settings** → **Repository secrets**
+3. Dodaj secret `OPENAI_API_KEY` z wartością twojego klucza
+4. Zrestartuj Space
+
+## Testowanie lokalne przed wdrożeniem
+
+```bash
+# Test wszystkich komponentów
+python test_startup.py
+
+# Test aplikacji Gradio
+python app.py
+```
+
+## Sprawdzanie logów na HF Spaces
+
+1. **Podczas budowy:**
+   - Kliknij na swój Space
+   - Przejdź do zakładki **Logs**
+   - Szukaj błędów podczas `Building` i `Running`
+
+2. **Podczas działania:**
+   - Logi są na żywo w zakładce **Logs**
+   - Szukaj komunikatów ERROR lub stacktrace'ów
+
+## Debugowanie z kodem
+
+### Dodaj więcej logowania:
+```python
+import traceback
+try:
+    # twój kod
+except Exception as e:
+    logger.error(f"Error: {e}")
+    logger.error(traceback.format_exc())
+```
+
+### Sprawdź zmienne środowiskowe:
+```python
+import os
+logger.info(f"SPACE_ID: {os.getenv('SPACE_ID')}")
+logger.info(f"HF environment: {os.getenv('SYSTEM')}")
+```
+
+## Checklist przed wdrożeniem
+
+- [ ] `python test_startup.py` przechodzi bez błędów
+- [ ] Baza danych `lancedb/` jest w repo i śledzona przez Git LFS
+- [ ] Secret `OPENAI_API_KEY` jest ustawiony w HF Spaces
+- [ ] `README.md` ma prawidłową konfigurację YAML na górze
+- [ ] `.gitignore` nie blokuje ważnych plików
+- [ ] `requirements.txt` zawiera wszystkie zależności
+
+## Przydatne komendy
+
+```bash
+# Sprawdź rozmiar bazy danych
+du -sh lancedb/
+
+# Sprawdź pliki LFS
+git lfs ls-files
+
+# Wymuś rebuild Space na HF
+# (w ustawieniach Space → Factory reboot)
+```
+
+## Kontakt i Wsparcie
+
+Jeśli nadal masz problemy:
+1. Sprawdź pełne logi w zakładce Logs na HF Spaces
+2. Porównaj z working example na https://huggingface.co/spaces/jacekAI/a11y-expert
+3. Otwórz issue w repozytorium z pełnymi logami

agent/a11y_agent.py

@@ -177,9 +177,8 @@ def create_agent(language: Optional[str] = None) -> A11yExpertAgent:
     
     settings = get_settings()
     
-    # Create and connect clients
+    # Create vector store with lazy connection
     vector_store = VectorStoreClient(uri=settings.lancedb_uri)
-    vector_store.connect()
     
     api_key = settings.openai_api_key
     

app.py

@@ -32,15 +32,41 @@ agent_error = None
 
 # --- Agent Initialization ---
 def initialize_agent_background():
-    """Initialize the agent in background thread."""
+    """Initialize the agent in background thread with timeout."""
     global agent_instance, agent_ready, agent_error
+    
+    def _init_with_timeout():
+        import time
+        import signal
+        
+        def timeout_handler(signum, frame):
+            raise TimeoutError("Agent initialization timed out after 30 seconds")
+        
+        try:
+            # Set 30 second timeout for Unix-like systems
+            if hasattr(signal, 'SIGALRM'):
+                signal.signal(signal.SIGALRM, timeout_handler)
+                signal.alarm(30)
+            
+            logger.info("🔄 Starting agent initialization in background...")
+            time.sleep(2)
+            agent_instance = create_agent()
+            agent_ready = True
+            logger.success("✅ A11y Expert Agent is ready!")
+            
+            # Cancel timeout
+            if hasattr(signal, 'SIGALRM'):
+                signal.alarm(0)
+                
+        except Exception as e:
+            logger.error(f"❌ Failed to initialize agent: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+            raise
+    
     try:
-        logger.info("🔄 Starting agent initialization in background...")
-        agent_instance = create_agent()
-        agent_ready = True
-        logger.success("✅ A11y Expert Agent is ready!")
+        _init_with_timeout()
     except Exception as e:
-        logger.error(f"❌ Failed to initialize agent: {e}")
         agent_error = str(e)
         agent_instance = None
 

config.py

@@ -109,10 +109,12 @@ class Settings(BaseSettings):
         v = v or ""
         v = v.strip()
         if not v:
-            raise ValueError(
-                "OPENAI_API_KEY is required. "
-                "Set it in your .env file or environment variables."
-            )
+            import os
+            if not os.getenv("SPACE_ID"):
+                raise ValueError(
+                    "OPENAI_API_KEY is required. "
+                    "Set it in your .env file or environment variables."
+                )
         return v
     
     @field_validator("log_level")

database/vector_store_client.py

@@ -57,9 +57,20 @@ class VectorStoreClient:
             LanceDB database connection
         """
         if self._db is None:
+            import os
             logger.info(f"Connecting to LanceDB at: {self.uri}")
-            self._db = lancedb.connect(self.uri)
-            logger.info("✅ Connected to LanceDB")
+            
+            try:
+                os.makedirs(self.uri, exist_ok=True)
+            except Exception as e:
+                logger.warning(f"Could not create directory {self.uri}: {e}")
+            
+            try:
+                self._db = lancedb.connect(self.uri)
+                logger.info("✅ Connected to LanceDB")
+            except Exception as e:
+                logger.error(f"Failed to connect to LanceDB: {e}")
+                raise
         return self._db
     
     @property

test_startup.py

@@ -30,6 +30,10 @@ def test_config():
     try:
         logger.info("Testing configuration...")
         from config import get_settings
+        import os
+        
+        os.environ.setdefault("OPENAI_API_KEY", "test-key-for-validation")
+        
         settings = get_settings()
         logger.info(f"LLM Model: {settings.llm_model}")
         logger.info(f"Embedding Model: {settings.embedding_model}")
@@ -45,11 +49,14 @@ def test_vector_store():
     try:
         logger.info("Testing vector store...")
         from config import get_settings
-        from vector_store_client import VectorStoreClient
+        from database.vector_store_client import VectorStoreClient
+        import os
+        
+        os.environ.setdefault("OPENAI_API_KEY", "test-key-for-validation")
         
         settings = get_settings()
         client = VectorStoreClient(uri=settings.lancedb_uri)
-        client.connect()
+        
         count = client.count_documents()
         logger.info(f"Documents in database: {count}")
         client.close()
@@ -57,6 +64,8 @@ def test_vector_store():
         return True
     except Exception as e:
         logger.error(f"❌ Vector store failed: {e}")
+        import traceback
+        logger.error(traceback.format_exc())
         return False
 
 def test_embeddings():
@@ -78,20 +87,22 @@ def test_agent():
     """Test agent creation."""
     try:
         logger.info("Testing agent creation...")
-        import asyncio
         from agent.a11y_agent import create_agent
+        import os
+        
+        os.environ.setdefault("OPENAI_API_KEY", "test-key-for-validation")
         
-        async def _test():
-            agent = await create_agent()
-            logger.info(f"Agent language: {agent.language}")
-            logger.info(f"Agent model: {agent.model}")
-            agent.close()
+        agent = create_agent()
+        logger.info(f"Agent language: {agent.language}")
+        logger.info(f"Agent model: {agent.model}")
+        agent.close()
         
-        asyncio.run(_test())
         logger.success("✅ Agent created successfully")
         return True
     except Exception as e:
         logger.error(f"❌ Agent creation failed: {e}")
+        import traceback
+        logger.error(traceback.format_exc())
         return False
 
 def main():