rules

Create a new underwriting rule with triggers and effects.

Code
Soft delete an underwriting rule and its triggers and effects.

Marks the rule and all associated triggers and effects as deleted.
This is a soft delete - records are not removed from the database.

Parameters
----------
rule_id : str
    UUID of the rule to delete

Returns
-------
dict
    A JSON object containing:
    - `success` : bool : Whether the deletion was successful

Code
Returns available event types for rules.
Each event type has an id (the constant value) and a name (human-readable text).
Returns a serialized list of IdName objects.

Get a single underwriting rule by ID with its triggers and effects.

Code
Get rules configuration for a policy type.

Parameters
----------
policy_type_id : str
    UUID of the policy type.

Returns
-------
dict
    Response containing rules configuration:
    - policy_type_configs: Category mappings per policy type
    - triggers_spec: Trigger type UI metadata
    - effects_spec: Effect type UI metadata
    - trigger_restrictions: Restrictions for triggers
    - effect_restrictions: Restrictions for effects
    - module_restrictions: Restrictions for modules
    - policy_type_items: Items for trigger/effect dropdowns
    - sub_lines: Sub lines for sub line effect actions
    - ... (other static config)

Code
Get Advanced Triggers documentation for rules.

Returns all markdown documentation files for writing advanced trigger code,
including available data points, referenced data models, and examples.
This documentation applies to advanced triggers across all rule types
(underwriting, STP, events, etc.).

Returns
-------
dict
    A JSON object containing:
    - `content` : str : All documentation files concatenated with separators
    - `files_count` : int : Number of documentation files included
    - `total_chars` : int : Total character count of the content
    - `files` : list : List of relative file paths included

Code
List all underwriting rules for a policy type.

Returns all rules with their triggers and effects, sorted by sort_order.

Parameters
----------
policy_type_id : str
    UUID of the policy type to list rules for.

Returns
-------
dict
    A JSON object with standard API wrapper containing:
    - `success` : bool : Whether the API call succeeded
    - `messages` : list : Error messages if any
    - `data` : list : List of rule objects, each containing:
        - id: UUID of the rule
        - name: Rule name
        - category: Rule category (policy, driver, property, etc.)
        - module: Rule module (all, bc, bq, stp, events)
        - severity: Severity level for STP rules
        - triggers: List of trigger objects
        - effects: List of effect objects
        - ... (other rule fields)

Examples
--------
Request::

    {"policy_type_id": "abc123-..."}

Response::

    {
        "success": true,
        "messages": [],
        "data": [
            {
                "id": "rule-uuid-1",
                "name": "Block high risk drivers",
                "category": "driver",
                "module": "stp",
                "severity": "high",
                "triggers": [...],
                "effects": [...]
            },
            ...
        ]
    }

Code
List STP (Straight-Through Processing) execution results for a revision with pagination.

Retrieves all STP rule execution instances and their individual rule results
for a specific revision, ordered by execution date descending.

Parameters
----------
params : dict
    A JSON object containing request parameters. Required fields include:
    - `revision_id` : str : UUID of the revision to get STP results for.
    Optional fields include:
    - `page` : int : Page number for pagination (default: 1).
    - `page_size` : int : Number of executions per page, max 100 (default: 25).

Returns
-------
dict
    A JSON object containing paginated STP execution results:
    - `results` : list : Array of STP execution objects, each containing:
        - `id` : str : UUID of the STP execution.
        - `revision_id` : str : UUID of the associated revision.
        - `execution_start_time` : str : ISO datetime when execution started.
        - `execution_end_time` : str : ISO datetime when execution ended.
        - `status` : str : Overall execution status ('success' or 'error').
        - `total_rules_executed` : int : Total number of rules executed.
        - `total_rules_succeeded` : int : Number of rules that succeeded.
        - `total_rules_failed` : int : Number of rules that failed.
        - `results` : list : Array of individual rule execution results, each containing:
            - `id` : str : UUID of the rule result.
            - `rule_name` : str : Name of the executed rule.
            - `rule_severity` : str or null : Severity level of the rule
              ('critical', 'high', 'medium', 'low') or null if not set.
            - `status` : str : Rule execution status ('success' or 'error').
            - `error_description` : str or null : Error details if rule failed.
            - `custom_error_code_id` : str or null : Associated custom error code ID.
            - `custom_error_code` : dict or null : Custom error code details if available, containing:
                - `id` : str : UUID of the custom error code.
                - `module` : str : Error code module (e.g., 'stp').
                - `code` : str : Error code string.
                - `description` : str : Error description.
            - `property_id` : str or null : Property ID if rule is property-specific.
            - `driver_contact_id` : str or null : Driver contact ID if rule is driver-specific.
    - `pagination` : dict : Pagination metadata containing:
        - `page` : int : Current page number.
        - `page_size` : int : Number of items per page.
        - `total_count` : int : Total number of executions.
        - `total_pages` : int : Total number of pages.

