PIDGIN-YAML(5)

NAME
pidgin-yaml - YAML specification format for Pidgin experiments

SYNOPSIS
experiment.yaml

DESCRIPTION
Pidgin experiments can be configured using YAML files that specify all parameters for running conversations. This allows for reproducible experiments and complex configurations that would be unwieldy on the command line.

FORMAT
The YAML file uses the following structure:

BASIC STRUCTURE
    # Experiment metadata
    name: my-experiment          # Optional: auto-generated if not provided
    description: |               # Optional: experiment description
      Multi-line description
      of the experiment
    # Agent configuration
    agents:
      agent_a: claude           # Model for agent A
      agent_b: gpt-4           # Model for agent B
    # Core parameters
    initial_prompt: "Let's discuss philosophy"
    max_turns: 50
    num_conversations: 10       # Number of repetitions
    # Optional parameters
    temperature: 0.7            # Temperature for both agents
    temperatures:               # Or set per-agent
      agent_a: 0.3
      agent_b: 0.9
    # System prompt awareness
    awareness: enhanced         # For both agents
    awareness_levels:           # Or set per-agent
      agent_a: full
      agent_b: basic
    # Convergence settings
    convergence:
      threshold: 0.85
      action: stop              # stop, continue, or notify

    # Execution settings
    max_parallel: 10            # Parallel conversation limit
    output_mode: default        # Display mode

FIELDS

  Required Fields

agents
    Object containing agent_a and agent_b model specifications.

max_turns
    Maximum number of turns (exchanges) per conversation.

num_conversations
    Number of conversations to run in the experiment.

  Optional Fields

name
    Experiment name. Auto-generated if not provided.

description
    Free-form description of the experiment's purpose.

initial_prompt
    Starting prompt for conversations. Can use multi-line YAML syntax. Default: "I'm excited to have this conversation with you."

temperature / temperatures
    Model temperature settings (0.0-2.0). Can be set globally or per-agent.

awareness / awareness_levels
    System prompt awareness (none, basic, enhanced, full).

convergence
    Object with threshold (0.0-1.0) and action settings.

dimensional_prompt
    Dimensional prompt specification (perspective:topic:style).

custom_instructions
    Per-agent custom system prompt additions.

max_parallel
    Maximum concurrent conversations (default: 20).

output_mode
    Display mode: default, minimal, none, markdown, json.

meditation_mode
    Enable longer pauses between messages.

tags
    List of tags for experiment categorization.

EXAMPLES

  Minimal Configuration
    agents:
      agent_a: haiku
      agent_b: gpt-4o-mini
    max_turns: 20
    num_conversations: 5

  Research Configuration
    name: compression-dynamics
    description: |
      Studying how language models compress communication
      over extended interactions

    agents:
      agent_a: claude
      agent_b: gpt-4
    initial_prompt: |
      You're about to engage in a freeform conversation.
      Be yourself and explore ideas naturally.
    max_turns: 100
    num_conversations: 50
    temperatures:
      agent_a: 0.3
      agent_b: 0.3
    convergence:
      threshold: 0.95
      action: stop
    awareness_levels:
      agent_a: full
      agent_b: full
    max_parallel: 10
    output_mode: minimal
    tags:
      - compression
      - long-form
      - matched-temperature

  Dimensional Prompt Example
    agents:
      agent_a: opus
      agent_b: gemini
    dimensional_prompt:
      perspective: teachers
      topic: quantum_physics
      style: socratic
    max_turns: 30
    num_conversations: 10

  Custom Instructions
    agents:
      agent_a: gpt-4
      agent_b: claude
    custom_instructions:
      agent_a: |
        You have a background in poetry and tend to use
        metaphorical language in your responses.
      agent_b: |
        You are highly analytical and prefer precise,
        technical language.
    max_turns: 40
    num_conversations: 20

VALIDATION
YAML files are validated before execution. Common errors include:

•   Missing required fields (agents, max_turns, num_conversations)

•   Invalid model names

•   Out-of-range values (e.g., temperature > 2.0)

•   Conflicting settings (e.g., both temperature and temperatures)

NOTES
YAML files support comments (lines starting with #) for documentation. Use meaningful experiment names and descriptions for better organization.

File paths in YAML are relative to the YAML file's location, not the current working directory.

SEE ALSO
pidgin(1), pidgin-run(1), yaml(1)

AUTHOR
Nicholas Lange and contributors