8.5 KiB
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