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 (obcan.justice.sk). Systém umožňuje používateľom pristupovať k štruktúrovaným právnym informáciám prostredníctvom prirodzeného jazyka v reálnom čase.

Hlavné funkcie:

• Vyhľadávanie súdov, sudcov, rozhodnutí, zmlúv a konaní
• Automatická extrakcia a validácia parametrov zo vstupných otázok
• Načítavanie dát výlučne cez oficiálne API Ministerstva spravodlivosti SR
• Prezentácia výsledkov v zrozumiteľnom formáte v slovenskom jazyku
• Streamovanie odpovedí v reálnom čase token po tokene

---

Použité knižnice a technológie

Jadro aplikácie

Technológia	Verzia	Účel
Python	3.11	Hlavný programovací jazyk
openai-agents	0.6.3	Tvorba AI agentov a streamovanie odpovedí
FastAPI	≥ 0.136.0	Backend REST API a SSE streaming
Chainlit	2.11.0	Framework pre chat rozhranie (frontend)
FastMCP	≥ 2.7.0	MCP server pre nástroje Justice API
LiteLLM	–	Proxy pre viacero LLM modelov
Docker	–	Kontajnerizácia aplikácie

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)
aiohttp	HTTP komunikácia na strane frontendu (Chainlit)

Testovanie

Technológia	Účel
pytest	Testovací framework
pytest-asyncio	Podpora asynchrónnych testov
pytest-html	Generovanie HTML reportov z testov

---

Štruktúra projektu

legal-ai-assistant/
├── backend/                        # Backendová logika
│   ├── agent/                      # AI agent
│   │   ├── agent.py                # Inicializácia agenta
│   │   ├── hooks.py                # Sledovanie behu agenta
│   │   ├── response.py             # Streamovanie SSE odpovedí
│   │   └── sys_prompt.py           # Systémový prompt
│   ├── routers/                    # FastAPI routery
│   │   ├── health.py               # Health check endpoint
│   │   ├── info.py                 # Informácie o aplikácii
│   │   └── run_agent.py            # Hlavný endpoint /api/run
│   ├── tools/
│   │   ├── api/
│   │   │   ├── http_request_handler.py  # HTTP komunikácia s API
│   │   │   └── schemas.py               # Pydantic schémy pre každý endpoint
│   │   └── mcp/
│   │       ├── factory.py          # Továrňa na MCP nástroje
│   │       └── server.py           # FastMCP server (všetky nástroje)
│   ├── logger.py                   # Logovanie
│   └── main.py                     # FastAPI aplikácia
├── frontend/                       # Frontendová logika
│   ├── services/
│   │   ├── agent_client.py         # HTTP komunikácia s backendom
│   │   └── tool_steps.py           # Zobrazovanie krokov nástrojov v UI
│   ├── public/                     # Verejné zdroje (ikony, CSS, logo)
│   ├── .chainlit/
│   │   ├── config.toml             # Konfigurácia Chainlit
│   │   └── translations/           # Preklady UI
│   └── app.py                      # Hlavná Chainlit aplikácia
├── tests/                          # Testy
├── configs.py                      # Globálna konfigurácia (modely, URL, konštanty)
├── litellm-config.yaml             # Konfigurácia LiteLLM proxy
├── compose.yaml                    # Docker Compose
└── pyproject.toml                  # Závislosti projektu

---

Opis konfigurácie kontajnerov

Aplikácia beží ako sada Docker kontajnerov definovaných v compose.yaml.

Kontajner	Port	Popis
frontend	8000	Chainlit chat rozhranie
backend	8001	FastAPI server – spracovanie požiadaviek a agent
mcp	8002	FastMCP server – nástroje pre Justice API
litellm	4000	LiteLLM proxy – routing LLM modelov
db	5432	PostgreSQL – ukladanie histórie konverzácií

Každý kontajner má nastavený healthcheck. Backend čaká na LiteLLM a MCP, frontend čaká na backend a databázu.

Premenné prostredia (API kľúče, databázové pripojenie atď.) sa načítavajú zo súboru .env.

---

Testovanie

Projekt obsahuje tri vrstvy testov:

Unit testy (tests/unit/) — overujú Pydantic schémy (validácia, normalizácia ID), HTTP handler (cachovanie, chybové stavy), továrňu MCP nástrojov a systémový prompt.

Integračné testy (tests/integration/) — overujú správanie FastAPI endpointov (/, /info, /api/run), formát SSE odpovede a štruktúru správ histórie.

Eval testy (tests/evals/) — LLM-as-Judge hodnotenie agenta: presnosť výberu nástrojov (F1), grounding voči API dátam, bezpečnosť (žiadne právne rady) a detekcia halucinácie. Výsledky sa ukladajú ako JSON, heatmapa, tabuľka a radar chart do tests/results/.

Štruktúra testov

tests/
├── e2e/                           # End-to-end testy agenta (LLM-as-Judge hodnotenie)
│   ├── test_hallucination.py      # Testy detekcie halucinácie
│   ├── test_not_found.py          # Testy správania pri nenájdených výsledkoch
│   └── test_safety.py             # Testy bezpečnosti (žiadne právne rady)
├── evals/                         # Eval scenáre pre manuálne spustenie
│   ├── requests.json              # Referenčné požiadavky pre eval scenáre
│   └── test_scenarios.py          # Spúšťač eval scenárov
├── integration/                   # Integračné testy
│   ├── test_format.py             # Testy FastAPI endpointov a SSE formátu
│   ├── test_mcp_server.py         # Testy registrácie MCP nástrojov
│   ├── test_results.py            # Testy štruktúry API odpovedí
│   └── test_tools.py              # Testy volania a parametrov MCP nástrojov
├── reports/                       # Generované testovacie reporty (HTML)
├── unit/                          # Unit testy
│   ├── test_http.py               # Testy HTTP handlera (cache, chyby)
│   ├── test_prompt.py             # Testy systémového promptu
│   └── test_schemas.py            # Testy Pydantic schém (validácia, normalizácia)
├── __init__.py
└── conftest.py                    # Zdieľané fixtures pre všetky testy

Spustiť testy

# Unit testy
./scripts/testctl.sh unit

# Integračné testy
./scripts/testctl.sh integration

# Eval testy (vyžaduje bežiaci backend)
MODEL=gemini-2.5-flash ./scripts/testctl.sh evals

---

Návod na použitie

Požiadavky

• Docker a Docker Compose
• API kľúče pre LLM modely (Groq, Gemini, OpenRouter, Cerebras)

Spustenie aplikácie

1. Naklonovanie repozitára

git clone <url-repozitara>
cd legal-ai-assistant

2. Vytvorenie virtuálneho prostredia (voliteľné, pre lokálny vývoj)

./scripts/install.sh

Skript vytvorí venv a nainštaluje všetky závislosti. Ak prostredie už existuje, skript sa zastaví.

3. Zostavenie a spustenie

./scripts/appctl.sh --build

4. Otvorenie aplikácie

Aplikácia je dostupná na: http://localhost:8000

Ďalšie príkazy

./scripts/appctl.sh --start    # Spustiť (bez zostavenia)
./scripts/appctl.sh --stop     # Zastaviť
./scripts/appctl.sh --logs     # Zobraziť logy
./scripts/appctl.sh --clean    # Vyčistiť Docker cache

---

Zdroje

• Chainlit dokumentácia
• openai-agents dokumentácia
• FastMCP dokumentácia
• LiteLLM dokumentácia
• API Ministerstva spravodlivosti SR
• LiteLLM modely – Groq
• LiteLLM modely – Gemini
• LiteLLM modely – OpenRouter