insika 0.0.1 → 0.2.0

data/lib/insika/frontmatter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # TOLERANT frontmatter parser (the YAML `--- ... ---` block of a SKILL.md).
+  # The convention is YAML, but real packs carry PROSE in `description` — with `: `
+  # (colon + space), quotes, parentheses — which STRICT YAML rejects
+  # ("mapping values are not allowed in this context"). The OpenClaw gateway
+  # tolerates it; the insika has to tolerate it too (the same pack must hold).
+  #
+  # Strategy: try YAML (respects quoted / multi-line / lists); if the YAML
+  # fails OR doesn't yield a Hash, fall back to a LINE-BY-LINE parse that splits on
+  # the FIRST `:` and treats the rest as a raw string — recovers name/description
+  # even with `: ` in the middle of the value. -> Hash with String keys. NEVER raises.
+  module Frontmatter
+    module_function
+
+    def parse(text)
+      loaded = begin
+        YAML.safe_load(text.to_s)
+      rescue Psych::SyntaxError
+        nil
+      end
+      loaded.is_a?(Hash) ? stringify(loaded) : lenient(text)
+    end
+
+    # Split on the first `:` of each line; value = the rest (string). A line
+    # without `:` is ignored. Preserves `: ` internal to the value (the case that breaks YAML).
+    def lenient(text)
+      text.to_s.each_line.each_with_object({}) do |line, acc|
+        next unless line.include?(":")
+
+        key, _, value = line.partition(":")
+        k = key.strip
+        acc[k] = value.strip unless k.empty?
+      end
+    end
+
+    def stringify(hash) = hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+  end
+end

