Analysis Tools

The analysis tools provide statistical analysis and comparison capabilities for negotiation results.

Main Platform Interface

Negotiation Platform - Main Entry Point

This module serves as the primary entry point for the Negotiation Platform, providing command-line interface, demonstration capabilities, and example usage patterns for researchers and developers.

Key Features:

  • Command-line interface for quick testing and experimentation

  • Single negotiation runs for focused analysis

  • Comprehensive model comparison across multiple games

  • Interactive mode for guided exploration

  • Configurable logging and output options

  • Integration examples for all platform components

Usage Modes:

  1. Quick Mode: Single negotiation with default settings

  2. Comparison Mode: Full model comparison across games

  3. Interactive Mode: Guided selection of options

  4. Custom Mode: Programmatic usage with specific configurations

Example Command Lines:

python main.py –quick –models model_a model_b –game company_car python main.py –comparison –models model_a model_b model_c python main.py –log-level DEBUG

Architecture:

The main module demonstrates the complete platform initialization workflow: ConfigManager -> LLMManager -> GameEngine -> MetricsCalculator -> SessionManager -> Results. This pattern should be followed for custom integrations and extensions.

negotiation_platform.main.setup_logging(level='INFO')[source]

Configure comprehensive logging for the negotiation platform.

Sets up dual-output logging (file and console) with detailed formatting for debugging, monitoring, and analysis of negotiation sessions.

Parameters:

level (str, optional) – Logging level (DEBUG, INFO, WARNING, ERROR). Defaults to “INFO”. DEBUG provides detailed execution traces, INFO shows key events and progress, WARNING highlights potential issues, ERROR logs only critical failures.

Logging Configuration:

  • File Output: negotiation_platform.log (persistent record)

  • Console Output: Real-time feedback during execution

  • Format: Timestamp - Logger Name - Level - Message

  • Rotation: Not configured (manual cleanup required)

Log Categories:

  • SessionManager: Negotiation progress and outcomes

  • LLMManager: Model loading, switching, and memory management

  • GameEngine: Game creation and state transitions

  • MetricsCalculator: Performance analysis and calculations

  • Individual Games: Game-specific events and decisions

Example

>>> setup_logging("DEBUG")
>>> logger = logging.getLogger(__name__)
>>> logger.info("Platform initialized successfully")
2023-12-01 10:30:45,123 - __main__ - INFO - Platform initialized successfully

Note

Should be called early in application startup before other components are initialized to ensure all log messages are captured.

negotiation_platform.main.run_single_negotiation(config_manager, models, game_type='company_car')[source]

Execute a single negotiation session between two AI models for analysis.

Demonstrates the complete negotiation workflow from platform initialization through result analysis. Useful for focused testing, debugging, and detailed analysis of specific model interactions.

Parameters:

  • config_manager (ConfigManager) – Initialized configuration manager containing model definitions, game settings, and platform parameters.

  • models (List[str]) – List of model identifiers to use as negotiation participants. Only the first two models are used for bilateral games.

  • game_type (str, optional) –

    Type of negotiation game to run. Must be registered in the GameEngine. Options include:

    • ”company_car”: Bilateral vehicle price negotiation

    • ”resource_allocation”: Multi-resource team distribution

    • ”integrative_negotiations”: Multi-issue collaborative negotiation

    Defaults to “company_car”.

Returns:

Complete negotiation results containing:

  • agreement_reached (bool): Whether players reached an agreement

  • agreement_round (int): Round when agreement was reached

  • final_utilities (Dict[str, float]): Final utility values per player

  • metrics (Dict[str, Dict[str, float]]): Computed performance metrics

  • session_metadata (Dict[str, Any]): Session information and timestamps

  • actions_history (List[Dict]): Complete action log for analysis

Return type:

Dict[str, Any]

Workflow:

  1. Initialize all platform components with configurations

  2. Set up lazy-loading LLM manager for memory efficiency

  3. Create game instance with specified type and configuration

  4. Execute negotiation session with turn-based interaction

  5. Calculate comprehensive performance metrics

  6. Display results and maintain model state for reuse

Example

>>> config = ConfigManager()
>>> models = ["model_a", "model_b"]
>>> result = run_single_negotiation(config, models, "company_car")
>>> print(result['agreement_reached'])
True
>>> print(result['metrics']['utility_surplus'])
{'model_a': 2500.0, 'model_b': 1800.0}
Performance Notes:

  • Uses lazy loading to minimize GPU memory usage

  • Models remain loaded after completion for potential reuse

  • Detailed logging provides debugging and analysis capabilities

  • All metrics are calculated automatically for comprehensive analysis

