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 +7 -0
- data/CHANGELOG.md +22 -0
- data/CODE_OF_CONDUCT.md +60 -0
- data/LICENSE.txt +21 -0
- data/README.md +317 -0
- data/exe/is_even_ai +7 -0
- data/lib/is_even_ai/cache.rb +46 -0
- data/lib/is_even_ai/cli.rb +146 -0
- data/lib/is_even_ai/configuration.rb +164 -0
- data/lib/is_even_ai/errors.rb +44 -0
- data/lib/is_even_ai/http_client.rb +139 -0
- data/lib/is_even_ai/providers/anthropic.rb +56 -0
- data/lib/is_even_ai/providers/base.rb +150 -0
- data/lib/is_even_ai/providers/gemini.rb +59 -0
- data/lib/is_even_ai/providers/jev.rb +179 -0
- data/lib/is_even_ai/providers/openai.rb +54 -0
- data/lib/is_even_ai/providers/openai_compatible.rb +65 -0
- data/lib/is_even_ai/providers/registry.rb +35 -0
- data/lib/is_even_ai/refinements.rb +31 -0
- data/lib/is_even_ai/result.rb +35 -0
- data/lib/is_even_ai/version.rb +5 -0
- data/lib/is_even_ai.rb +151 -0
- metadata +75 -0
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.
|
data/CODE_OF_CONDUCT.md
ADDED
|
@@ -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
|
+
[](https://badge.fury.io/rb/is_even_ai)
|
|
6
|
+
[](https://github.com/chayuto/is_even_ai/actions/workflows/ci.yml)
|
|
7
|
+
[](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,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
|