data/lib/insika/golden_store.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require "yaml"
+
+module Insika
+  # AUTHORED eval cases (promoted to a store by).
+  #
+  # A golden case used to be a YAML file in `evals/golden/`, which means only someone
+  # with a checkout and a text editor could add one. The rubric is the part of an eval
+  # a domain owner can actually write ("consults the coupon by tool and does NOT invent
+  # a code") — so it has to be authorable where they already work, the Studio.
+  #
+  # One record per case in the ConfigStore (scope "goldens"):
+  #   { "case" => { "id" =>, "agent" =>, "turns" => [...], "expect" => {...} },
+  #     "updated_at" => iso8601 }
+  #
+  # The stored shape is the SAME mapping the YAML file holds, and every write is
+  # validated by `Evals::GoldenLoader.build` — the one validator, so a case authored in
+  # the Studio and a case read from disk cannot diverge. `evals/golden/**` stays the
+  # export format and the seed for a fresh deploy (`insika evals:import`), for the same
+  # reason the knowledge RFC keeps markdown as both: no converter to keep honest.
+  #
+  # No version history here, unlike the prompt/skill stores: the corpus on disk IS the
+  # backup, and re-importing restores it.
+  class GoldenStore
+    SCOPE = "goldens"
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # Upsert. `raw` is the case mapping (string or symbol keys), validated before it
+    # lands. -> Evals::Golden. InvalidGolden if malformed — a silently dropped case is
+    # a hole in the safety net, which is why the loader raises instead of skipping.
+    def write(raw, path: nil)
+      golden = Evals::GoldenLoader.build(Coercion.deep_stringify(raw), source: "(store)")
+      record = { "case" => case_hash(golden), "updated_at" => timestamp }
+      # Remember where it came from, so an export reproduces the corpus LAYOUT instead
+      # of renaming every file. The curated corpus groups the safety suite by PURPOSE
+      # (`safety/`) while its cases belong to an example agent — deriving the path from
+      # the agent would scatter them. An edit keeps whatever path it already had.
+      record["path"] = Coercion.presence(path) || @cs.get(SCOPE, golden.id)&.fetch("path", nil)
+      @cs.put(SCOPE, golden.id, record.compact)
+      golden
+    end
+
+    # -> Evals::Golden | nil. A stored case that no longer validates surfaces as nil
+    # rather than raising here; `insika doctor`-style sweeps are the place to shout.
+    def find(id)
+      record = @cs.get(SCOPE, id.to_s)
+      record && build(record)
+    end
+
+    # -> [String] case ids, lexicographic (a stable run order, like the file loader's
+    # sort by path).
+    def ids = @cs.keys(SCOPE)
+
+    # -> [Evals::Golden] every valid case, in id order.
+    def all = ids.filter_map { |id| find(id) }
+
+    # -> [Evals::Golden] one agent's cases.
+    def for_agent(agent_id) = all.select { |g| g.agent == agent_id.to_s }
+
+    # -> [String] ids whose stored mapping no longer validates (an edit that broke the
+    # shape). The Studio shows these; they never silently vanish from a run.
+    def invalid
+      ids.reject { |id| find(id) }
+    end
+
+    # -> bool (did it exist?)
+    def delete(id) = @cs.delete(SCOPE, id.to_s)
+
+    # Bulk import from the corpus on disk. Returns the ids written. `overwrite: false`
+    # keeps an already-authored case (the store wins over the seed, same rule the
+    # SkillCatalog overlay uses).
+    def import_dir(dir, overwrite: true)
+      root = File.expand_path(dir)
+      Evals::GoldenLoader.load_dir(dir).filter_map do |golden|
+        next if !overwrite && @cs.get(SCOPE, golden.id)
+
+        # Expand both sides: the loader's `source` is whatever shape `dir` was given in
+        # (a relative glob stays relative), so comparing raw strings would leave the
+        # corpus prefix inside the stored path.
+        relative = File.expand_path(golden.source.to_s).delete_prefix("#{root}/")
+        write(case_hash(golden), path: relative).id
+      end
+    end
+
+    # The export format IS the import format, written at the path the case came from
+    # (falling back to `<agent>/<id>.yml` for a case authored in the Studio). -> [paths]
+    #
+    # It is NOT a faithful copy of the curated corpus: `YAML.dump` drops the comments
+    # those files carry, and each one explains what its case is for. So exporting over
+    # an existing corpus demands `force` — losing that prose silently would be a bad
+    # trade for a convenience.
+    def export_dir(dir, force: false)
+      existing = Dir.glob(File.join(dir, "**", "*.{yml,yaml}"))
+      if existing.any? && !force
+        raise Insika::ValidationError,
+              "#{dir} already holds #{existing.size} case file(s); exporting rewrites them and " \
+              "DROPS their comments — pass --force to accept that, or export somewhere else"
+      end
+
+      all.map do |golden|
+        path = File.join(dir, path_of(golden))
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, YAML.dump(case_hash(golden)))
+        path
+      end
+    end
+
+    private
+
+    def path_of(golden)
+      Coercion.presence(@cs.get(SCOPE, golden.id)&.fetch("path", nil)) ||
+        File.join(golden.agent, "#{golden.id}.yml")
+    end
+
+    def build(record)
+      Evals::GoldenLoader.build(record["case"] || {}, source: "(store)")
+    rescue Evals::GoldenLoader::InvalidGolden
+      nil
+    end
+
+    # Golden -> the plain mapping (what YAML holds and what the store persists).
+    # `source` is a load-time detail, never part of the case.
+    # `requires` is omitted when empty so a case that runs everywhere stays as short
+    # in the store as it is on disk — but it is NEVER dropped when present: a case
+    # that silently lost its requirements would come back as a failure on every
+    # deployment that lacks the tool, which is the exact lie `requires` exists to end.
+    def case_hash(golden)
+      h = { "id" => golden.id, "agent" => golden.agent, "turns" => golden.turns }
+      h["requires"] = golden.requires unless golden.requires.empty?
+      # Same rule for `reference`: omitted when absent, never dropped
+      # when present. A case that lost its reference in a round-trip would stop being
+      # compared against the incumbent and the report would look identical.
+      h["reference"] = golden.reference unless golden.reference.empty?
+      h.merge("expect" => golden.expect)
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end

data/lib/insika/hooks.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Insika
+  # Hooks ALTER the input/output of the ONE stage they wrap: Middleware
+  # modifies, Hooks alter, Events observe. They don't create their own flow nor skip
+  # stages. Synchronous and without rescue — the error->state mapping belongs to the Executor.
+  class Hooks
+    PAIRS = %i[task prompt agent tool].freeze
+
+    def initialize
+      @before = Hash.new { |h, k| h[k] = [] }
+      @after = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # callables; multiple per pair. Registration order is significant.
+    def register(pair, before: nil, after: nil)
+      raise ArgumentError, "unknown hook pair: #{pair.inspect}" unless PAIRS.include?(pair)
+
+      @before[pair] << before if before
+      @after[pair] << after if after
+      nil
+    end
+
+    # befores in registration order (may ALTER the subject by returning the new one),
+    # yield(subject), afters in REVERSE order (may alter the result). With no
+    # registrations -> degenerates into yield(subject) (no-op). A hook that doesn't alter
+    # returns what it received; returning nil IS altering to nil (no special case).
+    def around(pair, subject)
+      run_after(pair, yield(run_before(pair, subject)))
+    end
+
+    # Public halves of around. Needed for the :tool pair, whose
+    # stage "body" is RubyLLM's inner loop — there is no block
+    # to wrap; the halves are called from the before_tool_call/
+    # after_tool_result callbacks separately.
+    def run_before(pair, subject)
+      raise ArgumentError, "unknown hook pair: #{pair.inspect}" unless PAIRS.include?(pair)
+
+      @before[pair].reduce(subject) { |subj, hook| hook.call(subj) }
+    end
+
+    def run_after(pair, result)
+      raise ArgumentError, "unknown hook pair: #{pair.inspect}" unless PAIRS.include?(pair)
+
+      @after[pair].reverse.reduce(result) { |res, hook| hook.call(res) }
+    end
+  end
+end

data/lib/insika/http_client.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "coercion"
+
+module Insika
+  # Default HTTP client for data-tools. Net::HTTP (stdlib, zero-dep — spec)
+  # with its own socket timeouts (mitigates reactor blocking even if the
+  # envelope timer doesn't fire) and a response-size CAP via streaming (
+  # avoids OOM). It is INJECTABLE: tests pass a double (none hit the network);
+  # can swap in async-http without touching DataDefinedTool.
+  #
+  # Contract: request(method:, url:, headers:, body:, timeout:) -> { status:, body: }
+  # (+ `location:` on a 3xx). It does NOT follow redirects: the destination is
+  # cleared by the EgressGuard in the CALLER (DataDefinedTool), before the call —
+  # a hop taken in here would carry the model's tool call to a host nobody
+  # allowed (an SSRF around the guard). A data-tool whose API moved gets a
+  # 3xx surfaced as an error naming the new URL, and the fix is to author the
+  # final URL in the definition.
+  class HttpClient
+    DEFAULT_TIMEOUT = 30
+    MAX_BYTES = 1_000_000 # 1 MB
+
+    class ResponseTooLarge < Insika::Error; end
+
+    def initialize(max_bytes: MAX_BYTES)
+      @max_bytes = max_bytes
+    end
+
+    def request(method:, url:, headers: {}, body: nil, timeout: nil)
+      uri = URI.parse(url)
+      req = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body && !body.to_s.empty?
+
+      t = timeout || DEFAULT_TIMEOUT
+      opts = { use_ssl: uri.scheme == "https", open_timeout: t, read_timeout: t }
+      Net::HTTP.start(uri.host, uri.port, opts) do |http|
+        result = nil
+        http.request(req) do |resp|
+          # Accumulate in BINARY: Net::HTTP yields ASCII-8BIT chunks and a
+          # multi-byte character can straddle two of them, so only byte
+          # concatenation is safe here. (A `+""` buffer would also SILENTLY turn
+          # BINARY the first time a chunk carried a non-ASCII byte.)
+          collected = +"".b
+          resp.read_body do |chunk|
+            collected << chunk
+            raise ResponseTooLarge, "response exceeds #{@max_bytes} bytes" if collected.bytesize > @max_bytes
+          end
+          # One tag at the end, over whole bytes: the body leaves here as valid
+          # UTF-8 (see Coercion.utf8) because it goes on to be a tool result —
+          # transcript, event, SSE frame — and JSON.generate rejects anything else.
+          result = { status: resp.code.to_i, body: Coercion.utf8(collected) }
+          # The redirect TARGET, so a moved API is reported as "moved to <url>"
+          # instead of a bare 3xx with the empty body servers send with it.
+          result[:location] = resp["location"].to_s if resp["location"]
+        end
+        result
+      end
+    end
+  end
+end

data/lib/insika/inbound_log.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Short-lived memory of inbound event ids, so a platform's retry does not become
+  # a second LLM turn and a second reply.
+  #
+  # Every messaging platform retries a webhook it did not see acked in time, and a
+  # relay consumer that hands us its own queue does the same. Without this, the
+  # cost of one flaky ack is a duplicated turn (paid for) and a duplicated answer
+  # (visible to the customer). With it, the retry finds the id and gets the SAME
+  # task back — the caller learns it already sent this, which is a different fact
+  # from "your message was merged into someone else's turn".
+  #
+  # The id is the CALLER's (`wamid.…`, a Slack event id, whatever the consumer's
+  # queue uses). A caller that cannot supply a stable one gets at-least-once turns
+  # and is told so in the docs — the engine does not hash the content and call
+  # that dedup, because two customers legitimately typing "oi" one second apart is
+  # not a duplicate.
+  #
+  # TTL, not forever: this is a retry window, not an audit log. An expired entry is
+  # deleted lazily on read; `sweep` (boot) clears whatever nobody read back.
+  class InboundLog
+    SCOPE = "inbound"
+    KEY_PREFIX = "inbound:"
+
+    DEFAULT_TTL = 86_400 # 24h — longer than any platform's retry schedule
+
+    def initialize(store:, ttl: DEFAULT_TTL, clock: -> { Time.now.utc })
+      @store = store
+      @ttl = ttl.to_i
+      @clock = clock
+    end
+
+    # -> the task id this event already produced, or nil (never seen, or the
+    # window closed). An expired entry is removed as it is read: the next
+    # identical id is honestly a new message by then.
+    def find(key)
+      record = @store.get(SCOPE, key_for(key))
+      return nil if record.nil?
+
+      if expired?(record)
+        @store.delete(SCOPE, key_for(key))
+        return nil
+      end
+      record["task_id"]
+    end
+
+    # Remembers that `key` produced `task_id`. Last write wins, like every other
+    # store — a re-record inside the window just refreshes the expiry.
+    def record(key, task_id)
+      @store.set(SCOPE, key_for(key), {
+                   "key" => key.to_s,
+                   "task_id" => task_id&.to_s,
+                   "expires_at" => (@clock.call + @ttl).iso8601
+                 })
+      task_id
+    end
+
+    # Boot housekeeping: drops the entries nobody came back for. -> count removed.
+    def sweep
+      @store.list(SCOPE, KEY_PREFIX).count do |key|
+        record = @store.get(SCOPE, key)
+        next false unless record && expired?(record)
+
+        @store.delete(SCOPE, key)
+      end
+    end
+
+    private
+
+    def expired?(record)
+      at = record["expires_at"]
+      return false if at.nil? # no expiry recorded -> keep (fail-safe, not fail-open)
+
+      Time.parse(at.to_s) <= @clock.call
+    rescue ArgumentError
+      false
+    end
+
+    def key_for(key) = "#{KEY_PREFIX}#{key}"
+  end
+end

data/lib/insika/llm_configurator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Insika
+  # Applies the authored LLM providers (LLMProviderStore) to RubyLLM at RUNTIME.
+  # Goal: swap a provider's key/base WITHOUT a restart —
+  # RubyLLM exposes `config.<api>_api_key=` / `config.<api>_api_base=`, so
+  # reconfiguring is a matter of setting those accessors per provider.
+  #
+  # Core constraint: this file does NOT require ruby_llm at load-time — the
+  # `require` is lazy, inside `apply` (and injectable via `configure:` for tests,
+  # which run without the gem/key). A provider that RubyLLM doesn't recognize (no
+  # matching accessor) does NOT blow up: it goes into `skipped` (degrades to "restart
+  # recommended", like OpenClaw), the rest applies.
+  #
+  # ⚠️ GOTCHA — the DEFAULT target is a global singleton (RubyLLM research).
+  # With no `configure:`, `apply`/`unapply` mutate the PROCESS-WIDE config
+  # (`RubyLLM.config`). They are therefore admin operations (rare, operator-driven:
+  # a provider key/base edit in the Studio), NOT a per-request/per-turn path — a
+  # concurrent turn reading the config mid-mutation would observe a torn key/base.
+  # This is tolerable ONLY because reconfiguration is infrequent and single-writer
+  # (one reactor). Do NOT call this per turn, and do NOT reach for it to vary the
+  # MODEL per turn — the model is chosen at chat build time (ModelResolver ->
+  # chat(model:)), never by mutating the global.
+  #
+  # PER-GRAPH credentials are no longer hypothetical: the DSL runtime
+  # passes `configure:` targeting its own `RubyLLM.context` — an isolated config dup
+  # — so an operator's key edit in an EMBEDDED graph applies to that graph and stops
+  # there. See `DSL::Runtime#llm_configure` and docs/EMBEDDING.md.
+  class LLMConfigurator
+    def initialize(provider_store:, configure: nil)
+      @provider_store = provider_store
+      @configure = configure # ->(&blk){ blk.call(config_target) }; default = RubyLLM
+    end
+
+    # Reconfigures RubyLLM with `providers` (raw records, with the real api_key) or,
+    # if nil, with ALL from the store. -> { applied: [api], skipped: [{api:, reason:}] }.
+    def apply(providers = nil)
+      records = providers || @provider_store.all_raw
+      applied = []
+      skipped = []
+
+      with_config do |config|
+        records.each do |rec|
+          api = fetch(rec, :api)
+          key = fetch(rec, :api_key)
+          if key.nil? || key.to_s.empty?
+            skipped << { api: api, reason: "sem api_key" }
+            next
+          end
+
+          if set_accessor(config, "#{api}_api_key", key)
+            base = fetch(rec, :base_url)
+            set_accessor(config, "#{api}_api_base", base) if base && !base.to_s.empty?
+            applied << api
+          else
+            skipped << { api: api, reason: "provider '#{api}' not recognized by RubyLLM" }
+          end
+        end
+      end
+
+      { applied: applied, skipped: skipped }
+    end
+
+    # UNDOES a provider's config in RubyLLM at runtime (delete without a restart,
+    # clears `<api>_api_key`/`<api>_api_base`. A provider that RubyLLM
+    # doesn't recognize (no accessor) -> unapplied: false (nothing applied, nothing to undo).
+    # -> { unapplied: bool }.
+    def unapply(api)
+      api = api.to_s
+      unapplied = false
+      with_config do |config|
+        unapplied = set_accessor(config, "#{api}_api_key", nil)
+        set_accessor(config, "#{api}_api_base", nil)
+      end
+      { unapplied: unapplied }
+    end
+
+    private
+
+    def with_config(&blk)
+      if @configure
+        @configure.call(&blk)
+      else
+        require "ruby_llm"
+        RubyLLM.configure(&blk)
+      end
+    end
+
+    def set_accessor(config, name, value)
+      setter = "#{name}="
+      return false unless config.respond_to?(setter)
+
+      config.public_send(setter, value)
+      true
+    end
+
+    def fetch(rec, key) = rec[key.to_s] || rec[key.to_sym]
+  end
+end

data/lib/insika/llm_provider_store.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Insika
+  # LLM providers authored at runtime. One record per
+  # provider in the ConfigStore (scope "llm_providers"), keyed by the API slug
+  # (`deepseek`, `openai`, ...). Holds base_url/auth_header/models and the `api_key`.
+  #
+  # The `api_key` NEVER leaves here in plaintext to the UI: the display reads
+  # (`get`/`all`) mask it with the `__OCULTO__` sentinel. Only `all_raw`/`get_raw`
+  # (consumed by the LLMConfigurator, never by the screen) return the real key.
+  # On write, the sentinel coming back preserves the key; a new string replaces it; ""
+  # clears it (see Insika::SecretMasking).
+  class LLMProviderStore
+    include Coercion
+
+    SCOPE = "llm_providers"
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> MASKED Hash | nil.
+    def get(api)
+      mask(raw(api))
+    end
+
+    # -> Hash with REAL api_key | nil. Internal use (LLMConfigurator).
+    def get_raw(api)
+      raw(api)
+    end
+
+    # -> [String] slugs, lexicographic order.
+    def apis = @cs.keys(SCOPE)
+
+    # -> [Hash] all MASKED (for the UI).
+    def all
+      apis.filter_map { |a| get(a) }
+    end
+
+    # -> [Hash] all with REAL api_key (for the configurator). Never goes to the screen.
+    def all_raw
+      apis.filter_map { |a| raw(a) }
+    end
+
+    # Upsert with secret reconciliation. `attrs` (string|symbol keys):
+    #   api (required), base_url, auth_header, api_key (sentinel-aware), models[]
+    # -> MASKED Hash (the stored record).
+    def upsert(attrs)
+      h = symbolize(attrs)
+      api = presence(h[:api])
+      raise Insika::ValidationError, "api is required" if api.nil?
+
+      existing = raw(api)
+      record = {
+        "api" => api,
+        "base_url" => presence(h[:base_url]),
+        "auth_header" => presence(h[:auth_header]),
+        "api_key" => SecretMasking.reconcile(h[:api_key], existing&.fetch("api_key", nil)),
+        "models" => Array(h[:models]).map(&:to_s)
+      }
+      @cs.put(SCOPE, api, record)
+      mask(record)
+    end
+
+    # -> bool (did it exist?).
+    def delete(api) = @cs.delete(SCOPE, api.to_s)
+
+    private
+
+    def raw(api) = @cs.get(SCOPE, api.to_s)
+
+    # Swaps the real api_key for the sentinel (or nil if absent) — never leaks plaintext.
+    def mask(record)
+      return nil if record.nil?
+
+      record.merge("api_key" => SecretMasking.mask(record["api_key"]))
+    end
+
+    def symbolize(attrs)
+      (attrs || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end