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.
The rules
One page: what a function may do, what it must declare, and the libraries it may import.
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.
The SDK
bff-sdk, for trying a function on your machine and deploying
it. It comes from this site, never from public PyPI.
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.
| Example | Kind | What it does |
|---|---|---|
| naive | Model | The day before on Tuesday to Friday; the week before on Monday, Saturday and Sunday. The benchmark a forecast must beat. |
| smoothed_naive | Model | The naive forecast, pulled toward the week's mean, read from the platform's rolling-mean indicator: a model that uses an indicator. |
| profile_mean | Model | 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. |
| lear | Model | 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_ensemble | Model | The mean of LEAR's four windows. |
| llm_outlook | Model | 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_spread | Indicator | 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.
- 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.
- A first model: write one, run it, score it against what happened, and make it better.
- 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.
- An indicator: how it differs from a model, and how to write one.
- 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:
- what a caller may set: its parameters, each with a default;
- what it answers: its outputs, each with a unit;
- at least one example call, which the checks run.
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:
| State | Means | Who may call it |
|---|---|---|
checking | The checks run | Nobody |
waiting | The 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 host | Nobody |
failed | A check failed; the report says which and why | Nobody |
ready | Passed: a draft | You, naming its version: a call that names none takes your newest released one |
released | Fixed for good, and listed for those you granted | Your list |
deprecated | Still answers; points to your newest released version | Your list |
suspended | Stopped by an operator, with the reason | Nobody |
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-1 | Version | |
|---|---|---|
annotated-types | 0.8.0 | Comes with another |
anthropic | 2.8.0 | Promised |
anyio | 4.16.0 | Comes with another |
certifi | 2026.10.23 | Comes with another |
cloudpickle | 3.1.2 | Comes with another |
docstring-parser | 0.18.0 | Comes with another |
formulaic | 1.2.2 | Comes with another |
h11 | 0.16.0 | Comes with another |
httpcore | 1.0.9 | Comes with another |
httpcore2 | 2.16.0 | Comes with another |
httpx | 0.28.1 | Promised |
httpx2 | 2.16.0 | Comes with another |
idna | 3.20 | Comes with another |
interface-meta | 2.0.1 | Comes with another |
jiter | 0.19.0 | Comes with another |
joblib | 1.6.0 | Promised |
lightgbm | 4.7.0 | Promised |
narwhals | 2.28.0 | Comes with another |
numpy | 2.5.5 | Promised |
openai | 3.51.0 | Promised |
opentelemetry-api | 1.45.2 | Comes with another |
packaging | 26.3 | Comes with another |
pandas | 3.1.1 | Promised |
patsy | 1.0.3 | Comes with another |
pyarrow | 26.0.1 | Promised |
pydantic | 2.14.3 | Comes with another |
pydantic-core | 2.50.4 | Comes with another |
python-dateutil | 4.0.0 | Comes with another |
scikit-learn | 1.9.1 | Promised |
scipy | 1.18.1 | Promised |
sniffio | 1.3.1 | Comes with another |
statsmodels | 0.15.0 | Promised |
threadpoolctl | 3.8.0 | Comes with another |
truststore | 0.10.5 | Comes with another |
typing-extensions | 4.16.0 | Comes with another |
typing-inspection | 0.4.5 | Comes with another |
tzdata | 2026.6 | Comes with another |
wrapt | 2.5.2 | Comes 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.
- 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_unavailableafter 90. - Each call runs in a fresh copy of the loaded module. What a call changes in memory is gone at the next.
- 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.
- 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 withmodel_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.
| What | Limit |
|---|---|
| A model's time for one call | 60 s; declare less with time="20s" |
| An indicator's time for one call | 5 s |
| Loading the code, on a first call | 120 s; the caller is told runner_unavailable after 90 |
| How long a loaded function stays warm for one caller | 10 idle minutes |
| Reads in one call | 20; bff-sdk check holds a laptop's run to the same |
| Values given to one call, across its reads | 400,000; held on a laptop too |
| Values in an answer | 200,000 |
| An answer's size | 16 MiB |
| What a call may send to outside hosts | 50 MiB; every connection is cut when the call ends |
The scratch folder, BFF_SCRATCH | 512 MiB in memory, shared with the unpacked upload; emptied at each call; HOME and TMPDIR are the same folder |
| A run's log | 64 KiB: every print, warning and traceback, as well as call.log; what is over is cut |
| An upload | 50 MiB |
| An upload, unpacked | 200 MiB |
| Files in an upload | 1,000 |
| Outside hosts a function declares | 8 |
| Variables a function declares | 20 |
| A variable's value | 4 KiB |
| Examples a function declares | 4 |
| Functions a person has | 20 |
| Versions of one function | 50 |
| Grants on one function | 100 |
| Library requests open | 20 |
| Calls a minute, of one caller, across people's functions | 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 |
| Runs kept | 30 days |
| Reads in one call, on a laptop | 20, as on the platform |
| Values read in one call, on a laptop | 400,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.
| Code | Status | Who meets it | What it means, and what to do |
|---|---|---|---|
invalid_upload | 400 | Author | 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. |
invalid_name | 400 | Author | A function's name is a-z, 0-9 and _, starting with a letter, at most 64 characters. |
invalid_username | 403 | Author | 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. |
name_taken | 400 | Author | You have a function of that name already: a name is yours once, across models and indicators. |
unknown_runtime | 400 | Author | No runtime of that name; leave it out for the newest. |
too_many_functions | 400 | Author | Over 20 functions: delete one you no longer need. |
too_many_versions | 400 | Author | Over 50 versions of one function: delete drafts, or the function, and start again. |
too_many_grants | 400 | Author | Over 100 grants on one function. |
too_many_variables | 400 | Author | Over 20 variables on one function. |
too_many_requests | 400 | Author | Over 20 library requests open: wait for an answer. |
invalid_grant | 400 | Author | A grant is user:{username}, role:trader, role:analyst or everyone. |
invalid_env | 400 | Author | A 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_change | 409 | Author | 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. |
conflict | 409 | Author | A variable a released version declares cannot be deleted: change its value, but it stays. |
not_found | 404 | Author | No such function, version, variable, host or request of yours. |
payload_too_large | 413 | Author, caller | 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. |
unknown_function | 400 | Caller | No such function, or one you may not call: the same answer. An owner calling their own draft names its version in the path. |
unknown_version | 400 | Caller | No such version. For a version that exists and does not answer, the details list the released ones. |
invalid_parameter | 400 | Caller | A parameter is outside its declared range, or not of its type; the problem's detail names it. |
invalid_time | 400 | Caller | start, end or as_of is not a time with its zone. |
invalid_request | 400 | Author, caller | The request broke a rule it names: a field missing, one it does not know, or a period that ends before it starts. |
unknown_series | 400 | Caller | A series the call names does not exist, or you may not read it: a function reads with its caller's rights. |
access_denied | 403 | Caller | A person's function is called by a person, not by a service's own token. |
version_suspended | 403 | Caller | An operator stopped the version; the reason says why. |
rate_limited | 429 | Caller | Over the calls a minute an operator has set, across people's functions; none is set unless one is. Try again after Retry-After. |
model_failed | 500 | Caller | 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. |
invalid_answer | 500 | Caller | The answer broke its declaration: an output missing, a value outside the period, over 200,000 values or 16 MiB. |
model_timeout | 504 | Caller | 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. |
runner_busy | 503 | Caller | Every worker is busy; try again after Retry-After. |
runner_unavailable | 503 | Caller | 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. |
secrets_unavailable | 503 | Author | The platform cannot read its variables' key: tell an operator. |
caller_left | 500 | Nobody | The 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.