Specs

Models and indicators of your own

Write a forecasting model or an indicator in Python, try it on the platform's data from your own machine, and deploy it. The platform checks it, keeps every version, and runs it when someone calls it: from a screen, beside the data, or through the API. You decide who may call it.

To deploy, you need the author role, which an operator grants. To call someone's function, you need the right to read the platform's data, as for any series, and the owner's grant.

Start here

A template

A main.py to fill in, the rules as README.md, and AGENTS.md for a coding assistant.

model.zip indicator.zip

The rules

One page: what a function may do, what it must declare, and the libraries it may import.

rules.txt

For a coding assistant

Everything an assistant needs to write a function, in one file. Give it this file and say what the function should do.

llms.txt

The SDK

bff-sdk, for trying a function on your machine and deploying it. It comes from this site, never from public PyPI.

bff-sdk package index

Examples to start from

Each runs on the platform's data as it is; download one, change it, and deploy it under a name of your own.

ExampleKindWhat it does
naiveModel The day before on Tuesday to Friday; the week before on Monday, Saturday and Sunday. The benchmark a forecast must beat.
smoothed_naiveModel The naive forecast, pulled toward the week's mean, read from the platform's rolling-mean indicator: a model that uses an indicator.
profile_meanModel Each moment of the day, the mean of that moment over the last days: a model with parameters, days and alike, which a screen shows as a form. It answers any period, a day or a month.
learModel epftoolbox's LEAR, a Lasso model of day-ahead prices, on a window of 56 to 1,456 days. Of a longer period, it forecasts the 8 latest days, and its log says which it left out.
lear_ensembleModel The mean of LEAR's four windows.
llm_outlookModel Claude's forecast of a day, checked against the market's limits, with the naive forecast to fall back on. It calls an outside host, so it needs a key and an operator's approval.
peak_spreadIndicator Each weekday's peak average less its base average.

lear and lear_ensemble are ported from epftoolbox and are under the GNU Affero General Public License, version 3: see the LICENSE in each.

Where the platform deploys the examples for you, as the development stack does, you need not download anything to see them work: every chart lists them under Series and indicators, owned by examples.

Learn step by step

New to forecasting, or to the platform? Five short notebooks teach it from the beginning. Each builds on the one before and works on real prices. Each asks you to predict a result before you see it, because a surprise is what makes an idea stick.

  1. What was known, and when: every value has a time it is for and a time it became known. The cut-off keeps a forecast honest.
  2. A first model: write one, run it, score it against what happened, and make it better.
  3. Parameters, periods and steps: what a caller may change, why a model must answer any period, and data by the hour or by the quarter-hour.
  4. An indicator: how it differs from a model, and how to write one.
  5. Deploy, share and delete: from your notebook to a colleague's chart, and back out.

Download all five, with the examples they use, unpack them, and open them in JupyterLab with bff-sdk[python-1,lab] installed (2. Try it says how), after bff-sdk login. Start with the first.

1. Write it

A function is one Python file, or a folder zipped with its main.py, holding exactly one function marked @bff.model(...) or @bff.indicator(...). Its declaration says:

The platform calls it with a period, a cut-off and the parameters. It reads the data it needs through the SDK (call.series, call.read, call.catalog, call.indicator), always as known at the cut-off, with the caller's rights, and returns call.answer(...). The rules say the rest; the templates follow them.

The period belongs to the caller

A screen calls a function with the period its chart shows, a day or a month, and with the chart's moment as the cut-off. A function must answer that whole period. It must never refuse one for being long.

Some of a period cannot be known, and that is fine. Take a model that copies the day before. Asked on Monday morning for the whole week, it can forecast Tuesday, which copies Monday. It cannot forecast Wednesday, which would copy a Tuesday nobody has seen yet. So it leaves Wednesday empty and answers the rest. If the whole period would take longer than the function's time, it computes what it can, leaves out the rest and says so in its log. lear, for instance, forecasts the 8 latest days of a longer period.

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: 96 a day, not 24. Take the step from the data you read; never assume an hour. The examples show how, with a small function called step_of. A model built on hours, like lear, says so and averages each hour's quarters.

