Investigación Multi-Agente con JamJet

JamJet proporciona a los investigadores una infraestructura completa de experimentación lista para usar: ejecución durable para reproducibilidad, seis estrategias de razonamiento para estudios de ablación, una cuadrícula de experimentos para barridos de parámetros, evaluación integrada con calificadores personalizados, y exportación para publicación (LaTeX, CSV, JSON) con pruebas estadísticas.

Esta guía recorre un flujo de trabajo de investigación completo — desde el esqueleto del proyecto hasta resultados listos para publicar.

Consejo: ¿Ya conoces JamJet? Ve directamente a Ejecutar experimentos o Exportar para publicación.

Configuración

1. Instalar JamJet

   pip install jamjet

2. Crear el esqueleto de un proyecto de investigación

   jamjet init my-study --template research
   cd my-study

3. Revisar la estructura generada

   my-study/
   ├── agents/
   │   └── researcher.py       # Definición del agente con herramientas
   ├── baselines/
   │   └── baseline.py         # Plantillas de comparación con líneas base
   ├── experiments/
   │   ├── config.yaml          # Configuración de modelo, semilla y estrategia
   │   └── runner.py            # Bucle de experimentos
   ├── evals/
   │   ├── dataset.jsonl        # Conjunto de datos de evaluación
   │   └── scorers.py           # Definiciones de calificadores personalizados
   ├── results/                 # Directorio de salida (.gitkeep)
   ├── workflow.yaml            # Definición del flujo de trabajo
   └── README.md

Define tus agentes

Los agentes son funciones Python decoradas con @task. Cada agente puede usar una estrategia de razonamiento diferente.

from jamjet import task, tool

@tool
async def web_search(query: str) -> str:
    """Search the web for current information."""
    ...

@task(model="claude-sonnet-4-6", tools=[web_search])
async def researcher(question: str) -> str:
    """Research a question using web search."""

Seis estrategias integradas

JamJet compila nombres de estrategias de alto nivel en sub-DAGs IR explícitos. Intercambia con un solo parámetro — mismo agente, razonamiento diferente:

# workflow.yaml — cambiar estrategia para comparar

agents:
  researcher:
    model: claude-sonnet-4-6
    strategy: debate        # cambiar a: react, reflection, consensus...
    tools: [web_search]
    max_iterations: 6

Ejecutar experimentos

ExperimentGrid ejecuta cada combinación de condiciones y semillas como ejecuciones de flujo de trabajo durables. Si una ejecución falla, se reanuda desde el checkpoint — sin volver a ejecutar pasos previos.

from jamjet.eval import ExperimentGrid

grid = ExperimentGrid(
    conditions={
        "strategy": ["react", "plan_and_execute", "critic",
                      "reflection", "consensus", "debate"],
        "model": ["claude-sonnet-4-6", "gpt-4o"],
    },
    seeds=[42, 123, 456],
    dataset="evals/dataset.jsonl",
    scorers=["llm_judge", "factuality"],
)

results = await grid.run()
results.summary()  # Tabla detallada en terminal

Esto ejecuta 6 estrategias x 2 modelos x 3 semillas = 36 ejecuciones durables, cada una con trazas de eventos completas y checkpoints.

Nota: Cada ejecución utiliza event-sourcing. Si el experimento falla en la ejecución 22 de 36, se reanuda desde la ejecución 22 — sin desperdiciar tokens reejecutando condiciones completadas.

Evaluar resultados

Scorers integrados

JamJet incluye cuatro tipos de scorers de fábrica:

• llm_judge — Un LLM evalúa la salida según una rúbrica (escala 0-5)
• assertion — Verificación booleana contra estructura o contenido de salida
• latency — Puntúa según tiempo de ejecución vs umbral
• cost — Puntúa según costo de tokens vs presupuesto

Scorers personalizados

Registra scorers específicos de dominio con el decorador @scorer:

from jamjet import scorer
from jamjet.eval import ScorerResult

@scorer(name="factuality", description="Verificar precisión factual")
async def factuality_scorer(input: dict, output: dict, context: dict) -> ScorerResult:
    # Tu lógica de puntuación personalizada aquí
    return ScorerResult(
        score=0.85,
        passed=True,
        reason="Todas las afirmaciones verificadas contra la fuente",
    )

Los scorers personalizados están disponibles automáticamente en ExperimentGrid y EvalNode por nombre.

