OPF API

Dispatcher Brains API Manual

Overview

Dispatcher Brains is the standalone decision engine for the OPF BESS platform. It is responsible for assembling a normalized decision request, validating inputs, optimizing charge and discharge schedules, checking physical and operational safety, persisting decisions, and returning the decision payload to the rest of the platform.

This service is intentionally safety-first and does not directly publish commands to field devices. Execution is authorized through a guarded policy interface, but actual device-triggering remains disabled unless an external execution layer explicitly implements it under a separate contract.

The canonical runtime data model is built around PostgreSQL persistence and InfluxDB-backed telemetry reads. MongoDB is legacy-only and is not the active source of truth for the brains decision pipeline.

Purpose and Scope

The brains service exists to answer a single operational question:

"Given the current site state, forecast, market conditions, and safety constraints, what is the safe and explainable battery schedule for the next decision horizon?"

Its responsibilities include:

• validating request structure and input quality
• assembling site, forecast, market, weather and reserve inputs
• computing a deterministic schedule with a constrained optimization step
• re-validating the schedule against physical and operational safety rules
• persisting decision metadata, KPI records, slots and overrides
• exposing decision lifecycle states and authorization hooks
• producing explainable results and safe fallback decisions when inputs are stale, invalid or infeasible

It does not replace the dispatcher-agent or the field execution layer. It produces decisions, not direct device control.

System Boundary

The brains service sits between:

• upstream data adapters and persistence layers
• site and market input providers
• a planning and optimization engine
• an execution authorization layer
• downstream UI and orchestration consumers

The service boundary is intentionally narrow:

• it reads normalized inputs
• it computes decisions
• it persists auditable results
• it exposes policy and authorization endpoints
• it never executes device commands by itself

Runtime Architecture

Core runtime components

• app.main
• FastAPI application bootstrap
• startup/shutdown lifecycle logging
• router registration

• app.api
• all HTTP endpoints and orchestration flows
• health, readiness, decision assembly, execution authorization, forecasts, KPI listing and lifecycle transitions

• app.config
• runtime configuration and production validation
• readiness summary for Postgres, InfluxDB and solver timeouts

• app.domain.models
• decision request and domain contracts

• app.input_assembly
• building a normalized request from market, weather, forecast and telemetry inputs

• app.input_quality
• input acceptance, stale-data detection and validation checks

• app.optimization.optimizer
• deterministic optimization routine for charge/discharge scheduling

• app.optimization.balancing
• reserve allocation logic

• app.safety.validator
• independent safety check after optimization

• app.persistence.repository
• PostgreSQL storage for decisions, overrides, KPIs, slot candidates and audits

• app.persistence.adapters
• adapters for PostgreSQL and InfluxDB-backed reads

• app.execution
• execution policy and authorization

• app.orchestrator
• slot candidate resolution and due-candidate selection

• app.forecasting.baseline
• baseline metrics and forecast quality evaluation

Canonical operational model

The service uses one consistent sign convention for battery power:

• positive battery_power_kw = discharge
• negative battery_power_kw = charge
• zero battery_power_kw = idle

This remains consistent across optimization, safety validation and persisted decision output.

Decision Lifecycle

A decision usually follows this path:

1. client sends a normalized decision request with x-account-id
2. service validates required account and payload fields
3. request is assembled from source data and quality checks
4. optimization runs deterministically
5. reserve allocation and independent safety validation are applied
6. a valid decision is persisted to PostgreSQL
7. slot candidates are generated and saved
8. KPIs are recorded
9. the response returns the decision object or a fallback explanation

Accepted and rejected transitions are stored with account scope and audit metadata.

Request and Response Model

Required HTTP headers

All relevant endpoints require the x-account-id header. The service checks it at the API boundary before performing action-specific logic.

Decision request contract

The decision request carries the normalized site context, time horizon, battery state, forecast values, prices, physical limits and safety assumptions needed for optimization.

The model includes fields such as:

• account and site identity
• request id and idempotency key
• decision mode
• time horizon start and end
• SoC and reserve constraints
• charge/discharge power limits
• efficiency assumptions
• market and price inputs
• forecasts and site metadata

If the same request is submitted repeatedly with the same account, site and idempotency key, the service returns the previously stored decision instead of recalculating it.

Decision response structure

A successful decision response contains:

• decision_id
• request_id
• site_id
• status
• mode
• generated_at
• algorithm_version
• solver_status
• objective_value
• schedule
• warnings
• constraints
• explanation
• fallback

Fallback responses are used when optimization fails or a request is rejected for safety or quality reasons. These remain structured and auditable rather than silent failures.