run

Code
Simulate execution of a rule against a revision or claim without persisting.

Accepts a full rule definition (with triggers and effects) plus an anchor to
run it against, executes the rule through the engine in dry-run mode, and
returns per-trigger and per-effect results.

For UI-scoped categories (``vehicle-ui`` / ``driver-ui`` / ``watercraft-ui``)
the simulation fans out across every matching risk on the revision by
default; ``property_id`` is ignored on this path. Callers can still pass
an explicit ``ui_context`` to override the autoload (useful for Bruno-style
what-if testing of partial form data).

Claim-scoped rules are anchored to a claim instead of a revision: pass
``claim_id`` rather than ``quote_id``. The rule is simulated once against
the whole claim -- triggers are evaluated for the claim itself, then each
effect is previewed against every exposure whose coverage type it targets.
The revision comes from the claim, falling back to an exposure's coverage
exactly as the production claim-rules path does. Which exposures are
actually affected is decided by the rule's own effect targets, not by the
caller.

Parameters
----------
params : dict
    A JSON object containing:
    - `rule` : dict : Full rule definition (same structure as create_rule).
    - `quote_id` : str : UUID of the revision to simulate against.
        Required for every category except ``claim``.
    - `property_id` : str, optional : UUID of a specific property to scope.
        Ignored for UI-scoped and claim-scoped rule categories.
    - `ui_context` : dict, optional : Override for UI-scoped categories.
        Same shape as the production ``run_quoting_ui_rules`` payload.
        When omitted, the simulation runs against every vehicle / driver /
        watercraft on the revision matching the rule's category.
    - `claim_id` : str : UUID of the claim to simulate against. Required
        when the rule's category is ``claim``.

Returns
-------
dict
    A JSON object containing:
    - `success` : bool : Whether simulation completed without errors.
    - `would_fire` : bool : Whether the rule's triggers would fire.
    - `trigger_results` : list : Per-trigger evaluation results.
    - `effects_preview` : list : Per-effect application previews.
    - `execution_time_ms` : int : Simulation duration in milliseconds.
    - `error` : dict or None : Error details if simulation failed.

Update an existing underwriting rule with its triggers and effects.

Code
Triggers and effects present in the database but absent from the payload
are automatically soft-deleted.

Code
Validate an underwriting rule without creating or updating it.

This endpoint validates the rule structure, triggers, and effects
against the schema and business rules. Use this to check for errors
before submitting a create or update request.

Validates:
    - Category and module are known values
    - Module is allowed for the category
    - STP module requires severity
    - Events module requires event type
    - Waiver behavior and waiver_terms cross-validation
    - Date range is valid (from <= to)
    - Triggers are allowed for the category
    - Trigger required fields per type (policy_type_item_id, label_name, value)
    - Effects are allowed for the category
    - Effect required fields per type (target_id, label_name, value, popup_message)
    - Effect is allowed for the module
    - Advanced trigger code syntax and variable usage

Also validates (requires database access):
    - Module, trigger, and effect restrictions for the policy type
    - Trigger/effect items match the rule's category
    - Items referenced by policy_type_item_id/target_id exist and are valid

Parameters
----------
params : dict
    A JSON object containing the rule to validate. Same structure as
    create_rule/update_rule requests.

Returns
-------
dict
    A JSON object with standard API wrapper containing:
    - `success` : bool : Always true (API call succeeded)
    - `messages` : list : Empty list
    - `data` : dict : Validation result with:
        - `valid` : bool : Whether the rule passed validation
        - `errors` : dict : Raw Marshmallow validation errors, empty if valid
        - `conflicting_rules` : list : Names of existing rules whose triggers
          and effects conflict with this rule. Empty list when there are no
          conflicts. Conflicts are warnings -- they do not affect `valid`.
          On updates (`id` set in the payload), the rule itself is excluded
          from the candidate set.

Examples
--------
Valid rule response::

    {
        "success": true,
        "messages": [],
        "data": {
            "valid": true,
            "errors": {},
            "conflicting_rules": []
        }
    }

Valid rule with conflicts response::

    {
        "success": true,
        "messages": [],
        "data": {
            "valid": true,
            "errors": {},
            "conflicting_rules": ["Existing Conflicting Rule"]
        }
    }

Invalid rule response::

    {
        "success": true,
        "messages": [],
        "data": {
            "valid": false,
            "errors": {
                "severity": ["Severity is required for STP rules"],
                "_schema": [{"module": ["Module 'stp' is not allowed for category 'claim'"]}]
            },
            "conflicting_rules": []
        }
    }