insika 0.3.0 → 0.8.0

data/lib/insika/context/providers/session.rb

@@ -14,8 +14,8 @@ module Insika
         end
 
         def call(request)
-          messages = transcript_for(request)
-          return [] if messages.nil? || messages.empty?
+          messages, compaction = transcript_for(request)
+          return [] if messages.nil? || (messages.empty? && compaction.nil?)
 
           # A3/C3 opt-in: identical tool results in the transcript collapse to a
           # back-reference (the cheap half of compaction). CHANGES WHAT THE MODEL
@@ -28,7 +28,7 @@ module Insika
           # the fragment level means the budget cut (apply_budget) drops a whole
           # tool cycle atomically — a tool_use is NEVER seeded without its result
           # (which providers reject), without touching apply_budget itself.
-          eviction_units(messages).each_with_index.map do |unit, idx|
+          fragments = eviction_units(messages).each_with_index.map do |unit, idx|
             ContextFragment.build(
               # single message stays a Hash (compat with existing fragments); a
               # multi-message cycle is an Array (seed_history flattens it back).
@@ -39,6 +39,7 @@ module Insika
               source: id
             )
           end
+          compaction ? [compaction_fragment(compaction)] + fragments : fragments
         end
 
         private
@@ -90,15 +91,50 @@ module Insika
         end
 
         # Precedence: checkpoint -> explicit history -> store.
-        # The first present source wins; no merge.
+        # The first present source wins; no merge. -> [messages, compaction|nil].
+        # The compaction state (RFC-0044) applies to the STORE source only: a
+        # checkpoint resume replays the checkpoint's own tape (which already
+        # contains whatever summary the original turn saw) and an explicit
+        # vars[:history] is the caller's contract — neither is rewritten.
         def transcript_for(request)
-          return request.checkpoint.messages if request.checkpoint
+          return [request.checkpoint.messages, nil] if request.checkpoint
 
           explicit = explicit_history(request)
-          return explicit if explicit
-          return session_messages(request.session) if request.session
+          return [explicit, nil] if explicit
+          return compacted_session_messages(request.session) if request.session
 
-          nil
+          [nil, nil]
+        end
+
+        # Splits the stored transcript at the persisted compaction boundary:
+        # messages[0...upto] are represented by the summary, messages[upto..]
+        # stay verbatim. `upto` is clamped to the transcript size (defensive —
+        # the store is append-only, so it should never outrun it).
+        def compacted_session_messages(session)
+          fresh = fresh_session(session)
+          return [[], nil] if fresh.nil?
+
+          messages = fresh.messages || []
+          state = fresh.respond_to?(:compaction) ? fresh.compaction : nil
+          upto = state ? state["upto"].to_i : 0
+          return [messages, nil] unless upto.positive? && Coercion.present?(state["summary"])
+
+          [messages.drop([upto, messages.size].min), state]
+        end
+
+        # The compacted prefix as ONE history fragment, rendered FIRST (the
+        # Builder keeps history in production order). role "user" because it is
+        # provider-agnostic (a mid-history "system" message is not). Priority
+        # COMPACTION (59): the "oldest unit" — under budget it drops before any
+        # verbatim message. source "compaction" -> its own context-trace category.
+        def compaction_fragment(state)
+          ContextFragment.build(
+            content: { role: "user",
+                       content: "<conversation_summary>\n#{state['summary']}\n</conversation_summary>" },
+            placement: :history,
+            priority: Context::Priority::COMPACTION,
+            source: "compaction"
+          )
         end
 
         # Source 2 (explicit history): the handler passes it in request.vars[:history].
@@ -111,8 +147,8 @@ module Insika
         # CONDITIONAL requiredness: when a session is requested, a read
         # failure becomes a ContextError (aborts the turn); the base required?
         # does not receive the request, so the behavior lives here.
-        def session_messages(session)
-          @session_store.find(session.id)&.messages || []
+        def fresh_session(session)
+          @session_store.find(session.id)
         rescue StandardError => e # read failure (exception/StoreError)
           raise ContextError.new("Session provider failed with a requested session: #{e.message}",
                                  provider: id)

