# Spoločný výstupný kontrakt RAG a GraphRAG

V6 prenáša polia úplnosti a verzie aj do kontextu LLM a kontroluje ich pri
generovaní. Kontrola citácií sa vzťahuje na zoznam aj odkazy v texte odpovede.
[Implementácia, meranie a obmedzenia](graphrag_v6_2026-10-25_worklog.md).

Kontrakt v1 zjednocuje polia pre hlavného agenta a budúce OpenWebUI nástroje.
Vyhľadávanie naďalej vracia svoje pôvodné dáta. Klasický RAG zachováva
`context`, `instructions`, `answer_format` a rozšírené zdroje; GraphRAG
zachováva `facts`, `paths`, `documents`, `aggregation` a rozpoznané entity.
Historické evaluačné súbory ani zmrazené manifesty sa neprepisujú.

## Spoločné polia

| Pole | Význam |
|---|---|
| `status` | `ok`, `no_answer`, `ambiguous` alebo `error` |
| `reason` | Stabilný strojový dôvod; pri úspechu `null` |
| `sources` | Zoznam zdrojov s `source_id`, `document_path`, `source_url`, `title` |
| `index_version` | Spoločná generácia indexov vrátane Git revízie; `null`, ak nie je známa |
| `complete` | `true`: úplné vyhľadanie v rozsahu nástroja; `false`: neúplné; `null`: úplnosť nemožno zaručiť |
| `truncated` | Nástroj preukázateľne narazil na limit výberu alebo výstupu |
| `truncation_reasons` | Konkrétne limity; prázdne pole, ak žiadny nebol zistený |

`source_id` má tvar `S1`, `S2`, … v rámci jednej odpovede. URL a názov
môžu byť `null`, ak ich zdroj neposkytuje; nesmú sa domýšľať. RAG si v každom
zdroji ponecháva aj text, sekcie a retrieval metadáta. GraphRAG pridáva
`sources` popri pôvodnom `documents`, takže existujúci evaluator môže
ďalej používať pôvodné polia. Zdrojový dokument je identifikovaný cestou.

`ok` znamená úspešné získanie dôkazov alebo výsledku agregácie. Neznamená,
že LLM už odpovedal ani že vie zo zdrojov zodpovedať každú časť otázky.
Nulová, korektne vykonaná agregácia môže mať `status=ok`, `count=0` a žiadne
zdroje. `no_answer` označuje nenájdenie požadovaných faktov alebo entity;
`ambiguous` označuje nejednoznačné rozpoznanie; `error` zlyhanie nástroja.

## Význam úplnosti

Úplnosť **nevyjadruje percento presnosti ani pravdivosť odpovede**.

RAG je radený výber kandidátov. Ak sa preukáže orezanie, uvádza
`complete=false`; inak `null`, pretože nemôže zaručiť vyčerpávajúci zoznam
všetkých významovo relevantných informácií. Hlási `candidate_limit`,
`per_document_limit` a `result_limit`. Dodatočný kandidát slúži na detekciu
orezania a nezaraďuje sa do pôvodného radeného výberu. Rozšírenia kontextu
ďalej používajú svoje existujúce limity; `truncated=false` preto nie je
zárukou úplnosti kontextu ani pokrytia celej wiki.

GraphRAG vyjadruje úplnosť v rámci podporovaných štruktúrovaných dotazov
a nakonfigurovaných grafových prechodov. Hlási `entity_limit`,
`evidence_limit`, `fact_limit` a `path_limit`. Pri prechádzaní grafu overí
aj jeden výsledok nad limitom, aby rozpoznal orezanie už na úrovni Cypher.
`complete=true` neznamená neobmedzený prechod celým grafom: všeobecné
prechody naďalej používajú pôvodnú povolenú dĺžku ciest. Pri nejednoznačnosti
alebo chybe je `complete=false`, aj keď `truncated=false`.

