iriq 0.0.1 → 0.1.0

data/lib/iriq/corpus.rb

@@ -0,0 +1,268 @@
+require "json"
+
+module Iriq
+  # Streaming-friendly observer over a (potentially unbounded) corpus of IRIs.
+  # Maintains rolling aggregates and per-(host, prefix) frequency stats so
+  # that classification can improve as more data flows in.
+  #
+  # The deterministic, single-IRI API (Iriq.normalize/explain) is unchanged —
+  # Corpus#normalize and Corpus#explain are the corpus-informed variants.
+  class Corpus
+    # Type-based: position is "mostly variable" (UUIDs/integers/etc.).
+    VARIABLE_DOMINANCE_THRESHOLD = 0.8
+
+    # Cardinality-based: position has mostly distinct literal values, so the
+    # literal "type" is misleading — it's really a variable slot. We trigger
+    # on either:
+    #   - very high cardinality fraction (most observations are singletons), OR
+    #   - moderate cardinality fraction AND high absolute distinct count
+    # The second branch catches realistic streams where popular outliers
+    # bring the frac down but the long tail is clearly variable.
+    LITERAL_UNIQUENESS_THRESHOLD          = 0.8
+    LITERAL_UNIQUENESS_MODERATE_THRESHOLD = 0.5
+    MIN_CARDINALITY_FOR_INFERENCE         = 20
+
+    # Don't apply corpus heuristics until we have at least this many
+    # observations at a position — too easy to be wrong with tiny samples.
+    MIN_OBSERVATIONS_FOR_INFERENCE = 5
+
+    # Value-fraction at or above which a literal is considered the stable
+    # occupant of its position.
+    STABLE_LITERAL_THRESHOLD = 0.5
+
+    # Within a high-cardinality literal position (mostly singletons), a
+    # specific value qualifies as a "popular outlier" — and gets preserved
+    # as :stable_literal instead of being lumped into :corpus_inferred_variable
+    # — when its count is at least POPULAR_MIN_COUNT and its frequency is at
+    # least POPULAR_BASELINE_MULTIPLE × the uniform baseline (1/cardinality).
+    POPULAR_MIN_COUNT         = 5
+    POPULAR_BASELINE_MULTIPLE = 3
+
+    attr_reader :host_counts, :path_length_counts, :raw_shape_counts,
+                :fingerprint_counts, :position_stats
+
+    def initialize(classifier: SegmentClassifier::DEFAULT,
+                   max_values_per_position: PositionStats::DEFAULT_MAX_VALUES)
+      @classifier              = classifier
+      @max_values_per_position = max_values_per_position
+      @host_counts             = Hash.new(0)
+      @path_length_counts      = Hash.new(0)
+      @raw_shape_counts        = Hash.new(0)
+      @fingerprint_counts      = Hash.new(0)
+      @position_stats          = {}
+      @clusterer               = Clusterer.new(classifier: classifier)
+    end
+
+    # Observe a single IRI. Returns an Observation.
+    def observe(input)
+      iri = coerce(input)
+      hinted_entries = SegmentHints.derive(iri.path_segments, @classifier)
+      record_aggregates(iri, hinted_entries)
+      hinted_shape = PathShape.new(classifier: @classifier, hints: true).from_entries(hinted_entries)
+      cluster = @clusterer.add(iri, shape: hinted_shape)
+      Observation.new(corpus: self, identifier: iri, cluster: cluster)
+    end
+
+    # Corpus-informed normalization. Falls back to mechanical normalization
+    # when the corpus has no signal for a position.
+    def normalize(input)
+      iri = coerce(input)
+      return Normalizer.normalize_identifier(iri) if iri.urn? || iri.path_segments.empty?
+
+      tokens = annotate_segments(iri).map { |entry| corpus_token(entry) }
+      out = +""
+      out << "#{iri.scheme}://" if iri.scheme
+      out << iri.host if iri.host
+      out << ":#{iri.port}" if iri.port
+      out << "/" << tokens.join("/")
+      out
+    end
+
+    # Per-segment explanation with corpus-informed `classification`.
+    # Returns an array of entries shaped like the Explanation rows plus
+    # `classification:` ∈ :stable_literal, :variable_identifier,
+    # :rare_literal, :ambiguous, :corpus_inferred_variable.
+    def explain(input)
+      iri = coerce(input)
+      annotate_segments(iri).map do |entry|
+        entry.reject { |k, _| k == :prefix }
+      end
+    end
+
+    def clusters
+      @clusterer.clusters
+    end
+
+    def size
+      @clusterer.size
+    end
+
+    # Stats for a given (host, prefix_shape) — useful for tests and
+    # debugging. Returns nil if nothing has been observed there.
+    def stats_for(host, prefix)
+      @position_stats[[host, prefix]]
+    end
+
+    private
+
+    def coerce(input)
+      input.is_a?(Identifier) ? input : Parser.parse(input)
+    end
+
+    def record_aggregates(iri, hinted_entries)
+      @host_counts[iri.host] += 1 if iri.host
+      @path_length_counts[iri.path_segments.size] += 1
+
+      raw = PathShape.new(classifier: @classifier, hints: false).from_entries(hinted_entries)
+      fp  = PathShape.new(classifier: @classifier, hints: true).from_entries(hinted_entries)
+      @raw_shape_counts[raw] += 1
+      @fingerprint_counts[fp] += 1
+
+      record_position_stats(iri, hinted_entries)
+    end
+
+    def record_position_stats(iri, hinted_entries)
+      prefix = ""
+      hinted_entries.each do |entry|
+        key   = [iri.host, prefix]
+        stats = @position_stats[key] ||= PositionStats.new(max_values: @max_values_per_position)
+        stats.observe(entry[:value], entry[:type])
+        prefix = "#{prefix}/#{placeholder(entry)}"
+      end
+    end
+
+    # Walks the IRI's segments and returns hint-derived entries enriched with
+    # the (host, prefix) PositionStats reference and a :classification symbol.
+    def annotate_segments(iri)
+      hinted = SegmentHints.derive(iri.path_segments, @classifier)
+      prefix = ""
+      hinted.map do |entry|
+        stats = @position_stats[[iri.host, prefix]]
+        out = entry.merge(
+          prefix:         prefix,
+          classification: classify(entry, stats),
+        )
+        prefix = "#{prefix}/#{placeholder(entry)}"
+        out
+      end
+    end
+
+    def placeholder(entry)
+      return entry[:value] unless entry[:variable]
+
+      "{#{entry[:hint] || entry[:type]}}"
+    end
+
+    def classify(entry, stats)
+      variable = entry[:variable]
+
+      return variable ? :variable_identifier : :ambiguous if stats.nil? || stats.total.zero?
+      return :variable_identifier if variable
+
+      value            = entry[:value]
+      total            = stats.total
+      variable_frac    = stats.variable_fraction(@classifier)
+      cardinality_frac = stats.cardinality.to_f / total
+      enough_data      = total >= MIN_OBSERVATIONS_FOR_INFERENCE
+      value_frac       = stats.value_fraction(value)
+
+      if enough_data && variable_frac >= VARIABLE_DOMINANCE_THRESHOLD
+        # Position is dominated by variable types (UUIDs, integers, etc.).
+        # A literal here is a special-case outlier (e.g. /users/me).
+        stats.value_counts.key?(value) ? :rare_literal : :ambiguous
+      elsif value_frac >= STABLE_LITERAL_THRESHOLD
+        # This specific value dominates — preserve it regardless of how
+        # diverse the rest of the position is.
+        :stable_literal
+      elsif enough_data && high_cardinality_literal_position?(stats, cardinality_frac)
+        # High-cardinality literal position — usually a variable slot, but
+        # recognize values that dramatically exceed the uniform baseline as
+        # "popular outliers" (e.g. /workspaces/mainspace surviving in a slot
+        # full of one-shot user-created workspace names).
+        popular_outlier?(stats, value) ? :stable_literal : :corpus_inferred_variable
+      elsif stats.cardinality == 1
+        :stable_literal
+      elsif stats.value_counts.key?(value)
+        :rare_literal
+      else
+        :ambiguous
+      end
+    end
+
+    def high_cardinality_literal_position?(stats, cardinality_frac)
+      return true if cardinality_frac >= LITERAL_UNIQUENESS_THRESHOLD
+
+      cardinality_frac >= LITERAL_UNIQUENESS_MODERATE_THRESHOLD &&
+        stats.cardinality >= MIN_CARDINALITY_FOR_INFERENCE
+    end
+
+    def popular_outlier?(stats, value)
+      count = stats.value_counts[value] || 0
+      return false if count < POPULAR_MIN_COUNT
+
+      baseline = 1.0 / stats.cardinality
+      stats.value_fraction(value) >= POPULAR_BASELINE_MULTIPLE * baseline
+    end
+
+    def corpus_token(entry)
+      case entry[:classification]
+      when :variable_identifier, :corpus_inferred_variable
+        placeholder_for_variable(entry)
+      else
+        entry[:value]
+      end
+    end
+
+    def placeholder_for_variable(entry)
+      return "{#{entry[:hint] || entry[:type]}}" if entry[:variable]
+
+      # corpus-inferred variable: classifier said literal, corpus says
+      # otherwise. Derive a hint from the prefix's last literal segment if
+      # we can.
+      last_literal = entry[:prefix].split("/").reject(&:empty?).reject { |s| s.start_with?("{") }.last
+      base = last_literal ? Inflector.singularize(last_literal) : nil
+      base ? "{#{base}}" : "{value}"
+    end
+
+    public
+
+    def dump
+      {
+        "host_counts"             => @host_counts,
+        "path_length_counts"      => @path_length_counts.transform_keys(&:to_s),
+        "raw_shape_counts"        => @raw_shape_counts,
+        "fingerprint_counts"      => @fingerprint_counts,
+        "max_values_per_position" => @max_values_per_position,
+        "position_stats"          => @position_stats.map { |(host, prefix), s| [host, prefix, s.dump] },
+        "clusterer"               => @clusterer.dump,
+      }
+    end
+
+    def save(path)
+      tmp = "#{path}.tmp"
+      File.write(tmp, JSON.generate(dump))
+      File.rename(tmp, path)
+    end
+
+    def self.from_dump(h, classifier: SegmentClassifier::DEFAULT)
+      c = new(
+        classifier: classifier,
+        max_values_per_position: h.fetch("max_values_per_position", PositionStats::DEFAULT_MAX_VALUES),
+      )
+      c.instance_variable_set(:@host_counts,        Hash.new(0).merge(h["host_counts"]))
+      c.instance_variable_set(:@path_length_counts, Hash.new(0).merge(h["path_length_counts"].transform_keys(&:to_i)))
+      c.instance_variable_set(:@raw_shape_counts,   Hash.new(0).merge(h["raw_shape_counts"]))
+      c.instance_variable_set(:@fingerprint_counts, Hash.new(0).merge(h["fingerprint_counts"]))
+      stats = h["position_stats"].each_with_object({}) do |(host, prefix, sdump), acc|
+        acc[[host, prefix]] = PositionStats.from_dump(sdump)
+      end
+      c.instance_variable_set(:@position_stats, stats)
+      c.instance_variable_set(:@clusterer, Clusterer.from_dump(h["clusterer"], classifier: classifier))
+      c
+    end
+
+    def self.load(path, classifier: SegmentClassifier::DEFAULT)
+      from_dump(JSON.parse(File.read(path)), classifier: classifier)
+    end
+  end
+end

