DSPyTools: Un CLI Auto-Evolucionable para la Gestión de Programas DSPy

DSPy made declarative LLM programming practical — define signatures, attach metrics, let the optimizer search. But managing the full lifecycle of compiled programs — selecting the right optimizer, deploying without downtime, tracking experiments, evolving over time — remained a manual, fragmented process. DSPyTools closes that gap. It is a production-grade CLI with 24 command groups, 110+ subcommands, 17+ optimizers, 11 arXiv paper implementations, and a self-evolving engine that treats program optimization as a continuous, automated loop rather than a one-off compilation step.

DSPy hizo que la programación declarativa de LLMs fuera práctica — define signatures, adjunta métricas, deja que el optimizador busque. Pero gestionar el ciclo de vida completo de los programas compilados — seleccionar el optimizador correcto, desplegar sin downtime, rastrear experimentos, evolucionar con el tiempo — seguía siendo un proceso manual y fragmentado. DSPyTools cierra esa brecha. Es un CLI de grado producción con 24 grupos de comandos, más de 110 subcomandos, más de 17 optimizadores, 11 implementaciones de papers de arXiv y un motor auto-evolutivo que trata la optimización de programas como un bucle continuo y automatizado en lugar de un paso de compilación único.

The Teacher-Student Architecture

La Arquitectura Profesor-Estudiante

DSPyTools is built on a teacher-student split. The student — a Qwen3.5-9B model served via llama-cpp-server on port 8080 — handles all compiled program inference at production latency. The teacher — DeepSeek V4 Flash via API — handles the heavy optimization work: GEPA reflection, MIPROv2 proposal generation, Meta Agent Search archive validation, Gödel Agent holdout testing. This separation means a 9B model can serve production inference while a frontier model does the expensive meta-reasoning during compilation. The student never calls the teacher at inference time — only during optimization cycles.

DSPyTools está construido sobre una división profesor-estudiante. El estudiante — un modelo Qwen3.5-9B servido vía llama-cpp-server en el puerto 8080 — maneja toda la inferencia de programas compilados a latencia de producción. El profesor — DeepSeek V4 Flash vía API — maneja el trabajo pesado de optimización: reflexión GEPA, generación de propuestas MIPROv2, validación de archivo Meta Agent Search, pruebas de holdout del Gödel Agent. Esta separación significa que un modelo de 9B puede servir inferencia de producción mientras un modelo frontera hace el meta-razonamiento costoso durante la compilación. El estudiante nunca llama al profesor en tiempo de inferencia — solo durante los ciclos de optimización.

17+ Optimizers in One CLI

Más de 17 Optimizadores en un Solo CLI

The core value proposition is that DSPyTools exposes every major DSPy optimizer through a single, consistent CLI interface. dspytools compile knn <module> <trainset> for KNN-based few-shot selection. dspytools compile mipro <module> <trainset> for Bayesian instruction optimization. dspytools compile gepa <module> <trainset> for evolutionary prompt reflection with Pareto sampling. dspytools compile grpo <module> <trainset> for Group Relative Policy Optimization. And 13 more — from simple labeled few-shot to full teacher-student distillation. Each optimizer is registered in a factory that handles construction, configuration, and MLflow logging automatically. The user never writes optimizer setup code — they declare which optimizer, which module, which training set, and the CLI handles the rest.

La propuesta de valor central es que DSPyTools expone cada optimizador importante de DSPy a través de una única interfaz CLI consistente. dspytools compile knn <module> <trainset> para selección few-shot basada en KNN. dspytools compile mipro <module> <trainset> para optimización Bayesiana de instrucciones. dspytools compile gepa <module> <trainset> para reflexión evolutiva de prompts con muestreo Pareto. dspytools compile grpo <module> <trainset> para Group Relative Policy Optimization. Y 13 más — desde labeled few-shot simple hasta destilación completa profesor-estudiante. Cada optimizador se registra en una factoría que maneja construcción, configuración y logging de MLflow automáticamente. El usuario nunca escribe código de configuración del optimizador — declara qué optimizador, qué módulo, qué conjunto de entrenamiento, y el CLI maneja el resto.

The Generative Feedback Loop Pipeline

El Pipeline de Generative Feedback Loop

