Project Structure Reorganization

v2.6.0 - Project Structure Reorganization & Comprehensive Testing

🎯 Major Changes

Project Structure Reorganization

• Reorganized codebase into clear directory structure:
  • src/ - Core application modules (optimizer, models, price_analyzer, etc.)
  • tests/ - Test suite with test data
  • utils/ - Utility scripts
• Updated all imports to use new structure
• Updated Dockerfile for Lambda deployment
• Improved project maintainability and clarity

✨ New Features

Comprehensive Test Suite

• Added test_december_2025.py - Full test suite against real December 2025 price data
• Validates all optimization rules: no overlaps, proper spread, discharge validation
• Tests against 31 days of actual Czech OTE price data

Developer Experience

• Added AGENTS.md - Comprehensive context guide for AI agents working with the codebase
• Updated README with new project structure and commands
• Clear documentation of UV dependency management and Lambda deployment

🐛 Bug Fixes

• Fixed crucial bug in optimizer.py (critical optimization logic fix)
• Fixed timezone handling inconsistencies
• Fixed test imports after reorganization

🔧 Improvements

• Enhanced logging separation for Lambda vs local execution
• Added timezone support to fix Lambda scheduling issues
• Enabled midday arbitrage charging by sizing charge windows to discharge capacity
• Added comprehensive configuration options for valley/discharge timing preferences

📝 Migration Notes

**Running the optimizer:**ash

Old: uv run optimizer.py

New: uv run python -m src.optimizer

Enhanced Arbitrage Validation & Overnight Charging

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[v2.5.0] - 2025-12-13

Added

• Discharge validation in arbitrage cycles: Ensures discharge windows are sufficient for charged energy, using SOC gains and average load calculations with 5% buffer.
• Overnight charging extensions: Automatically extends short overnight valleys (up to 20% above average price) to meet full charging duration requirements.
• calculate_full_discharge_slots() in BatteryManager: Estimates slots needed to discharge from 95% to 20% SOC, capacity-aware with fallback approximation and 20% buffer.
• Period formatting helper in ESSClient for concise logging.

Changed

• Logging in schedule setters: Consolidated to single-line summaries (e.g., "✓ Charging enabled: 00:00→03:00").
• CLI: Made --dry-run explicit; --date now supports live runs on specific dates.
• Config: price_multiplier adjusted from 1.2 to 1.18 for more aggressive low-price charging.

Files Changed

• battery_manager.py: +11 lines (new discharge slots method).
• config.yaml: price_multiplier 1.2 → 1.18.
• ess_client.py: +15 lines (period formatting and log cleanup).
• optimizer.py: +109 lines (validation, extension logic, CLI updates).

This release enhances arbitrage reliability, especially for overnight cycles, while maintaining compatibility.

Modular Architecture Refactoring Latest

🚀 Overview

This release represents a major architectural refactoring, splitting the monolithic codebase into focused, maintainable modules. The optimizer now follows a clean separation of concerns, making it easier to test, maintain, and extend.

✨ New Features

Modular Component Architecture - Split ESS.py into focused, single-responsibility modules:

• optimizer.py - Main orchestration and optimization logic
• ess_client.py - AlphaESS API client abstraction with clean interface
• battery_manager.py - Battery state calculations and capacity management
• price_analyzer.py - Price analysis, valley/peak detection, and smoothing
• price_cache.py - Price data caching with ephemeral storage support
• models.py - Data models (PriceWindow, ArbitrageCycle, OptimizationPlan)

🔧 Improvements

Better Code Organization - Each module has a clear, single responsibility for improved maintainability

Configuration Fix - Fixed min_soc default value in config.yaml (changed from 0 to 10) as per AlphaESS API docs

📦 New Files

File	Purpose
optimizer.py	Main optimizer orchestration
ess_client.py	AlphaESS API client wrapper
battery_manager.py	Battery state and capacity calculations
price_analyzer.py	Price analysis and valley/peak detection
price_cache.py	Price data caching logic
models.py	Data models and type definitions

