thinkthen 0.1.1-x86_64-linux → 0.2.0-x86_64-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.
- checksums.yaml +4 -4
- data/API.md +40 -0
- data/LICENSE +21 -0
- data/README.md +562 -0
- data/THIRD-PARTY-NOTICES/anstream-1.0.0/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/anstream-1.0.0/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/anstyle-1.0.14/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/anstyle-1.0.14/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/anstyle-parse-1.0.0/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/anstyle-parse-1.0.0/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/anstyle-query-1.1.5/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/anstyle-query-1.1.5/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/base64-0.23.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/base64-0.23.1/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/bitflags-2.13.2/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/bitflags-2.13.2/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/block-buffer-0.10.4/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/block-buffer-0.10.4/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/bytes-1.12.1/LICENSE +25 -0
- data/THIRD-PARTY-NOTICES/cfg-if-1.0.5/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/cfg-if-1.0.5/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/clap-4.6.7/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/clap-4.6.7/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/clap_builder-4.6.7/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/clap_builder-4.6.7/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/clap_complete-4.6.11/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/clap_complete-4.6.11/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/clap_lex-1.1.1/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/clap_lex-1.1.1/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/clap_mangen-0.2.33/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/clap_mangen-0.2.33/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/colorchoice-1.0.5/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/colorchoice-1.0.5/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/command-group-5.0.1/COPYRIGHT +29 -0
- data/THIRD-PARTY-NOTICES/command-group-5.0.1/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/command-group-5.0.1/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/cpufeatures-0.2.17/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/cpufeatures-0.2.17/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/crc32fast-1.5.3/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/crc32fast-1.5.3/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/crypto-common-0.1.7/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/crypto-common-0.1.7/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/ctrlc-3.5.2/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/ctrlc-3.5.2/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/digest-0.10.7/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/digest-0.10.7/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/dyn-clone-1.0.20/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/dyn-clone-1.0.20/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/equivalent-1.0.3/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/equivalent-1.0.3/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/fastrand-2.5.0/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/fastrand-2.5.0/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/flate2-1.1.10/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/flate2-1.1.10/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/generic-array-0.14.7/LICENSE +21 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.2.17/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.2.17/LICENSE-MIT +26 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.3.4/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.3.4/LICENSE-MIT +26 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.4.3/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/getrandom-0.4.3/LICENSE-MIT +26 -0
- data/THIRD-PARTY-NOTICES/hashbrown-0.17.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/hashbrown-0.17.1/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/http-1.5.0/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/http-1.5.0/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/httparse-1.10.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/httparse-1.10.1/LICENSE-MIT +20 -0
- data/THIRD-PARTY-NOTICES/httpdate-1.0.3/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/httpdate-1.0.3/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/index.json +633 -0
- data/THIRD-PARTY-NOTICES/indexmap-2.14.2/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/indexmap-2.14.2/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/is_terminal_polyfill-1.70.2/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/is_terminal_polyfill-1.70.2/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/itoa-1.0.18/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/itoa-1.0.18/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/libc-0.2.190/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/libc-0.2.190/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/COPYRIGHT +29 -0
- data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-Apache-2.0_WITH_LLVM-exception +220 -0
- data/THIRD-PARTY-NOTICES/linux-raw-sys-0.12.1/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/log-0.4.34/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/log-0.4.34/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/memchr-2.8.3/COPYING +3 -0
- data/THIRD-PARTY-NOTICES/memchr-2.8.3/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/nix-0.27.1/LICENSE +21 -0
- data/THIRD-PARTY-NOTICES/nix-0.31.3/LICENSE +21 -0
- data/THIRD-PARTY-NOTICES/once_cell-1.21.4/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/once_cell-1.21.4/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/openssl-probe-0.2.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/openssl-probe-0.2.1/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/percent-encoding-2.3.2/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/percent-encoding-2.3.2/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/quick-xml-0.41.0/LICENSE-MIT.md +23 -0
- data/THIRD-PARTY-NOTICES/ref-cast-1.0.27/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/ref-cast-1.0.27/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE +9 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE-BoringSSL +272 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/LICENSE-other-bits +13 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/src/polyfill/once_cell/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/src/polyfill/once_cell/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/ring-0.17.14/third_party/fiat/LICENSE +15 -0
- data/THIRD-PARTY-NOTICES/roff-1.1.1/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/roff-1.1.1/LICENSE-MIT +19 -0
- data/THIRD-PARTY-NOTICES/rustix-1.1.5/COPYRIGHT +29 -0
- data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-Apache-2.0_WITH_LLVM-exception +220 -0
- data/THIRD-PARTY-NOTICES/rustix-1.1.5/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-ISC +15 -0
- data/THIRD-PARTY-NOTICES/rustls-0.23.46/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE +10 -0
- data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-ISC +15 -0
- data/THIRD-PARTY-NOTICES/rustls-native-certs-0.8.5/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/rustls-pki-types-1.15.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/rustls-pki-types-1.15.1/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/rustls-platform-verifier-0.7.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/rustls-platform-verifier-0.7.1/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/rustls-webpki-0.103.16/LICENSE +19 -0
- data/THIRD-PARTY-NOTICES/schemars-1.2.3/LICENSE +21 -0
- data/THIRD-PARTY-NOTICES/serde-1.0.229/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/serde-1.0.229/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/serde_core-1.0.229/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/serde_core-1.0.229/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/serde_json-1.0.151/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/serde_json-1.0.151/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/sha2-0.10.9/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/sha2-0.10.9/LICENSE-MIT +27 -0
- data/THIRD-PARTY-NOTICES/strsim-0.11.1/LICENSE +23 -0
- data/THIRD-PARTY-NOTICES/subtle-2.6.1/LICENSE +29 -0
- data/THIRD-PARTY-NOTICES/tempfile-3.23.0/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/tempfile-3.23.0/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/thiserror-2.0.21/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/thiserror-2.0.21/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-APACHE.md +202 -0
- data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-MIT.md +5 -0
- data/THIRD-PARTY-NOTICES/tinyvec-1.13.3/LICENSE-ZLIB.md +11 -0
- data/THIRD-PARTY-NOTICES/typed-path-0.13.0/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/typed-path-0.13.0/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE +1 -0
- data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/typenum-1.20.1/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/unicode-general-category-1.1.0/LICENSE +201 -0
- data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/COPYRIGHT +7 -0
- data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/unicode-normalization-0.1.26/LICENSE-UNICODE +39 -0
- data/THIRD-PARTY-NOTICES/untrusted-0.9.0/LICENSE.txt +13 -0
- data/THIRD-PARTY-NOTICES/ureq-3.4.2/LICENSE-APACHE +201 -0
- data/THIRD-PARTY-NOTICES/ureq-3.4.2/LICENSE-MIT +21 -0
- data/THIRD-PARTY-NOTICES/ureq-proto-0.6.4/LICENSE-APACHE.txt +202 -0
- data/THIRD-PARTY-NOTICES/ureq-proto-0.6.4/LICENSE-MIT.txt +7 -0
- data/THIRD-PARTY-NOTICES/utf8-zero-0.8.1/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/utf8-zero-0.8.1/LICENSE-MIT +23 -0
- data/THIRD-PARTY-NOTICES/utf8parse-0.2.2/LICENSE-APACHE +176 -0
- data/THIRD-PARTY-NOTICES/utf8parse-0.2.2/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/zeroize-1.9.0/LICENSE-APACHE +202 -0
- data/THIRD-PARTY-NOTICES/zeroize-1.9.0/LICENSE-MIT +25 -0
- data/THIRD-PARTY-NOTICES/zip-9.1.2/LICENSE +21 -0
- data/THIRD-PARTY-NOTICES/zlib-rs-0.6.8/LICENSE +19 -0
- data/THIRD-PARTY-NOTICES/zmij-1.0.23/LICENSE-MIT +23 -0
- data/lib/thinkthen/call_owner.rb +68 -0
- data/lib/thinkthen/client.rb +293 -0
- data/lib/thinkthen/configuration.rb +76 -0
- data/lib/thinkthen/contract.rb +89 -0
- data/lib/thinkthen/{thinkthen.so → libthinkthen_ffi.so} +0 -0
- data/lib/thinkthen/native.rb +350 -0
- data/lib/thinkthen/native_allocator.rb +35 -0
- data/lib/thinkthen/native_reader.rb +87 -0
- data/lib/thinkthen/questions.rb +184 -0
- data/lib/thinkthen/row.rb +173 -0
- data/lib/thinkthen/rows.rb +199 -0
- data/lib/thinkthen/values.rb +111 -0
- data/lib/thinkthen/version.rb +3 -1
- data/lib/thinkthen.rb +79 -699
- data/sig/error_codes.rbs +3 -0
- data/sig/internal.rbs +277 -0
- data/sig/thinkthen.rbs +440 -0
- metadata +207 -13
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 2a915d870968cfa9a9a7b2b5965c04aaef12ed1f55287821e95773c711827ba9
|
|
4
|
+
data.tar.gz: f3b719642b372d39b00833a96c2416df3585670fb74248029f371f94f84674f6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: f23f5aa25c0250e20158d44f2b446908152eec1e87f1a08a24b87a2aff2423923a34526415afacda62d91d423a74afe8c54874ba584a3860331ea08054e59375
|
|
7
|
+
data.tar.gz: 3a75371362b3f59b92015076beaae31979b56d04f8eefc5499518b67c57d8a9d14b395338c60ece7ac37d38da2137e6004736b0d2ab132c9144afc46c031814c
|
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.
|