Metadata-Version: 2.4
Name: skypro
Version: 3.4.0
Summary: Skyprospector — by Simtricity
License: AGPL-3.0-or-later
License-File: LICENSE
License-File: NOTICE
Author: damonrand
Author-email: damon@cepro.energy
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: arrow (>=1.3.0,<2.0.0)
Requires-Dist: marshmallow (>=3.21.3,<4.0.0)
Requires-Dist: marshmallow-dataclass (>=8.7.0,<9.0.0)
Requires-Dist: pandas (>=2.2.2,<3.0.0)
Requires-Dist: pendulum (>=3.0.0,<4.0.0)
Requires-Dist: plotly (>=5.21.0,<6.0.0)
Requires-Dist: psycopg2-binary (>=2.9.10,<3.0.0)
Requires-Dist: pulp (>=2.9.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: sqlalchemy (>=2.0.37,<3.0.0)
Requires-Dist: streamlit (>=1.45.1,<2.0.0)
Requires-Dist: tabulate (>=0.9.0,<0.10.0)
Description-Content-Type: text/markdown

# Skypro

Skypro is the smart grid simulation and reporting engine behind Skyprospector, by
Simtricity. It models the electricity flows, costs and revenues of a
battery-and-solar smart grid — the kind that runs a UK community-energy site — to
answer two questions:

- **What would happen?** — `skypro simulate` projects how a site behaves under a
  chosen battery control strategy over historical (or synthetic) load, solar and
  price data, and reports the resulting energy flows, costs and revenues.
- **What actually happened?** — `skypro report` collates real metering data into
  performance reports and supplier-invoice estimates, flagging data-quality
  problems as Notices.

It is both a command-line tool and an importable Python engine.

## Install

```bash
pip install --upgrade skypro
```

Requires Python 3.10+. Run `skypro --help` (or `skypro <command> --help`) for the
full flag reference — this README covers the concepts and capabilities behind the
commands rather than repeating their usage.

## Quick start

A scenario is one YAML file containing one or more named simulations; select one
and run it:

```bash
skypro simulate -c scenario.yaml --sim my-scenario --plot
```

This writes the detail and summary CSVs named in the scenario's `output` block. A
report over a billing month:

```bash
skypro report -c report.yaml -m 2025-04
```

Both read the environment file described below. See `skypro <command> --help` for
every flag.

## Commands

- **`skypro simulate`** — project smart grid behaviour, cost and revenue over a
  time frame under a control strategy. Reads a YAML scenario config; writes
  detail and summary CSVs (and, for MPC, a per-tick NDJSON *replay* sidecar).
- **`skypro report`** — analyse real metering data for a billing period:
  reconstruct the smart grid flows, estimate the supplier bill, and surface
  metering inconsistencies as Notices.
- **`skypro pull-elexon-imbalance`** — fetch and cache Elexon imbalance
  volume/price data, used by imbalance-priced tariffs and forecasters.
- **`skypro replay validate`** — check a replay NDJSON against the schema
  (structural → per-line → cross-line → reconciliation layers). Downstream
  consumers use it to verify their own output.
- **`skypro replay solve-replay`** — re-solve a single recorded tick through the
  engine's own builder, trust-gate it against the recorded plan, and `--swap` one
  input to attribute why a decision differs.

## Core concepts

A little of the domain model goes a long way for authoring scenarios and reading
results.

### Seven energy flows
In every interval, energy moves along seven flows:

```
solar_to_load   solar_to_batt   solar_to_grid
grid_to_load    grid_to_batt
batt_to_load    batt_to_grid
```

Costs, revenues and levies are attributed per flow.

### Rates
Each flow carries rates in four categories:

- **Volumetric** (p/kWh) — DUoS, supplier fees, final-consumption levies.
- **Fixed** (p/day, p/kVA/day) — standing and capacity charges.
- **Market** — the actual cashflow with a supplier or counterparty.
- **Internal** — a notional opportunity-cost value the optimiser dispatches
  against.

Rates are supplied per flow, from JSON/YAML files or a rates database.

### Control strategies
Pick one per scenario under `strategy:`:

- **`perfectHindsightOptimiser`** — an LP that finds the optimal dispatch given
  perfect foresight of prices. The upper-bound benchmark.
- **`mpc`** — model-predictive control: a rolling-horizon LP re-solved each tick
  against *forecast* inputs. The realistic deployable; emits a replay NDJSON.
- **`priceCurveAlgo`** — a real-time heuristic (NIV chase, peak shaving, load
  following) driven by a price/state-of-energy curve.
- **`extension`** — a proprietary or external strategy loaded via a plugin seam
  (see `CLAUDE.md`).

### MPC forecasters
MPC drives its LP from forecasts, configured under the strategy. Solar and load
forecasts resolve independently. Rate forecasters: `rates_block`, `baseline`,
`composer`, `dayahead_rollforward`, `persistence`, `naive_seasonal`. Profile
(solar/load) forecasters: `meteo_solar` (weather-driven solar),
`naive_profile_persistence`, `perfect`.

### OSAM (P395)
The On-site Allocation Methodology for final-demand levies runs alongside
Skypro's own flow methodology; any discrepancy between the two is reported as a
Notice.

### Replay NDJSON
An MPC run can emit a per-tick NDJSON *replay* sidecar: a manifest, each tick's
forecast/LP/dispatch, half-hourly settlement records, and a summary trailer. It is
the shared format between the simulator, live edge producers, and replay viewers,
and is checked by `skypro replay validate`.

## Configuration

### Environment file (`~/.simt/env.json`)
Skypro reads a JSON environment file for directory shortcuts and database
credentials (override the path with `--env`):

```json
{
  "vars":  { "PROFILE_DIR": "/path/to/profiles" },
  "flows": { "dbUrl": "postgres://…" },
  "flux":  { "dbUrl": "postgres://…", "schema": "flux" },
  "rates": { "dbUrl": "postgres://…" }
}
```

- **`vars`** — arbitrary path variables. `$PROFILE_DIR` anywhere in a config path
  resolves from here.
- **`flows`** — the Flows database (plot meter tables).
- **`flux`** — the Flux database (meter and BESS readings, market data). `schema`
  defaults to `flux`; set it to `flows` for legacy single-schema databases.
- **`rates`** — the Rates database.

Only the sections a given run actually uses are required.

### Scenario config (YAML)
A simulation is described by a YAML scenario. The main sections are `timeFrame`,
`site.gridConnection`, `site.bess`, `site.solar` / `site.load` (profiles),
`rates` (per-flow rate files), `strategy`, and `output`. An annotated,
runnable example ships at
`src/tests/integration/fixtures/simulation/config.yaml`.

---

Skypro is developed and maintained by Simtricity Limited. Developer, release and
engine-embedding docs are in `CLAUDE.md`; version history is in `CHANGELOG.md`.

