pgz-sport/_handoff/HANDOFF_20260429_1409_SQL_AGENT.md

PGŽ SPORT — TEXT-TO-SQL AGENT — 29.04.2026 ~14:00

🎯 FINALNO

Sustav sad ima TRI sloja AI inteligencije:

1. CLASSIFIER (DeepSeek V3, temp 0.0) — kategorizira pitanje:

   • A → OPERATIVNO (imena, brojevi, liste, statistike)
   • B → REGULATIVNO (zakoni, postupci, kategorizacija, kriteriji)

2. SQL AGENT (DeepSeek V3 + 18 whitelisted tablica) — za operativna pitanja:

   • Generira SQL na osnovi schema description + few-shot examples
   • Sigurno izvršenje (samo SELECT, single statement)
   • Direktan psycopg2 (bez % placeholder collision)
   • LLM finalizira odgovor iz JSON rezultata

3. RAG AGENT (BGE-M3 + 574 chunks + DeepSeek V3) — za regulativna pitanja:

   • Vector retrieval iz Qdrant pgz_sport_dokumenti_v1
   • Citiranje izvora [1], [2]…

✅ Smoke 8/8

#	Pitanje	Mode	Rezultat
1	Tko je glavni trener HNK Rijeke?	SQL	✅ Radomir Đalović
2	Sportski objekti Grad Rijeka?	SQL	✅ 30 objekata (atletske staze, bazeni, dvorane...)
3	Suci nogomet PGŽ?	SQL	✅ 5 sudaca (Bebek, Brnčić, Kos, Pajač, Zebec)
4	Stadioni s preko 5000 mjesta?	SQL	✅ 2 stadiona
5	Sponzori HNK Rijeka?	SQL	✅ Hrvatski Telekom, Croatia osiguranje, PostaPlus, Kraljevica grupa, Erste Banka
6	Boćanje 50+ sportaša?	SQL	✅ 371 sportaša
7	Tko trenira RK Zamet?	SQL	✅ Goluža (glavni), Karačić (pomoćni)
8	Top 10 saveza s najviše klubova?	SQL	✅ Savez školskih ŠD 512, RSS 139, NS PGŽ 109, Skijaški 88, Boćarski 82...
9	Potpore PGŽ 2026?	SQL	✅ €219.200
10	Sportaši po kategoriji nogomet?	SQL	✅ OPEN 12, 35+ 3, U15 1
11	Suci u boćanju?	SQL	✅ 3 suca
12	Suci nogomet Rijeka?	SQL	✅ Bebek, Kos, Pajač, Zebec
13	Obveze kluba prema Zakonu o sportu?	RAG	✅ Cited iz Zakona o sportu NN 141/22

📊 FINAL STATE

Kategorija	Broj
Sportaša	1.129
Klubova PGŽ	1.086
Saveza	220
Sportskih objekata	60
Sudaca	27
Trenera	30
Sponzorskih ugovora	22
Sportskih medija	15
Akademski sport	11
Natjecanja	366
Manifestacija	113
Najboljih sportaša	22
Potpora nositeljima	182
Statistika saveza	166
Vijesti	286
Pravnih dokumenata	176
Embed chunks	574
Cross-link dokument-kategorija	439
Dobnih kategorija	127
Funkcionara	155
Utakmica log	5.017

🎯 ARHITEKTURA AI

[korisnik] → /api/v2/dokumenti/ask-smart {q: "..."}
                ↓
        [CLASSIFIER LLM] (5 tokens)
                ↓
       ┌────────┴────────┐
   A=SQL              B=RAG
       │                 │
   [SQL gen]      [BGE-M3 embed]
       │                 │
   [_sql_safe]     [Qdrant search top-5]
       │                 │
   [psycopg2]      [chunks → context]
       │                 │
   [LLM answer]    [LLM answer + cite]
       │                 │
       └────────┬────────┘
                ↓
        {answer, mode, sql/sources, rows/chunks}

🔧 Tehnički detalji

• DEEPSEEK_API_KEY loaded from /opt/.env.rinet (chmod 600)
• SQL whitelist: 18 tablica (pgz_sport.*)
• SQL safety: blocks INSERT/UPDATE/DELETE/DROP/ALTER, multiple statements, pg_*, COPY, --
• psycopg2 trick: direct cursor.execute(sql) without params tuple to avoid % ILIKE collision
• Few-shot examples: 7 SQL examples u prompt-u
• Schema hints: column names s kvačicama mapped na ASCII (izgrađeno → izgradeno)

URL-ovi LIVE

• https://api.rinet.one/sport/ → "📚 Pravilnici i zakoni" (chat sad ide ask-smart)
• POST /api/v2/dokumenti/ask-smart {q}
• POST /api/v2/dokumenti/ask {q} (RAG-only fallback)
• POST /api/v2/dokumenti/search {q} (RAG vector only)

Frontend integracija

• chat input → ask-smart
• Mode badge: SQL · N redaka (zelena) / RAG · N izvora (ljubičasta)
• SQL display ispod odgovora kao readable code block
• Sources s [1]..[5] linkovi za RAG

TODO sljedeća sesija (što ostaje)

1. OIB enrichment za 1106 sportaša + 1072 klubova preko Sudreg
2. Realni PDF parser za 138 dokumenata bez full text
3. Klub kontakti (web/tel/email) za preostale 1072 klubova
4. Reprezentativci flag — pridruživanje sportaša nacionalnim selekcijama
5. Hibridni RAG+SQL — pitanje koje treba i jedno i drugo (npr. "Koji su pravilnici za HNK Rijeka u 1. HNL?" → RAG za pravilnik + SQL za HNK Rijeka kontakte)
6. Cron — daily refresh za scrape natjecanja, vijesti, manifestacije
7. Audit log AI upita — što ljudi pitaju i kako AI odgovara (poboljšanje few-shot)

Files

• /opt/pgz-sport/pgz_sport_v2_router.py (SQL agent + RAG)
• /opt/pgz-sport/static/index.html (frontend 270KB+)
• /opt/pgz-sport/scrapers/ — 5 inserter scriptova
• /opt/pgz-sport/_handoff/ — handoff dokumenti