Make Back-End Calculation Logic Transparent To Everyone

From calculation logic to trusted outputs

Source of calculation logic

CalculationSourceObject JSON and annotated Python.

Zod validation

Validate symbols, formulas, units, and results.

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 giving the exporter enough metadata to build a transparent formula graph for review.

Annotated Python

@calculation(id="beam-check", title="Beam Check")
@section(title="Concrete", root=True)
def calculate_beam(b: float, h: float):
    area: Annotated[
        float,
        symbol(
            glyph="A_c",
            unit="mm^2",
            description="Concrete area",
        ),
    ] = b * h

    return {"area": area}

Formula source

{
  "id": "area",
  "glyph": "A_c",
  "valueTree": {
    "rootKey": "area",
    "result": { "kind": "number", "value": 150000 },
    "nodes": [
      { "key": "b", ... , "symbol": { "id": "b" } },
      { "key": "h", ... , "symbol": { "id": "h" } },
      {
        "key": "area",
        "mode": "FUNCTION",
        "funcSpec": { "id": "fg.multiply" },
        "funcArgs": [{ "key": "b" }, { "key": "h" }]
      }
    ]
  }
}

FormulaSheet row

Calculations

Description

Concrete area

Symbol Name

A_{c}

Formula

A_{c} = b h

Value

150000

Unit

{mm}^{2}

Comment

Area from section width and depth

Why It Matters

A small contract for real calculations

FormulaSheet keeps the calculation object deliberately compact: enough structure to validate engineering logic, make it inspectable, and translate it without dragging along application workspace baggage.

Variables

ASCII names, rendered symbols, and code identifiers stay tied to one field.

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

Zod validation

Strict parsing rejects unknown public-source fields, duplicate ids, duplicate node keys, unresolved references, and unsupported functions.

Available

FormulaSheet rendering

Validated calculations render as transparent sheet rows with formulas, values, units, descriptions, and comments.

Available

Python export

The calculation graph exports to dependency-ordered Python from the same validated object.

Available

FormulaSheet print/PDF

Browser printing and repo PDF tooling keep sheets in the same transparent document lane.

Available

Annotated Python input

Author calculations in constrained Python, parse them into the contract, then export sheets and code through repo tooling.

Planned

C# / TypeScript export

Use the contract for future NuGet and npm language targets.

Planned

Package-manager hosting

Host reusable calculation packages natively on PyPI/pip, npm, and NuGet.