tork-governance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 66f973f8bfa19b713628ce8bb3942b67fba1bbdf6a138c55ec56060ffb2e0c2e
+  data.tar.gz: 4f9d8086d72580bac59d31397cb62d5ce21a3ca053f6b54ba9b4df69d73a410a
+SHA512:
+  metadata.gz: fc1120abb85021b2e921f577925e469a6b4a6daa69389136ab96be1720e99f715977bc8041277b3931c0d109d19c2f107ea2c81ee0b4fe0af3e1e2ae0197552e
+  data.tar.gz: 967c1f7abdfdf9274c994487921de2e314fef6dcdaf7849164d5b72a99191138e099e17967b8b6085b03ec6882b29aaa676f11e8cc56469aa0e24d35008c3c1e

data/README.md

@@ -0,0 +1,425 @@
+# Tork AI Governance SDK for Ruby
+
+Official Ruby SDK for the [Tork AI Governance Platform](https://tork.network). Provides comprehensive tools for AI safety, content moderation, PII detection, policy enforcement, and compliance monitoring for LLM applications.
+
+[![Gem Version](https://badge.fury.io/rb/tork-governance.svg)](https://badge.fury.io/rb/tork-governance)
+[![Build Status](https://github.com/torkjacobs/tork-ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/torkjacobs/tork-ruby-sdk/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tork-governance'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install tork-governance
+```
+
+## Quick Start
+
+```ruby
+require 'tork'
+
+# Configure with your API key
+Tork.configure do |config|
+  config.api_key = 'tork_your_api_key'
+end
+
+# Evaluate content
+result = Tork.evaluate(prompt: "What is the capital of France?")
+puts result['data']['passed'] # => true
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+Tork.configure do |config|
+  config.api_key = 'tork_your_api_key'
+  config.base_url = 'https://api.tork.network/v1'  # Default
+  config.timeout = 30                               # Request timeout in seconds
+  config.max_retries = 3                            # Max retry attempts
+  config.retry_base_delay = 0.5                     # Base delay for exponential backoff
+  config.raise_on_rate_limit = true                 # Raise exception on rate limit
+  config.logger = Logger.new(STDOUT)                # Enable logging
+end
+```
+
+### Environment Variable
+
+You can also set the API key via environment variable:
+
+```bash
+export TORK_API_KEY=tork_your_api_key
+```
+
+### Per-Client Configuration
+
+```ruby
+client = Tork::Client.new(
+  api_key: 'tork_different_key',
+  base_url: 'https://custom.api.com'
+)
+```
+
+## Usage
+
+### Content Evaluation
+
+```ruby
+client = Tork::Client.new(api_key: 'tork_your_api_key')
+
+# Basic evaluation
+result = client.evaluate(prompt: "Hello, how are you?")
+
+# Evaluation with response
+result = client.evaluate(
+  prompt: "What is 2+2?",
+  response: "The answer is 4."
+)
+
+# Evaluation with specific policy
+result = client.evaluate(
+  prompt: "Process this request",
+  policy_id: "pol_abc123"
+)
+
+# Evaluation with specific checks
+result = client.evaluations.create(
+  prompt: "Contact me at john@example.com",
+  checks: ['pii', 'toxicity', 'moderation']
+)
+```
+
+### PII Detection & Redaction
+
+```ruby
+# Detect PII
+result = client.evaluations.detect_pii(
+  content: "My email is john@example.com and SSN is 123-45-6789"
+)
+# => { "has_pii" => true, "types" => ["email", "ssn"] }
+
+# Redact PII
+result = client.evaluations.redact_pii(
+  content: "Call me at 555-123-4567",
+  replacement: "mask"
+)
+# => { "redacted" => "Call me at ***-***-****" }
+```
+
+### Jailbreak Detection
+
+```ruby
+result = client.evaluations.detect_jailbreak(
+  prompt: "Ignore previous instructions and..."
+)
+
+if result['data']['is_jailbreak']
+  puts "Jailbreak attempt detected!"
+  puts "Techniques: #{result['data']['techniques']}"
+end
+```
+
+### Policy Management
+
+```ruby
+policies = client.policies
+
+# List all policies
+all_policies = policies.list(page: 1, per_page: 20)
+
+# Get a specific policy
+policy = policies.get('pol_abc123')
+
+# Create a new policy
+new_policy = policies.create(
+  name: "Content Safety Policy",
+  description: "Block harmful content",
+  rules: [
+    {
+      type: "block",
+      condition: "toxicity > 0.8",
+      action: "reject",
+      message: "Content flagged as toxic"
+    },
+    {
+      type: "redact",
+      condition: "pii.detected",
+      action: "mask"
+    }
+  ],
+  enabled: true
+)
+
+# Update a policy
+policies.update('pol_abc123', name: "Updated Policy Name")
+
+# Enable/Disable a policy
+policies.enable('pol_abc123')
+policies.disable('pol_abc123')
+
+# Delete a policy
+policies.delete('pol_abc123')
+
+# Test a policy
+test_result = policies.test('pol_abc123',
+  content: "Test content here",
+  context: { user_role: "admin" }
+)
+```
+
+### Batch Evaluation
+
+```ruby
+items = [
+  { prompt: "First prompt" },
+  { prompt: "Second prompt", response: "Second response" },
+  { prompt: "Third prompt" }
+]
+
+results = client.evaluations.batch(items, policy_id: 'pol_abc123')
+```
+
+### RAG Validation
+
+```ruby
+chunks = [
+  { content: "Document chunk 1", source: "doc1.pdf", page: 1 },
+  { content: "Document chunk 2", source: "doc2.pdf", page: 3 }
+]
+
+result = client.evaluations.validate_rag(
+  chunks: chunks,
+  query: "What is the company policy?"
+)
+```
+
+### Metrics & Analytics
+
+```ruby
+metrics = client.metrics
+
+# Get Torking X score for an evaluation
+score = metrics.torking_x(evaluation_id: 'eval_abc123')
+
+# Get usage statistics
+usage = metrics.usage(period: 'month')
+
+# Get policy performance
+performance = metrics.policy_performance(policy_id: 'pol_abc123')
+
+# Get violation statistics
+violations = metrics.violations(period: 'week', group_by: 'type')
+
+# Get dashboard summary
+dashboard = metrics.dashboard
+
+# Get latency metrics
+latency = metrics.latency(period: 'day', percentiles: [50, 95, 99])
+
+# Export metrics
+export = metrics.export(
+  type: 'usage',
+  start_date: '2024-01-01',
+  end_date: '2024-01-31',
+  format: 'csv'
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  result = client.evaluate(prompt: "Test content")
+rescue Tork::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Tork::RateLimitError => e
+  puts "Rate limited. Retry after #{e.retry_after} seconds"
+rescue Tork::ValidationError => e
+  puts "Validation failed: #{e.message}"
+  puts "Details: #{e.details}"
+rescue Tork::PolicyViolationError => e
+  puts "Policy violation: #{e.message}"
+  puts "Violations: #{e.violations}"
+rescue Tork::NotFoundError => e
+  puts "Resource not found: #{e.message}"
+rescue Tork::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Tork::TimeoutError => e
+  puts "Request timed out"
+rescue Tork::ConnectionError => e
+  puts "Connection failed"
+rescue Tork::Error => e
+  puts "Tork error: #{e.message}"
+end
+```
+
+## Rails Integration
+
+### Initializer
+
+Create `config/initializers/tork.rb`:
+
+```ruby
+Tork.configure do |config|
+  config.api_key = Rails.application.credentials.tork_api_key
+  config.logger = Rails.logger
+  config.timeout = 30
+end
+```
+
+### Controller Example
+
+```ruby
+class MessagesController < ApplicationController
+  def create
+    result = Tork.evaluate(
+      prompt: params[:content],
+      policy_id: current_user.organization.policy_id
+    )
+
+    if result['data']['passed']
+      @message = Message.create!(content: params[:content])
+      render json: @message
+    else
+      render json: {
+        error: 'Content blocked',
+        violations: result['data']['violations']
+      }, status: :unprocessable_entity
+    end
+  rescue Tork::RateLimitError => e
+    render json: { error: 'Rate limited' }, status: :too_many_requests
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+class ContentModerationJob < ApplicationJob
+  queue_as :default
+
+  def perform(message_id)
+    message = Message.find(message_id)
+
+    result = Tork.evaluate(
+      prompt: message.content,
+      checks: ['toxicity', 'pii']
+    )
+
+    if result['data']['violations'].any?
+      message.update!(
+        flagged: true,
+        moderation_result: result['data']
+      )
+
+      NotificationService.notify_moderators(message)
+    end
+  end
+end
+```
+
+## Logging
+
+Enable detailed logging for debugging:
+
+```ruby
+require 'logger'
+
+Tork.configure do |config|
+  config.api_key = 'tork_your_api_key'
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+## Retry Behavior
+
+The SDK automatically retries failed requests with exponential backoff:
+
+- **Retryable status codes**: 408, 500, 502, 503, 504
+- **Default max retries**: 3
+- **Default base delay**: 0.5 seconds
+- **Backoff factor**: 2x
+- **Jitter**: 50% randomness
+
+Customize retry behavior:
+
+```ruby
+Tork.configure do |config|
+  config.max_retries = 5
+  config.retry_base_delay = 1.0
+  config.retry_max_delay = 60.0
+end
+```
+
+## Thread Safety
+
+The SDK is thread-safe. Each `Tork::Client` instance maintains its own connection pool.
+
+```ruby
+# Shared client (thread-safe)
+client = Tork::Client.new(api_key: 'tork_your_api_key')
+
+threads = 10.times.map do |i|
+  Thread.new do
+    client.evaluate(prompt: "Thread #{i} content")
+  end
+end
+
+threads.each(&:join)
+```
+
+## Development
+
+After checking out the repo:
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Generate documentation
+bundle exec rake doc
+
+# Build the gem
+bundle exec rake build
+
+# Install locally
+bundle exec rake install
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -am 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## Support
+
+- **Documentation**: [docs.tork.network](https://docs.tork.network)
+- **Email**: support@tork.network
+- **Issues**: [GitHub Issues](https://github.com/torkjacobs/tork-ruby-sdk/issues)

data/Rakefile

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+desc "Run tests with coverage"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task[:spec].invoke
+end
+
+desc "Generate documentation"
+task :doc do
+  sh "yard doc --output-dir doc lib/**/*.rb"
+end
+
+desc "Open documentation in browser"
+task :doc_server do
+  sh "yard server --reload"
+end
+
+desc "Build and install gem locally"
+task :local_install do
+  sh "gem build tork-governance.gemspec"
+  sh "gem install tork-governance-#{Tork::VERSION}.gem"
+end
+
+desc "Release gem to RubyGems"
+task :publish do
+  sh "gem build tork-governance.gemspec"
+  sh "gem push tork-governance-#{Tork::VERSION}.gem"
+end

data/lib/tork/client.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module Tork
+  # HTTP client for interacting with the Tork API
+  class Client
+    attr_reader :config
+
+    # Initialize a new client
+    # @param api_key [String, nil] API key (uses config if not provided)
+    # @param base_url [String, nil] Base URL (uses config if not provided)
+    # @param config [Configuration, nil] Configuration object
+    def initialize(api_key: nil, base_url: nil, config: nil)
+      @config = config || Tork.configuration.dup
+      @config.api_key = api_key if api_key
+      @config.base_url = base_url if base_url
+      @config.validate!
+
+      @connection = build_connection
+    end
+
+    # Access policy resources
+    # @return [Resources::Policy]
+    def policies
+      @policies ||= Resources::Policy.new(self)
+    end
+
+    # Access evaluation resources
+    # @return [Resources::Evaluation]
+    def evaluations
+      @evaluations ||= Resources::Evaluation.new(self)
+    end
+
+    # Access metrics resources
+    # @return [Resources::Metrics]
+    def metrics
+      @metrics ||= Resources::Metrics.new(self)
+    end
+
+    # Shorthand for evaluating content
+    # @param prompt [String] The prompt to evaluate
+    # @param response [String, nil] The response to evaluate
+    # @param policy_id [String, nil] Policy ID to use
+    # @param options [Hash] Additional options
+    # @return [Hash] Evaluation result
+    def evaluate(prompt:, response: nil, policy_id: nil, **options)
+      evaluations.create(
+        prompt: prompt,
+        response: response,
+        policy_id: policy_id,
+        **options
+      )
+    end
+
+    # Make a GET request
+    # @param path [String] API path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed response
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # Make a POST request
+    # @param path [String] API path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    # Make a PUT request
+    # @param path [String] API path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def put(path, body = {})
+      request(:put, path, body: body)
+    end
+
+    # Make a PATCH request
+    # @param path [String] API path
+    # @param body [Hash] Request body
+    # @return [Hash] Parsed response
+    def patch(path, body = {})
+      request(:patch, path, body: body)
+    end
+
+    # Make a DELETE request
+    # @param path [String] API path
+    # @return [Hash] Parsed response
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(url: config.base_url) do |conn|
+        # Request configuration
+        conn.request :json
+        conn.headers["Authorization"] = "Bearer #{config.api_key}"
+        conn.headers["User-Agent"] = config.full_user_agent
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+
+        # Retry configuration with exponential backoff
+        conn.request :retry,
+                     max: config.max_retries,
+                     interval: config.retry_base_delay,
+                     interval_randomness: 0.5,
+                     backoff_factor: 2,
+                     max_interval: config.retry_max_delay,
+                     retry_statuses: [408, 500, 502, 503, 504],
+                     retry_if: ->(env, _exception) { retryable?(env) },
+                     retry_block: ->(env, _options, retries, exception) {
+                       log_retry(env, retries, exception)
+                     }
+
+        # Response parsing
+        conn.response :json, content_type: /\bjson$/
+        conn.response :logger, config.logger, bodies: true if config.logger
+
+        # Timeout
+        conn.options.timeout = config.timeout
+        conn.options.open_timeout = 10
+
+        # Adapter
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, params: nil, body: nil)
+      response = @connection.send(method) do |req|
+        req.url path
+        req.params = params if params
+        req.body = body.to_json if body
+      end
+
+      handle_response(response)
+    rescue Faraday::TimeoutError
+      raise TimeoutError
+    rescue Faraday::ConnectionFailed
+      raise ConnectionError
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body || {}
+      when 401
+        raise AuthenticationError, extract_error_message(response)
+      when 404
+        raise NotFoundError, extract_error_message(response)
+      when 422
+        handle_validation_error(response)
+      when 429
+        handle_rate_limit(response)
+      when 400..499
+        raise ValidationError.new(extract_error_message(response), details: response.body)
+      when 500..599
+        raise ServerError, extract_error_message(response)
+      else
+        raise Error.new(
+          "Unexpected response: #{response.status}",
+          http_status: response.status
+        )
+      end
+    end
+
+    def handle_rate_limit(response)
+      retry_after = response.headers["Retry-After"]&.to_i
+      message = extract_error_message(response)
+
+      if config.raise_on_rate_limit
+        raise RateLimitError.new(message, retry_after: retry_after)
+      else
+        {
+          error: true,
+          code: "RATE_LIMIT_ERROR",
+          message: message,
+          retry_after: retry_after
+        }
+      end
+    end
+
+    def handle_validation_error(response)
+      body = response.body || {}
+
+      if body.dig("error", "code") == "POLICY_VIOLATION"
+        raise PolicyViolationError.new(
+          extract_error_message(response),
+          violations: body.dig("error", "violations") || []
+        )
+      else
+        raise ValidationError.new(extract_error_message(response), details: body)
+      end
+    end
+
+    def extract_error_message(response)
+      body = response.body
+      return "Unknown error" unless body.is_a?(Hash)
+
+      body.dig("error", "message") ||
+        body["message"] ||
+        body["error"] ||
+        "Request failed with status #{response.status}"
+    end
+
+    def retryable?(env)
+      # Don't retry POST/PUT/PATCH unless idempotent
+      return true if %i[get head delete].include?(env.method)
+
+      # Retry server errors for all methods
+      env.status.nil? || env.status >= 500
+    end
+
+    def log_retry(env, retries, exception)
+      return unless config.logger
+
+      config.logger.warn(
+        "[Tork] Retry ##{retries} for #{env.method.upcase} #{env.url}: " \
+        "#{exception&.message || "status #{env.status}"}"
+      )
+    end
+  end
+end