swarm-rd-orchestrator

Registro de eventos de solo anexión para compartir contexto/memoria entre agentes mediante 3 herramientas MCP.

GitHubPrueba este MCPPatrocinado

Documentación

swarm-rd-orchestrator-cli

PyPI npm License: Apache 2.0 Python Tests Status

Instalación • Inicio rápido • Referencia de comandos • Servidor MCP • Comparación • Preguntas frecuentes

Intercambio de contexto y memoria nativo de Ray para agentes de investigación paralelos, con una CLI nativa para agentes y un servidor MCP.

Demo: appending findings from two agents and pulling them back through swarm-rd-cli

Un registro de eventos de solo adición respaldado por SQLite-WAL envuelto como un actor de Ray, para que agentes paralelos puedan escribir hallazgos y consultar los de los demás sin un almacén mutable compartido, además de una CLI y un servidor MCP para que tanto humanos como otros agentes puedan manejarlo directamente.

Este es un prototipo del Hito 1 (2026-08-03): valida el enfoque en una tarea real antes de seguir construyendo. Consulta Decisiones bloqueadas a continuación y spike.py para el arnés de validación real.

Instalación

pip install swarm-rd-orchestrator-cli
# or
npm install -g swarm-rd-orchestrator-cli

Cualquiera de las dos opciones te da un comando swarm-rd-cli en tu PATH. El paquete npm es un envoltorio delgado alrededor de la CLI de Python: ejecuta el binario real, no lo reimplementa. Instala también el paquete de Python si usas el de npm.

Estado: activo en ambos registros (PyPI publicado mediante GitHub Actions OIDC, sin token almacenado). Ambos se verificaron con una instalación real y una ejecución real de comandos en un entorno limpio, no solo con una carga exitosa.

[!ADVERTENCIA] Este es un prototipo del Hito 1 previo a la validación (0.0.x), aún no es una versión estable. Probado solo en macOS; el soporte para Windows no está verificado, ya que el soporte de Ray para Windows es más limitado que el de Linux/macOS en el upstream.

Inicio rápido

swarm-rd-cli append task-1 agent-a "found a race condition in the retry loop" --kind result
swarm-rd-cli append task-1 agent-b "confirmed: retry loop isn't holding the lock" --kind result
swarm-rd-cli pull task-1
# [1] (agent-a/result) found a race condition in the retry loop
# [2] (agent-b/result) confirmed: retry loop isn't holding the lock

swarm-rd-cli --json pull task-1     # structured output for scripts/agents
swarm-rd-cli list-tasks             # every task_id with a delta count
swarm-rd-cli mcp                    # run as an MCP server over stdio

Cada comando que devuelve datos admite --json para consumo por agentes y scripts, sin necesidad de extraer texto de pantalla. El subcomando mcp expone append_delta, pull_deltas y list_tasks como herramientas MCP tipadas sobre stdio, para que un agente pueda llamarlo programáticamente en lugar de invocar un subproceso.

Características

  • Adición atómica, probada, no solo afirmada. Una prueba dedicada simula un fallo a mitad de escritura y confirma que la capa WAL de SQLite deja cero filas parciales, no solo una descripción de la garantía.
  • Salida estructurada en cada comando de datos. --json en append, pull y list-tasks significa que un agente que invoca esta CLI nunca tiene que extraer texto de formato humano.
  • Un servidor MCP, no solo una CLI. swarm-rd-cli mcp expone las mismas tres operaciones como herramientas tipadas sobre stdio, para que un agente pueda llamarlo programáticamente en lugar de generar un subproceso.
  • Concurrencia probada con actores reales de Ray, no simulados. La prueba de carga ejecuta 3 actores reales de Ray añadiendo de forma concurrente y concilia el resultado, el mismo mecanismo que usa la carga de trabajo real.
  • Entrada malformada falla de forma ruidosa. Un delta que carece de task_id, agent_id o content lanza InvalidDeltaError antes de tocar el almacenamiento. Sin descartes silenciosos.

Referencia de comandos

Demo: swarm-rd-cli --help output

Generado a partir de la salida --help de la propia CLI:

usage: swarm-rd-cli [-h] [--db DB] [--json] {append,pull,list-tasks,mcp} ...