API Endpoints

GET /health

Returns liveness information for the service.

Example response:

{
  "status": "ok",
  "service": "dispatcher-brains",
  "environment": "production"
}

GET /ready

Returns a readiness summary and dependency status.

Example response:

{
  "status": "ready",
  "service": "dispatcher-brains",
  "environment": "production",
  "dependencies": {
    "postgres": {"configured": true},
    "influxdb": {"configured": true},
    "secrets": {"production_safe": true},
    "solver": {"valid_timeout": true}
  }
}

GET /v1/execution/policy

Returns execution policy metadata. The service explicitly reports:

• automatic_enabled
• emergency_stop
• supported modes
• device_publishing: false

This is a key safety contract: the brains service does not by itself push device commands.

POST /v1/execution/authorize

Authorizes an execution request under the service policy. This endpoint logs an execution audit event and returns whether the command is allowed and the associated command id.

Input shape is an execution request containing:

• decision_id
• site_id
• mode
• status
• command metadata

The endpoint never publishes a device command to hardware.

POST /v1/decisions

Creates one normalized decision.

Operation:

• validates x-account-id
• rejects duplicate idempotent requests for the same site and key
• optimizes the schedule
• runs safety checks
• records KPI and decision data
• returns the decision or a structured fallback

POST /v1/decisions/assemble

Assembles and validates the decision inputs without immediately performing the full optimization cycle.

It accepts a payload object containing the site, horizon, price, market, forecast and telemetry context. It returns:

• accepted: boolean
• quality summary
• assembled normalized request

This endpoint is used for input quality inspection and pre-flight validation.

POST /v1/decisions/cycle

Runs the decision assembly path and immediately performs the standard safe decision pipeline.

This is the service’s main full-cycle orchestration endpoint for planning runs.

GET /v1/decisions

Lists recent decisions for an account and optional site filter.

GET /v1/kpis

Returns recent KPI rows and aggregates for the caller account and site.

Typical KPI categories include:

• solver_duration
• cost
• revenue
• decision lifecycle outcomes
• aggregate metrics derived from persisted records

POST /v1/forecasts/evaluate

Evaluates forecast quality using actual and predicted series.

Example payload:

{
  "actual": [1.0, 2.0, 3.0],
  "predicted": [1.1, 1.9, 3.2],
  "thresholds": {
    "mape_max": 15.0,
    "mae_max": 0.5
  }
}

Returns forecast metrics and a quality result.

POST /v1/orchestration/resolve

Resolves due slot candidates using the stored candidate queue and the current time. This path selects only top-priority due slots, while still keeping device execution disabled.

The endpoint returns:

• resolved candidates
• executed: []
• device_publishing: false

POST /v1/decisions/{decision_id}/transition

Transitions a decision between lifecycle states, such as queued, approved, rejected, cancelled or completed, depending on the business policy. This is persisted with account scope and audit information.

POST /v1/decisions/{decision_id}/override

Stores a manual override record and associated reason/actor metadata.

Data Stores

PostgreSQL

The project’s canonical persistence layer is PostgreSQL. It stores:

• decisions
• decision status transitions
• overrides
• slot candidates
• execution audit records
• KPI values
• model and forecast metadata
• idempotent request tracking

The repository boundary is implemented in app.persistence.repository.

InfluxDB

InfluxDB is the telemetry and time-series data source for live normalized readings and measurement history. It is used for assembled decision inputs rather than as the replacement for PostgreSQL persistence.

MongoDB

MongoDB is not the authoritative data source for the modern brains workflow. It is treated as a legacy or transitional store only. The canonical architecture is PostgreSQL + InfluxDB.

Safety and Execution Rules

The brains service is deliberately conservative.

Safety principles

• no automatic device control by default
• explicit execution policy required before any command is allowed
• optimizer schedule must pass an independent validation step
• stale telemetry is rejected before optimization
• fallback decisions are returned when conditions are poor or safety checks fail
• execution authorization is audited and linked to a decision

Execution policy

The runtime config sets:

• automatic_mode = false
• emergency_stop = false

This means the service does not directly start automatic charging or discharging without an explicit higher-level policy flow.

Validation stages

1. input quality assessment
2. request assembly
3. deterministic optimization
4. reserve allocation
5. safety validation
6. persisted decision creation
7. candidate generation and KPI persistence

If safety validation fails, the engine returns a fallback rather than an unsafe plan.

Configuration

Runtime properties are defined in app.config.Settings, with environment values loaded from the local environment or .env file.

Key settings include:

• service_name
• port
• environment
• postgres host, db, user and password
• influxdb URL, token, org and bucket
• solver_timeout_seconds
• automatic_mode
• emergency_stop

The production validator rejects unsafe default secrets and invalid solver timeouts.

A readiness check evaluates:

• Postgres configuration
• InfluxDB configuration
• production secret strength
• solver timeout validity

Local Development

Run from the brains directory:

python3.12 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
uvicorn app.main:app --reload --port 3010

Check health:

curl http://127.0.0.1:3010/health
curl http://127.0.0.1:3010/ready

Run tests:

pytest

Or use the project compose stack from the repository root:

docker compose build dispatcher_brains
docker compose up -d dispatcher_brains
docker compose exec -T dispatcher_brains wget -qO- http://127.0.0.1:3010/health

Operational Notes

Decision quality gates

The request assembly flow evaluates all relevant quality signals before optimization. If key telemetry is stale or malformed, the system can reject the request and return a structured outcome instead of feeding a dangerous schedule downstream.

A/B and pilot readiness

The brains service supports local repo-controlled validation, but pilot deployment, contract validation and external device execution remain outside this repository’s direct control. The service is production-aware but intentionally prevents operation beyond validated internal logic.

Litgrid and external integrations

The codebase already documents the need for a formal Litgrid IEC 60870-5-104 implementation. That work depends on the official point map, IDs, protocol mapping and production test endpoint, and is not considered a local repository-only task.

Key Risks and Guardrails

• invalid or stale inputs are not silently accepted
• optimization is not trusted without independent safety validation
• device execution remains disabled unless a higher-level contract explicitly authorizes it
• cross-account separation is enforced through account-scoped persistence and API checks
• all critical decision paths are persisted for audit and settlement review

Summary

Dispatcher Brains is a repository-controlled decision engine for safe battery scheduling. It is designed to be deterministic, explainable, auditable and operationally conservative. In its current architecture, it provides strong local gatekeeping and optimization logic, while keeping actual device execution under a separate, policy-controlled layer.

This is the correct architecture for a production-ready BESS decision service: compute safe decisions locally, persist them clearly, and require explicit external authorization before movement of real-world assets occurs.

Complete Project Technical Reference

This section consolidates the implementation information from the service README, Phase 5 execution policy, ordered migrations, work-order status and the current source tree. It is intended to be the technical reference for operators, integrators and developers using the public manual.

Service Components

The Python package is organized around these ownership boundaries:

The service is packaged as opf-dispatcher-brains for Python 3.12 or newer. Runtime dependencies include FastAPI, Uvicorn, Pydantic Settings, SciPy, psycopg, InfluxDB Client and scikit-learn. Test dependencies include pytest and HTTPX.

End-to-End Data Flow

1. dispatcher-agent, opf-api or an internal scheduler submits a request with an authenticated account scope.
2. The input assembly path reads or receives site state, telemetry, forecasts, weather, prices, market commitments and reserve data.
3. Quality gates check timestamps, timezone, completeness, finite numeric values, stale telemetry and source quality.
4. The domain model validates the normalized request and all physical ranges.
5. The optimizer calculates a deterministic schedule with mutually exclusive charge/discharge decisions.
6. Reserve allocation adjusts the schedule without violating the battery model.
7. The independent safety validator checks every slot again.
8. A valid decision, snapshot, slot candidates, transition information and KPI values are persisted to PostgreSQL.
9. The caller receives a calculated schedule, warnings, explanations and objective values.
10. The dry-run orchestrator may select one due candidate per 15-minute slot, but selection is not execution.

Versioned Decision Contract

The canonical example is contracts/decision-v1.request.example.json. A request contains:

All timestamps must be timezone-aware. Numeric values must be finite and physically meaningful. Slot boundaries must align with the requested horizon. Invalid contract data returns a validation error instead of entering optimization.

Physical Battery Model

The canonical power convention is:

• battery_power_kw > 0: discharge; stored energy decreases.
• battery_power_kw < 0: charge; stored energy increases.
• battery_power_kw == 0: idle.

For a slot with duration duration_h:

discharge_delta_kWh = -(power_kW * duration_h / discharge_efficiency)
charge_delta_kWh = abs(power_kW) * duration_h * charge_efficiency

The model checks capacity, minimum and maximum SoC, reserve SoC, charge and discharge power, ramp rate, temperature and grid import/export limits. The physical model is independent from the optimizer so a solver result cannot bypass safety validation.

Optimization Behavior

The optimizer is deterministic and uses a constrained SciPy-based formulation. Charge and discharge are mutually exclusive in each slot through binary mode gates. The objective can combine:

• energy cost minimization
• peak reduction
• PV self-consumption
• day-ahead or intraday market revenue
• balancing reserve value
• degradation cost

Negative market prices are handled explicitly. Solver status, duration, objective components and binding constraints are returned. A solver timeout, infeasible model or failed safety validation produces an idle/fallback outcome with warnings rather than an unvalidated schedule.

Input Quality and Fallbacks

Quality checks are performed before optimization and include:

• required horizon and site fields
• timezone-aware timestamps
• finite numeric values
• slot alignment
• telemetry freshness
• explicit telemetry quality flags
• missing forecast or market values
• source completeness and range checks

An accepted quality result can still contain warnings. A rejected quality result returns accepted: false from input assembly and does not optimize. A schedule that fails the independent validator returns a structured fallback with the failed safety constraints. This behavior prevents stale or malformed data from becoming an executable recommendation.

Phase 5 Execution Policy

Phase 5 implements guarded execution foundations only. The current modes are:

Authorization is rejected when any of these conditions is true:

• emergency stop is active
• automatic mode is disabled
• required approval is missing
• decision status is not executable
• telemetry is older than five minutes
• command expiry has passed
• device publishing has not been explicitly enabled

The configured default is DISPATCHER_BRAINS_AUTOMATIC_MODE=false. The brains service records and audits authorization decisions but never publishes MQTT commands. The dispatcher-agent owns any future command executor and feedback path.

15-Minute Candidate Resolution

Multiple independent schedules may exist for the same site and 15-minute slot. They are not overwritten or merged. The resolver chooses exactly one due candidate by descending priority:

Equal priorities resolve by newest candidate, then candidate ID. POST /v1/orchestration/resolve persists the selected winner and returns executed: [] and device_publishing: false. A selected candidate is a database resolution, not a device command.

Persistence and Migrations

PostgreSQL is the canonical decision store. Ordered migrations are:

The repository persists decision input snapshots, algorithm versions, schedules, transitions, overrides, candidate rows, execution authorization events, forecast metadata and solver/cost/revenue KPIs. PostgreSQL account scope is applied to reads, writes and transitions. Idempotency is keyed by account, site and idempotency key.

InfluxDB is the time-series source for telemetry reads and freshness-aware input assembly. It is not the decision audit store. MongoDB is a legacy or rollback source only and is not the canonical brains data path.

Forecasting

The current forecasting foundation includes:

• seasonal and baseline forecasts
• persisted linear model artifacts
• active-version loading
• forecast-run records
• training-sample persistence
• MAE, RMSE, bias and MAPE metrics
• prediction-interval coverage
• configurable threshold evaluation

Richer models, feature stores, scheduled retraining, drift detection, bias analysis, champion/challenger workflows, rollback automation and multi-site acceptance gates remain future work.

Markets, Balancing and Settlement

The current foundation supports:

• day-ahead and transparency input paths
• balancing A84/A60 input paths
• reserve allocation
• negative-price optimization behavior
• commitment validation
• revenue and settlement calculation helpers
• raw provider payload retention foundations

Provider-specific activation feedback, intraday/Nord Pool commitment workflows, recovery scheduling, imbalance reports, provider compliance mapping and forecast-versus-realized reconciliation require official provider contracts and validated response mappings.

API and Platform Integration

The public opf-api owns authentication, account and site management, telemetry ingestion, operator-facing API access and the public documentation site. It forwards internal decision work to dispatcher-brains and exposes the public API reference at https://api.opf.lt/.

The dispatcher-agent is the integration boundary for provider synchronization, MQTT site configuration and any future command execution. The dispatcher-room is the operator interface for fleet telemetry, decisions, approvals and controls. The brains service remains independent and does not publish directly to MQTT.

Security and Tenant Isolation

Every brains endpoint that accesses account data requires x-account-id. The current boundary enforces presence and applies account scope to persistence operations. Production deployments must additionally provide authenticated service identity and site-to-account authorization rather than trusting an arbitrary caller value.

Production configuration rejects default PostgreSQL and InfluxDB secrets and rejects non-positive solver timeouts. Rate limiting, TLS termination, dependency timeouts and resource limits are deployment responsibilities that must be completed for a production rollout.

Testing and Validation

The test suite covers:

• service scaffold and health/readiness behavior
• domain and API contract validation
• physical battery transitions
• optimizer and safety scenarios
• persistence and migrations
• adapter and lifecycle behavior
• forecasting, market and settlement foundations
• Phase 5 controls and execution gates
• slot priority resolution

Run the complete suite with:

pytest -q

