# Writing a function for the BlueGrid platform: instructions for a coding assistant You are writing a function that the BlueGrid forecasting platform runs when someone calls it: a **model** (a forecast of a series) or an **indicator** (a figure computed from series). It is Python, in a folder whose `main.py` holds exactly one function marked `@bff.model(...)` or `@bff.indicator(...)`. The platform calls it with a period, a cut-off and parameters; it reads the data it needs through the SDK, `bff`, and returns an answer. This file is all you need. Its rules use MUST and MUST NOT; follow them exactly. ## The contract A call gives: - `call.start`, `call.end`: the period to answer, `[start, end)`, pandas Timestamps in UTC. - `call.as_of`: the cut-off, a Timestamp in UTC. The function answers as at that moment; reads see nothing known after it. - `call.parameters`: a dict of every declared parameter, defaults filled in. - `call.rng`: a `numpy.random.Generator`, seeded by the code and the call. - `call.log`: a `logging.Logger`. A call's log holds what it writes, and every `print`, warning and traceback, up to 64 KiB a call. The owner reads the logs of their own calls and of the checks; an operator, any. The function returns `call.answer(name=bff.values(series, **columns), ...)`. Rules: 1. The folder MUST have `main.py` (or one `.py` file at its top) holding exactly one decorated function. Other modules in the folder may be imported by name; data files may be read relative to `main.py`. 2. Every parameter MUST have a default. A call with no parameters answers. 3. The declaration MUST have at least one example, at most 4. Each example MUST answer on the platform's data within the time declared: the checks run each one twice, in two workers. The time is the call's own: the wait for a worker and the loading of the code are not counted. 4. The answer MUST hold every declared output and no other. Each output's index MUST be UTC times, sorted, unique, within `[call.start, call.end)`. Values MUST be finite floats or NaN. Each declared column MUST be given, as long as its output. At most 200,000 values in all. 5. The function MUST read data only through `call.series`, `call.read`, `call.catalog` and `call.indicator`. It MUST NOT open other network connections, except to the hosts it declares in `hosts=[...]`, over HTTPS. 6. A function that declares no host MUST answer the same call the same way, bit for bit. It MUST draw random numbers from `call.rng`. It MUST NOT read the clock (`datetime.now()`, `time.time()`), the process id, or anything else that changes between runs, nor depend on a set's order. 7. It MUST NOT keep anything between calls: each call runs in a fresh copy of the loaded module, and the folder is closed to writing. Module-level code runs once, at load, within 120 seconds, with the function's variables and without a call: it MAY read files of the folder, read `os.environ` and build tables; it MUST NOT read the platform's data (it has no token), start a thread or a process, or open a connection. A model that must be trained on the platform's data is trained inside the call, each time. A loaded function serves one caller and stays warm for ten idle minutes: another caller's first call loads it again. 8. It MUST import only the standard library, the runtime's promised libraries (listed below), the SDK `bff`, and its own modules. What those libraries bring with them can be imported too, and is not promised: a patch of the runtime may change or drop one, so do not build on it. matplotlib is for notebooks alone: `main.py`, and the modules it imports, MUST NOT import it. `bff-sdk check` and `bff-sdk push` refuse such an import, by file and line. 9. A model MUST finish within 60 seconds, an indicator within 5; `time="20s"` declares less. Memory is 2 GiB and one processor: the platform holds each library to one thread (`OMP_NUM_THREADS=1`), and code SHOULD NOT ask for more (LightGBM's `n_jobs` is left alone, or 1). Files MAY be written only under the folder in the environment variable `BFF_SCRATCH` (512 MiB, in memory, emptied at each call; `HOME` and `TMPDIR` are the same folder). A call that writes anywhere else fails with `model_failed`. 10. Secrets MUST come from environment variables the declaration names in `env=[...]`, read with `os.environ`. A name is `[A-Z][A-Z0-9_]*`, at most 64 characters, and not one the platform sets: `PATH`, `HOME`, `USER`, `SHELL`, `TMPDIR`, `TZ`, `LANG`, `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, `SSL_CERT_FILE`, `SSL_CERT_DIR`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `MALLOC_CONF`, `JE_ARROW_MALLOC_CONF`, nor any that begins `LC_`, `PYTHON`, `LD_`, `OMP_`, `OPENBLAS_`, `MKL_`, `NUMEXPR_` or `BFF_`. A secret MUST NOT be written in the code, nor logged, nor put in an exception's message. 11. A call MAY make at most 20 reads and be given at most 400,000 values; one read at most 20 series and 200,000 values. 12. Names of parameters, outputs and columns MUST match `[a-z][a-z0-9_]*`, at most 32 characters. Series names are dotted, such as `epf.price`. 13. A function SHOULD fail loudly: raise an exception with a clear message when it cannot answer at all, for instance when a series it needs does not exist. The caller sees `model_failed`, the run's id and the exception's first line, up to 500 characters: so the message MUST say what is wrong and MUST NOT hold a secret or another person's data. The traceback is in the log, which the caller cannot read. 14. A function MUST answer the caller's whole period, whatever its length. It MUST NOT raise because the period is long or lies beyond the cut-off. A screen asks for the period its chart shows and gives the chart's moment as the cut-off. Times that cannot be known at the cut-off MUST be NaN or left out. If the whole period would take longer than the declared time, the function MUST compute what it can, leave out the rest and say in `call.log` what it left out. 15. A function MUST handle data by the hour and by the quarter-hour (ENTSO-E's day-ahead prices for Germany have come in quarter-hours since October 2025). It SHOULD answer at the data's step, taken from the data it reads, as the examples' `step_of` does, not assume `"PT1H"`. A model built on hours, such as LEAR, MUST say so in its description and MUST read quarter-hours as each hour's mean, not as the hour's first quarter. ## The SDK ```text import bff # Marking the function (one per module) @bff.model(*, title, description=None, parameters=None, outputs=None, card=None, examples=None, hosts=None, env=None, runtime=None, time=None) @bff.indicator(*, title, description=None, parameters=None, outputs=None, examples=None, hosts=None, env=None, runtime=None, time=None) # title: text; parameters: {name: parameter}; outputs: {name: bff.output(...)}; # examples: [bff.example(...)]; hosts: exact host names; env: variable names; # runtime: "python-1", the newest if absent; time: "20s", at most 60s / 5s. # Parameters: each with a default bff.integer(default, minimum, maximum, *, description=None) # range required bff.number(default, minimum, maximum, *, description=None) # finite, range required bff.choice(default, choices, *, description=None) # 2 to 32 strings bff.text(default, max_length=200, *, description=None) bff.series(default, *, unit=None, description=None) # a series name; unit filters # what a caller is offered # Outputs bff.output(unit, quantiles=(), columns=(), *, description=None) # quantiles: levels in (0, 1); each becomes a column "q" + its digits: # 0.1 -> "q10", 0.5 -> "q50", 0.975 -> "q975". columns: other names. bff.card(*, market=None, product=None, horizon=None, target=None, tested=None) # models only bff.example(start, end, as_of, parameters=None) # times with offsets, as "2017-03-01T23:00:00Z" # The call call.series(name, since=None, until=None) -> pandas.Series # floats by UTC valid time, as known at the cut-off; since defaults to start, # until to end (left out); a value not a number is NaN; nothing known: empty. call.read(names, since=None, until=None) -> pandas.DataFrame # columns valid_at, name, value, known_at call.catalog(market=None, product=None, source=None, q=None) -> pandas.DataFrame # columns name, kind, unit, description, market, product, source, # first_valid_at, last_valid_at, latest_known_at: the series it may read call.indicator(id, version, inputs, parameters=None, since=None, until=None) -> dict[str, pandas.DataFrame] # a platform indicator's outputs, each with value # and its columns, by valid time call.grid(step, zone="Europe/Berlin") -> pandas.DatetimeIndex # the valid times from start to end by an ISO 8601 step ("PT1H", "PT15M", "P1D"); # a day's step counts the market's days: 23 or 25 hours when the clocks change call.answer(**outputs) -> bff.Answer bff.values(series, **columns) -> bff.Values # series: a pandas Series by UTC time; a column given as a Series is aligned # to it by time, any other sequence taken in order # Errors bff.ReadRefused # a read the platform refused: .code, .message, .status, .details bff.DeclarationError # a declaration that breaks a rule, raised at import bff.InvalidAnswer # an answer that breaks the declaration ``` The market's days are Berlin's: a day starts at 00:00 Europe/Berlin, which is 23:00 UTC in winter and 22:00 UTC in summer. Day-ahead prices for a day are known at about 12:45 Berlin time the day before; forecasts of load and renewables at 09:00. ## The manifest's schema The SDK writes this from the declaration; the platform validates it. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://bff.invalid/contracts/function-manifest.schema.json", "title": "The manifest of a person's function", "description": "What the SDK writes, in the sandbox, from a function's declaration (@bff.model or @bff.indicator); the read API validates every field again and stores it with the version. Version 1 of the SDK.", "type": "object", "additionalProperties": false, "required": ["sdk", "kind", "entry", "title", "parameters", "outputs", "examples"], "properties": { "sdk": {"const": 1, "description": "The SDK's major version the function was written for"}, "kind": {"enum": ["model", "indicator"]}, "entry": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Za-z_][A-Za-z0-9_]*$", "maxLength": 200, "description": "module:function, as imported from the upload's root", "examples": ["main:forecast"] }, "title": {"type": "string", "minLength": 1, "maxLength": 200}, "description": {"type": "string", "maxLength": 2000}, "parameters": { "type": "object", "maxProperties": 16, "propertyNames": {"$ref": "#/$defs/name"}, "additionalProperties": {"$ref": "#/$defs/parameter"} }, "outputs": { "type": "object", "minProperties": 1, "maxProperties": 8, "propertyNames": {"$ref": "#/$defs/name"}, "additionalProperties": {"$ref": "#/$defs/output"} }, "card": {"$ref": "#/$defs/card"}, "examples": { "type": "array", "minItems": 1, "maxItems": 4, "items": {"$ref": "#/$defs/example"} }, "hosts": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "maxLength": 253, "pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$", "description": "An exact host name, reached on port 443 over HTTPS; no wildcards" } }, "env": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,63}$"}, "description": "The environment variables the function needs; the read API refuses the platform's own names" }, "runtime": { "type": ["string", "null"], "pattern": "^[a-z][a-z0-9-]{0,31}$", "description": "The runtime the function names; null for the newest" }, "time_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "description": "Its time limit per call; at most 60 for a model and 5 for an indicator, which the read API checks; absent for the kind's maximum" } }, "$defs": { "name": {"type": "string", "pattern": "^[a-z][a-z0-9_]{0,31}$"}, "parameter": { "type": "object", "required": ["type", "default"], "properties": { "type": {"enum": ["integer", "number", "choice", "text", "series"]}, "default": {}, "minimum": {"type": "number"}, "maximum": {"type": "number"}, "choices": {"type": "array", "minItems": 2, "maxItems": 32, "uniqueItems": true, "items": {"type": "string", "minLength": 1, "maxLength": 100}}, "max_length": {"type": "integer", "minimum": 1, "maximum": 2000}, "unit": {"type": "string", "maxLength": 50}, "description": {"type": "string", "maxLength": 500} }, "additionalProperties": false, "allOf": [ {"if": {"properties": {"type": {"const": "integer"}}}, "then": {"required": ["minimum", "maximum"], "properties": {"default": {"type": "integer"}, "minimum": {"type": "integer"}, "maximum": {"type": "integer"}}}}, {"if": {"properties": {"type": {"const": "number"}}}, "then": {"required": ["minimum", "maximum"], "properties": {"default": {"type": "number"}}}}, {"if": {"properties": {"type": {"const": "choice"}}}, "then": {"required": ["choices"], "properties": {"default": {"type": "string"}}}}, {"if": {"properties": {"type": {"const": "text"}}}, "then": {"properties": {"default": {"type": "string"}}}}, {"if": {"properties": {"type": {"const": "series"}}}, "then": {"properties": {"default": {"type": "string", "minLength": 1, "maxLength": 200}}}} ] }, "output": { "type": "object", "required": ["unit"], "additionalProperties": false, "properties": { "unit": {"type": "string", "minLength": 1, "maxLength": 50}, "quantiles": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": {"type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1}, "description": "Each level becomes a column named q followed by its digits: 0.1 is q10, 0.975 is q975" }, "columns": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": {"$ref": "#/$defs/name"}, "description": "Columns besides the quantiles' (at most 16 in all)" }, "description": {"type": "string", "maxLength": 500} } }, "card": { "type": "object", "additionalProperties": false, "properties": { "market": {"type": "string", "maxLength": 50}, "product": {"type": "string", "maxLength": 50}, "horizon": {"type": "string", "maxLength": 20, "description": "An ISO 8601 duration, such as P1D"}, "target": {"type": "string", "maxLength": 200, "description": "What it forecasts: a parameter's name, or a series"}, "tested": {"type": "string", "maxLength": 2000} } }, "example": { "type": "object", "required": ["start", "end", "as_of"], "additionalProperties": false, "properties": { "start": {"type": "string", "format": "date-time"}, "end": {"type": "string", "format": "date-time"}, "as_of": {"type": "string", "format": "date-time"}, "parameters": {"type": "object"} } } } } ``` ## The runtime python-1 CPython 3.14 on Linux. These libraries are promised, at these versions, which a runtime never changes. A runtime may gain a library that moves none already there: LightGBM joined in 3.2.15. What they bring with them (the guide lists each, with its version) can be imported and is not promised: ```text numpy==2.5.5 pandas==3.1.1 pyarrow==26.0.1 scipy==1.18.1 scikit-learn==1.9.1 lightgbm==4.7.0 statsmodels==0.15.0 joblib==1.6.0 httpx==0.28.1 anthropic==2.8.0 openai==3.51.0 ``` ## A whole model: naive `main.py`: ```python """The naive benchmark of electricity price forecasting, as epftoolbox has it. Tuesday to Friday repeat the day before; Monday, Saturday and Sunday repeat the same day a week before, since the day before them differs in kind. It follows the series' own step, an hour or a quarter-hour: each value moves 24 hours ahead, or a week, on the market's clock, so a day the clocks change copies what it can, and the time that did not exist on the day copied is empty. It answers the whole period it is asked for: a day whose day before is not known at the cut-off is empty. """ import numpy as np import pandas as pd import bff ZONE = "Europe/Berlin" WEEKLY = (0, 5, 6) # Monday, Saturday and Sunday, Monday being 0 @bff.model( title="Naive", description="The day before on Tuesday to Friday; the week before on Monday, Saturday " "and Sunday. The benchmark a forecast must beat.", parameters={ "series": bff.series( default="epf.price", unit="EUR/MWh", description="The prices to repeat" ) }, outputs={"forecast": bff.output(unit="EUR/MWh")}, card=bff.card(market="DE-LU", product="day-ahead", horizon="P1D", target="epf.price"), examples=[ bff.example( start="2017-03-01T23:00:00Z", end="2017-03-02T23:00:00Z", as_of="2017-03-01T09:00:00Z" ) ], time="10s", ) def forecast(call: bff.Call) -> bff.Answer: known = call.series( call.parameters["series"], since=call.start - pd.Timedelta(days=7), until=call.end - pd.Timedelta(days=1), ) # Each time of the period, at the series' own step. grid = call.grid(step_of(known)) local = grid.tz_convert(ZONE) back = np.where(np.isin(local.day_of_week, WEEKLY), 7, 1) # The same moment on the market's clock, a day or a week before. wall = local.tz_localize(None) - pd.to_timedelta(back, unit="D") past = wall.tz_localize(ZONE, ambiguous=True, nonexistent="NaT").tz_convert("UTC") return call.answer(forecast=bff.values(pd.Series(known.reindex(past).to_numpy(), index=grid))) def step_of(known: pd.Series) -> str: """The series' own step, as an ISO 8601 duration: the most common gap between its values, an hour or a quarter-hour; an hour when there are too few to tell.""" gaps = known.index.to_series().diff().dropna() gaps = gaps[gaps > pd.Timedelta(0)] if gaps.empty: return "PT1H" seconds = int(gaps.mode().iloc[0].total_seconds()) return f"PT{seconds // 3600}H" if seconds % 3600 == 0 else f"PT{seconds // 60}M" ``` ## A model that reads a platform indicator: smoothed_naive `call.indicator` reads one of the platform's indicators (`GET /v1/indicators` lists them) as known at the cut-off, as every read is: ask for it over the period you need, and use the last value it gives, never a later one. ```python """The naive forecast, pulled toward the week's mean: a model that reads a platform indicator. Each value, at the series' own step (an hour or a quarter-hour), starts from the naive forecast (the day before on Tuesday to Friday, the week before on Monday, Saturday and Sunday) and moves `pull` of the way toward the latest weekly mean known at the cut-off: the platform's own rolling mean of a week of prices (`rolling-mean`, version 2: 168 hourly or 672 quarter-hourly values). The indicator is read through `call.indicator`, as every read is, as known at the call's cut-off: it is asked for over the whole period, and gives only what was known. """ import numpy as np import pandas as pd import bff ZONE = "Europe/Berlin" WEEKLY = (0, 5, 6) # Monday, Saturday and Sunday, Monday being 0 WEEK = pd.Timedelta(days=7) @bff.model( title="Smoothed naive", description="The naive forecast, moved part of the way toward the latest weekly mean " "of prices known at the cut-off, the platform's rolling-mean indicator.", parameters={ "series": bff.series(default="epf.price", unit="EUR/MWh", description="The prices"), "pull": bff.number( default=0.5, minimum=0.0, maximum=1.0, description="How far toward the week's mean: 0 is the naive forecast, 1 the mean", ), }, outputs={"forecast": bff.output(unit="EUR/MWh")}, card=bff.card(market="DE-LU", product="day-ahead", horizon="P1D", target="epf.price"), examples=[ bff.example( start="2017-03-01T23:00:00Z", end="2017-03-02T23:00:00Z", as_of="2017-03-01T09:00:00Z" ) ], time="10s", ) def forecast(call: bff.Call) -> bff.Answer: series, pull = call.parameters["series"], call.parameters["pull"] known = call.series( series, since=call.start - pd.Timedelta(days=7), until=call.end - pd.Timedelta(days=1) ) # Each time of the period, at the series' own step, an hour or a quarter-hour. step = step_of(known) grid = call.grid(step) local = grid.tz_convert(ZONE) back = np.where(np.isin(local.day_of_week, WEEKLY), 7, 1) # The same moment on the market's clock, a day or a week before. wall = local.tz_localize(None) - pd.to_timedelta(back, unit="D") past = wall.tz_localize(ZONE, ambiguous=True, nonexistent="NaT").tz_convert("UTC") naive = pd.Series(known.reindex(past).to_numpy(), index=grid) # The weekly mean up to the day's end, as known at the cut-off: its last value # is the latest mean anyone could have computed then. means = call.indicator( "rolling-mean", "2", {"series": series}, parameters={"window": int(WEEK / pd.Timedelta(step))}, since=call.start - pd.Timedelta(days=2), until=call.end, )["mean"] latest = means["value"].dropna() week = latest.iloc[-1] if len(latest) else np.nan return call.answer(forecast=bff.values((1 - pull) * naive + pull * week)) def step_of(known: pd.Series) -> str: """The series' own step, as an ISO 8601 duration: the most common gap between its values, an hour or a quarter-hour; an hour when there are too few to tell.""" gaps = known.index.to_series().diff().dropna() gaps = gaps[gaps > pd.Timedelta(0)] if gaps.empty: return "PT1H" seconds = int(gaps.mode().iloc[0].total_seconds()) return f"PT{seconds // 3600}H" if seconds % 3600 == 0 else f"PT{seconds // 60}M" ``` ## A whole model: lear A folder of two files. `main.py`: ```python """LEAR, epftoolbox's Lasso model of day-ahead prices, as a model on the platform. The port is lear.py, beside this file; README.md says how it is held to epftoolbox. AGPL-3.0, as epftoolbox's files: see LICENSE. """ import bff import lear @bff.model( title="LEAR", description="epftoolbox's LEAR: a Lasso model for each hour of the day, its penalty " "chosen by AIC, on the prices of the days before and the forecasts of load and " "renewables; learnt again for each day. Hourly: quarter-hours count as their " "hour's mean. Of a longer period, its latest days: 8 at most, 3 at 1,092 days " "of window. Given another source's prices alone, it reads that source's " "forecasts of load, solar and wind; a history shorter than its window gives the " "longest window it fills.", parameters={ "window": bff.choice( default="1092", choices=["56", "84", "1092", "1456"], description="The days it learns from", ), "series": bff.series(default="epf.price", unit="EUR/MWh", description="The prices"), "load": bff.series( default="epf.load_forecast", unit="MW", description="The forecast of load; left as it is, the forecast beside the prices", ), "renewables": bff.series( default="epf.renewables_forecast", unit="MW", description="The forecast of wind and solar; left as it is, " "the forecasts beside the prices, summed", ), }, outputs={"forecast": bff.output(unit="EUR/MWh")}, card=bff.card( market="DE-LU", product="day-ahead", horizon="P1D", target="epf.price", tested="Held to epftoolbox's own code at commit 47d6e06 on eight days of " "2016 and 2017, and to its published forecasts for Germany.", ), examples=[ bff.example( start="2017-03-01T23:00:00Z", end="2017-03-02T23:00:00Z", as_of="2017-03-01T09:00:00Z" ) ], time="60s", ) def forecast(call: bff.Call) -> bff.Answer: return lear.answer(call, windows=[int(call.parameters["window"])], most_days=8) ``` `lear.py`, beside it: ```python """LEAR, the Lasso Estimated AutoRegressive model of electricity prices. Ported from epftoolbox, by Jesus Lago: epftoolbox/models/_lear.py and epftoolbox/data/_wrangling.py at commit 47d6e0629f65ebd19d3c12cb5689dbad0c2ea078 (https://github.com/jeslago/epftoolbox). Those files are under the GNU Affero General Public License, version 3, and so is this one: see LICENSE beside it. Lago, Marcjasz, De Schutter and Weron, "Forecasting day-ahead electricity prices: A review of state-of-the-art algorithms, best practices and an open-access benchmark", Applied Energy 293 (2021). What changed, on 2026-11-16, for the BlueGrid platform: - The features are built by indexing arrays of days by hours, not by looking times up in a frame: the same 247 features, in the same order. - statsmodels' `mad` is written out: the median absolute deviation over the normal distribution's third quartile, 0.6745. - scikit-learn has since removed `LassoLarsIC`'s `normalize` (1.2), and since 1.1 estimates the noise's variance itself, which it cannot when a window has fewer days than features. The port normalises the features as scikit-learn 0.2x did, and gives it the target's variance, as 0.2x used: the same penalty is chosen. - `Lasso` is given the Gram matrix (`precompute=True`): the same coordinate updates, about 2.5 times faster. And on 2026-11-17: - A column whose median absolute deviation is zero is scaled by its standard deviation, where epftoolbox divides by zero: a solar forecast alone, zero at night on most days. No column of epftoolbox's file is such, so its forecasts stand as they were. Checked against epftoolbox's own code, unchanged, on scikit-learn 0.23.2: see README.md and test_lear.py. """ from __future__ import annotations import warnings from collections.abc import Sequence import numpy as np import pandas as pd from sklearn.exceptions import ConvergenceWarning from sklearn.linear_model import Lasso, LassoLarsIC import bff #: The days before whose prices each hour learns from. PAST_PRICES = (1, 2, 3, 7) #: The days before whose forecasts of load and renewables it learns from, besides the day's own. PAST_FORECASTS = (1, 7) #: statsmodels' normalising constant for the median absolute deviation: the third quartile of #: the standard normal distribution. QUARTILE = 0.6744897501960817 #: Lasso's iterations, as epftoolbox has them. ITERATIONS = 2500 def features( price: np.ndarray, load: np.ndarray, renewables: np.ndarray, days: np.ndarray, weekday: np.ndarray, ) -> np.ndarray: """epftoolbox's features of each day in `days`: one row a day, 247 columns. The prices, the load and the renewables are arrays of days by 24 hours of the market's clock; `weekday` is each day's, Monday being 0. The columns: for each hour, the price of 1, 2, 3 and 7 days before; for each hour, the load and renewables forecasts of 1 and 7 days before, then the day's own; the weekday, as 7 columns of 0 or 1. """ columns = [] for hour in range(24): for back in PAST_PRICES: columns.append(price[days - back, hour]) for hour in range(24): for back in PAST_FORECASTS: for forecast in (load, renewables): columns.append(forecast[days - back, hour]) for forecast in (load, renewables): columns.append(forecast[days, hour]) for day in range(7): columns.append((weekday[days] == day).astype(float)) return np.column_stack(columns) class Invariant: """epftoolbox's "Invariant" scaling of each column: asinh of its distance from the median, in median absolute deviations.""" def __init__(self, data: np.ndarray) -> None: self.median = np.median(data, axis=0) self.mad = np.median(np.abs(data - self.median), axis=0) / QUARTILE # A column more than half of whose values are its median has a # median absolute deviation of zero: a solar forecast at night, zero # on most days of an autumn window. epftoolbox would divide by it. # Such a column is scaled by its standard deviation instead, so the # days it does differ on still count; one that never varies tells # nothing, and is left at zero. flat = self.mad == 0 if np.any(flat): spread = np.std(data, axis=0) self.mad = np.where(flat, np.where(spread > 0, spread, 1.0), self.mad) def transform(self, data: np.ndarray) -> np.ndarray: return np.arcsinh((data - self.median) / self.mad) def inverse(self, data: np.ndarray) -> np.ndarray: return np.sinh(data) * self.mad + self.median def _penalty(x: np.ndarray, y: np.ndarray) -> float: """The penalty LassoLarsIC chooses by AIC, as scikit-learn 0.2x chose it: on features centred and of unit length, with the target's variance as the noise's.""" centred = x - x.mean(axis=0) length = np.sqrt((centred**2).sum(axis=0)) length[length == 0] = 1.0 chooser = LassoLarsIC(criterion="aic", max_iter=ITERATIONS, noise_variance=float(np.var(y))) return float(chooser.fit(centred / length, y).alpha_) def forecast_day( price: np.ndarray, load: np.ndarray, renewables: np.ndarray, weekday: np.ndarray, day: int, window: int, ) -> np.ndarray: """The 24 prices of row `day`, learnt from the `window` days before it. As epftoolbox's `recalibrate_and_forecast_next_day`: the first week of the window gives only the past values of the days after it, so `window - 7` days are learnt from. Each hour has its own model: its penalty chosen by AIC, then a Lasso with it, on scaled features and prices. """ if day < window: raise ValueError(f"LEAR needs {window} days before the day it forecasts") learnt = np.arange(day - window + 7, day) x = features(price, load, renewables, learnt, weekday) asked = features(price, load, renewables, np.array([day]), weekday) prices = Invariant(price[learnt]) y = prices.transform(price[learnt]) # The weekday's 7 columns are not scaled. scale = Invariant(x[:, :-7]) x[:, :-7] = scale.transform(x[:, :-7]) asked[:, :-7] = scale.transform(asked[:, :-7]) found = np.zeros(24) with warnings.catch_warnings(): # As epftoolbox: Lasso stops at its iterations, converged or not. warnings.simplefilter("ignore", ConvergenceWarning) for hour in range(24): model = Lasso(alpha=_penalty(x, y[:, hour]), max_iter=ITERATIONS, precompute=True) found[hour] = model.fit(x, y[:, hour]).predict(asked)[0] return prices.inverse(found.reshape(1, -1))[0] # On the platform: the call's market days, its series by day and hour of the # market's clock, as epftoolbox's files hold them, and its answer. ZONE = "Europe/Berlin" #: The parameters that name the series LEAR reads. SERIES = ("series", "load", "renewables") def market_days(start: pd.Timestamp, end: pd.Timestamp) -> pd.DatetimeIndex: """The market's days that [start, end) touches: their midnights, in the market's zone.""" first = start.tz_convert(ZONE).normalize() last = (end - pd.Timedelta(microseconds=1)).tz_convert(ZONE).normalize() return pd.date_range(first, last, freq="D") def by_day_and_hour(series: pd.Series, first: pd.Timestamp, days: int) -> np.ndarray: """A series as `days` rows of 24 hours of the market's clock, from the midnight `first`. As epftoolbox's files: the hour the clocks skip in spring is the mean of the hours either side; of the hour they repeat in autumn, the first. An hour without a value is NaN. Quarter-hours count as their hour's mean: LEAR is a model of 24 hours. """ wall = series.index.tz_convert(ZONE).tz_localize(None) values = pd.Series(series.to_numpy(), index=wall) values = values[~values.index.duplicated(keep="first")] values = values.groupby(values.index.floor("h")).mean() hours = pd.date_range(first.tz_localize(None), periods=days * 24, freq="h") found = values.reindex(hours) skipped = hours.tz_localize(ZONE, ambiguous=True, nonexistent="NaT").isna() found[skipped] = ((found.shift(1) + found.shift(-1)) / 2)[skipped] return found.to_numpy(dtype="float64").reshape(days, 24) def _first_missing(name: str, rows: np.ndarray, first: pd.Timestamp, offset: int) -> str | None: """Where a series has no value, in words; None if it has every one.""" gaps = np.argwhere(np.isnan(rows)) if len(gaps) == 0: return None row, hour = gaps[0] when = first.tz_localize(None) + pd.Timedelta(days=int(offset + row), hours=int(hour)) return f"{name} has no value at {when:%Y-%m-%d %H:%M}, the market's time" #: epftoolbox's windows, the longest first: what a window falls back to. WINDOWS = (1456, 1092, 84, 56) #: What a call may learn, in days of window summed over the days it forecasts: #: a day at 1,092 days takes about 12 s on a shared processor, of the 60 s a #: model has. A count, not a clock: the same call answers the same days. BUDGET = 3_600 #: The series the declaration names for the forecasts, of the epftoolbox file. DECLARED = {"load": "epf.load_forecast", "renewables": "epf.renewables_forecast"} #: A source that has no forecast of renewables as one series has these, summed. PARTS = ("solar_forecast", "wind_onshore_forecast", "wind_offshore_forecast") def sources(parameters: dict) -> dict[str, list[str]]: """The series behind each input. Given another source's prices (`entsoe.de_lu_price`), with load and renewables left as declared, the source's own forecasts beside its prices are read: its `load_forecast`, and the sum of its solar and wind forecasts.""" price = parameters["series"] named = {name: [parameters[name]] for name in SERIES} beside = price[: -len("price")] if price.endswith("price") else None if beside is None or beside == "epf.": return named if parameters["load"] == DECLARED["load"]: named["load"] = [beside + "load_forecast"] if parameters["renewables"] == DECLARED["renewables"]: named["renewables"] = [beside + part for part in PARTS] return named def _nothing(call: bff.Call, why: str) -> bff.Answer: call.log.info(f"no day of the call could be forecast: {why}") return call.answer( forecast=bff.values(pd.Series([], index=pd.DatetimeIndex([], tz="UTC"), dtype="float64")) ) def answer(call: bff.Call, windows: Sequence[int], most_days: int) -> bff.Answer: """LEAR's forecast of each market day of the call, as the mean over `windows`. Each day is forecast as at its day before: learnt from the days before it, with the forecasts of load and renewables of the day itself. A day whose values are not all known at the call's cut-off is left out, and the log says why. A window longer than the series' history gives way to the longest of epftoolbox's windows that the history fills, and the log says which. The caller's period is never refused: of a longer one, the `most_days` latest days are forecast, within the function's time, and the log names the days left out. """ days = market_days(call.start, call.end) if len(days) > most_days: early = days[:-most_days] call.log.info( f"{len(early)} days left out, {early[0]:%Y-%m-%d} to {early[-1]:%Y-%m-%d}: " f"LEAR forecasts the {most_days} latest days of a call, in its time" ) days = days[-most_days:] named = sources(call.parameters) label = {name: " + ".join(series) for name, series in named.items()} until = (days[-1] + pd.DateOffset(days=1)).tz_convert("UTC") # The prices first, as far back as the longest window: how far they go # says how much of the forecasts is worth reading. asked = max(windows) far = days[0] - pd.DateOffset(days=asked) prices = by_day_and_hour( call.series(named["series"][0], since=far.tz_convert("UTC"), until=until), far, asked + len(days), ) held = np.argwhere(~np.isnan(prices).all(axis=1)) history = asked - int(held[0][0]) if len(held) else 0 fitting = [w for w in WINDOWS if w <= asked and w <= history] longest = fitting[0] if fitting else min(windows) # As many of the latest days as the windows in use leave time for. cost = sum(w for w in windows if w <= longest) or longest fit = max(1, BUDGET // cost) skipped = max(0, len(days) - fit) if skipped: call.log.info( f"{skipped} days left out, {days[0]:%Y-%m-%d} to {days[skipped - 1]:%Y-%m-%d}: " f"at {cost} days of window a day, LEAR forecasts the {fit} latest days of " "a call, in its time" ) days = days[skipped:] first = days[0] - pd.DateOffset(days=longest) rows = longest + len(days) read = {"series": prices[asked - longest + skipped :]} try: for name in ("load", "renewables"): read[name] = sum( by_day_and_hour( call.series(series, since=first.tz_convert("UTC"), until=until), first, rows ) for series in named[name] ) except bff.ReadRefused as refused: return _nothing( call, f"{label[name]} could not be read ({refused.code}): " "name the forecasts of load and renewables to use", ) weekday = pd.date_range(first.tz_localize(None), periods=rows, freq="D").day_of_week.to_numpy() def missing(row: int, window: int) -> str | None: # The prices of the days before; the forecasts of those days and of the day itself. return _first_missing( label["series"], read["series"][row - window : row], first, row - window ) or next( ( why for name in ("load", "renewables") if ( why := _first_missing( label[name], read[name][row - window : row + 1], first, row - window ) ) ), None, ) found: list[pd.Series] = [] left_out: list[str] = [] said: set[int] = set() for index, day in enumerate(days): row = longest + index usable = [w for w in windows if w <= longest and not missing(row, w)] if not usable: # None of the windows asked for: the longest shorter one the history fills. usable = [w for w in WINDOWS if w <= longest and not missing(row, w)][:1] if usable and usable[0] not in said: said.add(usable[0]) call.log.info( f"the history does not fill a window of {min(windows)} days: " f"{usable[0]} days are learnt from" ) if not usable: left_out.append(f"{day:%Y-%m-%d} left out: {missing(row, min(min(windows), longest))}") call.log.info(left_out[-1]) continue forecast = np.mean( [ forecast_day(read["series"], read["load"], read["renewables"], weekday, row, window) for window in usable ], axis=0, ) hours = pd.date_range(day, day + pd.DateOffset(days=1), freq="h", inclusive="left") found.append(pd.Series(forecast[hours.hour], index=hours.tz_convert("UTC"))) if not found: return _nothing(call, left_out[0]) forecast = pd.concat(found) forecast = forecast[(forecast.index >= call.start) & (forecast.index < call.end)] return call.answer(forecast=bff.values(forecast)) ``` ## The limits Each limit a function meets, and the line of the platform's code that sets it: ```json { "about": "Every limit a person's function meets. Each names the line of code that sets it: checks/functions_docs.py fails when that line is no longer there, so the published table cannot drift from the code.", "limits": [ { "what": "A model's time for one call", "limit": "60 s; declare less with `time=\"20s\"`", "file": "sdk/python/bff/declare.py", "pattern": "LIMITS = {\"model\": 60, \"indicator\": 5}" }, { "what": "An indicator's time for one call", "limit": "5 s", "file": "sdk/python/bff/declare.py", "pattern": "LIMITS = {\"model\": 60, \"indicator\": 5}" }, { "what": "Loading the code, on a first call", "limit": "120 s; the caller is told `runner_unavailable` after 90", "file": "platform/services/worker/src/main.rs", "pattern": "const LOAD_TIME: Duration = Duration::from_secs(120);" }, { "what": "How long a loaded function stays warm for one caller", "limit": "10 idle minutes", "file": "platform/services/runner/src/main.rs", "pattern": "seconds(\"PF_RUNNER_IDLE\", 600)" }, { "what": "Reads in one call", "limit": "20; `bff-sdk check` holds a laptop's run to the same", "file": "platform/services/api/src/runs.rs", "pattern": "requests: 20," }, { "what": "Values given to one call, across its reads", "limit": "400,000; held on a laptop too", "file": "platform/services/api/src/runs.rs", "pattern": "rows: 400_000," }, { "what": "Values in an answer", "limit": "200,000", "file": "platform/services/api/src/calls.rs", "pattern": "pub const MAX_VALUES: usize = 200_000;" }, { "what": "An answer's size", "limit": "16 MiB", "file": "platform/services/api/src/calls.rs", "pattern": "pub const MAX_ANSWER: usize = 16 * 1024 * 1024;" }, { "what": "What a call may send to outside hosts", "limit": "50 MiB; every connection is cut when the call ends", "file": "platform/services/runner/src/proxy.rs", "pattern": "pub const MAX_OUT: u64 = 50 * 1024 * 1024;" }, { "what": "The scratch folder, `BFF_SCRATCH`", "limit": "512 MiB in memory, shared with the unpacked upload; emptied at each call; `HOME` and `TMPDIR` are the same folder", "file": "docker-compose.yml", "pattern": "tmpfs: [\"/scratch:size=512m,mode=1777\"]" }, { "what": "A run's log", "limit": "64 KiB: every `print`, warning and traceback, as well as `call.log`; what is over is cut", "file": "platform/services/worker/src/python.rs", "pattern": "pub const MAX_LOG: usize = 64 * 1024;" }, { "what": "An upload", "limit": "50 MiB", "file": "platform/crates/ext/src/upload.rs", "pattern": "pub const MAX_BODY: usize = 50 * 1024 * 1024;" }, { "what": "An upload, unpacked", "limit": "200 MiB", "file": "platform/crates/ext/src/upload.rs", "pattern": "pub const MAX_UNPACKED: u64 = 200 * 1024 * 1024;" }, { "what": "Files in an upload", "limit": "1,000", "file": "platform/crates/ext/src/upload.rs", "pattern": "pub const MAX_FILES: usize = 1000;" }, { "what": "Outside hosts a function declares", "limit": "8", "file": "contracts/function-manifest.schema.json", "pattern": "\"maxItems\": 8" }, { "what": "Variables a function declares", "limit": "20", "file": "platform/crates/ext/src/secret.rs", "pattern": "pub const MAX_VARIABLES: usize = 20;" }, { "what": "A variable's value", "limit": "4 KiB", "file": "platform/crates/ext/src/secret.rs", "pattern": "pub const MAX_VALUE: usize = 4096;" }, { "what": "Examples a function declares", "limit": "4", "file": "contracts/function-manifest.schema.json", "pattern": "\"maxItems\": 4" }, { "what": "Functions a person has", "limit": "20", "file": "platform/services/api/src/ext.rs", "pattern": "pub const MAX_ENTRIES: i64 = 20;" }, { "what": "Versions of one function", "limit": "50", "file": "platform/services/api/src/ext.rs", "pattern": "pub const MAX_VERSIONS: i64 = 50;" }, { "what": "Grants on one function", "limit": "100", "file": "platform/services/api/src/ext.rs", "pattern": "pub const MAX_GRANTS: usize = 100;" }, { "what": "Library requests open", "limit": "20", "file": "platform/services/api/src/ext.rs", "pattern": "pub const MAX_OPEN_REQUESTS: i64 = 20;" }, { "what": "Calls a minute, of one caller, across people's functions", "limit": "None, unless an operator sets one (`PF_EXT_RATE_LIMIT`). What bounds a flood is the workers: with none free within 10 s, a call is answered `runner_busy`", "file": "platform/services/api/src/main.rs", "pattern": "number(\"PF_EXT_RATE_LIMIT\", 0)" }, { "what": "Runs kept", "limit": "30 days", "file": "platform/services/api/src/runs.rs", "pattern": "pub const RUNS_DAYS: i64 = 30;" }, { "what": "Reads in one call, on a laptop", "limit": "20, as on the platform", "file": "sdk/python/bff/local.py", "pattern": "MAX_READS = 20" }, { "what": "Values read in one call, on a laptop", "limit": "400,000, as on the platform", "file": "sdk/python/bff/local.py", "pattern": "MAX_VALUES_READ = 400_000" } ] } ``` ## The errors Each error a function, its owner or its caller can meet: its HTTP status, who meets it, and what to do. An upload itself answers 202; a fault in a declaration is not one of these, but a version that fails its checks with a message. ```json { "about": "Every error a person's function, its owner or its caller can meet (docs/design-functions.md). checks/functions_docs.py holds this list to the code, and the published guide's table to this list; a test of bff-core holds each status.", "errors": [ { "code": "invalid_upload", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "The upload broke a rule it names: a `.py` or a `.zip`, `main.py` or one `.py` at the top, at most 1,000 files, 50 MiB, 200 MiB unpacked." }, { "code": "invalid_name", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "A function's name is a-z, 0-9 and `_`, starting with a letter, at most 64 characters." }, { "code": "invalid_username", "kind": "AccessDenied", "status": 403, "who": "author", "says": "Your user name cannot own functions: it must be a-z, 0-9 and `_`, starting with a letter, at most 32 characters. Ask an operator." }, { "code": "name_taken", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "You have a function of that name already: a name is yours once, across models and indicators." }, { "code": "unknown_runtime", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "No runtime of that name; leave it out for the newest." }, { "code": "too_many_functions", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "Over 20 functions: delete one you no longer need." }, { "code": "too_many_versions", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "Over 50 versions of one function: delete drafts, or the function, and start again." }, { "code": "too_many_grants", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "Over 100 grants on one function." }, { "code": "too_many_variables", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "Over 20 variables on one function." }, { "code": "too_many_requests", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "Over 20 library requests open: wait for an answer." }, { "code": "invalid_grant", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "A grant is `user:{username}`, `role:trader`, `role:analyst` or `everyone`." }, { "code": "invalid_env", "kind": "InvalidRequest", "status": 400, "who": "author", "says": "A variable's name is A-Z, 0-9 and `_`, starting with a letter, at most 64 characters, and not one the platform sets." }, { "code": "invalid_status_change", "kind": "InvalidRequest", "status": 409, "who": "author", "says": "The version cannot go from its state to that one: a draft being checked cannot be released or deleted; a released one is deprecated before it can be deleted." }, { "code": "conflict", "kind": "InvalidRequest", "status": 409, "who": "author", "says": "A variable a released version declares cannot be deleted: change its value, but it stays." }, { "code": "not_found", "kind": "InvalidRequest", "status": 404, "who": "author", "says": "No such function, version, variable, host or request of yours." }, { "code": "payload_too_large", "kind": "InvalidRequest", "status": 413, "who": "author, caller", "says": "An upload over 50 MiB; a variable over 4 KiB; inside a call, a read past the run's budget of 20 reads and 400,000 values: read fewer series or a shorter period." }, { "code": "unknown_function", "kind": "InvalidRequest", "status": 400, "who": "caller", "says": "No such function, or one you may not call: the same answer. An owner calling their own draft names its version in the path." }, { "code": "unknown_version", "kind": "InvalidRequest", "status": 400, "who": "caller", "says": "No such version. For a version that exists and does not answer, the details list the released ones." }, { "code": "invalid_parameter", "kind": "InvalidRequest", "status": 400, "who": "caller", "says": "A parameter is outside its declared range, or not of its type; the problem's detail names it." }, { "code": "invalid_time", "kind": "InvalidRequest", "status": 400, "who": "caller", "says": "`start`, `end` or `as_of` is not a time with its zone." }, { "code": "invalid_request", "kind": "InvalidRequest", "status": 400, "who": "author, caller", "says": "The request broke a rule it names: a field missing, one it does not know, or a period that ends before it starts." }, { "code": "unknown_series", "kind": "InvalidRequest", "status": 400, "who": "caller", "says": "A series the call names does not exist, or you may not read it: a function reads with its caller's rights." }, { "code": "access_denied", "kind": "AccessDenied", "status": 403, "who": "caller", "says": "A person's function is called by a person, not by a service's own token." }, { "code": "version_suspended", "kind": "AccessDenied", "status": 403, "who": "caller", "says": "An operator stopped the version; the reason says why." }, { "code": "rate_limited", "kind": "InvalidRequest", "status": 429, "who": "caller", "says": "Over the calls a minute an operator has set, across people's functions; none is set unless one is. Try again after `Retry-After`." }, { "code": "model_failed", "kind": "Model", "status": 500, "who": "caller", "says": "The code raised an error, ended, ran out of memory, or wrote outside its scratch folder. The caller reads the error's first line; the log, with the traceback, is the owner's for their own calls and the checks, and an operator's for any." }, { "code": "invalid_answer", "kind": "Model", "status": 500, "who": "caller", "says": "The answer broke its declaration: an output missing, a value outside the period, over 200,000 values or 16 MiB." }, { "code": "model_timeout", "kind": "Service", "status": 504, "who": "caller", "says": "The call took more than its declared time: do less in a call, or declare more, up to 60 s for a model and 5 s for an indicator." }, { "code": "runner_busy", "kind": "Service", "status": 503, "who": "caller", "says": "Every worker is busy; try again after `Retry-After`." }, { "code": "runner_unavailable", "kind": "Service", "status": 503, "who": "caller", "says": "No worker has joined, or the runner did not answer in 90 s (a load that takes longer than that): try again; if it lasts, tell an operator." }, { "code": "secrets_unavailable", "kind": "Source", "status": 503, "who": "author", "says": "The platform cannot read its variables' key: tell an operator." }, { "code": "caller_left", "kind": "Service", "status": 500, "who": "nobody", "says": "The caller closed the connection before the answer: recorded with the run, seen by no one." } ] } ``` ## Common mistakes - **Answering outside the period.** Shifted or reindexed series often keep times before `call.start` or at `call.end`. Filter: `found[(found.index >= call.start) & (found.index < call.end)]`. - **Naive times.** Every index MUST be timezone-aware UTC. A market's hour is `index.tz_convert("Europe/Berlin").hour`, not `index.hour`. - **Days of 24 hours.** A market day has 23 or 25 hours when the clocks change. Build a period's times with `call.grid(step)`, or a day's with `pd.date_range(day, day + pd.DateOffset(days=1), freq=step, inclusive="left")` with `day` a Berlin midnight; never `day + pd.Timedelta(hours=24)`. - **Assuming hours.** Data may come in quarter-hours: 96 values a day, not 24. A forecast built on `call.grid("PT1H")` then answers one value an hour and drops three in four. Take the step from the data. - **Refusing the period.** `raise ValueError("ask for one day")` breaks every chart that shows a week. Answer the whole period; leave out what cannot be known or computed in time, and log it. - **Reading the future.** A read past the cut-off returns nothing, quietly; code that assumes a value exists then fails. Check for empty series and NaN. - **Reading too much.** Read each series once, for the whole span the call needs, not once a day: 20 reads a call. - **Randomness and the clock.** `np.random.default_rng()` or `datetime.now()` makes answers differ between the checks' two runs. Use `call.rng`. A library with a seed of its own gets a fixed one: LightGBM's `LGBMRegressor(random_state=0, deterministic=True, n_jobs=1, verbose=-1)`. - **Work at import.** Reading the platform's data, starting threads, or opening connections at module level fails the load ("loading started threads"). Reading `os.environ` and the folder's files there is fine. - **Writing beside the code.** `open("cache.pkl", "wb")` fails: the folder is closed to writing. Write under `os.environ["BFF_SCRATCH"]`, and expect it empty at the next call. - **A secret in an error.** `raise RuntimeError(f"key {key} refused")` shows the key to whoever called. Say what failed, not what was sent. - **Undeclared imports.** A library not in the runtime fails the checks with "No module named ...". Ask for it instead of vendoring it. - **Secrets.** Never write a key in the code; declare `env=[...]` and read `os.environ`. ## Trying and deploying ```sh bff-sdk login # signs in, by the device flow bff-sdk run . --example 1 # runs it here, as you, against the platform bff-sdk check . # imports, the declaration, each example twice, within a call's budget of reads bff-sdk push . --name my_model --kind model # uploads it and follows the checks bff-sdk pull my_model --kind model # a version of yours back, into my_model/ bff-sdk delete my_model --kind model --yes # deletes it, every version: frees one of 20 ``` In JupyterLab on a laptop, with `bff-sdk[python-1,lab]` and `bff-sdk login`, the same from Python, in a notebook beside `main.py` (`try.ipynb`, which is never uploaded): ```python from bff import lab prices = lab.series("epf.price", "2017-03-01T23:00:00Z", "2017-03-02T23:00:00Z", as_of="2017-03-01T12:00:00Z") # a series as known at a cut-off answer = lab.run(".") # its first example; or start=, end=, as_of=, parameters answer.plot() # each output, its quantiles as a fan, beside its series lab.check(".") # imports, the declaration, each example twice lab.push(".", release=True) # a new version; prints its address in the read API lab.pull("my_model", kind="model") # a version of yours back into a folder # lab.delete("my_model", kind="model") # deletes it, every version: frees one of 20 ``` A notebook may draw with matplotlib; a function's files may not import it.