insika 0.0.1 → 0.1.0

data/lib/insika/dsl.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative "pack"
+
+module Insika
+  # Public Ruby DSL (item 36 / §13.3) — the OSS "business card":
+  #
+  #   agent = Insika.agent("assistant") do
+  #     model "deepseek-chat"
+  #     instructions "You are a concise, friendly assistant."
+  #   end
+  #   puts agent.reply("hi, what can you do?")   # one turn, in-process
+  #   agent.serve                                # control UI + /v1 on :9292
+  #
+  # It is THIN SUGAR that GENERATES the data (a Insika::Pack), never a bypass of
+  # config-over-code (COMPETITIVE-ANALYSIS §4.1). `Insika.agent { … }.to_pack`
+  # is the same portable artifact the PackImporter consumes at runtime — the DSL
+  # and a hand-written pack produce the SAME profile (the parity spec proves it),
+  # because BOTH go through the standard import → StoredProfileSource round-trip.
+  #
+  # Nothing here loads ruby_llm or the HTTP server: `require "insika"` stays light.
+  # The runtime (chat/serve) is pulled in lazily by Definition (dsl/runtime.rb).
+  module DSL
+    module_function
+
+    # Insika.agent("id") { … } → Definition (see #agent below on the module).
+    def agent(id, &block)
+      Builder.new(id).build(&block)
+    end
+
+    # Insika.system { agent("a") { … }; agent("b") { … } } → System.
+    def system(&block)
+      SystemBuilder.new.build(&block)
+    end
+
+    # Insika.embed(backend:) { … } → System (see #embed below on the module).
+    def embed(backend:, &block)
+      SystemBuilder.new.build(backend: backend, &block)
+    end
+
+    # Collects several agents into ONE runtime. A single agent is a Definition;
+    # more than one needs a container, because delegation (`subagents`) and any
+    # multi-agent pattern only mean something when the children live in the same
+    # graph. It adds no new engine path: each agent is still its own Pack,
+    # imported through the standard PackImporter.
+    class SystemBuilder
+      def initialize
+        @definitions = []
+        @workflows = []
+        @runtime = {}
+      end
+
+      def build(backend: nil, &block)
+        instance_eval(&block) if block
+        raise ArgumentError, "Insika.system needs at least one agent" if @definitions.empty?
+
+        System.new(definitions: @definitions, workflows: @workflows, runtime: @runtime, backend: backend)
+      end
+
+      # Declares one agent — the SAME block the standalone `Insika.agent` takes.
+      # Returns its Definition, so a script can keep a handle if it wants one.
+      def agent(id, &block)
+        definition = Builder.new(id).build(&block)
+        if @definitions.any? { |d| d.id == definition.id }
+          raise ArgumentError, "duplicate agent id in system: #{definition.id}"
+        end
+
+        @definitions << definition
+        definition
+      end
+
+      # Declares a WORKFLOW: deterministic Ruby orchestrating agent turns, for the
+      # shapes a single tool-loop should not decide on its own — chaining, routing,
+      # evaluate-and-retry. It is registered in the same WorkflowRegistry a
+      # deployment uses, so it gets a durable run (the run id IS a Task),
+      # `:workflow_started`/`:workflow_completed` on the event stream, and — when
+      # served — `GET /v1/workflows` + `POST /v1/workflows/:name`.
+      #
+      #   workflow "draft", input: { type: "object", required: ["topic"], … } do |input, ctx|
+      #     draft = ctx.ask("writer", "Write about #{input['topic']}")
+      #     ctx.ask("editor", "Tighten this:\n#{draft}")
+      #   end
+      #
+      # `input:`/`output:` take a JSON Schema Hash (validated by the engine's
+      # zero-dep validator) or any dry-schema-compatible `#call`-able. A bad input
+      # is refused synchronously, with NO run created.
+      def workflow(name, description: nil, input: nil, output: nil, &block)
+        raise ArgumentError, "workflow '#{name}' needs a block" if block.nil?
+
+        name = name.to_s
+        raise ArgumentError, "duplicate workflow in system: #{name}" if @workflows.any? { |w| w[:name] == name }
+
+        @workflows << { name: name, description: description,
+                        input_schema: input, output_schema: output, block: block }
+        name
+      end
+
+      # System-wide runtime knobs (NOT part of any pack): they configure the LLM
+      # clients for every agent. A per-agent `provider` still wins for that agent;
+      # this is the default and the place to put a shared key.
+      def provider(name) = @runtime[:provider] = name.to_s
+      def api_key(value) = @runtime[:api_key] = value.to_s
+      def api_base(value) = @runtime[:api_base] = value.to_s
+    end
+
+    # Collects the declarations and emits a Insika::Pack. Declarations map 1:1 to
+    # the pack manifest (AgentProfile.build attrs) + the pack's files/skills/tools —
+    # so what you write is exactly the data the engine stores.
+    class Builder
+      def initialize(id)
+        @id = id.to_s
+        @config = {}
+        @files = {}
+        @skills = {}
+        @tools = []
+        # Auto-enable the allowlist policies: harmless when the allowlist is nil=all,
+        # correct once you restrict tools/skills. Visible in #to_pack — no hidden magic.
+        @config[:policies] = %i[tool_allowlist skill_allowlist]
+        @runtime = {} # non-pack knobs (llm provider/key/base) consumed by the runtime
+      end
+
+      def build(&block)
+        instance_eval(&block) if block
+        Definition.new(pack: to_pack, runtime: @runtime)
+      end
+
+      # --- identity & model ------------------------------------------------
+      def model(name) = @config[:model] = name.to_s
+
+      # Provider for both the profile AND the RubyLLM configuration at run time.
+      def provider(name)
+        @config[:provider] = name.to_s
+        @runtime[:provider] ||= name.to_s
+      end
+
+      def instructions(text) = @config[:base_prompt] = text.to_s
+      alias_method :prompt, :instructions
+
+      # An extra prompt FILE (identity fragment). Name = the file name (e.g. "SOUL.md").
+      def prompt_file(name, content)
+        @files[name.to_s] = content.to_s
+      end
+
+      # --- tools -----------------------------------------------------------
+      # tools "a", "b"  → allowlist [names]. Not called → nil = all (parity).
+      def tools(*names)
+        @config[:tools_allow] = names.flatten.map(&:to_s)
+      end
+
+      def deny_tools(*names)
+        @config[:tools_deny] = names.flatten.map(&:to_s)
+      end
+
+      # A DATA-DEFINED (declarative HTTP) tool — pure config-over-code. `defn` is a
+      # ToolDefinition hash (name/description/parameters/binding…). Its name is
+      # auto-added to the allowlist so the agent can call its own tool (NF2).
+      def data_tool(defn)
+        h = defn.transform_keys(&:to_s)
+        @tools << h
+        name = h["name"].to_s
+        (@config[:tools_allow] ||= []) << name unless name.empty? || Array(@config[:tools_allow]).include?(name)
+        h
+      end
+
+      # --- skills ----------------------------------------------------------
+      # skill "escalate", "<full SKILL.md>"  — or —
+      # skill "escalate", description: "…", instructions: "…"
+      # The name is auto-added to the agent's skill allowlist.
+      def skill(name, content = nil, description: nil, instructions: nil)
+        n = name.to_s
+        @skills[n] = normalize_skill(n, content, description, instructions)
+        (@config[:skills] ||= []) << n unless @config.fetch(:skills, []).include?(n)
+        n
+      end
+
+      # --- delegation ------------------------------------------------------
+      # subagents "security", "performance" → the child agents this one MAY
+      # spawn (RFC-0010). CAPACITY field: opt-in, never inherited, and the ids
+      # must be agents of the same system (`Insika.system { … }`) or already in
+      # the store. Present ⇒ the engine wires `spawn_subagent`/`spawn_subagents`.
+      def subagents(*ids)
+        @config[:subagents] = ids.flatten.map(&:to_s)
+      end
+
+      # --- knobs -----------------------------------------------------------
+      def memory(on = true) = @config[:memory] = on
+
+      # Content-safety guardrails (RFC-0009) — opt-in and configurable per agent.
+      # Pure config-over-code: the hash is stored on the profile and consumed by
+      # Safety::Config.from_profile. Merges, so repeated calls accumulate.
+      #   guardrails input: true, output: true, strictness: "medium",
+      #              moderator: "deepseek/deepseek-chat",
+      #              responses: { "injection" => "I can't help with that." }
+      def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Refinement (RFC-0013) — how the agent's own instruction files may be
+      # improved from real traffic. Same config-over-code shape as `guardrails`;
+      # omitting it entirely leaves the agent report-only (phase A writes nothing).
+      #   refine mode: "propose", window: { last_sessions: 200 }, files: %w[TOOLS.md],
+      #          proposers: ["deepseek/deepseek-chat", "gpt-5-mini"],
+      #          budget: { tokens: 200_000 }
+      def refine(hash) = (@config[:refinement] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Facts about THIS deployment that are not tools (RFC-0014 §3.5), so an eval
+      # case can declare what it needs and be skipped where it is absent instead of
+      # failing for the wrong reason.
+      #   declares "promotions", "human_handoff"
+      def declares(*names)
+        (@config[:capabilities_declared] ||= []).concat(names.flatten.map(&:to_s))
+      end
+
+      # Which internal channels may cross to the CUSTOMER. Both off by default: the
+      # answer is the answer, and the provider's reasoning (`thinking`) or the model
+      # narrating its tool loop (`intermediate`) is for the Studio and the trace.
+      # Each opted-in channel gets its OWN frame type at `/v1/responses` — never the
+      # answer's — so a consumer that only reads the answer is unaffected either way.
+      #   edge_stream thinking: true, intermediate: false
+      def edge_stream(hash) = (@config[:edge_stream] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # LLM generation params (v2, §10). `param :temperature, 0.2` or `params(...)`.
+      def param(key, value) = (@config[:params] ||= {})[key.to_sym] = value
+      def params(hash) = (@config[:params] ||= {}).merge!(hash.transform_keys(&:to_sym))
+      def temperature(value) = param(:temperature, value)
+      def max_tokens(value) = param(:max_tokens, value)
+
+      # Per-agent limits (timeouts/budgets). `limit :turn_timeout, 120` or `limits(...)`.
+      def limit(key, value) = (@config[:limits] ||= {})[key.to_sym] = value
+      def limits(hash) = (@config[:limits] ||= {}).merge!(hash.transform_keys(&:to_sym))
+
+      def policies(*names) = @config[:policies] = names.flatten.map(&:to_sym)
+      def metadata(hash) = (@config[:metadata] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # --- runtime (LLM provider) config — NOT part of the pack ------------
+      # Configures RubyLLM at chat/serve time. Defaults: provider = the agent's
+      # provider; key = ENV["<PROVIDER>_API_KEY"].
+      def api_key(value) = @runtime[:api_key] = value.to_s
+      def api_base(value) = @runtime[:api_base] = value.to_s
+
+      # The generated portable artifact — the heart of "generates the data".
+      def to_pack
+        Insika::Pack.from_h(
+          config: @config.merge(id: @id),
+          files: @files, skills: @skills, tools: @tools
+        )
+      end
+
+      private
+
+      # Ensure the skill body is a valid SKILL.md (YAML frontmatter with `name`),
+      # which is what SkillCatalog parses. Raw content with frontmatter passes
+      # through untouched; a bare body / structured args get wrapped.
+      def normalize_skill(name, content, description, instructions)
+        return content.to_s if content.is_a?(String) && content.lstrip.start_with?("---")
+
+        body = (instructions || content).to_s
+        desc = (description || first_line(body) || name).to_s
+        <<~SKILL
+          ---
+          name: #{name}
+          description: #{desc}
+          ---
+
+          #{body}
+        SKILL
+      end
+
+      def first_line(text) = text.to_s.strip.lines.first&.strip
+    end
+  end
+
+  module_function
+
+  # Top-level entry point (see Insika::DSL). Returns a Insika::DSL::Definition.
+  def agent(id, &block)
+    DSL.agent(id, &block)
+  end
+
+  # Several agents in one runtime — the shape every multi-agent pattern needs
+  # (delegation, fan-out/fan-in, routing). Returns a Insika::DSL::System.
+  def system(&block)
+    DSL.system(&block)
+  end
+
+  # RFC-0017 A1 — the front door for MOUNTING Insika into an app you already
+  # have. Same block as `Insika.system`, one added obligation: the caller names
+  # the store, so the graph stops discovering it from `INSIKA_DB` and two graphs
+  # in one process can no longer read each other's sessions.
+  #
+  #   INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: "storage/insika.sqlite3")) do
+  #     agent "support" do
+  #       model "deepseek-chat"
+  #       instructions "…"
+  #     end
+  #   end
+  #   # config/routes.rb — mount the /v1 transport as a value:
+  #   mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
+  #
+  # It is a thin front door over the SAME assembly `Insika.system` uses — there is
+  # one pipeline (RFC-0001), and the parity spec holds it to that. What an embedded
+  # graph owns, and what it still shares with the process, is docs/EMBEDDING.md.
+  def embed(backend:, &block)
+    DSL.embed(backend: backend, &block)
+  end
+end
+
+require_relative "dsl/definition"
+require_relative "dsl/system"

data/lib/insika/edge_limiter.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "middleware"
+require_relative "coercion"
+
+module Insika
+  # The production edge (item 33 / §12 G7): THE named place where volume/cost
+  # abuse is cut. A Middleware with two independent limits, both OPT-IN
+  # (nil/0 = off — a bare wiring behaves exactly as before):
+  #
+  #   · chat rate limit    — turn ATTEMPTS per chat per window. Counted on entry
+  #     (a blocked attempt still counts), so a flood keeps hitting the wall.
+  #   · agent token ceiling — total tokens per agent per window. Checked on entry
+  #     against the accumulated ledger; the turn's own usage is recorded AFTER the
+  #     terminal returns (the Middleware wraps stages 5-9, so state.usage is set).
+  #
+  # Config resolution, per turn (configuration over convention):
+  #   profile.limits[:chat_rate_limit / :agent_token_ceiling]  — per-agent override
+  #   settings["edge"]                                          — platform default
+  # A per-agent 0 explicitly disables a platform default for that agent.
+  #
+  # On breach it uses the graceful-halt contract (RFC-0009 §3.1): halt_response
+  # (the safe reply) + guardrail_block (audit -> :guardrail_blocked) and does NOT
+  # call `nxt` — the turn completes with ZERO LLM calls. It sits BEFORE the
+  # InputGuardrail in the stack so a flood can't spend the LLM moderator either.
+  class EdgeLimiter < Middleware
+    CHAT_KIND   = "chat"
+    TOKENS_KIND = "tokens"
+
+    DEFAULT_CHAT_WINDOW   = 60      # seconds
+    DEFAULT_TOKEN_WINDOW  = 86_400  # seconds (daily ceiling)
+
+    # Neutral fallback, same contract as Safety::SafeResponses (pt-BR — the
+    # pilot's language; override via settings edge.limit_response).
+    DEFAULT_RESPONSE = "Estou recebendo muitas mensagens agora. Aguarde um " \
+                       "momento e tente novamente, por favor."
+
+    def initialize(ledger:, settings_store: nil)
+      @ledger = ledger
+      @settings = settings_store
+    end
+
+    def call(state, &nxt)
+      edge = platform_edge
+      limits = state.profile.limits || {}
+      # A resume (crash/pause recovery) re-enters the pipeline for a turn that was
+      # ALREADY admitted: re-counting it would swallow a legitimate message with
+      # the rate-limit reply exactly when the window is saturated. Entry checks
+      # are skipped; the turn's usage still lands on the ledger below.
+      resumed = state.resumed
+
+      if !resumed && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
+        breach = check_chat_rate(state, limit, edge)
+        return block(state, edge, **breach) if breach
+      end
+
+      # NB: a per-agent key PRESENT with nil (e.g. an imported pack carrying
+      # `"chat_rate_limit": null`) reads as OFF for that agent, not "inherit".
+      if (ceiling = positive(limits.key?(:agent_token_ceiling) ? limits[:agent_token_ceiling] : edge["agent_token_ceiling"]))
+        token_window = positive(edge["agent_token_window"]) || DEFAULT_TOKEN_WINDOW
+        unless resumed
+          spent = @ledger.count(TOKENS_KIND, state.profile.id.to_s, window: token_window)
+          if spent >= ceiling
+            return block(state, edge, category: :token_ceiling,
+                                      detail: "agent #{state.profile.id}: #{spent}/#{ceiling} tokens per #{token_window}s")
+          end
+        end
+
+        record_after = token_window
+      end
+
+      result = nxt.call(state)
+      record_usage(state, record_after) if record_after
+      result
+    end
+
+    private
+
+    # One KV get per turn (same order of cost as the guardrail's config read);
+    # no SettingsStore in the wiring -> per-agent limits only.
+    def platform_edge
+      (@settings&.get || {})["edge"] || {}
+    end
+
+    # Counts the ATTEMPT first, then compares — the standard fixed-window
+    # semantics (blocked attempts keep counting). A blank chat id is skipped:
+    # unrelated anonymous traffic must not share one bucket.
+    def check_chat_rate(state, limit, edge)
+      chat_id = (state.turn_context || {})[:chat_id].to_s
+      return nil if chat_id.empty?
+
+      window = positive(edge["chat_rate_window"]) || DEFAULT_CHAT_WINDOW
+      taken = @ledger.add(CHAT_KIND, chat_id, window: window)
+      return nil if taken <= limit
+
+      { category: :rate_limit, detail: "chat #{chat_id}: #{taken}/#{limit} turns per #{window}s" }
+    end
+
+    # The turn's real spend, accumulated on the agent's ledger. The engine's
+    # `total_tokens` is input + output and DELIBERATELY excludes the cached
+    # prefix (`Executor#usage_of` reports `cached_tokens`/`cache_creation_tokens`
+    # alongside it) — on a cached identity that prefix is ~95% of what the
+    # provider actually processed, so a ceiling reading only `total_tokens` is
+    # blind (RFC-0016 A4). Same billed-spend rule as `Evals::Runner#billed_tokens`.
+    # nil usage (workflow turn / provider without counts) records nothing.
+    def record_usage(state, window)
+      usage = state.usage || {}
+      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
+               usage[:cache_creation_tokens].to_i
+      return if tokens.zero?
+
+      @ledger.add(TOKENS_KIND, state.profile.id.to_s, window: window, by: tokens)
+    end
+
+    # Graceful halt: safe reply + audit metadata, short-circuit (no nxt).
+    # `detail` carries only ids/counters — never message content.
+    def block(state, edge, category:, detail:)
+      state.halt_response = Coercion.presence(edge["limit_response"]) || DEFAULT_RESPONSE
+      state.guardrail_block = {
+        category: category.to_s, source: "edge", action: "refuse", detail: detail
+      }
+      nil
+    end
+
+    def positive(value)
+      v = value.to_i
+      v.positive? ? v : nil
+    end
+  end
+end

data/lib/insika/egress_guard.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "uri"
+require "ipaddr"
+require "resolv"
+
+module Insika
+  # EGRESS guard for data-tools (SSRF). A data-tool makes a server-side HTTP
+  # request with a URL coming from UI-editable config — without a guard, it's an
+  # SSRF vector (hitting cloud metadata, internal services, localhost). Rules
+  # (spec NF2):
+  #   - https only by default (http requires explicit opt-in);
+  #   - host required;
+  #   - optional host allowlist (when present, only it passes);
+  #   - resolves the host and BLOCKS if ANY address falls into a private/
+  #     loopback/link-local/metadata network (defense against DNS rebinding);
+  #   - `allow_private:` (opt-in) ALLOWS the private target — to reach a trusted
+  #     INTERNAL API (NF4: the consumer's /api/internal/* comes in via an
+  #     allowlist). Dangerous without `host_allowlist`: PIN it to a known host.
+  #     Default false = strict guard.
+  #
+  # `violation(url, ...)` returns nil (ok) or a String with the reason — the
+  # DataDefinedTool turns the reason into `{ error: }` to the model (never raises).
+  module EgressGuard
+    BLOCKED = [
+      "0.0.0.0/8", "10.0.0.0/8", "100.64.0.0/10", "127.0.0.0/8",
+      "169.254.0.0/16", "172.16.0.0/12", "192.0.0.0/24", "192.168.0.0/16",
+      "198.18.0.0/15", "::1/128", "fc00::/7", "fe80::/10", "::ffff:0:0/96"
+    ].map { |c| IPAddr.new(c) }.freeze
+
+    module_function
+
+    # -> nil (allowed) | String (block reason).
+    def violation(url, allow_http: false, host_allowlist: nil, allow_private: false)
+      uri = begin
+        URI.parse(url.to_s)
+      rescue URI::InvalidURIError
+        return "invalid URL"
+      end
+
+      return "unsupported scheme" unless %w[http https].include?(uri.scheme)
+      return "http not allowed (use https)" if uri.scheme == "http" && !allow_http
+
+      host = uri.host
+      return "missing host" if host.nil? || host.empty?
+      return "host not in allowlist" if host_allowlist && !host_allowlist.include?(host)
+
+      addrs = resolve(host)
+      return "host did not resolve" if addrs.empty?
+      # allow_private skips the private-network block (trusted internal API,
+      # NF4). Without it, a private/loopback/metadata target is always blocked.
+      return "private-network destination blocked" if !allow_private && addrs.any? { |ip| blocked?(ip) }
+
+      nil
+    end
+
+    # Literal host (IP) -> itself; hostname -> resolve via DNS. -> [IPAddr].
+    def resolve(host)
+      literal = ip_or_nil(host.delete_prefix("[").delete_suffix("]"))
+      return [literal] if literal
+
+      Resolv.getaddresses(host).filter_map { |a| ip_or_nil(a) }
+    rescue Resolv::ResolvError, SocketError
+      []
+    end
+
+    def blocked?(ip) = BLOCKED.any? { |net| net.include?(ip) }
+
+    def ip_or_nil(str)
+      IPAddr.new(str)
+    rescue IPAddr::InvalidAddressError
+      nil
+    end
+  end
+end