Auto Arena Skill#

End-to-end automated model comparison using the OpenJudge AutoArenaPipeline:

1. Generate queries — LLM creates diverse test queries from task description
2. Collect responses — query all target endpoints concurrently
3. Generate rubrics — LLM produces evaluation criteria from task + sample queries
4. Pairwise evaluation — judge model compares every model pair (with position-bias swap)
5. Analyze & rank — compute win rates, win matrix, and rankings
6. Report & charts — Markdown report + win-rate bar chart + optional matrix heatmap

Prerequisites#

bash

# Install OpenJudge
pip install py-openjudge

# Extra dependency for auto_arena (chart generation)
pip install matplotlib

Gather from user before running#

InfoRequired?NotesTask descriptionYesWhat the models/agents should do (set in config YAML)Target endpointsYesAt least 2 OpenAI-compatible endpoints to compareJudge endpointYesStrong model for pairwise evaluation (e.g. gpt-4, qwen-max)API keysYesEnv vars: OPENAI_API_KEY, DASHSCOPE_API_KEY, etc.Number of queriesNoDefault: 20Seed queriesNoExample queries to guide generation styleSystem promptsNoPer-endpoint system promptsOutput directoryNoDefault: ./evaluation_resultsReport languageNo"zh" (default) or "en"

Quick start#

CLI#

bash

# Run evaluation
python -m cookbooks.auto_arena --config config.yaml --save

# Use pre-generated queries
python -m cookbooks.auto_arena --config config.yaml \
  --queries_file queries.json --save

# Start fresh, ignore checkpoint
python -m cookbooks.auto_arena --config config.yaml --fresh --save

# Re-run only pairwise evaluation with new judge model
# (keeps queries, responses, and rubrics)
python -m cookbooks.auto_arena --config config.yaml --rerun-judge --save

Python API#

python

import asyncio
from cookbooks.auto_arena.auto_arena_pipeline import AutoArenaPipeline

async def main():
    pipeline = AutoArenaPipeline.from_config("config.yaml")
    result = await pipeline.evaluate()

    print(f"Best model: {result.best_pipeline}")
    for rank, (model, win_rate) in enumerate(result.rankings, 1):
        print(f"{rank}. {model}: {win_rate:.1%}")

asyncio.run(main())

Minimal Python API (no config file)#

python

import asyncio
from cookbooks.auto_arena.auto_arena_pipeline import AutoArenaPipeline
from cookbooks.auto_arena.schema import OpenAIEndpoint

async def main():
    pipeline = AutoArenaPipeline(
        task_description="Customer service chatbot for e-commerce",
        target_endpoints={
            "gpt4": OpenAIEndpoint(
                base_url="https://api.openai.com/v1",
                api_key="sk-...",
                model="gpt-4",
            ),
            "qwen": OpenAIEndpoint(
                base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
                api_key="sk-...",
                model="qwen-max",
            ),
        },
        judge_endpoint=OpenAIEndpoint(
            base_url="https://api.openai.com/v1",
            api_key="sk-...",
            model="gpt-4",
        ),
        num_queries=20,
    )
    result = await pipeline.evaluate()
    print(f"Best: {result.best_pipeline}")

asyncio.run(main())

CLI options#

FlagDefaultDescription--config—Path to YAML configuration file (required)--output_dirconfig valueOverride output directory--queries_file—Path to pre-generated queries JSON (skip generation)--save``FalseSave results to file--fresh``FalseStart fresh, ignore checkpoint--rerun-judge``FalseRe-run pairwise evaluation only (keep queries/responses/rubrics)

Minimal config file#

yaml

task:
  description: "Academic GPT assistant for research and writing tasks"

target_endpoints:
  model_v1:
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4"
  model_v2:
    base_url: "https://api.openai.com/v1"
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-3.5-turbo"

judge_endpoint:
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-4"

Full config reference#

task#

