insights

Acknowledge an insight with reshow-driven resolution.

Code
Stamps ``last_acknowledged_at`` / ``last_acknowledged_by`` and applies
the insight's ``reshow`` policy: snooze (``UNTIL_RESOLVED``), dismiss
(``ON_DATA_CHANGE`` / ``ONCE_ONLY``), or stamp-only for
``IMMEDIATE_BLOCKING`` severity. Writes an audit note on the parent
claim or policy. Does not touch ``last_evaluated_at``.

Parameters
----------
id : str
    UUID of the insight to acknowledge.

Returns
-------
dict
    ``{"insight": {...}}`` -- the updated insight.

Create a new insight.

Code
Called exclusively by the copilot agents (via the ``bc-insights`` MCP
server); human users do not hit this endpoint.

Parameters
----------
reference_type : str
    ``CLAIM`` or ``POLICY``.
reference_id : str
    UUID of the claim or policy to attach the insight to.
insight_type : str
    One of ``MISSING``, ``WORKFLOW``, ``ADVISORY``, ``QUALITY``,
    ``CONFLICT``, ``FRAUD``, ``GAPS``, ``DOC``.
insight_severity : str
    One of ``IMMEDIATE_BLOCKING``, ``ACTION_NEEDED``,
    ``RECOMMENDED_REVIEW``, ``INFORMATIONAL``.
title : str
    Short headline (1-120 characters).
description : str
    Reader-facing narrative (1-4000 characters).
product_area : str, optional
    A product area valid for the reference type (see
    ``list_insights``). Omit / null for reference-wide insights.
selector : str, optional
    Optional card-level deep-link within ``product_area`` (requires
    a non-null product area). Valid values are per-product-area
    enums (see ``CLAIM_INSIGHT_SELECTORS`` /
    ``POLICY_INSIGHT_SELECTORS``).
reshow : str, optional
    Acknowledge re-show policy (one of ``UNTIL_RESOLVED``,
    ``ON_DATA_CHANGE``, ``ONCE_ONLY``). Defaults to ``UNTIL_RESOLVED``.
snooze_days : int, optional
    Per-insight snooze-window override in days; null falls back to the
    severity default.

Returns
-------
dict
    ``{"insight": {...}}`` -- the freshly persisted insight, including
    the server-assigned ``id`` and timestamps.

Hard-delete an insight.

Code
Parameters
----------
id : str
    UUID of the insight to delete.
reference_type : str, optional
    ``CLAIM`` or ``POLICY``; accepted for backwards compatibility
    but ignored -- the write scope is resolved from the stored
    row's own reference type, and the service additionally enforces
    the row's type lens.

Returns
-------
dict
    ``{"deleted": true}`` on success.

Trigger an out-of-band reconcile for a claim or policy.

Code
Asks the matching copilot agent (Claims Copilot for CLAIM, Policy
Copilot for POLICY) to run its reconcile procedure for the reference
as an AIAgents background job. Progress is mirrored in the local
``agent_jobs`` index and returned as ``evaluation_status`` (also
available from ``list_insights`` while the job is in flight). The
agent applies the result via ``reconcile_insights``; no claim or
policy state is mutated by this endpoint itself.

Parameters
----------
reference_type : str
    ``CLAIM`` or ``POLICY``.
reference_id : str
    UUID of the claim or policy to (re)evaluate.

Returns
-------
dict
    ``{"status": "QUEUED"|"SKIPPED", "evaluation_status": {...}?}``.

List insights for a claim or policy, persona-filtered server-side.

Code
The result set is trimmed to the insight types the caller is permitted
to see for the reference type (R-30). A user with zero type-lens
permissions receives an empty list and zero counts.

Tab / product-area visibility is a client-side display filter, not a
server ACL. This endpoint still returns every type-permitted insight.

Parameters
----------
reference_type : str
    ``CLAIM`` or ``POLICY``.
reference_id : str
    UUID of the claim or policy whose insights are being requested.
product_area : str, optional
    Restrict results to a single product area. For CLAIM references:
    one of INFORMATION, PARTIES, VEHICLES, DAMAGED_PROPERTIES,
    INJURIES, ESTIMATIONS, ACCOUNTING, DISPUTES, NOTES, ATTACHMENTS.
    For POLICY references: one of INFORMATION, UNDERWRITING,
    SUBJECTIVITIES, CONTACTS, PROPERTY, VEHICLES, DRIVERS, COVERAGES,
    RATING, NOTES, ATTACHMENTS, RENEWAL. Pass the literal string
    ``__NULL__`` to limit results to reference-wide insights (rows
    whose ``product_area`` is null). Omit / null for "no product-area
    filter". Any other value is rejected with HTTP 400.
