Cardinal-System

Cardinal-System es un framework de Swift (SwiftPM) para construir aplicaciones orientadas a eventos, acciones y permisos, con un sistema de red basado en WebSockets y un módulo de agente (LLM) para tomar decisiones de forma distribuida entre nodos.

Requisitos

• Swift 5.9+ (probado con Swift 6.3 en Linux)
• macOS 10.14+ o Linux

Estructura del paquete

Sources/
├── Cardinal-System/        # Librería principal
│   ├── Core/                # Protocolos base: Information, Event, Listener, Command, Entity
│   ├── Action/               # CardinalAction (protocolo) y ActionExecutor (actor, registro/despacho de acciones)
│   ├── Permission/           # Permission, Group, Context y PermissionManager (actor)
│   ├── Storage/               # Storage (protocolo) y ConfigStorage (YAML vía Yams)
│   ├── Network/               # Servidor WebSocket (SwiftNIO)
│   ├── Agent/                 # Agente LLM híbrido (ver más abajo)
│   └── System/                 # Cardinal (protocolo de entrada) y Application
└── Run/                     # Ejecutable de ejemplo (target `Run`)

Tests/
└── Cardinal-SystemTests/    # Pruebas unitarias

Conceptos principales

• Event / Listener / CardinalAction: modelo pub-sub. Un Event lleva asociada una action (@Sendable () -> Void); un Listener reacciona a eventos; un CardinalAction se dispara cuando ocurre un evento asociado.
• EventManager (actor): registra eventos y expone subscribe() como AsyncStream<Event> para consumidores async, además del modelo legacy de Listeners.
• ActionExecutor (actor, ActionExecutor.shared): registro central de acciones (registerAction) y despacho (notifyActions). También expone toolManifest() para listar las acciones registradas como herramientas utilizables por un agente.
• PermissionManager (actor): control de permisos (add, remove, isGranted).
• Cardinal (protocolo): punto de entrada de la aplicación (run(), excutableServer() para levantar el servidor WebSocket).

Agente híbrido (Sources/Cardinal-System/Agent)

El módulo Agent implementa un ciclo de decisión basado en LLM, pensado para un sistema distribuido donde cada nodo puede resolver localmente o escalar ("delegar") a un nodo líder:

• CardinalAgentClient: protocolo que abstrae el proveedor del modelo. Implementaciones incluidas:
  • OllamaClient — vía AsyncHTTPClient contra /api/chat de Ollama.
  • OpenRouterClient — vía AsyncHTTPClient contra /chat/completions de OpenRouter (API key inyectada por el llamador, nunca hardcodeada).
• AgentMessage: mensaje de chat agnóstico de proveedor (role, content).
• Decision / ActionSchema: formato JSON estructurado que el modelo debe devolver, validado y convertido a AgentAction.
• AgentAction: respond, callTool, createSkill o delegate.
• ToolSpec: describe una herramienta disponible para el agente (se genera, entre otros, desde ActionExecutor.toolManifest()).
• PromptBuilder: construye el system prompt con el manifiesto de tools.
• CardinalAgent (actor): mantiene el historial de conversación por nodo y ejecuta un paso de decisión (step(input:tools:)) contra cualquier CardinalAgentClient.

Ver MIGRATION_PLAN.md para el diseño completo de la arquitectura distribuida (nodos líder/worker, delegación, red) y el trabajo pendiente (skill-registry, network-envelope, node-role, wire-example).

Compilar y probar

swift build
swift test --parallel

Ejecutar el ejemplo (Run)

swift run Run

El target Run (Sources/Run/ALO.swift) registra acciones de ejemplo y levanta el servidor WebSocket vía Cardinal.excutableServer().

Licencia

Apache License 2.0 — ver LICENSE.txt.