.. _explanation-agent:

==================
Explanation Agent
==================

The Explanation Agent is an AI-powered feature that explains insurance premium calculations in plain, conversational language. It helps users understand how their premium was calculated by breaking down complex rating logic into easy-to-understand explanations.

.. contents:: Table of Contents
   :local:
   :depth: 2

Overview
========

What is the Explanation Agent?
-------------------------------

.. figure:: _static/screenshots/explanation_agent_interface.png
   :alt: Explanation Agent Interface
   :align: center
   :width: 100%

   *Screenshot Placeholder: Chat modal showing conversation with agent explaining a $2,340 BOP premium with breakdown of factors and coverages*

The Explanation Agent is a conversational AI assistant that:

* Explains why your premium is a specific amount
* Breaks down calculations step-by-step
* Answers questions about rating factors
* Compares "what-if" scenarios
* Translates insurance jargon into plain language

Key Features
------------

.. table:: Explanation Agent Features
   :widths: 30 70

   +---------------------------+------------------------------------------------------------+
   | Feature                   | Description                                                |
   +===========================+============================================================+
   | Automatic Explanation     | Provides initial summary when you open the chat            |
   +---------------------------+------------------------------------------------------------+
   | Interactive Q&A           | Ask follow-up questions in natural language                |
   +---------------------------+------------------------------------------------------------+
   | Factor Analysis           | Explains how each factor affected the premium              |
   +---------------------------+------------------------------------------------------------+
   | Coverage Breakdown        | Details each coverage's premium calculation                |
   +---------------------------+------------------------------------------------------------+
   | Formula Details           | Shows how formulas were applied                            |
   +---------------------------+------------------------------------------------------------+
   | Scenario Comparison       | Answers "what-if" questions                                |
   +---------------------------+------------------------------------------------------------+

When to Use
-----------

Use the Explanation Agent when you need to:

* Understand why a premium is higher or lower than expected
* Explain pricing to a client or colleague
* Identify which factors have the biggest impact
* Learn how a specific product's rating works
* Troubleshoot unexpected results
* Prepare for client presentations

Getting Started
===============

Accessing the Agent
-------------------

.. figure:: _static/screenshots/explain_quote_button.png
   :alt: Explain This Quote Button
   :align: center
   :width: 100%

   *Screenshot Placeholder: Rating run detail page with "Explain This Quote" button prominently displayed in action buttons section*

To access the Explanation Agent:

1. Complete a rating calculation
2. Navigate to the **Rating History** page
3. Click on a completed rating to view details
4. Click the **Explain This Quote** button

.. note::
   The "Explain This Quote" button only appears for ratings with status "success" or "warning". Failed ratings cannot be explained.

Opening the Chat
----------------

.. figure:: _static/screenshots/explanation_modal_opening.png
   :alt: Explanation Modal Opening
   :align: center
   :width: 100%

   *Screenshot Placeholder: Modal sliding in from right showing "Connecting..." then "Connected" status*

When you click "Explain This Quote":

1. Modal window slides in from the right
2. Connection status shows "Connecting..."
3. Agent automatically analyzes the rating
4. Initial explanation appears (typically 5-10 seconds)
5. Input field becomes active for your questions

Understanding the Interface
============================

Chat Window Components
-----------------------

.. figure:: _static/screenshots/explanation_interface_anatomy.png
   :alt: Explanation Interface Anatomy
   :align: center
   :width: 100%

   *Screenshot Placeholder: Annotated chat interface showing header with close button, scrollable message area, typing indicator, and input field with send button*

The chat interface includes:

1. **Header Bar**:
   * Title: "Premium Explanation"
   * Close button (×)
   * Rating run reference

2. **Message Area**:
   * Auto-scrolls to latest message
   * Agent messages on left (blue)
   * User messages on right (gray)
   * Markdown formatting support
   * Timestamps on hover

3. **Status Indicators**:
   * Connection status alerts
   * Typing indicator when agent is thinking
   * Error messages if connection fails

4. **Input Area**:
   * Text input field
   * Send button
   * Enter key to send
   * Shift+Enter for new line

Message Formatting
------------------

.. figure:: _static/screenshots/explanation_message_formatting.png
   :alt: Message Formatting Examples
   :align: center
   :width: 100%

   *Screenshot Placeholder: Examples of formatted messages with bold text, bullet lists, code blocks, and numbered steps*

Agent messages support rich formatting:

* **Bold text** for emphasis
* *Italic text* for terms
* Bullet lists for factors
* Numbered lists for steps
* Code blocks for formulas
* Tables for comparisons

Using the Explanation Agent
============================

Initial Explanation
-------------------

.. figure:: _static/screenshots/initial_explanation_example.png
   :alt: Initial Explanation Example
   :align: center
   :width: 100%

   *Screenshot Placeholder: Agent's first message showing premium amount, coverage breakdown, and key factors that affected the price*

When you open the chat, the agent automatically provides:

* **Total Premium**: The final calculated amount
* **Coverage Summary**: List of coverages with individual premiums
* **Key Factors**: Most impactful rating factors
* **Calculation Overview**: High-level explanation
* **Invitation**: Prompt to ask questions

Example initial explanation:

.. code-block:: text

   Your total premium is $2,340.00. This includes two coverages:

   • General Liability: $1,140.00
   • Property: $1,200.00

   The calculation started with base premiums based on your business
   type and location. Then we applied adjustments for:

   • Your building's construction type (brick - lower fire risk)
   • Territory rating (urban area)
   • Coverage limits you selected
   • Your chosen deductibles

   What would you like to know more about?

Asking Questions
----------------

.. figure:: _static/screenshots/asking_questions_flow.png
   :alt: Asking Questions Flow
   :align: center
   :width: 100%

   *Screenshot Placeholder: Example conversation flow showing user questions and agent responses*

Best practices for asking questions:

**Good Questions:**

.. code-block:: text

   ✓ "Why is my premium higher than last year?"
   ✓ "How did the territory factor affect the price?"
   ✓ "What's included in the General Liability premium?"
   ✓ "Can you explain the building class rating?"

**Less Effective:**

.. code-block:: text

   ✗ "Why?" (too vague)
   ✗ "Tell me everything" (too broad)
   ✗ "Is this a good price?" (subjective)

Question Types
==============

Factor Questions
----------------

Ask about specific rating factors:

**Example 1: Territory**

.. code-block:: text

   User: "Why did my territory affect the premium?"

   Agent: "Your territory (14 - Downtown Metro) affects your premium
   because it's in an urban area with higher exposure to certain risks.

   Here's how it impacted your calculation:
   • Territory factor: 1.15 (15% increase)
   • This increased your base premium from $2,035 to $2,340
   • Urban territories have higher rates due to:
     - More traffic (liability exposure)
     - Higher replacement costs
     - Greater crime risk

   Suburban territories (like 02 or 03) would have factors around
   0.85-0.95, which could save approximately $230-$350 annually."

**Example 2: Building Value**

.. code-block:: text

   User: "How does building value affect my premium?"

   Agent: "Your building value of $750,000 is the primary driver of
   your Property coverage premium. Here's the breakdown:

   • Base rate: $0.45 per $100 of value
   • Calculation: ($750,000 / 100) × $0.45 = $3,375
   • After adjustments (construction type, protection): $1,200

   If you increased the building value to $1,000,000, your Property
   premium would increase to approximately $1,600 (a $400 increase)."

Coverage Questions
------------------

Ask about coverage calculations:

**Example 1: Coverage Breakdown**

.. code-block:: text

   User: "Break down the General Liability coverage"

   Agent: "Your General Liability coverage ($1,140) was calculated as:

   Step 1: Base Premium
   • Liability limit: $1,000,000
   • Class code: 43211 (Retail Store)
   • Base rate: $1.12 per $1,000 of payroll
   • Your estimated payroll: $500,000
   • Base: ($500,000 / 1,000) × $1.12 = $560

   Step 2: Modifications
   • Territory modifier: 1.15 (urban area)
   • Experience modifier: 1.05 (claims history)
   • Subtotal: $560 × 1.15 × 1.05 = $677

   Step 3: Additional Coverages
   • Products/Completed Operations: $463

   Total GL Premium: $677 + $463 = $1,140"

**Example 2: Coverage Limits**

.. code-block:: text

   User: "Why do I need $1 million liability coverage?"

   Agent: "The $1,000,000 General Liability limit you selected is
   the standard coverage amount for businesses in your industry.

   This limit provides:
   • Per occurrence protection up to $1M
   • Aggregate coverage (total for all claims)
   • Defense costs in addition to the limit

   You could select a $2,000,000 limit for approximately $350 more
   annually, or reduce to $500,000 to save about $280. However,
   $1M is recommended for retail businesses due to customer
   exposure and product liability risks."

Formula Questions
-----------------

Ask about how formulas work:

**Example: Formula Explanation**

.. code-block:: text

   User: "How was the base premium calculated?"

   Agent: "The base premium uses the 'CALC_BASE_PROPERTY' formula:

   Formula: (building_value / 100) × base_rate × construction_factor

   Your values:
   • building_value: $750,000
   • base_rate: $0.45 (from territory/class lookup table)
   • construction_factor: 0.85 (brick construction discount)

   Calculation:
   ($750,000 / 100) × $0.45 × 0.85 = $2,868.75

   The construction_factor of 0.85 represents a 15% discount
   because brick construction has lower fire risk than wood frame."

What-If Scenarios
-----------------

Ask comparative questions:

**Example 1: Deductible Change**

.. code-block:: text

   User: "What if I increased my deductible to $5,000?"

   Agent: "Increasing your deductible from $1,000 to $5,000 would
   typically reduce your premium by approximately 12-15%.

   For your current premium of $2,340:
   • Estimated savings: $280-$350 annually
   • New premium: ~$1,990-$2,060

   Trade-off:
   • Save: $280-$350 per year
   • Risk: Pay $4,000 more out-of-pocket per claim

   Break-even: If you have a claim every 11-14 years, the higher
   deductible saves money. If claims are more frequent, the lower
   deductible may be better."

**Example 2: Coverage Change**

.. code-block:: text

   User: "What if I dropped the Business Income coverage?"

   Agent: "Business Income coverage is optional and adds $385 to
   your premium. Removing it would reduce your total to $1,955.

   However, Business Income coverage protects you if:
   • Your business must close due to covered damage
   • You lose revenue during repairs
   • You have ongoing expenses (rent, payroll)

   For a retail business with $50,000/month revenue, even a
   1-month closure could cost $50,000 in lost income. The $385
   premium provides up to $100,000 in coverage.

   Consider: Can your business survive without revenue for
   several months during repairs?"

Advanced Usage
==============

Multi-Step Conversations
------------------------

.. figure:: _static/screenshots/multi_step_conversation.png
   :alt: Multi-Step Conversation
   :align: center
   :width: 100%

   *Screenshot Placeholder: Conversation showing progressive dive into a topic with user drilling down from high-level to specific details*

The agent maintains context across multiple questions:

.. code-block:: text

   User: "Why is my premium higher than my friend's?"
   Agent: "Premiums vary based on many factors. Which specific
   factors differ between your businesses?"

   User: "We both have retail stores in the same area"
   Agent: "Territory is the same, so let's look at other factors.
   What are the differences in building values, construction types,
   or business classifications?"

   User: "My building is wood frame, theirs is brick"
   Agent: "That's a significant factor! Wood frame construction
   typically increases property premiums by 20-30% compared to
   brick. For your $750,000 building value:
   • Wood frame (you): $1,200 property premium
   • Brick (your friend): ~$840-$920 property premium
   • Difference: $280-$360

   This accounts for most of the premium difference."

Comparing Multiple Ratings
---------------------------

The agent can only access one rating at a time, but you can ask comparative questions:

.. code-block:: text

   User: "How does this compare to my quote from last month?"

   Agent: "I can see this current rating's details but don't have
   access to your previous quotes. However, I can explain what
   factors might cause differences:

   Common changes that affect premiums:
   • Effective date (rates may have changed)
   • Building value updates
   • Coverage limit changes
   • Claims history updates
   • Territory or classification changes

   What changed between the quotes?"

Explanation for Clients
-----------------------

.. figure:: _static/screenshots/client_explanation.png
   :alt: Client Explanation
   :align: center
   :width: 100%

   *Screenshot Placeholder: Agent providing client-friendly explanation without technical jargon*

Request client-friendly explanations:

.. code-block:: text

   User: "Explain this in simple terms for my client"

   Agent: "Here's a client-friendly explanation:

   'Your annual insurance premium is $2,340, which covers your
   business for property damage and liability claims.

   This includes:
   • Building and contents protection: $1,200
   • Liability coverage (if someone gets hurt): $1,140

   The price is based on:
   • Your business location (downtown metro area)
   • Type of business (retail store)
   • Building size and construction
   • Coverage amounts you selected

   This is a competitive rate for your business type and location.
   You can reduce the premium by increasing deductibles, but that
   means you'd pay more out-of-pocket if you have a claim.'"

Technical Details
=================

How It Works
------------

.. figure:: _static/screenshots/explanation_agent_architecture.png
   :alt: Explanation Agent Architecture
   :align: center
   :width: 100%

   *Screenshot Placeholder: Technical diagram showing WebSocket connection, AI processing, and data access flow*

The Explanation Agent:

1. **Retrieves Data**: Loads complete rating run data including:
   * Input factors
   * Calculation steps
   * Formula executions
   * Table lookups
   * Final results

2. **Analyzes**: Uses AI (Claude 3.5 Sonnet) to:
   * Understand the calculation flow
   * Identify key factors
   * Determine impact of each component

3. **Explains**: Generates responses that:
   * Use plain language
   * Provide relevant details
   * Include examples
   * Answer the specific question

4. **Maintains Context**: Remembers the conversation to:
   * Reference previous answers
   * Follow up on topics
   * Avoid repetition

Available Tools
---------------

The agent has access to these data retrieval tools:

.. table:: Agent Tools
   :widths: 30 70

   +---------------------------+------------------------------------------------------------+
   | Tool                      | Purpose                                                    |
   +===========================+============================================================+
   | get_calculation_overview  | High-level summary of the entire calculation               |
   +---------------------------+------------------------------------------------------------+
   | get_coverage_breakdown    | Detailed breakdown for specific coverage                   |
   +---------------------------+------------------------------------------------------------+
   | get_factor_explanation    | How a specific factor affected the premium                 |
   +---------------------------+------------------------------------------------------------+
   | get_formula_details       | Details about formulas used in calculations                |
   +---------------------------+------------------------------------------------------------+

Example tool usage:

.. code-block:: text

   User: "Explain the property coverage"

   [Agent calls: get_coverage_breakdown(coverage_code="PROPERTY")]

   Agent receives:
   {
     "coverage_code": "PROPERTY",
     "coverage_name": "Building & Contents",
     "base_premium": 2868.75,
     "modified_premium": 1200.00,
     "calculation_breakdown": [
       {
         "step": 1,
         "description": "Calculate base property premium",
         "formula": "CALC_BASE_PROPERTY",
         "result": 2868.75
       },
       ...
     ]
   }

   Agent uses this data to explain to you.

Security and Privacy
====================

Access Control
--------------

The Explanation Agent enforces strict access control:

* **Authentication Required**: Must be logged in
* **Authorization Check**: Can only explain ratings you created or have permission to view
* **Session Isolation**: Each chat is independent
* **No Data Sharing**: Your conversations are not shared with other users

.. warning::
   If you try to access a rating you don't own, the connection will be rejected with an "Access Denied" error.

Data Retention
--------------

Conversation data handling:

.. table:: Data Retention Policy
   :widths: 30 70

   +---------------------+------------------------------------------------------------+
   | Data Type           | Retention                                                  |
   +=====================+============================================================+
   | Messages            | Not stored (ephemeral session only)                        |
   +---------------------+------------------------------------------------------------+
   | Rating Data         | Stored as part of rating run (permanent)                   |
   +---------------------+------------------------------------------------------------+
   | Usage Metrics       | Aggregated metrics only (no message content)               |
   +---------------------+------------------------------------------------------------+

Best Practices
==============

Getting Better Explanations
----------------------------

1. **Be Specific**: Instead of "Why?", ask "Why did the territory factor increase my premium?"

2. **Provide Context**: "I'm presenting this to a client" helps the agent adjust language

3. **Ask Follow-ups**: If unclear, ask for clarification or examples

4. **Request Comparisons**: "What if I changed X?" helps understand impact

5. **Focus on One Topic**: Address one question at a time for clearer answers

Example Progression
-------------------

.. code-block:: text

   ❌ Vague: "Is this right?"
   ✓ Better: "Why is the General Liability premium $1,140?"
   ✓✓ Best: "Break down how the General Liability premium of $1,140
             was calculated, and explain which factors had the
             biggest impact."

When to Use vs. Not Use
-----------------------

**Good Use Cases:**

* Understanding unexpected premium changes
* Preparing client presentations
* Training new underwriters
* Troubleshooting calculations
* Learning product rating logic

**Not Recommended For:**