2. Try it on your machine

Install the SDK in a virtual environment. Its extra python-1 installs the platform's own libraries at their exact versions, so your machine computes as the platform does:

python3 -m venv .venv
.venv/bin/pip install "bff-sdk[python-1] @ http://localhost:8640/sdk/files/bff_sdk-1.4.0-py3-none-any.whl"

The SDK finds the platform by two settings. For this platform they are these; set them in each terminal you use, or in your shell's profile:

export BFF_SDK_API=http://localhost:8620
export BFF_SDK_ISSUER=http://localhost:8180/realms/bff

Then sign in (a browser opens to approve it), and run your function against the platform's data, as you, at its example's cut-off or at any other:

.venv/bin/bff-sdk login
.venv/bin/bff-sdk run . --example 1
.venv/bin/bff-sdk run . --start 2017-06-01T22:00:00Z --end 2017-06-02T22:00:00Z \
    --as-of 2017-06-01T08:00:00Z --param window=84
.venv/bin/bff-sdk check .

check validates the declaration and runs each example twice. The platform's own checks decide, on its machines.

Or in a notebook

The same steps, in JupyterLab on your machine, with bff-sdk[python-1,lab] installed and bff-sdk login done. A folder of yours is one function: main.py, the files it reads, and try.ipynb, its notebook, which is never uploaded. lab.new makes one from a template:

from bff import lab

prices = lab.series("epf.price", "2017-03-01T23:00:00Z", "2017-03-02T23:00:00Z",
                    as_of="2017-03-01T08:00:00Z")   # the data as known then: none yet
lab.new("my_model", kind="model")       # a folder from the template, with its notebook
answer = lab.run("my_model")            # its first example, on the platform's data, as you
answer.plot()                           # the forecast, beside the prices as known now
lab.check("my_model")                   # its imports, its declaration, its examples
lab.push("my_model", release=True)      # a new version; ends with its address in the read API

lab.run takes start=, end=, as_of= and the function's parameters too; nothing it computes is published until you push. To change a version you deployed, lab.pull("my_model") brings it back into its folder, never over a file you changed.

A function imports the runtime's libraries alone; a notebook may also draw with matplotlib, which lab.check and lab.push refuse in a function's files, by file and line.

3. Upload it

From your machine:

.venv/bin/bff-sdk push . --name my_model --kind model

which zips the folder and follows the checks. Or with the read API: the file or the zip as the body of POST /v1/functions/{you}/{name}/versions?kind=model. Each upload is a new version, numbered from 1; the code of a version never changes.

4. Wait for the checks

A version is checked in about a minute, once its turn comes: the upload's rules, its declaration, then each example twice, in two workers. The checks take one version at a time for the whole platform, so yours may wait behind another's. Each example must answer within the time you declared; that time is the call's own, as a caller's call is held to it, and does not count the wait for a worker or the loading of your code.

The check loads your code with the variables you have set, as a call does, so a module may read its key as it loads. It then runs each example with the variables you declared alone: one you read and did not declare fails there.

If the platform has no worker free for your checks for a quarter of an hour, the version fails and says the fault was the platform's: upload it again. Its states:

StateMeansWho may call it
checkingThe checks runNobody
waitingThe checks wait for a variable you have not set, or a host an operator has not approved; they go on when it comes. If the operator declines the host, the version fails, and says for which hostNobody
failedA check failed; the report says which and whyNobody
readyPassed: a draftYou, naming its version: a call that names none takes your newest released one
releasedFixed for good, and listed for those you grantedYour list
deprecatedStill answers; points to your newest released versionYour list
suspendedStopped by an operator, with the reasonNobody

Give --release to push, or release=on-pass to the upload, to release it as soon as it is ready.

5. Release it and grant it

Release a ready version to let others call it (POST …/versions/{version}/release). Deprecate an older one to point its callers to the newest (…/deprecate). A draft can be deleted once its checks have ended, and so can a deprecated version: its code goes, its number is never used again, and a call that names it finds no such version. A released version is deprecated first.