The GFL pipeline is DSPyTools’ most distinctive feature. Instead of picking one optimizer and hoping, it runs four optimizers in parallel — BootstrapFewShot, MIPROv2, GEPA, and Sequential BetterTogether — tracks their delta improvements in an LSE tracker, gates the winner through a holdout validation (minimum 2% improvement, p < 0.05), and auto-deploys the winner via hot-swap. The pipeline then feeds the winning program into Trace2Skill — rollout traces are analyzed by compilable DSPy modules (ErrorAnalystModule, SuccessAnalystModule, MergeOperatorModule) to consolidate lessons into the skill graph for future optimization cycles. This turns a single compile into a self-reinforcing improvement loop.

El pipeline GFL es la característica más distintiva de DSPyTools. En lugar de elegir un optimizador y esperar, ejecuta cuatro optimizadores en paralelo — BootstrapFewShot, MIPROv2, GEPA y Sequential BetterTogether — rastrea sus mejoras delta en un tracker LSE, aprueba el ganador mediante validación holdout (mejora mínima del 2%, p < 0.05) y auto-despliega el ganador vía hot-swap. El pipeline luego alimenta el programa ganador en Trace2Skill — los traces de rollout son analizados por módulos DSPy compilables (ErrorAnalystModule, SuccessAnalystModule, MergeOperatorModule) para consolidar lecciones en el grafo de habilidades para futuros ciclos de optimización. Esto convierte una sola compilación en un bucle de mejora auto-reforzante.

SPRT Post-Compile Validation

Validación SPRT Post-Compilación

A critical production concern with DSPy optimizers is overfitting — the optimizer improves on the training set but the compiled program regresses on real data. DSPyTools addresses this with Sequential Probability Ratio Testing. After the GFL pipeline selects the best optimizer, it runs SPRT (α=0.05, β=0.20) on a reserved holdout set that the optimizer never saw. SPRT enables early termination on clear wins — typically around 12 examples — while maintaining statistical rigor. If SPRT rejects the candidate, the pipeline falls back to the current baseline. A regressor is never deployed.

Una preocupación crítica de producción con los optimizadores de DSPy es el overfitting — el optimizador mejora en el conjunto de entrenamiento pero el programa compilado regresa en datos reales. DSPyTools aborda esto con Sequential Probability Ratio Testing. Después de que el pipeline GFL selecciona el mejor optimizador, ejecuta SPRT (α=0.05, β=0.20) en un conjunto holdout reservado que el optimizador nunca vio. SPRT permite terminación temprana en victorias claras — típicamente alrededor de 12 ejemplos — manteniendo rigor estadístico. Si SPRT rechaza el candidato, el pipeline cae al baseline actual. Un regresor nunca se despliega.

Hot-Swap Inference: Zero-Downtime Deployment

Inferencia Hot-Swap: Despliegue Sin Interrupciones

Compiled programs need to serve inference, and swapping a new version without dropping in-flight requests is a production requirement. DSPyTools’ HotSwapManager handles this with thread-safe refcounting: concurrent infer() calls are protected by a threading lock, and swap(wait_for_drain=True) blocks until all in-flight requests complete before atomically swapping the active program. Warm swap mode (POST /swap/{id}?warm=true) loads the new program, verifies it via a signature-aware test inference, and only then commits the swap. Compiled programs are cached in an LRU cache (max 16 loaded) backed by a JSON registry for persistence. A FastAPI server exposes POST /infer, POST /swap/{run_id}, and GET /programs endpoints — enough to run a production inference service without any additional infrastructure.

Los programas compilados necesitan servir inferencia, y cambiar a una nueva versión sin perder solicitudes en vuelo es un requisito de producción. El HotSwapManager de DSPyTools maneja esto con conteo de referencias thread-safe: las llamadas concurrentes a infer() están protegidas por un lock de threading, y swap(wait_for_drain=True) bloquea hasta que todas las solicitudes en vuelo se completen antes de cambiar atómicamente el programa activo. El modo warm swap (POST /swap/{id}?warm=true) carga el nuevo programa, lo verifica mediante una inferencia de prueba consciente del signature, y solo entonces confirma el cambio. Los programas compilados se almacenan en caché LRU (máximo 16 cargados) respaldados por un registro JSON para persistencia. Un servidor FastAPI expone endpoints POST /infer, POST /swap/{run_id} y GET /programs — suficiente para ejecutar un servicio de inferencia de producción sin infraestructura adicional.

