site-calc-investment 1.2.0__py3-none-any.whl

site_calc_investment/models/common.py

@@ -0,0 +1,174 @@
+# SYNC: This file may be synced between investment and operational clients
+"""Common models shared across the investment client."""
+
+from datetime import date, datetime, timedelta
+from enum import Enum
+from zoneinfo import ZoneInfo
+
+from pydantic import BaseModel, Field, computed_field, field_validator
+
+
+class Resolution(str, Enum):
+    """Time resolution for optimization intervals."""
+
+    MINUTES_15 = "15min"
+    HOUR_1 = "1h"
+
+    @property
+    def minutes(self) -> int:
+        """Get resolution in minutes."""
+        return 15 if self == Resolution.MINUTES_15 else 60
+
+    @property
+    def intervals_per_day(self) -> int:
+        """Get number of intervals per day."""
+        return 96 if self == Resolution.MINUTES_15 else 24
+
+
+class TimeSpan(BaseModel):
+    """Time period for optimization.
+
+    Represents a time period with explicit interval count, allowing precise
+    control over array sizes and computed end time.
+
+    Examples:
+        Full day at 15-minute resolution:
+        >>> ts = TimeSpan.for_day(date(2025, 11, 6), Resolution.MINUTES_15)
+        >>> ts.intervals
+        96
+        >>> ts.duration
+        timedelta(days=1)
+
+        Custom 10-year planning:
+        >>> ts = TimeSpan(
+        ...     start=datetime(2025, 1, 1, tzinfo=ZoneInfo("Europe/Prague")),
+        ...     intervals=87600,
+        ...     resolution=Resolution.HOUR_1
+        ... )
+        >>> ts.years
+        10.0
+    """
+
+    start: datetime = Field(..., description="Start time (Europe/Prague timezone required)")
+    intervals: int = Field(..., ge=1, le=100_000, description="Number of time intervals")
+    resolution: Resolution = Field(..., description="Time resolution (15min or 1h)")
+
+    @field_validator("start")
+    @classmethod
+    def validate_timezone(cls, v: datetime) -> datetime:
+        """Ensure timezone is Europe/Prague."""
+        prague_tz = ZoneInfo("Europe/Prague")
+        if v.tzinfo is None:
+            raise ValueError("Timezone must be specified")
+        if v.tzinfo != prague_tz:
+            raise ValueError(f"Timezone must be Europe/Prague, got {v.tzinfo}")
+        return v
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def end(self) -> datetime:
+        """Computed end time based on start, intervals, and resolution."""
+        delta = timedelta(minutes=self.intervals * self.resolution.minutes)
+        return self.start + delta
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def duration(self) -> timedelta:
+        """Total duration of the time period."""
+        return timedelta(minutes=self.intervals * self.resolution.minutes)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def years(self) -> float:
+        """Duration in years (approximate, using 365.25 days/year)."""
+        return self.duration.total_seconds() / (365.25 * 24 * 3600)
+
+    @classmethod
+    def for_day(cls, date: date, resolution: Resolution) -> "TimeSpan":
+        """Create timespan for a full day.
+
+        Args:
+            date: The date to optimize
+            resolution: Time resolution (15min or 1h)
+
+        Returns:
+            TimeSpan covering the full day
+
+        Example:
+            >>> ts = TimeSpan.for_day(date(2025, 11, 6), Resolution.HOUR_1)
+            >>> ts.intervals
+            24
+        """
+        start = datetime.combine(date, datetime.min.time()).replace(tzinfo=ZoneInfo("Europe/Prague"))
+        return cls(start=start, intervals=resolution.intervals_per_day, resolution=resolution)
+
+    @classmethod
+    def for_hours(cls, start: datetime, hours: int, resolution: Resolution) -> "TimeSpan":
+        """Create timespan for N hours.
+
+        Args:
+            start: Start datetime (must have Europe/Prague timezone)
+            hours: Number of hours
+            resolution: Time resolution
+
+        Returns:
+            TimeSpan covering the specified hours
+
+        Example:
+            >>> start = datetime(2025, 11, 6, tzinfo=ZoneInfo("Europe/Prague"))
+            >>> ts = TimeSpan.for_hours(start, 48, Resolution.HOUR_1)
+            >>> ts.intervals
+            48
+        """
+        intervals = hours * (60 // resolution.minutes)
+        return cls(start=start, intervals=intervals, resolution=resolution)
+
+    @classmethod
+    def for_years(cls, start_year: int, years: int, resolution: Resolution = Resolution.HOUR_1) -> "TimeSpan":
+        """Create timespan for N years.
+
+        Args:
+            start_year: Starting year (e.g., 2025)
+            years: Number of years
+            resolution: Time resolution (defaults to 1h)
+
+        Returns:
+            TimeSpan covering the specified years
+
+        Example:
+            >>> ts = TimeSpan.for_years(2025, 10)
+            >>> ts.intervals
+            87600
+            >>> ts.years
+            10.0
+        """
+        start = datetime(start_year, 1, 1, tzinfo=ZoneInfo("Europe/Prague"))
+        intervals = years * 8760  # 8760 hours per year
+        return cls(start=start, intervals=intervals, resolution=resolution)
+
+    def to_api_dict(self) -> dict:
+        """Convert to API format.
+
+        Returns:
+            Dictionary with period_start, period_end, resolution for API requests
+        """
+        return {
+            "period_start": self.start.isoformat(),
+            "period_end": self.end.isoformat(),
+            "resolution": self.resolution.value,
+        }
+
+
+class Location(BaseModel):
+    """Geographic location for devices like photovoltaic systems.
+
+    Attributes:
+        latitude: Latitude in degrees (-90 to 90)
+        longitude: Longitude in degrees (-180 to 180)
+
+    Example:
+        >>> prague = Location(latitude=50.0751, longitude=14.4378)
+    """
+
+    latitude: float = Field(..., ge=-90, le=90, description="Latitude in degrees")
+    longitude: float = Field(..., ge=-180, le=180, description="Longitude in degrees")

site_calc_investment/models/devices.py

@@ -0,0 +1,263 @@
+"""Device models for investment client (NO ancillary services)."""
+
+from typing import List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field, field_validator
+
+from site_calc_investment.models.common import Location
+
+# Device Properties Models
+
+
+class BatteryProperties(BaseModel):
+    """Battery storage properties."""
+
+    capacity: float = Field(..., gt=0, description="Energy capacity (MWh)")
+    max_power: float = Field(..., gt=0, description="Power rating for charge/discharge (MW)")
+    efficiency: float = Field(..., gt=0, le=1, description="Round-trip efficiency (0-1)")
+    initial_soc: float = Field(0.5, ge=0, le=1, description="Initial state of charge (0-1)")
+    soc_anchor_interval_hours: Optional[int] = Field(
+        None,
+        gt=0,
+        description="If set, force SOC to target at regular intervals (hours). E.g., 4320 = every 6 months",
+    )
+    soc_anchor_target: float = Field(
+        0.5,
+        ge=0,
+        le=1,
+        description="Target SOC fraction at anchor points (0-1)",
+    )
+
+
+class CHPProperties(BaseModel):
+    """Combined Heat and Power properties."""
+
+    gas_input: float = Field(..., gt=0, description="Gas consumption at full load (MW)")
+    el_output: float = Field(..., gt=0, description="Electricity generation at full load (MW)")
+    heat_output: float = Field(..., gt=0, description="Heat generation at full load (MW)")
+    is_binary: bool = Field(False, description="True=on/off only (relaxed for investment), False=modulating")
+    min_power: Optional[float] = Field(None, ge=0, le=1, description="Min power fraction if modulation limited")
+
+
+class HeatAccumulatorProperties(BaseModel):
+    """Heat accumulator (thermal storage) properties."""
+
+    capacity: float = Field(..., gt=0, description="Thermal energy capacity (MWh)")
+    max_power: float = Field(..., gt=0, description="Charge/discharge power (MW)")
+    efficiency: float = Field(..., gt=0, le=1, description="Storage efficiency (0-1)")
+    initial_soc: float = Field(0.5, ge=0, le=1, description="Initial state of charge (0-1)")
+    loss_rate: float = Field(0.001, ge=0, description="Standing losses (fraction/hour)")
+
+
+class PhotovoltaicProperties(BaseModel):
+    """Photovoltaic system properties."""
+
+    peak_power_mw: float = Field(..., gt=0, description="Peak power capacity (MW)")
+    location: Location = Field(..., description="Geographic location")
+    tilt: int = Field(..., ge=0, le=90, description="Panel tilt angle (degrees)")
+    azimuth: int = Field(..., ge=0, lt=360, description="Azimuth angle (degrees, 180=south)")
+    generation_profile: Optional[List[float]] = Field(None, description="Optional normalized generation profile (0-1)")
+
+    @field_validator("generation_profile")
+    @classmethod
+    def validate_profile(cls, v: Optional[List[float]]) -> Optional[List[float]]:
+        """Validate generation profile values are between 0 and 1."""
+        if v is not None:
+            if not all(0 <= val <= 1 for val in v):
+                raise ValueError("Generation profile values must be between 0 and 1")
+        return v
+
+
+class DemandProperties(BaseModel):
+    """Demand properties (heat or electricity)."""
+
+    max_demand_profile: List[float] = Field(..., description="Maximum demand profile (MW, not MWh!)")
+    min_demand_profile: Union[List[float], float] = Field(
+        0, description="Minimum demand profile (MW) or constant value"
+    )
+
+    @field_validator("max_demand_profile", "min_demand_profile")
+    @classmethod
+    def validate_positive(cls, v: Union[List[float], float]) -> Union[List[float], float]:
+        """Validate demand values are non-negative."""
+        if isinstance(v, list):
+            if not all(val >= 0 for val in v):
+                raise ValueError("Demand values must be non-negative")
+        elif isinstance(v, (int, float)):
+            if v < 0:
+                raise ValueError("Demand value must be non-negative")
+        return v
+
+
+class MarketImportProperties(BaseModel):
+    """Market import device properties (electricity or gas)."""
+
+    price: List[float] = Field(..., description="Price profile (EUR/MWh)")
+    max_import: float = Field(..., gt=0, description="Maximum import capacity (MW)")
+    max_import_unit_cost: Optional[float] = Field(
+        None, ge=0, description="Optional reserved capacity cost (EUR/MW/year)"
+    )
+
+
+class MarketExportProperties(BaseModel):
+    """Market export device properties (electricity or heat)."""
+
+    price: List[float] = Field(..., description="Price profile (EUR/MWh)")
+    max_export: float = Field(..., gt=0, description="Maximum export capacity (MW)")
+    max_export_unit_cost: Optional[float] = Field(None, ge=0, description="Optional export capacity cost (EUR/MW/year)")
+
+
+# Schedule Model
+
+
+class Schedule(BaseModel):
+    """Operational schedule constraints.
+
+    Defines when and how a device can operate with runtime constraints
+    and binary availability arrays.
+    """
+
+    # Runtime constraints
+    min_continuous_run_hours: Optional[float] = Field(None, ge=0, description="Minimum runtime once started")
+    max_continuous_run_hours: Optional[float] = Field(None, ge=0, description="Maximum continuous operation")
+    max_hours_per_day: Optional[float] = Field(None, ge=0, le=24, description="Total hours per day")
+    max_starts_per_day: Optional[int] = Field(None, ge=0, description="Maximum number of startups")
+    min_downtime_hours: Optional[float] = Field(None, ge=0, description="Minimum off time between runs")
+
+    # Binary availability arrays
+    can_run: Optional[List[Union[int, float]]] = Field(
+        None, description="0=cannot run, 1=can run (or fractional for PV)"
+    )
+    must_run: Optional[List[int]] = Field(None, description="1=must run")
+
+    # Power ranges when must_run=1
+    min_power: Optional[List[float]] = Field(None, description="Minimum power when must_run=1 (MW)")
+    max_power: Optional[List[float]] = Field(None, description="Maximum power when must_run=1 (MW)")
+
+    @field_validator("can_run")
+    @classmethod
+    def validate_can_run(cls, v: Optional[List[Union[int, float]]]) -> Optional[List[Union[int, float]]]:
+        """Validate can_run array."""
+        if v is not None:
+            if len(v) not in [24, 96]:
+                raise ValueError("can_run array length must be 24 (1-hour) or 96 (15-min)")
+            # Allow fractional values for PV, but validate range
+            if not all(0 <= val <= 1 for val in v):
+                raise ValueError("can_run values must be between 0 and 1")
+        return v
+
+    @field_validator("must_run")
+    @classmethod
+    def validate_must_run(cls, v: Optional[List[int]]) -> Optional[List[int]]:
+        """Validate must_run is binary."""
+        if v is not None:
+            if len(v) not in [24, 96]:
+                raise ValueError("must_run array length must be 24 (1-hour) or 96 (15-min)")
+            if not all(val in [0, 1] for val in v):
+                raise ValueError("must_run must contain only 0 or 1")
+        return v
+
+
+# Device Models
+
+
+class Battery(BaseModel):
+    """Battery storage device (NO ancillary services for investment client)."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["battery"] = "battery"
+    properties: BatteryProperties
+    schedule: Optional[Schedule] = None
+
+
+class CHP(BaseModel):
+    """Combined Heat and Power device.
+
+    Note: is_binary is automatically relaxed to continuous for investment planning.
+    """
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["chp"] = "chp"
+    properties: CHPProperties
+    schedule: Optional[Schedule] = None
+
+
+class HeatAccumulator(BaseModel):
+    """Heat accumulator (thermal storage) device."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["heat_accumulator"] = "heat_accumulator"
+    properties: HeatAccumulatorProperties
+    schedule: Optional[Schedule] = None
+
+
+class Photovoltaic(BaseModel):
+    """Photovoltaic system device."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["photovoltaic"] = "photovoltaic"
+    properties: PhotovoltaicProperties
+    schedule: Optional[Schedule] = None
+
+
+class HeatDemand(BaseModel):
+    """Heat demand device."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["heat_demand"] = "heat_demand"
+    properties: DemandProperties
+
+
+class ElectricityDemand(BaseModel):
+    """Electricity demand device."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["electricity_demand"] = "electricity_demand"
+    properties: DemandProperties
+
+
+class ElectricityImport(BaseModel):
+    """Electricity import (grid connection for buying)."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["electricity_import"] = "electricity_import"
+    properties: MarketImportProperties
+
+
+class ElectricityExport(BaseModel):
+    """Electricity export (grid connection for selling)."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["electricity_export"] = "electricity_export"
+    properties: MarketExportProperties
+
+
+class GasImport(BaseModel):
+    """Gas import (gas supply connection)."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["gas_import"] = "gas_import"
+    properties: MarketImportProperties
+
+
+class HeatExport(BaseModel):
+    """Heat export (district heating connection)."""
+
+    name: str = Field(..., description="Unique device identifier")
+    type: Literal["heat_export"] = "heat_export"
+    properties: MarketExportProperties
+
+
+# Union type for all devices
+Device = Union[
+    Battery,
+    CHP,
+    HeatAccumulator,
+    Photovoltaic,
+    HeatDemand,
+    ElectricityDemand,
+    ElectricityImport,
+    ElectricityExport,
+    GasImport,
+    HeatExport,
+]

site_calc_investment/models/requests.py

@@ -0,0 +1,133 @@
+"""Request models for investment client."""
+
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from site_calc_investment.models.common import Resolution, TimeSpan
+from site_calc_investment.models.devices import Device
+
+
+class Site(BaseModel):
+    """Site definition with devices.
+
+    A site represents a physical location with multiple devices
+    that are optimized together.
+    """
+
+    site_id: str = Field(..., description="Unique site identifier")
+    description: Optional[str] = Field(None, description="Optional site description")
+    devices: List[Device] = Field(..., min_length=1, description="List of devices at this site")
+
+    @field_validator("devices")
+    @classmethod
+    def validate_unique_names(cls, v: List[Device]) -> List[Device]:
+        """Ensure all device names are unique within a site."""
+        names = [d.name for d in v]
+        if len(names) != len(set(names)):
+            raise ValueError("Device names must be unique within a site")
+        return v
+
+
+class InvestmentParameters(BaseModel):
+    """Financial parameters for investment analysis.
+
+    These parameters are used to calculate NPV, IRR, and other
+    investment metrics.
+    """
+
+    discount_rate: float = Field(..., ge=0, le=0.5, description="Annual discount rate for NPV (0-0.5, e.g., 0.05 = 5%)")
+    project_lifetime_years: int = Field(..., ge=1, le=50, description="Project lifetime in years")
+    investment_budget: Optional[float] = Field(None, ge=0, description="Maximum investment budget in EUR")
+    carbon_price: Optional[float] = Field(None, ge=0, description="Carbon price in EUR/tCO2")
+    device_capital_costs: Optional[Dict[str, float]] = Field(
+        None, description="CAPEX for each device (EUR), keyed by device name"
+    )
+    device_annual_opex: Optional[Dict[str, float]] = Field(
+        None, description="Annual O&M costs (EUR/year), keyed by device name"
+    )
+    price_escalation_rate: Optional[float] = Field(
+        None, ge=0, le=1, description="Annual price escalation rate (e.g., 0.02 = 2%)"
+    )
+
+
+class OptimizationConfig(BaseModel):
+    """Optimization configuration."""
+
+    objective: Literal["maximize_profit", "minimize_cost", "maximize_self_consumption"] = Field(
+        "maximize_profit", description="Optimization objective"
+    )
+    time_limit_seconds: int = Field(300, gt=0, le=900, description="Solver timeout (max 15 minutes)")
+    relax_binary_variables: bool = Field(
+        True, description="Relax binary CHP variables to continuous (recommended for long horizons)"
+    )
+
+
+class TimeSpanInvestment(TimeSpan):
+    """TimeSpan with investment client validation.
+
+    Investment clients:
+    - Only support 1-hour resolution
+    - Maximum 100,000 intervals
+    """
+
+    resolution: Literal[Resolution.HOUR_1] = Resolution.HOUR_1  # type: ignore
+
+    @field_validator("intervals")
+    @classmethod
+    def validate_max_intervals(cls, v: int) -> int:
+        """Investment client limited to 100,000 intervals."""
+        if v > 100_000:
+            raise ValueError("Investment client limited to 100,000 intervals (~11 years)")
+        return v
+
+    @field_validator("resolution")
+    @classmethod
+    def validate_resolution(cls, v: Resolution) -> Resolution:
+        """Investment client only supports 1-hour resolution."""
+        if v != Resolution.HOUR_1:
+            raise ValueError("Investment client only supports 1-hour resolution")
+        return v
+
+
+class InvestmentPlanningRequest(BaseModel):
+    """Request for long-term investment planning optimization.
+
+    This request creates a device planning job for capacity sizing
+    and investment ROI analysis over multi-year horizons.
+
+    Example:
+        >>> request = InvestmentPlanningRequest(
+        ...     sites=[site],
+        ...     timespan=TimeSpanInvestment.for_years(2025, 10),
+        ...     investment_parameters=InvestmentParameters(
+        ...         discount_rate=0.05,
+        ...         device_capital_costs={"Battery1": 500000}
+        ...     ),
+        ...     optimization_config=OptimizationConfig(
+        ...         objective="maximize_npv",
+        ...         time_limit_seconds=3600
+        ...     )
+        ... )
+    """
+
+    sites: List[Site] = Field(..., min_length=1, max_length=50, description="Sites to optimize (max 50)")
+    timespan: TimeSpanInvestment = Field(..., description="Time period (1-hour resolution only)")
+    investment_parameters: Optional[InvestmentParameters] = Field(
+        None, description="Optional financial parameters for ROI calculation"
+    )
+    optimization_config: OptimizationConfig = Field(
+        default=OptimizationConfig(),  # type: ignore[call-arg]
+        description="Optimization configuration",
+    )
+
+    def model_dump_for_api(self) -> dict:
+        """Convert to API format.
+
+        Returns:
+            Dictionary ready for JSON serialization and API submission
+        """
+        data = self.model_dump()
+        # Convert timespan to API format
+        data["timespan"] = self.timespan.to_api_dict()
+        return data

site_calc_investment/models/responses.py

@@ -0,0 +1,105 @@
+"""Response models for investment client."""
+
+from datetime import datetime
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Job(BaseModel):
+    """Job status and metadata.
+
+    Represents an asynchronous optimization job submitted to the API.
+    """
+
+    job_id: str = Field(..., description="Unique job identifier")
+    status: Literal["pending", "running", "completed", "failed", "cancelled"] = Field(..., description="Job status")
+    created_at: Optional[datetime] = Field(None, description="Job creation timestamp")
+    started_at: Optional[datetime] = Field(None, description="Job start timestamp")
+    completed_at: Optional[datetime] = Field(None, description="Job completion timestamp")
+    failed_at: Optional[datetime] = Field(None, description="Job failure timestamp")
+    progress: Optional[int] = Field(None, ge=0, le=100, description="Progress percentage (optional)")
+    message: Optional[str] = Field(None, description="Status message")
+    error: Optional[Dict] = Field(None, description="Error details if failed")
+    estimated_completion_seconds: Optional[int] = Field(None, description="Estimated completion time")
+    # Fields returned by server for completed/failed jobs
+    objective_value: Optional[float] = Field(None, description="Optimization objective value")
+    solver_time: Optional[float] = Field(None, description="Solver execution time in seconds")
+    total_time: Optional[float] = Field(None, description="Total job time in seconds")
+    error_code: Optional[str] = Field(None, description="Error code (e.g., PROBLEM_INFEASIBLE, SOLVER_TIMEOUT)")
+    suggestion: Optional[str] = Field(None, description="Suggestion for resolving errors")
+
+
+class DeviceSchedule(BaseModel):
+    """Optimized schedule for a single device.
+
+    Contains flows (power/energy by material), state of charge (for storage),
+    and any binary status indicators.
+    """
+
+    flows: Dict[str, List[float]] = Field(
+        ..., description="Material flows keyed by material (e.g., 'electricity', 'gas', 'heat')"
+    )
+    soc: Optional[List[float]] = Field(None, description="State of charge (0-1) for storage devices")
+    binary_status: Optional[List[int]] = Field(None, description="Binary on/off status (0/1) for CHP")
+    ancillary_reservations: Optional[Dict[str, List[float]]] = Field(
+        None, description="Reserved capacity by service (e.g., {'afrr_plus': [...], 'afrr_minus': [...]})"
+    )
+
+
+class SiteResult(BaseModel):
+    """Optimization results for a single site."""
+
+    device_schedules: Dict[str, DeviceSchedule] = Field(..., description="Device schedules keyed by device name")
+    grid_flows: Optional[Dict[str, List[float]]] = Field(None, description="Grid import/export flows")
+
+
+class InvestmentMetrics(BaseModel):
+    """Investment analysis metrics.
+
+    Financial metrics calculated from the optimization results.
+    NPV and IRR are typically calculated client-side using the
+    annual_revenue_by_year and annual_costs_by_year arrays along
+    with investment_parameters (discount_rate, device_capital_costs).
+    """
+
+    npv: Optional[float] = Field(None, description="Net present value (EUR) - typically calculated client-side")
+    irr: Optional[float] = Field(None, description="Internal rate of return (fraction, e.g., 0.12 = 12%)")
+    payback_period_years: Optional[float] = Field(None, description="Simple payback period (years)")
+    total_revenue_10y: Optional[float] = Field(None, description="Total revenue over planning horizon (EUR)")
+    total_costs_10y: Optional[float] = Field(None, description="Total costs over planning horizon (EUR)")
+    annual_revenue_by_year: Optional[List[float]] = Field(None, description="Annual revenue for each year")
+    annual_costs_by_year: Optional[List[float]] = Field(None, description="Annual costs for each year")
+
+
+class Summary(BaseModel):
+    """Optimization summary with investment metrics."""
+
+    total_da_revenue: Optional[float] = Field(None, description="Day-ahead market revenue (EUR)")
+    total_ancillary_revenue: Optional[float] = Field(None, description="Total ANS capacity payments (EUR)")
+    total_cost: Optional[float] = Field(None, description="Total operational costs (EUR)")
+    expected_profit: Optional[float] = Field(None, description="Expected profit (revenue - cost) (EUR)")
+    solver_status: str = Field(..., description="Solver status (optimal, timeout, infeasible, etc.)")
+    solve_time_seconds: float = Field(..., ge=0, description="Solver execution time")
+    sites_count: Optional[int] = Field(None, description="Number of sites optimized")
+
+
+class InvestmentPlanningResponse(BaseModel):
+    """Complete response for investment planning optimization.
+
+    Contains optimized device schedules for all sites, grid flows,
+    and financial analysis metrics.
+
+    Example:
+        >>> result = client.wait_for_completion(job_id)
+        >>> print(f"NPV: €{result.investment_metrics.npv:,.0f}")
+        >>> print(f"IRR: {result.investment_metrics.irr*100:.2f}%")
+    """
+
+    job_id: str = Field(..., description="Job identifier")
+    status: Literal["completed"] = "completed"
+    sites: Dict[str, SiteResult] = Field(..., description="Results keyed by site_id")
+    summary: Summary = Field(..., description="Optimization summary and metrics")
+    investment_metrics: Optional[InvestmentMetrics] = Field(
+        None, description="Investment analysis metrics (if investment_parameters provided)"
+    )