Scenario Models¶

This page documents the data models related to what-if scenarios, trades, and simulation results.

Scenario¶

Represents a what-if trade simulation scenario.

Properties¶

Property	Type	Description
`id`	string (UUID)	Unique scenario identifier
`name`	string	Scenario name
`description`	string?	Optional description
`status`	ScenarioStatus	Current scenario status
`base_workbook_id`	string (UUID)?	Base workbook for calculations
`trade_count`	integer	Number of trades in scenario
`created_by`	string	Email of user who created
`created_at`	string (ISO 8601)	Creation timestamp
`updated_at`	string (ISO 8601)	Last update timestamp

Example¶

{
  "id": "990e8400-e29b-41d4-a716-446655440010",
  "name": "Q1 2026 Portfolio Optimization",
  "description": "Test impact of selling low-rated assets and buying high-quality loans",
  "status": "completed",
  "base_workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "trade_count": 5,
  "created_by": "user@example.com",
  "created_at": "2026-01-25T09:00:00Z",
  "updated_at": "2026-01-25T10:30:00Z"
}

ScenarioStatus¶

Enumeration of scenario processing states.

Value	Description
`draft`	Scenario created, awaiting simulation
`calculating`	Simulation in progress
`completed`	Simulation finished successfully
`failed`	Simulation encountered an error

Status Transitions¶

draft -> calculating -> completed
                     -> failed

completed -> draft (if modified)

Trade¶

Represents a proposed trade within a scenario.

Properties¶

Property	Type	Description
`id`	string (UUID)	Unique trade identifier
`scenario_id`	string (UUID)	Parent scenario
`trade_type`	TradeType	Buy or sell
`cusip`	string?	CUSIP identifier
`borrower_name`	string?	Borrower/obligor name
`par_value`	number	Par value of the trade
`price`	number?	Trade price (percentage of par)
`spread`	number?	Interest rate spread
`rating_moodys`	string?	Moody's rating
`rating_sp`	string?	S&P rating
`rating_fitch`	string?	Fitch rating
`industry`	string?	Industry classification
`maturity_date`	string (date)?	Loan maturity date
`loan_data`	object?	Additional loan attributes
`created_at`	string (ISO 8601)	Creation timestamp

Example¶

{
  "id": "aa0e8400-e29b-41d4-a716-446655440020",
  "scenario_id": "990e8400-e29b-41d4-a716-446655440010",
  "trade_type": "buy",
  "cusip": "NEW456DEF",
  "borrower_name": "Strong Corp",
  "par_value": 500000.00,
  "price": 99.5,
  "spread": 2.5,
  "rating_moodys": "Ba2",
  "rating_sp": "BB",
  "rating_fitch": null,
  "industry": "Technology",
  "maturity_date": "2029-06-15",
  "loan_data": {
    "facility_type": "Term Loan B",
    "currency": "USD",
    "seniority": "First Lien"
  },
  "created_at": "2026-01-25T09:00:00Z"
}

TradeType¶

Enumeration of trade directions.

Value	Description
`buy`	Purchase/add position
`sell`	Sell/reduce position

TradeRequest¶

Request body for creating a trade.

Properties¶

Property	Type	Required	Description
`trade_type`	TradeType	Yes	Buy or sell
`cusip`	string	No	CUSIP identifier
`borrower_name`	string	No	Borrower name
`par_value`	number	Yes	Par value
`price`	number	No	Trade price (default: 100)
`spread`	number	No	Interest spread
`rating_moodys`	string	No	Moody's rating
`rating_sp`	string	No	S&P rating
`rating_fitch`	string	No	Fitch rating
`industry`	string	No	Industry
`maturity_date`	string (date)	No	Maturity date
`loan_data`	object	No	Additional attributes

Example¶

{
  "trade_type": "buy",
  "cusip": "NEW456DEF",
  "borrower_name": "Strong Corp",
  "par_value": 500000.00,
  "rating_moodys": "Ba2",
  "spread": 2.5,
  "industry": "Technology"
}

SimulationResult¶

Results from running a scenario simulation.

Properties¶

Property	Type	Description
`scenario_id`	string (UUID)	Scenario identifier
`status`	string	Simulation status
`results`	TestImpact[]	Impact on each compliance test
`impact_summary`	ImpactSummary	Aggregated impact summary
`new_failures`	integer	Number of tests that would newly fail
`total_tests`	integer	Total tests evaluated
`message`	string	Summary message
`executed_at`	string (ISO 8601)	Execution timestamp
`execution_time_ms`	integer	Processing time in milliseconds

Example¶

{
  "scenario_id": "990e8400-e29b-41d4-a716-446655440010",
  "status": "completed",
  "results": [
    {
      "test_name": "Single Obligor Concentration",
      "test_category": "concentration",
      "current_value": 4.2,
      "projected_value": 4.1,
      "threshold_value": 5.0,
      "cushion_current": 0.8,
      "cushion_projected": 0.9,
      "status_current": "pass",
      "status_projected": "pass",
      "impact_direction": "improve"
    },
    {
      "test_name": "CCC Rated Assets",
      "test_category": "rating",
      "current_value": 8.5,
      "projected_value": 6.2,
      "threshold_value": 7.5,
      "cushion_current": -1.0,
      "cushion_projected": 1.3,
      "status_current": "fail",
      "status_projected": "pass",
      "impact_direction": "improve"
    }
  ],
  "impact_summary": {
    "improve": 2,
    "worsen": 1,
    "neutral": 12
  },
  "new_failures": 0,
  "total_tests": 15,
  "message": "Simulation completed: 2 trades applied to 150 loans",
  "executed_at": "2026-01-25T10:30:00Z",
  "execution_time_ms": 1523
}

