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

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

2. Vytvorenie virtuálneho prostredia

Windows:

python -m venv venv
venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

3. Inštalácia závislostí

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

ollama pull qwen3.5:cloud

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