serial-alice-agent 1.0.1__tar.gz

serial_alice_agent-1.0.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: serial-alice-agent
+Version: 1.0.1
+Summary: Serial Alice Agent — Verifiable energy and compute attestation
+Author-email: Sirius GreenTech <contact@serialalice.pt>
+License: Proprietary
+Project-URL: Homepage, https://serialalice.pt
+Project-URL: Documentation, https://api.serialalice.pt/docs
+Project-URL: Repository, https://github.com/SerialAlicev3/serial-alice
+Keywords: energy,compute,attestation,cryptography,gpu
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: cryptography>=41.0
+Provides-Extra: gpu
+Requires-Dist: pynvml>=11.5; extra == "gpu"
+Provides-Extra: windows
+Requires-Dist: pywin32>=306; extra == "windows"
+Requires-Dist: wmi>=1.5.1; extra == "windows"
+Provides-Extra: full
+Requires-Dist: serial-alice-agent[gpu,windows]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+
+# Serial Alice Agent
+
+Verifiable energy and compute attestation agent for AI workloads.
+Issues Ed25519-signed certificates of energy consumption, anchored on Polygon.
+
+## Install
+
+```bash
+# From the self-hosted zip (no PyPI, no GitHub auth required):
+pip install https://api.serialalice.pt/agent/download/linux
+
+# Or download first:
+curl -L https://api.serialalice.pt/agent/download/linux -o serial-alice-agent.zip
+pip install serial-alice-agent.zip
+
+# With NVIDIA GPU telemetry:
+pip install "serial-alice-agent.zip[gpu]"
+```
+
+## Quick start
+
+```bash
+export SA_AGENT_API_KEY=sa_live_...   # from https://app.serialalice.pt
+
+serial-alice-agent status             # verify API connectivity
+serial-alice-agent discover           # list detected hardware
+serial-alice-agent run --job-name my-training -- python train.py
+```
+
+## Run without installing
+
+```bash
+unzip serial-alice-agent.zip
+cd serial-alice-agent
+pip install requests pyyaml psutil cryptography   # core deps
+python -m agent.cli status
+```
+
+## Configuration
+
+```yaml
+# agent.yaml
+api_url: https://api.serialalice.pt
+api_key: ${SA_AGENT_API_KEY}
+measurement_interval_s: 10
+hardware:
+  gpu: auto
+  cpu: true
+```
+
+## Links
+
+- Documentation: https://api.serialalice.pt/docs
+- Platform: https://serialalice.pt

serial_alice_agent-1.0.1/README.md

@@ -0,0 +1,54 @@
+# Serial Alice Agent
+
+Verifiable energy and compute attestation agent for AI workloads.
+Issues Ed25519-signed certificates of energy consumption, anchored on Polygon.
+
+## Install
+
+```bash
+# From the self-hosted zip (no PyPI, no GitHub auth required):
+pip install https://api.serialalice.pt/agent/download/linux
+
+# Or download first:
+curl -L https://api.serialalice.pt/agent/download/linux -o serial-alice-agent.zip
+pip install serial-alice-agent.zip
+
+# With NVIDIA GPU telemetry:
+pip install "serial-alice-agent.zip[gpu]"
+```
+
+## Quick start
+
+```bash
+export SA_AGENT_API_KEY=sa_live_...   # from https://app.serialalice.pt
+
+serial-alice-agent status             # verify API connectivity
+serial-alice-agent discover           # list detected hardware
+serial-alice-agent run --job-name my-training -- python train.py
+```
+
+## Run without installing
+
+```bash
+unzip serial-alice-agent.zip
+cd serial-alice-agent
+pip install requests pyyaml psutil cryptography   # core deps
+python -m agent.cli status
+```
+
+## Configuration
+
+```yaml
+# agent.yaml
+api_url: https://api.serialalice.pt
+api_key: ${SA_AGENT_API_KEY}
+measurement_interval_s: 10
+hardware:
+  gpu: auto
+  cpu: true
+```
+
+## Links
+
+- Documentation: https://api.serialalice.pt/docs
+- Platform: https://serialalice.pt