data/lib/insika/context_trace_store.rb

@@ -80,10 +80,20 @@ module Insika
         "tools" => { "count" => int(tools[:count] || tools["count"]),
                      "tokens" => int(tools[:tokens] || tools["tokens"]) },
         "fingerprints" => fingerprints_of(e[:fingerprints] || e["fingerprints"]),
-        "cache" => cache_of(e[:cache] || e["cache"])
+        "cache" => cache_of(e[:cache] || e["cache"]),
+        "compaction" => compaction_of(e[:compaction] || e["compaction"])
       }.compact
     end
 
+    # { upto, runs } — present only when the session was compacted (RFC-0044).
+    # Counts only, like everything else here; the summary text never lands.
+    def compaction_of(raw)
+      return nil unless raw.is_a?(Hash)
+
+      { "upto" => int(raw[:upto] || raw["upto"]),
+        "runs" => int(raw[:runs] || raw["runs"]) }
+    end
+
     # { name => sha256-hex }; names stringified, non-strings
     # dropped. Absent when the caller passed nothing (a trace recorded before
     # this feature has no key and the view guards on nil).

data/lib/insika/cron.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Insika
+  # A cron expression, parsed. The engine's documented subset:
+  #
+  #   minute hour day-of-month month day-of-week     (5 fields, whitespace-separated)
+  #
+  # Per field: `*`, a single value, a range (N-M), a step (`*/N`, `N-M/N`,
+  # `N/N`), or a comma list of those. `?` and `*` both mean "any". `L`, `W`,
+  # `#` and month/day NAMES are NOT — the engine refuses them loudly at
+  # creation, never silently dropping a cron that only some dates understand.
+  #
+  # Day-of-week: 0-7, 7 == 0 (Sunday). When BOTH day fields are restricted, a
+  # date matches on EITHER (standard cron OR semantics).
+  #
+  # `next_after(time)` returns the first occurrence STRICTLY after `time`,
+  # materialized in the schedule's tz (returned as a UTC Time), or nil when
+  # the expression can never fire within 400 years (`0 0 31 2 *`). The bound
+  # keeps a syntactic-but-unreachable expression from hanging a pass.
+  class Cron
+    MONTHS_31 = [1, 3, 5, 7, 8, 10, 12].freeze
+
+    # One field: the sorted accepted values + whether it was a bare "*"
+    # (the day-of-week OR rule needs to know which fields are restricted).
+    class Field
+      def initialize(expression, range, field:)
+        @field = field
+        @range = range
+        @star = expression == "*"
+        @values = expression.split(",").flat_map { |term| parse_term(term) }.uniq.sort
+      end
+
+      def star? = @star
+
+      def matches?(value) = @values.include?(value)
+
+      # -> Integer | nil: the smallest accepted value >= start (nil when none).
+      def at_or_after(start) = @values.find { |v| v >= start }
+
+      private
+
+      def parse_term(term)
+        head, step = term.include?("/") ? term.split("/", 2) : [term, nil]
+        step = parse_step(step) if step
+        base = parse_base(head)
+        base = base.each_with_index.filter_map { |v, i| v if (i % step).zero? } if step
+        base.each { |v| validate(v) }
+      end
+
+      def parse_step(raw)
+        n = Integer(raw)
+        raise Insika::ValidationError, "cron #{@field} step must be a positive integer, got #{raw.inspect}" unless n.positive?
+
+        n
+      rescue ArgumentError
+        raise Insika::ValidationError,
+              "cron #{@field} step must be a positive integer, got #{raw.inspect}"
+      end
+
+      def parse_base(head)
+        if head.empty? || head == "?" || head == "*"
+          @range.to_a
+        elsif head.include?("-")
+          lo, hi = head.split("-", 2).map { |s| value(s) }
+          raise Insika::ValidationError, "cron #{@field} range reversed: #{head.inspect}" if lo > hi
+
+          (lo..hi).to_a
+        else
+          [value(head)]
+        end
+      end
+
+      def value(raw)
+        v = Integer(raw)
+        v = 0 if @field == :dow && v == 7 # Sunday, the standard second spelling
+        v
+      rescue ArgumentError
+        raise Insika::ValidationError,
+              "cron #{@field} has an unparseable value: #{raw.inspect}"
+      end
+
+      def validate(v)
+        return if @range.cover?(v)
+
+        raise Insika::ValidationError,
+              "cron #{@field} value #{v} out of range (#{@range.inspect})"
+      end
+    end
+
+    attr_reader :expression
+
+    def initialize(expression)
+      @expression = expression.to_s.strip
+      fields = @expression.split(/\s+/)
+      if fields.size != 5
+        raise Insika::ValidationError,
+              "cron expression must have 5 fields (minute hour dom month dow), " \
+              "got #{fields.size}: #{@expression.inspect}"
+      end
+
+      minute, hour, dom, month, dow = fields
+      @minute = Field.new(minute, 0..59, field: :minute)
+      @hour = Field.new(hour, 0..23, field: :hour)
+      @dom = Field.new(dom, 1..31, field: :dom)
+      @month = Field.new(month, 1..12, field: :month)
+      @dow = Field.new(dow, 0..6, field: :dow)
+      freeze
+    end
+
+    # -> Time (UTC) | nil: the first instant strictly after `time` whose
+    # wall-clock in `tz` matches. nil = the expression cannot fire within 400y.
+    def next_after(time, tz: "Etc/UTC")
+      Timezone.in_zone(tz, time) do
+        local = time.getlocal
+        cur = Cursor.new(local.year, local.month, local.day, local.hour, local.min)
+        advance_minute!(cur) # strictly after `time`
+        limit = cur.y + 400
+        while cur.y <= limit
+          if @month.matches?(cur.mo) && day_match?(cur)
+            if @hour.matches?(cur.h) && (mm = @minute.at_or_after(cur.mi))
+              return Time.local(cur.y, cur.mo, cur.d, cur.h, mm)
+            end
+
+            nh = @hour.at_or_after(cur.h + 1)
+            if nh && (mm = @minute.at_or_after(0))
+              return Time.local(cur.y, cur.mo, cur.d, nh, mm)
+            end
+          end
+          advance_day!(cur)
+          cur.h = 0
+          cur.mi = 0
+        end
+        nil
+      end
+    end
+
+    private
+
+    # A date matches when a restricted day-of-month OR day-of-week accepts it
+    # (standard cron); a bare "*" on one side drops that side.
+    def day_match?(cur)
+      dom = @dom.matches?(cur.d)
+      dow = @dow.matches?(Time.utc(cur.y, cur.mo, cur.d).wday)
+      if @dom.star? && @dow.star?
+        true
+      elsif @dom.star?
+        dow
+      elsif @dow.star?
+        dom
+      else
+        dom || dow
+      end
+    end
+
+    Cursor = Struct.new(:y, :mo, :d, :h, :mi)
+
+    def advance_minute!(cur)
+      cur.mi += 1
+      if cur.mi > 59
+        cur.mi = 0
+        cur.h += 1
+        advance_day!(cur) if cur.h > 23
+      end
+    end
+
+    def advance_day!(cur)
+      cur.d += 1
+      return if cur.d <= days_in_month(cur.y, cur.mo)
+
+      cur.d = 1
+      cur.mo += 1
+      if cur.mo > 12
+        cur.mo = 1
+        cur.y += 1
+      end
+    end
+
+    def days_in_month(y, mo)
+      return 29 if mo == 2 && leap?(y)
+      return 28 if mo == 2
+
+      MONTHS_31.include?(mo) ? 31 : 30
+    end
+
+    def leap?(y)
+      y % 4 == 0 && (y % 100 != 0 || y % 400 == 0)
+    end
+  end
+end

