insika 0.2.0 → 0.7.0

data/lib/insika/router/app.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+require "rack/request"
+require "async/http/client"
+require "async/http/endpoint"
+require "protocol/http/body/buffered"
+require_relative "session_key"
+require_relative "proxy_body"
+
+module Insika
+  module Router
+    # The standalone Rack/Async app: session-key extraction →
+    # consistent-hash pick → proxy, on the same Async/Falcon stack the engine
+    # already runs on. A request whose key has no live owner (nothing found,
+    # or the ring itself is empty) round-robins; a request whose chosen
+    # backend is unreachable answers the retry envelope — it is NOT
+    # retried against a different backend (§3.5): that backend may already
+    # hold a durable, at-most-once claim on the task this request names.
+    class App
+      DEFAULT_BODY_MAX_BYTES = 262_144 # 256 KiB — small JSON control payloads, never uploads (§5)
+      RETRY_AFTER_SECONDS = 1
+      HOP_BY_HOP = %w[connection keep-alive proxy-connection transfer-encoding upgrade host content-length].freeze
+
+      # client_factory: (backend_url, timeout) -> an object answering #call(request)
+      # -> Protocol::HTTP::Response. Defaults to a real Async::HTTP::Client;
+      # a spec injects a fake instead of opening real sockets.
+      def initialize(pool:, body_max_bytes: DEFAULT_BODY_MAX_BYTES, backend_timeout: 10, logger: $stdout,
+                     client_factory: DEFAULT_CLIENT_FACTORY)
+        @pool = pool
+        @body_max_bytes = body_max_bytes
+        @backend_timeout = backend_timeout
+        @logger = logger
+        @client_factory = client_factory
+        @clients = {} # backend address -> memoized client (persistent connections)
+        @clients_mutex = Mutex.new
+        @rr_index = -1
+      end
+
+      DEFAULT_CLIENT_FACTORY = lambda do |backend, timeout|
+        Async::HTTP::Client.new(Async::HTTP::Endpoint.parse(backend, timeout: timeout))
+      end
+      private_constant :DEFAULT_CLIENT_FACTORY
+
+      def call(env)
+        req = Rack::Request.new(env)
+        segments = req.path_info.split("/").reject(&:empty?)
+
+        return health_response if req.request_method == "GET" && segments == ["up"]
+
+        raw_body = read_body(env)
+        backend = pick_backend(req.request_method, segments, raw_body)
+        return unavailable_response if backend.nil?
+
+        proxy(req, backend, raw_body)
+      end
+
+      private
+
+      def pick_backend(method, segments, raw_body)
+        backends = @pool.backends
+        return nil if backends.empty?
+
+        key = session_key(method, segments, raw_body)
+        return @pool.ring.backend_for(key) if key
+
+        @rr_index = (@rr_index + 1) % backends.size
+        backends[@rr_index]
+      end
+
+      def session_key(method, segments, raw_body)
+        return nil if raw_body.nil?
+
+        if raw_body.bytesize > @body_max_bytes
+          log("router: body #{raw_body.bytesize}B exceeds body_max_bytes=#{@body_max_bytes} — " \
+              "skipping session-key extraction (round-robin), forwarding it whole regardless")
+          return nil
+        end
+
+        SessionKey.extract(method, segments, body: -> { JSON.parse(raw_body) })
+      end
+
+      # Reads the WHOLE body (it must be forwarded intact) — `body_max_bytes`
+      # only bounds how much of it #session_key will try to parse as JSON,
+      # never how much reaches the backend (§3.1, §5).
+      def read_body(env)
+        input = env["rack.input"]
+        return nil if input.nil?
+
+        data = input.read
+        input.rewind if input.respond_to?(:rewind)
+        data.nil? || data.empty? ? nil : data
+      end
+
+      def proxy(req, backend, raw_body)
+        client = client_for(backend)
+        path = req.script_name.to_s + req.path_info
+        path += "?#{req.query_string}" unless req.query_string.to_s.empty?
+        body = raw_body ? Protocol::HTTP::Body::Buffered.wrap(raw_body) : nil
+
+        response = client.call(
+          Protocol::HTTP::Request.new(nil, nil, req.request_method, path, nil,
+                                      forward_headers(req), body)
+        )
+        [response.status, response_headers(response), response.body ? ProxyBody.new(response.body) : []]
+      rescue StandardError => e
+        log("router: backend #{backend} unreachable (#{e.class}: #{e.message})")
+        unavailable_response
+      end
+
+      def client_for(backend)
+        @clients_mutex.synchronize { @clients[backend] ||= @client_factory.call(backend, @backend_timeout) }
+      end
+
+      def forward_headers(req)
+        headers = Protocol::HTTP::Headers.new
+        req.each_header do |key, value|
+          next unless key.start_with?("HTTP_")
+
+          name = key.sub(/\AHTTP_/, "").tr("_", "-").downcase
+          headers.add(name, value) unless HOP_BY_HOP.include?(name)
+        end
+        headers.add("content-type", req.content_type) if req.content_type
+        headers
+      end
+
+      def response_headers(response)
+        headers = {}
+        response.headers&.each do |key, value|
+          name = key.to_s
+          headers[name] = headers.key?(name) ? Array(headers[name]) + [value] : value
+        end
+        headers
+      end
+
+      def health_response
+        json_response(200, { status: "ok", backends: @pool.backends.size })
+      end
+
+      def unavailable_response
+        json_response(503, { error: { class: "Insika::Router::BackendUnavailable",
+                                       message: "no backend reachable",
+                                       retryable: true, retry_after: RETRY_AFTER_SECONDS } })
+      end
+
+      def json_response(status, body)
+        [status, { "content-type" => "application/json" }, [JSON.generate(body)]]
+      end
+
+      def log(message)
+        @logger&.puts(message)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/insika/router/backend_pool.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "resolv"
+require_relative "hash_ring"
+
+module Insika
+  module Router
+    # Backend discovery + the ring it feeds. Two modes:
+    #
+    #   static — a fixed list, resolved once (the Railway shape: N local
+    #     Falcon workers on known ports inside one container).
+    #   dns    — one hostname re-resolved on an interval (the Kubernetes
+    #     shape: a headless Service, one A/AAAA record per ready pod).
+    #
+    # The ring is rebuilt ONLY when the resolved set actually changed — a DNS
+    # poll that returns the same pods is a no-op, not a ring rebuild every
+    # `dns_interval` seconds.
+    class BackendPool
+      def initialize(static: nil, dns: nil, dns_port: nil, dns_interval: 15,
+                      replicas: HashRing::DEFAULT_REPLICAS, resolver: Resolv, logger: $stdout)
+        raise ArgumentError, "static or dns is required, not both" if static.nil? == dns.nil?
+        raise ArgumentError, "dns_port is required with dns:" if dns && dns_port.nil?
+        raise ArgumentError, "static must not be empty" if static && Array(static).empty?
+
+        @static = Array(static)
+        @dns = dns
+        @dns_port = dns_port
+        @dns_interval = dns_interval
+        @replicas = replicas
+        @resolver = resolver
+        @logger = logger
+        @mutex = Mutex.new
+        @ring = nil
+        refresh!
+      end
+
+      def dns? = !@dns.nil?
+
+      def ring
+        @mutex.synchronize { @ring }
+      end
+
+      def backends
+        @mutex.synchronize { @ring&.backends || [] }
+      end
+
+      # Re-resolves (a no-op for static after the first call) and rebuilds
+      # the ring iff the resolved set changed. -> bool (did it change?).
+      def refresh!
+        resolved = @dns ? resolve_dns : @static
+        if resolved.empty?
+          log("router: 0 backends resolved — keeping the previous ring" \
+              "#{" (#{@ring.backends.size} backend(s))" if @ring}")
+          return false
+        end
+
+        @mutex.synchronize do
+          return false if @ring && @ring.backends.sort == resolved.sort
+
+          @ring = HashRing.new(resolved, replicas: @replicas)
+        end
+        log("router: ring rebuilt — #{resolved.sort.join(', ')}")
+        true
+      end
+
+      # Starts the periodic re-resolve loop (dns mode only — a no-op for
+      # static) inside the caller's Async task, so a spec can drive #refresh!
+      # directly without ever starting this loop.
+      def start_polling(task)
+        return unless dns?
+
+        task.async do |t|
+          loop do
+            t.sleep(@dns_interval)
+            refresh!
+          rescue StandardError => e
+            log("router: DNS re-resolve failed (#{e.class}: #{e.message}) — keeping the previous ring")
+          end
+        end
+      end
+
+      private
+
+      def resolve_dns
+        @resolver.getaddresses(@dns).map { |ip| "http://#{ip.include?(':') ? "[#{ip}]" : ip}:#{@dns_port}" }
+      rescue StandardError => e
+        log("router: DNS resolve of #{@dns} failed (#{e.class}: #{e.message})")
+        []
+      end
+
+      def log(message)
+        @logger&.puts(message)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/insika/router/hash_ring.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Insika
+  module Router
+    # Ketama-style consistent hash ring. Each backend gets
+    # `replicas` virtual points on a 0..2**32-1 circle (CRC32 of "backend#i");
+    # a key's owner is the first point clockwise from CRC32(key). Removing or
+    # adding one backend only remaps the ~1/N of the space that belonged to
+    # that backend's own points — not the whole ring — which is what keeps a
+    # rolling deploy from bouncing every live session to a new owner at once.
+    class HashRing
+      DEFAULT_REPLICAS = 160
+
+      def initialize(backends, replicas: DEFAULT_REPLICAS)
+        raise ArgumentError, "at least one backend is required" if Array(backends).empty?
+
+        @replicas = replicas
+        @backends = backends.uniq.sort
+        @ring = {}
+        @backends.each do |backend|
+          @replicas.times { |i| @ring[Zlib.crc32("#{backend}\0#{i}")] = backend }
+        end
+        @points = @ring.keys.sort
+      end
+
+      attr_reader :backends, :points, :ring
+
+      # -> the backend owning `key` — the first ring point at or after
+      # CRC32(key), wrapping around to the first point when `key` hashes past
+      # the last one. O(log N) via binary search, not a hash-map rebuild.
+      def backend_for(key)
+        backend_for_point(Zlib.crc32(key.to_s))
+      end
+
+      # Fraction of a representative KEY SAMPLE whose owner changes between
+      # two rings — the measurement acceptance §6.2 asks for, not an
+      # assumption. (Ring POINTS themselves are the wrong yardstick: a's/b's/
+      # c's/d's own points stay put when "e" is added — only the space of
+      # arbitrary keys BETWEEN points shifts.) `sample_size` large enough that
+      # the law of large numbers keeps the estimate tight without a spec
+      # needing thousands of literal keys of its own.
+      def self.remapped_fraction(before, after, sample_size: 20_000)
+        moved = (0...sample_size).count { |i| before.backend_for(i) != after.backend_for(i) }
+        moved.to_f / sample_size
+      end
+
+      def backend_for_point(point)
+        idx = @points.bsearch_index { |p| p >= point } || 0
+        @ring[@points[idx]]
+      end
+    end
+  end
+end

data/lib/insika/router/proxy_body.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Insika
+  module Router
+    # Streams an upstream `Protocol::HTTP::Response` body back to the
+    # downstream client. Exposes `#call(stream)`, NOT `#each` — the same
+    # discovery `Server::SSEBody` documents: under protocol-rack/protocol-http1
+    # (the stack of Async::HTTP::Server AND Falcon), a body that only responds
+    # to `#each` is routed to `Body::Enumerable`, whose `read` runs the `#each`
+    # in a plain Enumerator Fiber where `Async::Task.current` is unavailable —
+    # so a long-running SSE turn proxied through this router would come out
+    # empty. `#call` routes it to `Body::Streaming` instead, scheduled via
+    # `Fiber.schedule` under the reactor, which is what makes an SSE stream
+    # drain through the router with no added buffering beyond the one-time
+    # request-body read (§6.5).
+    class ProxyBody
+      def initialize(upstream_body)
+        @upstream_body = upstream_body
+      end
+
+      def call(stream)
+        @upstream_body.each { |chunk| stream.write(chunk) }
+      rescue StandardError
+        # The downstream client disconnected, or the upstream connection
+        # dropped mid-stream: no exception escapes (same rule as SSEBody) —
+        # the turn itself belongs to the backend, not this connection.
+        nil
+      ensure
+        @upstream_body.close
+        stream.close
+      end
+    end
+  end
+end

data/lib/insika/router/session_key.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Insika
+  module Router
+    # Session-key extraction, matched to the routes that
+    # actually carry production traffic in `Server::App` today. The RFC's own
+    # sketch of a path-based `/api/widget/sessions/:token/…` route was written
+    # from memory and does not match what `server/app.rb` implements — the
+    # widget/relay surface is `POST /channels/:id/messages` (and `/events`),
+    # with the session id as `session_id` in the JSON body, not a path
+    # segment. `/v1/responses` and `/v1/messages` carry it as `user`. Every
+    # other route (health checks, `/studio/*`, onboarding) has no session key
+    # and round-robins — none of them depend on a worker's in-memory
+    # `SessionActor` (§3.1 point 3).
+    module SessionKey
+      BODY_FIELD_BY_ROUTE = {
+        %w[v1 responses] => "user",
+        %w[v1 messages] => "user"
+      }.freeze
+
+      module_function
+
+      # segments: the request path split on "/" with empty parts removed.
+      # body: a zero-arg callable returning the parsed JSON body (a Hash) —
+      # called AT MOST ONCE, and only when a route that carries a session key
+      # actually matches, so a GET or an unrelated POST never pays for a
+      # parse. A malformed body yields no key (the backend's own parser is
+      # what answers the client's 400/422), never a router-level error.
+      def extract(method, segments, body:)
+        return nil unless method == "POST"
+
+        field =
+          if segments.length == 3 && segments[0] == "channels" && %w[messages events].include?(segments[2])
+            "session_id"
+          else
+            BODY_FIELD_BY_ROUTE[segments]
+          end
+        return nil unless field
+
+        read_field(body, field)
+      end
+
+      def read_field(body, field)
+        parsed = body.call
+        return nil unless parsed.is_a?(Hash)
+
+        value = parsed[field] || parsed[field.to_sym]
+        Insika::Coercion.present?(value) ? value.to_s : nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/insika/router.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Session-sticky router. NOT required by `require "insika"` (like
+# server/ and the Studio, it pulls in async-http and is only needed by an
+# operator who actually runs `bin/insika-router`): the engine's serving path
+# (`insika serve` / `DSL::ServerBoot` / `WEB_CONCURRENCY=1`) is completely
+# unaffected by this file's existence — the router is additive infrastructure
+# for whoever chooses to scale past one worker, never a default.
+require_relative "coercion"
+require_relative "router/hash_ring"
+require_relative "router/session_key"
+require_relative "router/backend_pool"
+require_relative "router/app"
+
+module Insika
+  module Router
+  end
+end

data/lib/insika/routing.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Insika
+  # WS4: intent routing as DATA. When `AgentProfile#routes` is present, the
+  # turn's message is classified into one of the configured routes with a cheap
+  # model BEFORE the agent chat is assembled. This class owns the PURE parts —
+  # normalizing the route config, generating the classifier prompt from the
+  # route descriptions, and parsing the model's answer back into a route — so
+  # they are testable without a provider. The ask itself and its usage are the
+  # Executor's (a pre-stage call counted in the turn's usage and trace).
+  #
+  # Config shape (string keys at the persistence boundary — the pack and the
+  # Studio store it like any other free-form hash):
+  #
+  #   { "shopping" => "the customer wants to browse products",
+  #     "order"    => { "description" => "asks about an existing order",
+  #                     "delegate" => "order-agent" },     # hand the turn to that agent
+  #     "human"    => { "description" => "the customer is frustrated or asks for a person",
+  #                     "stuck" => true, "message" => "..." }, # end the turn :stuck (WS5)
+  #     "default"  => "shopping",                            # deterministic fallback
+  #     "model"    => "deepseek-v4-flash" }                  # the CHEAP classifier
+  #
+  # `default`/`model`/`provider` are reserved top-level keys; everything else is
+  # a route name (single token). A route value is a description String or a Hash
+  # with `description` + optional `delegate` (an existing agent the turn is
+  # handed to) / `stuck` (the turn ends with the WS5 stuck outcome) / `message`
+  # (the consumer-facing lead-in for a stuck route).
+  class Routing
+    RESERVED = %w[model provider default].freeze
+    # A name the classifier can actually answer with: one lowercase token.
+    NAME = /\A[a-z0-9][a-z0-9_-]*\z/
+    # The turn's usage fields the classifier call can contribute.
+    TOKEN_FIELDS = %i[input_tokens output_tokens cached_tokens cache_creation_tokens total_tokens].freeze
+
+    Entry = Data.define(:name, :description, :delegate, :stuck, :message)
+
+    class << self
+      # -> { entries: [Entry], default: String, model: String, provider: String }
+      # | nil (routes absent/empty = routing off). Raises ValidationError on a
+      # route name the classifier could never answer with (spaces/symbols) or on
+      # a config with zero routes — a routing config that silently routes nothing
+      # is a config error, not a quiet off.
+      def normalize(routes)
+        return nil unless routes.is_a?(Hash) && !routes.empty?
+
+        bad = routes.keys.map(&:to_s).reject { |k| RESERVED.include?(k) || k.match?(NAME) }
+        unless bad.empty?
+          raise Insika::ValidationError,
+                "route names may not contain spaces or symbols: #{bad.join(', ')}"
+        end
+
+        entries = routes.each_with_object([]) do |(name, value), acc|
+          next if RESERVED.include?(name.to_s)
+
+          cfg = value.is_a?(Hash) ? stringify(value) : { "description" => value.to_s }
+          acc << Entry.new(name: name.to_s, description: cfg["description"].to_s,
+                           delegate: cfg["delegate"].to_s, stuck: cfg["stuck"] == true,
+                           message: cfg["message"].to_s)
+        end
+        raise Insika::ValidationError, "routes must define at least one route" if entries.empty?
+
+        default = routes["default"].to_s
+        default = entries.first.name if default.empty?
+        unless entries.any? { |e| e.name == default }
+          raise Insika::ValidationError,
+                "default route '#{default}' is not a configured route"
+        end
+        { entries: entries, default: default,
+          model: routes["model"].to_s, provider: routes["provider"].to_s }
+      end
+
+      # The classifier's instructions, auto-generated from the route descriptions
+      # (config-over-code: no per-route prompt file).
+      def classifier_prompt(meta)
+        lines = meta[:entries].map do |e|
+          "-#{e.name}: #{e.description.empty? ? e.name : e.description}"
+        end
+        <<~PROMPT
+          Classify the customer's message into exactly one of these intents.
+          Reply with ONLY the intent name — nothing else.
+
+          #{lines.join("\n")}
+        PROMPT
+      end
+
+      # -> Symbol: the route the model named; the DEFAULT when it named nothing
+      # usable (prose, punctuation, an unknown name, empty). Deterministic by
+      # construction — a chatty or confused classifier can never invent a route.
+      def parse(text, meta)
+        token = text.to_s.strip.split(/\s+/).first.to_s.downcase
+                    .delete_suffix(".").delete_suffix(",")
+        names = meta[:entries].map(&:name)
+        (names.include?(token) ? token : meta[:default]).to_sym
+      end
+    end
+
+    def self.stringify(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+  end
+end

data/lib/insika/safety/config.rb

@@ -16,8 +16,19 @@ module Insika
     #     moderator:  "provider/model"|nil,  # LLM moderator model; nil = deterministic only
     #     strictness: "low"|"medium"|"high", # which input categories fire (default medium)
     #     responses:  { <category> => "<safe reply>", ... }  # per-agent override, see below
+    #     corpora:    { "languages" => ["en"], "extra" => { "abuse" => ["/\\bdupa\\b/i"] } }
     #   }
     #
+    # `corpora`  is the removability knob for the shipped
+    # pt-BR corpus: `languages` filters the shipped families (nil = all,
+    # [] = none, ["en"] = the EN-only corpus — dropping the pt-BR input
+    # heuristics AND the CPF/CNPJ output redaction, a documented consequence),
+    # `extra` adds source-string patterns per family. Absent = the full
+    # shipped default, byte-for-byte today's behavior (parity). Validation
+    # fails loud (Insika::ValidationError naming the value): the doctor's
+    # guardrail-corpora check compiles every declaration, so a typo'd language
+    # surfaces at boot — `insika doctor` exits non-zero — never mid-turn.
+    #
     # `responses` is the CONFIGURATION-OVER-CONVENTION knob. The engine
     # ships neutral built-in refusals (Safety::SafeResponses::DEFAULTS), but this is
     # OSS across arbitrary businesses/languages, so we never hard-bake tone: an agent
@@ -37,14 +48,18 @@ module Insika
 
       DEFAULT_STRICTNESS = :medium
 
-      attr_reader :input, :output, :moderator, :strictness, :responses
+      attr_reader :input, :output, :moderator, :strictness, :responses, :corpora
 
-      def initialize(input:, output:, moderator:, strictness:, responses: {})
+      def initialize(input:, output:, moderator:, strictness:, responses: {}, corpora: nil)
         @input = input
         @output = output
         @moderator = moderator
         @strictness = strictness
         @responses = responses # { "category" => "safe reply" }, agent override map
+        @corpora = corpora     # { "languages" => [...]?, "extra" => {...}? } | nil (nil = the shipped default)
+        # Built ONCE at construction: the compiled corpus the whole turn reads.
+        @corpus = Corpus.compile(languages: corpora && corpora["languages"],
+                                 extra: (corpora && corpora["extra"]) || {})
       end
 
       # Builds a Config from a profile. A nil/empty `guardrails` -> the
@@ -58,10 +73,22 @@ module Insika
           output: bool(h.fetch(:output, true)),
           moderator: presence(h[:moderator]),
           strictness: normalize_strictness(h[:strictness]),
-          responses: normalize_responses(h[:responses])
+          responses: normalize_responses(h[:responses]),
+          corpora: normalize_corpora(h[:corpora])
         )
       end
 
+      # The compiled corpus for this agent  — never nil: absent
+      # corpora -> the full shipped default.
+      def corpus = @corpus
+
+      # The resolved corpus languages (for the doctor's enumeration, C3):
+      # nil corpora (or nil languages) = ALL shipped languages.
+      def corpus_languages
+        langs = @corpora && @corpora["languages"]
+        langs.nil? ? Corpus::DEFAULTS.keys : langs
+      end
+
       # Input categories the deterministic scan should run, per strictness.
       def input_categories = STRICTNESS_CATEGORIES.fetch(@strictness, STRICTNESS_CATEGORIES[DEFAULT_STRICTNESS])
 
@@ -103,7 +130,20 @@ module Insika
         end
       end
 
-      private_class_method :symbolize, :bool, :presence, :normalize_strictness, :normalize_responses
+      # `corpora` -> { "languages" => ...?, "extra" => ...? } with STRING keys |
+      # nil when absent/empty. Validation of the values happens in
+      # Corpus.compile (from_hash fails loud with the value named).
+      def self.normalize_corpora(v)
+        return nil unless v.is_a?(Hash)
+
+        h = v.each_with_object({}) { |(k, val), acc| acc[k.to_s] = val }
+        return nil if h["languages"].nil? && h["extra"].nil?
+
+        { "languages" => h["languages"], "extra" => h["extra"] }
+      end
+
+      private_class_method :symbolize, :bool, :presence, :normalize_strictness, :normalize_responses,
+                           :normalize_corpora
     end
   end
 end