Compute risk metrics (DV01, delta, gamma, PV01) for a contract.

Uses finite difference approximation on the nominal interest rate. Returns the metric value, base PV, and computation parameters.

Args: attributes: Contract attributes dict (same format as simulate). risk_metric: One of "dv01", "delta", "gamma", "pv01". base_rate: Base nominal interest rate (default 0.05). bump_size: Finite difference bump size (default 0.0001 = 1bp).

Get detailed information about a specific ACTUS contract type.

Returns the contract description, category, implementation class, MCP simulatability status, and whether a ChildContractObserver is required. Use this to understand what a contract type represents and whether it can be simulated via MCP.

Args: contract_type: ACTUS contract type code. Examples: PAM (bonds/loans), LAM (amortizing loans), ANN (mortgages), SWPPV (interest rate swaps), OPTNS (options), FXOUT (FX forwards).

Get required and optional parameters for a contract type.

Returns field names, types, descriptions, and example Python code — everything needed to build valid attributes for jactus_simulate_contract. This is the authoritative source for contract parameters; there is no need to read source code.

Also indicates whether the contract can be simulated via MCP or requires the Python API (e.g., contracts needing a ChildContractObserver).

Args: contract_type: ACTUS contract type code (e.g., PAM, LAM, SWPPV).

Get the structure of JACTUS documentation, listing all files with their section headers.

Returns available documentation files with their headers, useful for understanding what documentation is available before searching.

Note: Requires JACTUS source tree access. Set JACTUS_ROOT env var if needed.

List all ACTUS event types with descriptions.

Returns event type codes (IED, IP, PR, MD, RR, etc.) and their meanings. Events represent cash flows and state transitions during a contract's life. Use this to understand the events returned by jactus_simulate_contract.

Retrieve a specific code example's source code.

Returns the full source code, docstring, and metadata for an example. Use jactus_list_examples first to see available examples.

Note: Requires JACTUS source tree access. Set JACTUS_ROOT env var if needed.

Args: example_name: Name of the example (e.g., pam_example, interest_rate_swap_example).

Get a simple quick start example showing a basic PAM contract simulation.

Returns ready-to-run Python code that creates a PAM (Principal at Maturity) contract and simulates it. Good starting point for learning the JACTUS API.

Get a structured guide for a specific JACTUS topic.

Returns a comprehensive markdown guide on the requested topic. More focused than jactus_search_docs for common areas.

Args: topic: Topic name. Available: "contracts" (overview of all types), "behavioral" (behavioral observers, callout events, prepayment/deposit models), "scenario" (scenario management, bundling observers), "jax" (JAX integration and autodiff), "events" (event types and lifecycle), "attributes" (contract parameters and conventions), "array_mode" (batch simulation, portfolio API, GPU/TPU acceleration).

Get JACTUS and MCP server version information.

Returns versions for both the MCP server and the JACTUS library, plus Python version and compatibility status.

Verify MCP server and JACTUS are working correctly.

Checks that JACTUS is installed and importable, examples and docs are accessible, and contracts are registered. Returns status ("healthy", "degraded", or "unhealthy") with specific check results.

List all 18 available ACTUS contract types organized by category.

Returns contract types grouped into: principal (PAM, LAM, LAX, NAM, ANN, CLM), non-principal (UMP, CSH, STK), exotic (COM), and derivative (FXOUT, OPTNS, FUTUR, SWPPV, SWAPS, CAPFL, CEG, CEC).

Start here to discover which contract type matches your financial instrument. Follow up with jactus_get_contract_info for details or jactus_get_contract_schema for the required parameters.

List all available code examples in JACTUS.

Returns Python scripts and Jupyter notebooks from the examples directory. Use jactus_get_example to retrieve the code or jactus_run_example to execute it.

Note: Requires JACTUS source tree access. Set JACTUS_ROOT env var if needed.

List all available risk factor observer types with usage guidance.

Returns observer types organized by complexity, from simple constant values to advanced time-series and curve observers. Each entry includes a description, typical use case, and whether it's available via MCP or requires the Python API.

Use this to determine which risk factor approach to use with jactus_simulate_contract. For MCP simulation, you can use: constant_value (default), risk_factors (dict), or time_series (time-varying). For advanced observers (curves, composites, callbacks, JAX), use the Python API directly.

Also includes behavioral observers (PrepaymentSurfaceObserver, DepositTransactionObserver) that inject callout events into the simulation timeline. These require the Python API.

Execute a JACTUS example and return its output.

Runs the example in a subprocess with a 30-second timeout and returns stdout, stderr, and return code. Use jactus_list_examples to see available examples.

Note: Requires JACTUS source tree access. Set JACTUS_ROOT env var if needed.

Args: example_name: Name of the example (e.g., pam_example, lam_example).

Search JACTUS documentation for specific topics.

Searches across architecture docs, contract guides, and the README. Returns matching lines with context. Use jactus_get_topic_guide for structured guides on common topics.

Note: Requires JACTUS source tree access. Set JACTUS_ROOT env var if needed.

Args: query: Search query (e.g., 'day count convention', 'state transition', 'rate reset', 'prepayment').

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.

Simulate a portfolio of contracts and return aggregate results.

Simulates each contract and aggregates total inflows, outflows, and net cashflow across the portfolio. Returns per-contract summaries.

Args: contracts: Array of contract attribute dicts (same format as simulate). risk_factor_rate: Flat risk factor rate for all contracts (default 0.05).

Validate contract attributes for correctness before simulation.

Checks that all required fields are present, values are valid, and types are correct. Returns field-level error messages and warnings for unknown fields. Call this before jactus_simulate_contract to catch errors early.

Args: attributes: Contract attributes dictionary to validate. Should include contract_type, status_date, contract_role, and type-specific fields.