Configuration

Configuration is loaded from environment variables (and an optional .env file) via pydantic-settings — see src/scheduling_bridge/config.py.

Market setup

Variable	Default	Meaning
`HOME_CONTROL_AREA`	`TenneT`	Control area whose balancing group receives the EPEX/ECC delivery
`ACTIVE_CONTROL_AREAS`	all four	Comma-separated subset, e.g. `TenneT,Amprion`
`INCLUDE_EXCHANGE_LEG`	`true`	Include the EPEX/ECC leg in the Engrate submission (`false` if ECC auto-nominates)
`UNIT`	`MW`	Input unit: `MW` (average per 15 min) or `MWH`. Engrate always receives MW (average power per quarter-hour); MWh is converted (×4)

HOME_CONTROL_AREA defaults to TenneT as a placeholder. Set it to the real home area before any live use — it decides where the physical EPEX delivery lands.

Engrate

Variable	Default	Meaning
`ENGRATE_ENVIRONMENT`	`staging`	The go-live switch: `staging` or `production`. Selects which URL/key pair below is used; staging submissions always carry Engrate’s `test` flag, production submissions never do
`ENGRATE_BASE_URL`	`https://api.staging.engrate.net`	Engrate staging API base URL
`ENGRATE_API_KEY`	—	Staging API key, sent raw in the `authorization` header
`ENGRATE_PRODUCTION_BASE_URL`	`https://api.engrate.io`	Engrate production API base URL
`ENGRATE_PRODUCTION_API_KEY`	—	Production API key from the Engrate console. Switching to `production` is refused while this is empty
`ENGRATE_TEST_MODE`	`false`	Deprecated — no longer consulted; the `test` flag follows `ENGRATE_ENVIRONMENT`
`MABIS_QUELLE`	`makoflow`	Where the views read the MaBiS sum series and the BIKO’s reBAP: `makoflow` (the MSCONS and PRICAT in the mako365 inbox) or `engrate` (what the `engrate-mabis` routine read from Engrate; the inbox is then not read for them). Console: Engrate tab. See The values from Engrate
`AREA_MARKET_IDS`	see below	JSON: per-area market identifiers
`EXCHANGE_COUNTERPARTY_EIC`	unset	Party EIC of the ECC counterparty for the exchange leg

AREA_MARKET_IDS maps each control area to its identifiers:

{
  "TenneT": {
    "balancing_group_eic": "<EIC of our TenneT balancing group>",
    "control_area_eic": "10YDE-EON------1",
    "tso": "TENNET_DE_TSO",
    "receiver_eic": "10XDE-EON------1"
  }
}

The control-area EIC Y codes default to the public, stable values. The balancing-group EICs default to placeholders and must be configured; the TSO identifiers and receiver EICs follow Engrate’s documented pattern and need verification — see Assumptions.

Market communication

Beyond the identifiers above, the message loops have their own settings — PARTIN, Zuordnungsermächtigung and the APERAK acknowledgements. Whether a loop runs on the orchestrator is no setting any more: each loop is a process agent switched in the console’s Agenten tab (the former AUTO_* switches were read once into the seeded agents):

