tork-governance 0.1.0

data/lib/tork/configuration.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Tork
+  # Configuration class for Tork SDK
+  class Configuration
+    # @return [String] The API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] The base URL for the Tork API
+    attr_accessor :base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Maximum number of retries for failed requests
+    attr_accessor :max_retries
+
+    # @return [Float] Base delay for exponential backoff (in seconds)
+    attr_accessor :retry_base_delay
+
+    # @return [Float] Maximum delay between retries (in seconds)
+    attr_accessor :retry_max_delay
+
+    # @return [Boolean] Whether to raise on rate limit or return error response
+    attr_accessor :raise_on_rate_limit
+
+    # @return [Logger, nil] Logger instance for debugging
+    attr_accessor :logger
+
+    # @return [String, nil] Custom user agent string
+    attr_accessor :user_agent
+
+    # Default configuration values
+    DEFAULTS = {
+      base_url: "https://api.tork.network/v1",
+      timeout: 30,
+      max_retries: 3,
+      retry_base_delay: 0.5,
+      retry_max_delay: 30.0,
+      raise_on_rate_limit: true,
+      logger: nil,
+      user_agent: nil
+    }.freeze
+
+    def initialize
+      DEFAULTS.each do |key, value|
+        send("#{key}=", value)
+      end
+      @api_key = ENV["TORK_API_KEY"]
+    end
+
+    # Validate the configuration
+    # @raise [Tork::AuthenticationError] if API key is missing
+    def validate!
+      raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      DEFAULTS.each do |key, value|
+        send("#{key}=", value)
+      end
+      @api_key = ENV["TORK_API_KEY"]
+    end
+
+    # Build user agent string
+    # @return [String]
+    def full_user_agent
+      base = "tork-ruby/#{Tork::VERSION} Ruby/#{RUBY_VERSION}"
+      user_agent ? "#{user_agent} #{base}" : base
+    end
+  end
+end

data/lib/tork/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Tork
+  # Base error class for all Tork errors
+  class Error < StandardError
+    attr_reader :http_status, :code, :details
+
+    def initialize(message = nil, http_status: nil, code: nil, details: nil)
+      @http_status = http_status
+      @code = code
+      @details = details
+      super(message)
+    end
+  end
+
+  # Raised when API authentication fails
+  class AuthenticationError < Error
+    def initialize(message = "Invalid or missing API key")
+      super(message, http_status: 401, code: "AUTHENTICATION_ERROR")
+    end
+  end
+
+  # Raised when rate limit is exceeded
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil)
+      @retry_after = retry_after
+      super(message, http_status: 429, code: "RATE_LIMIT_ERROR")
+    end
+  end
+
+  # Raised when a resource is not found
+  class NotFoundError < Error
+    def initialize(message = "Resource not found")
+      super(message, http_status: 404, code: "NOT_FOUND")
+    end
+  end
+
+  # Raised when request validation fails
+  class ValidationError < Error
+    def initialize(message = "Validation failed", details: nil)
+      super(message, http_status: 400, code: "VALIDATION_ERROR", details: details)
+    end
+  end
+
+  # Raised when the server returns an error
+  class ServerError < Error
+    def initialize(message = "Server error")
+      super(message, http_status: 500, code: "SERVER_ERROR")
+    end
+  end
+
+  # Raised when a request times out
+  class TimeoutError < Error
+    def initialize(message = "Request timed out")
+      super(message, code: "TIMEOUT_ERROR")
+    end
+  end
+
+  # Raised when a connection cannot be established
+  class ConnectionError < Error
+    def initialize(message = "Failed to connect to Tork API")
+      super(message, code: "CONNECTION_ERROR")
+    end
+  end
+
+  # Raised when a policy violation is detected
+  class PolicyViolationError < Error
+    attr_reader :violations
+
+    def initialize(message = "Policy violation detected", violations: [])
+      @violations = violations
+      super(message, http_status: 422, code: "POLICY_VIOLATION")
+    end
+  end
+
+  # Raised when usage limit is exceeded
+  class UsageLimitError < Error
+    def initialize(message = "Usage limit exceeded")
+      super(message, http_status: 429, code: "USAGE_LIMIT_ERROR")
+    end
+  end
+end

