typesafe-jev 0.7.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0627352ab282ec9a72607ebbc8d39bc73e2577231c567b4c66a7fc74e6140a0e
-  data.tar.gz: 218abce1d559c90b75e1b6bcf5872ff3f661d453dc6dd5c9bd15613141a89f1a
+  metadata.gz: 7545ebcb0bdc5d72f1038ae64b4305c3d5aeb6110b0b5e53b0c37cb88de77ee5
+  data.tar.gz: 50b7471d5f3c5c5dad8c1c4b14c0dbc3f2b062fe0ee7e4cd076d2ff44b4b46e0
 SHA512:
-  metadata.gz: ff6c07bf97933605fe0aa29c6d63fc6ed2390fa9cde14e9fc0016d17c373b45a85482f58ccf98b4df5279bb1c43e9174db8521faa4599c0ab2656eb94bb04b48
-  data.tar.gz: d6cd7d83fcff85966c653434fa64a5fd87a0a5fa23a7970643c5669ac298b367a4ead66d7eb44ebefdb32ab4f2a54963af1bdf5a9eeb2254952ecca9b966addd
+  metadata.gz: 3d8c3637a1d48b857019ac364b7aca9875cf0accad92023021a02f00488569b518c685afceccb8c117e98bf72e80f63eae3469d632b213c745e7b6b7fd88a4ca
+  data.tar.gz: f4f8167797e08f99b23a0faa879ffe10e7d01370487e4c18d4472ef52256835df82c63426c37bb8d847672502f71902624f375520108880447880aace31c00ba

data/CHANGELOG.md

@@ -1,34 +1,76 @@
 # Changelog
 
-## 0.7.0
+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).
+
+## [1.0.0] - 2026-09-20
+
+### Added
+
+- Full MIT `LICENSE` text, a complete README (quickstart, question/answer/error guide), a `CONTRIBUTING.md` guide and GitHub issue templates.
+- Gemspec metadata: `documentation_uri` (rubydoc.info) and `rubygems_mfa_required`; homepage now points at the GitHub repository.
+
+### Changed
+
+- **Stability**: the public API shipped in 0.7.0 is now declared stable and covered by Semantic Versioning; breaking changes will require a major version bump from here on.
+
+## [0.7.0] - 2026-09-20
+
+### Changed
 
 - **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now raises typed `Typesafe::Error` subclasses on any non-2xx response instead of raw `Net::HTTPClientException`/`Net::HTTPFatalError`: `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422, with `#errors`), `RateLimitError` (429, with `#retry_after`), `OverloadedError` (529) and `ServerError` (5xx), all under the `Typesafe::APIError` base with `status`, `body`, `headers`, `request_id` and `#retryable?`. `Typesafe::Error` is the root rescuable class.
 
-## 0.6.0
+## [0.6.0] - 2026-09-20
+
+### Changed
 
 - **Breaking**: `Typesafe::Client#evaluate` (and `Typesafe::Jev.evaluate`) now returns a typed `Typesafe::Response` instead of the raw parsed Hash; answers come back as `NoulAnswer`/`ChoiceAnswer`/`ScoreAnswer` objects accessible via `response[question_id]` (String or Symbol). Use `response.to_h` for the previous raw-Hash behavior.
 
-## 0.5.0
+## [0.5.0] - 2026-09-20
+
+### Added
+
+- Response classes mirroring the question classes: abstract `Typesafe::Answer` base with `Answer.from_h` dispatching on the `type` tag, plus `Typesafe::NoulAnswer` (`noul`), `Typesafe::ChoiceAnswer` (`choice`, `probabilities`, `confidence`) and `Typesafe::ScoreAnswer` (`score`, `legend`, `probabilities`, `confidence`). Frozen, immutable value objects that validate their inputs and serialize via `#to_h`/`#to_json`.
+- `Typesafe::Usage` (token counts) and `Typesafe::Response` (`model`, `answers`, `usage`), with `Response.from_json`/`from_h` to parse an API response body into typed Answer objects; `Response#[]` accepts String or Symbol question ids.
+
+## [0.4.1] - 2026-09-20
 
