Mirrors/EOS
1
0
Fork 0
mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-10-09 07:56:40 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
Files
04f28997ea8ccf38682bb942a3a114e10c151df3
EOS/docs/_generated/openapi.md
T
AndreasGitHubAndreasChristinNormannBobby Noelter0b2g1t
 04f28997ea feat: deliver complete GENETIC optimization to main (#1330) 
* feat: adapt configuration for multi optimization algorithms

Decouple configuration from optimization algorithm parameters. Add to_[algorithm]_param() methods
to the configuration that derive optimization algorithm specific parameters from the configuration.
Add x-scope tags to the configuration options that describe for which specific algorithms the
configuration option is for.

The whole device settings are restructured. There are now general settings for the device classes
with the afore mentioned to_[algorithm]_param() methods. The general device settings got their own
directory `devices/settings`. By this the parameter class also does not have to be a pydantic model
which can be used for future optimization/ simulations speed up.

Also the parameter class for a device is now part of the device module. This better decouples and
also is the natural place for parameters of a device.

Besides this feature there are also fixes and improvements:

* feat: extend home appliance time window settings and simulation

  Home appliance can now be configured for multiple runs with per-cycle allowed time windows. The
  number of remaining cycles to plan is determined at runtime by reading the
  ``cycles_completed_measurement_key`` from the measurement store.

* feat: specialiced CycleTimeWindowSequence for time window sequences

  Sequence of time windows associated to cycles.

  This model specializes ``ValueTimeWindowSequence`` so that the ``value``
  field of each ``ValueTimeWindow`` encodes the **cycle index** (0-based
  integer) the window belongs to.

  Typical use: an appliance that must run ``n`` times per day, each run
  constrained to a distinct time window.  Assign ``value=0`` to windows
  for the first cycle, ``value=1`` for the second, and so on.  Multiple
  windows may share the same cycle index (their allowed regions are unioned).
  Windows with ``value=None`` are silently ignored by all cycle-aware methods.

* fix: Make test_configmigrate also regard the _ANY_SENTENIEL in key values

* chore: Make devices configurations a map instead of a list

  This makes config paths stable regardless of declaration order and lets each device settings
  class build its own config path from ``self.device_id`` without needing an external index.
  Tests are adapted likewise.

  Devices configurations are automatically migrated from lists to maps.

* chore: rename levelized_cost_of_storage_kwh to levelized_cost_of_storage_amt kwh

  This better fits in the naming scheme and also makes clear the costs are money.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

* fix: runtime config update ignored by config file

Runtime settings were handed back to pydantic-settings as init settings,
which rank below the config file and the environment. Any key already
present in EOS.config.json or in the environment silently discarded the
update, so a bulk PUT /v1/config returned 200 without applying anything,
while the granular PUT /v1/config/{path} endpoint kept working.

Add a dedicated runtime settings source ranked directly below the command
line arguments and record granular updates there as well, so both
endpoints share one store that survives re-evaluation of the settings
sources. Environment variables keep precedence over the config file for
all keys that were not set at runtime.

Also repairs revert_settings() and update(), which passed their data
through the same init settings.

Closes #1303

* fix: env vars ignored on first config build

ConfigEOS.__init__ passed self as first positional argument to _setup,
which forwards it to pydantic_settings.BaseSettings.__init__. Its first
positional parameter is _case_sensitive, so the environment source
matched the upper case variable names against the lower case field names
and returned nothing. Environment settings only took effect after the
next configuration setup.

* docs: changelog for config priority fixes

* fix(config): preserve device identities and storage costs during migration

* fix(measurement): restore JSON records into the existing singleton

* fix(devices): preserve charge-rate typing and public import compatibility

* feat(measurement): integrate typed energy quality and capacity APIs

Port the locally backed-up measurement extensions to main async storage and PR #1256 device maps. Preserve runtime capacity estimates across #1305 bulk updates. Confirm JSON singleton restore defect on unchanged main and add regression. No production configuration or measurements included.

Co-authored-by: Andreas <drbacke@gmx.de>

* docs(measurement): describe household settings and consolidate regression coverage

* docs(measurement): regenerate configuration and API contracts

* test(measurement): isolate capacity database state between tests

* ruff format fix

* fix(measurement): restore JSON records into the existing singleton

* test(measurement): assert restored timestamps before timezone conversion

* test(measurement): assert restored timestamps before timezone conversion

* fix: preserve imported feed-in revenue during parameter preparation

Cancel GENETIC preparation when imported revenue cannot be read or contains invalid values, preserving the chosen provider instead of replacing it with demo tariffs. Keep valid positive, zero and negative amount/Wh series unchanged.

Adapt the revenue-preservation regressions from PRs #1224 and #1304 to the async main API, including real timestamped imports and simulation repricing. The feature-only direct-marketing override remains outside this main fix.

Co-authored-by: Christin <info@bikinibottom.capital>

Co-authored-by: Normann <github@koldrack.com>

* feat(devices): port slot-aware battery export and direct-use physics

Port scoped device changes from d2e2d58237. Keep PR #1256 parameter conversion structure and separate GENETIC0 devices. Validate physical flows and reprice changed simulation results.

Co-authored-by: Andreas <drbacke@gmx.de>

Co-authored-by: Christin <info@bikinibottom.capital>

* docs(measurement): align API version with refreshed prerequisites

* fix: return only completed optimization results per run

* feat(pvforecast): add calibrated local Akkudoktor backend

Port local PV modeling and outage calibration from feature commits f976335, 6dc58c3 and faed0fd by Andreas. Keep PVForecastAkkudoktor identity and remote default, adapt to async storage, and migrate legacy provider settings.

* fix(cache): distinguish callables in the shared EMS cache

Include the function object in cache keys so methods of one interpolator cannot reuse a probability as a power value. Cover both call orders, keyword arguments, cache hits and separate closures with identical qualified names.

* fix(devices): constrain the physics port and validate export levels

Defer inactive EV deadline fields to the optimizer port, reject nonfinite export rates, and document the hourly Optimize boundary. Verify converter IDs, rates and LCOS, separate GENETIC0 interpolation, physical boundary flows and independent GENETIC repricing.

* docs(pvforecast): regenerate local backend configuration schema

* docs(devices): regenerate slot-physics configuration and OpenAPI schemas

* test: type dynamic Optimize regression arguments

* style: wrap imported tariff test parameter import

* style(pvforecast): apply CI import formatting

* docs(pvforecast): refresh API version after CI formatting

* fix(config): satisfy typed device conversion and migration contracts

* docs(config): refresh validated configuration prerequisite schemas

* fix(measurement): enforce typed capacity and sample validation

* test(devices): align physics regressions with strict type checking

* style(measurement): normalize imports for CI

* docs(measurement): refresh typed measurement API schemas

* docs(devices): refresh API version after prerequisite merge

* test: make optimization dispatch timezones explicit

* docs(interpolator): use portable reStructuredText markup

* docs(devices): refresh API version after docstring compatibility fix

* feat: complete configuration-driven GENETIC optimization and reports (#1329)

* feat(devices): port slot-aware battery export and direct-use physics

Port scoped device changes from d2e2d58237. Keep PR #1256 parameter conversion structure and separate GENETIC0 devices. Validate physical flows and reprice changed simulation results.

Co-authored-by: Andreas <drbacke@gmx.de>

Co-authored-by: Christin <info@bikinibottom.capital>

* feat(optimization): port tested terminal and tail value primitives

Source d2e2d58237. 22 primitive tests pass; integration with the optimizer, forecast horizon and API is still pending.

Co-authored-by: Andreas <drbacke@gmx.de>

Co-authored-by: Christin <info@bikinibottom.capital>

* fix(devices): preserve charge-rate typing and public import compatibility

* feat(measurement): integrate typed energy quality and capacity APIs

Port the locally backed-up measurement extensions to main async storage and PR #1256 device maps. Preserve runtime capacity estimates across #1305 bulk updates. Confirm JSON singleton restore defect on unchanged main and add regression. No production configuration or measurements included.

Co-authored-by: Andreas <drbacke@gmx.de>

* test(integration): validate optimizer economics and document measurement settings

* docs(integration): record tested checkpoint and remaining consolidation work

* docs(development): define isolated PR packages and remaining porting gates

* docs(integration): refresh API version after measurement reconciliation

* docs(integration): record PR readiness verification results

* docs(development): record publication and verification of PR 1322

* test(measurement): assert restored timestamps before timezone conversion

* docs(development): record corrected PR head and CI progress

* docs(integration): refresh API version after prerequisite alignment

* docs(integration): define parallel packages and Optimize compatibility gates

* fix: preserve imported feed-in revenue during parameter preparation

Cancel GENETIC preparation when imported revenue cannot be read or contains invalid values, preserving the chosen provider instead of replacing it with demo tariffs. Keep valid positive, zero and negative amount/Wh series unchanged.

Adapt the revenue-preservation regressions from PRs #1224 and #1304 to the async main API, including real timestamped imports and simulation repricing. The feature-only direct-marketing override remains outside this main fix.

Co-authored-by: Christin <info@bikinibottom.capital>

Co-authored-by: Normann <github@koldrack.com>

* test(integration): verify tariff protection with mapped device physics

* fix: return only completed optimization results per run

* test(integration): verify algorithm aliases and mapped-device contracts

* fix(cache): distinguish callables in the shared EMS cache

Include the function object in cache keys so methods of one interpolator cannot reuse a probability as a power value. Cover both call orders, keyword arguments, cache hits and separate closures with identical qualified names.

* fix(devices): constrain the physics port and validate export levels

Defer inactive EV deadline fields to the optimizer port, reject nonfinite export rates, and document the hourly Optimize boundary. Verify converter IDs, rates and LCOS, separate GENETIC0 interpolation, physical boundary flows and independent GENETIC repricing.

* feat(pvforecast): add calibrated local Akkudoktor backend

Port local PV modeling and outage calibration from feature commits f976335, 6dc58c3 and faed0fd by Andreas. Keep PVForecastAkkudoktor identity and remote default, adapt to async storage, and migrate legacy provider settings.

* docs(integration): record combined compatibility checks and green JSON PR CI

* test: type dynamic Optimize regression arguments

* docs(integration): record Optimize fix PR publication

* docs(integration): record imported tariff protection PR

* style(pvforecast): apply CI import formatting

* style(integration): align combined regression imports

* test: make optimization dispatch timezones explicit

* docs(interpolator): use portable reStructuredText markup

* chore: validate combined integration with locked mypy

* docs: hand off six validated pull requests for manual review

* feat: report genetic interval and terminal value diagnostics

* feat(devices): reconcile flexible profiles and EV deadlines with cycle scheduling

Adapt the flexible consumer primitives from d2e2d582 while retaining the keyed settings and per-cycle scheduling introduced by #1256. Preserve slot battery physics and GENETIC0 flat-load conversion. Cover energy conservation, deadlines, window intersections, DST, completed cycles and EV converters.

* test: satisfy typed genetic PDF chart contracts

* feat(optimization): resolve quarter-hour GENETIC requests from configuration

* test(genetic): verify real device scheduling, measurement and export contracts

Register appliance completed-cycle measurement keys so the real store accepts both default and custom counters. Exercise complete low-budget optimizer runs, persisted measurements, generic solution output and instructions, including zero-power phases, EV departure boundaries, per-cycle windows and LCOS.

* fix: bound genetic report forecasts to executable horizon

* feat: complete native genetic scheduling and retained result contracts

* fix: retain missing raw samples when dropna is disabled

* fix: align local optimization slots and measurement instants

* docs: explain complete genetic rollout and PR dependencies

* feat: expose retained GENETIC report through the versioned API

* docs: regenerate complete genetic configuration and API schema

* docs: format consolidation and review handoff markdown

* test: align isolated EMS fixture with native genetic run options

* test(genetic): clean up singleton measurements after device integration tests

* test: freeze the clock without replacing timestamp conversion

* fix: preserve explicit warmstart timezones in runtime requests

* test(genetic): validate device schedules in UTC and Berlin

Use explicit Berlin origins for Berlin wall-clock windows, compare absolute deadline instants correctly, and run all real device optimizer scenarios under both UTC and Europe/Berlin. Compare exported starts in the run timezone instead of assuming the output timezone matches the host.

* fix: start automatic genetic runs in the site timezone

* Preserve aware GENETIC snapshot times across host timezones

* docs: specify site clock and rehearsed merge resolutions

* test: isolate invalid measurement records and refresh API version

* fix: render single-slot genetic tail diagnostics

* docs: refresh schema version after report fix

* fix: preserve configuration-only Optimize API contract

* docs: refresh configuration request schema

---------

Co-authored-by: Christin <info@bikinibottom.capital>
Co-authored-by: Normann <github@koldrack.com>

---------

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: r0b2g1t <r0b2g1t@users.noreply.github.com>
Co-authored-by: Normann <github@koldrack.com>
Co-authored-by: Christin <info@bikinibottom.capital>
2026-09-17 20:14:24 +02:00

63 KiB
Raw Blame History

Akkudoktor-EOS

Version: v0.3.0.dev2609171762020752

Description: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.

Currency Information

All monetary values in this API are expressed in the locally configured currency of the EOS installation. The system is designed to work with any currency (e.g., EUR, SEK, CHF, USD, GBP, etc.). Each installation uses a single, consistent currency throughout all endpoints and responses.

Values are given in whole currency units, not in hundredth subunits: a value of 0.0003 in an installation configured for Euro means 0.0003 EUR/Wh (i.e. 0.30 EUR/kWh), never cents. The same applies to all totals (e.g. total_costs of 1.5 = 1.50 EUR).

Field names containing cost, price, revenue, tariff, or similar monetary terms (e.g., total_costs, electricity_price_per_wh, revenue_per_hour) represent amounts in the configured currency, without explicit currency designation in the field name to maintain currency-neutrality.

Deprecated Field Names

The genetic optimization API fields were renamed from German to English. For backward compatibility the old German field names (e.g. gesamtlast, pv_prognose_wh, Gesamtbilanz_Euro) are still accepted on input and are emitted in responses alongside the English names, marked as deprecated in the schema. They will be removed in a future release — new clients should use the English field names only.

Base URL: No base URL provided.

Endpoints:

POST /gesamtlast

Links: local, eos

Fastapi Gesamtlast

"""
Deprecated: Total Load Prediction with adjustment.

Endpoint to handle total load prediction adjusted by latest measured data.

Total load prediction starts at 00.00.00 today and is provided for 48 hours
in 1-hour intervals. If no prediction values are available the missing ones
at the start of the series are filled with the first available prediction value.

Note:
    Use '/v1/prediction/list?key=loadforecast_power_w' instead.
    Load energy meter readings to be added to EOS measurement by:
    '/v1/measurement/value' or
    '/v1/measurement/series' or
    '/v1/measurement/dataframe' or
    '/v1/measurement/data'
"""

Request Body:

  • application/json: { "$ref": "#/components/schemas/GesamtlastRequest" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /gesamtlast_simple

Links: local, eos

Fastapi Gesamtlast Simple

"""
Deprecated: Total Load Prediction.

Endpoint to handle total load prediction.

Total load prediction starts at 00.00.00 today and is provided for 48 hours
in 1-hour intervals. If no prediction values are available the missing ones
at the start of the series are filled with the first available prediction value.

Args:
    year_energy (float): Yearly energy consumption in Wh.

Note:
    Set LoadAkkudoktor as provider, then update data with
    '/v1/prediction/update'
    and then request data with
    '/v1/prediction/list?key=loadforecast_power_w' instead.
"""

Parameters:

  • year_energy (query, required): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

POST /optimize

Links: local, eos

Fastapi Optimize

"""
Deprecated: Optimize.

Endpoint to handle optimization.

Uses the `classic` GENETIC0 optimisation algorithm (__NO__ 15-minutes slots).

Note:
    Use automatic optimization instead.
    "v1/energy-management/optimization/solution/GENETIC0"
"""

Parameters:

  • start_hour (query, optional): Defaults to current hour of the day.

  • ngen (query, optional): Number of indivuals to generate for genetic algorithm.

Request Body:

  • application/json: { "$ref": "#/components/schemas/Genetic0OptimizationParameters-Input" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /pvforecast

Links: local, eos

Fastapi Pvforecast

"""
Deprecated: PV Forecast Prediction.

Endpoint to handle PV forecast prediction.

PVForecast starts at 00.00.00 today and is provided for 48 hours
in 1-hour intervals. If no forecast values are available the missing ones
at the start of the series are filled with the first available forecast value.

Note:
    Set PVForecastAkkudoktor as provider, then update data with
    '/v1/prediction/update'
    and then request data with
    '/v1/prediction/list?key=pvforecast_ac_power' and
    '/v1/prediction/list?key=pvforecastakkudoktor_temp_air' instead.
"""

Responses:

  • 200: Successful Response

GET /strompreis

Links: local, eos

Fastapi Strompreis

"""
Deprecated: Electricity Market Price Prediction per Wh [amount/Wh].

Electricity prices start at 00.00.00 today and are provided for 48 hours
in 1-hour intervals. If no prices are available the missing ones at the
start of the series are filled with the first available price.

Note:
    Electricity price charges are added.

Note:
    Set ElecPriceAkkudoktor as provider, then update data with
    '/v1/prediction/update'
    and then request data with
    '/v1/prediction/list?key=elecprice_marketprice_wh' or
    '/v1/prediction/list?key=elecprice_marketprice_kwh' instead.
"""

Responses:

  • 200: Successful Response

GET /v1/admin/cache

Links: local, eos

Fastapi Admin Cache Get

"""
Current cache management data.

Returns:
    data (dict): The management data.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/cache/clear

Links: local, eos

Fastapi Admin Cache Clear Post

"""
Clear the cache.

Deletes all cache files.

Returns:
    data (dict): The management data after cleanup.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/cache/clear-expired

Links: local, eos

Fastapi Admin Cache Clear Expired Post

"""
Clear the cache from expired data.

Deletes expired cache files.

Returns:
    data (dict): The management data after cleanup.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/cache/load

Links: local, eos

Fastapi Admin Cache Load Post

"""
Load cache management data.

Returns:
    data (dict): The management data that was loaded.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/cache/save

Links: local, eos

Fastapi Admin Cache Save Post

"""
Save the current cache management data.

Returns:
    data (dict): The management data that was saved.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/database/save

Links: local, eos

Fastapi Admin Database Save Post

"""
Save in memory data to database.

Returns:
    data (dict): The database stats after saving the records.
"""

Responses:

  • 200: Successful Response

GET /v1/admin/database/stats

Links: local, eos

Fastapi Admin Database Stats Get

"""
Get statistics from database.

Returns:
    data (dict): The database statistics
"""

Responses:

  • 200: Successful Response

POST /v1/admin/database/vacuum

Links: local, eos

Fastapi Admin Database Vacuum Post

"""
Remove old records from database.

Returns:
    data (dict): The database stats after removal of old records.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/server/restart

Links: local, eos

Fastapi Admin Server Restart Post

"""
Restart the server.

Restart EOS properly by starting a new instance before exiting the old one.
"""

Responses:

  • 200: Successful Response

POST /v1/admin/server/shutdown

Links: local, eos

Fastapi Admin Server Shutdown Post

"""
Shutdown the server.
"""

Responses:

  • 200: Successful Response

GET /v1/config

Links: local, eos

Fastapi Config Get

"""
Get the current configuration.

Returns:
    configuration (ConfigEOS): The current configuration.
"""

Responses:

  • 200: Successful Response

PUT /v1/config

Links: local, eos

Fastapi Config Put

"""
Update the current config with the provided settings.

Note that for any setting value that is None or unset, the configuration will fall back to
values from other sources such as environment variables, the EOS configuration file, or default
values.

Args:
    settings (SettingsEOS): The settings to write into the current settings.

Returns:
    configuration (ConfigEOS): The current configuration after the write.
"""

Request Body:

  • application/json: { "$ref": "#/components/schemas/SettingsEOS" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/config/backup

Links: local, eos

Fastapi Config Backup Get

"""
Get the EOS configuration backup identifiers and backup metadata.

Returns:
    dict[str, dict[str, Any]]: Mapping of backup identifiers to metadata.
"""

Responses:

  • 200: Successful Response

PUT /v1/config/file

Links: local, eos

Fastapi Config File Put

"""
Save the current configuration to the EOS configuration file.

Returns:
    configuration (ConfigEOS): The current configuration that was saved.
"""

Responses:

  • 200: Successful Response

POST /v1/config/reset

Links: local, eos

Fastapi Config Reset Post

"""
Reset the configuration to the EOS configuration file.

Returns:
    configuration (ConfigEOS): The current configuration after update.
"""

Responses:

  • 200: Successful Response

PUT /v1/config/revert

Links: local, eos

Fastapi Config Revert Put

"""
Revert the configuration to a EOS configuration backup.

Returns:
    configuration (ConfigEOS): The current configuration after revert.
"""

Parameters:

  • backup_id (query, required): EOS configuration backup ID.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/config/{path}

Links: local, eos

Fastapi Config Get Key

"""
Get the value of a nested key or index in the config model.

Args:
    path (str): The nested path to the key (e.g., "general/latitude" or "optimize/nested_list/0").

Returns:
    value (Any): The value of the selected nested key.
"""

Parameters:

  • path (path, required): The nested path to the configuration key (e.g., general/latitude).

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/config/{path}

Links: local, eos

Fastapi Config Put Key

"""
Update a nested key or index in the config model.

Args:
    path (str): The nested path to the key (e.g., "general/latitude" or "optimize/nested_list/0").
    value (Any): The new value to assign to the key or index at path.

Returns:
    configuration (ConfigEOS): The current configuration after the update.
"""

Parameters:

  • path (path, required): The nested path to the configuration key (e.g., general/latitude).

Request Body:

  • application/json: { "anyOf": [ {}, { "type": "null" } ], "description": "The value to assign to the specified configuration path (can be None).", "title": "Value" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/energy-management/optimization/solution

Links: local, eos

Fastapi Energy Management Optimization Solution Get

"""
Get the latest solution of the optimization.
"""

Responses:

  • 200: Successful Response

GET /v1/energy-management/optimization/solution/GENETIC/pdf

Links: local, eos

Fastapi Energy Management Optimization Solution Genetic Pdf Get

"""
Render the retained GENETIC result without rerunning optimization.

Rendering runs outside the event loop. Copy the result before offloading;
its recorded timestamp, interval and inputs own the report's time grid.
The legacy /visualization_results.pdf route continues to serve GENETIC0.
"""

Responses:

  • 200: Successful Response

GET /v1/energy-management/optimization/solution/{algorithm}

Links: local, eos

Fastapi Energy Management Optimization Solution Algorithm Get

"""
Get the latest algorithm specific solution of the optimization.

Args:
    algorithm: Optimization algorithm
"""

Parameters:

  • algorithm (path, required): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/energy-management/plan

Links: local, eos

Fastapi Energy Management Plan Get

"""
Get the latest energy management plan.
"""

Responses:

  • 200: Successful Response

GET /v1/health

Links: local, eos

Fastapi Health Get

"""
Health check endpoint to verify that the EOS server is alive.
"""

Responses:

  • 200: Successful Response

GET /v1/logging/log

Links: local, eos

Fastapi Logging Get Log

"""
Get structured log entries from the EOS log file.

Filters and returns log entries based on the specified query parameters. The log
file is expected to contain newline-delimited JSON entries.

Args:
    limit (int): Maximum number of entries to return.
    level (Optional[str]): Filter logs by severity level (e.g., DEBUG, INFO).
    contains (Optional[str]): Return only logs that include this string in the message.
    regex (Optional[str]): Return logs that match this regular expression in the message.
    from_time (Optional[str]): ISO 8601 timestamp to filter logs not older than this.
    to_time (Optional[str]): ISO 8601 timestamp to filter logs not newer than this.
    tail (bool): If True, fetch the most recent log entries (like `tail`).

Returns:
    JSONResponse: A JSON list of log entries.
"""

Parameters:

  • limit (query, optional): Maximum number of log entries to return.

  • level (query, optional): Filter by log level (e.g., INFO, ERROR).

  • contains (query, optional): Filter logs containing this substring.

  • regex (query, optional): Filter logs by matching regex in message.

  • from_time (query, optional): Start time (ISO format) for filtering logs.

  • to_time (query, optional): End time (ISO format) for filtering logs.

  • tail (query, optional): If True, returns the most recent lines (tail mode).

Responses:

  • 200: Successful Response

  • 422: Validation Error

POST /v1/measurement/battery-capacity/{battery_id}

Links: local, eos

Post Battery Capacity

"""
Estimate capacity from independent SoC anchors and configured DC power.

store_estimate writes the separate capacity_estimate config field in memory.
Persistence follows the regular EOS configuration save mechanism.
The active capacity_wh and raw measurements are never changed here.
"""

Parameters:

  • battery_id (path, required): No description provided.

Request Body:

  • application/json: { "$ref": "#/components/schemas/BatteryCapacityRequest" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/measurement/data

Links: local, eos

Fastapi Measurement Data Put

"""
Merge the measurement data given as datetime data into EOS measurements.
"""

Request Body:

  • application/json: { "$ref": "#/components/schemas/PydanticDateTimeData" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/measurement/dataframe

Links: local, eos

Fastapi Measurement Dataframe Put

"""
Merge the measurement data given as dataframe into EOS measurements.
"""

Request Body:

  • application/json: { "$ref": "#/components/schemas/PydanticDateTimeDataFrame" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/measurement/energy

Links: local, eos

Get Energy

"""
Energy in Wh, with temporal coverage and quality; no missing-to-zero filling.
"""

Parameters:

  • key (query, required): No description provided.

  • start (query, required): No description provided.

  • end (query, required): No description provided.

  • interval_seconds (query, optional): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/measurement/household

Links: local, eos

Get Household

"""
Site, household without EV, and base without separately measured devices.
"""

Parameters:

  • start (query, required): No description provided.

  • end (query, required): No description provided.

  • interval_seconds (query, optional): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/measurement/keys

Links: local, eos

Fastapi Measurement Keys Get

"""
Get a list of available measurement keys.
"""

Responses:

  • 200: Successful Response

DELETE /v1/measurement/range

Links: local, eos

Fastapi Measurement Range Delete

"""
Delete measurement values for a key within a datetime range.
"""

Parameters:

  • key (query, required): Measurement key.

  • start_datetime (query, optional): Start datetime.

  • end_datetime (query, optional): End datetime.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/measurement/samples

Links: local, eos

Get Samples

"""
Read raw samples including quality, in a bounded half-open range.
"""

Parameters:

  • key (query, required): No description provided.

  • start (query, required): No description provided.

  • end (query, required): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/measurement/samples

Links: local, eos

Put Samples

"""
Upsert raw values and their quality; legacy value/series payloads remain valid.
"""

Request Body:

  • application/json: { "type": "array", "items": { "$ref": "#/components/schemas/MeasurementSample" }, "maxItems": 10000, "title": "Samples" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/measurement/series

Links: local, eos

Fastapi Measurement Series Get

"""
Get measurements for given key within given date range as series.

Args:
    key (str): Measurement key
    start_datetime (Optional[str]): Starting datetime (inclusive).
        Defaults to datetime of first measurement.
    end_datetime (Optional[str]: Ending datetime (exclusive).
        Defaults to datetime after latest measurement.
    interval (Optional[str]): Time duration for each interval.
        Defaults to 1 hour.
    fill_method (str): Method to handle missing values during resampling.

        - 'linear': Linearly interpolate missing values (for numeric data only).
        - 'time': Interpolate missing values (for numeric data only).
        - 'ffill': Forward fill missing values.
        - 'bfill': Backward fill missing values.
        - Defaults to 'linear' for numeric values, otherwise 'ffill'.

    resample_method (str):
        Method used to aggregate values within a resampling interval.

        - "first": Use the first value in each interval.
        - "mean": Compute the arithmetic mean of all samples in each interval.
        - "interval_mean": Compute the time-weighted mean assuming each
            value remains valid until the next timestamp (piecewise-constant
            signal).

    dropna: (bool): Whether to drop NAN/ None values before processing.
        Defaults to True.
    boundary (Literal["strict", "context"]): resampling boundary
        "strict"  → only values inside [start, end)
        "context" → include one value before and after for proper resampling
    align_to_interval (bool): When True, snap the resample origin to the nearest
        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
        that bucket timestamps always fall on wall-clock-round times regardless of
        when ``start_datetime`` falls:

        - 15-minute interval → buckets on :00, :15, :30, :45
        - 1-hour interval    → buckets on the hour

        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
        no start is given), preserving the existing behaviour where buckets are
        aligned to the query window rather than the clock.

        Set to True when storing compacted records back to the database so that the
        resulting timestamps are predictable and human-readable.  Leave False for
        forecast or reporting queries where alignment to the exact query window is
        more important than clock-round boundaries.
    processing (SeriesProcessing):
        Processing mode for the returned series.

        - ``SeriesProcessing.RESAMPLED``: Return a processed series.
            Measurements are first filtered by ``start_datetime``,
            ``end_datetime``, and ``dropna``, then resampled according to
            ``interval`` and ``resample_method``, and finally missing values
            are filled using ``fill_method``.
        - ``SeriesProcessing.RAW``: Return the original measurement series.
            Measurements are filtered by ``start_datetime``,
            ``end_datetime``, and ``dropna`` only. No resampling or filling is
            performed, and ``interval``, ``fill_method``,
            ``resample_method``, ``boundary``, and
            ``align_to_interval`` are ignored.

        Defaults to ``SeriesProcessing.RAW``.

Returns:
    Series
"""

Parameters:

  • key (query, required): Measurement key.

  • start_datetime (query, optional): Starting datetime (inclusive).

  • end_datetime (query, optional): Ending datetime (exclusive).

  • interval (query, optional): Time duration for each interval. Defaults to 1 hour.

  • fill_method (query, optional): Method to handle missing values during resampling.

  • resample_method (query, optional): Method used to aggregate values within a resampling interval.

  • dropna (query, optional): Drop NAN/ None values before processing.

  • boundary (query, optional): Resampling boundary mode.

  • align_to_interval (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.

  • processing (query, optional): Processing mode. 'raw' returns original measurement data without resampling or filling.

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/measurement/series

Links: local, eos

Fastapi Measurement Series Put

"""
Merge measurement given as series into given key.
"""

Parameters:

  • key (query, required): Measurement key.

Request Body:

  • application/json: { "$ref": "#/components/schemas/PydanticDateTimeSeries" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/measurement/value

Links: local, eos

Fastapi Measurement Value Put

"""
Merge the measurement of given key and value into EOS measurements at given datetime.
"""

Parameters:

  • datetime (query, required): Datetime.

  • key (query, required): Measurement key.

  • value (query, required): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

POST /v1/optimize

Links: local, eos

Fastapi Optimize Config

"""
Optimize GENETIC using configured devices and optional fresh runtime inputs.

Static settings belong in configuration; query overrides are rejected.
Forecast arrays start at local
midnight and contain Wh per configured GENETIC slot; prices are currency/Wh.
An empty body uses configured providers and fresh measured states of charge.
The deprecated /optimize endpoint continues to run hourly GENETIC0.
"""

Request Body:

  • application/json: { "$ref": "#/components/schemas/ConfigOptimizationRequest" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/prediction/dataframe

Links: local, eos

Fastapi Prediction Dataframe Get

"""
Get prediction for given keys within given date range as dataframe.

Args:
    key (list[str]): Prediction keys
    start_datetime (Optional[str]): Starting datetime (inclusive).
        Defaults to start datetime of latest prediction.
    end_datetime (Optional[str]: Ending datetime (exclusive).
        Defaults to end datetime of latest prediction.
    interval (Optional[str]): Time duration for each interval.
        Defaults to 1 hour.
    fill_method (str): Method to handle missing values during resampling.

        - 'linear': Linearly interpolate missing values (for numeric data only).
        - 'time': Interpolate missing values (for numeric data only).
        - 'ffill': Forward fill missing values.
        - 'bfill': Backward fill missing values.
        - Defaults to 'linear' for numeric values, otherwise 'ffill'.

    resample_method (str):
        Method used to aggregate values within a resampling interval.

        - "first": Use the first value in each interval.
        - "mean": Compute the arithmetic mean of all samples in each interval.
        - "interval_mean": Compute the time-weighted mean assuming each
            value remains valid until the next timestamp (piecewise-constant
            signal).

    dropna: (bool): Whether to drop NAN/ None values before processing.
        Defaults to True.
    boundary (Literal["strict", "context"]): resampling boundary
        "strict"  → only values inside [start, end)
        "context" → include one value before and after for proper resampling
    align_to_interval (bool): When True, snap the resample origin to the nearest
        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
        that bucket timestamps always fall on wall-clock-round times regardless of
        when ``start_datetime`` falls:

        - 15-minute interval → buckets on :00, :15, :30, :45
        - 1-hour interval    → buckets on the hour

        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
        no start is given), preserving the existing behaviour where buckets are
        aligned to the query window rather than the clock.

        Set to True when storing compacted records back to the database so that the
        resulting timestamps are predictable and human-readable.  Leave False for
        forecast or reporting queries where alignment to the exact query window is
        more important than clock-round boundaries.
"""

Parameters:

  • keys (query, required): Prediction keys.

  • start_datetime (query, optional): Starting datetime (inclusive).

  • end_datetime (query, optional): Ending datetime (exclusive).

  • interval (query, optional): Time duration for each interval. Defaults to 1 hour.

  • fill_method (query, optional): Method to handle missing values during resampling.

  • resample_method (query, optional): Method used to aggregate values within a resampling interval.

  • dropna (query, optional): Drop NAN/ None values before processing.

  • boundary (query, optional): Resampling boundary mode.

  • align_to_interval (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/prediction/import/{provider_id}

Links: local, eos

Fastapi Prediction Import Provider

"""
Import prediction for given provider ID.

Args:
    provider_id: ID of provider to update.
    data: Prediction data.
    force_enable: Update data even if provider is disabled.
        Defaults to False.
"""

Parameters:

  • provider_id (path, required): Provider ID.

  • force_enable (query, optional): No description provided.

Request Body:

  • application/json: { "anyOf": [ { "$ref": "#/components/schemas/PydanticDateTimeDataFrame" }, { "$ref": "#/components/schemas/PydanticDateTimeData" }, { "type": "object", "additionalProperties": true }, { "type": "null" } ], "title": "Data" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/prediction/keys

Links: local, eos

Fastapi Prediction Keys Get

"""
Get a list of available prediction keys.
"""

Responses:

  • 200: Successful Response

GET /v1/prediction/list

Links: local, eos

Fastapi Prediction List Get

"""
Get prediction for given key within given date range as value list.

Args:
    key (str): Prediction key
    start_datetime (Optional[str]): Starting datetime (inclusive).
        Defaults to start datetime of latest prediction.
    end_datetime (Optional[str]: Ending datetime (exclusive).
        Defaults to end datetime of latest prediction.
    interval (Optional[str]): Time duration for each interval.
        Defaults to 1 hour.
    fill_method (str): Method to handle missing values during resampling.

        - 'linear': Linearly interpolate missing values (for numeric data only).
        - 'time': Interpolate missing values (for numeric data only).
        - 'ffill': Forward fill missing values.
        - 'bfill': Backward fill missing values.
        - Defaults to 'linear' for numeric values, otherwise 'ffill'.

    resample_method (str):
        Method used to aggregate values within a resampling interval.

        - "first": Use the first value in each interval.
        - "mean": Compute the arithmetic mean of all samples in each interval.
        - "interval_mean": Compute the time-weighted mean assuming each
            value remains valid until the next timestamp (piecewise-constant
            signal).

    dropna: (bool): Whether to drop NAN/ None values before processing.
        Defaults to True.
    boundary (Literal["strict", "context"]): resampling boundary
        "strict"  → only values inside [start, end)
        "context" → include one value before and after for proper resampling
    align_to_interval (bool): When True, snap the resample origin to the nearest
        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
        that bucket timestamps always fall on wall-clock-round times regardless of
        when ``start_datetime`` falls:

        - 15-minute interval → buckets on :00, :15, :30, :45
        - 1-hour interval    → buckets on the hour

        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
        no start is given), preserving the existing behaviour where buckets are
        aligned to the query window rather than the clock.

        Set to True when storing compacted records back to the database so that the
        resulting timestamps are predictable and human-readable.  Leave False for
        forecast or reporting queries where alignment to the exact query window is
        more important than clock-round boundaries.
"""

Parameters:

  • key (query, required): Prediction key.

  • start_datetime (query, optional): Starting datetime (inclusive).

  • end_datetime (query, optional): Ending datetime (exclusive).

  • interval (query, optional): Time duration for each interval. Defaults to 1 hour.

  • fill_method (query, optional): Method to handle missing values during resampling.

  • resample_method (query, optional): Method used to aggregate values within a resampling interval.

  • dropna (query, optional): Drop NAN/ None values before processing.

  • boundary (query, optional): Resampling boundary mode.

  • align_to_interval (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/prediction/providers

Links: local, eos

Fastapi Prediction Providers Get

"""
Get a list of available prediction providers.

Args:
    enabled (bool): Return enabled/disabled providers. If unset, return all providers.
"""

Parameters:

  • enabled (query, optional): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/prediction/pvforecast/pvlib/inverters

Links: local, eos

Fastapi Prediction Pvforecast Inverters Get

"""
Get inverter names supported by PVForecast PVLib provider.
"""

Responses:

  • 200: Successful Response

GET /v1/prediction/pvforecast/pvlib/modules

Links: local, eos

Fastapi Prediction Pvforecast Modules Get

"""
Get module names supported by PVForecast PVLib provider.
"""

Responses:

  • 200: Successful Response

DELETE /v1/prediction/range

Links: local, eos

Fastapi Prediction Range Delete

"""
Delete prediction values for a key within a datetime range.
"""

Parameters:

  • key (query, required): Prediction key.

  • start_datetime (query, optional): Start datetime.

  • end_datetime (query, optional): End datetime.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/prediction/series

Links: local, eos

Fastapi Prediction Series Get

"""
Get prediction for given key within given date range as series.

Args:
    key (str): Prediction key
    start_datetime (Optional[str]): Starting datetime (inclusive).
        Defaults to start datetime of latest prediction.
    end_datetime (Optional[str]: Ending datetime (exclusive).
        Defaults to end datetime of latest prediction.
    interval (Optional[str]): Time duration for each interval.
        Defaults to 1 hour.
    fill_method (str): Method to handle missing values during resampling.

        - 'linear': Linearly interpolate missing values (for numeric data only).
        - 'time': Interpolate missing values (for numeric data only).
        - 'ffill': Forward fill missing values.
        - 'bfill': Backward fill missing values.
        - Defaults to 'linear' for numeric values, otherwise 'ffill'.

    resample_method (str):
        Method used to aggregate values within a resampling interval.

        - "first": Use the first value in each interval.
        - "mean": Compute the arithmetic mean of all samples in each interval.
        - "interval_mean": Compute the time-weighted mean assuming each
            value remains valid until the next timestamp (piecewise-constant
            signal).

    dropna: (bool): Whether to drop NAN/ None values before processing.
        Defaults to True.
    boundary (Literal["strict", "context"]): resampling boundary
        "strict"  → only values inside [start, end)
        "context" → include one value before and after for proper resampling
    align_to_interval (bool): When True, snap the resample origin to the nearest
        UTC epoch-aligned boundary of ``interval`` before resampling.  This ensures
        that bucket timestamps always fall on wall-clock-round times regardless of
        when ``start_datetime`` falls:

        - 15-minute interval → buckets on :00, :15, :30, :45
        - 1-hour interval    → buckets on the hour

        When False (default), the origin is ``query_start`` (or ``"start_day"`` when
        no start is given), preserving the existing behaviour where buckets are
        aligned to the query window rather than the clock.

        Set to True when storing compacted records back to the database so that the
        resulting timestamps are predictable and human-readable.  Leave False for
        forecast or reporting queries where alignment to the exact query window is
        more important than clock-round boundaries.
    processing (SeriesProcessing):
        Processing mode for the returned series.

        - ``SeriesProcessing.RESAMPLED``: Return a processed series.
            Measurements are first filtered by ``start_datetime``,
            ``end_datetime``, and ``dropna``, then resampled according to
            ``interval`` and ``resample_method``, and finally missing values
            are filled using ``fill_method``.
        - ``SeriesProcessing.RAW``: Return the original measurement series.
            Measurements are filtered by ``start_datetime``,
            ``end_datetime``, and ``dropna`` only. No resampling or filling is
            performed, and ``interval``, ``fill_method``,
            ``resample_method``, ``boundary``, and
            ``align_to_interval`` are ignored.

        Defaults to ``SeriesProcessing.RAW``.

Returns:
    Array
"""

Parameters:

  • key (query, required): Prediction key.

  • start_datetime (query, optional): Starting datetime (inclusive).

  • end_datetime (query, optional): Ending datetime (exclusive).

  • interval (query, optional): Time duration for each interval. Defaults to 1 hour.

  • fill_method (query, optional): Method to handle missing values during resampling.

  • resample_method (query, optional): Method used to aggregate values within a resampling interval.

  • dropna (query, optional): Drop NAN/ None values before processing.

  • boundary (query, optional): Resampling boundary mode.

  • align_to_interval (query, optional): Snap resample origin to the nearest UTC epoch-aligned boundary of interval.

  • processing (query, optional): Processing mode. 'raw' returns original measurement data without resampling or filling.

Responses:

  • 200: Successful Response

  • 422: Validation Error

POST /v1/prediction/update

Links: local, eos

Fastapi Prediction Update

"""
Update predictions for all providers.

Args:
    force_update: Update data even if it is already cached.
        Defaults to False.
    force_enable: Update data even if provider is disabled.
        Defaults to False.
"""

Parameters:

  • force_update (query, optional): No description provided.

  • force_enable (query, optional): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

POST /v1/prediction/update/{provider_id}

Links: local, eos

Fastapi Prediction Update Provider

"""
Update predictions for given provider ID.

Args:
    provider_id: ID of provider to update.
    force_update: Update data even if it is already cached.
        Defaults to False.
    force_enable: Update data even if provider is disabled.
        Defaults to False.
"""

Parameters:

  • provider_id (path, required): No description provided.

  • force_update (query, optional): No description provided.

  • force_enable (query, optional): No description provided.

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /v1/resource/status

Links: local, eos

Fastapi Devices Status Get

"""
Get the latest status of a resource/ device.

Return:
    latest_status: The latest status of a resource/ device.
"""

Parameters:

  • resource_id (query, required): Resource ID.

  • actuator_id (query, optional): Actuator ID.

Responses:

  • 200: Successful Response

  • 422: Validation Error

PUT /v1/resource/status

Links: local, eos

Fastapi Devices Status Put

"""
Update the status of a resource/ device.

Return:
    latest_status: The latest status of a resource/ device.
"""

Parameters:

  • resource_id (query, required): Resource ID.

  • actuator_id (query, optional): Actuator ID.

Request Body:

  • application/json: { "anyOf": [ { "$ref": "#/components/schemas/PowerMeasurement" }, { "$ref": "#/components/schemas/EnergyMeasurement" }, { "$ref": "#/components/schemas/PPBCPowerProfileStatus" }, { "$ref": "#/components/schemas/OMBCStatus" }, { "$ref": "#/components/schemas/FRBCActuatorStatus" }, { "$ref": "#/components/schemas/FRBCEnergyStatus" }, { "$ref": "#/components/schemas/FRBCStorageStatus" }, { "$ref": "#/components/schemas/FRBCTimerStatus" }, { "$ref": "#/components/schemas/DDBCActuatorStatus" } ], "description": "Resource Status.", "title": "Status" }

Responses:

  • 200: Successful Response

  • 422: Validation Error

GET /visualization_results.pdf

Links: local, eos

Get Pdf

Responses:

  • 200: Successful Response

Auto generated from openapi.json.

Reference in New Issue View Git Blame Copy Permalink