znyx-sdk 1.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 816193b73770d4949028adf8359e4e402aa8cdd2fc9a2f39235ea9bc47acc946
+  data.tar.gz: 4cff940a92b4b7905422405a09a70e6f08864d08f318adb8e20c58e2ce5e3a8f
+SHA512:
+  metadata.gz: 71e56c056f15328e7f7cb1a83177906755f6fbb8e5279700b593673f09a49b04ab7754a611fc5f660e47bde51975491f35155377270f51da190942f3286ea3ad
+  data.tar.gz: fb7938b04ed59c4b2b3d51c6245b25f1a0ca58b0b5329fff2096a96b732d2f31c76f48dee14cfa3f72958791114e7af6b5bbb709b30b519e3c40474429324d53

data/lib/znyx_sdk/client.rb

@@ -0,0 +1,113 @@
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module ZnyxSdk
+  # Official Ruby SDK for the ZNYX Runtime guardrails API.
+  #
+  # @example
+  #   client = ZnyxSdk::Client.new("http://localhost:8080")
+  #
+  #   result = client.evaluate_input(
+  #     tenant_id: "my-org",
+  #     app_id:    "my-app",
+  #     text:      user_message
+  #   )
+  #   raise result.user_message if result.blocked?
+  #
+  class Client
+    # @param base_url [String] URL of the running ZNYX Runtime (e.g. "http://localhost:8080")
+    # @param api_key  [String, nil] Optional API key sent as Authorization: Bearer
+    # @param timeout  [Integer] HTTP read/open timeout in seconds (default: 10)
+    def initialize(base_url, api_key: nil, timeout: 10)
+      @uri     = URI.parse(base_url.chomp("/"))
+      @api_key = api_key
+      @timeout = timeout
+
+      # Anonymous, opt-out install telemetry (ZNYX_TELEMETRY=false to disable).
+      begin
+        Telemetry.maybe_send_install_ping
+      rescue StandardError
+        # telemetry must never break client construction
+      end
+    end
+
+    # Evaluates a user prompt before sending it to the LLM.
+    #
+    # @param text      [String] The text to evaluate
+    # @param tenant_id [String]
+    # @param app_id    [String]
+    # @param kwargs    [Hash]   Optional: agent_id, env, trace_id, session_id, metadata
+    # @return [EvaluationResponse]
+    def evaluate_input(text:, tenant_id: "default", app_id: "default", **kwargs)
+      post("/v1/evaluate/input", build_payload(text: text, tenant_id: tenant_id, app_id: app_id, **kwargs))
+    end
+
+    # Evaluates an LLM response before returning it to the user.
+    def evaluate_output(text:, tenant_id: "default", app_id: "default", **kwargs)
+      post("/v1/evaluate/output", build_payload(text: text, tenant_id: tenant_id, app_id: app_id, **kwargs))
+    end
+
+    # Evaluates a tool call before executing it.
+    #
+    # @param tool_name [String]
+    # @param tool_args [Hash]
+    def evaluate_tool(tool_name:, tool_args:, tenant_id: "default", app_id: "default", **kwargs)
+      payload = {
+        request_id: new_request_id,
+        tenant_id:  tenant_id,
+        app_id:     app_id,
+        agent_id:   kwargs.delete(:agent_id) || "default",
+        env:        kwargs.delete(:env)      || "prod",
+        tool_name:  tool_name,
+        tool_args:  tool_args,
+      }.merge(kwargs.compact)
+      post("/v1/evaluate/tool", payload)
+    end
+
+    private
+
+    def build_payload(text:, tenant_id:, app_id:, **kwargs)
+      {
+        request_id: new_request_id,
+        tenant_id:  tenant_id,
+        app_id:     app_id,
+        agent_id:   kwargs.delete(:agent_id) || "default",
+        env:        kwargs.delete(:env)      || "prod",
+        text:       text,
+      }.merge(kwargs.compact)
+    end
+
+    def post(path, payload)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl     = @uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      request = Net::HTTP::Post.new(path)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}" if @api_key
+      request.body = JSON.generate(payload)
+
+      response = http.request(request)
+
+      if response.code.to_i >= 400
+        raise ZnyxError.new(
+          "ZNYX Runtime returned #{response.code}: #{response.body}",
+          status_code: response.code.to_i
+        )
+      end
+
+      EvaluationResponse.new(JSON.parse(response.body))
+    rescue ZnyxError
+      raise
+    rescue => e
+      raise ZnyxError, "HTTP request failed: #{e.message}"
+    end
+
+    def new_request_id
+      "req_#{SecureRandom.hex(4)}"
+    end
+  end
+end