Variable	Default	Meaning
`APERAK_LOOKBACK_DAYS`	`30`	How far back the inbox is scanned for unanswered messages
`APERAK_MAX_PER_RUN`	`40`	Acknowledgements per run; a backlog spreads over following runs
`QUITTUNG_NACHFASS_KARENZ_STUNDEN`	`24`	Grace on top of the regulatory CONTRL/APERAK deadlines before a silent partner is chased by mail
`MAKOFLOW_TIMEOUT_SECONDS`	`60`	HTTP timeout per MakoFlow call. The reads (inbox, outbox, transport-log pages) are retried once on a read timeout - a single slow page must not fail an orchestrator step; the ingress (a delivery) is never retried
`MAKOFLOW_CACHE`	`true`	Incremental mirror of the MakoFlow reads: fetched inbox/outbox/transport-log entries are persisted in the audit directory and only the slice since the last sync is fetched again. Every store is keyed by kind, EDIFACT type and MP-ID and keeps only the BRP’s own entries: the shared mako365 outbox comes back unfiltered, and foreign senders’ files are dropped before anything is stored
`MAKOFLOW_CACHE_OVERLAP_HOURS`	`48`	Re-fetched overlap before the last sync — catches late-indexed entries and transport-log rows whose `as4Error` fills in after the row appears
`MAKOFLOW_CACHE_RETENTION_DAYS`	`200`	Store horizon. Never below 190 days (the cache clamps): the deepest read asks for 180 days, and a shorter horizon made every such read pull the missing history from mako365 again
`ZENTRALE_URL` / `ZENTRALE_API_KEY`	empty	On a Mandant: the Zentrale’s base URL and a report key of it. The reBAP history and the PARTIN directory are then copied from there, and netztransparenz.de and ENTSO-E are not read. Settable from the console; the key is never shown
`ZENTRALE_MANDANTEN`	`{}`	On the Zentrale: JSON, the Mandanten’s MP-IDs and role (`bkv`, `lieferant`) whose PARTINs it collects from the shared mako365 account, besides its own
`NETZTRANSPARENZ_CLIENT_ID` / `NETZTRANSPARENZ_CLIENT_SECRET`	empty	OAuth client (client credentials) registered at netztransparenz.de; the reBAP history and forecast need it, unless a Zentrale is set. Settable from the console; the secret is never shown
`NETZTRANSPARENZ_BASE_URL` / `NETZTRANSPARENZ_TOKEN_URL`	`https://ds.netztransparenz.de/api/v1` / `https://identity.netztransparenz.de/users/connect/token`	The data service and its token endpoint
`ENTSOE_API_TOKEN`	empty	Security token of an account at transparency.entsoe.eu, for the PICASSO/MARI prices behind reBAP module 1. Settable from the console; never shown
`KUNDEN_AUFSCHLAG_CT_KWH`	empty	The customers’ Aufschlag on the day-ahead spot price, in ct/kWh on the energy (net). With it, the calculation in the Fahrplan/Ist tab shows revenue and margin. Settable from the console (group “Kalkulation”)
`ENTSOE_BASE_URL`	`https://web-api.tp.entsoe.eu/api`	The Transparency Platform’s API
`MAKOFLOW_CACHE_MIN_REFRESH_SECONDS`	`120`	Reads of the same stream within this pause are served from the store instead of re-fetching the overlap; one request or orchestrator tick reads a stream many times. Our own sends lift the pause

Trader sFTP

Variable	Default	Meaning
`SFTP_HOST` / `SFTP_PORT`	— / `22`	Trader’s sFTP server
`SFTP_USERNAME`	—	Login user
`SFTP_PASSWORD`	unset	Password auth
`SFTP_PRIVATE_KEY_PATH`	unset	Key-file auth (alternative to password)
`SFTP_TARGET_DIR`	`/upload`	Drop directory for the open-position CSV
`SFTP_HOST_KEY`	unset	Pinned server host key, one `known_hosts`-style line (`<host> <keytype> <base64>`). When set, connections to a server presenting any other key are refused; when unset, the first-seen key is accepted (legacy behavior).
`FORECAST_HORIZON_DAYS`	`4`	How many days ahead the trader gets a CSV (D+1 to D+n) — backup series and generated forecasts both reach this far
`CUSTOMER_NOTIFICATION_EMAIL`	unset	Where the Day-ahead watch agent’s customer notification goes (the `kunden-hinweis` tool, sent on a person’s approval); unset = the tool is refused

Erstkontakt mailbox (SMTP)

