tork-governance 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66f973f8bfa19b713628ce8bb3942b67fba1bbdf6a138c55ec56060ffb2e0c2e
-  data.tar.gz: 4f9d8086d72580bac59d31397cb62d5ce21a3ca053f6b54ba9b4df69d73a410a
+  metadata.gz: 216554d503f29e742fd17648fe812add23b32f509c5af2a3df6620ff278e0c84
+  data.tar.gz: 3389e8d1f22910eed0a302963837a152bf541303690938d816ef7257b31be926
 SHA512:
-  metadata.gz: fc1120abb85021b2e921f577925e469a6b4a6daa69389136ab96be1720e99f715977bc8041277b3931c0d109d19c2f107ea2c81ee0b4fe0af3e1e2ae0197552e
-  data.tar.gz: 967c1f7abdfdf9274c994487921de2e314fef6dcdaf7849164d5b72a99191138e099e17967b8b6085b03ec6882b29aaa676f11e8cc56469aa0e24d35008c3c1e
+  metadata.gz: 8943faa1f06adf99915b6d3d2080a4890b9b42d399ad3e2464cd3e5a4caf90e58c88b730a59491caefe8672dcacc9fd54ed7afb8a5d38b8c3631a99da72f1942
+  data.tar.gz: 284b06a25065b00b0eddb0e581f376d15a097d58adfddeefab49eb2e579cc63593e85d2d991121e13ee89d461f564a48d2d1f147c59a67b75f6e8d55fa221821

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tork Network Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,26 +1,19 @@
-# Tork AI Governance SDK for Ruby
+# Tork Governance Ruby SDK
 
-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.
+On-device AI governance with PII detection, redaction, and cryptographic receipts for Ruby 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:
+Add to your Gemfile:
 
 ```ruby
 gem 'tork-governance'
 ```
 
-And then execute:
-
-```bash
-bundle install
-```
-
-Or install it yourself as:
+Or install directly:
 
 ```bash
 gem install tork-governance
@@ -29,397 +22,114 @@ gem install tork-governance
 ## Quick Start
 
 ```ruby
-require 'tork'
+require 'tork_governance'
 
-# 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
-```
+tork = TorkGovernance::Client.new
 
-## Configuration
+# Detect and redact PII
+result = tork.govern("My SSN is 123-45-6789 and email is john@example.com")
 
-### 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
+puts result.output  # "My SSN is [SSN_REDACTED] and email is [EMAIL_REDACTED]"
+puts result.pii.types  # ['ssn', 'email']
+puts result.receipt.id  # Cryptographic receipt ID
 ```
 
-### Environment Variable
+## Supported Frameworks (2 Adapters)
 
-You can also set the API key via environment variable:
+### Web Frameworks
+- **Rails** - Middleware and controller integration
+- **Grape** - API middleware and helpers
 
-```bash
-export TORK_API_KEY=tork_your_api_key
-```
+## Framework Examples
 
-### Per-Client Configuration
+### Rails Middleware
 
 ```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
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    config.middleware.use TorkGovernance::Middleware::Rails,
+      protected_paths: ['/api/'],
+      skip_paths: ['/api/health']
+  end
 end
 ```
 
-### Controller Example
-
 ```ruby
-class MessagesController < ApplicationController
+# In controllers
+class ChatController < 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
+    tork_result = request.env['tork.result']
+    render json: { status: 'ok', receipt_id: tork_result&.receipt&.id }
   end
 end
 ```
 
-### Background Job Example
+### Grape API Middleware
 
 ```ruby
-class ContentModerationJob < ApplicationJob
-  queue_as :default
+require 'tork_governance/middleware/grape'
 
-  def perform(message_id)
-    message = Message.find(message_id)
+class API < Grape::API
+  use TorkGovernance::Middleware::Grape,
+    protected_paths: ['/api/'],
+    skip_paths: ['/api/health']
 
-    result = Tork.evaluate(
-      prompt: message.content,
-      checks: ['toxicity', 'pii']
-    )
+  helpers TorkGovernance::Middleware::GrapeHelpers
 
-    if result['data']['violations'].any?
-      message.update!(
-        flagged: true,
-        moderation_result: result['data']
-      )
+  post '/chat' do
+    result = tork_result
+    receipt_id = tork_receipt_id
 
-      NotificationService.notify_moderators(message)
+    if tork_blocked?
+      error!({ error: 'Content blocked' }, 403)
     end
+
+    { status: 'ok', receipt_id: receipt_id }
   end
 end
 ```
 
-## Logging
-
-Enable detailed logging for debugging:
+### Grape Helper Methods
 
 ```ruby
-require 'logger'
-
-Tork.configure do |config|
-  config.api_key = 'tork_your_api_key'
-  config.logger = Logger.new(STDOUT)
-end
-```
-
-## Retry Behavior
+helpers TorkGovernance::Middleware::GrapeHelpers
 