positional arguments:
  {append,pull,list-tasks,mcp}
    append              append a delta to the event log
    pull                pull deltas for a task
    list-tasks          list every task_id with a delta count
    mcp                 run as an MCP server over stdio

options:
  -h, --help            show this help message and exit
  --db DB               path to the event log (default: swarm-events.db)
  --json                structured JSON output (for agent/script use)

usage: swarm-rd-cli append [-h] [--kind {note,result,tool_output}]
                            task_id agent_id content

positional arguments:
  task_id
  agent_id
  content

options:
  -h, --help            show this help message and exit
  --kind {note,result,tool_output}

usage: swarm-rd-cli pull [-h] [--since SINCE] task_id

positional arguments:
  task_id

options:
  -h, --help     show this help message and exit
  --since SINCE  cursor to pull after

Demo: appending deltas from two more agents, then list-tasks and a --json pull

Servidor MCP

swarm-rd-orchestrator-cli incluye un servidor del Protocolo de Contexto de Modelos (MCP), para que un agente pueda llamar al registro de eventos directamente como herramientas tipadas sobre stdio en lugar de invocar la CLI y analizar texto.

pip install "swarm-rd-orchestrator-cli[mcp]"

Ejecútalo con:

swarm-rd-cli mcp

Agrégalo a Claude Desktop (o a cualquier otro cliente MCP) apuntando a ese comando en tu configuración:

{
  "mcpServers": {
    "swarm-rd-orchestrator": {
      "command": "swarm-rd-cli",
      "args": ["mcp"]
    }
  }
}

Se exponen tres herramientas:

  • append_delta(task_id, agent_id, content, kind="note") - añade un hallazgo/resultado/salida de herramienta al registro de eventos de una tarea. Ejemplo: append_delta(task_id="task-1", agent_id="agent-a", content="found a race condition in the retry loop", kind="result").
  • pull_deltas(task_id, since_cursor=0) - extrae cada delta de una tarea con id mayor que since_cursor, del más antiguo al más reciente. Ejemplo: pull_deltas(task_id="task-1") devuelve el historial completo; pull_deltas(task_id="task-1", since_cursor=2) devuelve solo los deltas escritos después del cursor 2.
  • list_tasks() - lista cada task_id actualmente en el registro de eventos con su recuento de deltas. Ejemplo: list_tasks() devuelve [{"task_id": "task-1", "delta_count": 2}].

Comparación

swarmmesh es un proyecto hermano en el portafolio de este autor, también publicado como swarmmesh-cli en PyPI y npm. Es la opción más completa hoy en casi todas las dimensiones a continuación. Este proyecto existe como una alternativa deliberadamente nativa de Ray, no porque swarmmesh sea inferior.

swarm-rd-orchestrator-cliswarmmesh-cli
TransporteActor de Ray (en proceso / distribuido)Servidor HTTP
AlmacenamientoSQLite, modo WALEn memoria por defecto, o SQLite mediante --persist
Multi-lenguajeSolo PythonPython y Node
Búsqueda/clasificación de memoriaNinguna (extracción por task_id solamente)Clasificación por palabras clave BM25 en consultas de memoria
Servidor MCPSíSí
Publicado en PyPI/npmSí, activoSí, activo
CISíSí

Si el ángulo de cómputo distribuido nativo de Ray no termina siendo relevante para tu caso de uso, usa swarmmesh en su lugar. Está activo, probado contra uso real y hace más.

Qué es swarm-rd-orchestrator-cli y por qué existe

swarm-rd-orchestrator-cli es un registro de eventos compartido y duradero para agentes de investigación de IA paralelos construido sobre el modelo de actores de Ray. Cada agente escribe hallazgos como deltas estructurados; cualquier otro agente puede extraer el historial completo de una tarea sin un almacén mutable compartido ni un proceso de servidor coordinador.

Existe para probar una hipótesis específica y estrecha: que el modelo de actores y almacén de objetos de Ray es un mejor ajuste para coordinar un número genuinamente grande de agentes de investigación paralelos que una capa de coordinación basada en HTTP. Esa hipótesis no está probada. El proyecto se publica como un prototipo del Hito 1 específicamente para probarla contra una carga de trabajo real antes de cualquier inversión adicional; consulta Ejecuta el prototipo de validación real.