🗑️ Removed Files

• ESS.py - Split into modular components above
• build.sh - Deprecated build script

⚙️ Configuration

No breaking changes - all existing configuration remains compatible. The refactoring maintains full backward compatibility with existing .env and config.yaml files.

Updated Defaults:

• min_soc: Changed from 0 to 10 in config.yaml - AlphaESS API limit

This refactoring provides a solid foundation for future enhancements while maintaining all existing functionality.

AWS Lambda Deployment Support

🚀 Overview

This release adds full AWS Lambda compatibility, allowing the optimizer to run as a serverless function instead of a continuously running process.

---

✨ New Features

• AWS Lambda Handler - New lambda_handler.py with three invocation modes:

  • tomorrow - Optimize for next day (default, ideal for daily 18:00 trigger)
  • today - Re-optimize current day
  • reactive - Hourly reactive checks

• Docker Container Image - Production-ready Dockerfile targeting AWS Lambda arm64 (Graviton) runtime for better price-performance

• One-Command Deployment - deploy-lambda.sh script that:

  • Builds and pushes to Amazon ECR
  • Updates Lambda function code
  • Configures environment variables
  • Sets timeout and memory limits

🔧 Improvements

• Lambda-compatible logging - Auto-detects Lambda environment and uses CloudWatch instead of file logging
• Ephemeral cache support - Price cache uses /tmp in Lambda environments
• Environment variable configuration - All secrets loaded from environment variables (no hardcoded values)

📦 New Files

File	Purpose
Dockerfile	Lambda container image (arm64)
lambda_handler.py	Lambda entry point
deploy-lambda.sh	Automated deployment script
.env.example	Configuration template
.dockerignore	Optimized image builds

⚙️ Configuration

Required environment variables for Lambda:

APP_ID          - AlphaESS API app ID
APP_SECRET      - AlphaESS API app secret
SERIAL_NUMBER   - ESS serial number

📋 Recommended Lambda Settings

• Architecture: arm64
• Timeout: 30 seconds
• Memory: 256 MB
• Trigger: EventBridge rule at 17:00 UTC daily

---

v2.2.0

v2.2.0 Release Notes

Smarter Arbitrage Optimization

Charging improvements

• Finds the cheapest consecutive window within a valley instead of always starting at the beginning
• For Dec 5th example: shifted from 00:00-03:30 → 01:15-04:45, saving ~3 EUR/MWh

Discharge improvements

• Stricter backward extension threshold (85% of peak avg) prevents extending into mediocre slots
• Forward extension unchanged - captures all profitable hours after peak

Housekeeping

• Removed unused config values (charge_rate_kw, avg_overnight_load_kw)
• Merged redundant charge window methods
• Added configurable discharge_extension_threshold parameter
• Fixed potential None division bugs with battery capacity fallback

v2.1.0

Changelog

v2.1.0 (2025-12-03)

🔋 Smarter Battery Management

Full Valley Charging
Overnight and depleted battery scenarios now use the full valley duration instead of short top-up windows. Previously, a 10% SOC battery at midnight might only charge for 1 hour—now it uses the entire cheap period (capped at ~3.5h).

Extended Discharge Windows
Discharge no longer stops at the strict "peak" boundary. The system now extends discharge into all surrounding hours where price > charge_price × 1.2, maximizing energy arbitrage.

Consumption Tracking
New avg_overnight_load_kw config estimates SOC drain during gaps between windows, preventing optimistic calculations that ignore standby loads.

Fallback Discharge Detection
When no explicit peaks are detected (flat-ish price days), the optimizer scans for any profitable discharge opportunities above the 20% margin threshold.

⚙️ Config Changes

New parameter in config.yaml:

avg_overnight_load_kw: 1.6  # Standby consumption for SOC drain estimation

📊 Code Quality

• Reduced codebase from ~800 to ~650 lines
• All 63 tests passing