The repository validation baseline has passed the brains regression suite. Production readiness still requires integration, load, adversarial, provider, device and pilot validation.

Current Completion Status

Complete locally

• versioned decision contract and strict domain validation
• deterministic physical model, optimizer and independent safety validator
• explanations, warnings and idle fallbacks
• PostgreSQL decision persistence and ordered migrations
• account-scoped idempotent decision handling
• lifecycle transitions, overrides and transition audit
• input assembly and quality-gated decision cycle
• forecast metrics, model artifact structure and training samples
• reserve allocation, commitment validation and settlement foundations
• KPI persistence and aggregation
• dry-run 15-minute slot priority resolution
• guarded execution authorization with automatic publishing disabled

Foundation exists but production work remains

• full telemetry aggregation and configuration discovery
• dispatcher-agent command and feedback loop
• role-aware lifecycle policy and complete operator playback UI
• scheduled forecast monitoring, richer ML and retraining
• complete intraday, balancing activation and provider settlement compliance
• edge buffering, replay protection, acknowledgements and reconnect behavior
• command traceability, dashboards, alerts and model drift detection

Blocked by external validation

• real device execution and BMS/EMS command contract
• provider activation and settlement certification
• Litgrid IEC 60870-5-104 point map, IOA profile and test endpoint
• HA, backup/restore, certificates, RPO/RTO and production ownership
• pilot sites, A/B acceptance, operator approval and rollback evidence

Litgrid IEC 60870-5-104

Litgrid integration is a separate edge handler and publisher work item. It must receive the official point map, IOA and type identifiers, common address, units, limits, acknowledgement rules, test endpoint and certification requirements before implementation can be validated. The intended behavior is to normalize Litgrid activation signals into 15-minute priority candidates and publish approved measurements, statuses and acknowledgements back to Litgrid with reconnect, timeout, duplicate protection, raw-payload audit and simulator tests.

Production Completion Criteria

A production rollout requires all of the following:

• reproducible decisions from input snapshots and algorithm versions
• deterministic physical and safety validation for every schedule
• documented fallback or rejection for unsafe, stale or incomplete inputs
• explicit execution authorization and automatic mode disabled by default
• tenant isolation for every read, write, transition and execution path
• raw provider payload, forecast version and realized result retention
• command-to-slot-to-acknowledgement-to-telemetry correlation
• TLS, service identity, rate limits, dependency timeouts and resource limits
• PostgreSQL and InfluxDB backup, restore, HA and disaster-recovery evidence
• staged recommendation-only, approval-required and limited-automatic pilot evidence
• rollback criteria, named site approval and operator sign-off

MCP Natural-Language Explanation Service

Work order 26 now has a local implementation: a separate MCP-compatible JSON-RPC service for operator and AI-client explanations of dispatcher-brains behavior. It is a read-only explanation layer over persisted decision facts and versioned project documentation. The service is available inside Compose as dispatcher_brains_mcp on port 3011 and exposes POST /mcp.

Planned read-only tools include:

• explain_decision: explain a persisted decision, its input snapshot, algorithm version, schedule, warnings and safety result.
• explain_decision_slot: explain why one 15-minute slot charges, discharges or remains idle.
• explain_fallback: explain input-quality rejection, optimizer failure or safety fallback.
• explain_execution_policy: explain current mode, hard gates, authorization status and why device publishing is disabled.
• explain_candidate_resolution: explain every candidate, priority, tie-break and selected winner for a slot.
• explain_brains: answer documentation-grounded questions about the architecture and technical behavior.
• brains_status: expose readiness, enabled modes, algorithm version and known limitations.

The service must enforce authenticated account and site scope, redact secrets and personal data, and identify the decision ID, source snapshot timestamp, algorithm version and source records used. Natural-language output is a presentation of authoritative facts; it cannot change the facts, safety status or execution status.

The MCP service must never provide tools for approval, override, lifecycle transition, candidate activation, command execution or MQTT publication. It must clearly distinguish a calculated decision, a selected dry-run candidate, an authorization result and an executed device command. Deterministic template explanations are required when an optional language-model provider is unavailable or times out.

The local implementation provides MCP initialize, tools/list and tools/call, account-scoped PostgreSQL decision/candidate readers, deterministic policy and documentation explanations, a health endpoint and focused protocol tests. Production service identity, complete redaction audit, provider timeouts and optional LLM integration remain hardening work.

Implementation, schema tests, tenant-isolation tests, redaction tests, provider-fallback tests and deployment documentation are tracked in 26-mcp-natural-language-explanations.prompt.md. Automatic execution remains disabled throughout this work.