Nodos de evaluación en flujos de trabajo

La evaluación también puede ejecutarse en línea como un nodo de flujo de trabajo — durante la ejecución, no después:

nodes:
  check-quality:
    type: eval
    scorers:
      - type: llm_judge
        rubric: "Is the response accurate and well-sourced?"
        min_score: 4
    on_fail: retry_with_feedback
    max_retries: 2

Cuando la puntuación es demasiado baja, retry_with_feedback vuelve a ejecutar el nodo anterior con el razonamiento del evaluador como contexto adicional.

Exportar para publicación

Tablas LaTeX

results.to_latex("table1.tex", caption="Strategy comparison across models")

Genera una tabla con formato booktabs con media +/- desviación estándar por condición — lista para incluir con \input{} en tu artículo.

CSV para R / pandas

results.to_csv("results.csv")

JSON para análisis adicional

results.to_json("results.json")

Comparación estadística

Compara dos condiciones cualesquiera con pruebas de significancia integradas:

comparison = results.compare("debate", "react", test="auto", alpha=0.05)

Devuelve un ComparisonResult con:

Pruebas disponibles:

• welch — Prueba t de Welch (predeterminada, muestras independientes)
• wilcoxon — Rango con signo de Wilcoxon (muestras pareadas)
• mann_whitney — U de Mann-Whitney (no paramétrica, independiente)
• auto — Selecciona según el tamaño de muestra y el emparejamiento

Exportación por CLI

jamjet eval export results.json --format latex --caption "Table 1"
jamjet eval compare results.json --conditions "debate,react" --test auto

Reproducir y bifurcar

Reproducción exacta

Reproduce cualquier ejecución desde su checkpoint — mismos inputs, mismo camino de ejecución:

jamjet replay exec_abc123

El runtime obtiene los eventos de ejecución originales, extrae el workflow y el input, y crea una nueva ejecución con los mismos parámetros. Útil para verificación y debugging.

Fork para estudios de ablación

Haz fork desde una ejecución completada con inputs modificados — cambia una variable mientras mantienes todo lo demás idéntico:

jamjet fork exec_abc123 --override-input '{"model": "gpt-4o"}'

El input original se preserva y el override se fusiona. Este es el camino más rápido para estudios de ablación — sin reconfigurar, sin volver a ejecutar la cuadrícula completa.

Proveniencia

Cada completado de nodo en JamJet lleva ProvenanceMetadata:

La proveniencia se adjunta automáticamente — sin configuración extra necesaria. Fluye hacia event traces, logs de auditoría y resultados exportados.

Tip: Los metadatos de proveniencia son especialmente valiosos para experimentos multi-modelo donde necesitas atribuir qué modelo produjo qué resultado intermedio.

Inspeccionar workflows

Usa jamjet inspect para examinar workflows compilados, incluyendo detalles específicos de estrategia:

jamjet inspect workflow.yaml

Para agentes con strategy-aware, esto muestra:

• Nombre y tipo de estrategia
• Recuento de iteraciones y pasos del plan
• Veredictos del crítico (para estrategias critic/debate)
• Costo por iteración

Ejemplo: tarde completa de investigación

from jamjet.eval import ExperimentGrid

# 1. Define la cuadrícula

grid = ExperimentGrid(
    conditions={
        "strategy": ["react", "plan_and_execute", "critic",
                      "reflection", "consensus", "debate"],
    },
    seeds=[42, 123, 456],
    dataset="evals/dataset.jsonl",
    scorers=["llm_judge"],
)

# 2. Ejecuta (duradero — se reanuda tras fallos)

results = await grid.run()

# 3. Exporta tabla LaTeX

results.to_latex("table1.tex", caption="Comparación de estrategias")

# 4. Prueba estadística

comp = results.compare("debate", "react")
print(f"p = {comp.p_value:.4f}, d de Cohen = {comp.effect_size:.2f}")

# 5. Reproduce una ejecución específica

# $ jamjet replay exec_debate_seed42

# 6. Bifurca para ablación

# $ jamjet fork exec_debate_seed42 --override-input '{"model":"gpt-4o"}'

Próximos pasos

• Explora ejemplos de investigación — patrones de deliberación DCI y enrutamiento LDP
• Consulta la página /research para un resumen de capacidades
• Lee la documentación del harness de evaluación para configuración avanzada de evaluaciones
• Prueba jamjet init my-study --template research para comenzar