serial_alice_agent-1.0.1/agent/adapters/__init__.py

@@ -0,0 +1,161 @@
+"""
+Serial Alice — Adapter Registry v3
+====================================
+Registry de todos os adapters de medição multi-componente.
+
+Uso:
+  from agent.adapters import collect_all_measurements, AdapterRegistry
+
+  registry = AdapterRegistry()
+  measurements = registry.collect(started_at, ended_at)
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import List
+
+from .base import Measurement, EnergyAdapter
+
+logger = logging.getLogger("sa.adapters")
+
+
+class AdapterRegistry:
+    """
+    Registo e orquestrador de todos os adapters activos.
+
+    Inicializa os adapters disponíveis e recolhe medições de todos em paralelo.
+    Adapters indisponíveis são ignorados silenciosamente.
+    """
+
+    def __init__(
+        self,
+        enable_gpu:     bool = True,
+        enable_cpu:     bool = True,
+        enable_ram:     bool = True,
+        enable_disk:    bool = True,
+        enable_network: bool = True,
+        enable_machine: bool = True,
+    ):
+        self._adapters: list[EnergyAdapter] = []
+        self._init_adapters(enable_gpu, enable_cpu, enable_ram,
+                            enable_disk, enable_network, enable_machine)
+
+    def _init_adapters(self, gpu, cpu, ram, disk, net, machine):
+        if gpu:
+            try:
+                from .gpu import NvmlGpuAdapter, DcgmGpuAdapter
+                nvml = NvmlGpuAdapter()
+                if nvml.is_available():
+                    self._adapters.append(nvml)
+                    logger.info("Adapter activo: nvml_gpu")
+                else:
+                    dcgm = DcgmGpuAdapter()
+                    if dcgm.is_available():
+                        self._adapters.append(dcgm)
+                        logger.info("Adapter activo: dcgm_gpu")
+                    else:
+                        # Tenta Windows RAPL para iGPU Intel
+                        try:
+                            from .windows_rapl import WindowsRaplAdapter
+                            win_rapl = WindowsRaplAdapter()
+                            if win_rapl.is_available():
+                                self._adapters.append(win_rapl)
+                                logger.info("Adapter activo: windows_rapl (Intel iGPU + CPU via LHM)")
+                            else:
+                                logger.debug("GPU adapters indisponíveis (sem NVML, DCGM, ou LHM)")
+                        except Exception as we:
+                            logger.debug("WindowsRaplAdapter init: %s", we)
+                            logger.debug("GPU adapters indisponíveis")
+            except Exception as e:
+                logger.warning("GPU adapter init: %s", e)
+
+        if cpu:
+            try:
+                from .cpu import get_best_cpu_adapter
+                a = get_best_cpu_adapter()
+                self._adapters.append(a)
+                logger.info("Adapter activo: %s", a.adapter_name)
+            except Exception as e:
+                logger.warning("CPU adapter init: %s", e)
+
+        if ram:
+            try:
+                from .system import RamAdapter
+                a = RamAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: ram_model")
+            except Exception as e:
+                logger.warning("RAM adapter init: %s", e)
+
+        if disk:
+            try:
+                from .system import DiskAdapter
+                a = DiskAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: disk_model")
+            except Exception as e:
+                logger.warning("Disk adapter init: %s", e)
+
+        if net:
+            try:
+                from .system import NetworkAdapter
+                a = NetworkAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: network_model")
+            except Exception as e:
+                logger.warning("Network adapter init: %s", e)
+
+        if machine:
+            try:
+                from .machine import get_best_machine_adapter
+                a = get_best_machine_adapter()
+                if a:
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: %s", a.adapter_name)
+                else:
+                    logger.info("Machine adapter: nenhum disponível (sem BMC/PDU configurado)")
+            except Exception as e:
+                logger.warning("Machine adapter init: %s", e)
+
+            # IPMI/DCMI — bare-metal system-level power (ipmitool)
+            try:
+                from .ipmi_adapter import IpmiDcmiAdapter
+                ipmi = IpmiDcmiAdapter()
+                if ipmi.is_available():
+                    self._adapters.append(ipmi)
+                    logger.info("Adapter activo: ipmi_dcmi")
+            except Exception as e:
+                logger.debug("IPMI adapter init: %s", e)
+
+            # PDU/SNMP — rack-level power via SNMP
+            try:
+                from .pdu_snmp_adapter import PduSnmpAdapter
+                pdu = PduSnmpAdapter()
+                if pdu.is_available():
+                    self._adapters.append(pdu)
+                    logger.info("Adapter activo: pdu_snmp")
+            except Exception as e:
+                logger.debug("PDU/SNMP adapter init: %s", e)
+
+    def collect(
+        self,
+        interval_start: datetime,
+        interval_end:   datetime,
+    ) -> List[Measurement]:
+        """Recolhe medições de todos os adapters activos."""
+        all_measurements: List[Measurement] = []
+        for adapter in self._adapters:
+            try:
+                ms = adapter.collect(interval_start, interval_end)
+                all_measurements.extend(ms)
+                logger.debug("Adapter %s: %d measurements", adapter.adapter_name, len(ms))
+            except Exception as e:
+                logger.error("Adapter %s.collect() error: %s", adapter.adapter_name, e)
+        return all_measurements
+
+    def active_adapters(self) -> list[str]:
+        return [a.adapter_name for a in self._adapters]

serial_alice_agent-1.0.1/agent/adapters/adapters_init.py

@@ -0,0 +1,141 @@
+"""
+Serial Alice — Adapter Registry v3
+====================================
+Registry de todos os adapters de medição multi-componente.
+
+Uso:
+  from agent.adapters import collect_all_measurements, AdapterRegistry
+
+  registry = AdapterRegistry()
+  measurements = registry.collect(started_at, ended_at)
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import List
+
+from .base import Measurement, EnergyAdapter
+
+logger = logging.getLogger("sa.adapters")
+
+
+class AdapterRegistry:
+    """
+    Registo e orquestrador de todos os adapters activos.
+
+    Inicializa os adapters disponíveis e recolhe medições de todos em paralelo.
+    Adapters indisponíveis são ignorados silenciosamente.
+    """
+
+    def __init__(
+        self,
+        enable_gpu:     bool = True,
+        enable_cpu:     bool = True,
+        enable_ram:     bool = True,
+        enable_disk:    bool = True,
+        enable_network: bool = True,
+        enable_machine: bool = True,
+    ):
+        self._adapters: list[EnergyAdapter] = []
+        self._init_adapters(enable_gpu, enable_cpu, enable_ram,
+                            enable_disk, enable_network, enable_machine)
+
+    def _init_adapters(self, gpu, cpu, ram, disk, net, machine):
+        if gpu:
+            try:
+                from .gpu import NvmlGpuAdapter, DcgmGpuAdapter
+                nvml = NvmlGpuAdapter()
+                if nvml.is_available():
+                    self._adapters.append(nvml)
+                    logger.info("Adapter activo: nvml_gpu")
+                else:
+                    dcgm = DcgmGpuAdapter()
+                    if dcgm.is_available():
+                        self._adapters.append(dcgm)
+                        logger.info("Adapter activo: dcgm_gpu")
+                    else:
+                        # Tenta Windows RAPL para iGPU Intel
+                        try:
+                            from .windows_rapl import WindowsRaplAdapter
+                            win_rapl = WindowsRaplAdapter()
+                            if win_rapl.is_available():
+                                self._adapters.append(win_rapl)
+                                logger.info("Adapter activo: windows_rapl (Intel iGPU + CPU via LHM)")
+                            else:
+                                logger.debug("GPU adapters indisponíveis (sem NVML, DCGM, ou LHM)")
+                        except Exception as we:
+                            logger.debug("WindowsRaplAdapter init: %s", we)
+                            logger.debug("GPU adapters indisponíveis")
+            except Exception as e:
+                logger.warning("GPU adapter init: %s", e)
+
+        if cpu:
+            try:
+                from .cpu import get_best_cpu_adapter
+                a = get_best_cpu_adapter()
+                self._adapters.append(a)
+                logger.info("Adapter activo: %s", a.adapter_name)
+            except Exception as e:
+                logger.warning("CPU adapter init: %s", e)
+
+        if ram:
+            try:
+                from .system import RamAdapter
+                a = RamAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: ram_model")
+            except Exception as e:
+                logger.warning("RAM adapter init: %s", e)
+
+        if disk:
+            try:
+                from .system import DiskAdapter
+                a = DiskAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: disk_model")
+            except Exception as e:
+                logger.warning("Disk adapter init: %s", e)
+
+        if net:
+            try:
+                from .system import NetworkAdapter
+                a = NetworkAdapter()
+                if a.is_available():
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: network_model")
+            except Exception as e:
+                logger.warning("Network adapter init: %s", e)
+
+        if machine:
+            try:
+                from .machine import get_best_machine_adapter
+                a = get_best_machine_adapter()
+                if a:
+                    self._adapters.append(a)
+                    logger.info("Adapter activo: %s", a.adapter_name)
+                else:
+                    logger.info("Machine adapter: nenhum disponível (sem BMC/PDU configurado)")
+            except Exception as e:
+                logger.warning("Machine adapter init: %s", e)
+
+    def collect(
+        self,
+        interval_start: datetime,
+        interval_end:   datetime,
+    ) -> List[Measurement]:
+        """Recolhe medições de todos os adapters activos."""
+        all_measurements: List[Measurement] = []
+        for adapter in self._adapters:
+            try:
+                ms = adapter.collect(interval_start, interval_end)
+                all_measurements.extend(ms)
+                logger.debug("Adapter %s: %d measurements", adapter.adapter_name, len(ms))
+            except Exception as e:
+                logger.error("Adapter %s.collect() error: %s", adapter.adapter_name, e)
+        return all_measurements
+
+    def active_adapters(self) -> list[str]:
+        return [a.adapter_name for a in self._adapters]

