jorgasisten

# Jorgasisten

Jorgasisten adalah Telegram AI assistant untuk membaca, menambah, mengubah, menghapus, dan merangkum data Google Sheets. Bot tidak mengandalkan nama sheet tetap. Setiap request akan membaca struktur spreadsheet terbaru, melihat nama sheet, header kolom, dan contoh data, lalu memilih sheet tujuan dengan confidence score.

## Fitur Utama

- Telegram bot berbasis `aiogram`.
- Dynamic Google Sheets catalog: nama sheet, kolom, dan contoh data.
- AI decision parser dengan format JSON wajib sesuai brief.
- Chat umum seperti ChatGPT untuk pertanyaan yang tidak perlu data Google Sheets.
- Operasi `read`, `create`, `update`, `delete`, `summarize`, dan `ask_clarification`.
- Operasi struktur spreadsheet admin-only: buat sheet, ganti header, rename sheet, hapus sheet penuh.
- Tombol aksi setelah hasil data: refresh, detail, edit, hapus, dan ringkas sheet.
- Konfirmasi inline untuk aksi berisiko sebelum data benar-benar diubah.
- Audit log otomatis ke sheet `Bot_Log` untuk operasi write yang sukses.
- Multi-spreadsheet: tambah spreadsheet baru dari Telegram, lihat daftar, pilih spreadsheet aktif per chat, dan set default.
- Proteksi write operation untuk admin Telegram.
- Safe delete mode: soft delete jika ada kolom status/delete, atau row delete jika diaktifkan.
- Docker Compose untuk VPS.
- Unit test untuk schema routing, decision model, dan executor CRUD.

## Struktur Project

```text
jorgasisten/
  apps/jorgasisten/
    bot/              Telegram handlers dan keyboard
    core/             Config dan logging
    services/         AI parser, Google Sheets client, executor, formatter
    schemas.py        Model data dan decision JSON
  docs/               Blueprint dan prompt handoff Hermes
  tests/              Unit tests tanpa akses external API
  Dockerfile
  docker-compose.yml
  pyproject.toml
  .env.example
```

## Install Lokal

```bash
cd "D:\hermes agent\jorgasisten"
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
```

## Environment Variable

Copy `.env.example` menjadi `.env`, lalu isi:

```env
TELEGRAM_BOT_TOKEN=...
GOOGLE_SHEETS_SPREADSHEET_ID=...
GOOGLE_SERVICE_ACCOUNT_JSON_BASE64=...
# atau OAuth authorized-user:
GOOGLE_OAUTH_AUTHORIZED_USER_JSON_BASE64=...
# atau file JSON service-account / authorized-user:
GOOGLE_APPLICATION_CREDENTIALS=...
OPENROUTER_API_KEY=...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=openai/gpt-4o-mini
ADMIN_TELEGRAM_IDS=123456789,987654321
AUDIT_LOG_ENABLED=true
AUDIT_LOG_SHEET_NAME=Bot_Log
SPREADSHEET_REGISTRY_PATH=data/spreadsheets.json
DEFAULT_SPREADSHEET_KEY=default
```

Opsi credential Google yang didukung:

- `GOOGLE_SERVICE_ACCOUNT_JSON_BASE64`: paling stabil untuk bot headless/VPS.
- `GOOGLE_OAUTH_AUTHORIZED_USER_JSON_BASE64`: hasil login OAuth satu kali, cocok kalau memang tidak pakai service account.
- `GOOGLE_APPLICATION_CREDENTIALS`: path ke file JSON `service_account` atau `authorized_user`.

Catatan penting:

- File `client_secret_*.apps.googleusercontent.com.json` saja belum cukup untuk runtime bot.
- File itu harus dipakai dulu untuk generate `authorized_user` token.
- Helper yang disediakan: `python scripts/generate_google_oauth_authorized_user.py --client-secret "D:\hermes agent\envtreding.md"`

Jika memakai service account, service account harus diberi akses Editor ke spreadsheet.
Untuk multi-spreadsheet, setiap spreadsheet baru juga harus di-share ke service account yang sama.

## Menjalankan Bot

