Model/services/ara/README.md

ara

The Domna retrofit modelling backend. Replaces the legacy backend/engine/engine.py monolith with a service-oriented pipeline that survives the 30 May 2026 gov EPC API cut-over and that other team members can read, fix, and extend.

Design document: ../../ara_backend_design.md. Domain glossary: ../../CONTEXT.md.

Layout

src/ara/
├── services/        # the 9 domain services from PRD §9.2:
│                    #   EpcRemappingService, EpcPredictionService,
│                    #   FeatureBuilder, EpcEnergyDerivationService,
│                    #   RebaseliningService, RecommendationService,
│                    #   ImpactPredictionService, OptimiserService,
│                    #   ValuationService, ResultsPersister
├── orchestrators/   # IngestionPipeline, ModellingPipeline, RefreshOrchestrator
└── lambdas/         # one handler.py per Lambda + the event-shape contracts

Pipeline

See PRD §9.4 for the per-batch step order. Briefly: per-property setup (steps 1–6) runs once per Property; the per-scenario × per-phase loop (steps 7–10) re-derives candidates and impact predictions against the rolling Effective EPC state; results are persisted under one Unit of Work per (Plan, Scenario).

Testing

• tests/unit/ — service tests against fakes from tests/fakes/. No DB, no network, no ML lambda.
• tests/integration/ — real Postgres (testcontainers / localstack), fake fetchers + fake ML lambdas.
• ML transform contract tests live with domain.ml.transform in packages/domain/.