Variable	Default	Meaning
`SMTP_HOST` / `SMTP_PORT`	— / `587`	Submission server of the Erstkontakt mailbox
`SMTP_USERNAME` / `SMTP_PASSWORD`	unset	Login (password is a secret, write-only in the console)
`SMTP_FROM`	—	Sender address, e.g. `mako@customer.example`
`SMTP_STARTTLS`	`true`	STARTTLS on the submission port
`ERSTKONTAKT_SUBJECT`	see config	Subject template (`{company}`, `{bkv_mp_id}` placeholders)
`ERSTKONTAKT_MAX_PER_RUN`	`100`	Cap per send run — staggered sending protects sender reputation
`IMAP_HOST` / `IMAP_PORT`	— / `993`	Reading side of the same mailbox (TLS). Username/password fall back to the SMTP login when unset (`IMAP_USERNAME` / `IMAP_PASSWORD`)
`IMAP_FOLDER_INBOX` / `IMAP_FOLDER_ARCHIVE` / `IMAP_FOLDER_SENT`	`INBOX` / `Archive` / `Sent`	Folder names — provider-specific; “Mail testen” reports missing ones and the folder the mailbox flags as its Sent folder (RFC 6154 `\Sent`). Where the mailbox refuses `IMAP_FOLDER_SENT`, a sent mail’s copy goes into that folder - or one of the usual names (Sent Items, Gesendete Elemente, …) - and the event `mail_ablage_umgeleitet` says so. A folder the mailbox lacks altogether is created on first use and subscribed (a new mailbox holds only INBOX), under the server’s prefix (NAMESPACE, e.g. `INBOX.`) where it keeps one; the event `imap_ordner_angelegt` names it
`MAILBOX_LOOKBACK_DAYS`	`90`	How far back the folders are scanned
`MAILBOX_ARCHIVE_PROCESSED`	`true`	File handled inbox messages (Bestätigung, Bounce, Abwesenheit) into the archive folder
`AUTO_NACHVERSAND`	`true`	Carry out a partner’s written resend request (“bitte erneut senden”) from the mailbox reconciliation: PARTIN and/or ZOE, whichever went out before the mail and is still unacknowledged. Only on a confident LLM verdict; otherwise a Wiedervorlage
`RAHMENVERTRAG_STATUS_GESCHLOSSEN`	`["Vertrag geschlossen"]`	Values of the contract column in the customer’s VNB-Kampagne sheet that mean a Lieferantenrahmenvertrag is in place (case-insensitive). See PARTIN – Google-Sheet sync
`SLACK_PROTOKOLL_WEBHOOK_URL`	–	Incoming-webhook URL of a Slack app for the channel shared with the customer: every interaction of the bridge is posted there once (see Console – interaction log). Secret, write-only in the console. Separate from the alerting `SLACK_WEBHOOK_URL`
`SLACK_PROTOKOLL_AKTIV`	`true`	Switch for the feed
`SLACK_PROTOKOLL_INTERVALL_MINUTEN`	`60`	Post at most this often; the orchestrator ticks every 15 minutes
`SLACK_PROTOKOLL_START`	–	Where the very first run starts (ISO, UTC); empty: now. The history before was posted as weekly logs
`ANTHROPIC_API_KEY`	unset	Enables LLM classification of replies via the Claude API (secret, write-only). Empty = regex classifier only
`CLASSIFIER_MODEL`	`claude-opus-5`	Model for reply classification
`AGENT_MODEL`	`claude-opus-5-5`	Model for a process agent’s round, unless the agent’s definition names one (`behaviour.model`); same key
`CLASSIFIER_MIN_KONFIDENZ`	`0.7`	Below this confidence nothing is automated — the mail becomes a Wiedervorlage with the model’s reading attached

LLM reply classification: with a key set, every reply is read by the Claude API, which returns a strict verdict (bestätigt / Rückfrage / abwesend / unzustellbar / Empfangsbestätigung / Ablehnung / sonstiges) with a verbatim Beleg quote and a confidence. The model only labels — all actions stay in the bridge, which verifies the quote appears literally in the mail (and is not a sentence of our own template), only forwards to Vertreter addresses that literally occur in the mail, and demotes anything below the confidence bar to a Wiedervorlage. On API failure the regex classifier takes over (classifier_degraded event); LLM/regex disagreements are logged (classifier_disagreement). Replies are processed, not answered: the mailbox reconciliation adopts hand-sent Erstkontakt mails from Sent/Archive into the ledger, forwards the original mail to a Vertreter named in an Abwesenheitsnotiz — only while the Erstkontakt is still outstanding; a note answering a Quittungs-Nachfass or Korrektur mail, or from a partner already past Erstkontakt, becomes a Wiedervorlage with faellig_am read from the note (“bis einschließlich 04.09.” → due on the 5th) and nothing is forwarded — and files bounces and vertreterlose Abwesenheiten as Wiedervorlagen. The mail body ships with the package (data/erstkontakt_vorlage.txt), recipient addresses come from the BDEW code list (data/nb_kontakte.json), and the attached Kontaktdatenblatt (XLSX) is rendered from the PARTIN_COMPANY settings. PARTIN_COMPANY is our company’s record for every role, not only the PARTIN: VAT_ID holds a German USt-IdNr. or, for a company seated in Switzerland, its UID (CHE-...). Beside the PARTIN fields it carries what only the Kontaktdatenblätter print: fax, glaeubiger_id, geschaeftsfuehrung_name / geschaeftsfuehrung_email, edifact_email (the address the EDIFACT exchange runs over) and bilanzkreise_hinweis (say, an Unterbilanzkreis applied for whose EIC is still to come).

