Module: Iriq::Evidence

Defined in:
lib/iriq/evidence.rb

Overview

Evidence is the structured substrate for explanation. Each Record captures one fact about the system’s reasoning: “this segment classified as :integer because the Integer recognizer fired with specificity TYPED”, “the IPv4 type collapses to ip by policy”, “Position P is mostly variable because of corpus stats”.

Trace and Explanation are views over a list of Evidence records; the structured form is what programmatic consumers (test assertions, PR-diff annotators, downstream tooling) should build on. Human note strings emitted by Trace are derived from Evidence payloads, so adding a new note kind starts with adding a new Evidence shape.

Two axes:

subject_kind ∈ {:segment, :position, :cluster}
  What this Evidence is about. Today most Evidence is :segment
  (per-segment classification facts). :position and :cluster
  Evidence become load-bearing once corpus-informed Trace lands
  in a follow-up step.

source ∈ {:lexical, :recognizer, :corpus, :neighbor, :policy}
  What kind of fact is being asserted.
    :lexical    — pure shape match (e.g. "matches DATE_RE")
    :recognizer — a named Recognizer fired with confidence/specificity
    :corpus     — aggregated counts/distributions support this
    :neighbor   — adjacent context informed this (prior literal,
                  param name hint)
    :policy     — a normalization policy applied (ip umbrella
                  collapse, canonical date, currency upcase)

Defined Under Namespace

Classes: Record

Constant Summary collapse

SUBJECT_KINDS = 
%i[segment position cluster].freeze
SOURCES = 
%i[lexical recognizer corpus neighbor policy].freeze

Class Method Summary collapse

Class Method Details

.cluster(key:, source:, payload:, weight: nil, notes: []) ⇒ Object 



106
107
108
109
110
111
112
 
# File 'lib/iriq/evidence.rb', line 106

def cluster(key:, source:, payload:, weight: nil, notes: [])
  Record.new(
    subject_kind: :cluster,
    subject:      key,
    source:       source, payload: payload, weight: weight, notes: notes,
  )
end

.position(position:, source:, payload:, weight: nil, notes: []) ⇒ Object 



98
99
100
101
102
103
104
 
# File 'lib/iriq/evidence.rb', line 98

def position(position:, source:, payload:, weight: nil, notes: [])
  Record.new(
    subject_kind: :position,
    subject:      position,
    source:       source, payload: payload, weight: weight, notes: notes,
  )
end

.segment(index:, value:, source:, payload:, weight: nil, notes: []) ⇒ Object

Factories so call sites don’t have to repeat subject_kind:.



90
91
92
93
94
95
96
 
# File 'lib/iriq/evidence.rb', line 90

def segment(index:, value:, source:, payload:, weight: nil, notes: [])
  Record.new(
    subject_kind: :segment,
    subject:      { index: index, value: value },
    source:       source, payload: payload, weight: weight, notes: notes,
  )
end