-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
+# Available helpers:
+tork_result           # Get full governance result
+tork_receipt_id       # Get receipt ID
+tork_redacted_content # Get redacted content
+tork_blocked?         # Check if request was blocked
+tork_redacted?        # Check if content was redacted
+require_tork_governance!  # Raises 403 if blocked
 ```
 
-## Thread Safety
-
-The SDK is thread-safe. Each `Tork::Client` instance maintains its own connection pool.
+## Configuration
 
 ```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)
+TorkGovernance.configure(
+  api_key: ENV['TORK_API_KEY'],
+  policy_version: '1.0.0',
+  default_action: :redact
+)
 ```
 
-## Development
-
-After checking out the repo:
-
-```bash
-# Install dependencies
-bundle install
-
-# Run tests
-bundle exec rspec
+## PII Detection
 
-# Run linter
-bundle exec rubocop
+Detects 50+ PII types including:
 
-# Generate documentation
-bundle exec rake doc
+| Category | Types |
+|----------|-------|
+| **US** | SSN, EIN, ITIN, Passport, Driver's License |
+| **Australia** | TFN, ABN, ACN, Medicare |
+| **Financial** | Credit Card, Bank Account, SWIFT/BIC |
+| **Universal** | Email, IP Address, URL, Phone, DOB |
 
-# Build the gem
-bundle exec rake build
-
-# Install locally
-bundle exec rake install
-```
+## Documentation
 
-## 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
+- [Full Documentation](https://docs.tork.network)
+- [API Reference](https://docs.tork.network/api/ruby)
 
 ## 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)
+MIT License - see [LICENSE](LICENSE) for details.

data/Rakefile

@@ -1,38 +1,7 @@
 # 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
+task default: :spec

data/lib/tork/version.rb

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

data/lib/tork_governance/client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module TorkGovernance
+  # Governance result
+  class GovernResult
+    attr_reader :action, :output, :pii, :receipt
+
+    def initialize(action:, output:, pii:, receipt:)
+      @action = action
+      @output = output
+      @pii = pii
+      @receipt = receipt
+    end
+
+    def allowed?
+      action == ACTIONS[:allow]
+    end
+
+    def denied?
+      action == ACTIONS[:deny]
+    end
+
+    def redacted?
+      action == ACTIONS[:redact]
+    end
+
+    def to_h
+      {
+        action: action,
+        output: output,
+        pii: {
+          has_pii: pii.has_pii?,
+          types: pii.types,
+          count: pii.count
+        },
+        receipt: receipt.to_h
+      }
+    end
+  end
+
+  # Main Tork governance client
+  class Client
+    attr_reader :api_key, :policy_version, :default_action, :stats
+
+    def initialize(api_key: nil, policy_version: "1.0.0", default_action: ACTIONS[:redact])
+      @api_key = api_key
+      @policy_version = policy_version
+      @default_action = default_action
+      @stats = {
+        total_calls: 0,
+        total_pii_detected: 0,
+        total_processing_ns: 0,
+        action_counts: Hash.new(0)
+      }
+    end
+
+    # Apply governance to content
+    #
+    # @param input [String] the content to govern
+    # @return [GovernResult] the governance result
+    #
+    # @example
+    #   client = TorkGovernance::Client.new
+    #   result = client.govern("My email is test@example.com")
+    #   puts result.output # "My email is [EMAIL_REDACTED]"
+    #   puts result.receipt.id # "rcpt_..."
+    def govern(input)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+
+      # Detect PII
+      pii = PIIDetector.detect(input)
+
+      # Determine action and output
+      if pii.has_pii?
+        action = default_action
+        output = action == ACTIONS[:redact] ? pii.redacted_text : input
+      else
+        action = ACTIONS[:allow]
+        output = input
+      end
+
+      processing_time_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - start_time
+
+      # Generate receipt
+      receipt = Receipt.generate(
+        input: input,
+        output: output,
+        action: action,
+        pii_types: pii.types,
+        pii_count: pii.count,
+        policy_version: policy_version,
+        processing_time_ns: processing_time_ns
+      )
+
+      # Update stats
+      @stats[:total_calls] += 1
+      @stats[:total_pii_detected] += 1 if pii.has_pii?
+      @stats[:total_processing_ns] += processing_time_ns
+      @stats[:action_counts][action] += 1
+
+      GovernResult.new(
+        action: action,
+        output: output,
+        pii: pii,
+        receipt: receipt
+      )
+    end
+
+    # Reset statistics
+    def reset_stats
+      @stats = {
+        total_calls: 0,
+        total_pii_detected: 0,
+        total_processing_ns: 0,
+        action_counts: Hash.new(0)
+      }
+    end
+  end
+end