data/lib/tork/resources/evaluation.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tork
+  module Resources
+    # Evaluation resource for content evaluation
+    class Evaluation
+      # @param client [Tork::Client] The API client
+      def initialize(client)
+        @client = client
+      end
+
+      # Evaluate content against policies
+      # @param prompt [String] The prompt/input to evaluate
+      # @param response [String, nil] The response/output to evaluate
+      # @param policy_id [String, nil] Specific policy ID (uses default if nil)
+      # @param checks [Array<String>] Checks to perform (pii, toxicity, moderation)
+      # @param options [Hash] Additional options
+      # @return [Hash] Evaluation result
+      def create(prompt:, response: nil, policy_id: nil, checks: nil, **options)
+        body = { content: prompt }
+        body[:response] = response if response
+        body[:policy_id] = policy_id if policy_id
+        body[:checks] = checks if checks
+        body.merge!(options) unless options.empty?
+
+        @client.post("/evaluate", body)
+      end
+
+      # Get an evaluation by ID
+      # @param id [String] Evaluation ID
+      # @return [Hash] Evaluation details
+      def get(id)
+        @client.get("/evaluations/#{id}")
+      end
+
+      # List recent evaluations
+      # @param page [Integer] Page number
+      # @param per_page [Integer] Items per page
+      # @param policy_id [String, nil] Filter by policy
+      # @param status [String, nil] Filter by status (passed, failed, flagged)
+      # @param start_date [String, nil] Start date (ISO 8601)
+      # @param end_date [String, nil] End date (ISO 8601)
+      # @return [Hash] List of evaluations
+      def list(page: 1, per_page: 20, policy_id: nil, status: nil, start_date: nil, end_date: nil)
+        params = { page: page, per_page: per_page }
+        params[:policy_id] = policy_id if policy_id
+        params[:status] = status if status
+        params[:start_date] = start_date if start_date
+        params[:end_date] = end_date if end_date
+        @client.get("/evaluations", params)
+      end
+
+      # Batch evaluate multiple content items
+      # @param items [Array<Hash>] Array of items to evaluate
+      # @param policy_id [String, nil] Policy to apply to all
+      # @return [Hash] Batch evaluation results
+      def batch(items, policy_id: nil)
+        body = { items: items }
+        body[:policy_id] = policy_id if policy_id
+        @client.post("/evaluate/batch", body)
+      end
+
+      # Evaluate and get detailed analysis
+      # @param prompt [String] Content to analyze
+      # @param analysis_types [Array<String>] Types of analysis
+      # @return [Hash] Detailed analysis
+      def analyze(prompt:, analysis_types: %w[pii toxicity sentiment topics])
+        @client.post("/evaluate/analyze", {
+          content: prompt,
+          analysis_types: analysis_types
+        })
+      end
+
+      # Check PII in content
+      # @param content [String] Content to check
+      # @param pii_types [Array<String>, nil] Specific PII types to detect
+      # @param redact [Boolean] Whether to return redacted version
+      # @return [Hash] PII detection results
+      def detect_pii(content:, pii_types: nil, redact: false)
+        body = { content: content, redact: redact }
+        body[:pii_types] = pii_types if pii_types
+        @client.post("/pii/detect", body)
+      end
+
+      # Redact PII from content
+      # @param content [String] Content to redact
+      # @param pii_types [Array<String>, nil] Specific PII types to redact
+      # @param replacement [String] Replacement format (mask, type, custom)
+      # @return [Hash] Redacted content
+      def redact_pii(content:, pii_types: nil, replacement: "mask")
+        body = { content: content, replacement: replacement }
+        body[:pii_types] = pii_types if pii_types
+        @client.post("/pii/redact", body)
+      end
+
+      # Check for jailbreak attempts
+      # @param prompt [String] Prompt to check
+      # @return [Hash] Jailbreak detection results
+      def detect_jailbreak(prompt:)
+        @client.post("/jailbreak/detect", { prompt: prompt })
+      end
+
+      # Validate RAG chunks
+      # @param chunks [Array<Hash>] RAG chunks to validate
+      # @param query [String] Original query
+      # @return [Hash] Validation results
+      def validate_rag(chunks:, query:)
+        @client.post("/rag/validate", {
+          chunks: chunks,
+          query: query
+        })
+      end
+    end
+  end
+end

