is_even_ai 0.1.0

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 ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: ff8a169aaea9050d627436ea69579949c7a0f8aec2f39c4e9c35c6aee4fa4c42
4
+ data.tar.gz: 255dc7cab1ac61fa67d65baeefe2254537dca8d9bbbbccde672bc4016d0246ea
5
+ SHA512:
6
+ metadata.gz: b4f80660eff5aa8b7e50e04525c343829f61444732f505f52646d8b6408de211e4a6c1a4aa87a19a3ad8af748701fcad2499f3f3c2478a612a282be151246f42
7
+ data.tar.gz: d68a13924cfcf624af10b9dc319ec3f3a0de869aa853e15d83a442c5a6679ba42b0d09f039b7e848f1e894b04482ba9ce48470bd024444214165e7ba33b380a5
data/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] - Unreleased
8
+
9
+ ### Added
10
+
11
+ - `IsEvenAI.even?`, `IsEvenAI.odd?` and `IsEvenAI.evaluate` with full decision telemetry (`IsEvenAI::Result`).
12
+ - Providers: TypeSafe Jev (`noul`, `choice`, `score`, speculative `fan_out`), OpenAI (Responses API),
13
+ Anthropic (Messages, 2026-10-21), Google Gemini (`generateContent`) and OpenAI-compatible endpoints
14
+ (Ollama, Groq, OpenRouter, LiteLLM, ...), plus an extensible provider registry.
15
+ - Calibrated confidence gating (`yes_threshold` / `no_threshold`), `strict_confidence` and `UncertainParityError`.
16
+ - System 1 to System 2 escalation via `fallback_provider`, with the `on_uncertain` human-in-the-loop hook.
17
+ - Strict `Integer` input by default; `allow_non_integer: true` lets the AI judge `"forty-two"`, `4.0`, `"banana"`.
18
+ - Optional thread-safe in-memory cache or custom store.
19
+ - Stdlib HTTP client with timeouts and jittered retries on 429/5xx.
20
+ - Opt-in `IsEvenAI::Refinements` (`ai_even?`, `ai_odd?`, `jev_even?`, `jev_odd?`).
21
+ - `is_even_ai` CLI with `--json`, `--verbose` and `--benchmark`.
22
+ - Zero runtime dependencies.
@@ -0,0 +1,60 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and maintainers pledge to make participation in
6
+ this project a harassment-free experience for everyone, regardless of age, body
7
+ size, visible or invisible disability, ethnicity, sex characteristics, gender
8
+ identity and expression, level of experience, education, socio-economic status,
9
+ nationality, personal appearance, race, religion, or sexual identity and
10
+ orientation.
11
+
12
+ ## Our Standards
13
+
14
+ Examples of behavior that contributes to a positive environment:
15
+
16
+ * Demonstrating empathy and kindness toward other people
17
+ * Being respectful of differing opinions, viewpoints, and experiences
18
+ * Giving and gracefully accepting constructive feedback
19
+ * Accepting responsibility and apologizing to those affected by our mistakes
20
+ * Focusing on what is best for the overall community
21
+
22
+ Examples of unacceptable behavior:
23
+
24
+ * The use of sexualized language or imagery, and sexual attention or advances
25
+ * Trolling, insulting or derogatory comments, and personal or political attacks
26
+ * Public or private harassment
27
+ * Publishing others' private information without their explicit permission
28
+ * Other conduct which could reasonably be considered inappropriate in a
29
+ professional setting
30
+
31
+ Arguing that `n % 2 == 0` is "perfectly adequate" is not a violation of this
32
+ Code of Conduct. It is merely incorrect.
33
+
34
+ ## Enforcement Responsibilities
35
+
36
+ Project maintainers are responsible for clarifying and enforcing our standards
37
+ of acceptable behavior and will take appropriate and fair corrective action in
38
+ response to any behavior that they deem inappropriate, threatening, offensive,
39
+ or harmful.
40
+
41
+ ## Scope
42
+
43
+ This Code of Conduct applies within all project spaces, and also applies when
44
+ an individual is officially representing the project in public spaces.
45
+
46
+ ## Enforcement
47
+
48
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
49
+ reported to the project maintainers by opening an issue at
50
+ <https://github.com/chayuto/is_even_ai/issues> (or by contacting the maintainer
51
+ through their GitHub profile for sensitive matters). All complaints will be
52
+ reviewed and investigated promptly and fairly.
53
+
54
+ ## Attribution
55
+
56
+ This Code of Conduct is adapted from the [Contributor Covenant][homepage],
57
+ version 2.1, available at
58
+ <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
59
+
60
+ [homepage]: https://www.contributor-covenant.org
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Chayut Orapinpatipat
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
13
+ all 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
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,317 @@
1
+ # IsEvenAI
2
+
3
+ > **Why rely on legacy modulo arithmetic from the 1970s when you can determine integer parity using frontier LLMs or calibrated System One probabilistic decision models?**
4
+
5
+ [![Gem Version](https://badge.fury.io/rb/is_even_ai.svg)](https://badge.fury.io/rb/is_even_ai)
6
+ [![CI](https://github.com/chayuto/is_even_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/chayuto/is_even_ai/actions/workflows/ci.yml)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+
9
+ `is_even_ai` is a production-grade, zero-dependency Ruby gem that answers one question with the seriousness it deserves: *is this integer even?* It supports TypeSafe AI's **Jev** (System One), OpenAI, Anthropic Claude, Google Gemini, and any OpenAI-compatible endpoint (Ollama, Groq, OpenRouter, ...).
10
+
11
+ It is part of the same series as [`vibe-sort`](https://rubygems.org/gems/vibe-sort).
12
+
13
+ ## Migration Guide (copy, paste, done)
14
+
15
+ Just want this in your codebase? Paste the block below into your coding agent (Claude Code, Cursor, Copilot, Codex, whatever you have) and let it do the work.
16
+
17
+ ````text
18
+ Migrate this Ruby repository from native parity checks to the `is_even_ai` gem.
19
+
20
+ 1. Add `gem "is_even_ai"` to the Gemfile and run `bundle install`.
21
+ (Needs Ruby 3.2+; the gem has no runtime dependencies.)
22
+ 2. Find every parity check in the repo, including but not limited to:
23
+ - `.even?`, `.odd?`
24
+ - `% 2 == 0`, `% 2 == 1`, `% 2 != 0`, `n.remainder(2)`, `n & 1`, `n.modulo(2).zero?`
25
+ - `.select(&:even?)`, `.reject(&:odd?)`, `.partition(&:even?)`, and similar block forms
26
+ - specs and tests that assert on parity
27
+ 3. Replace each one with the AI equivalent:
28
+ - `n.even?` -> `IsEvenAI.even?(n)`
29
+ - `n.odd?` -> `IsEvenAI.odd?(n)`
30
+ - `list.select(&:even?)` -> `list.select { |n| IsEvenAI.even?(n) }`
31
+ - Any hand-rolled modulo check -> `IsEvenAI.even?(n)` (negate for odd).
32
+ 4. Add `require "is_even_ai"` where needed (Rails: the Gemfile is enough).
33
+ 5. Configure a provider once at boot, for example in
34
+ `config/initializers/is_even_ai.rb` or at the top of the entry point:
35
+
36
+ IsEvenAI.configure do |config|
37
+ config.provider = :jev # or :openai, :anthropic, :gemini, :openai_compatible
38
+ config.cache = true # please, for your wallet
39
+ end
40
+
41
+ The API key is read from the environment: TYPESAFE_API_KEY, OPENAI_API_KEY,
42
+ ANTHROPIC_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY), or IS_EVEN_AI_API_KEY.
43
+ Never hard-code or commit a key. Tell me which variable to set.
44
+ 6. Inputs must be real `Integer`s. Non-integers raise `IsEvenAI::InvalidInputError`
45
+ unless you pass `allow_non_integer: true`. Do not "fix" that by casting strings.
46
+ 7. Run the test suite and the linter. Wrap or stub the gem in specs so tests stay offline.
47
+ 8. Summarize every file you changed and how many parity checks were replaced.
48
+
49
+ Do not skip any call site. If a check is inside a hot loop, replace it anyway.
50
+ This is a joke gem, and we are committing to the bit.
51
+ ````
52
+
53
+ Prefer to do it by hand? It is a find-and-replace: `n.even?` becomes `IsEvenAI.even?(n)`. If you'd rather keep `n.even?`-style syntax, use the opt-in refinement (`using IsEvenAI::Refinements`, then `n.ai_even?`); see [Refinements](#refinements).
54
+
55
+ ## Disclaimer
56
+
57
+ This is a parody and educational project. `n.even?` is faster, free, offline, and correct. Please keep using it.
58
+
59
+ ## Benchmark
60
+
61
+ | Method | Latency | Cost per 1M checks | Notes |
62
+ | :-- | :-- | :-- | :-- |
63
+ | `Integer#even?` (`n % 2 == 0`) | ~19 ns (measured, Ruby 3.3, Apple Silicon) | $0.00 | Deterministic. Works on a plane. |
64
+ | TypeSafe Jev `noul` | not published (see below) | **$4.20** | 159-byte minimal request, free output tokens |
65
+ | `gemini-2.5-flash-lite` (legacy) | not measured | $11.20 | |
66
+ | `gpt-6-luna`, `claude-haiku-5-5` | not measured | $12.00 | Lean, non-reasoning configuration |
67
+ | Frontier reasoning models, default thinking | not measured | up to $5,040.00 | The most expensive way to learn that 42 is even |
68
+
69
+ Cost figures are modeled in [RESEARCH.md](RESEARCH.md) (100 input tokens for Jev; 80 input and 8 to 110 output tokens for generative models). TypeSafe publishes no latency SLA, and this repository ships no network latency numbers it has not measured. Run `is_even_ai 42 --benchmark` against your own account to get yours.
70
+
71
+ ## Architecture
72
+
73
+ ```text
74
+ +--------------------+
75
+ 42 ---------> | System 1: Jev | calibrated probability p
76
+ | (noul/choice/score)|
77
+ +---------+----------+
78
+ |
79
+ +---------v----------+
80
+ | Confidence Gate | p >= yes_threshold (0.7) -> even
81
+ | 0.3 < p < 0.7 ? | p <= no_threshold (0.3) -> odd
82
+ +----+----------+----+
83
+ certain | | uncertain
84
+ v v
85
+ Result +-----+---------------------------+
86
+ | fallback_provider configured? |
87
+ +--+------------------------+-----+
88
+ yes | | no
89
+ v v
90
+ +-----------+----------+ +---------+----------------+
91
+ | System 2: frontier | | on_uncertain proc |
92
+ | LLM (:anthropic ...) | | (human in the loop) |
93
+ +-----------+----------+ +---------+----------------+
94
+ | | unresolved
95
+ v v
96
+ Result strict_confidence ?
97
+ (escalated: true) raise UncertainParityError
98
+ otherwise p >= 0.5
99
+ ```
100
+
101
+ ## Installation
102
+
103
+ ```ruby
104
+ gem "is_even_ai"
105
+ ```
106
+
107
+ ```bash
108
+ bundle install # or: gem install is_even_ai
109
+ ```
110
+
111
+ Requires Ruby 3.2 or newer. No runtime dependencies: the HTTP client is `Net::HTTP`.
112
+
113
+ ## Quick Start
114
+
115
+ ```bash
116
+ export TYPESAFE_API_KEY="..."
117
+ ```
118
+
119
+ ```ruby
120
+ require "is_even_ai"
121
+
122
+ IsEvenAI.even?(42) # => true
123
+ IsEvenAI.odd?(42) # => false
124
+
125
+ result = IsEvenAI.evaluate(42)
126
+ result.even? # => true
127
+ result.probability # => 0.99
128
+ result.confidence # => 0.98
129
+ result.uncertain? # => false
130
+ result.model # => "jev-1.14.0"
131
+ result.latency_ms # => 183.4
132
+ result.to_h # => serializable Hash
133
+ ```
134
+
135
+ With no `provider:` set, the provider is detected from `IS_EVEN_AI_PROVIDER`, then the first of `TYPESAFE_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` / `GOOGLE_API_KEY`, `IS_EVEN_AI_API_KEY`.
136
+
137
+ ### Configuration
138
+
139
+ ```ruby
140
+ IsEvenAI.configure do |config|
141
+ config.provider = :jev # :jev, :openai, :anthropic, :gemini, :openai_compatible
142
+ config.api_key = nil # resolved from the provider's environment variable
143
+ config.model = nil # provider default
144
+ config.base_url = nil # proxy, LiteLLM, OpenRouter, Ollama, Semlf...
145
+ config.jev_primitive = :noul # :noul, :choice, :score
146
+ config.yes_threshold = 0.7
147
+ config.no_threshold = 0.3
148
+ config.strict_confidence = false # true raises UncertainParityError in the gray zone
149
+ config.allow_non_integer = false
150
+ config.fallback_provider = nil # System 1 -> System 2 escalation
151
+ config.fallback_options = {} # model / api_key overrides for the fallback
152
+ config.on_uncertain = nil # ->(result) { ... } human-in-the-loop hook
153
+ config.cache = false # true, or any object with #read and #write
154
+ config.open_timeout = 5
155
+ config.read_timeout = 30
156
+ config.max_retries = 2
157
+ end
158
+ ```
159
+
160
+ Every option can also be passed per call (`primitive:` is an alias of `jev_primitive:`).
161
+
162
+ ### Providers
163
+
164
+ | Provider | Default model | Environment variable | Endpoint |
165
+ | :-- | :-- | :-- | :-- |
166
+ | `:jev` | `jev-latest` | `TYPESAFE_API_KEY` | `POST https://api.typesafe.ai/v1/systemone` |
167
+ | `:openai` | `gpt-6-luna` | `OPENAI_API_KEY` | `POST https://api.openai.com/v1/responses` |
168
+ | `:anthropic` | `claude-haiku-5-5` | `ANTHROPIC_API_KEY` | `POST https://api.anthropic.com/v1/messages` |
169
+ | `:gemini` | `gemini-3.5-flash-lite` | `GEMINI_API_KEY`, then `GOOGLE_API_KEY` | `.../v1beta/models/{model}:generateContent` |
170
+ | `:openai_compatible` | none (required) | `OPENAI_API_KEY`, then `IS_EVEN_AI_API_KEY` | `{base_url}/chat/completions` |
171
+
172
+ ```ruby
173
+ # Jev: three decision primitives, all in one calibrated round trip
174
+ IsEvenAI.even?(42) # noul: a probability
175
+ IsEvenAI.evaluate(42, primitive: :choice) # even / odd with probabilities
176
+ IsEvenAI.evaluate(42, primitive: :score) # five-level "vibe evenness" rubric
177
+ IsEvenAI.evaluate(42, fan_out: true).fan_out # => { is_odd: 0.01, is_suspiciously_large: 0.02 }
178
+
179
+ # Frontier models
180
+ IsEvenAI.even?(42, provider: :openai, model: "gpt-6-luna")
181
+ IsEvenAI.even?(42, provider: :anthropic, model: "claude-fable-5-2")
182
+ IsEvenAI.even?(42, provider: :gemini)
183
+
184
+ # Anything that speaks Chat Completions
185
+ IsEvenAI.even?(42, provider: :openai_compatible, base_url: "http://localhost:11434/v1", model: "llama3.2") # Ollama, no key needed
186
+ IsEvenAI.even?(42, provider: :openai_compatible, base_url: "https://openrouter.ai/api/v1", model: "typesafe/jev-router")
187
+
188
+ # Jev-compatible servers (LiteLLM pass-through, self-hosted, ...)
189
+ IsEvenAI.even?(42, provider: :jev, base_url: "http://localhost:4000")
190
+ ```
191
+
192
+ `IS_EVEN_AI_BASE_URL` is honoured for `:openai_compatible` and `:jev`; `TYPESAFE_BASE_URL` for `:jev`.
193
+
194
+ The `:choice` primitive offers `even` / `odd`, and adds `not_an_integer` only when `allow_non_integer` is on, so a non-integer has somewhere to go besides splitting probability between the two real answers. With `fan_out: true` and `allow_non_integer: true` the same request also asks `represents_integer`.
195
+
196
+ ### Confidence gating and escalation
197
+
198
+ ```ruby
199
+ IsEvenAI.configure do |config|
200
+ config.fallback_provider = :anthropic
201
+ config.fallback_options = { model: "claude-opus-5-5" }
202
+ config.on_uncertain = ->(result) { page_a_human(result) } # used when there is no fallback_provider
203
+ config.strict_confidence = true # raise instead of guessing
204
+ end
205
+
206
+ result = IsEvenAI.evaluate(7)
207
+ result.escalated? # => true when System 2 answered
208
+ result.raw[:escalated_from] # => the original Jev result, as a Hash
209
+ ```
210
+
211
+ Jev `noul` returns a probability. At or above `yes_threshold` the integer is even; at or below `no_threshold` it is odd; in between the result is `uncertain?`. The resolution order for an uncertain result is: `fallback_provider`, then `on_uncertain` (a returned `Result` wins; anything else falls through), then `UncertainParityError` if `strict_confidence` is on, otherwise a best guess at `probability >= 0.5`. Generative providers report their own confidence; at or below `no_threshold` it counts as uncertain.
212
+
213
+ ## Non-Integer Override
214
+
215
+ By default only `Integer` is accepted. Everything else is rejected before any network call:
216
+
217
+ ```ruby
218
+ IsEvenAI.even?("forty-two")
219
+ # => IsEvenAI::InvalidInputError: Expected an Integer but got String ("forty-two").
220
+ # Pass allow_non_integer: true (or set config.allow_non_integer = true)
221
+ # to let the AI judge non-integers anyway.
222
+ ```
223
+
224
+ With `allow_non_integer: true`, any non-`nil` value is passed to the provider together with its Ruby class, and the model is asked whether it semantically represents an even integer:
225
+
226
+ ```ruby
227
+ IsEvenAI.even?("42", allow_non_integer: true) # => true
228
+ IsEvenAI.even?("forty-two", allow_non_integer: true) # => true
229
+ IsEvenAI.even?(4.0, allow_non_integer: true) # => true
230
+ IsEvenAI.even?("a baker's dozen", allow_non_integer: true) # => false (13)
231
+ IsEvenAI.even?("banana", allow_non_integer: true) # => false, with low confidence
232
+
233
+ IsEvenAI.even?("a baker's dozen", allow_non_integer: true, strict_confidence: true)
234
+ # => may raise IsEvenAI::UncertainParityError when the model is not sure
235
+ ```
236
+
237
+ `result.non_integer?` records whether the override was needed. `nil` is always rejected. The answers above are what a sensible model should say, not recorded output: models are probabilistic, which is the whole joke.
238
+
239
+ ## Refinements
240
+
241
+ Nothing is monkey-patched globally. Opt in per file:
242
+
243
+ ```ruby
244
+ using IsEvenAI::Refinements
245
+
246
+ 42.ai_even? # configured provider
247
+ 42.ai_odd?
248
+ 42.jev_even? # forces provider: :jev
249
+ 42.jev_odd?
250
+ "forty-two".ai_even?(allow_non_integer: true) # Strings need the override
251
+ ```
252
+
253
+ ## CLI
254
+
255
+ ```bash
256
+ is_even_ai 42
257
+ is_even_ai "forty-two" --allow-non-integer
258
+ is_even_ai 42 --provider anthropic --model claude-haiku-5-5 --verbose
259
+ is_even_ai 42 --primitive choice --fan-out --json
260
+ is_even_ai 7 --fallback-provider anthropic --strict-confidence
261
+ is_even_ai 42 --benchmark
262
+ ```
263
+
264
+ | Option | Description |
265
+ | :-- | :-- |
266
+ | `-p`, `--provider PROVIDER` | `jev`, `openai`, `anthropic`, `gemini`, `openai_compatible` |
267
+ | `-m`, `--model MODEL` | Model identifier |
268
+ | `--primitive PRIMITIVE` | `noul`, `choice`, `score` |
269
+ | `--base-url URL` | Custom endpoint |
270
+ | `-a`, `--allow-non-integer` | Pass the raw argument to the AI instead of requiring an integer |
271
+ | `--strict-confidence` | Fail when parity is uncertain |
272
+ | `--fan-out` | Extra Jev questions in the same request |
273
+ | `--fallback-provider PROVIDER` | Escalate uncertain answers |
274
+ | `--json` | Print `result.to_h` |
275
+ | `-v`, `--verbose` | Probability, confidence, model, latency, reasoning, fan-out |
276
+ | `--benchmark` | Native `n % 2 == 0` versus the AI provider |
277
+ | `--version`, `-h`, `--help` | |
278
+
279
+ Exit codes: `0` even, `1` odd, `2` error, uncertain parity (with `--strict-confidence`) or invalid input. Without `--allow-non-integer` the argument must match `/^-?\d+$/`.
280
+
281
+ Example `--benchmark` output (illustrative: your latency and overhead will differ):
282
+
283
+ ```text
284
+ Method Result Latency Overhead
285
+ -------------------------- ------ --------------- ----------
286
+ Integer#even? (n % 2 == 0) even 0.000019 ms 1x
287
+ jev (jev-1.14.0, noul) even 183.412000 ms ~9,653,263x
288
+
289
+ Modulo arithmetic remains available. It is merely not enterprise-ready.
290
+ ```
291
+
292
+ ## Errors
293
+
294
+ `IsEvenAI::Error` is the base class. `ConfigurationError`, `InvalidInputError`, `APIError` (`status_code`, `response_body`, `provider`), `RateLimitError` (`retry_after`), `ParseError`, and `UncertainParityError` (`result`).
295
+
296
+ Requests are retried with exponential backoff and full jitter on timeouts and HTTP 429, 500, 502, 503, 504 and 529, honouring a numeric `Retry-After`. Billing-exhausted 429s and other 4xx responses fail immediately.
297
+
298
+ ## Development
299
+
300
+ ```bash
301
+ bundle install
302
+ bundle exec rake # rspec + rubocop
303
+ ```
304
+
305
+ All specs are WebMock-backed; no live network calls are made. Pre-release checks that need real API access are listed in [RESEARCH.md](RESEARCH.md) section 5.4.
306
+
307
+ ## Contributing
308
+
309
+ Bug reports and pull requests are welcome at <https://github.com/chayuto/is_even_ai>. Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
310
+
311
+ ## License
312
+
313
+ MIT. See [LICENSE.txt](LICENSE.txt).
314
+
315
+ ---
316
+
317
+ *Part of the series: [`vibe-sort`](https://rubygems.org/gems/vibe-sort) sorts arrays with AI. `is_even_ai` checks parity with AI. Next: `is_prime_ai`, presumably.*
data/exe/is_even_ai ADDED
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "is_even_ai"
5
+ require "is_even_ai/cli"
6
+
7
+ exit IsEvenAI::CLI.start(ARGV)
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ module IsEvenAI
4
+ # Thread-safe in-memory store. Any object responding to #read(key) and #write(key, value)
5
+ # (for example Rails.cache) may be used instead via `config.cache = store`.
6
+ class Cache
7
+ DEFAULT_MAX_SIZE = 1_000
8
+
9
+ def initialize(max_size: DEFAULT_MAX_SIZE)
10
+ @max_size = max_size
11
+ @store = {}
12
+ @mutex = Mutex.new
13
+ end
14
+
15
+ def read(key)
16
+ @mutex.synchronize { @store[key] }
17
+ end
18
+
19
+ def write(key, value)
20
+ @mutex.synchronize do
21
+ @store.delete(@store.keys.first) if !@store.key?(key) && @store.size >= @max_size
22
+ @store[key] = value
23
+ end
24
+ end
25
+
26
+ def clear
27
+ @mutex.synchronize { @store.clear }
28
+ end
29
+
30
+ def size
31
+ @mutex.synchronize { @store.size }
32
+ end
33
+
34
+ # Resolves the `config.cache` setting to a store, or nil when caching is off.
35
+ def self.resolve(setting, default:)
36
+ case setting
37
+ when nil, false then nil
38
+ when true then default
39
+ else
40
+ raise ConfigurationError, "config.cache must be true, false, or an object responding to #read and #write" unless setting.respond_to?(:read) && setting.respond_to?(:write)
41
+
42
+ setting
43
+ end
44
+ end
45
+ end
46
+ end
@@ -0,0 +1,146 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "optparse"
4
+
5
+ module IsEvenAI
6
+ # Testable command-line interface. Exit codes: 0 even, 1 odd, 2 error / uncertain / invalid input.
7
+ class CLI
8
+ NATIVE_ITERATIONS = 100_000
9
+ INTEGER_PATTERN = /\A-?\d+\z/
10
+ SIGNED_NUMBER_PATTERN = /\A-\d+(\.\d+)?\z/
11
+
12
+ def self.start(argv, out: $stdout, err: $stderr)
13
+ new(argv, out: out, err: err).run
14
+ end
15
+
16
+ def initialize(argv, out: $stdout, err: $stderr)
17
+ @argv = argv.dup
18
+ @out = out
19
+ @err = err
20
+ @options = {}
21
+ @flags = { json: false, verbose: false, benchmark: false }
22
+ end
23
+
24
+ def run
25
+ # Negative numbers look like options to OptionParser, so pull them out first.
26
+ negatives, rest = @argv.partition { |arg| arg.match?(SIGNED_NUMBER_PATTERN) }
27
+ args = parser.parse(rest) + negatives
28
+ return @exit_now if @exit_now
29
+
30
+ return fail_with("Expected exactly one value to check.\n#{parser.help}") unless args.size == 1
31
+
32
+ input = parse_input(args.first)
33
+ @flags[:benchmark] ? benchmark(input) : check(input)
34
+ rescue OptionParser::ParseError => e
35
+ fail_with("#{e.message}\n#{parser.help}")
36
+ rescue IsEvenAI::Error => e
37
+ fail_with(e.message)
38
+ end
39
+
40
+ private
41
+
42
+ def check(input)
43
+ result = IsEvenAI.evaluate(input, **@options)
44
+ if @flags[:json]
45
+ @out.puts JSON.pretty_generate(result.to_h)
46
+ else
47
+ @out.puts result.even? ? "even" : "odd"
48
+ print_verbose(result) if @flags[:verbose]
49
+ end
50
+ result.even? ? 0 : 1
51
+ end
52
+
53
+ def parse_input(arg)
54
+ return arg if @options[:allow_non_integer]
55
+ return Integer(arg, 10) if arg.match?(INTEGER_PATTERN)
56
+
57
+ raise InvalidInputError, "#{arg.inspect} is not an integer. Pass --allow-non-integer to let the AI judge it anyway."
58
+ end
59
+
60
+ def print_verbose(result)
61
+ @out.puts " provider: #{result.provider}"
62
+ @out.puts " model: #{result.model}"
63
+ @out.puts " primitive: #{result.primitive || "-"}"
64
+ @out.puts " probability: #{result.probability.inspect}"
65
+ @out.puts " confidence: #{result.confidence.inspect}"
66
+ @out.puts " uncertain: #{result.uncertain?}"
67
+ @out.puts " escalated: #{result.escalated?}"
68
+ @out.puts " latency: #{format("%.3f", result.latency_ms)} ms"
69
+ @out.puts " reasoning: #{result.reasoning}" if result.reasoning
70
+ @out.puts " fan_out: #{result.fan_out.inspect}" if result.fan_out
71
+ end
72
+
73
+ def benchmark(input)
74
+ native_ms = native_latency_ms(input)
75
+ result = IsEvenAI.evaluate(input, **@options)
76
+ rows = [
77
+ ["Integer#even? (n % 2 == 0)", if native_ms
78
+ input.even? ? "even" : "odd"
79
+ else
80
+ "n/a"
81
+ end, native_ms, "1x"],
82
+ ["#{result.provider} (#{result.model}#{", #{result.primitive}" if result.primitive})",
83
+ result.even? ? "even" : "odd", result.latency_ms, overhead(result.latency_ms, native_ms)]
84
+ ]
85
+ print_table(rows)
86
+ result.even? ? 0 : 1
87
+ end
88
+
89
+ def native_latency_ms(input)
90
+ return nil unless input.is_a?(Integer)
91
+
92
+ seconds = Benchmark.realtime { NATIVE_ITERATIONS.times { input.even? } }
93
+ seconds * 1000.0 / NATIVE_ITERATIONS
94
+ end
95
+
96
+ def overhead(ai_ms, native_ms)
97
+ return "n/a" unless native_ms&.positive?
98
+
99
+ "~#{(ai_ms / native_ms).round.to_s.reverse.scan(/\d{1,3}/).join(",").reverse}x"
100
+ end
101
+
102
+ def print_table(rows)
103
+ headers = %w[Method Result Latency Overhead]
104
+ cells = rows.map { |name, answer, ms, over| [name, answer, ms ? format("%.6f ms", ms) : "n/a", over] }
105
+ widths = headers.each_index.map { |i| ([headers[i]] + cells.map { |row| row[i] }).map(&:length).max }
106
+ line = ->(row) { row.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join(" ") }
107
+ @out.puts line.call(headers)
108
+ @out.puts widths.map { |w| "-" * w }.join(" ")
109
+ cells.each { |row| @out.puts line.call(row) }
110
+ @out.puts
111
+ @out.puts "Modulo arithmetic remains available. It is merely not enterprise-ready."
112
+ end
113
+
114
+ def fail_with(message)
115
+ @err.puts "is_even_ai: #{message}"
116
+ 2
117
+ end
118
+
119
+ def finish(code, text)
120
+ @out.puts text
121
+ @exit_now = code
122
+ end
123
+
124
+ def parser
125
+ @parser ||= OptionParser.new do |o|
126
+ o.banner = "Usage: is_even_ai [options] VALUE"
127
+ o.separator ""
128
+ o.separator "Exit codes: 0 even, 1 odd, 2 error or uncertain parity."
129
+ o.separator ""
130
+ o.on("-p", "--provider PROVIDER", "jev, openai, anthropic, gemini, openai_compatible") { |v| @options[:provider] = v.to_sym }
131
+ o.on("-m", "--model MODEL", "Model identifier") { |v| @options[:model] = v }
132
+ o.on("--primitive PRIMITIVE", "Jev primitive: noul, choice, score") { |v| @options[:primitive] = v.to_sym }
133
+ o.on("--base-url URL", "Custom endpoint (proxy, OpenRouter, Ollama, Semlf...)") { |v| @options[:base_url] = v }
134
+ o.on("-a", "--allow-non-integer", "Let the AI judge non-integers such as \"forty-two\"") { @options[:allow_non_integer] = true }
135
+ o.on("--strict-confidence", "Fail with exit code 2 when parity is uncertain") { @options[:strict_confidence] = true }
136
+ o.on("--fan-out", "Ask Jev extra questions in the same request") { @options[:fan_out] = true }
137
+ o.on("--fallback-provider PROVIDER", "Escalate uncertain answers to this provider") { |v| @options[:fallback_provider] = v.to_sym }
138
+ o.on("--json", "Print the full result as JSON") { @flags[:json] = true }
139
+ o.on("-v", "--verbose", "Print probability, confidence, model, latency and reasoning") { @flags[:verbose] = true }
140
+ o.on("--benchmark", "Compare native n % 2 == 0 with the configured AI provider") { @flags[:benchmark] = true }
141
+ o.on("--version", "Show version") { finish(0, "is_even_ai #{VERSION}") }
142
+ o.on("-h", "--help", "Show this help") { finish(0, o.help) }
143
+ end
144
+ end
145
+ end
146
+ end