Say who may call it with PUT /v1/functions/{you}/{name}/access: people by their user name, every trader, every analyst, or everyone who reads the platform. You always may. A person who may not call it does not see it. GET …/runs says when it was called, which version, how long it took and how it ended; never who.

A colleague you granted finds it among the functions they may call (GET /v1/functions), under your name; a screen sets its parameters, and draws its answer beside the data: a forecast's quantiles as a band.

Deleting a function

Each person may keep 20 functions. When you no longer need one, or need room for another, delete it: DELETE /v1/functions/{you}/{name}. Every version goes with it, released ones too, and charts that drew it say it is no longer available. Deleting cannot be undone. You may use the name again; its versions then count on from where they stopped, so a saved chart never draws new code by mistake. From a notebook, lab.delete("my_model", kind="model") does the same; from your machine, bff-sdk delete my_model --kind model --yes.

Reading the platform's indicators

A model may take one of the platform's indicators as an input with call.indicator(id, version, inputs, parameters, since, until). Like every read, it is computed as known at the call's cut-off: ask for it over the period you need, and it gives only what could have been computed by then, so a forecast never sees later data. The example smoothed_naive reads the weekly rolling-mean this way. The read API's reference lists each indicator, its parameters and its outputs.

Variables

A function that needs a secret, such as a key for an outside service, declares its name, env=["ANTHROPIC_API_KEY"], and reads it with os.environ. Set its value with PUT /v1/functions/{you}/{name}/env/{variable}. It is kept encrypted and never shown again, to you or anyone; calls that start after a change see the new value. A variable a released version declares can be changed, not deleted.

Outside hosts

A function that calls an outside service declares its host by its exact name, hosts=["api.anthropic.com"], on HTTPS. Its first version to name a host asks an operator, and waits; its version says which host it waits for. A function that calls a host is not repeatable: the same call may answer differently. Callers are told it sends data to that host, under your account.

The example llm_outlook calls Claude at api.anthropic.com. Set your own key as its variable ANTHROPIC_API_KEY; without one, it answers the naive forecast, and its log says why.

Runs and logs

Each call is a run, with its id. Under Runs: yours and the checks', in full, with their logs; others' calls as when, which version, how long and how they ended, without their id or their log. A log holds everything the code wrote: call.log, and every print, warning and traceback, up to 64 KiB a call. What a module writes while it loads is kept only if the load fails.