data/lib/tork/resources/metrics.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Tork
+  module Resources
+    # Metrics resource for analytics and reporting
+    class Metrics
+      # @param client [Tork::Client] The API client
+      def initialize(client)
+        @client = client
+      end
+
+      # Get Torking X score for an evaluation
+      # @param evaluation_id [String] Evaluation ID
+      # @return [Hash] Torking X metrics
+      def torking_x(evaluation_id:)
+        @client.get("/metrics/torking-x/#{evaluation_id}")
+      end
+
+      # Get usage statistics
+      # @param period [String] Time period (day, week, month, year)
+      # @param start_date [String, nil] Start date (ISO 8601)
+      # @param end_date [String, nil] End date (ISO 8601)
+      # @return [Hash] Usage statistics
+      def usage(period: "month", start_date: nil, end_date: nil)
+        params = { period: period }
+        params[:start_date] = start_date if start_date
+        params[:end_date] = end_date if end_date
+        @client.get("/metrics/usage", params)
+      end
+
+      # Get policy performance metrics
+      # @param policy_id [String, nil] Specific policy ID
+      # @param period [String] Time period
+      # @return [Hash] Policy metrics
+      def policy_performance(policy_id: nil, period: "month")
+        params = { period: period }
+        params[:policy_id] = policy_id if policy_id
+        @client.get("/metrics/policies", params)
+      end
+
+      # Get violation statistics
+      # @param period [String] Time period
+      # @param group_by [String] Grouping (policy, type, severity)
+      # @return [Hash] Violation statistics
+      def violations(period: "month", group_by: "type")
+        @client.get("/metrics/violations", {
+          period: period,
+          group_by: group_by
+        })
+      end
+
+      # Get PII detection statistics
+      # @param period [String] Time period
+      # @return [Hash] PII statistics
+      def pii_stats(period: "month")
+        @client.get("/metrics/pii", { period: period })
+      end
+
+      # Get latency metrics
+      # @param period [String] Time period
+      # @param percentiles [Array<Integer>] Percentiles to calculate
+      # @return [Hash] Latency metrics
+      def latency(period: "day", percentiles: [50, 95, 99])
+        @client.get("/metrics/latency", {
+          period: period,
+          percentiles: percentiles.join(",")
+        })
+      end
+
+      # Get cost metrics
+      # @param period [String] Time period
+      # @param group_by [String] Grouping (day, policy, model)
+      # @return [Hash] Cost breakdown
+      def costs(period: "month", group_by: "day")
+        @client.get("/metrics/costs", {
+          period: period,
+          group_by: group_by
+        })
+      end
+
+      # Get real-time metrics
+      # @return [Hash] Current metrics snapshot
+      def realtime
+        @client.get("/metrics/realtime")
+      end
+
+      # Get compliance report
+      # @param start_date [String] Start date (ISO 8601)
+      # @param end_date [String] End date (ISO 8601)
+      # @param format [String] Report format (json, pdf)
+      # @return [Hash] Compliance report data
+      def compliance_report(start_date:, end_date:, format: "json")
+        @client.get("/metrics/compliance", {
+          start_date: start_date,
+          end_date: end_date,
+          format: format
+        })
+      end
+
+      # Get dashboard summary
+      # @return [Hash] Dashboard metrics
+      def dashboard
+        @client.get("/metrics/dashboard")
+      end
+
+      # Export metrics
+      # @param type [String] Export type (usage, violations, costs)
+      # @param start_date [String] Start date
+      # @param end_date [String] End date
+      # @param format [String] Export format (csv, json)
+      # @return [Hash] Export URL or data
+      def export(type:, start_date:, end_date:, format: "csv")
+        @client.post("/metrics/export", {
+          type: type,
+          start_date: start_date,
+          end_date: end_date,
+          format: format
+        })
+      end
+    end
+  end
+end