data/lib/znyx_sdk/models.rb

@@ -0,0 +1,65 @@
+module ZnyxSdk
+  DECISIONS = %w[ALLOW BLOCK REDACT WARN TRANSFORM].freeze
+
+  # Immutable value object returned by all evaluate methods.
+  class EvaluationResponse
+    attr_reader :request_id, :decision, :risk_score, :policy_version,
+                :rule_hits, :sanitized_text, :user_message,
+                :developer_message, :latency_ms, :trace_id, :session_id,
+                :detector_results
+
+    def initialize(data)
+      @request_id        = data["request_id"]
+      @decision          = data["decision"]
+      @risk_score        = data["risk_score"].to_i
+      @policy_version    = data["policy_version"]
+      @rule_hits         = Array(data["rule_hits"]).map { |h| RuleHit.new(h) }
+      @sanitized_text    = data["sanitized_text"]
+      @user_message      = data["user_message"]
+      @developer_message = data["developer_message"]
+      @latency_ms        = data["latency_ms"].to_i
+      @trace_id          = data["trace_id"]
+      @session_id        = data["session_id"]
+      @detector_results  = Array(data["detector_results"]).map { |d| DetectorResult.new(d) }
+    end
+
+    def blocked?   = @decision == "BLOCK"
+    def redacted?  = @decision == "REDACT"
+
+    # Returns sanitized_text if present, otherwise the original string.
+    def safe_text(original)
+      sanitized_text.nil? || sanitized_text.empty? ? original : sanitized_text
+    end
+  end
+
+  class RuleHit
+    attr_reader :rule_id, :severity, :message
+
+    def initialize(data)
+      @rule_id  = data["rule_id"]
+      @severity = data["severity"]
+      @message  = data["message"]
+    end
+  end
+
+  class DetectorResult
+    attr_reader :detector_name, :decision, :risk_score, :latency_ms, :rule_hits
+
+    def initialize(data)
+      @detector_name = data["detector_name"]
+      @decision      = data["decision"]
+      @risk_score    = data["risk_score"].to_i
+      @latency_ms    = data["latency_ms"].to_i
+      @rule_hits     = Array(data["rule_hits"]).map { |h| RuleHit.new(h) }
+    end
+  end
+
+  class ZnyxError < StandardError
+    attr_reader :status_code
+
+    def initialize(message, status_code: nil)
+      super(message)
+      @status_code = status_code
+    end
+  end
+end

