README.md

metadata

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

🤖 A11y Expert - Asystent Dostępności Cyfrowej

Inteligentny agent AI wyspecjalizowany w dostępności cyfrowej (a11y), wykorzystujący RAG (Retrieval-Augmented Generation) z bazą wiedzy WCAG, ARIA i najlepszych praktyk.

✨ Główne Funkcje

• Obsługa wielu języków: Płynna rozmowa po polsku i angielsku z automatycznym wykrywaniem języka.
• Bogata baza wiedzy: Odpowiedzi oparte na standardach WCAG 2.2, ARIA oraz sprawdzonych praktykach dostępności.
• Wiarygodne odpowiedzi (RAG): Każda odpowiedź jest generowana w oparciu o konkretne źródła z bazy wektorowej, z możliwością cytowania.
• Streaming odpowiedzi: Agent generuje odpowiedzi w sposób płynny, token po tokenie.

🔧 Architektura i Technologie

• Interfejs użytkownika: Gradio
• Model językowy: OpenAI GPT-4 (lub nowszy)
• Wektorowa baza danych: LanceDB do przechowywania i przeszukiwania wiedzy.
• Wyszukiwanie semantyczne: Architektura RAG do precyzyjnego odnajdywania informacji.

---

🛠️ Uruchomienie i Rozwój

1. Wymagania wstępne

• Python 3.10+
• Klucz API OpenAI

2. Instalacja lokalna

1. Sklonuj repozytorium:

   git clone <URL_repozytorium>
   cd <nazwa_repozytorium>
   

2. Zainstaluj zależności:

   pip install -r requirements.txt
   

3. Skonfiguruj zmienne środowiskowe:

   • Skopiuj plik .env.example do .env:

     cp .env.example .env
     

   • Otwórz plik .env i wklej swój klucz API OpenAI:

     OPENAI_API_KEY="sk-..."
     

4. Uruchom aplikację:

   python app.py
   

   Aplikacja będzie dostępna pod adresem http://127.0.0.1:7860.

3. Testowanie

Przed wdrożeniem warto uruchomić prosty test startowy, aby upewnić się, że agent inicjalizuje się poprawnie:

python test_startup.py

---

☁️ Wdrożenie na Hugging Face Spaces

Aplikacja jest skonfigurowana do wdrożenia jako Gradio App na Hugging Face Spaces.

1. Konfiguracja w Hugging Face

• W ustawieniach swojego Space, w sekcji Secrets, dodaj sekret o nazwie OPENAI_API_KEY i wklej swój klucz API.

2. Kluczowe aspekty wdrożenia

• Baza danych lancedb: Baza jest tylko do odczytu i musi znajdować się w repozytorium, aby była dostępna dla aplikacji. Zalecane jest użycie git lfs do śledzenia katalogu lancedb/.
• Plik app.py: Logika startowa aplikacji jest dostosowana do wymogów HF Spaces - nie używa bloku if __name__ == "__main__:" do uruchomienia i nie wymaga ręcznego wywoływania demo.launch().
• Zarządzanie zasobami: Mechanizm atexit został celowo wyłączony, aby uniknąć przedwczesnego zamykania aplikacji w środowisku HF Spaces.

📄 Licencja

Ten projekt służy celom edukacyjnym. Baza wiedzy pochodzi z publicznych źródeł (W3C, MDN).