data/lib/iriq/explanation.rb

@@ -3,43 +3,27 @@ module Iriq
   #
   #   Explanation.explain("https://foo.com/users/123")
   #   # => [
-  #   #      { value: "users", type: :literal,    variable: false },
-  #   #      { value: "123",   type: :integer_id, variable: true },
+  #   #      { value: "users", type: :literal,    variable: false, hint: nil       },
+  #   #      { value: "123",   type: :integer_id, variable: true,  hint: "user_id" },
   #   #    ]
   module Explanation
     module_function
 
-    def explain(input, classifier: SegmentClassifier.new)
+    def explain(input, classifier: SegmentClassifier::DEFAULT)
       iri = input.is_a?(Identifier) ? input : Parser.parse(input)
 
       if iri.urn?
         explain_urn(iri, classifier)
       else
-        iri.path_segments.map { |s| segment_entry(s, classifier) }
+        SegmentHints.derive(iri.path_segments, classifier)
       end
     end
 
-    def segment_entry(segment, classifier)
-      type = classifier.classify(segment)
-      {
-        value:    segment,
-        type:     type,
-        variable: classifier.variable?(type),
-      }
-    end
-
     def explain_urn(iri, classifier)
       return [] unless iri.nss
 
-      if iri.nss.include?(":")
-        ns, value = iri.nss.split(":", 2)
-        [
-          { value: ns, type: :literal, variable: false },
-          segment_entry(value, classifier),
-        ]
-      else
-        [segment_entry(iri.nss, classifier)]
-      end
+      parts = iri.nss.include?(":") ? iri.nss.split(":", 2) : [iri.nss]
+      SegmentHints.derive(parts, classifier)
     end
   end
 end