data/lib/znyx_sdk/telemetry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+require "rbconfig"
+require "time"
+require "fileutils"
+
+module ZnyxSdk
+  # Anonymous install telemetry for the ZNYX Ruby SDK.
+  #
+  # Sends a single fire-and-forget ping when a client is first constructed, then
+  # at most one "heartbeat" ping per 24h. Non-sensitive metadata only:
+  # install_id (random UUID, persisted to ~/.znyx/sdk-state.json), SDK version,
+  # source ("ruby-sdk"), OS / arch / Ruby version, run_count.
+  #
+  # No PII, no request content, no tenant data. Opt out with
+  # ZNYX_TELEMETRY=false (on by default). Disclosed once to stderr on the first
+  # run. Every operation is best-effort — telemetry must never slow down, block,
+  # or break the calling application. See TELEMETRY.md.
+  module Telemetry
+    # Telemetry endpoint. Defaults to the ZNYX production receiver so anonymous
+    # install telemetry is on out of the box (opt-out, fully transparent).
+    # Override with ZNYX_TELEMETRY_URL (or ZNYX_HEARTBEAT_URL), or opt out with
+    # ZNYX_TELEMETRY=false.
+    ENDPOINT = (
+      (ENV["ZNYX_TELEMETRY_URL"] || "").empty? ? nil : ENV["ZNYX_TELEMETRY_URL"]
+    ) || (
+      (ENV["ZNYX_HEARTBEAT_URL"] || "").empty? ? nil : ENV["ZNYX_HEARTBEAT_URL"]
+    ) || "https://cp.znyx.ai/v1/install-telemetry"
+
+    STATE_FILE = File.join(Dir.home, ".znyx", "sdk-state.json")
+    HEARTBEAT_INTERVAL = 86_400 # seconds (24h)
+    SOURCE = "ruby-sdk"
+
+    DISCLOSURE =
+      "[znyx-sdk] Anonymous usage telemetry is on (install id, SDK version, OS - " \
+      "no PII, no request content). Opt out with ZNYX_TELEMETRY=false."
+
+    @attempted = false
+
+    class << self
+      # Send an anonymous install ping, throttled to once per 24h. Fire-and-forget.
+      def maybe_send_install_ping
+        return if @attempted
+
+        @attempted = true
+
+        return if ENDPOINT.to_s.empty? || !enabled?
+
+        state = load_state
+        last_ping = state["last_ping_at"]
+
+        if last_ping.nil?
+          event_type = "first_run"
+        else
+          begin
+            elapsed = Time.now - Time.iso8601(last_ping)
+          rescue StandardError
+            elapsed = HEARTBEAT_INTERVAL # unparseable -> treat as due
+          end
+          return if elapsed < HEARTBEAT_INTERVAL
+
+          event_type = "heartbeat"
+        end
+
+        install_id = state["install_id"] || SecureRandom.uuid
+        run_count  = (state["run_count"] || 0).to_i + 1
+        now_iso    = Time.now.utc.iso8601
+
+        state.merge!(
+          "install_id"    => install_id,
+          "first_seen_at" => state["first_seen_at"] || now_iso,
+          "last_ping_at"  => now_iso,
+          "run_count"     => run_count
+        )
+        save_state(state)
+
+        if event_type == "first_run"
+          begin
+            warn DISCLOSURE
+          rescue StandardError
+            # ignore
+          end
+        end
+
+        payload = {
+          install_id:   install_id,
+          version:      version,
+          event_type:   event_type,
+          source:       SOURCE,
+          os:           RbConfig::CONFIG["host_os"],
+          os_version:   host_os_version,
+          arch:         RbConfig::CONFIG["host_cpu"],
+          ruby_version: RUBY_VERSION,
+          run_count:    run_count,
+          timestamp:    now_iso
+        }
+
+        Thread.new { post(payload) }
+      rescue StandardError
+        # Telemetry must never break client construction.
+      end
+
+      private
+
+      def enabled?
+        val = (ENV["ZNYX_TELEMETRY"] || ENV["GUARDRAILS_TELEMETRY"] || "true").downcase
+        !%w[false 0 no].include?(val)
+      end
+
+      def version
+        defined?(ZnyxSdk::VERSION) ? ZnyxSdk::VERSION : "unknown"
+      end
+
+      def host_os_version
+        `uname -r`.strip
+      rescue StandardError
+        "unknown"
+      end
+
+      def load_state
+        return {} unless File.exist?(STATE_FILE)
+
+        JSON.parse(File.read(STATE_FILE))
+      rescue StandardError
+        {}
+      end
+
+      def save_state(state)
+        FileUtils.mkdir_p(File.dirname(STATE_FILE))
+        File.write(STATE_FILE, JSON.pretty_generate(state))
+      rescue StandardError
+        # best-effort; never raise
+      end
+
+      def post(payload)
+        uri = URI.parse(ENDPOINT)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 3
+        http.read_timeout = 3
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(payload)
+
+        http.request(request)
+      rescue StandardError
+        # never fail the app because of telemetry
+      end
+    end
+  end
+end

data/lib/znyx_sdk.rb

@@ -0,0 +1,7 @@
+require_relative "znyx_sdk/models"
+require_relative "znyx_sdk/client"
+require_relative "znyx_sdk/telemetry"
+
+module ZnyxSdk
+  VERSION = "1.0.1"
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: znyx-sdk
+version: !ruby/object:Gem::Version
+  version: 1.2.1
+platform: ruby
+authors:
+- Zitrino
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- community@zitrino.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/znyx_sdk.rb
+- lib/znyx_sdk/client.rb
+- lib/znyx_sdk/models.rb
+- lib/znyx_sdk/telemetry.rb
+homepage: https://znyx.ai
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/zitrino-oss/znyx-sdk
+  bug_tracker_uri: https://github.com/zitrino-oss/znyx-sdk/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the ZNYX Runtime guardrails API
+test_files: []