Lieferant

Every market role writes from a mailbox of its own. The Lieferant’s settings carry the prefix LF_ and are grouped as Lieferant in the console; the passwords are write-only there.

Variable	Default	Meaning
`LIEFERANT_MP_ID`	the customer’s	Our MP-ID as Lieferant; also the default Lieferant of a Zuordnungsermächtigung
`LF_SMTP_HOST` / `LF_SMTP_PORT` / `LF_SMTP_USERNAME` / `LF_SMTP_PASSWORD` / `LF_SMTP_FROM` / `LF_SMTP_STARTTLS`	— / `587` / — / — / — / `true`	Submission server and sender of the Lieferant’s mailbox
`LF_IMAP_HOST` / `LF_IMAP_PORT` / `LF_IMAP_USERNAME` / `LF_IMAP_PASSWORD`	— / `993` / — / —	Reading side of the same mailbox; username and password fall back to the SMTP login
`LF_IMAP_FOLDER_INBOX` / `LF_IMAP_FOLDER_ARCHIVE` / `LF_IMAP_FOLDER_SENT`	`INBOX` / `Archive` / `Sent`	Its folders; the Sent folder falls back, and a missing folder is created, like the BKV’s. “Mail testen” in the console’s Lieferant tab (`POST /v1/process/lrv/postfach/pruefen`) reports missing ones and the mailbox’s own Sent folder
`LRV_MIN_KONFIDENZ`	`0.8`	Below this confidence the reading of a Netzbetreiber’s answer leads to no step; a person decides
`LRV_NACHFASS_WERKTAGE` / `LRV_ESKALATION_WERKTAGE`	`5` / `10`	Werktage without an answer before the one Nachfass, and before a person is asked; the escalation lies after the Nachfass
`LRV_KONTAKTFUNKTIONEN_GV` / `LRV_KONTAKTFUNKTIONEN_DV`	`["Z11","Z13","Z10"]` / `["Z11","Z16","Z13","Z10"]`	Whom a request goes to: the contact blocks of the Netzbetreiber’s PARTIN by NAD qualifier, first match wins (PARTIN AHB 1.1: Z11 Rahmenverträge - sent to a Lieferant only -, Z16 Einspeiseprozesse, Z13 Wechselprozesse, Z10 Übertragungsweg)

Inbound API scopes and audit

Variable	Default	Meaning
`EXTERNAL_API_KEY`	unset	The customer’s key — grants the data-delivery endpoints
`PROCESS_API_KEY`	unset	Internal key — grants the `/v1/process/*` endpoints (and everything external)
`REPORT_API_KEY`	unset	Status key — grants the status endpoints (market partner overview, Zeitreihen) and the sheet snapshots a spreadsheet script sends (Rahmenverträge, Kundenhochlauf), which are stored and send nothing themselves. Exception: the Kundenhochlauf counts scale the CSV-only backup series the orchestrator writes to the trader’s sFTP. Hand it to a spreadsheet script or dashboard, not to anyone who must not influence those files
`EXTERNAL_API_KEYS`	unset	Several named keys: `name:secret,name:secret`
`PROCESS_API_KEYS`	unset	Same, for the process scope
`REPORT_API_KEYS`	unset	Same, for the report scope
`SANDBOX_API_KEY`	unset	Sandbox key — same endpoints as external, but every call is forced into validate-only mode: full validation, nothing stored, nothing toward the market
`SANDBOX_API_KEYS`	unset	Same, several named keys: `name:secret,name:secret`
`DASHBOARD_API_KEY`	unset	Dashboard key — `/v1/dashboard` and nothing else, read-only: a day’s or a month’s forecast, schedule, allocation and reBAP for the customer’s screens (Dashboard data)
`DASHBOARD_API_KEYS`	unset	Same, several named keys: `name:secret,name:secret`
`ALLOW_UNAUTHENTICATED`	`false`	Development escape hatch — see below
`MOBILE_API_KEY_HASHES`	unset	Operator-app device keys as hashes only: `mobile-<handle>-<device>:<sha256 hex>,…`. A malformed value stops startup — check it with `scripts/validate_mobile_key_hashes.py` first. See Operator app
`MOBILE_RATE_LIMIT_PER_MINUTE` / `MOBILE_RATE_LIMIT_BURST`	`30` / `10`	Per-device token bucket for `/v1/mobile`, separate from the other callers’
`MOBILE_MIN_APP_VERSION`	`0.1.0`	Apps below this version (`MAJOR.MINOR.PATCH`) show “Bitte aktualisieren”
`MOBILE_STALE_AFTER_SECONDS` / `MOBILE_EXPIRE_AFTER_SECONDS`	`1800` / `21600`	The apps add “Stand HH:MM” after the first, show grey after the second
`MOBILE_HEARTBEAT_STALE_AFTER_SECONDS`	`1200`	The app reports the orchestrator’s timer as stopped after this long without a call; follows `orchestrateCron`
`API_DOCS_ENABLED`	`false`	Serve `/docs`, `/redoc` and `/openapi.json`. They list every internal route — development only
`AUDIT_DIR`	`data/audit`	Root directory of the audit trail