```bash
python -m jorgasisten.bot.main
```

## Menu Telegram

Menu utama:

```text
Chat Umum | Tanya Data
Tambah Data | Update Data
Hapus Data | Ringkasan
Sheet/Tabel | Bantuan
```

Submenu `Sheet/Tabel`:

```text
Lihat Semua Sheet
Buat Sheet Baru
Ganti Header/Kolom
Rename Sheet
Hapus Sheet Penuh
Kembali
```

Submenu `Spreadsheet`:

```text
Spreadsheet Aktif
Daftar Spreadsheet
Tambah Spreadsheet
Pilih Spreadsheet
Set Default Spreadsheet
Kembali
```

Tombol yang berisiko seperti `Hapus Data` dan `Hapus Sheet Penuh` tidak menjalankan hapus sekali klik.
Bot akan menampilkan contoh format instruksi dan tetap memakai guardrail permission/konfirmasi dari executor.

Setelah hasil baca/ringkasan data, bot juga bisa menampilkan tombol inline:

```text
Refresh | Detail
Edit | Hapus
Ringkas Sheet Ini
```

`Edit` dan `Hapus` dari tombol inline hanya memberi template instruksi yang aman. Eksekusi perubahan tetap harus lewat pesan user dan konfirmasi inline.

## Docker Compose

```bash
docker compose up -d --build
docker compose ps
docker compose logs -f bot
```

## Quality Check

```bash
ruff check .
mypy apps
pytest
python -m compileall apps
```

## Contoh Prompt Telegram

```text
Catat pembelian oli 10 botol harga 50000
Ada data booking atas nama Budi?
Update stok oli MPX jadi 8
Hapus data transaksi invoice INV-001
Buat ringkasan penjualan minggu ini
Buat sheet Booking dengan kolom Nama, Nomor WA, Motor, Status
Ubah kolom sheet Products jadi Nama Produk, Harga, Stok
Rename sheet Booking jadi Booking Masuk
Hapus sheet penuh Booking Lama
Tambah spreadsheet Stok Gudang https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
Daftar spreadsheet
Pakai spreadsheet Stok Gudang
Spreadsheet aktif
```

## Manual Testing Checklist

- `/start` menampilkan menu utama.
- Tombol `Chat Umum` menampilkan contoh pertanyaan bebas.
- Tombol `Tanya Data`, `Tambah Data`, `Update Data`, `Hapus Data`, dan `Ringkasan` menampilkan panduan format.
- Tombol `Sheet/Tabel` membuka submenu struktur spreadsheet.
- Tombol `Kembali` mengembalikan keyboard ke menu utama.
- Tombol inline hasil data bisa refresh, tampil detail, memberi template edit/hapus, dan membuat ringkasan sheet.
- Hapus data, ganti header, rename sheet, dan hapus sheet penuh menampilkan tombol konfirmasi sebelum eksekusi.
- Operasi write yang sukses masuk ke sheet audit `Bot_Log`.
- Tombol `Spreadsheet` menampilkan submenu multi-spreadsheet.
- `Tambah spreadsheet Nama Link/ID` menyimpan spreadsheet baru dan mengaktifkannya untuk chat itu.
- `Pilih Spreadsheet` menampilkan tombol realtime dan langsung mengganti spreadsheet aktif chat ini.
- `Set Default Spreadsheet` menampilkan tombol realtime dan langsung mengganti spreadsheet bawaan bot.
- `Pakai spreadsheet Nama/Key` tetap bisa dipakai sebagai alternatif manual.
- `/schema` menampilkan daftar sheet dan kolom dari Google Sheets.
- Pertanyaan baca data memakai sheet yang relevan.
- Input data baru hanya menyimpan ke kolom yang ada.
- Update data meminta klarifikasi jika target lebih dari satu.
- Delete data tidak berjalan jika confidence rendah.
- Ringkasan data menampilkan jumlah dan contoh baris relevan.
- Bot memberi error aman jika Google Sheets atau AI provider gagal.
- Non-admin tidak bisa create/update/delete jika `REQUIRE_ADMIN_FOR_WRITES=true`.