Atomizer/docs/protocols/operations/OP_08_GENERATE_REPORT.md

# OP_08: Generate Study Report

<!--
PROTOCOL: Automated Study Report Generation
LAYER: Operations
VERSION: 1.0
STATUS: Active
LAST_UPDATED: 2026-01-06
PRIVILEGE: user
LOAD_WITH: []
-->

## Overview

This protocol covers automated generation of comprehensive study reports via the Dashboard API or CLI. Reports include executive summaries, optimization metrics, best solutions, and engineering recommendations.

---

## When to Use

| Trigger | Action |
|---------|--------|
| "generate report" | Follow this protocol |
| Dashboard "Report" button | API endpoint called |
| Optimization complete | Auto-generate option |
| CLI `atomizer report <study>` | Direct generation |

---

## Quick Reference

**API Endpoint**: `POST /api/optimization/studies/{study_id}/report/generate`

**Output**: `STUDY_REPORT.md` in study root directory

**Formats Supported**: Markdown (default), JSON (data export)

---

## Generation Methods

### 1. Via Dashboard

Click the "Generate Report" button in the study control panel. The report will be generated and displayed in the Reports tab.

### 2. Via API

```bash
# Generate report
curl -X POST http://localhost:8003/api/optimization/studies/my_study/report/generate

# Response
{
  "success": true,
  "content": "# Study Report: ...",
  "path": "/path/to/STUDY_REPORT.md",
  "generated_at": "2026-01-06T12:00:00"
}
```

### 3. Via CLI

```bash
# Using Claude Code
"Generate a report for the bracket_optimization study"

# Direct Python
python -m optimization_engine.reporting.markdown_report studies/bracket_optimization
```

---

## Report Sections

### Executive Summary

Generated automatically from trial data:
- Total trials completed
- Best objective value achieved
- Improvement percentage from initial design
- Key findings

### Results Table

| Metric | Initial | Final | Change |
|--------|---------|-------|--------|
| Objective 1 | X | Y | Z% |
| Objective 2 | X | Y | Z% |

### Best Solution

- Trial number
- All design variable values
- All objective values
- Constraint satisfaction status
- User attributes (source, validation status)

### Design Variables Summary

| Variable | Min | Max | Best Value | Sensitivity |
|----------|-----|-----|------------|-------------|
| var_1 | 0.0 | 10.0 | 5.23 | High |
| var_2 | 0.0 | 20.0 | 12.87 | Medium |

### Convergence Analysis

- Trials to 50% improvement
- Trials to 90% improvement
- Convergence rate assessment
- Phase breakdown (exploration, exploitation, refinement)

### Recommendations

Auto-generated based on results:
- Further optimization suggestions
- Sensitivity observations
- Next steps for validation

---

## Backend Implementation

**File**: `atomizer-dashboard/backend/api/routes/optimization.py`

```python
@router.post("/studies/{study_id}/report/generate")
async def generate_report(study_id: str, format: str = "markdown"):
    """
    Generate comprehensive study report.

    Args:
        study_id: Study identifier
        format: Output format (markdown, json)

    Returns:
        Generated report content and file path
    """
    # Load configuration
    config = load_config(study_dir)

    # Query database for all trials
    trials = get_all_completed_trials(db)
    best_trial = get_best_trial(db)

    # Calculate metrics
    stats = calculate_statistics(trials)

    # Generate markdown
    report = generate_markdown_report(study_id, config, trials, best_trial, stats)

    # Save to file
    report_path = study_dir / "STUDY_REPORT.md"
    report_path.write_text(report)

    return {
        "success": True,
        "content": report,
        "path": str(report_path),
        "generated_at": datetime.now().isoformat()
    }
```

---

## Report Template

The generated report follows this structure:

```markdown
# {Study Name} - Optimization Report

**Generated:** {timestamp}
**Status:** {Completed/In Progress}

---

## Executive Summary

This optimization study completed **{n_trials} trials** and achieved a
**{improvement}%** improvement in the primary objective.

| Metric | Value |
|--------|-------|
| Total Trials | {n} |
| Best Value | {best} |
| Initial Value | {initial} |
| Improvement | {pct}% |

---

## Objectives

| Name | Direction | Weight | Best Value |
|------|-----------|--------|------------|
| {obj_name} | minimize | 1.0 | {value} |

---

## Design Variables

| Name | Min | Max | Best Value |
|------|-----|-----|------------|
| {var_name} | {min} | {max} | {best} |

---

## Best Solution

**Trial #{n}** achieved the optimal result.

### Parameters
- var_1: {value}
- var_2: {value}

### Objectives
- objective_1: {value}

### Constraints
- All constraints satisfied: Yes/No

---

## Convergence Analysis

- Initial best: {value} (trial 1)
- Final best: {value} (trial {n})
- 90% improvement reached at trial {n}

---

## Recommendations

1. Validate best solution with high-fidelity FEA
2. Consider sensitivity analysis around optimal design point
3. Check manufacturing feasibility of optimal parameters

---

*Generated by Atomizer Dashboard*
```

---

## Prerequisites

Before generating a report:
- [ ] Study must have at least 1 completed trial
- [ ] study.db must exist in results directory
- [ ] optimization_config.json must be present

---

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| "No trials found" | Empty database | Run optimization first |
| "Config not found" | Missing config file | Verify study setup |
| "Database locked" | Optimization running | Wait or pause first |
| "Invalid study" | Study path not found | Check study ID |

---

## Cross-References

- **Preceded By**: [OP_04_ANALYZE_RESULTS](./OP_04_ANALYZE_RESULTS.md)
- **Related**: [SYS_13_DASHBOARD](../system/SYS_13_DASHBOARD.md)
- **Triggered By**: Dashboard Report button

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-01-06 | Initial release - Dashboard integration |