-- Add response classes mirroring the question classes: abstract `Typesafe::Answer` base with `Answer.from_h` dispatching on the `type` tag, plus `Typesafe::NoulAnswer` (`noul`), `Typesafe::ChoiceAnswer` (`choice`, `probabilities`, `confidence`) and `Typesafe::ScoreAnswer` (`score`, `legend`, `probabilities`, `confidence`). Frozen, immutable value objects that validate their inputs and serialize via `#to_h`/`#to_json`.
-- Add `Typesafe::Usage` (token counts) and `Typesafe::Response` (`model`, `answers`, `usage`), with `Response.from_json`/`from_h` to parse an API response body into typed Answer objects; `Response#[]` accepts String or Symbol question ids.
+### Fixed
 
-## 0.4.1
+- Gemspec metadata: point `source_code_uri`/`changelog_uri` and author/email at the `dtheofr` GitHub account.
 
-- Fix gemspec metadata: point `source_code_uri`/`changelog_uri` and author/email at the `dtheofr` GitHub account.
+## [0.4.0] - 2026-09-20
 
-## 0.4.0
+### Added
 
-- Add `Typesafe::Jev`, a `Typesafe::Client` subclass with the model pinned to `jev-latest`: `Jev.new(api_key: nil).evaluate(...)` plus a one-shot `Typesafe::Jev.evaluate(state:, questions:, api_key: nil)`.
+- `Typesafe::Jev`, a `Typesafe::Client` subclass with the model pinned to `jev-latest`: `Jev.new(api_key: nil).evaluate(...)` plus a one-shot `Typesafe::Jev.evaluate(state:, questions:, api_key: nil)`.
 
-## 0.3.0
+## [0.3.0] - 2026-09-20
 
-- Add `Typesafe::Client`: `initialize(api_key:, model:)` (key from argument or `TYPESAFE_API_KEY`, model defaults to `jev-latest`) and `evaluate(state:, questions:, model: nil)` posting to the System One endpoint. Returns the parsed JSON response; non-2xx responses raise the stdlib `Net::HTTP` error as-is.
+### Added
 
-## 0.2.0
+- `Typesafe::Client`: `initialize(api_key:, model:)` (key from argument or `TYPESAFE_API_KEY`, model defaults to `jev-latest`) and `evaluate(state:, questions:, model: nil)` posting to the System One endpoint. Returns the parsed JSON response; non-2xx responses raise the stdlib `Net::HTTP` error as-is.
 
-- Add question classes: `Typesafe::Noul`, `Typesafe::Choice`, `Typesafe::Score` with the abstract `Typesafe::Question` base. Frozen, immutable value objects that validate their inputs and serialize to the TypeSafe API shape via `#to_h`/`#to_json`.
+## [0.2.0] - 2026-09-20
 
-## 0.1.0
+### Added
+
+- Question classes: `Typesafe::Noul`, `Typesafe::Choice`, `Typesafe::Score` with the abstract `Typesafe::Question` base. Frozen, immutable value objects that validate their inputs and serialize to the TypeSafe API shape via `#to_h`/`#to_json`.
+
+## [0.1.0] - 2026-09-20
+
+### Added
 
 - Initial gem scaffold.
