Modeling Workflow

This document describes the Deal Modeling Workflow in the Foundry system — from interactive model authoring through validation, compilation, and code generation.

---

Overview

The Deal Foundry provides an end-to-end environment for defining, validating, and generating executable programs for entertainment deal types. Models are composed using the DealModel DSL, which defines primitives like:

• Variables — reusable values or expressions (e.g., gross_revenue, taxes, fees).
• Operators — named forms of and or or (e.g., versus, escalates_to).
• Events — conditional conditions or milestones (e.g., box_office >= 2 * cost).
• Clauses — atomic deal terms (e.g., guarantee, bonus, participation clause).
• Blocks — compositions of clauses joined by operators.
• Types — final deal definitions built from blocks.

Each deal model is versioned and self-contained, defining its logic independent of specific business data.

---

The Authoring Stage — Foundry UI

1. Interactive Model Builder
   The Foundry interface allows authors to visually assemble models using primitives. Each rule type has a dedicated editor form:

   • Variables → expressions or constants
   • Operators → definitions of and/or
   • Events → boolean conditions (optionally time-bounded)
   • Clauses → textual description, optional when event, and optional schedule
   • Blocks → drag-and-drop expressions combining clauses

2. Real-time Validation
   As the author edits the model, the Foundry passes the updated text to the ANTLR parser. Errors are displayed inline, allowing rapid correction.

3. Visual Composition View
   The user can see a live diagram (Mermaid or Graph view) of the current clause graph — showing events, conditionals, and operator relationships.

4. Versioning and Metadata
   Each model defines a header block:

   model { deal_type: Film Revenue, version: 1.0.0 }

   The Foundry stores all models with full version history and optional release notes.

---

Validation and Compilation

When a model is saved, the Foundry backend executes several stages:

Parsing

• The model text is parsed using ANTLR based on DealModel.g4.
• The parse tree is converted into an Abstract Syntax Tree (AST).

Semantic Validation

• Ensures all references (e.g., events, variables, operators) are defined.
• Checks name uniqueness and data type compatibility.
• Validates the block expression structure.

IR Generation

The compiler produces a structured Intermediate Representation (IR), typically JSON:

{
  "model": { "deal_type": "Film Revenue", "version": "1.0.0" },
  "variables": [ { "name": "gross_box_office" }, { "name": "taxes" } ],
  "operators": [ { "name": "versus", "type": "or" } ],
  "events": [ { "name": "box_office_threshold", "condition": "gross_box_office >= 2 * production_cost" } ],
  "clauses": [ { "name": "guarantee" }, { "name": "bonus", "when": "box_office_threshold" } ],
  "blocks": [ { "name": "payout", "expr": "guarantee versus bonus" } ],
  "type": { "name": "film_deal", "compose": "payout" },
  "interfaces": [ "DealSchema", "Calculations", "RevenueBlocks", "Events" ]
}

This IR is deterministic and serves as the canonical model definition for all downstream operations.

---

Code Generation

The codegen service takes the IR and produces language-specific skeletons implementing standard interfaces:

• DealSchema — metadata and version info
• Calculations — computation and payout logic
• RevenueBlocks — revenue data structures
• Events — event evaluation and activation

TypeScript Example

export class FilmDeal implements DealSchema, Calculations, RevenueBlocks, Events {
  dealType = "Film Revenue";
  version = "1.0.0";

  async compute(inputs) {
    // Compute guarantee vs bonus logic here
  }

  async evaluateEvents() {
    // Evaluate conditions such as box_office >= 2 * production_cost
  }
}

Other Targets

Additional generators can output:

• Python classes for analytics pipelines
• SQL schema for data warehousing
• JSON Schema for front-end form validation

---

Simulation and Testing

1. Interactive Sandbox — Users can enter sample data to simulate payouts and validate event logic.
2. Trace Viewer — Displays evaluation order: which clauses activated, which events fired, and how operators combined results.
3. Golden Tests — Each version of a model includes a set of test vectors ensuring backward compatibility.

---

Publishing and Integration

Once validated, a model can be published to the Deal Registry, making it available for:

• Deal instance creation in CRM or finance tools.
• Integration with reporting pipelines.
• Programmatic access via API (/api/deal-models/:type/:version).

Published models are immutable — new versions are created through controlled upgrades (1.0.0 → 1.1.0, 2.0.0, etc.).

---

Summary Workflow Diagram

graph LR
  A["Foundry UI<br/>Model Authoring"] --> B["ANTLR Parser<br/>Validation"]
  B --> C["Compiler<br/>IR Generation"]
  C --> D["Codegen<br/>TS / Python / SQL / JSON"]
  D --> E["Simulation<br/>& Testing"]
  E --> F["Deal Registry<br/>Publish & Integrate"]

---

Key Principles

• Grammar is the contract — all models validate through ANTLR.
• IR is the truth — every artifact (code, schema, UI) derives from IR.
• Interfaces are standardized — all generated code implements the same core contracts.
• Versioning is immutable — models evolve via explicit semantic version bumps.