insika 0.2.0 → 0.3.0

data/lib/insika/distill.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # the one place distillation asks a model for anything.
+  #
+  # The engine's generic prompt (what a durable customer fact is, the shape of
+  # the answer, and the "never invent, never guess a scope" rules). A pack
+  # `distill.prompt` REPLACES this wholesale (the forge's half) — the engine
+  # never writes store vocabulary.
+  module Distill
+    DEFAULT_PROMPT = <<~PROMPT.freeze
+      You are distilling durable facts about ONE customer from a finished
+      conversation, for a shop assistant's memory. A fact is something that
+      stays true across conversations: a size, a preference, a situation, an
+      address. It is NOT the conversation itself, not a summary, and not a
+      question.
+
+      Answer with a single JSON array and NOTHING else. No prose, no fences.
+
+      Rules:
+      - Each element is an object with "name" (the fact's key, short, lowercase,
+        underscore-separated), "value" (the fact's content, plain text), an
+        optional "confidence" (a number between 0 and 1) and an optional "turns"
+        (the message indexes in the transcript that support the fact).
+      - Never invent: only facts the conversation actually supports.
+      - Never guess a scope: you are not told any customer id or tenant — do not
+        include one, the engine stamps it.
+      - Fewer, better facts beat filling a quota.
+    PROMPT
+
+    # The SAFE-subset JSON Schema (object/array/string/number/integer + required
+    # + items — workflow.rb:77's subset). The validator is permissive on unknown
+    # keys, so the Distiller itself rejects a proposal carrying any key OUTSIDE
+    # this set (D1 — a model-authored `scope` is a cross-tenant escape) and
+    # counts the drop.
+    PROPOSAL_SCHEMA = Insika::Workflow::Schema.coerce({
+      "type" => "array",
+      "items" => {
+        "type" => "object",
+        "properties" => {
+          "name" => { "type" => "string" },
+          "value" => { "type" => "string" },
+          "confidence" => { "type" => "number" },
+          "turns" => { "type" => "array", "items" => { "type" => "integer" } }
+        },
+        "required" => ["name", "value"]
+      }
+    })
+
+    # The per-PROPOSAL half (an item of PROPOSAL_SCHEMA) — the Distiller
+    # validates each element against THIS, not the whole-answer schema.
+    ITEM_SCHEMA = Insika::Workflow::Schema.coerce(PROPOSAL_SCHEMA.json_schema["items"])
+
+    # The model's answer, filtered into data the command then dedups and a human
+    # then gates. Pure over an injected `ask` — the Refinement::Proposer shape:
+    # unit-testable without a provider, and the real ask is a lambda built by
+    # DistillerFactory (ruby_llm required lazily, load_guard stays green).
+    class Distiller
+      # A model that answers with prose instead of JSON produces NOTHING,
+      # loudly — empty output must not read as "the traffic is clean".
+      class Unusable < Insika::ValidationError; end
+
+      MAX_NAME_LENGTH = 120
+      MAX_VALUE_LENGTH = 500
+      MAX_TURNS = 20
+      ALLOWED_KEYS = %w[name value confidence turns].freeze
+      # The E4 audit counters: schema (shape/type/confidence range), unknown_key
+      # (a model-authored key — the D1 escape), oversized (length caps),
+      # bad_turns (evidence indexes), duplicate (exact repeats), capped (a
+      # survivor over max_proposals).
+      DROP_KEYS = %w[schema unknown_key oversized bad_turns duplicate capped].freeze
+
+      # ask:   ->(prompt) { "<raw model text>" } | something answering #content
+      #        (+ #input_tokens/#output_tokens/#cached_tokens for cost).
+      # model: the ref recorded in the events ("utility_model" default).
+      attr_reader :model
+
+      def initialize(ask:, model: "utility_model")
+        @ask = ask
+        @model = model.to_s
+      end
+
+      # -> { proposals: [{ "name", "value", "confidence"?, "turns"? }],
+      #      dropped: { "schema" => N, "unknown_key" => N, "oversized" => N,
+      #                 "bad_turns" => N, "duplicate" => N },
+      #      cost: { "spent" => N, "cached" => N } | nil }
+      # prompt: the pack prompt or DEFAULT_PROMPT (the caller resolved it).
+      # message_count: the session transcript size — turns are validated
+      #   against it (an index >= message_count drops the proposal).
+      # max_proposals: cap on surviving proposals (the model may return more).
+      # Drops are counted, never fixed up.
+      def distill(prompt:, message_count:, max_proposals: 10)
+        answer = @ask.call(prompt)
+        raw = parse(text_of(answer))
+        proposals = []
+        dropped = DROP_KEYS.to_h { |k| [k, 0] }
+        seen = {}
+        raw.each do |item|
+          verdict, reason = classify(item, message_count)
+          case verdict
+          when :keep
+            tuple = [item["name"].to_s, item["value"].to_s]
+            if seen[tuple]
+              dropped["duplicate"] += 1
+            elsif proposals.size >= max_proposals
+              dropped["capped"] += 1
+            else
+              seen[tuple] = true
+              proposals << normalize(item)
+            end
+          when :drop
+            dropped[reason] += 1
+          end
+        end
+        { proposals: proposals, dropped: dropped, cost: cost_of(answer) }
+      end
+
+      private
+
+      def text_of(answer) = (answer.respond_to?(:content) ? answer.content : answer).to_s
+
+      # nil when the provider said nothing — never 0 (the Proposer's
+      # discipline). The cached prefix is INCLUDED in the spent total.
+      def cost_of(answer)
+        return nil unless answer.respond_to?(:input_tokens) && answer.respond_to?(:output_tokens)
+
+        input = answer.input_tokens.to_i
+        output = answer.output_tokens.to_i
+        cached = answer.respond_to?(:cached_tokens) ? answer.cached_tokens.to_i : 0
+        spent = input + output + cached
+        spent.positive? ? { "spent" => spent, "cached" => cached } : nil
+      end
+
+      # Fences are stripped, the payload parsed STRICTLY: a model that
+      # improvises a schema fails here instead of producing half a proposal.
+      def parse(raw)
+        body = raw.strip.gsub(/\A```(?:json)?\s*|\s*```\z/, "")
+        parsed = JSON.parse(body)
+        raise Unusable, "the distiller's answer is not an array" unless parsed.is_a?(Array)
+
+        parsed
+      rescue JSON::ParserError => e
+        raise Unusable, "the distiller's answer is not valid JSON: #{e.message}"
+      end
+
+      # -> [:keep, nil] | [:drop, drop_key]. The order is the safety order:
+      # unknown keys first (D1 — a model-authored scope is a cross-tenant
+      # escape), then the turns bounds, then the schema, then the length and
+      # confidence bounds. Turns are checked before the schema so a
+      # non-integer / out-of-bounds index counts as bad_turns, never as a
+      # generic schema miss.
+      def classify(item, message_count)
+        # a non-Hash element is a shape violation, never an "unknown key"
+        return [:drop, "schema"] unless item.is_a?(Hash)
+        return [:drop, "unknown_key"] unless (item.keys.map(&:to_s) - ALLOWED_KEYS).empty?
+
+        turns = item["turns"]
+        if turns
+          return [:drop, "bad_turns"] if !turns.is_a?(Array) || turns.size > MAX_TURNS
+          return [:drop, "bad_turns"] if turns.any? { |t| !t.is_a?(Integer) || t.negative? || t >= message_count }
+        end
+
+        unless ITEM_SCHEMA.call(item).success?
+          return [:drop, "schema"]
+        end
+
+        name = item["name"].to_s
+        value = item["value"].to_s
+        return [:drop, "oversized"] if name.length > MAX_NAME_LENGTH || value.length > MAX_VALUE_LENGTH
+
+        confidence = item["confidence"]
+        if !confidence.nil? && (!confidence.is_a?(Numeric) || confidence.negative? || confidence > 1)
+          return [:drop, "schema"]
+        end
+
+        [:keep, nil]
+      end
+
+      # The SAFE subset only — anything the model smuggled in extra keys
+      # already dropped with the proposal.
+      def normalize(item)
+        item.slice("name", "value", "confidence", "turns")
+      end
+    end
+
+    # Resolves WHICH model distills, and builds the ask. Profile -> platform
+    # utility_model -> nil (D4 — nil means "feature inert", never a guess).
+    # `ask_factory`/`llm` injectable (specs).
+    module DistillerFactory
+      module_function
+
+      # config: the agent's `distill` hash. -> Distiller | nil
+      def build(config, utility_model: nil, ask_factory: nil, llm: nil)
+        ref = Coercion.presence(config && config["model"]) || Coercion.presence(utility_model)
+        return nil if ref.nil?
+
+        provider, model = split_ref(ref)
+        factory = ask_factory || ->(m, p) { ruby_llm_ask(m, p, llm: llm) }
+        Distiller.new(ask: factory.call(model, provider), model: ref)
+      end
+
+      # "provider/model" -> [provider, model]; "model" -> [nil, model] — the
+      # ProposerFactory reading, one syntax for "which model" across features.
+      def split_ref(ref)
+        prov, name = ref.to_s.split("/", 2)
+        name ? [prov, name] : [nil, prov]
+      end
+
+      # Temperature 0: a rejected fact must be re-proposable deterministically.
+      # `ruby_llm` is required lazily so nothing loads a provider gem until a
+      # distiller is actually configured (load_guard stays green).
+      def ruby_llm_ask(model, provider, llm: nil)
+        require "ruby_llm"
+        llm ||= RubyLLM
+        lambda do |prompt|
+          llm.chat(model: model, provider: provider, assume_model_exists: true)
+             .with_temperature(0).ask(prompt)
+        end
+      end
+    end
+  end
+end

data/lib/insika/distill_engine.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # the trigger — finds due sessions and distills them. It
+  # spawns a worker fiber (supervisor child, `Tick#start` shape) whose loop
+  # claims a window and runs the distillation for due sessions ON the worker
+  # fiber — off the tick's critical path and off every customer turn's path.
+  # The scan uses the engine default `idle_hours` (6) as the LOWER BOUND; the
+  # per-agent value is re-checked inside RunDistillation (a pack that wants
+  # 12 h is never distilled at 6).
+  #
+  # D2 — no queue: the per-session marker is the claim. A crash mid-pass
+  # leaves markers unwritten and the next boot re-scans; the dedup ledger
+  # filters duplicates. Two workers racing the same session both run, and the
+  # ledger still filters.
+  class DistillEngine
+    SCOPE = "distill"
+    KEY = "claim"
+    DEFAULT_WINDOW = 300 # seconds — the O(n) scan never rides the 60 s loop
+    DEFAULT_IDLE_HOURS = 6
+    DEFAULT_MIN_MESSAGES = 3
+
+    def initialize(store:, proposal_store:, session_store:, runner:, profiles: nil,
+                   logger: nil, window: DEFAULT_WINDOW,
+                   idle_hours: DEFAULT_IDLE_HOURS, sleeper: nil)
+      @store = store
+      @proposal_store = proposal_store
+      @session_store = session_store
+      @runner = runner
+      @profiles = profiles # profile source; nil/empty = nothing distills (parity)
+      @logger = logger
+      @window = window.to_i
+      @idle_hours = idle_hours.to_i
+      @sleeper = sleeper || method(:default_sleep)
+    end
+
+    # The supervisor child (tick.rb:69-83's shape): loop { sleeper(window);
+    # run_once rescue log }. Returns false when idle_hours <= 0 (the engine
+    # default OFF switch — parity) OR when no profile declares a distillation
+    # (a scan with nothing to distill would re-read every session record every
+    # window forever — each pass skips at the command, writes no marker, and
+    # repeats).
+    def start(parent:)
+      return false unless distillable?
+      return true if @task&.running?
+
+      @task = parent.async do |t|
+        t.annotate("insika-distill")
+        loop do
+          @sleeper.call(@window)
+          run_once
+        rescue StandardError => e
+          log(:warn, "distill pass failed: #{e.class}: #{e.message}")
+        end
+      end
+      true
+    end
+
+    # One pass. -> { claimed: false } | { claimed: true, distilled: N,
+    #   skipped: N, errors: N }
+    def run_once
+      return { claimed: false } unless distillable?
+      return { claimed: false } unless claim_window
+
+      distilled = 0
+      skipped = 0
+      errors = 0
+      due_sessions.each do |session|
+        begin
+          outcome = @runner.call(Insika::Command.build(:run_distillation,
+                                                       { session_id: session.id }))
+          if outcome[:distilled]
+            distilled += 1
+          else
+            skipped += 1
+          end
+        rescue StandardError
+          # a broken session must not hold the pass; the marker discipline
+          # keeps it re-runnable.
+          errors += 1
+        end
+      end
+      { claimed: true, distilled: distilled, skipped: skipped, errors: errors }
+    end
+
+    private
+
+    # The engine is inert unless the switch is on (idle_hours > 0) AND at
+    # least one profile declares an enabled distillation — without one, a pass
+    # would re-read every session record every window forever (each due
+    # session skips at the command, writes no marker, and repeats).
+    def distillable?
+      return false if @idle_hours <= 0
+      return false if @profiles.nil?
+
+      profiles_list.any? do |p|
+        config = p.respond_to?(:distill) ? p.distill : nil
+        config && Coercion.truthy?(config["enabled"])
+      end
+    end
+
+    def profiles_list
+      return @profiles.values if @profiles.respond_to?(:values)
+
+      @profiles.respond_to?(:all) ? @profiles.all : []
+    end
+
+    # Sessions whose `vars["customer"]` and `vars["agent"]` are present, older
+    # than the engine default idle window, with enough messages, and not yet
+    # distilled. Oldest first.
+    def due_sessions
+      cutoff = Time.now.utc - @idle_hours * 3600
+      ids = []
+      @session_store.each_id do |id|
+        session = @session_store.find(id)
+        next unless session
+        next if Coercion.blank?(session.vars["customer"])
+        next if Coercion.blank?(session.vars["agent"])
+        next unless aged?(session.updated_at, cutoff)
+        next if session.messages.size < DEFAULT_MIN_MESSAGES
+        next if @proposal_store.distilled?(id)
+
+        ids << session
+      end
+      ids.sort_by { |s| s.updated_at.to_s }
+    end
+
+    def aged?(updated_at, cutoff)
+      return false if Coercion.blank?(updated_at)
+
+      Time.iso8601(updated_at.to_s) <= cutoff
+    rescue ArgumentError
+      false
+    end
+
+    # One worker per window across N workers — the tick's claim idiom
+    # (one key, a timestamp, a window).
+    def claim_window
+      now = Time.now.utc
+      @store.transaction do
+        current = @store.get(SCOPE, KEY)
+        last = current && begin
+          Time.iso8601(current["claimed_at"].to_s)
+        rescue ArgumentError
+          nil # a corrupted claim is not a claim — take the window
+        end
+        if last.nil? || (now - last) >= @window
+          @store.set(SCOPE, KEY, { "claimed_at" => now.iso8601 })
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def default_sleep(seconds)
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      task ? task.sleep(seconds) : sleep(seconds)
+    end
+
+    def log(level, message)
+      @logger&.public_send(level, "[distill] #{message}")
+    rescue StandardError
+      nil
+    end
+  end
+end