serial_alice_agent-1.0.1/agent/adapters/base.py

@@ -0,0 +1,244 @@
+"""
+Serial Alice — EnergyAdapter base interface e schema Measurement
+===============================================================
+Arquitectura plugin-based para medição multi-componente.
+
+Todos os adapters implementam EnergyAdapter.collect() e retornam
+List[Measurement] com schema canónico definido aqui.
+
+Unidade interna: Joules (J).
+Todos os adapters convertem para J internamente.
+Helpers wh_to_j() e j_to_wh() estão disponíveis.
+
+Regras:
+  - timestamps em UTC, ISO 8601
+  - granularidade ≤ 5s (recomendado: 1s)
+  - provenance explícito: "measured" | "estimated"
+  - confidence: 0.0–1.0 numérico
+  - source identificado com versão de adapter
+
+Versão do schema: measurement-v1
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from enum import Enum
+from typing import List, Optional
+
+SCHEMA_VERSION = "measurement-v1"
+
+# ── Enumerações canónicas ─────────────────────────────────────────────────────
+
+class Component(str, Enum):
+    GPU     = "gpu"
+    CPU     = "cpu"
+    RAM     = "ram"
+    DISK    = "disk"
+    NETWORK = "network"
+    BOARD   = "board"   # motherboard / chipset
+    PSU     = "psu"     # power supply losses
+    FANS    = "fans"
+    TOTAL   = "total"   # máquina inteira (BMC/PDU)
+
+class Scope(str, Enum):
+    DEVICE = "device"   # leitura de um dispositivo específico
+    HOST   = "host"     # leitura de toda a máquina
+    RACK   = "rack"     # leitura do rack (PDU)
+
+class MetricType(str, Enum):
+    POWER       = "power"        # W instantâneo
+    ENERGY      = "energy"       # J ou Wh acumulado
+    UTILIZATION = "utilization"  # %
+
+class Unit(str, Enum):
+    WATTS      = "W"
+    JOULES     = "J"
+    WH         = "Wh"
+    PERCENT    = "%"
+    BYTES      = "B"
+    BYTES_SEC  = "B/s"
+
+class Provenance(str, Enum):
+    MEASURED  = "measured"   # leitura de sensor real
+    ESTIMATED = "estimated"  # modelo/heurística
+
+class MeasurementSource(str, Enum):
+    NVML      = "nvml"      # NVIDIA Management Library
+    DCGM      = "dcgm"      # NVIDIA DCGM exporter
+    RAPL      = "rapl"      # Intel RAPL (Running Average Power Limit)
+    AMD_SMI   = "amd_smi"   # AMD ROCm SMI
+    REDFISH   = "redfish"   # Redfish / IPMI BMC (REST interface)
+    IPMI      = "ipmi"      # IPMI/DCMI via ipmitool (binary protocol)
+    SNMP      = "snmp"      # PDU via SNMP
+    PDU_REST  = "pdu_rest"  # PDU via REST
+    PSUTIL    = "psutil"    # psutil (estimativa CPU)
+    MODEL     = "model"     # modelo estático (TDP, bandwidth)
+    MANUAL    = "manual"    # declarado pelo operador
+    SIMULATION= "simulation"# modo dev/teste
+
+
+# ── Schema canónico ───────────────────────────────────────────────────────────
+
+@dataclass
+class Measurement:
+    """
+    Leitura de energia canónica — única estrutura que atravessa todo o sistema.
+
+    Unidade interna: Joules (J) para energy, Watts (W) para power.
+    Adapters que lêem noutras unidades convertem antes de retornar.
+
+    Fields obrigatórios: timestamp, host_id, component, scope,
+                         metric_type, value, unit, provenance, source
+    Fields opcionais:    device_id, confidence, adapter_version,
+                         context (metadados extra do adapter)
+    """
+    # Identificação
+    timestamp:       str            # ISO 8601 UTC do momento da leitura
+    host_id:         str            # identificador da máquina (hash ou hostname)
+    component:       Component      # gpu | cpu | ram | disk | network | board | psu | total
+    scope:           Scope          # device | host | rack
+    metric_type:     MetricType     # power | energy | utilization
+    value:           float          # valor numérico
+    unit:            Unit           # W | J | Wh | % | B | B/s
+    provenance:      Provenance     # measured | estimated
+    source:          MeasurementSource  # nvml | rapl | redfish | snmp | ...
+
+    # Identificação de dispositivo
+    device_id:       str | None = None   # UUID, PCI slot, ou índice
+    device_model:    str | None = None   # modelo do hardware (ex: "A100-SXM4-80GB")
+
+    # Qualidade
+    confidence:      float = 1.0         # 0.0–1.0 (1.0 = máxima confiança)
+    uncertainty_pct: float = 5.0         # incerteza estimada em %
+
+    # Versionamento do adapter
+    adapter_version: str = "1.0"
+
+    # Metadados extra (específicos do adapter)
+    context:         dict = field(default_factory=dict)
+
+    # Schema version para auditabilidade
+    schema_version:  str = SCHEMA_VERSION
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        # Converter enums para strings para serialização
+        d["component"]   = self.component.value   if isinstance(self.component, Component) else self.component
+        d["scope"]       = self.scope.value        if isinstance(self.scope, Scope) else self.scope
+        d["metric_type"] = self.metric_type.value  if isinstance(self.metric_type, MetricType) else self.metric_type
+        d["unit"]        = self.unit.value         if isinstance(self.unit, Unit) else self.unit
+        d["provenance"]  = self.provenance.value   if isinstance(self.provenance, Provenance) else self.provenance
+        d["source"]      = self.source.value       if isinstance(self.source, MeasurementSource) else self.source
+        return d
+
+    def to_joules(self) -> float:
+        """Converte o valor para Joules independentemente da unidade."""
+        if self.unit == Unit.JOULES:
+            return self.value
+        if self.unit == Unit.WH:
+            return self.value * 3600.0
+        if self.unit == Unit.WATTS:
+            # Para leituras de potência, precisa do intervalo de tempo
+            # Retorna watts — caller deve multiplicar pelo dt
+            return self.value
+        return self.value
+
+    def canonical_hash(self) -> str:
+        """Hash SHA-256 do conteúdo canónico para deduplicação."""
+        key = json.dumps({
+            "timestamp": self.timestamp,
+            "host_id":   self.host_id,
+            "device_id": self.device_id,
+            "component": self.component.value if isinstance(self.component, Component) else self.component,
+            "source":    self.source.value if isinstance(self.source, MeasurementSource) else self.source,
+            "value":     self.value,
+        }, sort_keys=True)
+        return hashlib.sha256(key.encode()).hexdigest()[:16]
+
+
+# ── Interface do Adapter ──────────────────────────────────────────────────────
+
+class EnergyAdapter:
+    """
+    Interface base para todos os adapters de medição energética.
+
+    Cada adapter representa uma fonte de dados específica (NVML, RAPL,
+    Redfish, SNMP/PDU, etc.).
+
+    Implementação mínima:
+      - is_available() → bool
+      - adapter_name / adapter_version (class attributes)
+      - collect(interval_start, interval_end) → List[Measurement]
+
+    Boas práticas:
+      - Nunca lançar excepção em collect() — retornar lista vazia em caso de falha
+      - Registar erros com logger.warning() ou logger.error()
+      - Marcar leituras estimadas com provenance=Provenance.ESTIMATED
+      - Incluir metadata relevante no context de cada Measurement
+    """
+    adapter_name:    str = "base"
+    adapter_version: str = "0.0"
+
+    def __init__(self):
+        import logging
+        self._log = logging.getLogger(f"sa.adapter.{self.adapter_name}")
+        self._host_id = self._get_host_id()
+
+    def _get_host_id(self) -> str:
+        """Identificador único da máquina (hash do hostname + MAC)."""
+        import socket
+        hostname = socket.gethostname()
+        return hashlib.sha256(hostname.encode()).hexdigest()[:16]
+
+    def is_available(self) -> bool:
+        """Retorna True se o adapter pode operar neste ambiente."""
+        return False
+
+    def collect(
+        self,
+        interval_start: datetime,
+        interval_end:   datetime,
+    ) -> List[Measurement]:
+        """
+        Recolhe medições para o intervalo temporal especificado.
+
+        Args:
+            interval_start: início do intervalo (UTC)
+            interval_end:   fim do intervalo (UTC)
+
+        Returns:
+            Lista de Measurement. Pode ser vazia se adapter indisponível.
+        """
+        raise NotImplementedError
+
+    def _ts(self, dt: datetime | None = None) -> str:
+        """ISO 8601 UTC timestamp."""
+        return (dt or datetime.now(timezone.utc)).isoformat()
+
+    def _duration(self, start: datetime, end: datetime) -> float:
+        return (end - start).total_seconds()
+
+
+# ── Helpers de conversão ──────────────────────────────────────────────────────
+
+def wh_to_j(wh: float) -> float:
+    return wh * 3600.0
+
+def j_to_wh(j: float) -> float:
+    return j / 3600.0
+
+def trapezoid_integrate_wh(power_samples: list[float], duration_s: float) -> float:
+    """Integração trapezoidal de amostras de potência (W) → energia (Wh)."""
+    if len(power_samples) < 2:
+        return power_samples[0] * duration_s / 3600.0 if power_samples else 0.0
+    n   = len(power_samples)
+    dt  = duration_s / (n - 1)
+    ws  = 0.5 * (power_samples[0] + power_samples[-1])
+    ws += sum(power_samples[1:-1])
+    ws *= dt
+    return ws / 3600.0