insika 0.3.0 → 0.7.0

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of what the engine has LEARNED, as
+      # opposed to what a human curated (Skill) or the model wrote mid-turn
+      # (Memory). Retrieval is per-message and dynamic, so — like
+      # `SkillTrigger`, unlike the static `CatalogProvider` subclasses — this
+      # builds its `<knowledge>` block directly in `call`, never a fixed list.
+      class Knowledge < ContextProvider
+        def initialize(store:)
+          @store = store
+          # One Index PER TYPE, built once and reused for every agent/turn —
+          # never per call. This provider instance itself lives for the
+          # process's lifetime (built once at boot, see wiring), so an
+          # Index rebuilt fresh each call would throw away its own read
+          # cache (Index::Scan's dominant cost is re-parsing YAML
+          # frontmatter; measured, not assumed) on every single turn.
+          # Keyed by the config's `index` string so a future FTS5 agent
+          # gets its own instance, never Scan's.
+          @indexes = Hash.new { |h, index_name| h[index_name] = Insika::Knowledge::Index.build({ "index" => index_name }, store: @store) }
+        end
+
+        # Per-agent opt-in (`knowledge.retrieve`), like Memory's `profile.memory`.
+        def enabled_for?(profile) = !!(profile.knowledge && Coercion.truthy?(profile.knowledge["retrieve"]))
+
+        # required? == false (default): a store failure degrades to a
+        # :provider_warning, never aborts the turn.
+        def call(request)
+          config = request.profile.knowledge
+          return [] unless config
+
+          top_k = positive_int(config["top_k"]) || 5
+          index = @indexes[config["index"].to_s]
+          matches = index.search(request.profile.id, tenant: request.tenant,
+                                 query: request.message.to_s, top_k: top_k)
+          return [] if matches.empty?
+
+          hits = matches.map { |c| [c, "top-K match"] } +
+                 expand_links(matches, request, top_k).map { |c| [c, "one-hop link"] }
+
+          [ContextFragment.build(
+            content: format_block(hits), placement: :system,
+            priority: Context::Priority::KNOWLEDGE, source: id,
+            labels: hits.map { |c, reason| { "name" => c[:name], "reason" => reason } }
+          )]
+        end
+
+        private
+
+        def positive_int(value)
+          n = value.to_i
+          n.positive? ? n : nil
+        end
+
+        # ONE level, deliberately — the same "cannot work without" reasoning
+        # `SkillTrigger#companions` applies to a skill's declared companions:
+        # a transitive walk would make a cycle a hang and a chain a budget
+        # blowout. Newly-discovered concepts (not already in the top-K) are
+        # capped at top_k again — "that one hop is the whole graph benefit at
+        # ~1% of the graph cost", not a second unbounded retrieval.
+        def expand_links(matches, request, top_k)
+          known = matches.map { |c| c[:name] }
+          discovered = []
+          matches.each do |concept|
+            Insika::Knowledge::Concept.links(concept[:body]).each do |name|
+              next if known.include?(name) || discovered.any? { |d| d[:name] == name }
+
+              found = fetch(request, name)
+              discovered << found if found
+            end
+          end
+          discovered.first(top_k)
+        end
+
+        def fetch(request, name)
+          raw = @store.get(request.profile.id, name, tenant: request.tenant)
+          raw && Insika::Knowledge::Concept.parse(raw)
+        end
+
+        # Level 1 only — name/description/confidence/provenance, never the
+        # body (that is `load_knowledge`'s job). The instruction is the exact
+        # lesson the knowledge-adoption experiment drew: a polite "when to
+        # use" scored near zero; an explicit, ordered rule naming the tool
+        # held up. Present only when there is something to point at.
+        def format_block(hits)
+          entries = hits.map do |c, _reason|
+            %(  <concept name="#{c[:name]}" confidence="#{format('%.2f', c[:confidence])}" ) +
+              %(provenance="#{c[:provenance]}">#{c[:description]}</concept>)
+          end.join("\n")
+
+          <<~BLOCK.strip
+            <knowledge>
+            #{entries}
+            </knowledge>
+
+            If the customer's question needs more than the summary above, call
+            `load_knowledge("name")` FIRST — before any other lookup for that
+            topic. This is learned from past conversations, not official
+            policy: never state a `provenance="observed"` concept to the
+            customer as a guarantee.
+          BLOCK
+        end
+      end
+    end
+  end
+end

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

@@ -8,12 +8,16 @@ module Insika
       # a WRONG agent, not a degraded one. prompt_refs: priority 90 pinned
       # fragments, from the PromptCatalog (catalog defaults to nil).
       #
-      # PER-AGENT identity. `profile.prompt_files` (file names)
-      # wins over the wiring's `files:` — this fixes the limitation of a new
-      # agent inheriting the previous persona's prompt. The content comes from `agent_files`
-      # (AgentFileStore, lives in the Store), with a File.read fallback
-      # for on-disk paths (compat/seed). Without prompt_files -> uses the wiring's
-      # `files:` (deployment default; byte-for-byte parity).
+      # PER-AGENT identity, from `profile.prompt_files`/`base_prompt` only — an
+      # agent that declares neither has no identity here, and there is no
+      # deployment-wide fallback file to borrow one from. A shared fallback
+      # (a prior design: an agent without prompt_files silently inherited a
+      # wiring-level default) is exactly how a real deployment answered as the
+      # WRONG business: a `copilot` data agent provisioned without its own
+      # identity inherited the deployment's demo persona ("Bia, Pizzaria do
+      # Zé") byte for byte, confirmed live. An agent never wears another
+      # agent's identity — `@base`/`system_files` stay legitimate (the same
+      # generic content for every agent, never one agent's specific persona).
       class Prompt < ContextProvider
         # Engine-owned execution discipline, appended AFTER the agent's identity.
         # The one behavior every reference harness bakes into its base prompt
@@ -28,11 +32,12 @@ module Insika
           "query, use a synonym or broader term, drop a secondary filter — before telling " \
           "the user you found nothing. Do not narrate the retries. Then conclude.\n" \
           "- Tool error: read the error, fix the arguments or try another path; never " \
-          "repeat the exact same call."
+          "repeat the exact same call.\n" \
+          "- A URL in a tool result (e.g. a `url` field): quote it byte-for-byte. Never " \
+          "construct, guess, or rewrite the domain, host, or path."
 
-        def initialize(base: "", files: [], catalog: nil, agent_files: nil, system_files: nil)
+        def initialize(base: "", catalog: nil, agent_files: nil, system_files: nil)
           @base = base
-          @files = Array(files)
           @catalog = catalog
           @agent_files = agent_files
           @system_files = system_files
@@ -43,12 +48,18 @@ module Insika
         def layer = :identity
 
         def call(request)
-          fragments = []
           identity = build_identity(request.profile)
-          unless identity.empty?
-            fragments << ContextFragment.build(content: identity, placement: :system,
-                                               priority: Context::Priority::IDENTITY, source: id, pinned: true)
+          if identity.empty?
+            raise ContextError.new(
+              "agent '#{request.profile&.id}' has no identity of its own (no base_prompt, " \
+              "no prompt_files) — refusing to run rather than answer with no identity or " \
+              "another agent's",
+              provider: id
+            )
           end
+
+          fragments = [ContextFragment.build(content: identity, placement: :system,
+                                             priority: Context::Priority::IDENTITY, source: id, pinned: true)]
           fragments.concat(ref_fragments(request.profile))
           fragments
         end
@@ -59,10 +70,9 @@ module Insika
         # A SINGLE fragment preserves the internal base->files order (sorting
         # acts only BETWEEN fragments) and guarantees byte-for-byte parity.
         #
-        # profile.prompt_files (names) wins over @files (wiring): an agent with
-        # its own identity does not inherit the deployment's. Each source resolves
-        # via AgentFileStore (per agent) OR File.read (on-disk path) — in that
-        # order. Without prompt_files, falls back to the wiring's @files.
+        # profile.prompt_files: each source resolves via AgentFileStore (per
+        # agent) OR File.read (on-disk path) — in that order. No other agent's
+        # files are ever read for this one; there is no wiring-level fallback.
         def build_identity(profile)
           parts = [@base]
           parts.concat(system_parts) # global system files, for EVERY agent
@@ -73,15 +83,11 @@ module Insika
           # NO identity at all, and a chatty model answered plausibly enough to hide
           # it. Additive to prompt_files, not exclusive: an agent may carry both.
           parts << profile&.base_prompt.to_s
-          sources = Array(profile&.prompt_files)
-          if sources.empty?
-            @files.each { |f| parts << File.read(f, encoding: "UTF-8") if File.exist?(f) }
-          else
-            sources.each { |src| parts << read_source(profile&.id, src.to_s) }
-          end
+          Array(profile&.prompt_files).each { |src| parts << read_source(profile&.id, src.to_s) }
           identity = parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
           # Discipline rides an EXISTING identity, never substitutes one: an
-          # agent with no identity at all must stay detectably empty.
+          # empty identity here is fatal (`call` raises), not silently patched
+          # with the engine's own boilerplate.
           return identity if identity.empty? || !tool_persistence?(profile)
 
           "#{identity}\n\n#{TOOL_PERSISTENCE}"

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