typesafe-ai-rails 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d274cc3f15ebcb2e9660a74947c1e7487d930aef743b286a3735a046e010d45a
+  data.tar.gz: 555561362e7bfe28c3db08b8edd74d7fca31dee5831de921142a8b3dfe456f15
+SHA512:
+  metadata.gz: 3e656b5c1000a3dcf37d29303b2c70489a1e6d98205a6d9eb35c84199b43bcb2a1a1f84e0b1c29e26481cd7b98f7893c89fe815600e6693b239feba0af75a221
+  data.tar.gz: 8a97bb57ff81e1ccc0fdc398fe13ad4ce41d29a8de38cc7b85d796ef2f46a8038c10f33e5b14688c41f0aec784b32abddbf7b7082236c0ba6ec140c88a595190

data/.gitignore

@@ -0,0 +1,5 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+*.gem
+.DS_Store

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.4.0
+
+Initial public release under the `typesafe-ai-rails` name.
+
+- Fail-closed Choice/Score confidence gating backed by Rails persistence.
+- Answer-specific policies with wildcard defaults and distinct fallback handlers.
+- Explicit Noul handling: probability is never treated as confidence.
+- Forward-compatible plain-hash question helpers with documented Score validation.
+- Direct per-call SDK keyword forwarding.
+- Model-aware, non-fatal call/cost telemetry with pricing snapshots, latency, usage,
+  and request IDs.
+- Jev-family pricing handles versioned response model names such as `jev-1.13.0`.
+- SDK logging is opt-in to avoid accidental request/response body logging.
+- Tests use the real community `typesafe-sdk` request/response contract.
+- Fresh-install and development-snapshot upgrade migrations.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genie Developments
+
+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

