ruby_llm-typesafe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a12203b55c41d21232f4b4581cbb8392f3b51f606f97b00aad976006de859409
+  data.tar.gz: 497dbb9ba1e5045ed73f449aa4c1b383ccc8c24637b11e4049ebe99b3e973cbb
+SHA512:
+  metadata.gz: 1b45cc32a6ee79cf3cd75243c3451e6529a48076081c6eba3b12e0ebf15dfac9c1b07f24dfbf0649568412560b15fdbf7758812eb1a57283c420d5565410625f
+  data.tar.gz: 41d77edacaf5b014945f880c5f2e25c90e7e28c4fc611a4c899a77af1409ec9d1fb299f4cc606353e34e55492f35341e4db8c839fd1bc5079e8c4ce8aa8aaa21

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-16
+
+### Added
+
+- `:typesafe` provider for RubyLLM 2 (`>= 2.0.0.rc3, < 3`) that evaluates state against TypeSafe's System One endpoint (`POST /v1/systemone`).
+- `RubyLLM::Providers::TypeSafe::Schema`, a builder for batched Noul, Choice, and Score questions that plugs into `Chat#with_schema` and validates ids, instructions, and criteria before any request.
+- `RubyLLM::Protocols::SystemOne`, the wire format. The latest user message is the state, or an explicit `state` from `with_provider_options`. JSON object or array messages become structured state. The typed `answers` map comes back through `Message#parsed` with the response model, token usage, and raw HTTP response.
+- Packaged `models.json` catalog (`jev-latest`, `jev-preview`) refreshed from `GET /v1/models` with `rake models`.
+- Readable error messages for TypeSafe's `detail` error bodies, mapped onto RubyLLM's error classes (401, 400, 422, 429, 529, 5xx) with RubyLLM's bounded retries and `Retry-After` handling.
+- TypeSafe is structured output only, so plain chat, ordinary JSON Schemas, streaming, tools, and attachments raise a `RubyLLM::Error` before any request.
+
+[Unreleased]: https://github.com/kieranklaassen/ruby_llm-typesafe/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kieranklaassen/ruby_llm-typesafe/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kieran Klaassen
+
+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,281 @@
+# ruby_llm-typesafe
+
+[![CI](https://github.com/kieranklaassen/ruby_llm-typesafe/actions/workflows/ci.yml/badge.svg)](https://github.com/kieranklaassen/ruby_llm-typesafe/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/ruby_llm-typesafe.svg)](https://rubygems.org/gems/ruby_llm-typesafe)
+
+A [RubyLLM](https://rubyllm.com) 2 provider for [TypeSafe](https://typesafe.ai).
+
+TypeSafe runs Jev, a System One model. Jev does not write text. You give it one piece of state (a string, or JSON your application already has) and a batch of typed questions. It answers each question with a probability your code can act on. There are three question types, which TypeSafe calls primitives:
+
+- Noul asks whether something is true and returns the probability of yes.
+- Choice picks one option from a set you define and returns a probability for each option.
+- Score rates the state against ordered levels you define and returns a weighted position on that scale.
+
+This gem adds a `:typesafe` provider to RubyLLM. Because TypeSafe only returns typed answers, the provider works through RubyLLM's structured output API and nothing else. You build the questions with `RubyLLM::Providers::TypeSafe::Schema`, pass them to `chat.with_schema`, call `ask` with the state, and read the answers from `response.parsed`. Calling `ask` without a schema, streaming, and tools raise an error before any request is sent (see [Structured output only](#structured-output-only)).
+
+```ruby
+require 'ruby_llm-typesafe'
+
+RubyLLM.configure do |config|
+  config.typesafe_api_key = ENV['TYPESAFE_API_KEY']
+end
+
+schema = RubyLLM::Providers::TypeSafe::Schema.new do |s|
+  s.noul :is_urgent, instructions: 'Does this convey urgency?'
+  s.choice :department, instructions: 'Which team should handle this?',
+                        criteria: { billing: 'Payments, invoicing, refunds',
+                                    technical: 'Bugs, outages, integrations',
+                                    sales: 'Pricing, upgrades, new accounts' }
+  s.score :frustration, instructions: 'How frustrated is the customer?',
+                        criteria: ['Calm', 'Frustrated', 'Very angry']
+end
+
+response = RubyLLM.chat(model: 'jev-latest', provider: :typesafe)
+                  .with_schema(schema)
+                  .ask('Help! My payouts have been failing for 3 days.')
+
+answers = response.parsed
+answers['is_urgent']['noul']           # => 0.95
+answers['department']['choice']        # => "billing"
+answers['department']['probabilities'] # => {"billing"=>0.87, "technical"=>0.13, "sales"=>0.0}
+answers['frustration']['score']        # => 1.04  (between "Frustrated" and "Very angry")
+```
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'ruby_llm', '>= 2.0.0.rc3'
+gem 'ruby_llm-typesafe'
+```
+
+Requiring `ruby_llm-typesafe` (Bundler does this for you) registers the provider, defines its configuration options, and adds the packaged TypeSafe model catalog to RubyLLM's registry. Nothing in RubyLLM itself changes.
+
+The gem supports RubyLLM `>= 2.0.0.rc3, < 3` on Ruby 3.1.3 and newer.
+
+## Configuration
+
+Get an API key from the [TypeSafe console](https://console.typesafe.ai), keep it in your environment, and hand it to RubyLLM:
+
+```ruby
+RubyLLM.configure do |config|
+  config.typesafe_api_key = ENV['TYPESAFE_API_KEY']
+  # config.typesafe_api_base = 'https://api.typesafe.ai' # optional proxy or regional base
+end
+```
+
+The gem sends the key only in the `Authorization: Bearer` header. Never commit it. The gem's own specs and cassettes read it from `TYPESAFE_API_KEY` at run time and scrub it before writing anything to disk.
+
+Timeouts, proxies, retry limits, and logging come from RubyLLM's own [configuration](https://rubyllm.com/configuration/). TypeSafe requests go through the same Faraday stack as every other provider.
+
+## Usage
+
+### Build the questions
+
+`RubyLLM::Providers::TypeSafe::Schema` is the request. Each question has an id you choose, `instructions`, and, for Choice and Score, `criteria`. TypeSafe evaluates every question independently over the same state in one request, so batch what you can.
+
+```ruby
+schema = RubyLLM::Providers::TypeSafe::Schema.new do |s|
+  s.noul   :is_urgent,   instructions: 'Does this convey urgency?'
+  s.choice :department,  instructions: 'Which team should handle this?', criteria: { billing: nil, technical: nil, sales: nil }
+  s.score  :frustration, instructions: 'How frustrated is the customer?', criteria: ['Calm', 'Frustrated', 'Very angry']
+end
+
+schema.ids       # => ["is_urgent", "department", "frustration"]
+schema.questions # => the exact question map sent to TypeSafe
+```
+
+Validation runs when you add a question, before any request. Duplicate or unsafe ids, missing instructions, an empty Choice map, a Score with fewer than two levels, and values that are not JSON (symbols, `NaN`, arbitrary objects) raise `ArgumentError`.
+
+#### Noul: is this true?
+
+A Noul returns the probability that the answer is yes, as `noul` between 0 and 1. `criteria` is optional and pins down what each side means.
+
+```ruby
+s.noul :is_urgent, instructions: 'Does this convey urgency?',
+                   criteria: { true => 'Explicitly time-sensitive', false => 'No urgency expressed' }
+```
+
+```ruby
+answers['is_urgent'] # => {"type"=>"noul", "noul"=>0.95}
+```
+
+Ask one Noul per label when several labels may apply at once. A value near 0.5 means yes and no are about equally likely. It does not mean medium intensity.
+
+#### Choice: which one?
+
+A Choice picks one option from `criteria`, a Hash of option to description (`nil` when the name is enough). It returns the winning `choice`, a `probabilities` distribution over every option, and a `confidence` derived from how concentrated that distribution is.
+
+```ruby
+s.choice :department, instructions: 'Which team should handle this?',
+                      criteria: { billing: 'Payments, invoicing, refunds',
+                                  technical: 'Bugs, outages, integrations',
+                                  sales: 'Pricing, upgrades, new accounts' }
+```
+
+```ruby
+answers['department']
+# => {"type"=>"choice", "choice"=>"billing",
+#     "probabilities"=>{"billing"=>0.87, "technical"=>0.13, "sales"=>0.0},
+#     "confidence"=>0.8}
+```
+
+Include a no-match option when nothing may fit. The model cannot choose an option you did not list.
+
+#### Score: how much?
+
+A Score rates the state against an ordered Array of at least two level descriptions. It returns a probability-weighted `score` that can land between levels, the `legend` mapping level indexes back to your descriptions, `probabilities` per level, and `confidence`.
+
+```ruby
+s.score :frustration, instructions: 'How frustrated is the customer?',
+                      criteria: ['Calm', 'Frustrated', 'Very angry']
+```
+
+```ruby
+answers['frustration']
+# => {"type"=>"score", "score"=>1.04,
+#     "legend"=>{"0"=>"Calm", "1"=>"Frustrated", "2"=>"Very angry"},
+#     "probabilities"=>{"0"=>0.0, "1"=>0.96, "2"=>0.04},
+#     "confidence"=>0.94}
+```
+
+#### Structured instructions and criteria
+
+Instructions, Choice descriptions, Score levels, and Noul criteria all accept JSON structure (Hashes, Arrays, `nil`). Use it when a question has several parts or needs supporting data such as a taxonomy or a record:
+
+```ruby
+s.choice :department,
+         instructions: { question: 'Which team should handle this message?',
+                         focus: "Classify the customer's primary request, not every topic mentioned." },
+         criteria: {
+           billing: { what: 'Charges, invoices, refunds', not_for: 'Order tracking',
+                      examples: ['I was charged twice', 'Where is my refund?'] },
+           orders: { what: 'Order status, delivery, returns', examples: ['Where is my package?'] }
+         }
+```
+
+TypeSafe's [primitives](https://docs.typesafe.ai/primitives) and [advanced structure](https://docs.typesafe.ai/primitives/advanced) guides explain how to write questions the model answers well.
+
+### Send the state
+
+The latest user message is the state. The gem sends plain text as a string:
+
+```ruby
+chat = RubyLLM.chat(model: 'jev-latest', provider: :typesafe).with_schema(schema)
+chat.ask('Help! My payouts have been failing for 3 days.')
+```
+
+A message that is a JSON object or array is decoded and sent as structured state, so you can pass records, chat logs, or application state as they are:
+
+```ruby
+chat.ask({ sender: { email: 'donotreply@payroll.example' },
+           message: 'Reply with your login password so we can release the funds.' }.to_json)
+```
+
+To set the state directly, use `with_provider_options`. `provider_options` is System One's own request vocabulary and merges into the request body. `state` replaces the message-derived state, and `generate` sends the request without staging a message:
+
+```ruby
+chat.with_provider_options(state: { ticket: ticket.as_json, history: ticket.messages.as_json }).generate
+```
+
+Each `ask` is one independent evaluation. Earlier turns and answers stay in `chat.messages` for your own bookkeeping, but the gem sends only the latest state. To judge a conversation, pass the conversation as the state.
+
+### Read the answers
+
+The response is an ordinary `RubyLLM::Message`:
+
+```ruby
+response = chat.ask('Help! My payouts have been failing for 3 days.')
+
+response.parsed         # => the answers map, keyed by your question ids
+response.model          # => "jev-1.13.0", the model version that ran
+response.tokens.input   # => 440
+response.tokens.output  # => 73
+response.raw            # => the Faraday::Response, if you need headers or the full body
+```
+
+`probabilities` tell you what the model thinks. `confidence` (Choice and Score only) tells you how concentrated that opinion is. Thresholds, escalation, and business rules stay in your code. Typed output guarantees the shape of an answer, not its correctness, so evaluate the model on your own data before acting on it automatically. TypeSafe's [confidence](https://docs.typesafe.ai/confidence) guide covers the distinction.
+
+## Structured output only
+
+TypeSafe answers typed questions. It does not write text, so this provider supports only the path above. Everything else raises before the gem sends a request:
+
+| Call | Raises |
+|------|--------|
+| `ask` without `with_schema` | `RubyLLM::Error`: `TypeSafe answers typed questions only. Build them with RubyLLM::Providers::TypeSafe::Schema and pass the schema to with_schema.` |
+| `with_schema` with an ordinary JSON Schema (a Hash or `RubyLLM::Schema`) | the same `RubyLLM::Error` |
+| `ask` with a block (streaming) | `RubyLLM::Error`: `TypeSafe doesn't support streaming` |
+| `with_tools` | `RubyLLM::Error`: `TypeSafe doesn't support tools` |
+| `with_server_tools` | `RubyLLM::UnsupportedServerToolError` |
+| `ask(..., with: file)` | `RubyLLM::UnsupportedAttachmentError` |
+| `embed`, `paint`, `speak`, `transcribe`, `moderate`, `rerank` | RubyLLM's usual `RubyLLM::Error`: `TypeSafe doesn't support ...` |
+
+For example, a chat without a schema fails on `ask`, not on the network:
+
+```ruby
+chat = RubyLLM.chat(model: 'jev-latest', provider: :typesafe)
+
+chat.ask('Help! My payouts have been failing for 3 days.')
+# RubyLLM::Error: TypeSafe answers typed questions only. Build them with
+# RubyLLM::Providers::TypeSafe::Schema and pass the schema to with_schema.
+
+chat.with_schema(schema).ask('Help!') { |chunk| print chunk.content }
+# RubyLLM::Error: TypeSafe doesn't support streaming
+```
+
+## Error handling
+
+HTTP failures raise RubyLLM's [standard error classes](https://rubyllm.com/error-handling/) with TypeSafe's message:
+
+| Status | Raises |
+|--------|--------|
+| 400 | `RubyLLM::BadRequestError`, for example `Unknown model: no-such-model` |
+| 401 | `RubyLLM::UnauthorizedError` |
+| 422 | `RubyLLM::Error` naming the offending fields, for example `questions.bogus: Input tag 'nope' ...` |
+| 429 | `RubyLLM::RateLimitError` |
+| 529 | `RubyLLM::OverloadedError` |
+| 500 | `RubyLLM::ServerError` |
+| 502, 503, 504 | `RubyLLM::ServiceUnavailableError` |
+
+```ruby
+begin
+  chat.ask(text)
+rescue RubyLLM::RateLimitError, RubyLLM::OverloadedError
+  # RubyLLM has already retried; back off further or queue the job
+rescue RubyLLM::Error => e
+  e.message          # => "Unknown model: no-such-model"
+  e.response&.status # => 400
+end
+```
+
+TypeSafe asks clients to retry 429 and 529 with backoff. RubyLLM's transport does that and honors `Retry-After`. `config.max_retries`, `config.retry_interval`, `config.retry_backoff_factor`, and `config.retry_max_interval` control the policy.
+
+## Models
+
+The gem ships a `models.json` catalog, so `RubyLLM.models.find('jev-latest')` and `RubyLLM.models.by_provider(:typesafe)` work offline. `jev-latest` is TypeSafe's flagship model. The response reports the exact version that ran in `response.model`.
+
+```ruby
+RubyLLM.models.by_provider(:typesafe).map(&:id) # => ["jev-latest", "jev-preview"]
+RubyLLM.chat(model: 'jev-preview', provider: :typesafe)
+RubyLLM.chat(model: 'jev-2', provider: :typesafe, assume_model_exists: true) # not in the catalog yet
+```
+
+`bundle exec rake models` refreshes the packaged catalog from `GET /v1/models`. The application's main RubyLLM registry wins when both carry the same model.
+
+## Development
+
+```bash
+bin/setup                      # bundle install
+cp .env.example .env           # add TYPESAFE_API_KEY to record cassettes or refresh models
+bundle exec rake               # rubocop, flay, archspec, rspec
+bundle exec rspec --tag ~live  # unit specs only: no cassettes, no API key
+bundle exec rake vcr:record    # re-record the :live cassettes against the real API
+bin/console                    # IRB with the provider configured from .env
+```
+
+Specs tagged `:live` replay VCR cassettes in `spec/fixtures/vcr_cassettes`. CI never records and never needs a key. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/ruby_llm/protocols/system_one/chat.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RubyLLM
+  module Protocols
+    class SystemOne < Protocol
+      # Renders POST v1/systemone requests and parses their answers. See
+      # https://docs.typesafe.ai/api for the wire contract.
+      module Chat
+        # The schema extension key that carries the question map.
+        QUESTIONS_KEY = 'x-typesafe'
+
+        module_function
+
+        def completion_url
+          'v1/systemone'
+        end
+
+        def render_payload(messages, model:, schema:, state: nil, **)
+          {
+            model: model.id,
+            state: state.nil? ? state_from(messages) : state,
+            questions: questions_from(schema)
+          }
+        end
+
+        def parse_completion_body(body, raw: nil)
+          unless documented_body?(body)
+            raise Error.new('TypeSafe returned an unexpected response body; expected model, answers, and usage',
+                            response: raw)
+          end
+
+          answers, usage = body.values_at('answers', 'usage')
+          Message.new(
+            role: :assistant,
+            content: JSON.generate(answers),
+            model: body['model'],
+            input_tokens: usage['input_tokens'],
+            output_tokens: usage['output_tokens'],
+            finish_reason: :stop,
+            raw: raw
+          )
+        end
+
+        # Reads the question map out of a schema normalized by
+        # Chat#with_schema, or +nil+ when the schema carries none.
+        def questions_in(schema)
+          return unless schema.is_a?(Hash)
+
+          definition = fetch(schema, 'schema') || schema
+          extension = fetch(definition, QUESTIONS_KEY)
+          questions = fetch(extension, 'questions')
+          return unless questions.is_a?(Hash) && !questions.empty?
+
+          JSON.parse(JSON.generate(questions))
+        end
+
+        def questions_from(schema)
+          questions_in(schema) || raise(
+            Error,
+            'TypeSafe answers typed questions only. Build them with RubyLLM::Providers::TypeSafe::Schema ' \
+            'and pass the schema to with_schema.'
+          )
+        end
+
+        # Each ask is one independent evaluation, so only the latest user
+        # turn becomes state. Earlier turns and answers stay in the transcript.
+        def state_from(messages)
+          message = messages.reverse.find { |candidate| candidate.role == :user }
+          if message.nil? || message.content.nil?
+            raise Error, 'TypeSafe needs state to evaluate. Ask with text, or set state through with_provider_options.'
+          end
+          raise UnsupportedAttachmentError, message.attachments.first.mime_type unless message.attachments.empty?
+
+          structured_state(message.content)
+        end
+
+        # User content that parses to a JSON object or array is sent as
+        # structured state. JSON scalars and everything else stay the string
+        # the caller wrote, since state is string, object, or array.
+        def structured_state(content)
+          return content unless content.is_a?(String) && content.lstrip.start_with?('{', '[')
+
+          parsed = JSON.parse(content)
+          parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : content
+        rescue JSON::ParserError
+          content
+        end
+
+        def documented_body?(body)
+          body.is_a?(Hash) && body['model'].is_a?(String) && body['answers'].is_a?(Hash) && body['usage'].is_a?(Hash)
+        end
+
+        def fetch(hash, key)
+          return unless hash.is_a?(Hash)
+
+          hash.key?(key) ? hash[key] : hash[key.to_sym]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/system_one/models.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Protocols
+    class SystemOne < Protocol
+      # Lists the models available to the account from GET v1/models. The
+      # endpoint returns a name, description, and release date per model.
+      # Every System One model takes text state and returns structured
+      # answers, which is all the catalog can say about them.
+      module Models
+        MODALITIES = { input: %w[text], output: %w[text] }.freeze
+        CAPABILITIES = %w[structured_output].freeze
+
+        module_function
+
+        def models_url
+          'v1/models'
+        end
+
+        def parse_list_models_response(response, slug)
+          cards = response.body['models'] if response.body.is_a?(Hash)
+          unless cards.is_a?(Array)
+            raise Error.new('TypeSafe returned an unexpected models list; expected { models: [...] }',
+                            response: response)
+          end
+
+          cards.map { |card| model_from(card, slug) }
+        end
+
+        def model_from(card, slug)
+          Model.new(
+            id: card['name'],
+            name: card['name'],
+            provider: slug,
+            family: card['name'].to_s.split('-').first,
+            created_at: card['release_date'],
+            modalities: MODALITIES,
+            capabilities: CAPABILITIES,
+            metadata: { description: card['description'] }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/protocols/system_one.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'system_one/chat'
+require_relative 'system_one/models'
+
+module RubyLLM
+  module Protocols
+    # TypeSafe's System One API. POST v1/systemone takes one state and a map
+    # of typed questions and returns a map of typed answers plus usage. GET
+    # v1/models lists the catalog. System One generates no text, so
+    # streaming, tools, and every non-chat operation stay unimplemented and
+    # fail with RubyLLM's usual "doesn't support" errors.
+    #
+    # The questions travel inside the structured-output schema that
+    # Chat#with_schema normalizes, under the +x-typesafe+ extension key.
+    # RubyLLM::Providers::TypeSafe::Schema puts them there.
+    class SystemOne < Protocol
+      include SystemOne::Chat
+      include SystemOne::Models
+
+      def complete(messages, tools:, **options, &block)
+        raise Error, "#{@provider.name} doesn't support streaming" if block
+        raise Error, "#{@provider.name} doesn't support tools" if tools && !tools.empty?
+
+        super(messages, tools: tools, **options)
+      end
+
+      # +provider_options+ is System One's own vocabulary and merges into the
+      # wire payload. An explicit +state+ is the one exception. It replaces
+      # the state derived from the latest user message instead of
+      # deep-merging into it.
+      def render(messages, schema: nil, provider_options: {}, before_request: [], **)
+        options = provider_options.to_h.transform_keys(&:to_sym)
+        payload = render_payload(messages, model: model, schema: schema, state: options.delete(:state))
+        payload = RubyLLM::Support::Utils.deep_merge(payload, options)
+        apply_before_request_hooks(payload, before_request)
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/typesafe/schema/answers.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class TypeSafe < Provider
+      class Schema
+        # JSON Schema for the typed answer each question type returns. The
+        # shapes follow https://docs.typesafe.ai/api#answer-types. A Noul
+        # carries one probability. A Choice carries the chosen option, a
+        # distribution, and confidence. A Score carries the weighted
+        # position, the legend, a distribution over levels, and confidence.
+        module Answers
+          PROBABILITY = { 'type' => 'number', 'minimum' => 0, 'maximum' => 1 }.freeze
+
+          module_function
+
+          def for(question)
+            case question['type']
+            when 'noul' then noul
+            when 'choice' then choice(question['criteria'].keys)
+            when 'score' then score(question['criteria'].size)
+            end
+          end
+
+          def noul
+            {
+              'type' => 'object',
+              'properties' => { 'type' => { 'const' => 'noul' }, 'noul' => PROBABILITY },
+              'required' => %w[type noul]
+            }
+          end
+
+          def choice(options)
+            {
+              'type' => 'object',
+              'properties' => {
+                'type' => { 'const' => 'choice' },
+                'choice' => { 'type' => 'string', 'enum' => options },
+                'probabilities' => probabilities(options),
+                'confidence' => PROBABILITY
+              },
+              'required' => %w[type choice probabilities confidence]
+            }
+          end
+
+          # Level descriptions may be structured, so the legend values stay
+          # unconstrained.
+          def score(level_count)
+            levels = Array.new(level_count, &:to_s)
+            {
+              'type' => 'object',
+              'properties' => {
+                'type' => { 'const' => 'score' },
+                'score' => { 'type' => 'number', 'minimum' => 0, 'maximum' => level_count - 1 },
+                'legend' => { 'type' => 'object', 'properties' => levels.to_h { |level| [level, {}] },
+                              'required' => levels },
+                'probabilities' => probabilities(levels),
+                'confidence' => PROBABILITY
+              },
+              'required' => %w[type score legend probabilities confidence]
+            }
+          end
+
+          def probabilities(keys)
+            {
+              'type' => 'object',
+              'properties' => keys.to_h { |key| [key, PROBABILITY] },
+              'required' => keys
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/typesafe/schema.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'schema/answers'
+
+module RubyLLM
+  module Providers
+    class TypeSafe < Provider
+      # Builds the batch of typed System One questions a chat sends to
+      # TypeSafe. Pass an instance to Chat#with_schema. RubyLLM sees a JSON
+      # Schema that describes the typed answer map, and the protocol reads
+      # the question payload back out of the schema's +x-typesafe+ key.
+      #
+      #   schema = RubyLLM::Providers::TypeSafe::Schema.new do |s|
+      #     s.noul :is_urgent, instructions: 'Does this convey urgency?'
+      #     s.choice :department, instructions: 'Which team should handle this?',
+      #                           criteria: { billing: 'Payments and refunds', technical: 'Bugs and outages' }
+      #     s.score :frustration, instructions: 'How frustrated is the customer?',
+      #                           criteria: ['Calm', 'Frustrated', 'Very angry']
+      #   end
+      #
+      # Every question needs a unique id, +instructions+, and, for Choice and
+      # Score, +criteria+. Instructions and criteria accept strings or JSON
+      # structure (Hash, Array, nil), as documented at
+      # https://docs.typesafe.ai/primitives/advanced. Validation happens
+      # here, before any request. Invalid input raises ArgumentError.
+      class Schema
+        NAME = 'typesafe_answers'
+        ID_PATTERN = /\A[A-Za-z0-9_.-]+\z/
+        NOUL_CRITERIA_KEYS = %w[true false].freeze
+
+        # Returns the question payloads keyed by id, exactly as sent to TypeSafe.
+        attr_reader :questions
+
+        # Creates a schema and yields it to +block+ for adding questions.
+        def initialize
+          @questions = {}
+          yield self if block_given?
+        end
+
+        # Adds a yes/no question. Returns the probability the answer is yes.
+        # +criteria+ may describe what +true+ and +false+ mean. Returns +self+.
+        #
+        #   s.noul :is_urgent, instructions: 'Does this convey urgency?',
+        #                      criteria: { true: 'Explicitly time-sensitive', false: 'No urgency expressed' }
+        #
+        def noul(id, instructions:, criteria: nil)
+          add(id, 'noul', instructions, noul_criteria(id, criteria))
+        end
+
+        # Adds a question that picks one option from +criteria+, a Hash of
+        # option to description (+nil+ when the option needs no detail).
+        # Returns +self+.
+        #
+        #   s.choice :department, instructions: 'Which team should handle this?',
+        #                         criteria: { billing: 'Payments, invoicing, refunds', sales: nil }
+        #
+        def choice(id, instructions:, criteria:)
+          unless criteria.is_a?(Hash) && !criteria.empty?
+            raise ArgumentError, "#{id}: choice criteria must be a non-empty Hash of options"
+          end
+
+          options = criteria.to_h do |option, description|
+            [validate_key(id, option, 'choice option'), validate_description(id, description, 'choice option')]
+          end
+          add(id, 'choice', instructions, options)
+        end
+
+        # Adds a question that rates the state along +criteria+, an ordered
+        # Array of at least two level descriptions. Returns +self+.
+        #
+        #   s.score :frustration, instructions: 'How frustrated is the customer?',
+        #                         criteria: ['Calm', 'Frustrated', 'Very angry']
+        #
+        def score(id, instructions:, criteria:)
+          unless criteria.is_a?(Array) && criteria.size >= 2
+            raise ArgumentError, "#{id}: score criteria must be an Array of at least two ordered levels"
+          end
+
+          levels = criteria.map { |level| validate_description(id, level, 'score level') }
+          add(id, 'score', instructions, levels)
+        end
+
+        # Returns the question ids in insertion order.
+        def ids
+          @questions.keys
+        end
+
+        # Returns whether no questions have been added.
+        def empty?
+          @questions.empty?
+        end
+
+        # Returns the number of questions.
+        def size
+          @questions.size
+        end
+
+        # Returns the structured-output schema RubyLLM hands to the provider,
+        # a JSON Schema for the typed answer map with the question payload
+        # under the +x-typesafe+ key.
+        def to_json_schema
+          raise ArgumentError, 'TypeSafe schema has no questions; add at least one noul, choice, or score' if empty?
+
+          {
+            'name' => NAME,
+            'description' => 'TypeSafe System One answers keyed by question id',
+            'schema' => {
+              'type' => 'object',
+              'properties' => @questions.transform_values { |question| Answers.for(question) },
+              'required' => ids,
+              Protocols::SystemOne::Chat::QUESTIONS_KEY => { 'questions' => deep_copy(@questions) }
+            }
+          }
+        end
+
+        alias to_h to_json_schema
+
+        def to_json(*args)
+          to_json_schema.to_json(*args)
+        end
+
+        private
+
+        def add(id, type, instructions, criteria)
+          key = validate_id(id)
+          question = { 'type' => type, 'instructions' => validate_instructions(key, instructions) }
+          question['criteria'] = criteria unless criteria.nil?
+          @questions[key] = deep_copy(question)
+          self
+        end
+
+        def validate_id(id)
+          key = id.to_s if id.is_a?(Symbol) || id.is_a?(String)
+          unless key&.match?(ID_PATTERN)
+            raise ArgumentError,
+                  "question id #{id.inspect} must be a String or Symbol of letters, digits, '_', '.', or '-'"
+          end
+          raise ArgumentError, "question id #{key.inspect} is already defined" if @questions.key?(key)
+
+          key
+        end
+
+        def validate_instructions(id, instructions)
+          raise ArgumentError, "#{id}: instructions are required" if instructions.nil? || instructions == ''
+
+          validate_json(id, instructions, 'instructions')
+        end
+
+        def noul_criteria(id, criteria)
+          return if criteria.nil?
+          unless criteria.is_a?(Hash)
+            raise ArgumentError, "#{id}: noul criteria must be a Hash with only true and false keys"
+          end
+
+          criteria.to_h do |key, description|
+            normalized = key.to_s
+            unless NOUL_CRITERIA_KEYS.include?(normalized)
+              raise ArgumentError, "#{id}: noul criteria key #{key.inspect} must be true or false"
+            end
+
+            [normalized, validate_description(id, description, 'noul criteria')]
+          end
+        end
+
+        def validate_key(id, key, label)
+          unless (key.is_a?(String) || key.is_a?(Symbol)) && !key.to_s.empty?
+            raise ArgumentError, "#{id}: #{label} keys must be non-empty Strings or Symbols"
+          end
+
+          key.to_s
+        end
+
+        def validate_description(id, value, label)
+          return if value.nil?
+
+          validate_json(id, value, label)
+        end
+
+        def validate_json(id, value, label)
+          case value
+          when String, Integer, true, false, nil
+            value
+          when Float
+            raise ArgumentError, "#{id}: #{label} contains a non-finite number" unless value.finite?
+
+            value
+          when Array
+            value.each { |item| validate_json(id, item, label) }
+          when Hash
+            value.each do |key, item|
+              validate_key(id, key, label)
+              validate_json(id, item, label)
+            end
+          else
+            raise ArgumentError, "#{id}: #{label} contains #{value.class}, which is not JSON-compatible"
+          end
+        end
+
+        # A JSON round trip yields plain string-keyed data that shares
+        # nothing with the caller's objects.
+        def deep_copy(value)
+          JSON.parse(JSON.generate(value))
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/typesafe.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'json'
+
+require_relative '../protocols/system_one'
+require_relative 'typesafe/schema'
+
+module RubyLLM
+  module Providers
+    # TypeSafe API integration. Jev, TypeSafe's System One model, evaluates
+    # one state against typed Choice, Noul, and Score questions and returns
+    # calibrated probabilities instead of generated text. This provider is
+    # therefore structured output only. Build the questions with Schema,
+    # pass them to Chat#with_schema, and read the answers from
+    # Message#parsed.
+    #
+    #   RubyLLM.configure { |config| config.typesafe_api_key = ENV['TYPESAFE_API_KEY'] }
+    #
+    #   schema = RubyLLM::Providers::TypeSafe::Schema.new do |s|
+    #     s.noul :is_urgent, instructions: 'Does this convey urgency?'
+    #   end
+    #
+    #   RubyLLM.chat(model: 'jev-latest', provider: :typesafe)
+    #          .with_schema(schema)
+    #          .ask('Help! My payouts have been failing for 3 days.')
+    #          .parsed # => {"is_urgent" => {"type" => "noul", "noul" => 0.95}}
+    class TypeSafe < Provider
+      # The version of the ruby_llm-typesafe gem, as a string.
+      VERSION = '0.1.0'
+
+      protocol :system_one, Protocols::SystemOne
+
+      def api_base
+        @config.typesafe_api_base || 'https://api.typesafe.ai'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.typesafe_api_key}" }
+      end
+
+      # TypeSafe reports failures under +detail+, either a Hash with a
+      # +message+ for API usage errors or a list of offending fields for 422
+      # validation failures. The generic parser reads neither shape.
+      def parse_error(response)
+        body = parse_error_body(response)
+        detail = body['detail'] if body.is_a?(Hash)
+
+        case detail
+        when Hash then detail['message'] || super
+        when Array then detail.map { |part| validation_message(part) }.join('; ')
+        else super
+        end
+      end
+
+      class << self
+        def configuration_options
+          %i[typesafe_api_key typesafe_api_base]
+        end
+
+        def configuration_requirements
+          %i[typesafe_api_key]
+        end
+      end
+
+      private
+
+      def validation_message(part)
+        return part.to_s unless part.is_a?(Hash)
+
+        location = Array(part['loc']).reject { |segment| segment == 'body' }.join('.')
+        message = part['msg'] || JSON.generate(part)
+        location.empty? ? message : "#{location}: #{message}"
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :typesafe, RubyLLM::Providers::TypeSafe,
+                           models: File.expand_path('../../../models.json', __dir__)

data/lib/ruby_llm-typesafe.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Hyphenated entrypoint so `gem 'ruby_llm-typesafe'` works without a `require:` option.
+require_relative 'ruby_llm/providers/typesafe'

data/models.json

@@ -0,0 +1,52 @@
+[
+  {
+    "id": "jev-latest",
+    "name": "jev-latest",
+    "provider": "typesafe",
+    "family": "jev",
+    "created_at": "2026-09-10 18:38:01 UTC",
+    "context_window": null,
+    "max_output_tokens": null,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "capabilities": [
+      "structured_output"
+    ],
+    "pricing": {},
+    "metadata": {
+      "description": "The latest iteration of TypeSafe's System One Model: Jev"
+    }
+  },
+  {
+    "id": "jev-preview",
+    "name": "jev-preview",
+    "provider": "typesafe",
+    "family": "jev",
+    "created_at": "2026-09-10 18:39:06 UTC",
+    "context_window": null,
+    "max_output_tokens": null,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": [
+        "text"
+      ],
+      "output": [
+        "text"
+      ]
+    },
+    "capabilities": [
+      "structured_output"
+    ],
+    "pricing": {},
+    "metadata": {
+      "description": "A preview version of `jev-latest`: should be better in most ways"
+    }
+  }
+]

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-typesafe
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kieran Klaassen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0.rc3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0.rc3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: 'Adds a :typesafe provider to RubyLLM 2 that evaluates text or structured
+  state against TypeSafe''s typed Choice, Noul, and Score questions through Chat#with_schema.
+  Structured output only: answers are calibrated probabilities, not generated text.'
+email:
+- kieranklaassen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ruby_llm-typesafe.rb
+- lib/ruby_llm/protocols/system_one.rb
+- lib/ruby_llm/protocols/system_one/chat.rb
+- lib/ruby_llm/protocols/system_one/models.rb
+- lib/ruby_llm/providers/typesafe.rb
+- lib/ruby_llm/providers/typesafe/schema.rb
+- lib/ruby_llm/providers/typesafe/schema/answers.rb
+- models.json
+homepage: https://github.com/kieranklaassen/ruby_llm-typesafe
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kieranklaassen/ruby_llm-typesafe
+  source_code_uri: https://github.com/kieranklaassen/ruby_llm-typesafe
+  changelog_uri: https://github.com/kieranklaassen/ruby_llm-typesafe/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/kieranklaassen/ruby_llm-typesafe#readme
+  bug_tracker_uri: https://github.com/kieranklaassen/ruby_llm-typesafe/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: RubyLLM provider for TypeSafe System One structured judgments.
+test_files: []