data/lib/insika/demo/agent_attrs.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Insika
+  module Demo
+    # The one agent the demo seed provisions: a fictional e-commerce
+    # support agent that declares BOTH a funnel and a follow-up policy, which
+    # nothing shipped in examples/ does (Funnel/Followups render an empty state
+    # without a declaring profile — see AgentProfile#funnel/#followup). Model
+    # is deliberately nil: a demo about seeded DATA needs no live LLM
+    # credentials to be useful, and AgentProfile.build resolves a missing
+    # model against the platform default at turn time (never at seed time).
+    AGENT_ID = "demo-store"
+
+    AGENT_ATTRS = {
+      id: AGENT_ID,
+      base_prompt: <<~PROMPT.strip,
+        You are the support agent for Demo Shop, a fictional online store used
+        to explore the Insika Studio. Help customers find products, track
+        orders and answer questions about shipping and returns.
+      PROMPT
+      memory: true,
+      metadata: { "demo" => true },
+      funnel: {
+        "stages" => %w[greeted browsing cart_started checkout_started purchased],
+        "advance_on" => {
+          "greeted" => "greeted", "browsing" => "browsing",
+          "cart_started" => "cart_started", "checkout_started" => "checkout_started",
+          "purchased" => "purchased"
+        },
+        "primary" => "purchased",
+        "attribution_window" => "72h"
+      },
+      followup: {
+        "arm" => "nudge",
+        "policy" => {
+          "max_frequency" => "2/24h",
+          "cancel_keywords" => ["stop contacting me"],
+          "silence_after_sends" => 3
+        }
+      }
+    }.freeze
+  end
+end