65-Tool MCP Server for Agent Interoperability

Servidor MCP con 65 Herramientas para Interoperabilidad de Agentes

DSPyTools exposes its entire feature set as 65 MCP tools — programs, registry, compile, skills, drift, self, MLflow, DSPy, evaluate, GFL, validation, sandbox, Trace2Skill, paper optimizers, diagnostics, cache, agents, generation, LoRA, graph queries, and memory operations. Each tool carries annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and descriptive schemas so AI assistants can reason about side effects before calling. Compatible with OpenCode, Claude Desktop, Codex, and any MCP client. Configuration is a single JSON block in the client config pointing at uv run dspytools mcp serve --transport stdio. An AI agent can compile a program, check its MLflow score, swap it into production, and monitor drift — all as native tool calls without shell scripting.

DSPyTools expone todo su conjunto de funcionalidades como 65 herramientas MCP — programas, registro, compilación, habilidades, drift, self, MLflow, DSPy, evaluación, GFL, validación, sandbox, Trace2Skill, optimizadores de papers, diagnósticos, caché, agentes, generación, LoRA, consultas de grafo y operaciones de memoria. Cada herramienta lleva anotaciones (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) y esquemas descriptivos para que los asistentes de IA puedan razonar sobre efectos secundarios antes de llamar. Compatible con OpenCode, Claude Desktop, Codex y cualquier cliente MCP. La configuración es un solo bloque JSON en la configuración del cliente apuntando a uv run dspytools mcp serve --transport stdio. Un agente de IA puede compilar un programa, verificar su puntuación en MLflow, cambiarlo a producción y monitorear el drift — todo como llamadas nativas de herramientas sin scripting de shell.

Self-Evolving Engine

Motor Auto-Evolutivo

The self-evolving engine is where DSPyTools transcends being a compile-and-deploy tool and becomes a continuous optimization system. A morphology tracker monitors which program structures work best for which task types. A UCB explorer balances exploitation (use the best-known optimizer) against exploration (try alternatives) using Upper Confidence Bound bandits. Knowledge transfer shares optimization insights across tasks. A skill graph in FalkorDB tracks transitive improvement dependencies — when skill A improves, the engine knows which downstream skills B and C should be re-optimized. The Gödel Agent (arXiv 2410.04444) validates every candidate program against a holdout set before deployment (p < 0.05). The Meta Agent Search (arXiv 2408.08435) archives discovered programs as searchable code, building a library of proven agent architectures over time.

El motor auto-evolutivo es donde DSPyTools trasciende ser una herramienta de compilar-y-desplegar y se convierte en un sistema de optimización continua. Un morphology tracker monitorea qué estructuras de programa funcionan mejor para qué tipos de tareas. Un explorador UCB balancea explotación (usar el mejor optimizador conocido) contra exploración (probar alternativas) usando bandits Upper Confidence Bound. La transferencia de conocimiento comparte insights de optimización entre tareas. Un grafo de habilidades en FalkorDB rastrea dependencias transitivas de mejora — cuando la habilidad A mejora, el motor sabe qué habilidades descendientes B y C deberían re-optimizarse. El Gödel Agent (arXiv 2410.04444) valida cada programa candidato contra un conjunto holdout antes del despliegue (p < 0.05). La Meta Agent Search (arXiv 2408.08435) archiva los programas descubiertos como código buscable, construyendo una biblioteca de arquitecturas de agentes probadas con el tiempo.

11 arXiv Paper Implementations

11 Implementaciones de Papers de arXiv