With no credential configured the service refuses the authenticated routes with 503 rather than serving them openly. /health stays reachable so the platform can still schedule the app. Set ALLOW_UNAUTHENTICATED=true only on a developer machine; the service announces it in the event log every time it starts.

See Security for the full model — named callers, rotation, OIDC and rate limiting.

Alerting

Variable	Default	Meaning
`SLACK_WEBHOOK_URL`	unset	Slack incoming webhook (the URL is the credential)
`PUSHOVER_APP_TOKEN` / `PUSHOVER_USER_KEY`	unset	Both required before the channel exists
`PUSHOVER_DEVICE`	unset	Limit alerts to one device
`PUSHOVER_RETRY_SECONDS` / `PUSHOVER_EXPIRE_SECONDS`	`300` / `3600`	Emergency repeat interval and give-up time
`TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN`	unset	Twilio credentials for SMS
`TWILIO_FROM` / `TWILIO_TO`	unset	Sender (number or alphanumeric ID) and comma-separated E.164 recipients
`SLACK_MIN_PRIORITY` / `PUSHOVER_MIN_PRIORITY` / `SMS_MIN_PRIORITY`	`-2` / `0` / `2`	Priority each channel starts at
`GATE_CLOSURE_LOCAL_TIME`	`14:30`	Day-ahead deadline in local market time, `HH:MM`. Anything else is refused: at startup, and with `422` in the console
`GATE_CLOSURE_WARN_MINUTES`	`60`	Lead time for the unsubmitted-day alarm, 0–720
`TRADER_DEADLINE_LOCAL_TIME`	`09:00`	When the trader orders the day ahead from the CSV it holds, `HH:MM` local. Refused like the gate closure when malformed
`TRADER_DEADLINE_WARN_MINUTES`	`60`	Lead time for the alarm that the day ahead still runs on the backup series (or has nothing), 0–720
`VERTRAG_WARNSCHWELLE_PROZENT`	`80`	From what share of a contract’s limit a forecast’s acknowledgement warns: the TSO’s maximum power per quarter-hour, the trader’s maximum per day. Settable from the console (group “Fahrplan”); see Contracts
`FORECAST_NUR_GANZE_KW`	`false`	A customer forecast must be in whole kW (MW with at most three decimals). Off: one with fractions of a kW is taken over, with `warnings` in the acknowledgement and the event `forecast_nicht_in_ganzen_kw`; on: it is refused with `422`. The bridge’s own backups and generated forecasts are rounded to whole kW when made. Settable from the console (group “Fahrplan”)

See Alerting for what pages and what stays quiet.

In the Azure deployment all of these are wired up by the Bicep template — secrets as Container Apps secrets, the audit directory on an Azure Files mount, and the orchestrator timer with the process key. See Azure deployment.

Implementing the Service

Running the Service

Reference

Internal API

Market setup

Engrate

Market communication

Trader sFTP

Erstkontakt mailbox (SMTP)

Lieferant

Inbound API scopes and audit

Alerting

​Market setup

​Engrate

​Market communication

​Trader sFTP

​Erstkontakt mailbox (SMTP)

​Lieferant

​Inbound API scopes and audit

​Alerting

Market setup

Engrate

Market communication

Trader sFTP

Erstkontakt mailbox (SMTP)

Lieferant

Inbound API scopes and audit

Alerting