data/lib/tork/resources/policy.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tork
+  module Resources
+    # Policy resource for managing governance policies
+    class Policy
+      # @param client [Tork::Client] The API client
+      def initialize(client)
+        @client = client
+      end
+
+      # List all policies
+      # @param page [Integer] Page number (default: 1)
+      # @param per_page [Integer] Items per page (default: 20)
+      # @param status [String, nil] Filter by status (active, draft, archived)
+      # @return [Hash] List of policies with pagination info
+      def list(page: 1, per_page: 20, status: nil)
+        params = { page: page, per_page: per_page }
+        params[:status] = status if status
+        @client.get("/policies", params)
+      end
+
+      # Get a specific policy
+      # @param id [String] Policy ID
+      # @return [Hash] Policy details
+      def get(id)
+        @client.get("/policies/#{id}")
+      end
+
+      # Create a new policy
+      # @param name [String] Policy name
+      # @param description [String, nil] Policy description
+      # @param rules [Array<Hash>] Policy rules
+      # @param enabled [Boolean] Whether policy is enabled (default: true)
+      # @param options [Hash] Additional options
+      # @return [Hash] Created policy
+      def create(name:, rules:, description: nil, enabled: true, **options)
+        body = {
+          name: name,
+          rules: rules,
+          enabled: enabled,
+          **options
+        }
+        body[:description] = description if description
+        @client.post("/policies", body)
+      end
+
+      # Update a policy
+      # @param id [String] Policy ID
+      # @param attributes [Hash] Attributes to update
+      # @return [Hash] Updated policy
+      def update(id, **attributes)
+        @client.patch("/policies/#{id}", attributes)
+      end
+
+      # Delete a policy
+      # @param id [String] Policy ID
+      # @return [Hash] Deletion confirmation
+      def delete(id)
+        @client.delete("/policies/#{id}")
+      end
+
+      # Duplicate a policy
+      # @param id [String] Policy ID to duplicate
+      # @param name [String, nil] New name for the duplicate
+      # @return [Hash] Duplicated policy
+      def duplicate(id, name: nil)
+        body = {}
+        body[:name] = name if name
+        @client.post("/policies/#{id}/duplicate", body)
+      end
+
+      # Enable a policy
+      # @param id [String] Policy ID
+      # @return [Hash] Updated policy
+      def enable(id)
+        update(id, enabled: true)
+      end
+
+      # Disable a policy
+      # @param id [String] Policy ID
+      # @return [Hash] Updated policy
+      def disable(id)
+        update(id, enabled: false)
+      end
+
+      # Get policy versions
+      # @param id [String] Policy ID
+      # @return [Hash] List of versions
+      def versions(id)
+        @client.get("/policies/#{id}/versions")
+      end
+
+      # Restore a policy version
+      # @param id [String] Policy ID
+      # @param version_id [String] Version ID to restore
+      # @return [Hash] Restored policy
+      def restore_version(id, version_id)
+        @client.post("/policies/#{id}/versions/#{version_id}/restore")
+      end
+
+      # Test a policy with sample content
+      # @param id [String] Policy ID
+      # @param content [String] Content to test
+      # @param context [Hash] Additional context
+      # @return [Hash] Test results
+      def test(id, content:, context: {})
+        @client.post("/policies/#{id}/test", {
+          content: content,
+          context: context
+        })
+      end
+    end
+  end
+end

data/lib/tork/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tork
+  VERSION = "0.1.0"
+end

data/lib/tork.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "tork/version"
+require_relative "tork/errors"
+require_relative "tork/configuration"
+require_relative "tork/client"
+require_relative "tork/resources/policy"
+require_relative "tork/resources/evaluation"
+require_relative "tork/resources/metrics"
+
+# Tork AI Governance SDK for Ruby
+#
+# @example Basic usage
+#   Tork.configure do |config|
+#     config.api_key = "tork_your_api_key"
+#   end
+#
+#   client = Tork::Client.new
+#   result = client.evaluate(prompt: "Hello world")
+#
+# @example Direct client initialization
+#   client = Tork::Client.new(api_key: "tork_your_api_key")
+#   result = client.evaluate(prompt: "Hello world")
+#
+module Tork
+  class << self
+    # @return [Configuration] Global configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the Tork SDK
+    # @yield [Configuration] Configuration instance
+    # @example
+    #   Tork.configure do |config|
+    #     config.api_key = "tork_your_api_key"
+    #     config.timeout = 60
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Reset configuration to defaults
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Create a new client with global configuration
+    # @return [Client]
+    def client
+      @client ||= Client.new
+    end
+
+    # Reset the default client
+    def reset_client!
+      @client = nil
+    end
+
+    # Convenience method to evaluate content
+    # @param prompt [String] Content to evaluate
+    # @param options [Hash] Additional options
+    # @return [Hash] Evaluation result
+    def evaluate(prompt:, **options)
+      client.evaluate(prompt: prompt, **options)
+    end
+
+    # Access policies via default client
+    # @return [Resources::Policy]
+    def policies
+      client.policies
+    end
+
+    # Access evaluations via default client
+    # @return [Resources::Evaluation]
+    def evaluations
+      client.evaluations
+    end
+
+    # Access metrics via default client
+    # @return [Resources::Metrics]
+    def metrics
+      client.metrics
+    end
+  end
+end

data/tork-governance.gemspec

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "lib/tork/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "tork-governance"
+  spec.version = Tork::VERSION
+  spec.authors = ["Tork Network"]
+  spec.email = ["support@tork.network"]
+
+  spec.summary = "Ruby SDK for Tork AI Governance Platform"
+  spec.description = <<~DESC
+    Official Ruby SDK for the Tork AI Governance Platform. Provides comprehensive
+    tools for AI safety, content moderation, PII detection, policy enforcement,
+    and compliance monitoring for LLM applications.
+  DESC
+  spec.homepage = "https://tork.network"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/torkjacobs/tork-ruby-sdk"
+  spec.metadata["changelog_uri"] = "https://github.com/torkjacobs/tork-ruby-sdk/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://docs.tork.network/sdks/ruby"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/torkjacobs/tork-ruby-sdk/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "faraday", "~> 2.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "vcr", "~> 6.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+end