rag-audit-toolkit 0.3.0

Audit toolkit for retrieval, evaluation, benchmark, and security checks in RAG systems

Mokesčių GPT asistentas (Sufleris Agent) — Paleidimo instrukcija

Kas tai?

OpenAI agentas, kuris:

1. Priima klausimą lietuviškai
2. Ieško Mokesčių SUFLERYJE (tavo paskyra, per naršyklės automatizaciją) ir/arba VMI viešame tinklalapyje (HTTP, be prisijungimo)
3. Atidaro reikšmingiausius straipsnius / VMI puslapius
4. Atsako su šaltinių nuorodomis ir aiškiai skiria oficialų VMI turinį nuo Kitas šaltinis portalo praktinių paaiškinimų

---

Žingsnis po žingsnio

1. Reikalavimai

• Python 3.12 arba 3.11 (rekomenduojama; su dabartiniais requirements.txt pin’ais Python 3.14 dažnai nesurinks ratų — greenlet / pydantic-core)
• OpenAI API raktas (https://platform.openai.com/api-keys)
• Aktyvi Kitas šaltinis portalo paskyra (mokesciu-sufleris.lt)

2. Instaliavimas

cd sufleris-agent

# Sukurti virtualią aplinką
python -m venv venv
source venv/bin/activate        # Mac/Linux
venv\Scripts\activate           # Windows

# Instaliuoti priklausomybes
pip install -r requirements.txt

# Instaliuoti Playwright naršyklę
playwright install chromium

Windows (PowerShell), projekto šaknyje: jei nori .venv šalia repo ir stabilų py launcherį:

cd C:\kelias\į\sufleris-agent
Remove-Item -Recurse -Force .venv -ErrorAction SilentlyContinue
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

Jei Activate.ps1 neįvykdomas dėl politikos:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Jei python debug_selectors.py meta UnicodeEncodeError ant lietuviškų raidžių konsolėje, prieš paleidimą:

$env:PYTHONIOENCODING = "utf-8"

3. Konfigūracija

Atidaryk .env failą ir užpildyk:

OPENAI_API_KEY=sk-...
# Jei pridėsi Anthropic integraciją šiame repozitorijoje, naudok raktą
# ANTHROPIC_API_KEY_SUFLERIS (ne ANTHROPIC_API_KEY), kad nesikirstų su Claude Code.
SUFLERIS_EMAIL=[e-mail]
SUFLERIS_PASSWORD=tavo_slaptazodis
SUFLERIS_BASE_URL=https://www.mokesciu-sufleris.lt
SUFLERIS_LOGIN_PATH=/login
SUFLERIS_SEARCH_PATH=/paieska
SUFLERIS_SEARCH_PARAM=q
RESULT_LINK_SELECTOR=.wrapper__main_content__content__list__item__link
SUFLERIS_USERNAME_SELECTOR=input[name="_username"]
SUFLERIS_PASSWORD_SELECTOR=input[name="_password"]

(Paieška vyksta per puslapio paieškos lauką, ne per ?q= URL; SUFLERIS_SEARCH_PATH nurodo tik /paieska puslapį. Rezultatai skaitomi iš #results .ContentItemCard; galima keisti per SUFLERIS_SEARCH_HIT_CARD_SELECTOR.)

VMI (vieši URL, slaptų reikšmių nereikia) — galima pridėti į .env tik jei reikia koreguoti adresus ar teksto ilgį:

VMI_BASE_URL=https://www.vmi.lt
VMI_SEARCH_URL=https://www.vmi.lt/evmi/paieska
VMI_SEARCH_PARAM=query
VMI_TEXT_MAX=10000
VMI_SEARCH_FALLBACK=bing

/search-vmi ir agento VMI paieška: pirmiausia bandoma VMI vidinė paieška (VMI_SEARCH_URL + VMI_SEARCH_PARAM). Jei rezultatų nėra, įjungiamas atsarginis Bing režimas su užklausa site:vmi.lt/evmi … — pirmiausia nuskaitomas viešas Bing RSS (/search?format=rss&…, be mokamos paieškos API); jei RSS tuščias, bandomas Bing HTML ir iš jo renkamos tik vmi.lt nuorodos į kelius /evmi/.... Tai nenaudoja mokamos paieškos API. Jei nori išjungti išorinę paiešką, nustatyk VMI_SEARCH_FALLBACK=none.

Jei neįrašysi — naudojamos numatytosios reikšmės kode. Esamų Suflerio ir OpenAI raktų nekeisk.

4. Rask teisingus selektorius (BŪTINA)

Suflerio HTML struktūra nėra žinoma iš anksto, todėl reikia vieną kartą patikrinti:

python debug_selectors.py

Programa:

• Atidarys naršyklę (bus matoma)
• Prisijungs prie Suflerio
• Parodys visas rastas nuorodas
• Išsaugos debug_search_after_input.html ir kitus debug failus

Ką daryti po to:

1. Atidaryk debug_search_after_input.html naršyklėje
2. DevTools → Elements (F12)
3. Hover ant straipsnio kortelės
4. Nukopijuok CSS klasę, pvz. .search-item a ar .result-title
5. Jei reikia — pakeisk RESULT_LINK_SELECTOR .env faile (numatytąją reikšmę nustato app/kitas_client.py)

5. Paleidimas

Windows: run.bat (rekomenduojama vienu dukstu)

1. Paleidimas: dukart spustelėk projekto šaknyje run.bat (arba paleisk iš Explorer / CMD). Skriptas per PowerShell (ExecutionPolicy Bypass, -NoExit) aktyvuoja .venv, nustato UTF-8 ir paleidžia serverį ant 127.0.0.1:8010. Po kelių sekundžių automatiškai atsidaro naršyklė su adresu http://127.0.0.1:8010/ (web chat langas).
2. Trumpinys ant darbalaukio: dešiniu pelės mygtuku ant run.bat → Siųsti į → Darbalaukis (sukurti nuorodą). Arba Sukurti nuorodą ir Tikslas: įrašyk pilną kelią į run.bat, pvz. C:\Users\...\Desktop\sufleris-agent\run.bat.
3. Sustabdymas: aktyviame PowerShell lange, kuriame veikia uvicorn, spausk Ctrl+C — serveris sustos; naršyklės langą gali uždaryti atskirai. (-NoExit palieka konsolę atidarytą po sustabdymo, kad matytum žinutes.)

Patikrinimas naršyklėje arba PowerShell:

• http://127.0.0.1:8010/ — pagrindinis puslapis (chat UI)
• http://127.0.0.1:8010/health
• http://127.0.0.1:8010/search?query=PVM&limit=5 — paieška Mokesčių SUFLERYJE
• http://127.0.0.1:8010/search-vmi?query=PVM%20registracijos%20riba&limit=5 — VMI: vidinė paieška, tada Bing RSS/HTML (site:vmi.lt/evmi)

(Tas pats per PowerShell: Invoke-RestMethod "http://127.0.0.1:8010/health".)

Web chat UI (naršyklėje)

• Atverk http://127.0.0.1:8010/ (arba palauk, kol run.bat pats atidarys naršyklę).
• Pavadinimas: Mokesčių GPT asistentas.
• Šaltiniai: žymės langeliai Kiti šaltiniai, VMI, Sodra, VDI, AVNT (numatytai įjungti Kiti šaltiniai ir VMI). Jei nepažymėtas nė vienas — rodoma klaida ir užklausa nesiunčiama.
• Atsakymo išsamumas: Trumpai (short), Standartiškai (standard, numatytasis), Išsamiai (detailed).
• Režimas: Oficialus (official — prioritetas VMI ir reguliaciniams DB tekstams), Praktinis (practical — prioritetas portalui / praktikai), Abu (balanced — numatytasis balansas tarp šaltinių).
• Į didelį lauką įrašyk klausimą lietuviškai ir spausk Klausti — rodoma eigos juosta (pseudo-progresas iki ~94 %, kol laukiamas /ask), etapai, procentai ir Praėjo: N s; po 90 s papildomas paaiškinimas, kad ilgos užklausos normalu skaitant kelis šaltinius. Užbaigus — 100 % ir Baigta, trumpam rodoma Atlikta per N s. Kiekvienas sėkmingas klausimas pridedamas į pokalbio istoriją (vienos naršyklės sesijos metu, atmintyje).
• Po kiekvienu atsakymu: Kopijuoti atsakymą, Kopijuoti nuorodas, Atidaryti visas nuorodas (gali reikėti leisti iššokančius langus). Po nuorodų kortelių rodomi trumpi būsenos pranešimai (pvz. Atsakymas nukopijuotas).
• Visos nuorodos iš atsakymo — kortelės, sugrupuotos pagal domeną: VMI (vmi.lt), Kiti šaltiniai (mokesciu-sufleris.lt), Sodra, VDI, AVNT, kiti; kortelėje — pavadinimas (jei pavyksta ištraukti iš „Pavadinimas – URL“), paspaudžiama nuoroda, mygtukas Atidaryti.
• Išvalyti lauką — ištuština tik klausimo lauką. Išvalyti pokalbį — išvalo visą istoriją ir atsakymų sritį. Ctrl+Enter siunčia klausimą. Kol vykdoma /ask užklausa, Klausti pakeičiamas į Vykdoma... ir išjungiamas; Išvalyti mygtukai lieka aktyvūs (neatšaukia jau išsiųstos užklausos).
• Sistemos būsena (puslapio viršuje): po užkrovimo kviečiamas GET /health — serveris, Kitas šaltinis, VMI, dokumentų skaičiai pagal DB šaltinį (documents_by_source) ir bendras (documents_total).

POST /ask kūno formatas (visi laukai, išskyrus question, neprivalomi su numatytaisiais):

{
  "question": "...",
  "sources": ["kitas", "vmi", "sodra", "vdi", "avnt"],
  "detail_level": "standard",
  "answer_mode": "balanced"
}

• Jei sources praleistas arba tuščias — serveris naudoja abu šaltinius. Leidžiamos reikšmės: kitas (arba legacy sufleris), vmi.
• Jei detail_level arba answer_mode neteisingi — serveris naudoja numatytąsias reikšmes (standard, balanced), negrąžina 422 dėl šių laukų.

---

Rankinis paleidimas (visos OS)

uvicorn app.main:app --reload

Matysi:

INFO | Paleidžiamas Kitas šaltinis klientas...
INFO | Sėkmingai prisijungta prie portalo ✓
INFO | Uvicorn running on http://127.0.0.1:8000

6. Testavimas

Paprastas testas (curl) — abu šaltiniai (numatytai, jei sources neįrašytas):

curl -X POST http://127.0.0.1:8010/ask \
  -H "Content-Type: application/json" \
  -d "{\"question\": \"Kaip veikia reprezentacinių išlaidų PVM atskaita?\", \"sources\": [\"kitas\", \"vmi\"]}"

Tik VMI (be Kitas šaltinis portalo paieškos naršyklėje):

curl -X POST http://127.0.0.1:8010/ask \
  -H "Content-Type: application/json" \
  -d "{\"question\": \"Kokia PVM registracijos riba?\", \"sources\": [\"vmi\"]}"

Paieška be AI (debuginimui):

curl "http://127.0.0.1:8010/search?query=PVM+atskaita&limit=5"
curl "http://127.0.0.1:8010/search-vmi?query=PVM+registracijos+riba&limit=5"

Sveikatos patikrinimas (status, kitas_logged_in, vmi_http, version, pvz. mvp-2.2):

curl http://127.0.0.1:8010/health

Interaktyvus API dokumentas:

http://127.0.0.1:8010/docs

---

Projekto struktūra

sufleris-agent/
├── app/
│   ├── __init__.py
│   ├── main.py              ← FastAPI: /, /ask, /search, /search-vmi, /health
│   ├── agent.py             ← OpenAI: paieška ir atsakymas (Kitas šaltinis + VMI)
│   ├── kitas_client.py      ← Naršyklės automatizavimas (Playwright)
│   ├── vmi_client.py        ← VMI HTTP paieška ir puslapio tekstas
│   └── static/              ← Web chat UI (index.html, style.css, app.js)
├── .env                     ← Tavo raktai (NIEKADA į Git!)
├── requirements.txt
├── run.bat                  ← Windows: paleidžia serverį (8010)
├── run.ps1                  ← Windows: .venv + UTF-8 + uvicorn
├── debug_selectors.py       ← Selektorių paieška (paleisk pirmą kartą)
└── README.md

---

Galimos klaidos ir sprendimai

Klaida	Sprendimas
Login may have failed	Patikrink el. paštą/slaptažodį .env faile
0 rezultatų	Pakeisk RESULT_LINK_SELECTOR .env arba kliente (paleisk debug_selectors.py)
Timeout	Kitas šaltinis portalas lėtas — padidink timeout reikšmę client'e
Session expired	Klientas automatiškai prisijungs iš naujo
OpenAI error	Patikrink OPENAI_API_KEY ir balansą

---

Svarbu

• Šis įrankis skirtas tik asmeniniam naudojimui su tavo paskyra
• Nekeliok .env failo į GitHub
• Portalo turinys lieka portalo serveriuose — AI gauna tik trumpas ištraukas atsakymui