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 MWh; MW 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`
`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 switches — PARTIN, Zuordnungsermächtigung and the APERAK acknowledgements:

Variable	Default	Meaning
`AUTO_ANSWER_PARTIN`	`false`	Answer every incoming PARTIN with our datasheet, on the orchestrator
`AUTO_ZOE`	`false`	Grant the standing Zuordnungsermächtigung selection once the PARTIN exchange is mutual
`AUTO_APERAK`	`true`	Acknowledge every received message with an APERAK Anerkennungsmeldung — the answer the AHB owes each sender
`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, so the shared-account scoping holds
`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`	`120`	Store horizon; a deeper lookback falls through to the API for the missing history

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).

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@cloover.com`
`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
`MAILBOX_LOOKBACK_DAYS`	`90`	How far back the folders are scanned
`AUTO_MAILBOX`	`true`	Reconcile the mailbox on every orchestrator run (once `IMAP_HOST` is set)
`MAILBOX_ARCHIVE_PROCESSED`	`true`	File handled inbox messages (Bestätigung, Bounce, Abwesenheit) into the archive folder
`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
`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.

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	Read-only key — grants only the status endpoints (market partner overview). Safe to hand to a spreadsheet script or dashboard
`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`
`ALLOW_UNAUTHENTICATED`	`false`	Development escape hatch — see below
`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
`GATE_CLOSURE_WARN_MINUTES`	`60`	Lead time for the unsubmitted-day alarm

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)

Inbound API scopes and audit

Alerting

​Market setup

​Engrate

​Market communication

​Trader sFTP

​Erstkontakt mailbox (SMTP)

​Inbound API scopes and audit

​Alerting

Market setup

Engrate

Market communication

Trader sFTP

Erstkontakt mailbox (SMTP)

Inbound API scopes and audit

Alerting