# Právny AI Asistent – integrácia s API

![Uvítacia obrazovka](frontend/public/frontend_start.png)

## 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)