# Event Signal

## Overview

`event` is a heuristic routing signal family for **structured event metadata** extracted from request text: event type, severity level, temporal urgency, and domain-specific action codes.

It maps to `config/signal/event/` and is declared under `routing.signals.events`.

## Key Advantages

- Zero ML inference — all matching is regex-based, running in sub-millisecond time.
- Routes enterprise event-driven payloads (error alerts, audit logs, incident reports) to specialized model pools without requiring a domain classifier.
- Confidence is proportional to the number of matched criteria, giving the decision engine a graded signal.
- Temporal urgency detection (`urgent`, `immediate`, `asap`, `deadline`, `time-sensitive`, `now`, `critical.window`) routes time-sensitive events independently of event type.

## What Problem Does It Solve?

Keyword and embedding signals are tuned for natural-language queries. Structured event payloads — JSON fragments, alert messages, transaction error codes — contain well-defined fields that keyword matching cannot model cleanly. `event` provides a named, composable signal for each class of event without forcing operators to write fragile regex keyword rules.

## When to Use

Use `event` when:

- requests contain machine-generated event payloads (error alerts, audit logs, transaction failures)
- you want to route by severity tier independently of event type
- domain-specific action codes (e.g. `TXN_DECLINE`, `AUTH_FAIL`) should deterministically select a model pool
- time-sensitive events need to bypass standard latency-tolerant queues

## Configuration

```yaml
routing:
  signals:
    events:
      - name: critical_payment_event
        description: Critical payment or transaction events that need incident-grade routing.
        event_types:
          - payment_failed
          - transaction_declined
        severities:
          - critical
          - high
        action_codes:
          - TXN_DECLINE
        temporal: true
```

### Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Rule name referenced in `routing.decisions[].rules` |
| `description` | string | Optional human-readable explanation of when the rule should match |
| `event_types` | list of strings | Event type patterns to match (case-insensitive word boundary) |
| `severities` | list of strings | Severity keywords: `critical`, `high`, `medium`, `low` |
| `action_codes` | list of strings | Domain-specific action codes (case-insensitive word boundary) |
| `temporal` | bool | When `true`, matches urgency markers: `urgent`, `immediate`, `asap`, `deadline`, `time-sensitive`, `now`, `critical.window` |

A rule matches when at least one configured criterion is satisfied. **Confidence** is `0.5 + 0.5 × (matched_criteria / total_criteria)`. With up to four criteria (`event_types`, `severities`, `action_codes`, `temporal`), a single-criterion match on a four-criterion rule yields `0.625`; a full match always yields `1.0`. A rule with only one configured criterion that matches also yields `1.0`.

## Example Decision

```yaml
routing:
  decisions:
    - name: route_critical_event
      rules:
        type: event
        name: critical_payment_event
      modelRefs:
        - model: fast-response-model
```