@@ -0,0 +1,208 @@
+# typesafe-ai-rails
+
+Community Rails integration for TypeSafe AI's System One API, built on the
+community [`typesafe-sdk`](https://github.com/joshmn/typesafe-sdk) Ruby gem.
+This project is not an official TypeSafe package.
+
+The SDK stays framework-neutral. `typesafe-ai-rails` adds Rails configuration,
+persisted usage/cost telemetry, and an opt-in persistence-backed confidence
+policy for Choice and Score answers.
+
+## Installation
+
+```bash
+bundle add typesafe-ai-rails
+bin/rails generate typesafe:rails:install
+bin/rails db:migrate
+```
+
+Bundler loads the gem through `typesafe-ai-rails`. The stable Ruby API remains
+under `Typesafe::Rails`; direct users may also `require "typesafe/rails"`.
+
+Add the API key to Rails credentials:
+
+```yaml
+typesafe:
+  api_key: sk-...
+```
+
+## Usage
+
+```ruby
+result = Typesafe::Rails.client.ask(
+  decision_type: "support_ticket_routing",
+  state: ticket.body,
+  questions: {
+    department: Typesafe::Rails.choice(
+      "Which team should handle this",
+      { billing: nil, technical: nil, sales: nil }
+    ),
+    is_urgent: Typesafe::Rails.noul("Is this time-sensitive?"),
+    frustration: Typesafe::Rails.score(
+      "How frustrated is the customer",
+      ["Calm", "Frustrated but civil", "Very angry"]
+    )
+  }
+)
+```
+
+`ask` sends all questions about the state in one System One call. That follows
+TypeSafe's recommendation to batch independent questions that share state.
+
+The returned `Result` exposes the SDK response directly:
+
+```ruby
+result[:department]
+result.choices
+result.scores
+result.nouls
+result.usage
+result.response
+```
+
+## Confidence policies
+
+TypeSafe returns `confidence` for Choice and Score answers. Noul does **not**
+have a separate confidence value; its `noul` field is the probability of yes.
+
+`Result#act!` is a fail-closed helper for Choice/Score side effects. Create
+either a policy for a specific answer or a wildcard policy for the decision:
+
+```ruby
+Typesafe::Rails::DecisionPolicy.create!(
+  decision_type: "support_ticket_routing",
+  answer_key: "department",
+  confidence_threshold: 0.7,
+  fallback: "surface_to_user"
+)
+```
+
+A wildcard row applies to every confidence-bearing answer that does not have a
+more specific row:
+
+```ruby
+Typesafe::Rails::DecisionPolicy.create!(
+  decision_type: "support_ticket_routing",
+  answer_key: "*",
+  confidence_threshold: 0.5,
+  fallback: "surface_to_user"
+)
+```
+
+Then gate the side effect:
+
+```ruby
+result.act!(
+  :department,
+  fallback: ->(_answer) { route_to_human(ticket) }
+) do |answer|
+  ticket.route_to!(answer.choice)
+end
+```
+
+If no active policy exists, `act!` raises
+`Typesafe::Rails::MissingPolicyError`. Intentionally ungated reads should use
+`result[:department]` directly.
+
+For distinct fallback modes, pass handlers by mode:
+
+```ruby
+result.act!(
+  :department,
+  fallback: {
+    deterministic_rule: ->(answer) { route_with_rules(ticket, answer) },
+    surface_to_user: ->(_answer) { ask_customer(ticket) },
+    missing_answer: ->(_answer) { route_to_human(ticket) }
+  }
+) do |answer|
+  ticket.route_to!(answer.choice)
+end
+```
+
+`fallback: "escalate"` raises `Typesafe::Rails::LowConfidenceError`.
+
+For Noul, threshold its probability directly:
+
+```ruby
+urgent = result[:is_urgent]
+escalate(ticket) if urgent.noul >= 0.8
+```
+
+## Question helpers
+
+`Typesafe::Rails.noul`, `.choice`, and `.score` return plain question hashes.
+The Ruby SDK accepts hashes, so new API fields can pass through before the SDK
+adds matching constructor keywords:
+
+```ruby
+Typesafe::Rails.noul(
+  "Is this relevant?",
+  weight: 2,
+  future_field: { enabled: true }
+)
+```
+
+Choice requires a non-empty criteria hash. Score requires the currently
+documented 2–10 ordered levels.
+
+You can always use `Typesafe::SDK::Noul`, `Choice`, `Score`, or raw hashes
+directly in the same `questions:` map.
+
+## Configuration
+
+```ruby
+Rails.application.config.typesafe.api_key =
+  Rails.application.credentials.dig(:typesafe, :api_key)
+
+Rails.application.config.typesafe.model = "jev-latest"
+Rails.application.config.typesafe.timeout = 10.0
+```
+
+Client-level SDK options are available through Rails configuration:
+`base_url`, `headers`, `user_agent`, `logger`, `retry_policy`, and `transport`.
+
+SDK logging is deliberately opt-in. At debug level, the Ruby SDK logs request
+and response bodies, so enabling it may place application state in logs:
+
+```ruby
+Rails.application.config.typesafe.logger = Rails.logger
+```
+
+Per-call SDK options are forwarded directly:
+
+```ruby
+Typesafe::Rails.client.ask(
+  decision_type: "routing",
+  state: ticket.body,
+  questions: questions,
+  model: "jev-1.12",
+  extra_body: { beam_width: 4 }
+)
+```
+
+For anything else, `Typesafe::Rails.client.sdk` exposes the underlying client.
+Calls made directly on it bypass Rails telemetry.
+
+## Telemetry and pricing
+
+Each successful `ask` attempts to append a row to `typesafe_calls` containing:
+
+- decision type and returned model
+- input/output token counts
+- the pricing rates used for the estimate
+- estimated USD cost
+- request ID and local latency
+
+Pricing is keyed by the returned model. The built-in defaults include a Jev
+family rate so `jev-latest` can resolve to versioned names such as `jev-1.13.0`
+without losing the cost estimate. Unknown model families are recorded with
+`cost_usd = NULL` rather than an invented price. Override `pricing` when
+TypeSafe changes its published rates.
+
+A telemetry database failure is non-fatal by default. Set
+`Rails.application.config.typesafe.strict_logging = true` when complete
+accounting is more important than availability.
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+
+task default: :test

data/lib/generators/typesafe/rails/install/install_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Typesafe
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::Rails::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Installs or upgrades TypeSafe AI Rails integration tables and configuration."
+
+        def self.next_migration_number(dirname)
+          ::ActiveRecord::Generators::Base.next_migration_number(dirname)
+        end
+
+        def create_migration_files
+          if migration_exists?("create_typesafe_rails_tables")
+            unless migration_exists?("upgrade_typesafe_rails_to_0_4")
+              migration_template(
+                "upgrade_typesafe_rails_to_0_4.rb.tt",
+                "db/migrate/upgrade_typesafe_rails_to_0_4.rb"
+              )
+            end
+          else
+            migration_template(
+              "create_typesafe_rails_tables.rb.tt",
+              "db/migrate/create_typesafe_rails_tables.rb"
+            )
+          end
+        end
+
+        def add_initializer
+          template "typesafe.rb.tt", "config/initializers/typesafe.rb"
+        end
+
+        def show_readme
+          readme "POST_INSTALL.md" if behavior == :invoke
+        end
+
+        private
+
+        def migration_exists?(basename)
+          Dir.glob(File.join(destination_root, "db/migrate/*_#{basename}.rb")).any?
+        end
+      end
+    end
+  end
+end

data/lib/generators/typesafe/rails/install/templates/POST_INSTALL.md

@@ -0,0 +1,20 @@
+Typesafe::Rails is installed.
+
+Next steps:
+
+  1. Run `bin/rails db:migrate`.
+
+  2. Add your API key: `bin/rails credentials:edit` and add:
+
+       typesafe:
+         api_key: sk-...
+
+  3. Call System One through `Typesafe::Rails.client.ask`.
+
+  4. Before calling `result.act!`, create an active policy for that answer
+     key, or a wildcard `answer_key: "*"` policy for the decision type.
+     `act!` intentionally fails closed when no policy exists.
+
+Noul answers do not have TypeSafe confidence. Read `answer.noul` and apply
+the probability threshold appropriate to your application instead of using
+`act!`.

data/lib/generators/typesafe/rails/install/templates/create_typesafe_rails_tables.rb.tt

@@ -0,0 +1,30 @@
+class CreateTypesafeRailsTables < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" %>
+  def change
+    create_table :typesafe_decision_policies do |t|
+      t.string  :decision_type, null: false
+      t.string  :answer_key, null: false, default: "*"
+      t.decimal :confidence_threshold, precision: 3, scale: 2, null: false
+      t.string  :fallback, null: false, default: "surface_to_user"
+      t.boolean :active, null: false, default: true
+
+      t.timestamps
+    end
+    add_index :typesafe_decision_policies, [:decision_type, :answer_key], unique: true
+
+    create_table :typesafe_calls do |t|
+      t.string   :decision_type, null: false
+      t.string   :model
+      t.integer  :input_tokens
+      t.integer  :output_tokens
+      t.decimal  :input_rate, precision: 12, scale: 6
+      t.decimal  :output_rate, precision: 12, scale: 6
+      t.decimal  :cost_usd, precision: 12, scale: 6
+      t.decimal  :latency_ms, precision: 12, scale: 3
+      t.string   :request_id
+      t.datetime :created_at, null: false
+    end
+    add_index :typesafe_calls, :decision_type
+    add_index :typesafe_calls, :created_at
+    add_index :typesafe_calls, :request_id
+  end
+end

data/lib/generators/typesafe/rails/install/templates/typesafe.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+Rails.application.config.typesafe.api_key =
+  Rails.application.credentials.dig(:typesafe, :api_key)
+
+Rails.application.config.typesafe.model = "jev-latest"
+Rails.application.config.typesafe.timeout = 10.0
+
+# SDK logging is opt-in. Debug logging includes request/response bodies, which
+# may contain sensitive application state.
+# Rails.application.config.typesafe.logger = Rails.logger
+
+# A telemetry write failure should not make a successful TypeSafe call fail.
+# Set this true when complete accounting is more important than availability.
+Rails.application.config.typesafe.strict_logging = false
+
+# TypeSafe currently prices the Jev family uniformly. Unknown model families
+# are logged with cost_usd = NULL rather than an invented price.
+Rails.application.config.typesafe.pricing = {
+  "jev" => { input_per_mtok: 0.042, output_per_mtok: 0.0 },
+  "jev-latest" => { input_per_mtok: 0.042, output_per_mtok: 0.0 },
+  "jev-1.12" => { input_per_mtok: 0.042, output_per_mtok: 0.0 }
+}

data/lib/generators/typesafe/rails/install/templates/upgrade_typesafe_rails_to_0_4.rb.tt

@@ -0,0 +1,30 @@
+class UpgradeTypesafeRailsTo04 < ActiveRecord::Migration<%= "[#{ActiveRecord::Migration.current_version}]" %>
+  def up
+    unless column_exists?(:typesafe_decision_policies, :answer_key)
+      add_column :typesafe_decision_policies, :answer_key, :string, null: false, default: "*"
+    end
+
+    if index_exists?(:typesafe_decision_policies, :decision_type, unique: true)
+      remove_index :typesafe_decision_policies, :decision_type
+    end
+
+    unless index_exists?(:typesafe_decision_policies, [:decision_type, :answer_key], unique: true)
+      add_index :typesafe_decision_policies, [:decision_type, :answer_key], unique: true
+    end
+
+    add_column :typesafe_calls, :model, :string unless column_exists?(:typesafe_calls, :model)
+    add_column :typesafe_calls, :input_rate, :decimal,
+               precision: 12, scale: 6 unless column_exists?(:typesafe_calls, :input_rate)
+    add_column :typesafe_calls, :output_rate, :decimal,
+               precision: 12, scale: 6 unless column_exists?(:typesafe_calls, :output_rate)
+    add_column :typesafe_calls, :latency_ms, :decimal,
+               precision: 12, scale: 3 unless column_exists?(:typesafe_calls, :latency_ms)
+
+    add_index :typesafe_calls, :request_id unless index_exists?(:typesafe_calls, :request_id)
+  end
+
+  def down
+    raise ActiveRecord::IrreversibleMigration,
+          "0.4 allows multiple answer-specific policies per decision_type"
+  end
+end

data/lib/typesafe/rails/call_log.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    class CallLog < ActiveRecord::Base
+      self.table_name = "typesafe_calls"
+    end
+  end
+end

data/lib/typesafe/rails/client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "typesafe/sdk"
+
+module Typesafe
+  module Rails
+    class Client
+      SDK_OPTIONS = %i[base_url headers user_agent logger retry_policy transport].freeze
+
+      DEFAULT_PRICING = {
+        "jev" => { input_per_mtok: 0.042, output_per_mtok: 0.0 },
+        "jev-latest" => { input_per_mtok: 0.042, output_per_mtok: 0.0 },
+        "jev-1.12" => { input_per_mtok: 0.042, output_per_mtok: 0.0 }
+      }.freeze
+
+      def self.from_config
+        config = Typesafe::Rails.configuration
+
+        new(
+          api_key: config&.api_key || ::Rails.application.credentials.dig(:typesafe, :api_key),
+          model: config&.model || "jev-latest",
+          timeout: config&.timeout || 10.0,
+          pricing: config&.pricing || DEFAULT_PRICING,
+          strict_logging: config&.strict_logging || false,
+          **sdk_options_from(config)
+        )
+      end
+
+      def self.sdk_options_from(config)
+        SDK_OPTIONS.each_with_object({}) do |key, acc|
+          value = config&.public_send(key)
+          acc[key] = value unless value.nil?
+        end
+      end
+      private_class_method :sdk_options_from
+
+      def initialize(
+        api_key:,
+        model: "jev-latest",
+        timeout: 10.0,
+        pricing: DEFAULT_PRICING,
+        strict_logging: false,
+        sdk_client: nil,
+        **sdk_options
+      )
+        @pricing = pricing
+        @strict_logging = strict_logging
+        @sdk = sdk_client || Typesafe::SDK::Client.new(
+          api_key: api_key, model: model, timeout: timeout, **sdk_options
+        )
+      end
+
+      def ask(decision_type:, state:, questions:, **call_options)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = @sdk.system_one(state: state, questions: questions, **call_options)
+        latency_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0
+
+        record_call(response, decision_type: decision_type, latency_ms: latency_ms)
+        Result.new(response: response, decision_type: decision_type)
+      end
+
+      def models
+        @sdk.models
+      end
+
+      def close
+        @sdk.close if @sdk.respond_to?(:close)
+        nil
+      end
+
+      attr_reader :sdk
+
+      private
+
+      def record_call(response, decision_type:, latency_ms:)
+        rates = pricing_for(response.model)
+        input_rate = rate_value(rates, :input_per_mtok)
+        output_rate = rate_value(rates, :output_per_mtok)
+
+        CallLog.create!(
+          decision_type: decision_type.to_s,
+          model: response.model,
+          input_tokens: response.usage&.input_tokens,
+          output_tokens: response.usage&.output_tokens,
+          input_rate: input_rate,
+          output_rate: output_rate,
+          cost_usd: estimate_cost(response.usage, input_rate, output_rate),
+          latency_ms: latency_ms,
+          request_id: response.respond_to?(:request_id) ? response.request_id : nil
+        )
+      rescue StandardError => error
+        raise if @strict_logging
+
+        warn_logging_failure(error)
+      end
+
+      def pricing_for(model)
+        return @pricing.call(model) if @pricing.respond_to?(:call)
+        return nil unless @pricing.respond_to?(:[])
+        return @pricing if rate_hash?(@pricing)
+
+        exact = @pricing[model] ||
+                (model.respond_to?(:to_sym) ? @pricing[model.to_sym] : nil)
+        return exact unless exact.nil?
+
+        if model.to_s.start_with?("jev-")
+          family = @pricing["jev"] || @pricing[:jev]
+          return family unless family.nil?
+        end
+
+        @pricing["default"] || @pricing[:default]
+      end
+
+      def rate_hash?(value)
+        value.is_a?(Hash) &&
+          (value.key?(:input_per_mtok) || value.key?("input_per_mtok"))
+      end
+
+      def rate_value(rates, key)
+        return nil unless rates.respond_to?(:[])
+
+        value = rates[key]
+        value = rates[key.to_s] if value.nil?
+        value&.to_f
+      end
+
+      def estimate_cost(usage, input_rate, output_rate)
+        return nil if usage.nil? || input_rate.nil? || output_rate.nil?
+        return nil if usage.input_tokens.nil?
+        return nil if output_rate.nonzero? && usage.output_tokens.nil?
+
+        input_cost = usage.input_tokens.to_f / 1_000_000 * input_rate
+        output_tokens = usage.output_tokens || 0
+        output_cost = output_tokens.to_f / 1_000_000 * output_rate
+        input_cost + output_cost
+      end
+
+      def warn_logging_failure(error)
+        return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+
+        ::Rails.logger.warn(
+          "typesafe-ai-rails could not persist call telemetry: #{error.class}: #{error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/typesafe/rails/decision_policy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    class DecisionPolicy < ActiveRecord::Base
+      self.table_name = "typesafe_decision_policies"
+
+      DEFAULT_ANSWER_KEY = "*"
+      FALLBACKS = %w[deterministic_rule surface_to_user escalate].freeze
+
+      validates :decision_type, presence: true
+      validates :answer_key, presence: true,
+                             uniqueness: { scope: :decision_type }
+      validates :confidence_threshold,
+                numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 }
+      validates :fallback, inclusion: { in: FALLBACKS }
+
+      scope :active, -> { where(active: true) }
+
+      def self.resolve(decision_type:, answer_key:)
+        decision_type = decision_type.to_s
+        answer_key = answer_key.to_s
+
+        active.find_by(decision_type: decision_type, answer_key: answer_key) ||
+          active.find_by(decision_type: decision_type, answer_key: DEFAULT_ANSWER_KEY)
+      end
+    end
+  end
+end

data/lib/typesafe/rails/questions.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    module Questions
+      def noul(instructions = nil, criteria = nil, **fields)
+        question_hash("noul", instructions, criteria, fields) do |value|
+          next if value.nil? || value.is_a?(Hash)
+
+          raise ArgumentError, "noul criteria must be a hash with true/false descriptions"
+        end
+      end
+
+      def choice(instructions = nil, criteria = nil, **fields)
+        question_hash("choice", instructions, criteria, fields) do |value|
+          unless value.is_a?(Hash) && !value.empty?
+            raise ArgumentError, "choice requires a non-empty criteria hash"
+          end
+        end
+      end
+
+      def score(instructions = nil, criteria = nil, **fields)
+        question_hash("score", instructions, criteria, fields) do |value|
+          unless value.is_a?(Array) && value.length.between?(2, 10)
+            raise ArgumentError, "score criteria must be an array with 2 to 10 levels"
+          end
+        end
+      end
+
+      private
+
+      def question_hash(type, instructions, criteria, fields)
+        fields = fields.dup
+        reject_type_override!(fields, type)
+        instructions = merge_argument!(fields, :instructions, instructions)
+        criteria = merge_argument!(fields, :criteria, criteria)
+        yield(criteria) if block_given?
+
+        question = { "type" => type }
+        question["instructions"] = instructions unless instructions.nil?
+        question["criteria"] = criteria unless criteria.nil?
+        fields.each { |key, value| question[key.to_s] = value }
+        question
+      end
+
+      def merge_argument!(fields, name, positional)
+        return positional unless fields.key?(name)
+        raise ArgumentError, "#{name} given both positionally and as a keyword" unless positional.nil?
+
+        fields.delete(name)
+      end
+
+      def reject_type_override!(fields, expected)
+        return unless fields.key?(:type)
+
+        supplied = fields.delete(:type)
+        return if supplied.to_s == expected
+
+        raise ArgumentError, "#{expected} helper cannot build type #{supplied.inspect}"
+      end
+    end
+  end
+end

data/lib/typesafe/rails/railtie.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.typesafe = ActiveSupport::OrderedOptions.new
+
+      config.typesafe.api_key = nil
+      config.typesafe.base_url = nil
+      config.typesafe.model = "jev-latest"
+      config.typesafe.timeout = 10.0
+      config.typesafe.headers = nil
+      config.typesafe.user_agent = nil
+      config.typesafe.logger = nil
+      config.typesafe.retry_policy = nil
+      config.typesafe.transport = nil
+      config.typesafe.strict_logging = false
+      config.typesafe.pricing = Client::DEFAULT_PRICING.transform_values(&:dup)
+
+      initializer "typesafe.configure" do |app|
+        Typesafe::Rails.configuration = app.config.typesafe
+      end
+
+      generators do
+        require "generators/typesafe/rails/install/install_generator"
+      end
+    end
+  end
+end

data/lib/typesafe/rails/result.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    class LowConfidenceError < StandardError
+      attr_reader :answer_key, :confidence, :policy
+
+      def initialize(answer_key, confidence, policy)
+        @answer_key = answer_key
+        @confidence = confidence
+        @policy = policy
+        super(
+          "#{answer_key.inspect} confidence #{confidence.inspect} is below the " \
+          "#{policy.confidence_threshold} threshold configured for " \
+          "decision_type #{policy.decision_type.inspect}"
+        )
+      end
+    end
+
+    class MissingPolicyError < StandardError
+      attr_reader :decision_type, :answer_key
+
+      def initialize(decision_type, answer_key)
+        @decision_type = decision_type
+        @answer_key = answer_key
+        super(
+          "no active TypeSafe decision policy for #{decision_type.inspect} / " \
+          "#{answer_key.inspect}; use Result#[] directly for intentionally ungated reads"
+        )
+      end
+    end
+
+    class UnsupportedConfidenceGateError < StandardError
+      attr_reader :answer_key, :answer
+
+      def initialize(answer_key, answer)
+        @answer_key = answer_key
+        @answer = answer
+        super(
+          "#{answer_key.inspect} returned #{answer.class}, which has no TypeSafe confidence value; " \
+          "Noul answers expose probability as #noul and must be thresholded explicitly"
+        )
+      end
+    end
+
+    class MissingConfidenceError < StandardError
+      attr_reader :answer_key, :answer
+
+      def initialize(answer_key, answer)
+        @answer_key = answer_key
+        @answer = answer
+        super("#{answer_key.inspect} returned a confidence-bearing answer with confidence=nil")
+      end
+    end
+
+    class Result
+      attr_reader :response, :decision_type
+
+      def initialize(response:, decision_type:)
+        @response = response
+        @decision_type = decision_type.to_s
+      end
+
+      def answers = response.answers
+      def nouls = response.nouls
+      def choices = response.choices
+      def scores = response.scores
+      def usage = response.usage
+      def [](key) = response[key]
+
+      def act!(answer_key, fallback:)
+        answer = response[answer_key]
+        return call_fallback(fallback, :missing_answer, nil) if answer.nil?
+
+        unless answer.respond_to?(:confidence)
+          raise UnsupportedConfidenceGateError.new(answer_key, answer)
+        end
+
+        confidence = answer.confidence
+        raise MissingConfidenceError.new(answer_key, answer) if confidence.nil?
+
+        policy = DecisionPolicy.resolve(decision_type: decision_type, answer_key: answer_key)
+        raise MissingPolicyError.new(decision_type, answer_key) if policy.nil?
+
+        return yield(answer) if confidence >= policy.confidence_threshold
+
+        case policy.fallback
+        when "escalate"
+          raise LowConfidenceError.new(answer_key, confidence, policy)
+        else
+          call_fallback(fallback, policy.fallback, answer)
+        end
+      end
+
+      private
+
+      def call_fallback(fallback, mode, answer)
+        handler =
+          if fallback.respond_to?(:call)
+            fallback
+          elsif fallback.respond_to?(:[])
+            fallback[mode.to_sym] || fallback[mode.to_s]
+          end
+
+        unless handler.respond_to?(:call)
+          raise ArgumentError, "fallback handler for #{mode.inspect} is required"
+        end
+
+        handler.call(answer)
+      end
+    end
+  end
+end

data/lib/typesafe/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module Rails
+    VERSION = "0.4.0"
+  end
+end

data/lib/typesafe/rails.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "typesafe/rails/version"
+require "typesafe/rails/questions"
+require "typesafe/rails/decision_policy"
+require "typesafe/rails/call_log"
+require "typesafe/rails/result"
+require "typesafe/rails/client"
+require "typesafe/rails/railtie" if defined?(::Rails::Railtie)
+
+module Typesafe
+  module Rails
+    class << self
+      include Questions
+
+      attr_accessor :configuration
+
+      def client
+        @client ||= Client.from_config
+      end
+
+      def reset_client!
+        @client&.close
+        @client = nil
+      end
+    end
+  end
+end

data/lib/typesafe-ai-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "typesafe/rails"

data/typesafe-ai-rails.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/typesafe/rails/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "typesafe-ai-rails"
+  spec.version     = Typesafe::Rails::VERSION
+  spec.authors     = ["Genie Developments"]
+
+  spec.summary     = "Community Rails integration for TypeSafe AI System One."
+  spec.description = "Rails configuration, model-aware call/cost telemetry, and fail-closed " \
+                     "confidence policies for TypeSafe Choice and Score judgments on top of " \
+                     "the community typesafe-sdk Ruby gem. This is not an official TypeSafe package."
+  spec.homepage    = "https://github.com/GenieRobot/typesafe-ai-rails"
+  spec.license     = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["source_code_uri"]       = spec.homepage
+  spec.metadata["changelog_uri"]         = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"]       = "#{spec.homepage}/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|\.github)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", ">= 7.0", "< 9.0"
+  spec.add_dependency "railties", ">= 7.0", "< 9.0"
+  spec.add_dependency "typesafe-sdk", "~> 0.3"
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "sqlite3", ">= 2.0", "< 3.0"
+end

metadata

@@ -0,0 +1,171 @@
+--- !ruby/object:Gem::Specification
+name: typesafe-ai-rails
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Genie Developments
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: typesafe-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Rails configuration, model-aware call/cost telemetry, and fail-closed
+  confidence policies for TypeSafe Choice and Score judgments on top of the community
+  typesafe-sdk Ruby gem. This is not an official TypeSafe package.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/typesafe/rails/install/install_generator.rb
+- lib/generators/typesafe/rails/install/templates/POST_INSTALL.md
+- lib/generators/typesafe/rails/install/templates/create_typesafe_rails_tables.rb.tt
+- lib/generators/typesafe/rails/install/templates/typesafe.rb.tt
+- lib/generators/typesafe/rails/install/templates/upgrade_typesafe_rails_to_0_4.rb.tt
+- lib/typesafe-ai-rails.rb
+- lib/typesafe/rails.rb
+- lib/typesafe/rails/call_log.rb
+- lib/typesafe/rails/client.rb
+- lib/typesafe/rails/decision_policy.rb
+- lib/typesafe/rails/questions.rb
+- lib/typesafe/rails/railtie.rb
+- lib/typesafe/rails/result.rb
+- lib/typesafe/rails/version.rb
+- typesafe-ai-rails.gemspec
+homepage: https://github.com/GenieRobot/typesafe-ai-rails
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/GenieRobot/typesafe-ai-rails
+  changelog_uri: https://github.com/GenieRobot/typesafe-ai-rails/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/GenieRobot/typesafe-ai-rails/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Community Rails integration for TypeSafe AI System One.
+test_files: []