jactus_simulate_contract

Simulate an ACTUS contract and return structured cash flow events.

Creates a contract from the provided attributes, runs the ACTUS simulation engine, and returns all generated events with payoffs, timing, and optional contract state snapshots. Supports ALL 18 contract types including composite contracts (SWAPS, CAPFL, CEG, CEC) via the child_contracts parameter.

Common workflow:

1. Use jactus_get_contract_schema to get required fields for your contract type

2. Build the attributes dict with those fields

3. Call this tool to simulate

4. Examine the events and summary in the response

Risk factor observer selection (in priority order):

1. time_series - Time-varying market data with interpolation (for rate resets)

2. risk_factors - Fixed per-identifier values (for static market data)

3. constant_value - Single constant for all risk factors (default: 0.0)

Output size management:

• For contracts with many events, use event_limit and event_offset to paginate

• If include_states=True produces output that is too large, events are auto-truncated to first 5 + last 5, with a pagination hint in the response

Args: attributes: Contract attributes dict. Must include contract_type (e.g., "PAM"), status_date (ISO date), contract_role ("RPA" or "RPL"), and type-specific required fields. Use jactus_get_contract_schema to see required fields. risk_factors: Dict mapping risk factor identifiers to constant values. Example: {"LIBOR-3M": 0.05, "USD/EUR": 1.18} time_series: Dict mapping identifiers to time-value pairs for time-varying data. Each entry is [date_string, value]. Example: {"LIBOR-3M": [["2024-01-01", 0.04], ["2024-07-01", 0.045]]} interpolation: Interpolation method for time_series: "step" (default) or "linear". Step uses the most recent known value; linear interpolates between points. Note: both modes give identical results when query dates exactly match data points. To see differences, use data points at different dates than resets. extrapolation: Extrapolation method for time_series: "flat" (default) or "raise". Flat returns the nearest endpoint value; raise returns an error. constant_value: Constant risk factor value (default 0.0). Used only when neither risk_factors nor time_series is provided. include_states: If True, include contract state before/after each event. Warning: this significantly increases output size for contracts with many events. event_limit: Maximum number of events to return. Use with event_offset for pagination. The summary always covers all events regardless. event_offset: Number of events to skip from the beginning (default 0). child_contracts: Dict mapping child identifiers to their attribute dicts. Required for composite contracts (SWAPS, CAPFL, CEG, CEC). Each child is simulated first, then its results are fed into the parent contract. The identifiers must match those referenced in the parent's contract_structure. Example for SWAPS: {"LEG1": {PAM attrs...}, "LEG2": {PAM attrs...}} Example for CAPFL/CEG/CEC: {"LOAN-001": {PAM attrs...}}

Returns: Dict with: success, contract_type, num_events, events (list of event dicts), summary (total_inflows, total_outflows, net_cashflow, first/last_event), initial_state, final_state, child_results (if child_contracts provided). If paginated: includes pagination dict. On error: success=False, error, error_type, hint.