# Právny AI Asistent – integrácia s API

## Popis

Právny AI Asistent je inteligentný asistent integrovaný s oficiálnymi verejnými API Ministerstva spravodlivosti Slovenskej republiky. Systém poskytuje užívateľom prístup k štruktúrovaným právnym informáciám prostredníctvom prirodzeného jazyka.

**Hlavné funkcie:**

- Interpretácia užívateľských otázok v prirodzenom jazyku
- Automatická extrakcia a validácia parametrov
- Načítavanie dát výlučne cez oficiálne API
- Prezentácia výsledkov v zrozumiteľnom formáte v slovenskom jazyku

---

## Použité knižnice a technológie
 
### Jadro aplikácie
 
| Technológia | Účel |
|---|---|
| **Python 3.11** | Hlavný programovací jazyk |
| **openai-agents** | Tvorba AI agentov a streamovanie odpovedí |
| **openai** | Python klient pre OpenAI / Ollama API |
| **Chainlit** | Framework pre chat rozhranie |
| **Ollama** | Lokálne spúšťanie AI modelov |
| **Docker** | Kontajnerizácia aplikácie |
| **python-dotenv** | Načítavanie premenných prostredia zo súboru `.env` |
 
### API a sieť
 
| Technológia | Účel |
|---|---|
| **httpx** | Asynchrónna HTTP komunikácia s API |
| **pydantic** | Validácia a serializácia vstupných parametrov (schémy) |
| **cachetools** | TTL cache pre API odpovede |
| **tenacity** | Automatické opakovanie požiadaviek pri chybách (retry) |
 
### Testovanie
 
| Technológia | Účel |
|---|---|
| **pytest** | Testovací framework |
| **pytest-asyncio** | Podpora asynchrónnych testov |
| **respx** | Mockovanie HTTP požiadaviek (httpx) |
| **pytest-html** | Generovanie HTML reportov z testov |
| **pytest-cov** | Meranie pokrytia kódu testami |
 
---

## Štruktúra projektu

```
ai-lawyer-agent/
├── .chainlit/                  # Konfigurácia Chainlit                
├── api/                        # API logika
│   ├── __init__.py
│   ├── fetch_api_data.py       # Spracovanie API
│   ├── config.py               # Konfigurácia API
│   ├── schemas.py              # Pydantic schémy
│   └── tools.py                # API nástroje (function tools pre agenta)
├── core/
│   ├── __init__.py
│   ├── config.py               # Konfigurácia agenta (modely, parametre)
│   ├── init_agent.py           # Inicializácia AI agenta
│   ├── stream_response.py      # Streamovanie odpovedí
│   └── system_prompt.py        # Systémový prompt
├── public/                     # Verejné zdroje
├── testing/                    # Testy a testovacie nástroje
│   ├── tests/
│   │   ├── test_api.py         # Integračné testy voči reálnemu API
│   │   ├── test_fetch.py       # Unit testy pre fetch_api_data
│   │   ├── test_llm_compare.py # LLM benchmark testy
│   │   ├── test_project.py     # LLM extrakcia parametrov (DB testy)
│   │   ├── test_schemas.py     # Unit testy Pydantic schém
│   │   ├── test_sys_prompt.py  # Unit testy systémového promptu
│   │   └── test_tools.py       # Unit testy API nástrojov
│   ├── charts/                 # Výstupné reporty a coverage (generované)
│   ├── test_cases.db           # SQLite databáza testovacích prípadov
│   └── run_tests.py            # Spúšťač testov (pytest + HTML report + coverage)
├── app.py                      # Hlavný súbor aplikácie (Chainlit + spracovanie API)
├── chainlit.md                 # Uvítacia obrazovka (default Chainlit)
└── chainlit_en-US.md           # Uvítacia obrazovka (Legal AI Assistant)
```
---

## Testovanie
 
Projekt obsahuje automatizované testy pokrývajúce unit testy schém, API nástrojov, fetchovania dát, systémového promptu a integračné testy voči reálnemu API Ministerstva spravodlivosti. LLM testy overujú správnosť extrakcie parametrov z prirodzeného jazyka oproti 54 referenčným prípadom uloženým v SQLite databáze.
 
![Test Report](testing/images/coverage_and_test_session.png)
 
---

## Inštrukcia pre inštaláciu

### Inštalácia cez Git

#### 1. Naklonovanie repozitára

```bash
git clone git@git.kemt.fei.tuke.sk:od059jr/ai-lawyer-agent.git
```

#### 2. Vytvorenie virtuálneho prostredia

**Windows:**
```bash
python -m venv venv
venv\Scripts\activate
```

**macOS / Linux:**
```bash
python3 -m venv venv
source venv/bin/activate
```

#### 3. Inštalácia závislostí

```bash
pip install -r requirements.txt
```

#### 4. Stiahnutie inštalátora Ollama

Stiahnite si Ollama z oficiálnej stránky: https://ollama.com/download

#### 5. Stiahnutie modelov

```bash
ollama pull qwen3.5:cloud
```

```bash
ollama pull gpt-oss:20b-cloud
```

---

### Inštalácia cez Docker

#### 1. Inštalácia Docker a Docker Desktop

Stiahnite a nainštalujte Docker Desktop: https://www.docker.com/products/docker-desktop

#### 2. Nainštalujte a spustite aplikáciu

Obraz je dostupný na Docker Hub: https://hub.docker.com/r/alexgott0616/ai-lawyer-agent