DSPyTools tracks and reproduces state-of-the-art optimization patterns from recent literature — not as toy demos, but as compilable DSPy modules integrated into the GFL pipeline. GEPA (2507.19457) provides reflective prompt evolution with Pareto frontier sampling. MIPROv2 (2406.11695) provides Bayesian optimization of instructions and demonstrations. TextGrad (2406.07496) implements textual backpropagation through LLM outputs. SPIN (NeurIPS 2024) adds self-play discrimination bootstrapping. R-Zero (2508.05004) adds zero-data co-evolution of prompt candidates via a challenger-solver framework. MetaSPO (2505.09666) adds bilevel meta-learning of system prompts. Purified OPSD (2607.02234) adds PMI-refined on-policy self-distillation. LSE (2603.18620) adds tree-guided evolution with UCB. Trace2Skill (2603.25158) mines rollout traces into consolidated skills. Each paper’s core contribution is a compilable module: dspytools compile gepa ErrorAnalystModule trainset.json optimizes the Trace2Skill error analysis module with GEPA.

DSPyTools rastrea y reproduce patrones de optimización de vanguardia de la literatura reciente — no como demos de juguete, sino como módulos DSPy compilables integrados en el pipeline GFL. GEPA (2507.19457) proporciona evolución reflexiva de prompts con muestreo de frontera Pareto. MIPROv2 (2406.11695) proporciona optimización Bayesiana de instrucciones y demostraciones. TextGrad (2406.07496) implementa backpropagation textual a través de salidas de LLM. SPIN (NeurIPS 2024) añade bootstrapping de discriminación por auto-juego. R-Zero (2508.05004) añade co-evolución sin datos de candidatos de prompts vía un framework challenger-solver. MetaSPO (2505.09666) añade meta-aprendizaje bilevel de prompts del sistema. Purified OPSD (2607.02234) añade auto-destilación on-policy refinada por PMI. LSE (2603.18620) añade evolución guiada por árbol con UCB. Trace2Skill (2603.25158) extrae traces de rollout en habilidades consolidadas. La contribución central de cada paper es un módulo compilable: dspytools compile gepa ErrorAnalystModule trainset.json optimiza el módulo de análisis de errores de Trace2Skill con GEPA.

FalkorDB Graph Database and Semantic Cache

Base de Datos de Grafos FalkorDB y Caché Semántica

Under the hood, DSPyTools uses a Redis Stack container running FalkorDB for O(1) graph traversal of skill dependencies and program lineage — sub-140ms p99 latency, 335x faster than Neo4j, with less than 100MB memory footprint. The skill dependency graph tracks which skills depend on which, enabling cascade re-optimization when an upstream skill improves. Program lineage tracking records full ancestry chains from compilation, so you can trace any deployed program back through its optimization history via Cypher queries. A semantic cache (RedisVL) stores LLM responses by cosine similarity, reducing API costs by approximately 70% — semantically similar prompts hit the cache instead of calling the model. A FalkorDB-native persistent memory layer provides automatic entity extraction, deduplication, semantic search, and graph-based relationships — integrated into the SelfEvolveEngine so on_compile() stores lessons and suggest_optimizer() searches memories.

Internamente, DSPyTools usa un contenedor Redis Stack ejecutando FalkorDB para traversal de grafos O(1) de dependencias de habilidades y linaje de programas — latencia p99 inferior a 140ms, 335x más rápido que Neo4j, con menos de 100MB de huella de memoria. El grafo de dependencias de habilidades rastrea qué habilidades dependen de cuáles, habilitando re-optimización en cascada cuando una habilidad upstream mejora. El seguimiento de linaje de programas registra cadenas completas de ancestros desde la compilación, por lo que puedes rastrear cualquier programa desplegado a través de su historial de optimización vía consultas Cypher. Una caché semántica (RedisVL) almacena respuestas de LLM por similitud coseno, reduciendo costos de API aproximadamente 70% — prompts semánticamente similares impactan la caché en lugar de llamar al modelo. Una capa de memoria persistente nativa de FalkorDB proporciona extracción automática de entidades, deduplicación, búsqueda semántica y relaciones basadas en grafos — integrada en el SelfEvolveEngine para que on_compile() almacene lecciones y suggest_optimizer() busque memorias.

LoRA Distillation and the Distill Pipeline

Destilación LoRA y el Pipeline de Destilación