`aggregation.complete` ostáva osobitným príznakom úplnosti **výpočtu**.
Príklad: presne napočítané 2 osoby, ale `limit=1` pre zobrazené dôkazy:

```json
{
  "status": "ok",
  "reason": null,
  "aggregation": {"count": 2, "complete": true},
  "complete": false,
  "truncated": true,
  "truncation_reasons": ["fact_limit", "path_limit"]
}
```

Príklad je skrátený. Agent môže uviesť presný počet podľa agregácie,
ale nesmie tvrdiť, že zobrazený výpis obsahuje všetky dôkazy.

## Nenájdenie a chyby

Nenájdenie používa napríklad `no_matching_sources`, `no_matching_facts`,
`unknown_person`, `unknown_keyword` alebo `unknown_title`. Nejednoznačnosť
používa napríklad `ambiguous_person`. Zostávajú zachované aj podrobnejšie
grafové `reasons` a dôkazy zamietnutých kandidátov.

API `/rag` a `/search` vracia pri chybách rovnakú obálku; pôvodné HTTP kódy
a `detail` zostávajú zachované. Dôvody zahŕňajú `invalid_query` (400),
`unauthorized` (401), `invalid_request` (422), `retrieval_unavailable` (503)
a `internal_error` (500). Validačné chyby nevracajú hodnoty zaslaných polí.

```json
{
  "status": "error",
  "reason": "retrieval_unavailable",
  "sources": [],
  "index_version": null,
  "complete": false,
  "truncated": false,
  "truncation_reasons": [],
  "detail": "Vyhľadávací index alebo embeddingový model momentálne nie je dostupný."
}
```

Po chybe sa neuvádza verzia dát, ktorú nástroj úspešne neprečítal. Chybová
obálka neobsahuje text interných výnimiek, heslá ani interné cesty.

Python knižničné funkcie naďalej vyhadzujú výnimky, aby existujúci kód mohol
riešiť chyby pomocou `try/except`. Transportné rozhrania ich prevádzajú na
obálku cez spoločné `error_result()`: HTTP API, grafový CLI a RAG CLI v režime
`--json`. Chybový CLI skončí návratovým kódom 1. Pre budúci MCP/HTTP adaptér
grafu sa použije ten istý prevod; nový grafový HTTP endpoint tento krok nepridáva.

## Použitie

```bash
python -m tools.rag.search_db 'strojový preklad' --json --limit 5
python -m tools.graphrag.graph_search 'Aký názov práce má Ján Holp?' --limit 5
```

Spoločné Pydantic modely aj tvorba obálky sú v `tools/retrieval_contract.py`.
OpenAPI pre `/rag` používa spoločné polia aj model chybovej odpovede.

## Overenie 25. 10. 2026

Kompletná sada projektu: **506 úspešných testov, 4 preskočené**. Nové testy
overujú spoločné polia, zachovanie rozšírených zdrojov RAG, detekciu limitov,
nejednoznačnosť, nenájdenie a chyby vrátane neplatného výstupu backendu.
Grafové testy používajú skutočný Neo4j v izolovanej transakcii s rollbackom.

Na nasadenom API sa overili `/rag`, `/search`, chyby autentifikácie a validácie
aj OpenAPI schéma. Skutočný GraphRAG napočítal 15 osôb s prácou v roku 2024;
počet bol rovnaký pri limite 1 a 100. Pri limite 1 správne označil dôkazy
za orezané, pričom samotný počet zostal úplný. Overilo sa tiež nenájdenie
neexistujúcej osoby a JSON chybové výstupy oboch CLI s návratovým kódom 1.

Nasadenie nevyžadovalo reindexáciu: verzia dát zostala nezmenená. Toto
overenie kontraktu nepredstavuje nové meranie presnosti LLM odpovedí.
Strojový záznam je v [vystupny_kontrakt_overenie.json](vystupny_kontrakt_overenie.json).