Make Back-End Calculation Logic Transparent To Everyone

From calculation logic to reviewable outputs

Source of calculation logic

CalculationSourceObject JSON and annotated Python.

Capture and validation

Capture Python execution and validate supplied calculation data.

CalculationSourceObject

symbols · formulas · units · descriptions · results

FormulaSheet print/PDF

Any code export

Proof

Annotated Python becomes formula source

The Python authoring layer keeps the calculation executable while capturing the metadata and observations needed to build a transparent formula graph for review.

Annotated Python file - {name}.cso.py

PanelWidth: TypeAlias = Annotated[
    float,
    symbol(
        glyph=r"w_{pan}",
        unit="m",
    ),
]
PanelHeight: TypeAlias = Annotated[
    float,
    symbol(
        glyph=r"h_{pan}",
        unit="m",
    ),
]

@calculation(
    id="panel-area-illustration",
    ...
)
@section(id="geometry", ...)
def panel_area(
    width: PanelWidth = 2,
    height: PanelHeight = 3,
) -> CalculationResults:
    area: Annotated[
        float,
        symbol(
            glyph=r"A_{rect}",
            unit="m^2",
            description="Panel area",
        ),
    ] = width * height
    return {"area": area}

CSO fragment

{
  "sections": [{ "items": [
    { "kind": "symbol", "symbol": {
        "id": "width", "glyph": "w_{pan}",
        "unit": "m", "valueTree": { "result": {
          "kind": "number", "value": 2 }, ... }
    }},
    { "kind": "symbol", "symbol": {
        "id": "height", "glyph": "h_{pan}",
        "unit": "m", "valueTree": { "result": {
          "kind": "number", "value": 3 }, ... }
    }},
    { "kind": "symbol", "symbol": {
        "id": "area", "glyph": "A_{rect}",
        "description": "Panel area",
        "unit": "m^2", "comment": "...",
        "valueTree": {
          "result": { "kind": "number",
            "value": 6 },
          "nodes": [..., {
            "mode": "FUNCTION",
            "funcSpec": {
              "id": "fg.multiply" },
            "funcArgs": [
              { "key": "width" },
              { "key": "height" }] }]
        }
    }}
  ]}, ...]
}

FormulaSheet row

Calculations

Description

Panel area

Symbol Name

A_{rect}

Formula

A_{rect} = w_{pan} h_{pan}

Value

Unit

m^{2}

Comment

...

Calculation record

What a CalculationSourceObject records

A CSO records formulas, symbols, results and source context. FormulaSheet presents its mathematical rows; a rendered sheet is not the complete calculation source.

Symbols

Descriptive code identifiers, displayed glyphs, units and values identify each quantity.

Formulas

Value-tree nodes keep calculation steps explicit instead of hiding them in code.

Units

Engineering units travel with the formula so reviewers see the context.

Context

Descriptions, comments, assumptions, and results remain attached to the calculation.

Current status

What works today

Available

Constrained Python authoring

Capture source and observe execution with annotated inputs, calculation steps and public outputs.

Available

Source-to-document consistency

Core verifyExecution compares documented formulas with Python observations. Structural parsing alone does not perform this check.

Available

Independent numerical references

Optional reference cases check separately established expected values. A missing matching case is not a pass.

Available

FormulaSheet and prepared documents

React displays supplied data with notation, substitutions, units and explanations. It does not execute calculations.

Available

Browser printing for development

printFormulaSheet requests a browser print. It does not run verification or publish CLI evidence.

Available

Verified CLI PDF publication

cso pdf verifies one captured execution, prepares its document and publishes the PDF with evidence by default. Page inspection remains a separate check.

Available

Core Python code generation

createPythonFromSheetDocument generates dependency-ordered Python from a validated sheet. Generation does not execute or verify it.

Planned

C# / TypeScript export

Additional language targets remain future work.

Planned

Package-manager hosting

Registry hosting for reusable calculation packages on PyPI, npm and NuGet remains future work.