Metadata-Version: 2.4
Name: rag-audit-toolkit
Version: 0.3.0
Summary: Audit toolkit for retrieval, evaluation, benchmark, and security checks in RAG systems
Project-URL: Homepage, https://github.com/office415/apskaitos-radaras
Project-URL: Repository, https://github.com/office415/apskaitos-radaras
Project-URL: Issues, https://github.com/office415/apskaitos-radaras/issues
Project-URL: Changelog, https://github.com/office415/apskaitos-radaras/blob/main/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Provides-Extra: pdf
Requires-Dist: reportlab<5,>=4; extra == "pdf"
Provides-Extra: ragas
Requires-Dist: ragas<0.4,>=0.1.21; extra == "ragas"
Provides-Extra: chromadb
Requires-Dist: chromadb<1,>=0.5; extra == "chromadb"
Provides-Extra: pgvector
Requires-Dist: psycopg<4,>=3; extra == "pgvector"
Provides-Extra: pinecone
Requires-Dist: pinecone<8,>=5; extra == "pinecone"
Provides-Extra: qdrant
Provides-Extra: deepeval
Requires-Dist: deepeval>=1.0.0; extra == "deepeval"
Provides-Extra: trulens
Requires-Dist: trulens>=0.27.0; extra == "trulens"
Provides-Extra: phoenix
Requires-Dist: arize-phoenix-evals>=2.0.0; extra == "phoenix"

# 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

```bash
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į:

```powershell
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:

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

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

```powershell
$env:PYTHONIOENCODING = "utf-8"
```

### 3. Konfigūracija

Atidaryk `.env` failą ir užpildyk:

```env
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=tavo@email.lt
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į:

```env
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:

```bash
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):

```json
{
  "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)

```bash
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):

```bash
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):**

```bash
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):**
```bash
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`):
```bash
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