FieldRequiredDescriptiondescriptionYesClear description of the task models will be tested onscenarioNoUsage scenario for additional context

target_endpoints.#

FieldDefaultDescriptionbase_url—API base URL (required)api_key—API key, supports ${ENV_VAR} (required)model—Model name (required)system_prompt—System prompt for this endpointextra_params—Extra API params (e.g. temperature, max_tokens)

judge_endpoint#

Same fields as target_endpoints.<name>. Use a strong model (e.g. gpt-4, qwen-max) with low temperature (~0.1) for consistent judgments.

query_generation#

FieldDefaultDescriptionnum_queries``20Total number of queries to generateseed_queries—Example queries to guide generationcategories—Query categories with weights for stratified generationendpointjudge endpointCustom endpoint for query generationqueries_per_call``10Queries generated per API call (1–50)num_parallel_batches``3Parallel generation batchestemperature``0.9Sampling temperature (0.0–2.0)top_p``0.95Top-p sampling (0.0–1.0)max_similarity``0.85Dedup similarity threshold (0.0–1.0)enable_evolution``falseEnable Evol-Instruct complexity evolutionevolution_rounds``1Evolution rounds (0–3)complexity_levels``["constraints", "reasoning", "edge_cases"]Evolution strategies

evaluation#

FieldDefaultDescriptionmax_concurrency``10Max concurrent API requeststimeout``60Request timeout in secondsretry_times``3Retry attempts for failed requests

output#

FieldDefaultDescriptionoutput_dir``./evaluation_resultsOutput directorysave_queries``trueSave generated queriessave_responses``trueSave model responsessave_details``trueSave detailed results

report#

FieldDefaultDescriptionenabled``falseEnable Markdown report generationlanguage``"zh"Report language: "zh" or "en"``include_examples``3Examples per section (1–10)chart.enabled``trueGenerate win-rate chartchart.orientation``"horizontal"``"horizontal" or "vertical"``chart.show_values``trueShow values on barschart.highlight_best``trueHighlight best modelchart.matrix_enabled``falseGenerate win-rate matrix heatmapchart.format``"png"Chart format: "png", "svg", or "pdf"

Interpreting results#

Win rate: percentage of pairwise comparisons a model wins. Each pair is evaluated in both orders (original + swapped) to eliminate position bias.

Rankings example:

text

  1. gpt4_baseline       [################----] 80.0%
  2. qwen_candidate      [############--------] 60.0%
  3. llama_finetuned      [##########----------] 50.0%

Win matrix: win_matrix[A][B] = how often model A beats model B across all queries.

Checkpoint & resume#

The pipeline saves progress after each step. Interrupted runs resume automatically:

• --fresh — ignore checkpoint, start from scratch
• --rerun-judge — re-run only the pairwise evaluation step (useful when switching judge models); keeps queries, responses, and rubrics intact
• Adding new endpoints to config triggers incremental response collection; existing responses are preserved

Output files#

text

evaluation_results/
├── evaluation_results.json     # Rankings, win rates, win matrix
├── evaluation_report.md        # Detailed Markdown report (if enabled)
├── win_rate_chart.png          # Win-rate bar chart (if enabled)
├── win_rate_matrix.png         # Matrix heatmap (if matrix_enabled)
├── queries.json                # Generated test queries
├── responses.json              # All model responses
├── rubrics.json                # Generated evaluation rubrics
├── comparison_details.json     # Pairwise comparison details
└── checkpoint.json             # Pipeline checkpoint

API key by model#

Model prefixEnvironment variablegpt-*, o1-*, o3-*``OPENAI_API_KEY``claude-*``ANTHROPIC_API_KEY``qwen-*, dashscope/*``DASHSCOPE_API_KEY``deepseek-*``DEEPSEEK_API_KEYCustom endpointset api_key + base_url in config

Additional resources#

• Full config examples: cookbooks/auto_arena/examples/
• Documentation: Auto Arena Guide