Metadata-Version: 2.4
Name: vledger
Version: 0.7.7
Summary: Vehicle ledger: trips, charging, refuelling and cost, derived from a raw log of Home Assistant states
Author-email: Michael Lenz <michael.lenz@nullvector.org>
License-Expression: BSD-3-Clause
Project-URL: Repository, https://github.com/michael-lenz/ha-vledger
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Home Automation
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: tzdata; extra == "test"
Provides-Extra: dev
Requires-Dist: vledger[test]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: ha
Requires-Dist: pytest-homeassistant-custom-component; extra == "ha"
Dynamic: license-file

# ha-vledger

> **Beta.** Everything the design describes is built — capture, trips,
> refuellings, charging sessions, receipts, metrics, entities, statistics,
> exports — and runs on the author's vehicle, against whose drives every
> derivation has been checked; against nobody else's yet. The options may
> still change between releases, a release may rebuild the derivation from
> the raw log, and there is no support. The log format is decided and will
> be read by every later version, so what is captured now is kept. Install
> it through HACS as a custom repository if you want to try it; this
> notice goes when the register's checklist for leaving it is met
> (TASK-0032).

A vehicle ledger for Home Assistant. It keeps a raw log of the handful of
vehicle states that matter to a ledger — odometer, position, fuel level,
state of charge, charging state — and derives from it what the vehicle's
own app never tells you reliably: trips, charging sessions, refuellings,
consumption and cost. Passively, from whatever integration already exposes
the vehicle, without a line of manufacturer-specific code, and without
touching anything else the vehicle reports: it is a ledger, not a monitor.

**Status:** everything described here is built, in the library and in
the integration, and the notice above says what that is worth. Every
behaviour is the design, held as requirements in the project's register
(`ha-vledger-pm`).

## What it does

- **Captures, losslessly.** Every change of a source entity you assign to
  a role becomes one record in a raw log (L0): JSON Lines, append-only, one
  stream per vehicle and per charge point, rotated monthly, kept outside
  the Home Assistant recorder and its retention. Start, stop and heartbeat
  markers make any capture gap visible; nothing is interpolated across one.
- **Derives, deterministically.** Trips (between standstills), charging
  sessions (from the charging state), refuellings (a fuel rise at unchanged
  odometer) and metrics are computed from L0, receipts and configuration
  (L1) — the same logic live in Home Assistant and in batch from the
  command line, recomputable from scratch at any time. Every derived value
  carries a quality flag: `measured`, `receipt`, `estimated` or
  `incomplete`.
- **Takes receipts.** Price and exact quantity come from you: a refuelling
  or charging receipt, entered from a dashboard, the Vehicle Ledger card
  beside its trip list, or an action — a
  notification of the new candidate opens the form — matched to the
  detected event by time. Receipt values beat sensor
  values; a detected event without a receipt stays visible as unconfirmed.
- **Knows your charge points.** Home, work, anywhere fixed: position,
  radius, tariff, optionally a meter. A charge point with a tariff but no
  meter still yields cost, estimated through a charging loss factor; a
  tariff of 0 is cost 0. Anything else is a foreign charge and asks for a
  receipt.
- **Reports.** Per month, year and rolling period: distance, litres and kWh,
  fuel and electricity cost, the cost per 100 km per energy carrier, the electric
  share two ways (energy by heating value, and an estimated distance
  share), charge cycles and tank-fill equivalents. Fuel consumption is
  tank-to-tank between any two receipts, corrected by the fuel level sensor,
  so a tank that is never filled up still gets a figure. A single trip's
  fuel and battery energy are its own figures beside that, in litres and
  kWh and per 100 km, from the trip computer or the sensor deltas, shown
  when they exceed their possible error or are right to the step they are
  shown in — an electric trip read from the trip computer is 0 L. A trip's
  cost is that consumption at the last prices known when it started.

## What it is built of

One repository, two packages, one version number (ADR-0002):

```
src/vledger/               the library and the vledger CLI: all derivation
                           logic, no Home Assistant, no dependencies;
                           published to PyPI as `vledger`
custom_components/vledger/ the Home Assistant integration, a shell over the
                           library: capture, config and options flows,
                           entities, actions, diagnostics, and the Lovelace
                           card as plain JavaScript under frontend/; pins
                           the library by the same version in manifest.json
tests/                     pytest: library tests on L0 fixtures, integration
                           tests with pytest-homeassistant-custom-component;
                           the card's model with Node's own test runner
docs/                      design documents, operating manuals, the user guide
```

A vehicle is a config entry; its source entities are assigned to roles
(`odometer`, `position`, `fuel_level`, `soc`, `charging_state`, …), and
what the vehicle can do follows from the roles it has. Everything is
configured in the UI; no YAML.

## Documentation

| Document | What it is |
|---|---|
| [docs/user-guide.md](docs/user-guide.md) | What a participant types: the `vledger` command, verb by verb |
| [docs/l0-format.md](docs/l0-format.md) | The raw log's layout, version 4 — the specification a reader of their own files needs |
| [docs/l1-format.md](docs/l1-format.md) | The derivation on disk: files, manifest, cursor, rebuilds, and the exports rendered from it |
| [docs/derivations.md](docs/derivations.md) | How each detection works as built: algorithm, roles and parameters, quality flags, limitations |
| [docs/receipts-format.md](docs/receipts-format.md) | Receipts on disk, corrections and cancellations, and how they meet events |
| [docs/glossary.md](docs/glossary.md) | The one English spelling of every domain term, and what it means |
| [docs/developing.md](docs/developing.md) | From a fresh clone to green tests, and the conditions behind each step |
| [docs/releasing.md](docs/releasing.md) | What the person cutting a release does, in order |

Decisions, requirements and the work queue are records in the project's
register, `ha-vledger-pm`, not prose here.

## Installing

Through HACS, as a custom repository while the notice above stands:
*Integrations → ⋮ → Custom repositories*, add
`https://github.com/michael-lenz/ha-vledger` as an *Integration*, install
it and restart; or copy `custom_components/vledger` into the configuration
directory by hand. Either way Home Assistant installs the library from
PyPI (`vledger==<version>`, pinned in the manifest). Then *Settings →
Devices & services → Add integration → Vehicle Ledger*: the
[user guide](docs/user-guide.md) walks the four steps. The library on its
own: `pip install vledger`, which brings the `vledger` command. A
development checkout runs differently —
[docs/developing.md](docs/developing.md).

## Developing

[docs/developing.md](docs/developing.md) is the manual; the short form:

```bash
python3 -m venv .venv && .venv/bin/pip install -e ".[dev,ha]"
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests custom_components
node --test tests/frontend/model.test.mjs
```

The library's tests run in any Python with `.[dev]`; the integration's
need the `ha` extra and a venv; the card's need Node and nothing else. `CLAUDE.md` says how a Claude session
works here and with the register.

## Privacy

The position history is personal data. It stays on your instance — nothing
is transmitted anywhere — and is redacted from logs and diagnostics, but
the default storage path lies under the Home Assistant configuration
directory and is therefore part of your backups.

## License

BSD-3-Clause — see [LICENSE](LICENSE).