The newest runs come first, 200 at a time: Show older runs reads the 200 before them. A run is kept for 30 days. A program that reads the runs asks for them by pages, as it does any list that grows: each answer says next_cursor, which asks for the page after it, and null on the last (the readers' guide shows how). The library requests you made are read the same way.

What a caller sees of a failure: a problem (RFC 9457) with its code, its run's id (details.run), and the error's first line, up to 500 characters, as its detail. Never the traceback. So write no secret, and nothing of another person's data, into an exception's message: whoever called reads it. A caller who is not you cannot read the run's log; an operator can read any.

Libraries

The code imports the runtime's libraries alone. Eleven are promised: named in the rules, at versions a runtime never changes. The others come with those eleven; they can be imported, and bff-sdk check lets them through, but nothing promises them: a patch of the runtime may change or drop one. Build on the promised ones. On your machine, bff-sdk[python-1] installs the eleven at these versions, and whatever versions of the others pip then picks.

LightGBM joined python-1 in 3.2.15, at 4.7.0: it needed no other version of a library already there, so no function released before it answers differently. A function has one processor, and the platform holds every library to one thread (OMP_NUM_THREADS=1): leave n_jobs alone, or set it to 1; a higher number starts threads that share the one processor, and the fit takes longer. For an answer that repeats, give it a fixed seed and its own switch: LGBMRegressor(random_state=0, deterministic=True, n_jobs=1). On a Mac, LightGBM also needs OpenMP, which pip does not install: brew install libomp.

Library, in python-1Version
annotated-types0.8.0Comes with another
anthropic2.8.0Promised
anyio4.16.0Comes with another
certifi2026.10.23Comes with another
cloudpickle3.1.2Comes with another
docstring-parser0.18.0Comes with another
formulaic1.2.2Comes with another
h110.16.0Comes with another
httpcore1.0.9Comes with another
httpcore22.16.0Comes with another
httpx0.28.1Promised
httpx22.16.0Comes with another
idna3.20Comes with another
interface-meta2.0.1Comes with another
jiter0.19.0Comes with another
joblib1.6.0Promised
lightgbm4.7.0Promised
narwhals2.28.0Comes with another
numpy2.5.5Promised
openai3.51.0Promised
opentelemetry-api1.45.2Comes with another
packaging26.3Comes with another
pandas3.1.1Promised
patsy1.0.3Comes with another
pyarrow26.0.1Promised
pydantic2.14.3Comes with another
pydantic-core2.50.4Comes with another
python-dateutil4.0.0Comes with another
scikit-learn1.9.1Promised
scipy1.18.1Promised
sniffio1.3.1Comes with another
statsmodels0.15.0Promised
threadpoolctl3.8.0Comes with another
truststore0.10.5Comes with another
typing-extensions4.16.0Comes with another
typing-inspection0.4.5Comes with another
tzdata2026.6Comes with another
wrapt2.5.2Comes with another

To ask for another, under Libraries: its name, what it is for, and for which function. An operator accepts or declines it, with the reason, then makes it available in a runtime; upload the version again then. Until then, a version importing it fails its checks, for instance No module named 'tensorflow'.

How your code is loaded and called

The platform keeps nothing of yours between calls but what your module built as it loaded.

  1. A first call loads the code. A worker unpacks your upload and imports your module once: its module-level code runs then, with your variables, without a call and without a token, so it can read the files in your folder and cannot read the platform's data. It has 120 seconds; the caller waits, and is told runner_unavailable after 90.
  2. Each call runs in a fresh copy of the loaded module. What a call changes in memory is gone at the next.
  3. A loaded function is one caller's. Another person's first call loads it again, in another worker. It stays warm for ten idle minutes; a call over its time, or one that ends the process, also ends it, and the next call loads anew.
  4. Your folder is closed to writing. Write files only under BFF_SCRATCH, which is emptied at each call. A call that writes anywhere else fails with model_failed.

So load what is the same for every call at import (a table, a fitted model shipped in the folder); read the caller's data inside the call. A model that must be trained on the platform's data is trained in the call, each time, within its time.

On your machine, bff-sdk check runs each example twice, as the platform does, and holds each run to the same budget of reads. Three things it cannot do as the platform does. Both runs share one process, so what the first leaves in a module-level variable the second sees; the platform gives each call a fresh copy. (If that changes the answer, the check says the two answers differ.) Your machine's memory and processor are not the platform's. And your code's time there is not its time here: the check warns when an example takes longer than declared.

Limits

Each is set by one line of the platform's code, and this table is made from the list that names those lines.

WhatLimit
A model's time for one call60 s; declare less with time="20s"
An indicator's time for one call5 s
Loading the code, on a first call120 s; the caller is told runner_unavailable after 90
How long a loaded function stays warm for one caller10 idle minutes
Reads in one call20; bff-sdk check holds a laptop's run to the same
Values given to one call, across its reads400,000; held on a laptop too
Values in an answer200,000
An answer's size16 MiB
What a call may send to outside hosts50 MiB; every connection is cut when the call ends
The scratch folder, BFF_SCRATCH512 MiB in memory, shared with the unpacked upload; emptied at each call; HOME and TMPDIR are the same folder
A run's log64 KiB: every print, warning and traceback, as well as call.log; what is over is cut
An upload50 MiB
An upload, unpacked200 MiB
Files in an upload1,000
Outside hosts a function declares8
Variables a function declares20
A variable's value4 KiB
Examples a function declares4
Functions a person has20
Versions of one function50
Grants on one function100
Library requests open20
Calls a minute, of one caller, across people's functionsNone, 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
Runs kept30 days
Reads in one call, on a laptop20, as on the platform
Values read in one call, on a laptop400,000, as on the platform

Each error, and what to do

An upload itself answers 202: it is taken, and checked after. A fault in what it declares (a host that is not an exact name, a parameter without a default) is not an HTTP error: the version fails its checks, and its report says which rule and where; bff-sdk check finds it first. The errors below are what a request answers with. This table is made from the platform's own list of them, which a test holds to the code.

CodeStatusWho meets itWhat it means, and what to do
invalid_upload400AuthorThe 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.
invalid_name400AuthorA function's name is a-z, 0-9 and _, starting with a letter, at most 64 characters.
invalid_username403AuthorYour user name cannot own functions: it must be a-z, 0-9 and _, starting with a letter, at most 32 characters. Ask an operator.
name_taken400AuthorYou have a function of that name already: a name is yours once, across models and indicators.
unknown_runtime400AuthorNo runtime of that name; leave it out for the newest.
too_many_functions400AuthorOver 20 functions: delete one you no longer need.
too_many_versions400AuthorOver 50 versions of one function: delete drafts, or the function, and start again.
too_many_grants400AuthorOver 100 grants on one function.
too_many_variables400AuthorOver 20 variables on one function.
too_many_requests400AuthorOver 20 library requests open: wait for an answer.
invalid_grant400AuthorA grant is user:{username}, role:trader, role:analyst or everyone.
invalid_env400AuthorA variable's name is A-Z, 0-9 and _, starting with a letter, at most 64 characters, and not one the platform sets.
invalid_status_change409AuthorThe 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.
conflict409AuthorA variable a released version declares cannot be deleted: change its value, but it stays.
not_found404AuthorNo such function, version, variable, host or request of yours.
payload_too_large413Author, callerAn 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.
unknown_function400CallerNo such function, or one you may not call: the same answer. An owner calling their own draft names its version in the path.
unknown_version400CallerNo such version. For a version that exists and does not answer, the details list the released ones.
invalid_parameter400CallerA parameter is outside its declared range, or not of its type; the problem's detail names it.
invalid_time400Callerstart, end or as_of is not a time with its zone.
invalid_request400Author, callerThe request broke a rule it names: a field missing, one it does not know, or a period that ends before it starts.
unknown_series400CallerA series the call names does not exist, or you may not read it: a function reads with its caller's rights.
access_denied403CallerA person's function is called by a person, not by a service's own token.
version_suspended403CallerAn operator stopped the version; the reason says why.
rate_limited429CallerOver the calls a minute an operator has set, across people's functions; none is set unless one is. Try again after Retry-After.
model_failed500CallerThe 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.
invalid_answer500CallerThe answer broke its declaration: an output missing, a value outside the period, over 200,000 values or 16 MiB.
model_timeout504CallerThe 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.
runner_busy503CallerEvery worker is busy; try again after Retry-After.
runner_unavailable503CallerNo 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.
secrets_unavailable503AuthorThe platform cannot read its variables' key: tell an operator.
caller_left500NobodyThe caller closed the connection before the answer: recorded with the run, seen by no one.

For operators

Operators answer through the read API's /v1/admin/… paths: the hosts and libraries asked for, the versions to suspend or lift, the runs' logs.

Hosts. Approve a service the company has terms with, which processes what it is sent and keeps it no longer than its terms say. Never approve a host whose received data its owner can read back: storage, a paste site, a webhook. Withdrawing a host suspends every version that names it.

Libraries. Accept a library that is maintained, of a licence the company accepts, with wheels for Linux on amd64 and arm64, and no advisory left unfixed, each checked on the day. A runtime never changes or removes a promised library. It may gain one that needs no other version of a library already there, as python-1 gained LightGBM: every function released on it then answers as before. A library that would move one already there waits for a new runtime, which a function names when it is uploaded again.

Suspending. Any version that has passed its checks, a draft that is ready among them, with a reason its owner and its callers read. Lifted, it returns to the state it left.

Workers and backups. Operations shows how many workers each pool has of those it is meant to, and the last backup; each in red when it needs you.