212 lines
8.5 KiB
Markdown
212 lines
8.5 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 (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
|
||
|
||
```bash
|
||
# 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**
|
||
```bash
|
||
git clone <url-repozitara>
|
||
cd legal-ai-assistant
|
||
```
|
||
|
||
**2. Vytvorenie virtuálneho prostredia (voliteľné, pre lokálny vývoj)**
|
||
```bash
|
||
./scripts/install.sh
|
||
```
|
||
Skript vytvorí `venv` a nainštaluje všetky závislosti. Ak prostredie už existuje, skript sa zastaví.
|
||
|
||
**3. Zostavenie a spustenie**
|
||
```bash
|
||
./scripts/appctl.sh --build
|
||
```
|
||
|
||
**4. Otvorenie aplikácie**
|
||
|
||
Aplikácia je dostupná na: [http://localhost:8000](http://localhost:8000)
|
||
|
||
### Ďalšie príkazy
|
||
|
||
```bash
|
||
./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](https://docs.chainlit.io)
|
||
- [openai-agents dokumentácia](https://openai.github.io/openai-agents-python/)
|
||
- [FastMCP dokumentácia](https://gofastmcp.com)
|
||
- [LiteLLM dokumentácia](https://docs.litellm.ai)
|
||
- [API Ministerstva spravodlivosti SR](https://obcan.justice.sk)
|
||
- [LiteLLM modely – Groq](https://docs.litellm.ai/docs/providers/groq)
|
||
- [LiteLLM modely – Gemini](https://docs.litellm.ai/docs/providers/gemini)
|
||
- [LiteLLM modely – OpenRouter](https://docs.litellm.ai/docs/providers/openrouter) |