TestImpact¶

Impact of scenario on a single compliance test.

Properties¶

Property	Type	Description
`test_name`	string	Test display name
`test_category`	string	Test category
`current_value`	number	Current metric value
`projected_value`	number	Projected value after trades
`threshold_value`	number	Test threshold
`cushion_current`	number	Current cushion
`cushion_projected`	number	Projected cushion
`status_current`	TestStatus	Current pass/fail status
`status_projected`	TestStatus	Projected pass/fail status
`impact_direction`	ImpactDirection	Direction of change

Example¶

{
  "test_name": "CCC Rated Assets",
  "test_category": "rating",
  "current_value": 8.5,
  "projected_value": 6.2,
  "threshold_value": 7.5,
  "cushion_current": -1.0,
  "cushion_projected": 1.3,
  "status_current": "fail",
  "status_projected": "pass",
  "impact_direction": "improve"
}

TestStatus¶

Enumeration of test result statuses.

Value	Description
`pass`	Test passes threshold
`fail`	Test fails threshold
`warning`	Test approaching threshold

ImpactDirection¶

Enumeration of impact directions.

Value	Description
`improve`	Projected value moves closer to passing
`worsen`	Projected value moves closer to failing
`neutral`	No significant change

ImpactSummary¶

Aggregated counts of impact directions.

Properties¶

Property	Type	Description
`improve`	integer	Tests that improve
`worsen`	integer	Tests that worsen
`neutral`	integer	Tests with no significant change

Example¶

{
  "improve": 2,
  "worsen": 1,
  "neutral": 12
}

ScenarioCreateRequest¶

Request body for creating a scenario.

Properties¶

Property	Type	Required	Description
`name`	string	Yes	Scenario name (1-200 chars)
`description`	string	No	Description (max 2000 chars)
`base_workbook_id`	string (UUID)	No	Base workbook for calculations
`trades`	TradeRequest[]	No	Initial trades to add

Example¶

{
  "name": "Q1 2026 Portfolio Optimization",
  "description": "Test impact of selling low-rated assets",
  "base_workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "trades": [
    {
      "trade_type": "sell",
      "cusip": "OLD123ABC",
      "borrower_name": "Weak Corp",
      "par_value": 500000.00,
      "rating_moodys": "Caa2"
    },
    {
      "trade_type": "buy",
      "cusip": "NEW456DEF",
      "borrower_name": "Strong Corp",
      "par_value": 500000.00,
      "rating_moodys": "Ba2",
      "spread": 2.5
    }
  ]
}

ScenarioUpdateRequest¶

Request body for updating a scenario.

Properties¶

Property	Type	Required	Description
`name`	string	No	New scenario name
`description`	string	No	New description
`base_workbook_id`	string (UUID)	No	New base workbook

Example¶

{
  "name": "Q1 2026 Portfolio Optimization (v2)",
  "description": "Updated with additional sell trades"
}

Portfolio Metrics Affected¶

Scenarios can impact the following portfolio metrics:

Concentration Metrics¶

Metric	Description
`single_obligor_concentration`	Maximum single obligor exposure
`top_5_concentration`	Top 5 obligors combined
`top_10_concentration`	Top 10 obligors combined
`industry_concentration`	Maximum industry exposure

Rating Metrics¶

Metric	Description
`ccc_bucket_pct`	CCC rated assets percentage
`average_rating_factor`	Portfolio average rating factor
`b_rated_pct`	B rated assets percentage

Coverage Metrics¶

Metric	Description
`oc_ratio`	Overcollateralization ratio
`ic_ratio`	Interest coverage ratio

Portfolio Metrics¶

Metric	Description
`wal`	Weighted average life
`was`	Weighted average spread
`warf`	Weighted average rating factor
`diversity_score`	Moody's diversity score

Workbook Models - Scenarios reference workbooks
Compliance Models - Scenarios impact compliance tests
User Models - Users who create scenarios

Scenario Models¶

Scenario¶

Properties¶

Example¶

ScenarioStatus¶

Status Transitions¶

Trade¶

Properties¶

Example¶

TradeType¶

TradeRequest¶

Properties¶

Example¶

SimulationResult¶

Properties¶

Example¶

TestImpact¶

Properties¶

Example¶

TestStatus¶

ImpactDirection¶

ImpactSummary¶

Properties¶

Example¶

ScenarioCreateRequest¶

Properties¶

Example¶

ScenarioUpdateRequest¶

Properties¶

Example¶

Portfolio Metrics Affected¶

Concentration Metrics¶

Rating Metrics¶

Coverage Metrics¶

Portfolio Metrics¶

Related Models¶