# The rules A function is a model or an indicator: Python, run by the platform when someone calls it. It is one file, `main.py`, or a folder zipped with `main.py` and its data files. It holds exactly one function marked `@bff.model(...)` or `@bff.indicator(...)`. ## What a call gives, and what an answer must be A call gives `call.start` and `call.end`, the period to answer, and `call.as_of`, the cut-off: the moment it answers as at, now if the caller gave none. All three are pandas Timestamps in UTC. `call.parameters` holds every declared parameter, the defaults filled in. The function returns `call.answer(...)`, each declared output as `bff.values(series, **columns)`: - every declared output, empty if it has nothing; - times in UTC, sorted, each once, within `[start, end)`; - values finite numbers or missing (NaN), each column as long as its output; - at most 200,000 values in all. ```python import pandas as pd import bff @bff.model( title="The day before", parameters={"series": bff.series(default="epf.price", unit="EUR/MWh")}, outputs={"forecast": bff.output(unit="EUR/MWh")}, examples=[bff.example(start="2017-03-01T23:00:00Z", end="2017-03-02T23:00:00Z", as_of="2017-03-01T09:00:00Z")], ) def forecast(call: bff.Call) -> bff.Answer: day = pd.Timedelta(days=1) price = call.series(call.parameters["series"], since=call.start - day, until=call.end - day) return call.answer(forecast=bff.values(price.shift(freq=day))) ``` ## The period belongs to the caller A screen asks for the period its chart shows, a day or a month, and gives the chart's moment as the cut-off. Answer the whole period. Never refuse one for being long or for lying beyond the cut-off. Some of the period cannot be known. A forecast that copies the day before needs Wednesday's prices to forecast Thursday; at Monday's cut-off nobody has them. Leave such times empty (NaN) or out. If the whole period would take longer than the time you declared, compute what you can, leave out the rest and say what you left out in `call.log`. Data comes by the hour or by the quarter-hour. ENTSO-E's day-ahead prices for Germany have come in quarter-hours since October 2025. Take the step from the data instead of assuming an hour; the examples' `step_of` shows how. A model built on hours, like LEAR, should say so and average each hour's quarters, not keep the first. ## Reading the platform's data - `call.series(name, since=, until=)`: one series, as known at the cut-off. - `call.read(names, since=, until=)`: several, with when each value was known. - `call.catalog(...)`: the series you may read. - `call.indicator(id, version, inputs, ...)`: a platform indicator. The code reads as the caller, so it sees what the caller may see, and nothing known after the cut-off. A read refused raises `bff.ReadRefused`. A call may make 20 reads, and be given 400,000 values in all. ## Libraries Your code may import the runtime's libraries alone: numpy, pandas, pyarrow, scipy, scikit-learn, lightgbm, statsmodels, joblib, httpx, anthropic and openai, at the versions `GET /v1/runtimes` lists. To ask for another, say what it is for with `POST /v1/libraries`; an operator answers. Your own modules, in the folder, may be imported. What those libraries bring with them can be imported too, but is not promised: a patch of the runtime may change or drop one. The guide lists them. ## Time and size A model has at most 60 seconds a call, an indicator 5; declare less with `time="20s"`. Memory is 2 GiB, one processor. The platform holds each library to one thread (`OMP_NUM_THREADS=1`); leave it so. With LightGBM, leave `n_jobs` alone or set it to 1: more threads share the one processor and take longer. An upload is at most 50 MiB, 200 MiB unpacked. Write files, if you must, under the folder in the `BFF_SCRATCH` environment variable; it is emptied at each call. Your own folder is closed to writing: a call that writes anywhere else fails. ## Nothing kept between calls Each call runs in a fresh copy of the loaded code. What one call keeps is gone at the next. The code is loaded once for each caller, on their first call, within 120 seconds, and stays warm for ten idle minutes. Load what you need at import (a file in the folder, a fitted table); fetch the caller's data inside the call. Start no thread or process at import. ## Outside hosts and variables Declare each host your code calls, `hosts=["api.anthropic.com"]`, by its exact name, on HTTPS; an operator approves it before the checks run. It sends data under your account, and callers are told so. Declare the variables it needs, `env=["ANTHROPIC_API_KEY"]`, and set each with the read API, `PUT /v1/functions/{owner}/{name}/env/{variable}`; the code reads them with `os.environ`. A value is never shown again. ## Repeatable answers A function that calls no outside host must give the same answer to the same call, bit for bit: the checks run each example twice. Draw random numbers from `call.rng`, which is seeded by the code and the call; never read the clock; let nothing depend on the order of a set. Give a library that draws its own a fixed seed: with LightGBM, `random_state=0` and `deterministic=True`. ## Before you upload ```sh bff-sdk run . --example 1 # runs it here, against the platform's data, as you bff-sdk check . # the declaration, and each example twice bff-sdk push . --name my_model --kind model ``` The platform checks it again: its declaration, each example twice. Then release it, and say who may call it.