+
+[unreleased]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.7.0...v1.0.0
+[0.7.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.4.1...v0.5.0
+[0.4.1]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/dtheofr/typesafe-jev-ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/dtheofr/typesafe-jev-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dtheofr
+
+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,14 +1,147 @@
 # typesafe-jev
 
-Ruby client for [Jev](https://docs.typesafe.ai), TypeSafe's System One model — starting point, under construction.
+[![CI](https://github.com/dtheofr/typesafe-jev-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/dtheofr/typesafe-jev-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/typesafe-jev?logo=rubygems&color=brightgreen)](https://rubygems.org/gems/typesafe-jev)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.1-red?logo=ruby)](https://rubygems.org/gems/typesafe-jev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Ruby client for [Jev](https://docs.typesafe.ai), TypeSafe's System One model. Ask natural-language questions about your application state and get typed, probabilistic answers you can program against.
+
+**Zero runtime dependencies**: pure Ruby stdlib (`Net::HTTP`, `JSON`), so it works in plain Ruby and Rails alike.
+
+## Installation
+
+```sh
+gem install typesafe-jev
+```
+
+or in your `Gemfile`:
+
+```ruby
+gem "typesafe-jev"
+```
+
+## Quickstart
+
+```ruby
+require "typesafe"
+
+response = Typesafe::Jev.evaluate(
+  state: { ticket: { text: "My payouts failed twice this week." } },
+  questions: {
+    refund_requested: Typesafe::Noul.new("Does the customer request a refund?"),
+    category: Typesafe::Choice.new("Which category does this ticket belong to?", criteria: {
+      billing:   "Payment, invoices, refunds",
+      technical: "Bugs and outages",
+      sales:     "Pre-sales questions"
+    }),
+    severity: Typesafe::Score.new("How severe is this ticket?", criteria: [
+      "Low: routine request",
+      "Medium: degraded experience",
+      "High: blocked user",
+      "Critical: money lost or security issue"
+    ])
+  }
+)
+
+response[:refund_requested].noul  # => 0.95 (yes/no probability, 0..1)
+response[:category].choice        # => "billing"
+response[:category].probabilities # => { "billing" => 0.88, "technical" => 0.12, "sales" => 0.0 }
+response[:severity].score         # => "High: blocked user"
+response.usage.input_tokens       # => 296
+```
+
+`Typesafe::Jev.evaluate` is the one-shot facade with the model pinned to `jev-latest`. For another model, use `Typesafe::Client` directly.
+
+## Questions
+
+Questions are frozen, immutable value objects. The question **id is not in the object**; it is the Hash key in the `questions:` map, and answers come back under the same key.
+
+| Class | Answers with | Criteria |
+|---|---|---|
+| `Typesafe::Noul` | a yes/no probability (`noul`, 0..1) | optional `{ true: ..., false: ... }` |
+| `Typesafe::Choice` | one option + full probability distribution + `confidence` | non-empty `{ key: "description" }` |
+| `Typesafe::Score` | a level + `legend` + distribution + `confidence` | non-empty `["Level 1", "Level 2", ...]` |
+
+```ruby
+Typesafe::Noul.new("Does the customer request a refund?",
+  criteria: { true: "The customer explicitly asks for their money back",
+              false: "The customer does not mention refunds" })
+
+Typesafe::Choice.new("Which category does this ticket belong to?",
+  criteria: { billing: "Payment, invoices, refunds", technical: "Bugs and outages" })
+
+Typesafe::Score.new("How severe is this ticket?",
+  criteria: ["Low", "Medium", "High", "Critical"])
+```
+
+Invalid input raises `ArgumentError` at construction time, so bad questions fail fast, before any HTTP call.
+
+## Responses
+
+`Client#evaluate` returns a frozen `Typesafe::Response`:
+
+- `response[id]` (or `response.answers`): a typed `NoulAnswer`, `ChoiceAnswer` or `ScoreAnswer`; String and Symbol ids both work
+- `response.model`: the model that performed the evaluation
+- `response.usage`: `Typesafe::Usage` with `input_tokens` / `output_tokens`
+- `response.to_h` / `response.to_json`: the raw API shape
+
+Each answer type exposes its own accessors (`#noul`, `#choice`, `#probabilities`, `#confidence`, `#score`, `#legend`, …) and serializes via `#to_h`/`#to_json`.
+
+## Errors
+
+Any non-2xx HTTP response raises a typed error. All inherit from `Typesafe::APIError` (root: `Typesafe::Error`), which carries `#status`, `#body`, `#headers`, `#request_id` and `#retryable?`.
+
+| Error | Status | Extras |
+|---|---|---|
+| `Typesafe::BadRequestError` | 400 | |
+| `Typesafe::AuthenticationError` | 401 | |
+| `Typesafe::PermissionDeniedError` | 403 | |
+| `Typesafe::NotFoundError` | 404 | |
+| `Typesafe::UnprocessableEntityError` | 422 | `#errors` (validation details) |
+| `Typesafe::RateLimitError` | 429 | `#retry_after` |
+| `Typesafe::OverloadedError` | 529 | |
+| `Typesafe::ServerError` | 5xx | |
+
+```ruby
+begin
+  Typesafe::Jev.evaluate(state: state, questions: questions)
+rescue Typesafe::RateLimitError => e
+  sleep(e.retry_after || 1.0)
+  retry
+rescue Typesafe::OverloadedError
+  sleep(2**attempt)
+  retry
+rescue Typesafe::APIError => e
+  raise "typesafe request failed (#{e.status}, request #{e.request_id}): #{e.body}"
+end
+```
+
+## Configuration
+
+The API key is read from the `TYPESAFE_API_KEY` environment variable unless passed explicitly:
+
+```ruby
+jev = Typesafe::Jev.new                      # key from ENV
+jev = Typesafe::Jev.new(api_key: "sk-...")   # or explicit
+
+client = Typesafe::Client.new(api_key: "sk-...", model: "other-model")
+client.evaluate(state:, questions:, model: "one-off-model") # per-call override
+```
+
+## Documentation
+
+TypeSafe docs live at [docs.typesafe.ai](https://docs.typesafe.ai). The full API reference for this gem is on [rubydoc.info](https://rubydoc.info/gems/typesafe-jev).
 
 ## Development
 
 ```sh
 bundle install
-bundle exec rake test
+bundle exec rake spec   # or: bundle exec rspec
 ```
 
+The test suite runs against Ruby 3.1 and 3.4 in CI. See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions.
+
 ## License
 
-MIT
+[MIT](LICENSE)

data/lib/typesafe/answer.rb

@@ -5,7 +5,7 @@ module Typesafe
   # System One API: {NoulAnswer}, {ChoiceAnswer}, and {ScoreAnswer}.
   #
   # An answer is an immutable value object mirroring its question: it carries
-  # what the model returned for one question, but not the question id — that
+  # what the model returned for one question, but not the question id; that
   # is the Hash key under which the answer appears in a {Response}.
   #
   # Use {Answer.from_h} (or {Response.from_json}) to build typed answers from

data/lib/typesafe/errors.rb

@@ -16,10 +16,10 @@ module Typesafe
   # The `detail` field of an error body comes in three shapes, all of which
   # are rendered into the exception message:
   #
-  # * a plain String — `{"detail": "Unknown model: jev-99"}`
-  # * a Hash with error_type/message —
+  # * a plain String: `{"detail": "Unknown model: jev-99"}`
+  # * a Hash with error_type/message:
   #   `{"detail": {"error_type": "authentication_error", "message": "..."}}`
-  # * an Array of validation entries (FastAPI/pydantic style) —
+  # * an Array of validation entries (FastAPI/pydantic style):
   #   `{"detail": [{"type": "missing", "loc": ["body", "questions"], "msg": "Field required"}]}`
   class APIError < Error
     # @return [Integer] the HTTP status code.

data/lib/typesafe/response.rb

@@ -8,7 +8,7 @@ module Typesafe
   #   response = Typesafe::Response.from_json(json)
   #   response[:refund_requested] # => #<Typesafe::NoulAnswer @noul=0.95>
   #
-  # The answer objects do not carry their question id — it is the Hash key
+  # The answer objects do not carry their question id: it is the Hash key
   # under which each answer appears in {#answers}, mirroring how questions
   # are sent.
   class Response

data/lib/typesafe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Typesafe
-  VERSION = "0.7.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typesafe-jev
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 1.0.0
 platform: ruby
 authors:
 - dtheofr
@@ -76,13 +76,15 @@ files:
 - lib/typesafe/score_answer.rb
 - lib/typesafe/usage.rb
 - lib/typesafe/version.rb
-homepage: https://docs.typesafe.ai
+homepage: https://github.com/dtheofr/typesafe-jev-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://docs.typesafe.ai
+  homepage_uri: https://github.com/dtheofr/typesafe-jev-ruby
   source_code_uri: https://github.com/dtheofr/typesafe-jev-ruby
   changelog_uri: https://github.com/dtheofr/typesafe-jev-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/typesafe-jev
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib