signals

signals

Signal dataclass

Signal(*, pattern: str, weight: int = 1, flags: int = 0)

A regex-based signal pattern used in the scoring pipeline.

Signals are matched against transcript text via re.search. Each match contributes weight to the cumulative score. Use negative weights to suppress false positives.

Example

Signal(pattern=r"retry", weight=2, flags=re.IGNORECASE)

Signals dataclass

Signals(
    patterns: Sequence[Signal | NlpSignal],
    threshold: int,
    window: int = 15,
)

Bundle of signal patterns with a scoring threshold.

When a bare list[Signal] is passed to a primitive, resolve_signals wraps it with threshold=1 — meaning any single signal match triggers. Pass a higher threshold to require multiple signals to fire together.

transcript_texts

transcript_texts(
    evt: BaseHookEvent, window: int
) -> list[str]

Extract text from recent transcript messages for signal scoring.

For UserPromptSubmit events, returns just the user prompt. Otherwise returns .text from the last window messages.

cite_message

cite_message(
    sig: Signals, triggering: list[str], message: str
) -> str

Append trigger context to a message when signal matches are found.

resolve_signals

resolve_signals(
    signals: Sequence[Signal | NlpSignal] | Signals | None,
) -> Signals | None

Normalize signals input into a Signals bundle, or None.

A bare list[Signal] is wrapped with threshold=1 (any single match triggers).