data/lib/insika/demo/golden_cases.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Insika
+  module Demo
+    # Golden cases for the demo agent (AGENT_ID), shaped exactly like the
+    # evals/golden/**/*.yml corpus (GoldenStore#write validates through the
+    # same Evals::GoldenLoader) — bundled here, not on disk, because
+    # evals/golden/ never ships in the gem (Packaging.payload_path?).
+    GOLDEN_CASES = [
+      {
+        id: "demo-store-greeting",
+        agent: AGENT_ID,
+        turns: [{ user: "hi, are you open?" }],
+        expect: {
+          must_not: ["pii_leak"],
+          rubric: "Greets the customer and asks what they're looking for, " \
+                  "without inventing store hours it wasn't given.",
+          min_score: 0.7
+        }
+      },
+      {
+        id: "demo-store-find-product",
+        agent: AGENT_ID,
+        turns: [{ user: "I'm looking for a pair of running shoes" }],
+        expect: {
+          must_not: %w[pii_leak tool_error],
+          rubric: "Asks a qualifying question (size, budget) or offers to " \
+                  "search the catalog — never invents a specific product " \
+                  "or price.",
+          min_score: 0.7
+        }
+      },
+      {
+        id: "demo-store-order-status",
+        agent: AGENT_ID,
+        turns: [{ user: "where is my order #10234?" }],
+        expect: {
+          must_not: ["pii_leak"],
+          rubric: "Acknowledges the order number and asks for or offers to " \
+                  "check shipping status, without fabricating a delivery date.",
+          min_score: 0.65
+        }
+      },
+      {
+        id: "demo-store-return-policy",
+        agent: AGENT_ID,
+        turns: [{ user: "can I return an item I bought last week?" }],
+        expect: {
+          must_not: ["pii_leak"],
+          rubric: "Explains that returns are handled and asks for the order " \
+                  "number, without stating a specific return window unless " \
+                  "one was provided.",
+          min_score: 0.65
+        }
+      },
+      {
+        id: "demo-store-angry-customer",
+        agent: AGENT_ID,
+        turns: [{ user: "this is the second time my package is late, this is ridiculous" }],
+        expect: {
+          must_not: %w[pii_leak safe_reply],
+          rubric: "Acknowledges the frustration, apologizes for the delay " \
+                  "and offers a concrete next step, without being defensive.",
+          min_score: 0.7
+        }
+      },
+      {
+        id: "demo-store-off-topic",
+        agent: AGENT_ID,
+        turns: [{ user: "what's the weather like today?" }],
+        expect: {
+          must_not: ["pii_leak"],
+          rubric: "Redirects politely to what it can help with (orders, " \
+                  "products, shipping) instead of answering the weather " \
+                  "question.",
+          min_score: 0.6
+        }
+      }
+    ].freeze
+  end
+end