generate-calculations

name	generate-calculations
description	Use when the user wants to turn a validated extract-parameters-from-full JSON into a Python module of deterministic functions implementing the formula_hint expressions for downstream scenario runs and Monte Carlo

Generate Deterministic Calculations from Extracted Parameters

Overview

Wraps the calculation-generator system prompt at system-prompt.txt (next to this file) and applies it to a parameter JSON produced by extract-parameters-from-full (validated by validate-parameters). Output is a single Python module of small, pure functions — one per formula_hint declared in recommended_first_calculations and derived_questions.

Stage 5 of the pipeline described in planexe_simulator/README.md.

When to Use

• User asks to "generate calculations", "emit Python", "materialise the formulas", or "build the deterministic functions" given a validated parameter JSON
• Pipeline step between validate-parameters (passes clean) / generate-bounds and run-scenarios
• User wants importable Python functions ready for scenario tables

Not for: regenerating the parameter JSON (use extract-parameters-from-full), validating it (use validate-parameters), producing low/base/high ranges (use generate-bounds), or running scenarios (use run-scenarios).

Workflow

1. Get the input JSON path. If the user did not provide one, ask. Do not guess.
2. Read system-prompt.txt (sibling of this SKILL.md). Its function-shape, division-guard, and module-structure rules are authoritative.
3. Read the parameter JSON. Assume it has already passed validate-parameters; if it visibly hasn't, tell the user and offer to validate first.
4. Produce the Python module per the system prompt.
5. Output destination. Default: write to a file. Suggested default path: <input-basename>.calculations.py next to the input. Print the file path back, plus a one-line summary (function count, any # skipped lines, any TODO stubs for P(...) notation).

What gets a function

Input list	Action
recommended_first_calculations	one function each
derived_questions	one function each
key_values	not converted — these are caller-supplied inputs
missing_values_to_estimate	not converted — supplied via bounds at scenario time

Skip an entry whose formula_hint is null, empty, or unparseable. Replace with a # skipped: <id> -- <reason> comment.

Function shape (re-stated for emphasis — see system prompt for full detail)

def x(a: float, b: float) -> float:
    return a * b

• Function name = LHS of formula_hint if present, else the entry's id
• Args = each depends_on id in declared order, all typed float
• Return type float
• Body: at most three lines (optional guard if, optional intermediate, return)

Division guards: every variable denominator must short-circuit to float("inf") when ≤ 0. Numeric-literal denominators (e.g. value / 100) need no guard.

Function-style notation translations

Source	Translation
max(...), min(...), abs(...), sum(...)	Python builtins
exp(...), log(...), sqrt(...), ln(...)	math.exp, math.log, math.sqrt (add import math)
mean(...), avg(...)	_mean(*args) helper at top of module
P(...), p(...)	raise NotImplementedError(...) stub with TODO comment carrying the original formula

Module structure

"""
Generated PlanExe deterministic calculations.

Plan: <plan_name>
Plan type: <plan_type>

One function per formula_hint entry...
"""

from __future__ import annotations
import math   # only if needed

# _mean helper, only if needed

# functions, in order: recommended_first_calculations, then derived_questions

No top-level executable code, no __main__ block, no file I/O, no classes, no decorators, no per-function docstrings, no in-body comments (except the P(...) TODO).

Common Mistakes

Mistake	Fix
Wrapping the Python output in ```python fences	Raw Python only
Adding a if __name__ == "__main__": demo block	This stage emits a library, not a runnable script
Generating a class hierarchy	One function per formula; no classes unless required by the formulas themselves (they aren't)
Inventing or omitting arguments to "make the formula work"	Args must match depends_on exactly, in order
Forgetting the divide-by-zero guard	Every variable denominator gets a guard; numeric literals don't
Emitting def people_contacted(...) -> float: """People contacted"""	No per-function docstrings — the signature is self-documenting
Translating P(x >= y) as a literal Python comparison	P(...) is probability notation; emit a NotImplementedError stub instead
Including functions for key_values or missing_values_to_estimate ids	Those are inputs, not calculations

Reference

• System prompt (authoritative): system-prompt.txt
• Pipeline overview and code-generation rules: ../../README.md, Stage 5
• Companion skills: ../extract-parameters-from-full/SKILL.md, ../validate-parameters/SKILL.md, ../generate-bounds/SKILL.md
• Example input for testing: /tmp/extract-params-heatwave-v10.json (passes validate-parameters with valid: true)