Developer Guide · BESSAI v2.16.0

De developer
a experto BESS en una tarde

148 tests NTSyCS compliance, mypy: 0 errores, ruff + bandit limpios, 10 GitHub Actions workflows activos. Arquitectura dual-repo (gateway OSS + IA privada).

148+ tests
0 mypy errors
10 CI/CD workflows
~32s suite completa
Quick Start ↓ Arquitectura ↓ GitHub ★
Quick Start

Elige tu camino de entrada

Path 1 · Recomendado

Simulador local

Sin hardware. Con datos CMg reales. Ideal para desarrollo y pruebas.

git clone https://github.com/bess-solutions/open-bess-edge

cd open-bess-edge

python -m venv .venv

source .venv/bin/activate  # Windows: .venv\Scripts\activate

pip install -e ".[dev]"

cp .env.example config/.env  # configurar sitio

make simulate   # BESS virtual + datos CMg

make test       # tests en ~32s
Path 2 · Monitoring

Docker Compose

Gateway + Prometheus + Grafana en un solo comando.

docker compose up -d \

  --profile monitoring



# Acceder a:

http://localhost:8000  # Gateway API

http://localhost:9090  # Prometheus

http://localhost:3000  # Grafana
Path 3 · Edge

Raspberry Pi 4/5

arm64 nativo. Sin emulación. Para despliegue real en el campo.

docker pull \

  ghcr.io/bess-solutions/open-bess-edge:latest



docker run -d \

  --name bessai \

  -p 8000:8000 \

  -v ./config.yaml:/app/config.yaml \

  ghcr.io/bess-solutions/open-bess-edge:latest
Arquitectura de módulos

Estructura modular pensada para escalar

src/

├── agents/         # → privado en bessai-core ⏘

│   # pip install bessai-agents (private)

│

├── drivers/        # Hardware abstraction

│   ├── modbus_driver.py # Modbus TCP client

│   ├── iec104_driver.py # IEC 60870-5-104 SCADA

│   ├── sep2_adapter.py  # IEEE 2030.5 server

│   ├── simulator_driver.py # BESS virtual (testing)

│   └── registry/ huawei_sun2000.json ...

│

├── interfaces/     # APIs y adaptadores

│   ├── health.py        # /health + /metrics

│   ├── compliance_api.py # /compliance/status+report

│   ├── pubsub_publisher.py # GCP Pub/Sub

│   └── mqtt_publisher.py  # MQTT multi-broker

│

└── core/           # Foundation

    ├── safety.py        # SafetyGuard GAP-001

    ├── compliance_stack.py # 11 GAPs façade

    ├── config.py        # 30+ env vars Pydantic

    ├── main.py          # Loop de control principal

    └── watchdog_manager.py # Auto self-heal

CI/CD Pipeline — 10 workflows

✓lint.ymlruff + bandit + mypy · ~45s
✓test.ymlpytest 685 tests · ~32s
✓security.ymlBandit + Trivy + CodeQL
✓hardware-ci.yml7 perfiles HW · martes 05:00 UTC
✓docker.ymlmultiarch amd64 + arm64 · ~3min
✓sbom.ymlCycloneDX + cosign sign
✓scorecard.ymlOpenSSF Scorecard weekly
✓evolve.ymlBESSAIEvolve weekly run
✓release.ymlSemver + CHANGELOG + GitHub Releases
✓codeql.ymlGitHub Advanced Security SAST
CONTRIBUTING.md ↗
Contribuir

El flujo de contribución en 5 pasos

1
Fork + setup
pip install -e ".[dev]" && pre-commit install
El pre-commit corre lint + typecheck automáticamente en cada commit.
2
Rama con convención
feature/BEP-XXXX-descripcion para features nuevas
fix/issue-NN-descripcion para bugs
3
Tests y tipos
pytest --tb=short -q — todos deben pasar
mypy src/ — 0 errores obligatorio
4
CHANGELOG.md
Añadir entrada bajo ## Unreleased describiendo el cambio. Seguimos Keep a Changelog + SemVer.
5
Pull Request
El CI corre automáticamente. Review en 48-72h hábiles. Si todo pasa → merge.

API Reference

GET/healthEstado del sistema
GET/metricsPrometheus (22 métricas)
GET/dashboardSOC, power, revenue, CMg
GET/scheduleVentanas óptimas 24h
GET/shap/{ts}SHAP values por decisión
GET/compliance/statusNTSyCS state (200/503)
GET/compliance/reportinforme JSON SEC/CEN
POST/setpointWrite authority (BEP-0300)

GOOD FIRST ISSUES

💚 Ver todos los Good First Issues en GitHub ↗

Issues etiquetados como bienvenida para nuevos contribuidores: desde documentación hasta tests y features pequeñas.

Recursos relacionados

🔧
Contribuir HardwareBEP-0100 · Tutorial 7 pasos
 🛡️
Compliance & SecurityIEC 62443 · PSIRT · SBOM
 🎓
BESSAIEvolve ResearchCMA-ES · NSGA-II · Publicar
 📈
Benchmarks DRL+44.18% revenue · BENCHMARK-004

¿Listo para empezar?

El entorno está un git clone de distancia. El simulador incluye datos CMg reales del mercado SEN.

GitHub — Fork ahora ★ Discord #dev → Docs completas ↗