The Complete Production SOP: How to Deploy and Run Spreadsheet & Financial Modeler in Autonomous AI Agents

---
name: "spreadsheets"
description: "Create, modify, analyze, and format spreadsheet files (xlsx, csv) with dynamic formulas, styling, and charts."
triggers:
  - "calculate excel"
  - "build financial model"
  - "format spreadsheet"
  - "analyze csv"
dependencies:
  python:
    - "openpyxl"
    - "pandas"
    - "xlsxwriter"
---

# Spreadsheet Engine Rules
- Enforce native Excel formulas: Never write computed totals as raw numbers; inject native strings (=SUM, =NPV, =IRR).
- Apply explicit number formatting: Apply '$#,##0.00' for currency and '0.0%' for percentages.
- Structural UX: Auto-adjust column widths based on maximum string lengths and always freeze top header rows.

import sys
import openpyxl
import pandas as pd
import xlsxwriter

print(f"[SUCCESS] Python {sys.version.split()[0]} ready with openpyxl {openpyxl.__version__}, pandas {pd.__version__}, xlsxwriter {xlsxwriter.__version__}")

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
ws = wb.active
ws.title = "Financial Model"
ws.views.sheetView[0].showGridLines = True

# Dynamic Native Formula Example
ws['B1'] = "ARR 2024"
ws['B2'] = 1000000
ws['C1'] = "ARR 2025 (Projected)"
ws['C2'] = "=B2*1.25"  # Native formula, never computed scalar

ws['B2'].number_format = '$#,##0.00'
ws['C2'].number_format = '$#,##0.00'
wb.save('models/saas_forecast.xlsx')

import openpyxl

def test_workbook_integrity():
    wb = openpyxl.load_workbook('models/saas_forecast.xlsx', data_only=False)
    sheet = wb.active
    
    # Verification Gate: Ensure formulas exist and header is frozen
    has_formula = any(str(cell.value).startswith('=') for row in sheet.rows for cell in row if cell.value)
    assert has_formula, "Quality Gate Failed: No native formulas detected in spreadsheet."
    assert sheet.freeze_panes is not None, "Quality Gate Failed: Header row must be frozen."
    print("Workbook integrity check passed successfully.")

if __name__ == '__main__':
    test_workbook_integrity()