> ## Documentation Index
> Fetch the complete documentation index at: https://icrl.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Exception Handling Demo

> ICRL vs vanilla: applying past precedents when policy is too rigid

## Overview

The exception handling demo shows ICRL's ability to learn from past precedents when handling unusual situations and edge cases. Unlike standard policy lookups, real exception handling requires institutional memory of what worked before.

## The Problem

Every organization handles exceptions based on unwritten rules and past precedents:

* "Refund requests > 30 days: approve if they're a long-term customer"
* "Enterprise customer asks for custom terms: always loop in legal first"
* "User claims they were charged twice: refund first, investigate later"
* "Competitor is poaching our customer: escalate to VP, offer retention discount"

This knowledge lives in past decisions by senior staff and tribal knowledge — **not in any policy document.**

## How ICRL Solves This

ICRL stores successful exception-handling decisions as trajectories. When a similar situation arises:

1. **Retrieves relevant precedents** based on situation similarity
2. **Applies learned decision patterns** instead of rigid policy
3. **Provides confident, consistent answers** aligned with past decisions

## Demo Structure

<Tree>
  <Tree.Folder name="examples/exception_handling_demo" defaultOpen>
    <Tree.File name="README.md" />

    <Tree.File name="setup_demo.py" />

    <Tree.File name="run_demo.py" />

    <Tree.File name="evaluate_responses.py" />

    <Tree.Folder name="scenarios" defaultOpen>
      <Tree.File name="seed_decisions.json" />

      <Tree.File name="test_scenarios.json" />

      <Tree.File name="policies.md" />
    </Tree.Folder>

    <Tree.File name="run_quick_demo.sh" />
  </Tree.Folder>
</Tree>

The `policies.md` contains strict, black-and-white rules that don't account for nuance. The **real** handling comes from past decisions.

## Running the Demo

From the project root:

```bash theme={null}
cd examples/exception_handling_demo

# 1. Setup — seeds the trajectory database with past decisions
uv run python setup_demo.py

# 2. Run the comparison test
uv run python run_demo.py

# 3. View detailed evaluation
uv run python evaluate_responses.py
```

Quick run:

```bash theme={null}
uv run bash run_quick_demo.sh
```

## Expected Results

| Scenario                    | ICRL                            | Vanilla                            |
| --------------------------- | ------------------------------- | ---------------------------------- |
| Late refund, loyal customer | Approve with goodwill           | Deny (policy says 30 days)         |
| Enterprise custom terms     | Loop in legal, likely approve   | Deny (policy says no custom terms) |
| Competitor poaching         | Escalate + retention offer      | Standard response                  |
| Billing dispute, high-value | Refund first, investigate later | Investigate first                  |

**Expected: ICRL matches precedent \~85%+ vs Vanilla \~30%**

## Prerequisites

* `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` set
* `uv run` from project root, or `python` with `PYTHONPATH` including `src/`

## Key Insight

This demo proves ICRL's value for **judgment-based tasks** where:

* Official policy is too rigid for real situations
* Past precedents define the actual practice
* Consistency matters for fairness and trust