* Changing the calculation (agent explains only, doesn't modify)
* Getting underwriting advice (agent explains data, not policy)
* Comparing to competitors (no external data)
* Historical trend analysis (one rating at a time)

Troubleshooting
===============

Connection Issues
-----------------

.. figure:: _static/screenshots/connection_error.png
   :alt: Connection Error
   :align: center
   :width: 100%

   *Screenshot Placeholder: Error alert showing "Connection failed. Please check your internet connection and try again."*

If the chat won't connect:

1. **Check Internet**: Ensure stable connection
2. **Refresh Page**: Reload the rating run detail page
3. **Try Again**: Click "Explain This Quote" again
4. **Check Browser**: Ensure JavaScript and WebSockets enabled
5. **Contact Support**: If problem persists

Agent Not Responding
--------------------

If the agent doesn't respond:

* **Wait**: Initial analysis can take 10-15 seconds
* **Check Typing Indicator**: Shows agent is processing
* **Review Message**: Ensure question was sent (look for your message in chat)
* **Refresh**: Close and reopen the chat
* **Report Issue**: If agent consistently fails to respond

Unclear Explanations
--------------------

If an explanation doesn't make sense:

.. code-block:: text

   User: "Can you explain that in simpler terms?"
   User: "Can you give me an example?"
   User: "What does [term] mean?"
   User: "Can you break that down step-by-step?"

Error Messages
--------------

Common error messages:

.. table:: Error Resolution
   :widths: 40 60

   +--------------------------------+-----------------------------------------------+
   | Error Message                  | Solution                                      |
   +================================+===============================================+
   | "Connection failed"            | Check internet, refresh page, try again       |
   +--------------------------------+-----------------------------------------------+
   | "Access denied"                | You don't own this rating, check permissions  |
   +--------------------------------+-----------------------------------------------+
   | "Rating not found"             | Rating may have been deleted, go back         |
   +--------------------------------+-----------------------------------------------+
   | "Service unavailable"          | AI service temporarily down, try later        |
   +--------------------------------+-----------------------------------------------+

Examples and Use Cases
======================

Example 1: Understanding Territory Impact
------------------------------------------

.. code-block:: text

   Context: Underwriter notices higher premium for urban location

   User: "Why is territory 14 more expensive than territory 01?"

   Agent: "Great question! Territory 14 (Downtown Metro) has
   a higher rating factor than Territory 01 (Rural Area) due to
   several risk factors:

   Territory 14 Characteristics:
   • Higher traffic density (increased liability exposure)
   • Greater property values (higher replacement costs)
   • More crime incidents (theft, vandalism risk)
   • Higher claims frequency historically
   • Factor: 1.15 (15% increase)

   Territory 01 Characteristics:
   • Lower traffic (reduced accident risk)
   • Lower property values
   • Less crime
   • Lower claims frequency
   • Factor: 0.85 (15% decrease)

   Impact on Your Premium:
   • Base premium: $2,035
   • Territory 14: $2,035 × 1.15 = $2,340
   • Territory 01 would be: $2,035 × 0.85 = $1,730
   • Difference: $610 annually

   This reflects actuarial data showing Territory 14 has
   approximately 35% higher claims costs than Territory 01."

Example 2: Client Presentation
-------------------------------

.. code-block:: text

   Context: Underwriter needs to explain pricing to client

   User: "Give me a simple explanation for my client about why
   their premium is $2,340"

   Agent: "Here's a client-friendly explanation:

   'Your business insurance premium is $2,340 per year. This
   covers you for:

   1. Property Protection ($1,200/year)
      - Covers your building and contents up to $750,000
      - Protects against fire, theft, weather damage
      - $1,000 deductible means you pay first $1,000 of any claim

   2. Liability Protection ($1,140/year)
      - Covers if someone gets injured on your property
      - Protects against lawsuits up to $1,000,000
      - Includes legal defense costs

   Why This Amount?
   • Your business is in downtown (higher risk area)
   • Retail stores have more customer exposure
   • Your building size and construction type
   • Amount of coverage you selected

   This rate is competitive for your business type and location.
   You have options to adjust the cost:
   • Higher deductible = lower premium (but more out-of-pocket)
   • Lower coverage limits = lower premium (but less protection)
   • Security improvements might qualify for discounts

   Would you like me to show you how different deductibles would
   affect your price?'"

Example 3: Troubleshooting Unexpected Results
----------------------------------------------

.. code-block:: text

   Context: Premium is higher than expected

   User: "The premium is $800 higher than I estimated. Why?"

   Agent: "Let's identify what's causing the difference. Your
   actual premium is $2,340. Can you tell me what you estimated?"

   User: "I estimated $1,540 based on the territory and building value"

   Agent: "I see the discrepancy. Here are the factors that
   added to the base calculation:

   Base Calculation:
   • Building value premium: ~$900
   • Base liability: ~$640
   • Estimated total: $1,540 ✓ (matches your estimate)

   Additional Factors Applied:
   • Territory modifier: +15% ($231)
   • Protection class: +8% ($123)
   • Claims history experience mod: +5% ($77)
   • Business income coverage: $385 (optional coverage included)
   • Deductible credit: -$16 (selected $1,000 deductible)

   Total Additions: $800

   The main difference is:
   1. Territory modifier (15% increase): $231
   2. Optional Business Income coverage: $385
   3. Protection class (no sprinklers): $123
   4. Experience modifier: $77

   To get closer to your estimate:
   • Remove Business Income coverage: -$385
   • Installing sprinklers could reduce protection class: ~-$120

   These changes would bring the premium to approximately
   $1,835, much closer to your $1,540 estimate."

Next Steps
==========

* **Try It**: Open a rating and click "Explain This Quote"
* **Learn More**: See :doc:`ai_agents_overview` for AI features overview
* **Get Training**: Contact your administrator for explanation agent training
* **API Access**: See :doc:`api_integration` for API-based explanations

.. tip::
   Practice with the Explanation Agent on familiar ratings first. This helps you understand how it works before using it with clients.

.. note::
   The Explanation Agent uses the exact same data and formulas as the rating engine. If an explanation seems incorrect, it may indicate a configuration issue that should be reviewed.