agmen 0.2.0__tar.gz

agmen-0.2.0/.gitignore

@@ -0,0 +1,5 @@
+/build*/
+__pycache__/
+*.pyc
+.vscode/
+.idea/

agmen-0.2.0/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+Todos los cambios importantes de Agmen se anotan aquí. Formato basado en
+[Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/); versiones según
+[SemVer](https://semver.org/lang/es/). Política completa en
+[`docs/VERSIONES.md`](docs/VERSIONES.md).
+
+## [Sin publicar]
+
+### Planeado (nivel 1, versión 0.3.0)
+- Sobre v1 de 64 bytes + codificación `compact` + esquema en texto (RFC 0001).
+
+## [0.2.0] — 2026-10-30
+
+**Todo el robot con un solo comando** y un panel web para controlarlo
+(RFC 0003). Se acabaron las diez terminales.
+
+### Agregado
+- Comando `agmen` (se instala con `pip install agmen`).
+- `agmen run robot.toml`: lanza todos los nodos descritos en un archivo, junta
+  sus logs en una sola terminal con color por nodo, los reinicia si fallan
+  (`restart = "on-failure"`), compila antes si se pide (`before`) y con Ctrl+C
+  los detiene a todos de forma ordenada. Errores de configuración con
+  sugerencias ("¿Quisiste decir 'name'?").
+- Panel web de control: estado de cada nodo con botones iniciar / detener /
+  reiniciar, logs de todos los nodos con filtros, gráficas de sensores y
+  **manejo del robot** con teclado (W A S D) o botones táctiles. Al soltar, el
+  robot frena.
+- `agmen web`: el panel solo, sin administrar nodos.
+- `examples/tutorial/robot.toml` y capítulo 5 del tutorial.
+- Pruebas `scripts/run_smoke.py` en el CI.
+
+### Cambiado
+- `tools/agmen-web/bridge.py` se reemplaza por `agmen web`, incluido en el paquete.
+
+### Corregido (encontrado por el primer CI en GitHub)
+- Windows: los nodos de Python ya no truenan al imprimir acentos o "→" cuando
+  su salida va a un archivo u otro programa (`agmen.ensure_utf8_output()`).
+- macOS: el panel ya no tarda en arrancar por una consulta DNS lenta.
+
+### Seguridad
+- El panel rechaza peticiones de otros sitios (protección CSRF), recorta los
+  comandos de manejo a la velocidad máxima y limita su frecuencia.
+
+## [0.1.0] — 2026-10-30
+
+Primera versión pública: **Nivel 0**.
+
+### Agregado
+- Núcleo en C++20 (`#include <agmen/agmen.hpp>`, `namespace agmen::`) con CMake.
+- Formato de cable v0: header de 32 bytes, `type_id` por hash del esquema y
+  errores claros (`agmen::wire::WireError`).
+- Socket UDP multiplataforma (Windows/Linux/macOS) y sleep de alta resolución
+  en Windows.
+- Ejemplos `publisher` y `subscriber` con medición de latencia y pérdidas.
+- Paquete de Python `agmen` (implementación de referencia del formato).
+- Prototipo de interfaz web `tools/agmen-web` (el navegador dibuja; el robot
+  solo publica).
+- Tutorial: capítulos 0 a 4.
+- RFC 0001 (formato de mensajes v1, **aceptado**) y RFC 0002 (interfaz web,
+  propuesta).
+- CI en Windows (MSVC), Linux (GCC + sanitizers) y macOS (Clang).
+
+[Sin publicar]: https://github.com/flkochu/Agmen/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/flkochu/Agmen/releases/tag/v0.2.0
+[0.1.0]: https://github.com/flkochu/Agmen/releases/tag/v0.1.0

agmen-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adán López Lozano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agmen-0.2.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: agmen
+Version: 0.2.0
+Summary: Agmen: el sistema nervioso para robótica, IA e IoT
+Project-URL: Repository, https://github.com/flkochu/Agmen
+Project-URL: Changelog, https://github.com/flkochu/Agmen/blob/main/CHANGELOG.md
+Author: Adán López Lozano
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,iot,middleware,pubsub,robotica,robotics,ros
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: tomli>=1.1; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# agmen (Python)
+
+**Agmen** es un framework de código abierto para robótica, IA e IoT. Su núcleo
+(en C++) es el "sistema nervioso" del robot: mueve mensajes entre nodos de
+forma rápida, confiable y con marca de tiempo.
+
+Este paquete es la **implementación de referencia en Python** del formato de
+mensajes. Con él, un nodo de Python habla con nodos de C++ sin dependencias
+extra.
+
+```bash
+pip install agmen
+```
+
+```python
+from agmen import wire
+
+msg = wire.ImuSample(accel=(0.0, 0.0, 9.81), gyro=(0.0, 0.0, 0.1))
+packet = wire.encode(msg, seq=0, stamp_ns=wire.now_ns())
+header, back = wire.decode(wire.ImuSample, packet)
+```
+
+También instala el comando `agmen`, que levanta todo tu robot con un solo
+comando y abre un panel web para controlarlo:
+
+```bash
+agmen run robot.toml     # todos los nodos + panel web (nodos, logs, sensores, manejar)
+agmen web                # solo el panel
+```
+
+> ⚠ Versión 0.x: la API todavía va a cambiar entre versiones menores.
+
+Documentación, tutorial y código: <https://github.com/flkochu/Agmen>

agmen-0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0

agmen-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+# Paquete de Python `agmen` (pip install agmen).
+#
+# Hoy contiene la implementación de referencia del formato en Python puro.
+# En el nivel 6 este mismo paquete se compilará desde el núcleo de C++
+# (nanobind + scikit-build-core) sin cambiar de nombre.
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agmen"
+dynamic = ["version"]
+description = "Agmen: el sistema nervioso para robótica, IA e IoT"
+readme = "python/README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "tomli>=1.1; python_version < '3.11'",   # robot.toml en Python 3.10
+]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Adán López Lozano" }]
+keywords = ["robotics", "robotica", "middleware", "pubsub", "ros", "ai", "iot"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Natural Language :: Spanish",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.scripts]
+agmen = "agmen.cli:main"
+
+[project.urls]
+Repository = "https://github.com/flkochu/Agmen"
+Changelog = "https://github.com/flkochu/Agmen/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "python/agmen/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/agmen"]
+
+[tool.hatch.build.targets.sdist]
+include = ["python/agmen", "python/README.md", "LICENSE", "VERSION", "CHANGELOG.md"]

agmen-0.2.0/python/README.md

@@ -0,0 +1,33 @@
+# agmen (Python)
+
+**Agmen** es un framework de código abierto para robótica, IA e IoT. Su núcleo
+(en C++) es el "sistema nervioso" del robot: mueve mensajes entre nodos de
+forma rápida, confiable y con marca de tiempo.
+
+Este paquete es la **implementación de referencia en Python** del formato de
+mensajes. Con él, un nodo de Python habla con nodos de C++ sin dependencias
+extra.
+
+```bash
+pip install agmen
+```
+
+```python
+from agmen import wire
+
+msg = wire.ImuSample(accel=(0.0, 0.0, 9.81), gyro=(0.0, 0.0, 0.1))
+packet = wire.encode(msg, seq=0, stamp_ns=wire.now_ns())
+header, back = wire.decode(wire.ImuSample, packet)
+```
+
+También instala el comando `agmen`, que levanta todo tu robot con un solo
+comando y abre un panel web para controlarlo:
+
+```bash
+agmen run robot.toml     # todos los nodos + panel web (nodos, logs, sensores, manejar)
+agmen web                # solo el panel
+```
+
+> ⚠ Versión 0.x: la API todavía va a cambiar entre versiones menores.
+
+Documentación, tutorial y código: <https://github.com/flkochu/Agmen>

agmen-0.2.0/python/agmen/__init__.py

@@ -0,0 +1,29 @@
+"""Agmen para Python.
+
+Por ahora contiene la implementación de referencia del formato de cable en
+Python puro (`agmen.wire`). Más adelante este paquete se compilará desde el
+núcleo de C++ (nanobind) y `agmen.wire` quedará como referencia y oráculo de pruebas.
+"""
+
+import sys
+
+from . import wire
+from ._version import __version__
+
+__all__ = ["wire", "__version__", "ensure_utf8_output"]
+
+
+def ensure_utf8_output() -> None:
+    """Hace que print() nunca truene por acentos, "→" o "µs".
+
+    En Windows, cuando la salida va a un archivo o a otro programa (no a la
+    consola), Python usa la codificación vieja cp1252 y falla con
+    UnicodeEncodeError. Llama a esto al inicio de tu nodo.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8", errors="replace")
+            except (ValueError, OSError):
+                pass
+

agmen-0.2.0/python/agmen/__main__.py

@@ -0,0 +1,7 @@
+"""Permite `python -m agmen run robot.toml` (igual que el comando `agmen`)."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

agmen-0.2.0/python/agmen/_version.py

@@ -0,0 +1,2 @@
+# Debe coincidir con el archivo VERSION de la raíz (lo verifica scripts/check_version.py).
+__version__ = "0.2.0"

agmen-0.2.0/python/agmen/cli.py

@@ -0,0 +1,121 @@
+"""El comando `agmen`.
+
+    agmen run [robot.toml]     lanza todo el robot + panel web, con un solo comando
+    agmen web                  solo el panel web (sin administrar nodos)
+    agmen version              muestra la versión
+"""
+
+from __future__ import annotations
+
+import argparse
+import signal
+import sys
+import threading
+
+from ._version import __version__
+
+
+def _wait_for_ctrl_c(stop: threading.Event) -> None:
+    def handler(signum, frame):
+        stop.set()
+
+    signal.signal(signal.SIGINT, handler)
+    signal.signal(signal.SIGTERM, handler)
+    if hasattr(signal, "SIGBREAK"):  # Windows
+        signal.signal(signal.SIGBREAK, handler)
+    while not stop.wait(0.3):
+        pass
+
+
+def cmd_run(args) -> int:
+    from .panel import Panel, Teleop
+    from .run import ConfigError, Launcher, load_config
+
+    try:
+        config = load_config(args.archivo)
+    except ConfigError as e:
+        print(f"error en {args.archivo}: {e}", file=sys.stderr)
+        return 2
+
+    launcher = Launcher(config)
+    launcher.say(f"Agmen {__version__} · robot '{config.name}' · {len(config.nodes)} nodos")
+    if not launcher.run_before():
+        return 1
+
+    panel = None
+    if config.web.enabled and not args.no_web:
+        teleop = Teleop(config.web.teleop.target, config.web.teleop.max_speed) if config.web.teleop else None
+        try:
+            panel = Panel(args.http or config.web.http, config.web.listen, config.name, launcher, teleop)
+        except OSError as e:
+            print(f"no se pudo abrir el panel web en {args.http or config.web.http}: {e}. "
+                  f"¿Ya hay otro 'agmen run' corriendo? Usa --http 127.0.0.1:8081", file=sys.stderr)
+            return 1
+        panel.start(open_browser=config.web.open_browser and not args.no_browser)
+        launcher.say(f"panel web: {panel.url}")
+
+    launcher.start_all()
+    launcher.say("todo arrancado. Ctrl+C para detener todo.")
+    stop = threading.Event()
+    try:
+        _wait_for_ctrl_c(stop)
+    finally:
+        launcher.stop_all()
+        if panel:
+            panel.shutdown()
+    return 0
+
+
+def cmd_web(args) -> int:
+    from .panel import Panel, Teleop
+
+    teleop = Teleop(args.teleop, 1.0) if args.teleop else None
+    try:
+        panel = Panel(args.http, args.listen, "", None, teleop)
+    except OSError as e:
+        print(f"no se pudo abrir el panel en {args.http}: {e}", file=sys.stderr)
+        return 1
+    panel.start(open_browser=not args.no_browser)
+    print(f"[agmen web] recibiendo Agmen en udp://{args.listen}")
+    print(f"[agmen web] abre {panel.url} en tu navegador")
+    if args.http.startswith("0.0.0.0"):
+        print("[agmen web] también accesible desde otros equipos de tu red (sin contraseña)")
+    stop = threading.Event()
+    try:
+        _wait_for_ctrl_c(stop)
+    finally:
+        panel.shutdown()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="agmen", description="Agmen: el sistema nervioso para robótica, IA e IoT")
+    ap.add_argument("--version", action="version", version=f"agmen {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True, metavar="comando")
+
+    p = sub.add_parser("run", help="lanza todos los nodos de robot.toml + el panel web")
+    p.add_argument("archivo", nargs="?", default="robot.toml", help="archivo del robot (default: robot.toml)")
+    p.add_argument("--no-web", action="store_true", help="no abrir el panel web")
+    p.add_argument("--no-browser", action="store_true", help="no abrir el navegador automáticamente")
+    p.add_argument("--http", help="dónde servir el panel (ej. 0.0.0.0:8080 para verlo desde el celular)")
+    p.set_defaults(func=cmd_run)
+
+    p = sub.add_parser("web", help="solo el panel web (sin administrar nodos)")
+    p.add_argument("--listen", default="127.0.0.1:7400", help="dónde recibir mensajes Agmen (UDP)")
+    p.add_argument("--http", default="127.0.0.1:8080", help="dónde servir el panel")
+    p.add_argument("--teleop", metavar="IP:PUERTO", help="habilita manejar el robot: destino de MotorCommand")
+    p.add_argument("--no-browser", action="store_true", help="no abrir el navegador automáticamente")
+    p.set_defaults(func=cmd_web)
+
+    p = sub.add_parser("version", help="muestra la versión")
+    p.set_defaults(func=lambda a: print(f"agmen {__version__}") or 0)
+
+    from . import ensure_utf8_output
+
+    ensure_utf8_output()
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agmen-0.2.0/python/agmen/panel/__init__.py

@@ -0,0 +1,5 @@
+"""Panel web de Agmen: el navegador dibuja, el robot solo publica."""
+
+from .server import MotorCommand, Panel, Teleop
+
+__all__ = ["Panel", "Teleop", "MotorCommand"]