Error Handling:

Exceptions during negotiation are logged and may result in incomplete results. Check the ‘success’ field in returned results and logs for error details.

negotiation_platform.main.run_model_comparison(config_manager, models, games=None)[source]

Execute comprehensive multi-model comparison across negotiation games.

Performs systematic evaluation of multiple AI models across different negotiation scenarios to assess relative performance, strategy effectiveness, and behavioral consistency. This function implements a rigorous comparison methodology with multiple runs per model pair for statistical reliability.

Parameters:

  • config_manager (ConfigManager) – Initialized configuration manager containing model definitions, game configurations, and platform settings.

  • models (List[str]) – List of model identifiers to compare. All pairwise combinations will be tested across specified games.

  • games (List[str], optional) – List of game types to include in comparison. Defaults to [“company_car”, “resource_allocation”, “integrative_negotiations”] if not specified. Each game type must be registered in GameEngine.

Returns:

Hierarchical results structure:

  • game_type -> model_pair -> list of session results

  • Each session result contains metrics, outcomes, and metadata

  • Suitable for statistical analysis and visualization

Return type:

Dict[str, Dict[str, List[Dict]]]

Comparison Methodology:

  1. For each game type in the evaluation set

  2. Test all unique model pairs (avoiding duplicates)

  3. Run multiple sessions per pair for statistical significance

  4. Calculate comprehensive metrics for each session

  5. Aggregate results with summary statistics

  6. Save detailed results to timestamped JSON file

Output Artifacts:

  • Console summary with agreement rates and average metrics

  • Detailed JSON results file in configured results directory

  • Individual session logs for debugging and analysis

Example

>>> config = ConfigManager()
>>> models = ["model_a", "model_b", "model_c"]
>>> results = run_model_comparison(config, models)
Running Model Comparison
Models: ['model_a', 'model_b', 'model_c']
>>> print(results.keys())
dict_keys(['company_car', 'resource_allocation', 'integrative_negotiations'])
Performance Considerations:

  • Models are loaded and unloaded for each pair to manage memory

  • Multiple runs per pair provide statistical reliability

  • Results are saved incrementally to prevent data loss

  • Detailed logging enables progress monitoring

Note

This function is designed for research and evaluation purposes. Large model sets or many games may require significant computation time and GPU resources. Consider running in stages for very large evaluations.

negotiation_platform.main.main()[source]

Main application entry point with command-line interface.

Provides comprehensive command-line interface for the Negotiation Platform with support for various execution modes including quick testing, systematic model comparison, and interactive exploration. Handles argument parsing, logging configuration, and orchestrates the appropriate execution workflow.

Command-Line Options:

–quick: Execute single negotiation session for rapid testing –comparison: Run comprehensive multi-model comparison study –models: Specify list of models to use (default: model_a, model_b, model_c) –game: Choose game type for single runs (default: company_car) –log-level: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)

Execution Modes:

  1. Quick Mode (–quick): Single negotiation with specified models and game

  2. Comparison Mode (–comparison): Systematic evaluation across model pairs

  3. Interactive Mode (default): User-guided selection of execution options

Example Usage:

# Quick single negotiation python main.py –quick –models model_a model_b –game company_car

# Comprehensive comparison python main.py –comparison –models model_a model_b model_c

# Interactive mode with debug logging python main.py –log-level DEBUG

Platform Initialization:

  1. Configure logging system with specified verbosity level

  2. Initialize ConfigManager with default or custom configuration

  3. Display available models and confirm selection

  4. Execute requested workflow with comprehensive error handling

Error Handling:

  • Graceful handling of KeyboardInterrupt (Ctrl+C)

  • Comprehensive exception logging with stack traces

  • Proper cleanup and resource management on exit

  • User-friendly error messages for common issues

Output:

  • Progress indicators during execution

  • Summary results and key findings

  • File locations for detailed results

  • Success confirmation upon completion

Note

This function serves as the primary demonstration of platform capabilities and provides templates for custom integration patterns. For programmatic usage, consider calling individual functions directly rather than using the command-line interface.

Game Statistics Comparison

Batch Analysis Tools

Tools for analyzing multiple negotiation runs and comparing results across different configurations.