Compiled DSPy programs encode optimized prompts and demonstrations. DSPyTools can distill these into LoRA adapters — turning prompt-level optimizations into weight-level optimizations that run faster and cost less at inference time. The distillation pipeline generates training data from compiled programs, stages files for Colab training (dspytools distill prepare-colab --adapter super --rank 64), and the LoRA lifecycle is fully managed: load, unload, list, chat, test, health, discover, extract, evaluate, and train. The auto_evolve_cycle() integrates distillation into the self-evolving loop — when a compiled program significantly outperforms its predecessor, the engine can automatically distill it into a LoRA adapter.

Los programas DSPy compilados codifican prompts y demostraciones optimizados. DSPyTools puede destilar estos en adaptadores LoRA — convirtiendo optimizaciones a nivel de prompt en optimizaciones a nivel de pesos que se ejecutan más rápido y cuestan menos en tiempo de inferencia. El pipeline de destilación genera datos de entrenamiento a partir de programas compilados, prepara archivos para entrenamiento en Colab (dspytools distill prepare-colab --adapter super --rank 64), y el ciclo de vida de LoRA se gestiona completamente: cargar, descargar, listar, chatear, probar, salud, descubrir, extraer, evaluar y entrenar. El auto_evolve_cycle() integra la destilación en el bucle auto-evolutivo — cuando un programa compilado supera significativamente a su predecesor, el motor puede destilarlo automáticamente en un adaptador LoRA.

Self-Optimizing Help and llms.txt Generation

Ayuda Auto-Optimizante y Generación de llms.txt

Two features showcase DSPyTools’ commitment to applying DSPy to itself. The --help system is itself a compiled DSPy program — the first dspytools self optimize call introspects the CLI, builds a training set from command metadata, compiles a help module with GEPA or LabeledFewShot using the local llama-cpp model, and caches the result. Subsequent --help calls use the compiled program to generate context-aware help text. The generate llms-txt command uses a 5-stage RepositoryAnalyzer pipeline to analyze repo structure, read README, explore packages, and generate documentation — with batch evaluation against ground truth examples and optional MCP git exploration via a ReActV2 agent.

Dos características muestran el compromiso de DSPyTools de aplicar DSPy a sí mismo. El sistema --help es en sí mismo un programa DSPy compilado — la primera llamada dspytools self optimize introspecciona el CLI, construye un conjunto de entrenamiento a partir de metadatos de comandos, compila un módulo de ayuda con GEPA o LabeledFewShot usando el modelo local llama-cpp, y almacena en caché el resultado. Las llamadas subsiguientes a --help usan el programa compilado para generar texto de ayuda consciente del contexto. El comando generate llms-txt usa un pipeline RepositoryAnalyzer de 5 etapas para analizar la estructura del repositorio, leer el README, explorar paquetes y generar documentación — con evaluación por lotes contra ejemplos ground truth y exploración opcional de git vía MCP usando un agente ReActV2.

SSOT Architecture: No Disconnected Islands

Arquitectura SSOT: Sin Islas Desconectadas

Every subsystem in DSPyTools is wired together via a Single Source of Truth pattern with fail-fast imports. The FalkorDB skill graph feeds the SelfEvolveEngine, the registry, and the MCP server. The semantic cache feeds the HotSwapManager’s infer() method. The memory manager feeds on_compile() and suggest_optimizer(). The drift monitor feeds the HotSwapManager and triggers re-optimization. There are no try/except blocks around imports or DSPy module constructors — only runtime operations (Redis down, network timeout) use graceful degradation. This means every subsystem is always available or the system fails loudly — no silent feature degradation, no zombie components that look alive but do nothing.

Cada subsistema en DSPyTools está conectado vía un patrón Single Source of Truth con imports fail-fast. El grafo de habilidades de FalkorDB alimenta el SelfEvolveEngine, el registro y el servidor MCP. La caché semántica alimenta el método infer() del HotSwapManager. El gestor de memoria alimenta on_compile() y suggest_optimizer(). El monitor de drift alimenta el HotSwapManager y dispara la re-optimización. No hay bloques try/except alrededor de imports o constructores de módulos DSPy — solo las operaciones de runtime (Redis caído, timeout de red) usan degradación elegante. Esto significa que cada subsistema siempre está disponible o el sistema falla ruidosamente — sin degradación silenciosa de funcionalidades, sin componentes zombi que parezcan vivos pero no hagan nada.

References

Referencias