Compilar desde el código fuente

git clone https://github.com/RudrenduPaul/swarm-rd-orchestrator.git
cd swarm-rd-orchestrator
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,mcp]"

Requiere Python 3.10 o más reciente (necesario para la dependencia del SDK mcp).

Ejecutar las pruebas

.venv/bin/pytest test_event_log.py -v

9/9 pasando, incluida la prueba de carga: 3 actores concurrentes de Ray añadiendo a un registro de eventos compartido, conciliado con cero deltas perdidos o duplicados.

Ejecutar el prototipo de validación real

Edita REAL_TASK_ID, REAL_TASK_DESCRIPTION y los hallazgos de agentes de muestra en spike.py para reflejar una tarea de investigación real, luego:

.venv/bin/python3 spike.py

Lee la rúbrica impresa al final. La regla de decisión: menos de 3 casos de fallo arquitectónico calificados contra Ray o LangGraph en bruto significa recurrir a un envoltorio CLI delgado en lugar de seguir construyendo esto.

Decisiones bloqueadas (2026-08-03)

  • Primitiva: Ray (modelo de actores y almacén de objetos), LangGraph como respaldo
  • Almacenamiento: SQLite, modo WAL
  • Forma del delta: {task_id, agent_id, timestamp, content, kind}
  • Delta malformado lanza InvalidDeltaError, nunca silencioso
  • Licencia: Apache 2.0
  • Python: 3.10 o más reciente, requerido para el SDK mcp
  • Publicación: activo en PyPI (mediante GitHub Actions OIDC Trusted Publishing, sin token almacenado) y npm, ambos verificados con una instalación real en entorno limpio

Preguntas frecuentes

¿Qué hace esto realmente? Da a agentes de IA paralelos, que se ejecutan como actores de Ray, un lugar compartido y duradero para escribir hallazgos y consultar los de los demás, sin pisarse el estado entre sí. Es una capa de transporte y persistencia, no un marco de orquestación: no programa agentes ni decide qué hacen.

¿En qué se diferencia de swarmmesh? Consulta Comparación arriba. Misma idea central, diferente transporte (actores de Ray en lugar de HTTP), y swarmmesh es actualmente la opción más completa y ya publicada.

¿Funciona en Windows, macOS y Linux? Probado en macOS. Ray admite Linux y macOS de forma nativa; el soporte de Windows para Ray es más limitado en el upstream, así que trata Windows como no verificado para este proyecto específicamente hasta que alguien lo confirme.

¿Necesita mis propias claves API? No. Este proyecto no hace llamadas de LLM por sí mismo. Es una capa de coordinación que tus propios agentes, sea cual sea el modelo o marco que usen, escriben y leen.

¿Es seguro depender de esto? No, aún no. Este es un prototipo del Hito 1 previo a la validación (versiones 0.0.x), no una versión estable. Las garantías centrales del registro de eventos (adición atómica, sin escrituras parciales) están probadas en test_event_log.py, pero el proyecto aún no se ha validado contra una carga de trabajo multiagente real más allá del script del prototipo.

¿Cómo lo uso desde un agente, no solo desde un humano? O invoca la CLI con --json en cada comando, o ejecuta swarm-rd-cli mcp y conéctate a él como servidor MCP. Ambos dan salida estructurada y analizable.

¿Es una biblioteca o solo una CLI? Ambos. Las clases EventLog y EventLogActor de event_log.py son directamente importables si ya estás en Python y no necesitas la CLI ni la capa MCP.

¿Bajo qué licencia está y puedo usarlo comercialmente? Apache 2.0. El uso comercial, la modificación y la redistribución están permitidos bajo sus términos; consulta LICENCIA para el texto completo.

Contribuciones

No hay CONTRIBUTING.md aún, ya que este es un prototipo previo a la validación, no un proyecto con contribuciones aceptadas. Abre un issue si quieres discutir un cambio antes de que esto exista formalmente.

Licencia

Apache 2.0. Consulta LICENCIA para el texto completo.