Skip to content
DigiSphereXPublic

About

Voltiva - worldwide smart electricity billing: auditable invoice engine, tariff management, AI/OCR bill scanning, PDF export (PyQt6)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Voltiva — Smart Electricity Billing

License: MIT Release Donate

Python PyQt6 Platform Version

Voltiva is a free, open-source desktop application for recording, reviewing, comparing and verifying electricity bills. It turns the official tariff rules into an auditable billing engine: every amount is explained, printable and verifiable, and the rules can be updated without editing code.

What it does

  • Auditable invoices — each bill shows the full calculation chain (tiers, fees, charges) so you can always answer "how did you arrive at this number?".
  • Tariff management — tariffs, fee schedules and rules are data, editable in-app via the Tariff Manager; simulation histories are kept for comparison.
  • AI bill scanning — photograph or scan a bill and a vision model reads the readings, dates, consumption, amount, account/meter numbers and the subscriber name into the import form. Three engines in Settings: Automatic — free AI (built-in service, free key), Custom AI (any OpenAI-compatible URL, key and model) and Offline — Tesseract.
  • Smart import (OCR) — the offline reader stays available for fully private scanning, and automatic mode falls back to it when the AI service is unreachable (requires Tesseract with the ara and eng language packs).
  • Subscribers & meters — manage subscriber records, meters, previous readings and debts.
  • Analytics dashboard — usage trends, cost breakdowns and exports.
  • Verification & review — compare simulated versus issued amounts to spot discrepancies.
  • Print / PDF export — professional printable documents and receipts, with no extra libraries required.
  • English demo data — one click in Settings loads a fully fictional English sample (2 tariffs, 4 subscribers, 4 self-verifying invoices) so you can explore every screen before entering your own records.
  • Nine interface languages — English, French, Spanish, German, Portuguese, Russian, Turkish, Hindi and Chinese, with automatic language and currency detection.
  • Six themes — Light, Warm Paper, Frost, Dark, Midnight Blue and Graphite, plus an automatic mode that follows Windows; every palette passes a WCAG AA contrast audit.

Download / Getting started

Requires Python 3.12+ with PyQt6 6.5+ (and optionally pytesseract + Pillow + numpy for OCR, plus openpyxl for Excel export).

Double-click Voltiva.exe — the launcher with the Voltiva icon (no console window opens) — or run the batch file:

run_voltiva.bat

or, from a terminal:

pythonw.exe run.py
python run.py

Your data is stored in ~/.voltiva/ (or %KSE_DATA_DIR% if set) as a local SQLite database — no cloud, no accounts, fully offline. A database created by an earlier version in ~/.kahraba_smart/ is adopted automatically on first start, so upgrading keeps every invoice, tariff and payment.

Screenshots

All pages and key dialogs (English UI, light palette):

Dashboard New invoice Invoices Verify Monthly review Analytics Tariffs Subscribers Settings Tariff dialog Subscriber dialog Import dialog

Dark palette:

Dashboard (dark) Invoices (dark) Analytics (dark) Settings (dark) Import dialog (dark)

How it works

Clean-architecture Python app: UI (PyQt6) → Application services → Domain billing engine → Infrastructure (SQLite, OCR, AI reader, exporters). The billing engine is 100% UI-independent, so the core rules can be reused or ported to other frontends. See src/kse/ for domain/, application/, infrastructure/ and presentation/.

Build & test from source

python -m pip install -r requirements-dev.txt
python -m pytest -q                    # full suite (engine, OCR/AI, GUI tour, infra)
python scripts/gui_smoke.py            # headless UI smoke test
python scripts/lint_qss.py             # static check of the Qt style sheet
python scripts/check_contrast.py       # WCAG contrast audit of all six palettes
python scripts/ui_geometry_audit.py    # detect clipped or shrunk widgets
python scripts/make_screenshots.py     # regenerate ScreenShot/*.png (light + dark)
python scripts/make_icons.py           # regenerate chevron/check icons after a palette change

The portable launcher is a single C# file, compiled with the .NET Framework compiler that ships with Windows:

csc /target:winexe /win32icon:energy.ico /r:System.Windows.Forms.dll launcher\Voltiva_launcher.cs

Requirements

  • Windows 10/11 (tested), Python 3.12 — install with pip install -r requirements.txt
  • PyQt6, and optionally: pytesseract (+ Tesseract binary with the ara and eng language packs), Pillow, numpy, openpyxl

Keyboard shortcuts: Ctrl+N new invoice, Ctrl+F invoices + search box, Ctrl+1 dashboard, Ctrl+2 analytics, Ctrl+R monthly review, Ctrl+Shift+V verify, Ctrl+T tariffs, Ctrl+U subscribers, Ctrl+, settings. Click a column header to sort invoices; click a bar in Analytics to open that month's invoices.

Disclaimer

Billing figures produced by Voltiva are analytical estimates for record and review purposes — not official documents. Always keep the paper/PDF invoice issued by your electricity provider as the authoritative record.

AI scanning sends the selected bill image to the provider you configure; the API key is stored in the local program database. Use the offline Tesseract engine if a bill must never leave the machine.

License

MIT — see LICENSE. The bundled Cairo typeface in assets/fonts/ is licensed under the SIL Open Font License 1.1 — see assets/fonts/OFL.txt.


☕ Support this project

Free and open source (MIT). If Voltiva saved you time or money, consider a small thank-you:

About

Voltiva - worldwide smart electricity billing: auditable invoice engine, tariff management, AI/OCR bill scanning, PDF export (PyQt6)

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages