149 lines
5.0 KiB
Markdown
149 lines
5.0 KiB
Markdown
# 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.
|
||
|
||
|
||
|
||
---
|
||
|
||
## 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 |