thinkthen 0.1.2-aarch64-linux → 0.2.0-aarch64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. checksums.yaml +4 -4
  2. data/API.md +40 -0
  3. data/LICENSE +21 -0
  4. data/README.md +562 -0
  5. data/THIRD-PARTY-NOTICES/anstream-1.0.0/LICENSE-APACHE +202 -0
  6. data/THIRD-PARTY-NOTICES/anstream-1.0.0/LICENSE-MIT +19 -0
  7. data/THIRD-PARTY-NOTICES/anstyle-1.0.14/LICENSE-APACHE +202 -0
  8. data/THIRD-PARTY-NOTICES/anstyle-1.0.14/LICENSE-MIT +19 -0
  9. data/THIRD-PARTY-NOTICES/anstyle-parse-1.0.0/LICENSE-APACHE +202 -0
  10. data/THIRD-PARTY-NOTICES/anstyle-parse-1.0.0/LICENSE-MIT +19 -0
  11. data/THIRD-PARTY-NOTICES/anstyle-query-1.1.5/LICENSE-APACHE +202 -0
  12. data/THIRD-PARTY-NOTICES/anstyle-query-1.1.5/LICENSE-MIT +19 -0
  13. data/THIRD-PARTY-NOTICES/base64-0.23.1/LICENSE-APACHE +201 -0
  14. data/THIRD-PARTY-NOTICES/base64-0.23.1/LICENSE-MIT +21 -0
  15. data/THIRD-PARTY-NOTICES/bitflags-2.13.2/LICENSE-APACHE +201 -0
  16. data/THIRD-PARTY-NOTICES/bitflags-2.13.2/LICENSE-MIT +25 -0
  17. data/THIRD-PARTY-NOTICES/block-buffer-0.10.4/LICENSE-APACHE +201 -0
  18. data/THIRD-PARTY-NOTICES/block-buffer-0.10.4/LICENSE-MIT +25 -0
  19. data/THIRD-PARTY-NOTICES/bytes-1.12.1/LICENSE +25 -0
  20. data/THIRD-PARTY-NOTICES/cfg-if-1.0.5/LICENSE-APACHE +201 -0
  21. data/THIRD-PARTY-NOTICES/cfg-if-1.0.5/LICENSE-MIT +25 -0
  22. data/THIRD-PARTY-NOTICES/clap-4.6.7/LICENSE-APACHE +202 -0
  23. data/THIRD-PARTY-NOTICES/clap-4.6.7/LICENSE-MIT +19 -0
  24. data/THIRD-PARTY-NOTICES/clap_builder-4.6.7/LICENSE-APACHE +202 -0
  25. data/THIRD-PARTY-NOTICES/clap_builder-4.6.7/LICENSE-MIT +19 -0
  26. data/THIRD-PARTY-NOTICES/clap_complete-4.6.11/LICENSE-APACHE +202 -0
  27. data/THIRD-PARTY-NOTICES/clap_complete-4.6.11/LICENSE-MIT +19 -0
  28. data/THIRD-PARTY-NOTICES/clap_lex-1.1.1/LICENSE-APACHE +202 -0
  29. data/THIRD-PARTY-NOTICES/clap_lex-1.1.1/LICENSE-MIT +19 -0
  30. data/THIRD-PARTY-NOTICES/clap_mangen-0.2.33/LICENSE-APACHE +202 -0
  31. data/THIRD-PARTY-NOTICES/clap_mangen-0.2.33/LICENSE-MIT +19 -0
  32. data/THIRD-PARTY-NOTICES/colorchoice-1.0.5/LICENSE-APACHE +202 -0
  33. data/THIRD-PARTY-NOTICES/colorchoice-1.0.5/LICENSE-MIT +19 -0
  34. data/THIRD-PARTY-NOTICES/command-group-5.0.1/COPYRIGHT +29 -0
  35. data/THIRD-PARTY-NOTICES/command-group-5.0.1/LICENSE-APACHE +176 -0
  36. data/THIRD-PARTY-NOTICES/command-group-5.0.1/LICENSE-MIT +23 -0
  37. data/THIRD-PARTY-NOTICES/cpufeatures-0.2.17/LICENSE-APACHE +201 -0
  38. data/THIRD-PARTY-NOTICES/cpufeatures-0.2.17/LICENSE-MIT +25 -0
  39. data/THIRD-PARTY-NOTICES/crc32fast-1.5.3/LICENSE-APACHE +202 -0
  40. data/THIRD-PARTY-NOTICES/crc32fast-1.5.3/LICENSE-MIT +21 -0
  41. data/THIRD-PARTY-NOTICES/crypto-common-0.1.7/LICENSE-APACHE +201 -0
  42. data/THIRD-PARTY-NOTICES/crypto-common-0.1.7/LICENSE-MIT +25 -0
  43. data/THIRD-PARTY-NOTICES/ctrlc-3.5.2/LICENSE-APACHE +201 -0
  44. data/THIRD-PARTY-NOTICES/ctrlc-3.5.2/LICENSE-MIT +23 -0
  45. data/THIRD-PARTY-NOTICES/digest-0.10.7/LICENSE-APACHE +201 -0
  46. data/THIRD-PARTY-NOTICES/digest-0.10.7/LICENSE-MIT +25 -0
  47. data/THIRD-PARTY-NOTICES/dyn-clone-1.0.20/LICENSE-APACHE +176 -0
  48. data/THIRD-PARTY-NOTICES/dyn-clone-1.0.20/LICENSE-MIT +23 -0
  49. data/THIRD-PARTY-NOTICES/equivalent-1.0.3/LICENSE-APACHE +201 -0
  50. data/THIRD-PARTY-NOTICES/equivalent-1.0.3/LICENSE-MIT +25 -0
  51. data/THIRD-PARTY-NOTICES/fastrand-2.5.0/LICENSE-APACHE +201 -0
  52. data/THIRD-PARTY-NOTICES/fastrand-2.5.0/LICENSE-MIT +23 -0
  53. data/THIRD-PARTY-NOTICES/flate2-1.1.10/LICENSE-APACHE +201 -0
  54. data/THIRD-PARTY-NOTICES/flate2-1.1.10/LICENSE-MIT +25 -0
  55. data/THIRD-PARTY-NOTICES/generic-array-0.14.7/LICENSE +21 -0
  56. data/THIRD-PARTY-NOTICES/getrandom-0.2.17/LICENSE-APACHE +201 -0
  57. data/THIRD-PARTY-NOTICES/getrandom-0.2.17/LICENSE-MIT +26 -0
  58. data/THIRD-PARTY-NOTICES/getrandom-0.3.4/LICENSE-APACHE +201 -0
  59. data/THIRD-PARTY-NOTICES/getrandom-0.3.4/LICENSE-MIT +26 -0
  60. data/THIRD-PARTY-NOTICES/getrandom-0.4.3/LICENSE-APACHE +201 -0
  61. data/THIRD-PARTY-NOTICES/getrandom-0.4.3/LICENSE-MIT +26 -0
  62. data/THIRD-PARTY-NOTICES/hashbrown-0.17.1/LICENSE-APACHE +201 -0
  63. data/THIRD-PARTY-NOTICES/hashbrown-0.17.1/LICENSE-MIT +25 -0
  64. data/THIRD-PARTY-NOTICES/http-1.5.0/LICENSE-APACHE +201 -0
  65. data/THIRD-PARTY-NOTICES/http-1.5.0/LICENSE-MIT +25 -0
  66. data/THIRD-PARTY-NOTICES/httparse-1.10.1/LICENSE-APACHE +201 -0
  67. data/THIRD-PARTY-NOTICES/httparse-1.10.1/LICENSE-MIT +20 -0
  68. data/THIRD-PARTY-NOTICES/httpdate-1.0.3/LICENSE-APACHE +201 -0
  69. data/THIRD-PARTY-NOTICES/httpdate-1.0.3/LICENSE-MIT +19 -0
  70. data/THIRD-PARTY-NOTICES/index.json +633 -0
  71. data/THIRD-PARTY-NOTICES/indexmap-2.14.2/LICENSE-APACHE +201 -0
  72. data/THIRD-PARTY-NOTICES/indexmap-2.14.2/LICENSE-MIT +25 -0
  73. data/THIRD-PARTY-NOTICES/is_terminal_polyfill-1.70.2/LICENSE-APACHE +202 -0
  74. data/THIRD-PARTY-NOTICES/is_terminal_polyfill-1.70.2/LICENSE-MIT +19 -0
  75. data/THIRD-PARTY-NOTICES/itoa-1.0.18/LICENSE-APACHE +176 -0
  76. data/THIRD-PARTY-NOTICES/itoa-1.0.18/LICENSE-MIT +23 -0
  77. data/THIRD-PARTY-NOTICES/libc-0.2.190/LICENSE-APACHE +176 -0
  78. data/THIRD-PARTY-NOTICES/libc-0.2.190/LICENSE-MIT +25 -0
  79. data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/COPYRIGHT +29 -0
  80. data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-APACHE +201 -0
  81. data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-Apache-2.0_WITH_LLVM-exception +220 -0
  82. data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-MIT +23 -0
  83. data/THIRD-PARTY-NOTICES/log-0.4.34/LICENSE-APACHE +201 -0
  84. data/THIRD-PARTY-NOTICES/log-0.4.34/LICENSE-MIT +25 -0
  85. data/THIRD-PARTY-NOTICES/memchr-2.8.3/COPYING +3 -0
  86. data/THIRD-PARTY-NOTICES/memchr-2.8.3/LICENSE-MIT +21 -0
  87. data/THIRD-PARTY-NOTICES/nix-0.27.1/LICENSE +21 -0
  88. data/THIRD-PARTY-NOTICES/nix-0.31.3/LICENSE +21 -0
  89. data/THIRD-PARTY-NOTICES/once_cell-1.21.4/LICENSE-APACHE +201 -0
  90. data/THIRD-PARTY-NOTICES/once_cell-1.21.4/LICENSE-MIT +23 -0
  91. data/THIRD-PARTY-NOTICES/openssl-probe-0.2.1/LICENSE-APACHE +201 -0
  92. data/THIRD-PARTY-NOTICES/openssl-probe-0.2.1/LICENSE-MIT +25 -0
  93. data/THIRD-PARTY-NOTICES/percent-encoding-2.3.2/LICENSE-APACHE +201 -0
  94. data/THIRD-PARTY-NOTICES/percent-encoding-2.3.2/LICENSE-MIT +25 -0
  95. data/THIRD-PARTY-NOTICES/quick-xml-0.41.0/LICENSE-MIT.md +23 -0
  96. data/THIRD-PARTY-NOTICES/ref-cast-1.0.27/LICENSE-APACHE +176 -0
  97. data/THIRD-PARTY-NOTICES/ref-cast-1.0.27/LICENSE-MIT +23 -0
  98. data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE +9 -0
  99. data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE-BoringSSL +272 -0
  100. data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE-other-bits +13 -0
  101. data/THIRD-PARTY-NOTICES/ring-0.17.14/src/polyfill/once_cell/LICENSE-APACHE +201 -0
  102. data/THIRD-PARTY-NOTICES/ring-0.17.14/src/polyfill/once_cell/LICENSE-MIT +23 -0
  103. data/THIRD-PARTY-NOTICES/ring-0.17.14/third_party/fiat/LICENSE +15 -0
  104. data/THIRD-PARTY-NOTICES/roff-1.1.1/LICENSE-APACHE +202 -0
  105. data/THIRD-PARTY-NOTICES/roff-1.1.1/LICENSE-MIT +19 -0
  106. data/THIRD-PARTY-NOTICES/rustix-1.1.5/COPYRIGHT +29 -0
  107. data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-APACHE +201 -0
  108. data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-Apache-2.0_WITH_LLVM-exception +220 -0
  109. data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-MIT +23 -0
  110. data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-APACHE +201 -0
  111. data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-ISC +15 -0
  112. data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-MIT +25 -0
  113. data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE +10 -0
  114. data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-APACHE +201 -0
  115. data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-ISC +15 -0
  116. data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-MIT +25 -0
  117. data/THIRD-PARTY-NOTICES/rustls-pki-types-1.15.1/LICENSE-APACHE +201 -0
  118. data/THIRD-PARTY-NOTICES/rustls-pki-types-1.15.1/LICENSE-MIT +25 -0
  119. data/THIRD-PARTY-NOTICES/rustls-platform-verifier-0.7.1/LICENSE-APACHE +201 -0
  120. data/THIRD-PARTY-NOTICES/rustls-platform-verifier-0.7.1/LICENSE-MIT +21 -0
  121. data/THIRD-PARTY-NOTICES/rustls-webpki-0.103.16/LICENSE +19 -0
  122. data/THIRD-PARTY-NOTICES/schemars-1.2.3/LICENSE +21 -0
  123. data/THIRD-PARTY-NOTICES/serde-1.0.229/LICENSE-APACHE +176 -0
  124. data/THIRD-PARTY-NOTICES/serde-1.0.229/LICENSE-MIT +23 -0
  125. data/THIRD-PARTY-NOTICES/serde_core-1.0.229/LICENSE-APACHE +176 -0
  126. data/THIRD-PARTY-NOTICES/serde_core-1.0.229/LICENSE-MIT +23 -0
  127. data/THIRD-PARTY-NOTICES/serde_json-1.0.151/LICENSE-APACHE +176 -0
  128. data/THIRD-PARTY-NOTICES/serde_json-1.0.151/LICENSE-MIT +23 -0
  129. data/THIRD-PARTY-NOTICES/sha2-0.10.9/LICENSE-APACHE +201 -0
  130. data/THIRD-PARTY-NOTICES/sha2-0.10.9/LICENSE-MIT +27 -0
  131. data/THIRD-PARTY-NOTICES/strsim-0.11.1/LICENSE +23 -0
  132. data/THIRD-PARTY-NOTICES/subtle-2.6.1/LICENSE +29 -0
  133. data/THIRD-PARTY-NOTICES/tempfile-3.23.0/LICENSE-APACHE +201 -0
  134. data/THIRD-PARTY-NOTICES/tempfile-3.23.0/LICENSE-MIT +25 -0
  135. data/THIRD-PARTY-NOTICES/thiserror-2.0.21/LICENSE-APACHE +176 -0
  136. data/THIRD-PARTY-NOTICES/thiserror-2.0.21/LICENSE-MIT +23 -0
  137. data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-APACHE.md +202 -0
  138. data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-MIT.md +5 -0
  139. data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-ZLIB.md +11 -0
  140. data/THIRD-PARTY-NOTICES/typed-path-0.13.0/LICENSE-APACHE +176 -0
  141. data/THIRD-PARTY-NOTICES/typed-path-0.13.0/LICENSE-MIT +23 -0
  142. data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE +1 -0
  143. data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE-APACHE +201 -0
  144. data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE-MIT +21 -0
  145. data/THIRD-PARTY-NOTICES/unicode-general-category-1.1.0/LICENSE +201 -0
  146. data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/COPYRIGHT +7 -0
  147. data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-APACHE +201 -0
  148. data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-MIT +25 -0
  149. data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-UNICODE +39 -0
  150. data/THIRD-PARTY-NOTICES/untrusted-0.9.0/LICENSE.txt +13 -0
  151. data/THIRD-PARTY-NOTICES/ureq-3.4.2/LICENSE-APACHE +201 -0
  152. data/THIRD-PARTY-NOTICES/ureq-3.4.2/LICENSE-MIT +21 -0
  153. data/THIRD-PARTY-NOTICES/ureq-proto-0.6.4/LICENSE-APACHE.txt +202 -0
  154. data/THIRD-PARTY-NOTICES/ureq-proto-0.6.4/LICENSE-MIT.txt +7 -0
  155. data/THIRD-PARTY-NOTICES/utf8-zero-0.8.1/LICENSE-APACHE +176 -0
  156. data/THIRD-PARTY-NOTICES/utf8-zero-0.8.1/LICENSE-MIT +23 -0
  157. data/THIRD-PARTY-NOTICES/utf8parse-0.2.2/LICENSE-APACHE +176 -0
  158. data/THIRD-PARTY-NOTICES/utf8parse-0.2.2/LICENSE-MIT +25 -0
  159. data/THIRD-PARTY-NOTICES/zeroize-1.9.0/LICENSE-APACHE +202 -0
  160. data/THIRD-PARTY-NOTICES/zeroize-1.9.0/LICENSE-MIT +25 -0
  161. data/THIRD-PARTY-NOTICES/zip-9.1.2/LICENSE +21 -0
  162. data/THIRD-PARTY-NOTICES/zlib-rs-0.6.8/LICENSE +19 -0
  163. data/THIRD-PARTY-NOTICES/zmij-1.0.23/LICENSE-MIT +23 -0
  164. data/lib/thinkthen/call_owner.rb +68 -0
  165. data/lib/thinkthen/client.rb +293 -0
  166. data/lib/thinkthen/configuration.rb +76 -0
  167. data/lib/thinkthen/contract.rb +89 -0
  168. data/lib/thinkthen/libthinkthen_ffi.so +0 -0
  169. data/lib/thinkthen/native.rb +350 -0
  170. data/lib/thinkthen/native_allocator.rb +35 -0
  171. data/lib/thinkthen/native_reader.rb +87 -0
  172. data/lib/thinkthen/questions.rb +184 -0
  173. data/lib/thinkthen/row.rb +173 -0
  174. data/lib/thinkthen/rows.rb +199 -0
  175. data/lib/thinkthen/values.rb +111 -0
  176. data/lib/thinkthen/version.rb +3 -1
  177. data/lib/thinkthen.rb +79 -699
  178. data/sig/error_codes.rbs +3 -0
  179. data/sig/internal.rbs +277 -0
  180. data/sig/thinkthen.rbs +440 -0
  181. metadata +207 -13
  182. data/lib/thinkthen/thinkthen.so +0 -0
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d0e9c4190dd2147056a678bc16a271ecfda832419d5ab78534d78d93fa0864b7
4
- data.tar.gz: 390a54f2d582b9266ff0ee3fe8118031ce4613e7c7fece3be71b6e4e855dbd25
3
+ metadata.gz: f9ef38cde623d046141083be276b5b22f480aea591d91190e3072549c5f24eb2
4
+ data.tar.gz: e34ff0c72b3935d62540ec75fe9b83534dde88837606cd78bd054b9f167f64ba
5
5
  SHA512:
6
- metadata.gz: 10f8415aacdd41ca096e01365edf5cd775ebe642ddeceff22a7dafda4f019139aa8cc46c8b2b3bca7b6d47c5b36088ef330860e9f43eb91d32e951ae151591d5
7
- data.tar.gz: e048548044c32fe9755952b6dd2793dafc41c5d38a51febd2e35b02343188da93341bdce0fee2a7b2fd6e6f2894fae2dcd744181fcf99035abcc35d161508512
6
+ metadata.gz: 8f378ae77f6f010de15df91604d7be81fc6b5aeaff4cf6f6630b258b8487590cfc32d0a27fec835e513a9762b4cbe3c605c17f82e35b017ad387df9817c17631
7
+ data.tar.gz: 5b975ce34dee5a44e30fb6c2db3fa7e9e39c5d97f4bdcb189528020a57ee82aa4c68b67cd978708d5d4b4cb4d6571a3bdead4974520afe8339c438dbd90d8803
data/API.md ADDED
@@ -0,0 +1,40 @@
1
+ # Ruby API
2
+
3
+ Use Ruby 3.3 or later and `require "thinkthen"`. `ThinkThen::Client.open { |client| ... }` closes the client at the end of the block. The functions on `ThinkThen` use a shared default client. `ThinkThen.configure` changes it before its first use; `ThinkThen.close` closes it.
4
+
5
+ Each result is immutable and has `function`, `status`, `probability`, `error`, `position`, `id`, `source`, `detail` and `item`. Status is `:answered`, `:unsure` or `:failed`. State checks, printing, inspection, hashing and serialization never read the answer. `.answer` raises `UnsureError` or `FailedError` when there is no answer. Only `DecideRow` has `.yes?`, with the same loud read. Ruby treats every result object as true in an `if`; always call `.yes?` or read `.answer`.
6
+
7
+ | Function | Answer | Required options |
8
+ | --- | --- | --- |
9
+ | `decide` | Boolean | None |
10
+ | `choose` | String or Symbol | `choices:` |
11
+ | `tag` | Frozen Array of Strings or Symbols | `labels:` |
12
+ | `score` | Float from 0 to 1 | `levels:` |
13
+ | `find` | `Span`, or answered `nil` | None |
14
+ | `recognize` | Frozen Array of `Name` | Record first, `kinds:` |
15
+ | `relate` | Frozen Array of `Relation` | Record first, `rules:` |
16
+ | `annotate` | Named full results under `.answer` | `AnnotationQuestions.new(refund: ..., topic: ...)` |
17
+
18
+ A scalar call raises `FailedError` at the call when its own parent row failed, including blank or missing input. A successful scalar result is answered or unsure. Scalar annotate still returns an answered parent with one, several or all entries failed; only an explicit `raise_if_failed` scans those entries.
19
+
20
+ Each has an `_each` form taking an Enumerable. An `_each` call remains many-record even with one input, retaining its failed row. With a block it yields results and closes the call, including after `break` or an exception. Without a block it returns a closable `Rows` Enumerator. Every result's `.item` is the caller's original object. A one-record call refuses an Array and names its `_each` alternative.
21
+
22
+ `filter(question, records)` yields only the caller's original kept records. It takes one threshold cut and refuses a band with guidance to `decide_each`. It yields kept records before raising one `FailedError` whose `rows` contains all failed results. There is no `filter_each`, `FilterRow`, `kept?` or failures option.
23
+
24
+ `rank(question, records, levels:, top:)` yields `RankRow` results in rank order. `.answer` is the rank, starting at 1. Failed results follow the ranked ones. Every `.item` is the original object, including invalid records. Keeping originals means retaining the inputs until ranking finishes, even with `top:`. There is no `rank_each` or second rank read.
25
+
26
+ Choices, labels and levels accept an Array of Symbols or an Array of Strings. A symbol domain returns symbols for choose and tag; strings return strings. The supplied Array's order defines a scale, lowest first. `descriptions:` is keyed by those words. Decide and filter take `yes_means:` and `no_means:`. `threshold:` is a Float; decide also accepts an inclusive Float Range.
27
+
28
+ `DecideQuestion`, `ChooseQuestion` and the other question classes save their options. `Toolbox.load_file(path)` loads canonical saved questions; `.choose(:topic)` and the other typed selectors reject a missing name or wrong function. `AnnotationQuestions` excludes filter, rank and annotate. `RelationRule.new(source:, target:, relation:, reads: nil, either: false)` uses named fields. A name has `kind`, `text`, `start`, `end`, `probability`. A relation has `source`, `target`, `relation`, `probability`, `either`.
29
+
30
+ Records are strings or JSON-like values, including Hashes with String or Symbol keys and caller classes converted through `to_h`. Conversion never calls `to_json`. `field:` selects a JSON Pointer; the reference also accepts a key path such as `[:text]`. Blank input, missing input and invalid records fail at the scalar call; many-record APIs retain them as failed results. IDs are strings, signed 64-bit integers or unsigned 64-bit integers. Invalid IDs are absent from failed results; the original `.item` remains available.
31
+
32
+ Results have value equality and hashing over their nine own fields, excluding `item` throughout nested forms. Comparing a result with a bare answer raises `TypeError` naming `.answer`; `eql?` returns false. `to_h` and `to_json` write the canonical wire row, omit `item` and preserve character offsets. Printing uses the command's words and folds CR, LF and tab inside string leaves to spaces; tabs separating labels or form entries remain.
33
+
34
+ `raise_if_failed` returns the same result unless it failed or an annotate entry failed. A failed outer form takes precedence; otherwise the first failed child in the engine's question-name order supplies the error. Unsure entries do not fail a form. Child results retain the parent's position, ID, source and original item.
35
+
36
+ `Client.open` accepts `backend:`, `model:`, `url:`, `api_key:`, `batch:`, `retry: RetryPolicy.new(...)` and the reference-only `max_requests:` allowance. Retry times use seconds. Every call also accepts `name:` and `cancel: Cancel.new`. Calls release Ruby's interpreter lock while waiting, and one client can serve several threads. Create a new client after `fork`. `client.usage` returns an immutable cumulative snapshot, including after close.
37
+
38
+ `NoAnswerError` is included by `UnsureError` and `FailedError`. `Error` covers engine and binding failures, including `UsageError` (also an `ArgumentError`), `SetupError`, `CancelledError`, `InternalError`, `UnknownCodeError` and `FailedError`; it excludes uncertainty. `UnsureError` carries its `row` and `probability`; `FailedError` carries `rows`, `code` and `http_status`. HTTP 401/403 always stop the call; an all-failed first batch with any HTTP 4xx also stops it. These remote call refusals raise `SetupError`, while other service failures fail at scalar calls and remain failed results in many-record APIs.
39
+
40
+ The gem ships [RBS signatures](sig/thinkthen.rbs). The ffi dependency does not support Ractors. The [Ruby guide](../../docs/surfaces/ruby.md) supplies runnable examples.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ian Maurer
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,562 @@
1
+ # Ruby functions that answer questions about text
2
+
3
+ ThinkThen is a classifier you call like a function. It reads text, answers one bounded question, and hands back a result you can branch on.
4
+
5
+ Use Ruby 3.3 or later. Run `gem install thinkthen`. The gem includes the engine. Set `THINKTHEN_API_KEY` in the environment first.
6
+
7
+ A one-record call raises `ThinkThen::FailedError` at the call when its record could not be judged. A successful call returns an answered or unsure result, with `failed?` false and its own `error` set to `nil`. Many-record calls keep failures in their results, so the shared result type has three states:
8
+
9
+ - **answered**: there is an answer, and `result.answer` is it.
10
+ - **not sure**: the model's number fell between the two bars you set, or no choice was likely enough.
11
+ - **failed**: the record could not be judged, or the service did not respond.
12
+
13
+ Three rules hold for every function on this page.
14
+
15
+ 1. **Reading the answer raises when there is none.** On a returned one-record result, `result.answer` can raise `ThinkThen::UnsureError`. On a many-record result, form entry or saved row, it can also raise `ThinkThen::FailedError`. A missing answer never reads as "no" or as an empty value.
16
+ 2. **Checking the state never raises.** `result.answered?`, `result.unsure?`, `result.failed?`, `result.probability` and `result.error` are always safe to call.
17
+ 3. **Printing never raises.** `puts result` and `"#{result}"` show the answer, `unsure`, or `failed:` with the reason. A yes prints as `true` and a no as `false`, the same words the `thinkthen` command prints.
18
+
19
+ ## decide
20
+
21
+ ### The simplest if
22
+
23
+ Ask a decide result `yes?` in an `if`.
24
+
25
+ ```ruby
26
+ require "thinkthen"
27
+
28
+ if ThinkThen.decide("Does the customer request a refund?", "Please refund my order.").yes?
29
+ puts "refund queue"
30
+ else
31
+ puts "inbox"
32
+ end
33
+ ```
34
+
35
+ If the message could not be judged, `ThinkThen.decide` raises `ThinkThen::FailedError` at the call. The `if` never receives a failed result and never falls through to `inbox` for a failure. With one bar, a returned decide result is yes or no; two bars can make its answer read raise `ThinkThen::UnsureError`.
36
+
37
+ Always write `yes?`. A result is an object, and Ruby counts every object except `nil` and `false` as true, so `if is_refund` takes the yes branch every time. Ruby gives a library no way to change that. Steep can report an unreachable-branch hint when it knows the type, but its default hint does not make the build fail.
38
+
39
+ ### Yes, no, or not sure
40
+
41
+ Set two bars and decide can also be not sure. `answered?` tells you whether there is a yes or no to read.
42
+
43
+ ```ruby
44
+ require "thinkthen"
45
+
46
+ is_refund = ThinkThen.decide(
47
+ "Does the customer request a refund?",
48
+ "Where is my parcel?",
49
+ threshold: 0.2..0.8,
50
+ )
51
+
52
+ if is_refund.answered?
53
+ puts is_refund.yes? ? "refund queue" : "inbox"
54
+ else
55
+ puts "a person reads it"
56
+ end
57
+ ```
58
+
59
+ You can also let the read raise and rescue `ThinkThen::UnsureError`. The call above has already succeeded, so this read cannot report a failed result.
60
+
61
+ ```ruby
62
+ begin
63
+ puts is_refund.yes? ? "refund queue" : "inbox"
64
+ rescue ThinkThen::UnsureError
65
+ puts "a person reads it"
66
+ end
67
+ ```
68
+
69
+ ### Did the call work
70
+
71
+ ```ruby
72
+ begin
73
+ is_refund = ThinkThen.decide("Does the customer request a refund?", "Please refund my order.")
74
+ puts is_refund
75
+ rescue ThinkThen::FailedError => failure
76
+ puts "could not judge it: #{failure}"
77
+ rescue ThinkThen::Error => failure
78
+ puts "the call did not complete: #{failure}"
79
+ end
80
+ ```
81
+
82
+ `ThinkThen::FailedError` reports failed judgements. `ThinkThen::Error` also covers usage, setup, cancellation and internal call errors, keeping their existing classifications. Printing a returned result does not read its answer.
83
+
84
+ Not sure counts as a successful call: ThinkThen did its job and returned an unsure result. Its answer read can raise `ThinkThen::UnsureError`, which neither rescue above handles.
85
+
86
+ ### Both bars and the probability
87
+
88
+ ```ruby
89
+ is_refund = ThinkThen.decide(
90
+ "Does the customer request a refund?",
91
+ "Where is my parcel?",
92
+ threshold: 0.2..0.8,
93
+ )
94
+ puts is_refund.probability
95
+ ```
96
+
97
+ - No `threshold:`: one bar at 0.5. The answer is always yes or no.
98
+ - `threshold: 0.7`: one bar. Yes at 0.7 or above, otherwise no.
99
+ - `threshold: 0.2..0.8`: two bars. No below 0.2, not sure from 0.2 up to 0.8, yes at 0.8 or above.
100
+
101
+ `probability` is the number ThinkThen compared with your bars: the model's probability of yes. A confident no has a low probability, such as `0.05`. It is present even for an unsure decide result. A failed many-record result has `nil` probability.
102
+
103
+ The number is the model's own. To choose bars for your data, run examples you have already labelled through `ThinkThen.decide_each`, save each `probability`, and compare with your labels.
104
+
105
+ ## choose with your own choices
106
+
107
+ Give your choices as a frozen list of symbols. The answer comes back as one of them.
108
+
109
+ ```ruby
110
+ require "thinkthen"
111
+
112
+ TOPIC = %i[billing shipping other].freeze
113
+
114
+ def team_for(topic)
115
+ case topic
116
+ in :billing then "billing team"
117
+ in :shipping then "warehouse"
118
+ in :other then "front desk"
119
+ end
120
+ end
121
+
122
+ topic = ThinkThen.choose(
123
+ "What is the message about?",
124
+ "I was charged twice for one invoice.",
125
+ choices: TOPIC,
126
+ )
127
+
128
+ if topic.unsure?
129
+ puts "a person reads it"
130
+ else
131
+ puts team_for(topic.answer)
132
+ end
133
+ ```
134
+
135
+ choose can be not sure even when you set no bar. Its bar is 0.5 on the best choice, and with three choices all three can fall below it. So check `topic.unsure?` before reading the answer. `threshold: 0.3` moves the bar.
136
+
137
+ The symbols (`:billing`, `:shipping`, `:other`) are the words the model reads, so make them plain words, not codes. The same symbols are what your code matches on.
138
+
139
+ Add a symbol to `TOPIC` and `team_for` raises `NoMatchingPatternError` the first time that topic arrives, so a new choice can't slip through as `nil`. Ruby does not check this before the program runs. A one-line test does: `TOPIC.each { |topic| team_for(topic) }`.
140
+
141
+ A choose result has no `yes?`, and is not equal to its answer. `topic.yes?` raises `NoMethodError`. `topic == :billing` raises `TypeError` and tells you to read `topic.answer`. Written the other way round, `:billing == topic` is quietly false, because Ruby asks the symbol and not the result. So always compare `topic.answer`.
142
+
143
+ Value equality and hashing cover only `function`, `status`, `answer`, `probability`, `error`, `position`, `id`, `source` and `detail`, using this language's names. They never include `item`, including on entries inside a form. Changing the caller's record cannot change a result's equality or hash.
144
+
145
+ A list of strings also works, `choices: ["billing", "shipping", "other"]`, and the answer is then a `String`. Use strings when a choice is a phrase with spaces.
146
+
147
+ ## Many records
148
+
149
+ Each one-record function has an `_each` form that takes many records and gives your block one result per record, in order. Each result carries your own record as `.item`.
150
+
151
+ ```ruby
152
+ require "thinkthen"
153
+
154
+ messages = [
155
+ "Please refund my order.",
156
+ "Where is my parcel?",
157
+ "I was charged twice for one invoice.",
158
+ ]
159
+
160
+ ThinkThen.decide_each(
161
+ "Does the customer request a refund?", messages, threshold: 0.2..0.8
162
+ ) do |is_refund|
163
+ if is_refund.unsure?
164
+ puts "a person reads it: #{is_refund.item}"
165
+ elsif is_refund.failed?
166
+ puts "try again later: #{is_refund.item}"
167
+ elsif is_refund.yes?
168
+ puts "refund queue: #{is_refund.item}"
169
+ else
170
+ puts "inbox: #{is_refund.item}"
171
+ end
172
+ end
173
+ ```
174
+
175
+ One failed record does not stop the call. Each result keeps its own state, with `position` counted from 1 and the record's `id` when it has one. An `_each` call remains many-record even with a one-item collection: its failed result is yielded. Collection length never chooses the scalar rule.
176
+
177
+ To stop on an encountered failed result, use its explicit check:
178
+
179
+ ```ruby
180
+ ThinkThen.decide_each(
181
+ "Does the customer request a refund?", messages, threshold: 0.2..0.8
182
+ ) do |is_refund|
183
+ puts is_refund.raise_if_failed
184
+ end
185
+ ```
186
+
187
+ `raise_if_failed` raises `ThinkThen::FailedError` for a failed result and otherwise returns that same result. Not sure does not raise here, and printing is safe. The method stays on the shared result class; it is redundant after a successful ordinary scalar call.
188
+
189
+ Pass the whole collection to one call so ThinkThen can send the records in batches. The call is closed when the block ends, even after an early `break`. Without a block, the call gives an Enumerator, and `.to_a` collects every result and closes it.
190
+
191
+ To save every result, write `result.to_json` as a line of JSON. It includes the state, so nothing is lost.
192
+
193
+ ## Many-result not sure or failed
194
+
195
+ Here each result comes from a many-record call, where all three states remain possible.
196
+
197
+ ```ruby
198
+ ThinkThen.decide_each(
199
+ "Does the customer request a refund?", messages, threshold: 0.2..0.8
200
+ ) do |is_refund|
201
+ if is_refund.unsure?
202
+ puts "a person reads it #{is_refund.probability}"
203
+ elsif is_refund.failed?
204
+ puts "try again later #{is_refund.error.code}"
205
+ elsif is_refund.yes?
206
+ puts "refund queue"
207
+ else
208
+ puts "inbox"
209
+ end
210
+ end
211
+ ```
212
+
213
+ Yes and no are the two answers. Not sure and failed are the two ways of having none. To name every state, use `case` with `in` and no `else`, in a method that returns a value:
214
+
215
+ ```ruby
216
+ def where_it_goes(is_refund)
217
+ case is_refund.status
218
+ in :answered then is_refund.yes? ? "refund queue" : "inbox"
219
+ in :unsure then "a person reads it"
220
+ in :failed then "try again later"
221
+ end
222
+ end
223
+ ```
224
+
225
+ Ruby does not check this before the program runs. What `in` gives you is a loud miss: a state with no branch raises `NoMatchingPatternError`, where `case` with `when` would quietly give `nil`.
226
+
227
+ Call the routing method on each result:
228
+
229
+ ```ruby
230
+ ThinkThen.decide_each(
231
+ "Does the customer request a refund?", messages, threshold: 0.2..0.8
232
+ ) do |is_refund|
233
+ puts "#{where_it_goes(is_refund)}: #{is_refund.item}"
234
+ end
235
+ ```
236
+
237
+ `ThinkThen::NoAnswerError` groups `ThinkThen::UnsureError` and `ThinkThen::FailedError` for answer reads on many-record results, form entries and saved rows. Rescue it when either state means there is no answer to use; rescue them separately when their routes differ. Scalar and many-record calls share the same function-specific result class: only a scalar result's own failed state is excluded at runtime.
238
+
239
+ ## filter
240
+
241
+ filter means "give me the yeses". It hands back your own records, in order.
242
+
243
+ ```ruby
244
+ require "thinkthen"
245
+
246
+ messages = [
247
+ "Please refund my order.",
248
+ "Where is my parcel?",
249
+ "I was charged twice for one invoice.",
250
+ ]
251
+
252
+ ThinkThen.filter("Does the customer request a refund?", messages) do |refund_request|
253
+ puts "refund queue: #{refund_request}"
254
+ end
255
+ ```
256
+
257
+ filter takes one bar, so every record is a yes or a no and none is left out for being not sure. `threshold: 0.7` moves the bar. Two bars are refused with `ThinkThen::UsageError`: when you want not sure, use `ThinkThen.decide_each`, as in the section above.
258
+
259
+ If a record fails, you still get every kept record first. Then filter raises one `ThinkThen::FailedError`, and its `rows` holds every failed result with its `.item`.
260
+
261
+ ```ruby
262
+ begin
263
+ ThinkThen.filter("Does the customer request a refund?", messages) do |refund_request|
264
+ puts "refund queue: #{refund_request}"
265
+ end
266
+ rescue ThinkThen::FailedError => failure
267
+ failure.rows.each do |failed|
268
+ puts "try again later: #{failed.item} #{failed.error.code}"
269
+ end
270
+ end
271
+ ```
272
+
273
+ ## tag
274
+
275
+ Labels work as choices do. The answer is a frozen Array of the symbols that fit, and it can be empty.
276
+
277
+ ```ruby
278
+ require "thinkthen"
279
+
280
+ TOPIC = %i[billing shipping].freeze
281
+
282
+ topics = ThinkThen.tag(
283
+ "Which topics appear?",
284
+ "I was charged twice and my parcel is late again.",
285
+ labels: TOPIC,
286
+ )
287
+
288
+ puts "billing team" if topics.answer.include?(:billing)
289
+ topics.answer.each do |topic|
290
+ puts topic
291
+ end
292
+ ```
293
+
294
+ tag is never not sure. `threshold:` sets how likely a label must be to count.
295
+
296
+ ## score
297
+
298
+ Levels name a scale, lowest first. The answer is a number from 0 to 1 along it. The order of the supplied Array defines the scale.
299
+
300
+ ```ruby
301
+ require "thinkthen"
302
+
303
+ URGENCY = %i[routine urgent].freeze
304
+
305
+ urgency = ThinkThen.score(
306
+ "How urgent is the request?",
307
+ "Please refund my order.",
308
+ levels: URGENCY,
309
+ )
310
+
311
+ puts "answer today" if urgency.answer > 0.5
312
+ puts urgency.answer.round(2)
313
+ ```
314
+
315
+ The score is a position between your levels, not one of them, so it is a `Float` and there is nothing to match with `case`. To get exactly one level back, ask with `ThinkThen.choose`. score is never not sure.
316
+
317
+ ## rank
318
+
319
+ rank puts many records in order along your levels, highest first.
320
+
321
+ ```ruby
322
+ require "thinkthen"
323
+
324
+ messages = [
325
+ "Please refund my order.",
326
+ "Where is my parcel?",
327
+ "I was charged twice for one invoice.",
328
+ ]
329
+
330
+ ThinkThen.rank("How urgent is the request?", messages, levels: URGENCY) do |ranked|
331
+ puts "#{ranked.answer} #{ranked.item}"
332
+ end
333
+ ```
334
+
335
+ `ranked.answer` is the rank, starting at 1, and `ranked.item` is your record. rank reads the whole collection before it gives anything back. `top: 5` selects the five highest-ranked records after judging the collection. A failed record comes back after the ranked ones, with `failed?` true.
336
+
337
+ ## find
338
+
339
+ find points to the one line that answers.
340
+
341
+ ```ruby
342
+ require "thinkthen"
343
+
344
+ message = "Morgan works for Example Group.\nPlease refund my order."
345
+ action = ThinkThen.find("Which line states the requested action?", message)
346
+
347
+ if action.unsure?
348
+ puts "a person reads it"
349
+ elsif action.answer.nil?
350
+ puts "no line answers"
351
+ else
352
+ puts action.answer.text
353
+ end
354
+ ```
355
+
356
+ The answer is a `ThinkThen::Span` with `text`, `start` and `end`, or `nil` when no line answers. `message[span.start...span.end]` is the line. Like choose, find can be not sure with no bar set.
357
+
358
+ ## recognize
359
+
360
+ ```ruby
361
+ require "thinkthen"
362
+
363
+ names = ThinkThen.recognize(
364
+ "Morgan works for Example Group.",
365
+ kinds: ["person", "organization"],
366
+ )
367
+
368
+ names.answer.each do |name|
369
+ puts "#{name.kind} #{name.text}"
370
+ end
371
+ ```
372
+
373
+ Each name also has `start`, `end` and `probability`. The answer can be empty. recognize is never not sure.
374
+
375
+ ## relate
376
+
377
+ ```ruby
378
+ require "thinkthen"
379
+
380
+ message = "Morgan works for Example Group.\nPlease refund my order."
381
+ rules = [ThinkThen::RelationRule.new(source: "person", target: "organization", relation: "works_for")]
382
+
383
+ relations = ThinkThen.relate(message, rules: rules)
384
+
385
+ relations.answer.each do |relation|
386
+ puts "#{relation.source.text} #{relation.relation} #{relation.target.text}"
387
+ end
388
+ ```
389
+
390
+ Each relation has `source`, `target`, `relation`, `probability` and `either`. `relations.detail.names` holds every name found, including names in no relation.
391
+
392
+ ## annotate
393
+
394
+ annotate asks several questions of each record and gives back one form per record.
395
+
396
+ ```ruby
397
+ require "thinkthen"
398
+
399
+ messages = [
400
+ "Please refund my order.",
401
+ "Where is my parcel?",
402
+ "I was charged twice for one invoice.",
403
+ ]
404
+
405
+ questions = ThinkThen::AnnotationQuestions.new(
406
+ refund: ThinkThen::DecideQuestion.new("Does the customer request a refund?", threshold: 0.2..0.8),
407
+ topic: ThinkThen::ChooseQuestion.new("What is the message about?", choices: TOPIC),
408
+ urgency: ThinkThen::ScoreQuestion.new("How urgent is the request?", levels: URGENCY),
409
+ )
410
+
411
+ ThinkThen.annotate_each(questions, messages) do |form|
412
+ if form.failed?
413
+ puts "try again later: #{form.item}"
414
+ next
415
+ end
416
+ entries = form.answer
417
+ is_refund, topic, urgency = entries[:refund], entries[:topic], entries[:urgency]
418
+ if is_refund.failed? || topic.failed? || urgency.failed?
419
+ puts "try again later: #{form.item}"
420
+ elsif is_refund.unsure? || topic.unsure?
421
+ puts "a person reads it: #{form.item}"
422
+ elsif is_refund.answered? && topic.answered? && urgency.answered? && is_refund.yes?
423
+ puts "refund queue: #{topic.answer} #{urgency.answer.round(2)}"
424
+ end
425
+ end
426
+ ```
427
+
428
+ `form.answer` holds one entry per question, under the name you gave it. Each entry is a result of its own function, with its own state. `form.answer[:refund]` is a decide result, so it has `yes?`. One entry can be not sure or failed while the others answer. Check every entry used by a branch before reading its answer; an answered form alone does not mean its entries all answered. Here `TOPIC` is the three-choice list from the choose section, and `URGENCY` is the list from the score section.
429
+
430
+ For one record, `ThinkThen.annotate(questions, message)` raises `ThinkThen::FailedError` only when the parent form itself failed. An answered parent is returned even when one, several or all entries failed. The scalar boundary does not run the recursive form check to decide whether to return it.
431
+
432
+ ```ruby
433
+ form = ThinkThen.annotate(questions, "Please refund my order.")
434
+ form.raise_if_failed
435
+ ```
436
+
437
+ The optional second line explicitly raises for a failed entry as well as a failed parent. An unsure entry is not a failure; otherwise this check returns the same form unchanged. It also works on forms yielded by `annotate_each`. Checking only the parent never authorizes reading an unchecked entry's answer.
438
+
439
+ ## Say what each answer means
440
+
441
+ When a short question is not enough, say what the answers mean.
442
+
443
+ ```ruby
444
+ is_refund = ThinkThen.decide(
445
+ "Does the customer request a refund?",
446
+ "I was charged twice for one invoice.",
447
+ yes_means: "the customer wants money back, including for a duplicate charge",
448
+ no_means: "the customer wants anything else",
449
+ )
450
+
451
+ topic = ThinkThen.choose(
452
+ "What is the message about?",
453
+ "I was charged twice for one invoice.",
454
+ choices: TOPIC,
455
+ descriptions: {
456
+ billing: "charges, invoices and refunds",
457
+ shipping: "parcels and delivery",
458
+ },
459
+ )
460
+ ```
461
+
462
+ decide and filter take `yes_means:` and `no_means:`. choose, tag, score and rank take `descriptions:`, keyed by your choices, labels or levels.
463
+
464
+ ## Records and fields
465
+
466
+ A record is a String, or a Hash or other JSON-like value. `field: "/text"` picks one field of a Hash. Without it, ThinkThen judges the whole record. A record of your own class works when it has `to_h`, as a `Struct` or a `Data` does.
467
+
468
+ Give Hash records an `id`. Each result carries it back as `.id`.
469
+
470
+ A one-record call given an Array raises `ThinkThen::UsageError` and names the `_each` form. A blank record (an empty string, only spaces, or `{}`) raises `ThinkThen::FailedError` at the scalar call with code `record.empty`; a `nil` record does so with code `record.missing`. Neither sends that input to the service. In the `_each` forms, the same inputs remain failed results, even with one input.
471
+
472
+ ## Saved questions
473
+
474
+ A question object holds a question and its options, so many calls can share one definition. Pass it in place of the question text.
475
+
476
+ ```ruby
477
+ asks_refund = ThinkThen::DecideQuestion.new(
478
+ "Does the customer request a refund?",
479
+ threshold: 0.2..0.8,
480
+ field: "/text",
481
+ )
482
+ is_refund = ThinkThen.decide(asks_refund, {id: "a1", text: "Please refund my order."})
483
+ ```
484
+
485
+ There is one class per function, such as `ThinkThen::ChooseQuestion` and `ThinkThen::ScoreQuestion`. A `ThinkThen::Toolbox` keeps named questions in a JSON file:
486
+
487
+ ```ruby
488
+ toolbox = ThinkThen::Toolbox.load_file("toolbox.json")
489
+ topic = ThinkThen.choose(toolbox.choose(:topic), {id: "a1", text: "Where is my parcel?"})
490
+ ```
491
+
492
+ ## Settings
493
+
494
+ The functions on `ThinkThen` use a shared client that reads `THINKTHEN_API_KEY` and `THINKTHEN_BACKEND` from the environment. To choose settings yourself, open a client and call the same functions on it.
495
+
496
+ ```ruby
497
+ ThinkThen::Client.open(model: "...", batch: 16, retry: ThinkThen::RetryPolicy.new(max_retries: 5)) do |client|
498
+ is_refund = client.decide("Does the customer request a refund?", "Please refund my order.")
499
+ end
500
+ ```
501
+
502
+ The options are `backend:`, `url:`, `model:`, `api_key:`, `batch:` and `retry:`. Times in `ThinkThen::RetryPolicy` are in seconds. Keep the key in the environment, not in your code. The block closes the client when it ends. Open a new client after `fork`.
503
+
504
+ Ruby has no `async` and `await`, so there is no second client. A call waits without holding Ruby's interpreter lock, so other threads keep running, and one client is safe to share between threads.
505
+
506
+ ## Usage
507
+
508
+ ```ruby
509
+ ThinkThen::Client.open do |client|
510
+ client.decide("Does the customer request a refund?", "Please refund my order.")
511
+ usage = client.usage
512
+ puts "#{usage.attempts} #{usage.input_tokens.reported} #{usage.output_tokens.reported}"
513
+ end
514
+ ```
515
+
516
+ `client.usage` counts everything the client has sent so far: `attempts`, `responses`, retries, bytes sent, and tokens in and out as the service reported them.
517
+
518
+ ## Cancel
519
+
520
+ ```ruby
521
+ stop = ThinkThen::Cancel.new
522
+ is_refund = ThinkThen.decide("Does the customer request a refund?", "Please refund my order.", cancel: stop)
523
+ ```
524
+
525
+ Calling `stop.cancel` from another thread stops the call, which raises `ThinkThen::CancelledError`. Ctrl-C does the same.
526
+
527
+ ## Errors
528
+
529
+ | What happened | When it raises | What is raised |
530
+ | --- | --- | --- |
531
+ | A mistake in the call, such as a bad threshold or an Array given to a one-record call | At the call | `ThinkThen::UsageError`, which is also an `ArgumentError` |
532
+ | The client could not start, such as no API key | At the call | `ThinkThen::SetupError` |
533
+ | The call was cancelled | At the call | `ThinkThen::CancelledError` |
534
+ | A one-record judgement failed, including blank/nil input or a service failure on its row | At the scalar call | `ThinkThen::FailedError` |
535
+ | A many-record result or form entry failed | At its answer read, `yes?` or `raise_if_failed` | `ThinkThen::FailedError` |
536
+ | An annotate parent failed | At the scalar call; retained as a failed form by `annotate_each` | `ThinkThen::FailedError` at the scalar call or later failed-form read/check |
537
+ | An answered annotate parent contains failed entries | The call returns it; reading a failed entry or explicitly checking the form raises | `ThinkThen::FailedError` |
538
+ | Not sure | When you read the answer | `ThinkThen::UnsureError` |
539
+ | You print a result, store it, or ask about its state | Never | |
540
+
541
+ Two parents let you rescue by meaning:
542
+
543
+ - `rescue ThinkThen::NoAnswerError` catches `ThinkThen::UnsureError` and `ThinkThen::FailedError`: there was no answer to read.
544
+ - `rescue ThinkThen::Error` catches the library's call errors, including `ThinkThen::FailedError`. It does not catch `ThinkThen::UnsureError`, because not sure is a result and not an error. Ruby's own argument and file errors keep their usual classes.
545
+
546
+ HTTP 401 or 403 stops the call. The call also stops when every request in its first batch fails and at least one failure has an HTTP status from 400 through 499. These remote call refusals raise `ThinkThen::SetupError`. Other service failures become failed rows: a scalar call promotes its own failed row to `ThinkThen::FailedError`, while `_each` calls retain it as a result.
547
+
548
+ `ThinkThen::FailedError` retains the former `ThinkThen::RecordError` payload: `code`, `http_status` and `rows`, the failed results. Only the concrete host exception name changes; result classes, status symbols, wire codes such as `record.empty` and engine error families do not change. `ThinkThen::UnsureError` carries `probability` and `row`.
549
+
550
+ ## Upgrading from 0.1
551
+
552
+ The baseline is the [published 0.1.2 package/source](https://rubygems.org/gems/thinkthen-0.1.2-x86_64-linux.gem). Replace its call envelopes with the results shown above.
553
+
554
+ | 0.1.2 | Now |
555
+ | --- | --- |
556
+ | `ThinkThen.decide(q, text).value`; `nil` for not sure | Scalar failures raise `ThinkThen::FailedError` at the call; a returned result is answered or unsure, with `.unsure?` and the loud answer read |
557
+ | `ThinkThen::Engine`, `ThinkThen.question(...)` | Client and typed saved questions/toolbox |
558
+ | Per-call `.facts` | Client usage |
559
+
560
+ ## More examples
561
+
562
+ The [complete guide](https://github.com/botassembly/thinkthen/blob/v0.2.0/docs/surfaces/ruby.md) is the tested reference for this SDK. [Recorded examples](https://thinkthen.dev/sdks/ruby/) show real backend answers.