AI MathService Lab

{
  "title": "Python CLI for Simulation Results Summary",
  "requirements": [
    {"id": "R1", "text": "Read simulation results from a CSV file", "priority": "must"},
    {"id": "R2", "text": "Compute statistical summaries (mean, standard deviation, quantiles) for selected metrics", "priority": "must"},
    {"id": "R3", "text": "Export the computed summary statistics to a JSON file", "priority": "must"},
    {"id": "R4", "text": "Provide a command-line interface to specify input CSV, output JSON, and metrics to summarize", "priority": "must"},
    {"id": "R5", "text": "Include unit tests covering CSV reading, statistics computation, and JSON export", "priority": "must"},
    {"id": "R6", "text": "Handle invalid input files or missing metrics gracefully with clear error messages", "priority": "should"},
    {"id": "R7", "text": "Allow configuration of quantile levels via CLI or config", "priority": "could"}
  ],
  "architecture": {
    "summary": "Modular CLI utility that reads CSV data, computes statistics on selected metrics, and writes a JSON summary output.",
    "components": [
      {"name": "CSVReader", "responsibility": "Load and validate CSV data from file"},
      {"name": "StatisticsCalculator", "responsibility": "Compute mean, std, and quantiles for specified metrics"},
      {"name": "JSONExporter", "responsibility": "Serialize computed statistics into JSON format and write to file"},
      {"name": "CLIHandler", "responsibility": "Parse command line arguments and coordinate workflow"},
      {"name": "ErrorHandler", "responsibility": "Manage errors and provide user-friendly messages"}
    ],
    "data_flow": [
      "CLIHandler parses input arguments",
      "CSVReader loads CSV data",
      "StatisticsCalculator computes summaries for selected metrics",
      "JSONExporter writes summary JSON output",
      "CLIHandler reports success or errors"
    ]
  },
  "files": [
    {"path": "cli.py", "purpose": "Entry point and CLI argument parsing", "main_symbols": ["main", "parse_args"]},
    {"path": "csv_reader.py", "purpose": "Load and validate CSV simulation results", "main_symbols": ["CSVReader"]},
    {"path": "statistics.py", "purpose": "Compute statistical summaries for metrics", "main_symbols": ["StatisticsCalculator"]},
    {"path": "json_exporter.py", "purpose": "Export computed statistics to JSON file", "main_symbols": ["JSONExporter"]},
    {"path": "errors.py", "purpose": "Define custom exceptions and error handling utilities", "main_symbols": ["InvalidInputError"]},
    {"path": "tests/test_csv_reader.py", "purpose": "Unit tests for CSV reading and validation", "main_symbols": ["test_csv_loading", "test_invalid_csv"]},
    {"path": "tests/test_statistics.py", "purpose": "Unit tests for statistics computations", "main_symbols": ["test_mean_std_quantiles"]},
    {"path": "tests/test_json_exporter.py", "purpose": "Unit tests for JSON export functionality", "main_symbols": ["test_json_output"]}
  ],
  "implementation_steps": [
    {"step": 1, "title": "Setup project structure and dependencies", "details": "Create project folders, initialize Python environment, add requirements (e.g. pandas, numpy)"},
    {"step": 2, "title": "Implement CSVReader", "details": "Develop CSVReader class to load CSV, validate presence of required columns, and handle errors"},
    {"step": 3, "title": "Implement StatisticsCalculator", "details": "Create functions to compute mean, std deviation, and configurable quantiles for given metrics"},
    {"step": 4, "title": "Implement JSONExporter", "details": "Serialize statistics dictionary to JSON and write to output file"},
    {"step": 5, "title": "Implement CLIHandler", "details": "Use argparse to parse input CSV path, output JSON path, and metrics list; invoke components in order"},
    {"step": 6, "title": "Add error handling and user messages", "details": "Catch and report errors such as file not found, missing metrics, or parse errors"},
    {"step": 7, "title": "Write unit tests", "details": "Cover CSV reading, statistics calculations, and JSON export with representative test cases"},
    {"step": 8, "title": "Manual testing and validation", "details": "Run CLI with sample CSV files, verify JSON output correctness and error handling"},
    {"step": 9, "title": "Documentation and usage instructions", "details": "Document CLI usage, input/output formats, and configuration options"}
  ],
  "test_plan": [
    {"type": "unit", "target": "CSVReader", "cases": ["valid CSV loads correctly", "missing columns raises error", "empty file handling"]},
    {"type": "unit", "target": "StatisticsCalculator", "cases": ["correct mean/std for sample data", "quantiles computed accurately", "handle empty data gracefully"]},
    {"type": "unit", "target": "JSONExporter", "cases": ["valid JSON output format", "file write success", "handle write permission errors"]},
    {"type": "integration", "target": "CLI end-to-end", "cases": ["valid input produces correct JSON", "invalid input shows error message", "metrics selection works as expected"]},
    {"type": "manual", "target": "CLI usability", "cases": ["help message clarity", "error messages user-friendly", "performance on large CSV files"]}
  ],
  "risks": [
    {"risk": "Input CSV files may have inconsistent formatting or missing data", "mitigation": "Implement robust validation and clear error messages; provide example CSV format"},
    {"risk": "Large CSV files may cause high memory usage or slow processing", "mitigation": "Use efficient libraries like pandas; consider streaming if needed"},
    {"risk": "User may specify metrics not present in CSV", "mitigation": "Validate metric names early and inform user with suggestions"},
    {"risk": "Quantile calculation may be misunderstood or misconfigured", "mitigation": "Document quantile defaults and allow user configuration with validation"}
  ],
  "open_questions": [
    "What are the exact metric names expected in the CSV and their data types?",
    "Should quantile levels be fixed or configurable via CLI?",
    "Is there a preferred JSON schema or structure for the summary output?",
    "Are there any performance constraints or expected CSV file sizes?"
  ]
}

```json
{
  "title": "Test impact of bonus frequency on RTP volatility",
  "goal": "Evaluate if increasing bonus frequency reduces RTP volatility under fixed CPU budget",
  "parameter_space": {
    "bonus_frequency": [0.05, 0.10, 0.20]
  },
  "success_criteria": {
    "primary_metric": "RTP_volatility",
    "decision_rule": "RTP_volatility decreases as bonus_frequency increases"
  },
  "budget": {
    "max_jobs": 3,
    "max_runtime_seconds": 3600
  },
  "suggested_jobs": [
    {
      "seed": 42,
      "priority": 70,
      "parameters": {"bonus_frequency": 0.05},
      "timeout_seconds": 1200
    },
    {
      "seed": 42,
      "priority": 60,
      "parameters": {"bonus_frequency": 0.20},
      "timeout_seconds": 1200
    }
  ]
}
```

```json
{
  "hypotheses": [
    {
      "title": "Higher Bonus Frequency Reduces RTP Volatility",
      "description": "Increasing the frequency of bonus events in the game math model will decrease RTP volatility by providing more frequent smaller wins, which may stabilize player experience under a fixed CPU budget.",
      "confidence": 0.35,
      "parent_id": null
    }
  ]
}
```

1. Вероятность выигрыша для всех стратегий примерно равна при длительной игре.  
2. Средний выигрыш игрока близок к нулю при большом числе раундов.  
3. Изменение параметров модели не приводит к систематическому преимуществу одной из сторон.