include_hidden : bool, optional
    When ``False`` (default), exclude dismissed insights and insights
    still inside an active snooze window from both the list and
    counts. When ``True``, return the full set including hidden rows.

Returns
-------
dict
    ``{"insights": [...], "counts": {"total": N, "by_type": {...}}}``
    -- ``insights`` is filtered by ``product_area`` when supplied;
    ``counts`` are reference-wide over the caller's permitted insight
    types, so a product-area tab can still show the full permitted
    severity summary.

Apply a full reconciliation payload from a copilot agent atomically.

Code
Combines four sub-operations into one request-level transaction:
``keep`` (touch), ``update`` (partial update), ``remove`` (delete),
``create`` (insert). Any per-row validation failure aborts the whole
payload -- no partial writes, ever (FR-036 convergence invariant).

All ids referenced in ``keep``, ``update``, and ``remove`` must
belong to the supplied reference -- cross-reference ids are rejected
with 400.

Parameters
----------
reference_type : str
    ``CLAIM`` or ``POLICY``.
reference_id : str
    UUID of the claim or policy under reconciliation.
keep : list of str, optional
    UUIDs of insights to retain (their ``last_evaluated_at`` is
    bumped). Default: empty list.
update : list of dict, optional
    Per-row partial updates. Each entry: ``{id, title?,
    description?, product_area?, selector?}``. An entry that moves
    ``product_area`` without a ``selector`` clears a stored selector
    the new area does not define. Default: empty list.
remove : list of str, optional
    UUIDs of insights to delete. Default: empty list.
create : list of dict, optional
    Per-row creates. Each entry: ``{insight_type, insight_severity,
    title, description, product_area?, selector?}``. The reference is
    taken from the parent envelope. Default: empty list.

Returns
-------
dict
    ``{"applied": {"kept": N, "updated": N, "removed": N,
    "created": N}, "created_ids": [...]}`` -- counts per arm and the
    server-assigned ids of the new rows in submission order.

Bulk-bump last_evaluated_at for the listed insight ids.

Code
Used by the copilot agents after a reconciliation run to mark
"still-valid" insights as freshly evaluated without changing their
content. All supplied ids must belong to the reference; cross-
reference ids are rejected.

Parameters
----------
reference_type : str
    ``CLAIM`` or ``POLICY``.
reference_id : str
    UUID of the claim or policy that owns every id in ``ids``.
ids : list of str
    UUIDs of the insights to touch (min length 1).

Returns
-------
dict
    ``{"updated": N}`` -- number of rows whose ``last_evaluated_at``
    was bumped.

Clear acknowledgment state and restore insight visibility.

Code
Clears ``last_acknowledged_at``, ``last_acknowledged_by``,
``snoozed_until``, and ``dismissed``. Writes an audit note on the
parent claim or policy.

Parameters
----------
id : str
    UUID of the insight to unacknowledge.

Returns
-------
dict
    ``{"insight": {...}}`` -- the updated insight.

Partially update an existing insight.

Code
Mutable fields: ``title``, ``description``, ``product_area``,
``selector`` only (FR-034c).

Immutable (rejected with 400 if present): ``reference_type``,
``reference_id``, ``insight_type``, ``insight_severity``,
``first_seen_at``, ``date_added``, ``last_evaluated_at``,
``date_updated``. To change type or severity, delete and recreate
(or reconcile ``remove`` + ``create``).

Parameters
----------
id : str
    UUID of the insight to update.
title : str, optional
    New headline (1-120 characters).
description : str, optional
    New narrative (1-4000 characters).
product_area : str, optional
    New product area (valid for the row's reference type), or null to
    clear.
selector : str, optional
    New card-level deep-link within ``product_area``, or null to
    clear. Requires a non-null effective product area. Changing
    ``product_area`` without sending ``selector`` clears a stored
    selector the new area does not define, since that card is not on
    the new page; send both to land on a specific card.

Returns
-------
dict
    ``{"insight": {...}}`` -- the updated insight.