shepherd-meta-agents

name	shepherd-meta-agents
version	1.0.0
description	Shepherd — runtime substrate para meta-agents con traces reversibles tipo Git y copy-on-write fork

Shepherd — Reversible Agent Execution Traces

Descripción

Shepherd es un runtime substrate para agents que necesitan inspección, reversibilidad y supervisión. Registra ejecuciones de agents como traces duraderos e inspeccionables, con copy-on-write fork ~5x más rápido que docker commit y ~95% KV-cache reuse en replay.

Por qué importa para David

• Meta-agents: Patrón avanzado de agents que supervisan/optimizan/entrenan otros agents
• Reversible execution: Git-like traces permiten replay, fork y revert de cualquier run
• Copy-on-write: Fork de workspace ultra-rápido sin duplicar datos
• KV-cache reuse: Reutiliza 95% del KV cache en replay → ahorrísimo en inference cost

Arquitectura

Meta-Agent → Supervisor
    ↓
Agent Run (workspace forked copy-on-write)
    ↓
Durable Execution Trace (inspectable, reversible)
    ↓
Meta-Agent: Observe → Fork → Replay → Revert

Instalación

pip install shepherd-ai
# Requiere Python 3.11+
# macOS: Seatbelt enforcement
# Linux: Landlock enforcement

Integración con proyectos de David

• Mastermind Orchestration: Patrón de supervisión de sub-agents con reversibilidad
• Debugging de agents: Replay de runs para debugging y optimización
• Multi-agent training: Tree RL con MCTS para optimización de agents

Pitfalls

• Proyecto alpha (junio 2026) → API inestable, puede cambiar
• Requiere Python 3.11+
• Enforcement OS-level (Seatbelt en macOS, Landlock en Linux)
• No tiene docs completas aún, hay que leer el código fuente
• Depende de kernel-level features que pueden no estar disponibles en MicroVM de NaN

Referencias

• GitHub: https://github.com/shepherd-agents/shepherd
• Docs: https://docs.shepherd-agents.ai/
• Paper: https://arxiv.org/abs/2605.10913
• Paper: https://arxiv.org/abs/2505.10913