data/lib/iriq/extractor.rb

@@ -0,0 +1,125 @@
+module Iriq
+  # Pulls IRIs out of free text. Scheme-anchored — only URLs whose scheme
+  # appears explicitly are extracted (scheme-less hosts like "foo.com/x" are
+  # too noisy to disambiguate from prose).
+  #
+  #   Iriq::Extractor.new.extract("Visit https://foo.com today.")
+  #   # => [#<Iriq::Identifier https://foo.com>]
+  #
+  # Design draws on twitter-text and GFM autolink rules: scheme anchoring,
+  # iterative trailing-punct trim, balanced-paren preservation.
+  class Extractor
+    SCHEMES = %w[https http ftp wss ws].freeze
+
+    # Conservative TLD allow-list for scheme-less extraction. Limited to a
+    # small set of very common TLDs to keep false-positive rate low. A
+    # scheme-less candidate ALSO requires a `/path` to count, so plain
+    # `foo.com` in prose still won't match — only `foo.com/something`.
+    SCHEMELESS_TLDS = %w[com org net io ai dev co app gov edu].freeze
+
+    # Boundary chars — a URL ends at any of these (whitespace, angle
+    # brackets, quotes, backtick).
+    BOUNDARY = %r{[\s<>"'`]}.freeze
+
+    # Non-ASCII Unicode brackets and quotation marks that almost always
+    # terminate a URL in source text (e.g. `「URL」`). ASCII brackets are NOT
+    # listed here — those stay inside the URL match so the balanced-paren
+    # trim step can handle them (Wikipedia URLs like /Foo_(bar) survive).
+    NON_ASCII_BOUNDARY = (
+      "」』）】〉》〕〗〙〛｠｝］＞" +  # CJK closing brackets
+      "「『（【〈《〔〖〘〚｟｛［＜" +  # CJK opening brackets
+      "“”‘’„‟‚«»‹›"                 # Unicode quotation marks
+    ).chars.uniq.join.freeze
+
+    URL_CHAR_CLASS = %{[^\\s<>"'`,#{NON_ASCII_BOUNDARY}]+}.freeze
+
+    CANDIDATE_RE = %r{
+      (?<![\w/])                                                    # not mid-word, not mid-path
+      (?:
+        (?i:#{SCHEMES.join("|")})://#{URL_CHAR_CLASS}               # absolute URL
+        |
+        urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,30}:#{URL_CHAR_CLASS}        # urn:NID:NSS
+      )
+    }xu.freeze
+
+    # Scheme-less alternative — same chars allowed as the absolute URL but
+    # requires a host with an allow-listed TLD AND a `/path` to keep prose
+    # noise low. The host part allows ASCII labels separated by dots; no
+    # Unicode hosts (those are too easily confused with prose).
+    SCHEMELESS_ALT = %{(?:[a-zA-Z0-9](?:[a-zA-Z0-9\\-]{0,61}[a-zA-Z0-9])?\\.)+(?i:#{SCHEMELESS_TLDS.join("|")})/#{URL_CHAR_CLASS}}.freeze
+
+    # Single-scan combined pattern used when scheme_less is on. One regex
+    # over the text is meaningfully cheaper than two.
+    COMBINED_RE = %r{
+      (?<![\w/.@])
+      (?:
+        (?i:#{SCHEMES.join("|")})://#{URL_CHAR_CLASS}
+        |
+        urn:[a-zA-Z0-9][a-zA-Z0-9\-]{0,30}:#{URL_CHAR_CLASS}
+        |
+        #{SCHEMELESS_ALT}
+      )
+    }xu.freeze
+
+    # Punctuation that's almost always sentence punctuation rather than part
+    # of a URL when it appears at the trailing edge.
+    TRAILING_PUNCT_RE = /[.,;:!?'"‘’“”]+\z/u.freeze
+
+    # Unmatched closing brackets that should be trimmed.
+    BRACKET_PAIRS = { ")" => "(", "]" => "[", "}" => "{" }.freeze
+
+    def initialize(scheme_less: true)
+      @scheme_less = scheme_less
+    end
+
+    def extract(text)
+      return [] if text.nil? || text.empty?
+
+      candidates = scan_candidates(text)
+      candidates.filter_map do |candidate|
+        trimmed = trim(candidate)
+        next nil if trimmed.empty?
+
+        begin
+          Parser.parse(trimmed)
+        rescue ParseError
+          nil
+        end
+      end
+    end
+
+    # Same as extract but returns only canonical strings, deduplicated,
+    # preserving first-seen order.
+    def extract_strings(text)
+      seen = {}
+      extract(text).each { |iri| seen[iri.canonical] ||= true }
+      seen.keys
+    end
+
+    private
+
+    # One regex scan over the text — combined pattern when scheme-less is
+    # on, scheme-anchored only otherwise.
+    def scan_candidates(text)
+      pattern = @scheme_less ? COMBINED_RE : CANDIDATE_RE
+      text.scan(pattern)
+    end
+
+    # Iteratively strip sentence punctuation and unmatched closing brackets
+    # until the candidate stabilizes.
+    def trim(candidate)
+      s = candidate.dup
+      loop do
+        before = s
+        s = s.sub(TRAILING_PUNCT_RE, "")
+        BRACKET_PAIRS.each do |close, open|
+          while s.end_with?(close) && s.count(close) > s.count(open)
+            s = s[0...-1]
+          end
+        end
+        break if s == before
+      end
+      s
+    end
+  end
+end

data/lib/iriq/identifier.rb

@@ -43,9 +43,17 @@ module Iriq
         out << "#{scheme}://" if scheme
         out << host if host
         out << ":#{port}" if port
-        out << "/" + path_segments.join("/") if path_segments.any?
-        out << "?#{query}" if query && !query.empty?
-        out << "##{fragment}" if fragment && !fragment.empty?
+        has_query    = query && !query.empty?
+        has_fragment = fragment && !fragment.empty?
+        if path_segments.any?
+          out << "/" + path_segments.join("/")
+        elsif has_query || has_fragment
+          # RFC 3986: an authority with query/fragment but no path needs the
+          # implied "/" to be a valid URI.
+          out << "/"
+        end
+        out << "?#{query}"    if has_query
+        out << "##{fragment}" if has_fragment
         out
       end
     end

data/lib/iriq/inflector.rb

@@ -0,0 +1,145 @@
+require "set"
+
+module Iriq
+  # Singularization with a swappable adapter.
+  #
+  # By default uses ActiveSupport's inflector if it can be required, otherwise
+  # falls back to BuiltinAdapter. Override globally:
+  #
+  #   Iriq::Inflector.adapter = MyAdapter   # must respond to .singularize(String)
+  #
+  # And reset to default with `Iriq::Inflector.reset_adapter!`.
+  module Inflector
+    # Vocabulary is bounded in practice; cache + cap matches the
+    # SegmentClassifier strategy.
+    CACHE_MAX = 10_000
+
+    class << self
+      def singularize(word)
+        cache = (@cache ||= {})
+        cached = cache[word]
+        return cached if cached
+
+        cache.clear if cache.size >= CACHE_MAX
+        cache[word] = adapter.singularize(word)
+      end
+
+      def adapter
+        @adapter ||= default_adapter
+      end
+
+      def adapter=(value)
+        @adapter = value
+        @cache = {} # different adapter could singularize differently
+      end
+
+      def reset_adapter!
+        @adapter = nil
+        @cache = {}
+      end
+
+      def default_adapter
+        require "active_support/inflector"
+        ActiveSupportAdapter
+      rescue LoadError
+        BuiltinAdapter
+      end
+    end
+
+    module ActiveSupportAdapter
+      def self.singularize(word)
+        ::ActiveSupport::Inflector.singularize(word.to_s)
+      end
+    end
+
+    # Rule-based English singularizer. Rules are ordered most-specific-first
+    # and adapted from ActiveSupport's default inflections.
+    module BuiltinAdapter
+      IRREGULARS = {
+        "people"   => "person",
+        "children" => "child",
+        "men"      => "man",
+        "women"    => "woman",
+        "mice"     => "mouse",
+        "geese"    => "goose",
+        "oxen"     => "ox",
+        "feet"     => "foot",
+        "teeth"    => "tooth",
+        "lives"    => "life",
+        "wives"    => "wife",
+        "moves"    => "move",
+        "zombies"  => "zombie",
+        # latin/greek plurals that don't fit a clean suffix rule
+        "indices"  => "index",
+        "vertices" => "vertex",
+        # -f/-fe words where the stem doesn't end in l/r/i
+        "leaves"   => "leaf",
+        "calves"   => "calf",
+        "halves"   => "half",
+        "loaves"   => "loaf",
+        "hooves"   => "hoof",
+      }.freeze
+
+      UNCOUNTABLE = Set.new(%w[
+        news fish sheep deer series species equipment information
+        money rice jeans police data media
+      ]).freeze
+
+      # [pattern, replacement] — first match wins.
+      RULES = [
+        [/(quiz)zes$/i,                       '\1'],
+        [/(matri|appendi)ces$/i,              '\1x'],
+        [/(ox)en$/i,                          '\1'],
+        [/(alias|status)(es)?$/i,             '\1'],
+        [/(octop|vir)(us|i)$/i,               '\1us'],
+        [/(cris|ax|test)es$/i,                '\1is'],
+        [/(shoe)s$/i,                         '\1'],
+        [/(bus)(es)?$/i,                      '\1'],
+        [/([ml])ice$/i,                       '\1ouse'],
+        [/(x|ch|ss|sh)es$/i,                  '\1'],
+        [/(m)ovies$/i,                        '\1ovie'],
+        [/(s)eries$/i,                        '\1eries'],
+        [/([^aeiouy]|qu)ies$/i,               '\1y'],
+        [/([lr])ves$/i,                       '\1f'],
+        [/(tive)s$/i,                         '\1'],
+        [/(hive)s$/i,                         '\1'],
+        [/([^f])ves$/i,                       '\1fe'],
+        [/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i, '\1sis'],
+        [/([ti])a$/i,                         '\1um'],
+        [/(n)ews$/i,                          '\1ews'],
+        [/(o)es$/i,                           '\1'],
+        [/(ss)$/i,                            '\1'],
+        [/s$/i,                               ''],
+      ].freeze
+
+      def self.singularize(word)
+        return word if word.nil? || word.empty?
+
+        lower = word.downcase
+        return word if UNCOUNTABLE.include?(lower)
+
+        if (irr = IRREGULARS[lower])
+          return preserve_case(word, irr)
+        end
+
+        RULES.each do |pattern, replacement|
+          if word.match?(pattern)
+            return word.sub(pattern, replacement)
+          end
+        end
+
+        word
+      end
+
+      def self.preserve_case(original, lowered)
+        if original == original.upcase
+          lowered.upcase
+        elsif original[0] == original[0].upcase
+          lowered.sub(/\A./, &:upcase)
+        else
+          lowered
+        end
+      end
+    end
+  end
+end

data/lib/iriq/normalizer.rb

@@ -2,24 +2,27 @@ module Iriq
   # Produces a canonical, shape-aware string for an identifier.
   #
   #   Normalizer.normalize("https://Foo.com:443/users/123")
-  #   # => "https://foo.com/users/{integer_id}"
+  #   # => "https://foo.com/users/{user_id}"
   #
   # The form is intended for grouping/diffing — it is not a round-trippable URL.
   module Normalizer
     module_function
 
-    def normalize(input, classifier: SegmentClassifier.new)
+    def normalize(input, classifier: SegmentClassifier::DEFAULT, hints: true)
       iri = input.is_a?(Identifier) ? input : Parser.parse(input)
-      normalize_identifier(iri, classifier: classifier)
+      normalize_identifier(iri, classifier: classifier, hints: hints)
     end
 
-    def normalize_identifier(iri, classifier: SegmentClassifier.new)
+    def normalize_identifier(iri, classifier: SegmentClassifier::DEFAULT, hints: true)
       if iri.urn?
-        # urn:isbn:0451450523 -> urn:isbn:{integer_id}
         if iri.scheme == "urn" && iri.nss && iri.nss.include?(":")
           ns, value = iri.nss.split(":", 2)
-          type      = classifier.classify(value)
-          shaped    = classifier.variable?(type) ? "{#{type}}" : value
+          entry     = SegmentHints.derive([ns, value], classifier).last
+          shaped    = if entry[:variable]
+                        "{#{(hints && entry[:hint]) || entry[:type]}}"
+                      else
+                        entry[:value]
+                      end
           "urn:#{ns}:#{shaped}"
         else
           iri.canonical
@@ -29,7 +32,7 @@ module Iriq
         out << "#{iri.scheme}://" if iri.scheme
         out << iri.host if iri.host
         out << ":#{iri.port}" if iri.port
-        out << PathShape.new(classifier: classifier).for(iri.path_segments)
+        out << PathShape.new(classifier: classifier, hints: hints).for(iri.path_segments)
         if iri.query_params && !iri.query_params.empty?
           out << "?" + shape_query(iri.query_params, classifier)
         end

data/lib/iriq/observation.rb

@@ -0,0 +1,25 @@
+module Iriq
+  # The result of Corpus#observe. Lightweight value object — heavy work
+  # (explanation, normalization) is deferred until you ask.
+  class Observation
+    attr_reader :identifier, :cluster
+
+    def initialize(corpus:, identifier:, cluster:)
+      @corpus     = corpus
+      @identifier = identifier
+      @cluster    = cluster
+    end
+
+    def fingerprint
+      @fingerprint ||= Normalizer.normalize_identifier(@identifier)
+    end
+
+    def explanation
+      @explanation ||= @corpus.explain(@identifier)
+    end
+
+    def normalize
+      @corpus.normalize(@identifier)
+    end
+  end
+end