README.md

---
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:**
    ```bash
    git clone <URL_repozytorium>
    cd <nazwa_repozytorium>
    ```

2.  **Zainstaluj zależności:**
    ```bash
    pip install -r requirements.txt
    ```

3.  **Skonfiguruj zmienne środowiskowe:**
    - Skopiuj plik `.env.example` do `.env`:
      ```bash
      cp .env.example .env
      ```
    - Otwórz plik `.env` i wklej swój klucz API OpenAI:
      ```
      OPENAI_API_KEY="sk-..."
      ```

4.  **Uruchom aplikację:**
    ```bash
    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:
```bash
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).