Going Polyglot

Step 1: Create the Python Block

Scaffold a new domain block with the Python runtime:

bashboa block create ComputeTax --layer domain --runtime python

This creates src/DomainBlocks/ComputeTax/ with stubs for block.boa and main.py.

Step 2: Define the Block Manifest

block.boaBLOCK ComputeTax 1.0.0
LAYER domain
RUNTIME python
ENTRY main.py
DESC Computes tax and adds it to the bill.

INTENT Calculate sales tax on a restaurant
  bill before computing the tip.

RULE tax = billAmount * taxRate.
RULE billWithTax = billAmount + tax.
RULE Round both to 2 decimal places.
RULE taxRate must be between 0 and 1.

TAGS tax, billing, python, domain

IN billAmount:number!
IN taxRate:number!
OUT tax:number
OUT billWithTax:number

FIXTURE {"billAmount":100,"taxRate":0.08}
  -> {"tax":8.0,"billWithTax":108.0}

FIXTURE {"billAmount":85.50,"taxRate":0.08}
  -> {"tax":6.84,"billWithTax":92.34}

ERR ValidationError

Pythonimport sys
import json

def main():
    raw = sys.stdin.read()
    envelope = json.loads(raw)
    inp = envelope["input"]

    bill = inp["billAmount"]
    rate = inp["taxRate"]

    if not isinstance(bill, (int, float)) \
       or not isinstance(rate, (int, float)) \
       or rate < 0 or rate > 1:
        json.dump({
            "success": False,
            "error": {
                "type": "ValidationError",
                "message":
                    "Invalid inputs"
            }
        }, sys.stdout)
        return

    tax = round(bill * rate, 2)
    total = round(bill + tax, 2)

    json.dump({
        "success": True,
        "output": {
            "tax": tax,
            "billWithTax": total
        }
    }, sys.stdout)

if __name__ == "__main__":
    main()

Step 3: URP Side-by-Side Comparison

Here’s the same protocol implemented in both languages:

TypeScript// 1. Read STDIN
const chunks: Buffer[] = [];
for await (const chunk of process.stdin)
  chunks.push(chunk as Buffer);

// 2. Parse envelope
const envelope = JSON.parse(
  Buffer.concat(chunks)
    .toString("utf-8")
);
const input = envelope.input;

// 3. Process
const result = /* ... */;

// 4. Write STDOUT
console.log(JSON.stringify({
  success: true,
  output: result
}));

Python# 1. Read STDIN
raw = sys.stdin.read()

# 2. Parse envelope
envelope = json.loads(raw)
inp = envelope["input"]

# 3. Process
result = # ...

# 4. Write STDOUT
json.dump({
    "success": True,
    "output": result
}, sys.stdout)

Four steps in any language: read, parse, process, write. That’s the entire integration contract.

Step 4: Register and Test

Add the new block to blocks.boa:

blocks.boaCalculateTip 1.0.0 -> src/DomainBlocks/CalculateTip
SplitBill 1.0.0 -> src/Primitives/SplitBill
ComputeTax 1.0.0 -> src/DomainBlocks/ComputeTax

Test the Python block (no compilation step needed — Python is interpreted):

bashboa test ComputeTax@1.0.0

  ComputeTax@1.0.0
    Fixture 1: PASS
    Fixture 2: PASS
  2 fixtures passed, 0 failed

Step 5: Rewire the Workflow

Update workflows/tip-calculator/workflow.boa to insert the tax step before tip calculation:

workflow.boaWORKFLOW TipCalculator 2.0.0
DESC Calculate tax, tip, and split the bill among people.

# Step 1: Compute tax (Python)
STEP tax = ComputeTax@1.0.0
  MAP billAmount <- _initial.billAmount
  MAP taxRate <- _initial.taxRate

# Step 2: Calculate tip on bill+tax (Node.js)
STEP calc = CalculateTip@1.0.0
  MAP billAmount <- tax.billWithTax
  MAP tipPercent <- _initial.tipPercent

# Step 3: Split the final total (Node.js)
STEP split = SplitBill@1.0.0
  MAP total <- calc.totalWithTip
  MAP people <- _initial.people

What changed

Step 6: Update project.boa

project.boaPROJECT TipCalculator 2.0.0
DESC Calculates tax, tips, and splits bills among people.

DOMAIN Billing
  ComputeTax: Calculates sales tax on a bill (Python)
  CalculateTip: Computes tip amount and total with tip (Node.js)
  SplitBill: Divides a total evenly among people (Node.js)

FLOW TipCalculator: ComputeTax -> CalculateTip -> SplitBill

Step 7: Run and Validate

Update input.json with the new taxRate field:

input.json{
  "billAmount": 85.50,
  "taxRate": 0.08,
  "tipPercent": 18,
  "people": 3
}

bashboa run workflows/tip-calculator/workflow.boa --input-file workflows/tip-calculator/input.json

# Step execution trace:
# 1. ComputeTax (python)  → tax: 6.84, billWithTax: 92.34
# 2. CalculateTip (node)   → tipAmount: 16.62, totalWithTip: 108.96
# 3. SplitBill (node)      → perPerson: 36.32

{
  "perPerson": 36.32
}

bashboa validate

  Blocks: 3 registered
  Fixtures: 6 passed, 0 failed
  Workflows: 1 valid
  Status: OK All valid

Updated Project Structure

Why Polyglot Matters