holonet-py 1.0.0

Infraestructura experimental para la simulación de redes muónicas holográficas

Holonet Muónica

Proyecto experimental basado en la hoja de ruta muónica. Este repositorio implementa la infraestructura necesaria para simular la red holográfica y preparar integraciones posteriores con hardware y servicios externos. La versión 1.0.0 marca el primer hito público disponible tanto en GitHub como en PyPI.

Instalación desde PyPI

pip install holonet-py

La distribución publica el paquete holonet y expone todas las abstracciones descritas en la documentación. Para verificar la versión instalada se puede ejecutar:

import holonet

print(holonet.__version__)

Si el comando imprime 1.0.0, la instalación coincide con la versión liberada.

Estructura inicial

src/holonet/
├── core/
├── modulation/
├── transmission/
├── decoding/
├── network/
├── interface/
├── simulation/
├── hardware/
└── security/

Plan de tareas

El desarrollo se organiza según las fases propuestas:

1. Inicialización: configuración de empaquetado, documentación y estructura base.
2. Abstracciones núcleo: definición de paquetes, señales y nodos.
3. Simulación: motor muónico inicial, transporte y decodificación.
4. Modulación: patrones leptónicos reutilizables.
5. Red: topologías y coordinación de nodos.
6. Interfaces: API web y puente WebSocket.
7. Hardware simulado: drivers mock y seguridad básica.
8. Inteligencia adaptativa: algoritmos de optimización y topología dinámica.
9. Empaquetado y CI/CD: documentación extendida y flujos de despliegue.

Cada tarea se implementa con módulos y pruebas específicas para facilitar la colaboración futura.

Uso

1. Instalar dependencias para desarrollo local (incluye pruebas y documentación):

   pip install -e .[tests,docs]
   

   Nota: el extra tests instala httpx, necesario para ejecutar las pruebas que dependen de fastapi.testclient.

2. Ejecutar pruebas con cobertura:

   coverage run -m pytest
   

3. Generar reportes de cobertura:

   coverage xml
   coverage report
   

   El archivo coverage.xml se puede abrir con herramientas compatibles (por ejemplo, VS Code o Codecov) y el comando coverage report mostrará un resumen en la terminal.
4. Generar documentación:

   mkdocs serve
   

5. Validar la documentación generada y los enlaces externos:

   mkdocs build --strict
   HTMLPROOFER_VALIDATE_RENDERED=true mkdocs build --strict
   

   El primer comando ejecuta una compilación estricta que activa el plugin mkdocs-htmlproofer-plugin sobre el contenido en Markdown. El segundo vuelve a ejecutar la verificación analizando el HTML final renderizado; así se detectan posibles problemas introducidos por plantillas o extensiones.

Despliegue automático de la documentación

El repositorio cuenta con un flujo de trabajo de GitHub Actions que instala las dependencias de documentación y ejecuta mkdocs gh-deploy cada vez que se hace push sobre la rama main. La acción utiliza el GITHUB_TOKEN integrado del repositorio con permisos de escritura sobre el historial para publicar el sitio en la rama gh-pages.

Para completar la configuración es necesario habilitar GitHub Pages desde Settings → Pages y seleccionar GitHub Actions como fuente de despliegue. Tras guardar los cambios, cada actualización en main generará y publicará automáticamente la última versión de la documentación.

Configuración de LeptonicGuard

• De forma predeterminada utiliza InMemoryTokenStore, un almacén en memoria que no requiere configuración adicional.
• Los tokens emitidos caducan automáticamente (TTL configurable, 5 minutos por defecto) y se registran eventos de auditoría accesibles mediante POST /audit/events.
• Para reutilizar tokens entre procesos se puede instalar la dependencia opcional redis e inicializar el guardián con RedisTokenStore:

  from redis import Redis
  from holonet.security.leptonic_guard import LeptonicGuard
  from holonet.security.token_store import RedisTokenStore
  
  guard = LeptonicGuard(store=RedisTokenStore(Redis.from_url("redis://localhost:6379/0")))
  

• En entornos de pruebas se recomienda inyectar un stub que implemente TokenStoreProtocol para verificar la emisión y validación de tokens.
• La API REST incorpora POST /nodes/register para asociar un secreto compartido a cada nodo antes de solicitar tokens con POST /token.

Repositorio de ejemplos

El directorio examples/ agrupa proyectos listos para clonar o copiar dentro de otros repositorios:

• Flask: microservicio que utiliza MTQBridge para exponer un endpoint REST con resultados de túneles cuánticos simulados.
• FastAPI: API asíncrona con streaming de eventos MTQ y validación mediante pydantic.
• Sockets MTQ: servidor y cliente que intercambian marcos ópticos encapsulados a través de sockets TCP convencionales, demostrando la capa túnel clásica.

Cada ejemplo incluye instrucciones de ejecución y comandos de prueba rápidos. Se puede utilizar como base de un repositorio externo dedicado a demostraciones.

Contenedor Docker experimental

El directorio docker/ contiene un Dockerfile listo para construir un contenedor con la red tunelada simulada. La imagen instala holonet-py, expone scripts para activar una topología MTQ mínima y configura tmux para observar los túneles generados. Ejemplo rápido de construcción y ejecución:

docker build -t holonet-sandbox docker/
docker run --rm -it -p 8000:8000 holonet-sandbox

El contenedor inicia un uvicorn con el demo de FastAPI y mantiene disponible una sesión interactiva para ejecutar los demás ejemplos.