Levandor

Agent Context — Alpiq BESS

3 min read

Agent Context — Alpiq BESS (Mando)

Purpose

Dense reference for AI agents to quickly gather project context. Load this file first when working on any Mando crate.

Identity

  • Project: Battery Energy Storage System optimization platform
  • Org: Alpiq, Sales & Origination / Flexible Assets
  • Repo: sales-and-origination/flexible-assets/bess/poc/mando (GitLab)
  • Source path: /Users/andras/coding/alpiq_cicd/sales-and-origination/flexible-assets/bess/poc/mando
  • Language: Rust 1.88.0 (edition 2021) + Python 3.12 via PyO3
  • Version: 1.4.11
  • Main branch: develop

Workspace Crates

CrateTypePurpose
mando-liblibCore: data models, repos (PG/DuckDB/SQLite), service trait, adapters (Alpiq/Volue/Fingrid), flows, validation
mando-lib-macroproc-macro#[derive(ErrorCode)] — maps error enum variants to static string codes
mando-bessbinREST API (Axum 0.8.7, port 8080): routes, flow execution, scheduling, auth (JWT/Entra ID)
py-mandocdylibPyO3 extension: algo params, DataFrame ops, algo runner HTTP server, adapters for Python
mando-scrtbinRust-based Python runtime: virtual module injection, Arrow FFI streaming, memory-safe algo hosting (PyO3 auto-initialize)
mando-clibinYAML-driven workflow orchestrator: recipes, docker compose, interactive prompts, state replay (standalone repo)

Key Abstractions

MandoService (async trait)
├── retrieve / retrieve_at / retrieve_history — read data points
├── insert — write data points
├── retrieve_catalog — list available data points
└── send — push data externally

Repository (trait) → DataPointRepository, CacheRepository
├── RepositoryPostgres    (production)
├── RepositoryDuckDb      (analytics/OLAP)
├── RepositorySqlite      (local dev)
└── RepositoryPassthrough  (caching layer)

DataPointId = hierarchical path: "Asset/FI/Battery/SoC" → ["Asset","FI","Battery","SoC"]
DataPointType = TimeSeriesDouble | TimeSeriesDoubleMatrix | StaticData
DataPointFilterQueryMode = ORIGINAL | OVERRIDE | MERGED

Feature Flags (mando-lib)

FlagEnables
appAxum + OpenTelemetry (used by mando-bess)
codegenCode generation with CSV
pythonPyO3 classes/functions
workflowFlow execution engine

Flow Engine

Versioned workflows for BESS trading strategies:

  • Trading (v1) — market trading
  • Manual Schedule (v1, v2) — operator schedules
  • Auction (v3) — auction bidding
  • Intraday / IDC Trading — intraday ops
  • Data Update — data pipelines
  • AFRR — frequency restoration reserve

External Integrations

SystemAdapterPurpose
Azure Entra IDEntraIdClientAuthentication
Alpiq EBSadapter/alpiq/Energy Balance System
Alpiq MDRadapter/alpiq/Market Data Repository
Alpiq OPLadapter/alpiq/Operations Planning
Volue EMSadapter/volue/Energy Management System
Volue ATPadapter/volue/Token provider
Fingridadapter/fingrid/Finnish market data

Tech Stack Summary

LayerTechnology
WebAxum 0.8.7, Tower middleware
DataPolars 0.49.1, Arrow 56.2.0
DBPostgreSQL (deadpool), DuckDB 1.4.2, SQLite (rusqlite)
AuthJWT (RS256), Entra ID, Volue EMS/ATP
PythonPyO3 0.25.1, pyo3-polars 0.22.0, Maturin 1.9.2
ObservabilityOpenTelemetry 0.30.0 (OTLP/gRPC), tracing
API docsutoipa + Scalar UI
GraphQLcynic 3.12.0 + graphql-ws-client
Serializationserde, serde_json, serde_yaml, Apache Avro
Error handlingthiserror + custom #[derive(ErrorCode)]

mando-bess Routes

EndpointMethodPurpose
/query_data—Read data points
/save_data—Write data points
/flow/{id}—Manage flows
/flow_executions—List executions
/flow_executions/{asset_id}—Asset executions
/audit_logs—Audit trail
/settings—Configuration CRUD
/versions—Component versions

Build Commands

cargo build                         # Build workspace
cargo test                          # Run tests
cd mando-bess && cargo run          # Run service (port 8080)
cd py-mando && maturin develop      # Build Python extension

CI/CD

  • Platform: GitLab CI
  • Stages: Security (Snyk) → Container → Setup → Build/Test → Publish → Release → Pages
  • Branching: feature/*, bugfix/*, develop → Dev ECR; release/* → Prod ECR
  • Runtime image: debian:13.1-slim with libssl3, samba-libs, bundled libduckdb.so

File Layout

mando/
├── mando-lib/src/          # 13 subdirs: adapter/, audit/, bess/, model/, util/, workflow/, ...
├── mando-bess/src/         # flow/ (9 subdirs), route/ (7 modules), database/, model/
├── mando-lib-macro/src/    # Single lib.rs
├── py-mando/src/           # 12 modules: algo, polars, adapter, data_point, ...
├── assets/                 # Test data
├── lib/libduckdb/          # Bundled DuckDB 1.4.2
├── scripts/                # Benchmarks, load tests, seed data
└── test/                   # Integration tests

Graph View

Backlinks