fuzzy-jev

Ask Jev typed questions about a piece of text and get calibrated probabilities back, rather than prose. A Choice between named options, a Score on an ordered scale, or a Noul — the probability that something is true.

Jev is TypeSafe's model. This client reaches it through OpenRouter, which serves it on the decisions endpoint (https://openrouter.ai/api/alpha/decisions), so the key you need is an OpenRouter one; --url points the same questions at another endpoint.

Every answer is already a degree from 0 to 1, so the answers can be used directly as fuzzy truth values. A rules file combines them with AND, OR, NOT and hedges into decisions, or into a crisp amount through fuzzy outputs. --svg draws the whole rule base. docs/rules.md is the full guide to rules.toml: every table, operator and formula, the output formats, the errors, and an example worked by hand.

A command for your terminal, a Rust library that also compiles for wasm32-unknown-unknown, and an Agent Skill that teaches a coding agent when to ask Jev instead of judging by eye — jev add skill writes it into your project. The crate and the command are both called jev.

export OPENROUTER_API_KEY=sk-or-...

jev 'Help! My payouts have been failing for 3 days.' \
  --noul 'is_urgent=Does this message convey urgency?' \
  --choice 'department=Which team should handle this?|billing:Payments, invoicing, refunds|technical:Bugs, outages, integrations|sales:Pricing, upgrades, new accounts' \
  --score 'frustration=How frustrated is the customer?|Calm|Frustrated|Very angry'

is_urgent    0.95 yes
department   billing  confidence 0.84  (billing 0.89, technical 0.11, sales 0.00)
frustration  1.04 of 2, nearest "Frustrated"  confidence 0.94
427 tokens in, 73 out, $0.000018, typesafe/jev-1.13-20260917

Every question sees the same state and is answered on its own, so ask all of them in one call: an extra question costs a few tokens and no extra round trip.

Install

From crates.io. The package is fuzzy-jev, since jev on crates.io is another project; the command it installs is jev. Needs a Rust toolchain.

cargo install fuzzy-jev --locked

It lands in ~/.cargo/bin, which rustup puts on your PATH, so jev works in any folder. cargo install fuzzy-jev --locked --force updates it; cargo uninstall fuzzy-jev takes it off your PATH again.

A built binary. Each release carries a .tar.gz per platform — Linux and macOS, x86-64 and Arm — with a .sha256 beside it:

tar -xzf jev-0.2.0-aarch64-apple-darwin.tar.gz
./jev --help

v0.1.0, from before this repository was renamed, has no fuzzy rules or drawing.

With cargo, from this repository. For what is on main before it is released, with no clone: cargo fetches the source and builds it.

cargo install --git https://github.com/dsaad68/fuzzy-jev --locked

A few variants:

# a particular release
cargo install --git https://github.com/dsaad68/fuzzy-jev --tag v0.2.0 --locked

# a branch, to try something before it is merged
cargo install --git https://github.com/dsaad68/fuzzy-jev --branch some-branch --locked

# over an older copy, when cargo says one is already installed
cargo install --git https://github.com/dsaad68/fuzzy-jev --locked --force

--locked builds with the dependency versions in Cargo.lock, which is what CI tested; leave it out to let cargo pick newer ones. To run it from a clone instead:

git clone https://github.com/dsaad68/fuzzy-jev
cd fuzzy-jev
cargo install --path . --locked      # or: cargo run -- --help

Then set OPENROUTER_API_KEY from an OpenRouter key. --dry-run prints the request instead of sending it, and needs no key.

Asking

A question on the command line is ID=INSTRUCTIONS, then |-separated criteria:

Each flag can be repeated, and the answers print in the order the questions were written. Text with a | in it, or structured criteria, goes in a JSON file of ids to questions passed with --questions (-q); file questions come first, then the flags'.

A structured state

--state-json sends the state as JSON rather than as text, so nested fields, numbers and lists reach the model as what they are. A support ticket, ticket.json:

{
  "subject": "Charged twice for the October invoice",
  "plan": "enterprise",
  "opened_days_ago": 6,
  "prior_escalations": 2,
  "messages": [
    {"from": "customer", "text": "We were billed EUR 4,800 twice on 3 October. Please refund one."},
    {"from": "support", "text": "Thanks, looking into it."},
    {"from": "customer", "text": "Six days now and no answer. Our finance team is escalating."}
  ]
}

The three question types, in one questions.json. A noul's criteria are keyed true and false, which is what the endpoint calls them — the --noul flag spells the same thing id=INSTRUCTIONS|WHAT YES MEANS|WHAT NO MEANS:

{
  "team": {
    "type": "choice",
    "instructions": "Which team should own this ticket?",
    "criteria": {
      "billing": "charges, invoices, refunds",
      "support": "the product itself, bugs, outages",
      "success": "the relationship, renewals, escalations"
    }
  },
  "urgency": {
    "type": "score",
    "instructions": "How urgently does this need a human today?",
    "criteria": ["Can wait a week", "This week", "Today", "Now"]
  },
  "churn_risk": {
    "type": "noul",
    "instructions": "Is this account at risk of leaving?",
    "criteria": {"true": "Threats, repeated escalation, money at stake", "false": "Routine, patient, one-off"}
  }
}

cat ticket.json | jev --state-json -q questions.json

team        billing  confidence 0.99  (billing 0.99, success 0.01, support 0.00)
urgency     2.48 of 3, nearest "Today"  confidence 0.52
churn_risk  0.86 yes
571 tokens in, 72 out, $0.000024, typesafe/jev-1.13-20260917

The numbers move a little from call to call, so a threshold is worth setting with a margin rather than at the value one run happened to give.

With --json, each answer is named after its type — .noul, .choice (with .confidence and .probabilities), .score — which is what a script gates on:

cat ticket.json | jev --state-json -q questions.json --json > answers.json
jq -r 'if .answers.churn_risk.noul > 0.8 then "page the account team" else "queue normally" end' answers.json

Fuzzy rules

The complete reference is docs/rules.md. This section is the short tour.

A decision is often several answers combined: "a raincoat when it rains, unless it's hot". A rules file says that directly. It names the answers it needs as terms, combines them with fuzzy logic, and gives each outcome a score. The rules are your knowledge; Jev only supplies how much each condition holds.

The questions, examples/rules/weather.json:

{
  "temp":     {"type": "score", "instructions": "How warm does it feel outside?", "criteria": ["Cold", "Mild", "Hot"]},
  "humidity": {"type": "score", "instructions": "How humid is the air?", "criteria": ["Dry", "Normal", "Humid"]},
  "raining":  {"type": "noul",  "instructions": "Is it raining, or about to?"}
}

The rules, examples/rules/wear.toml:

[logic]                  # optional
and = "min"              # min | product | lukasiewicz
or  = "max"              # max | probsum | bounded

[decide]                 # optional
threshold = 0.5

[terms]
cold    = "temp.Cold"    # a Score level, by its exact text
mild    = "temp.Mild"
hot     = "temp.Hot"
humid   = "humidity.Humid"
raining = "raining"      # a Noul, by its id
# stormy = "sky.storm"   (a Choice option, from a "sky" choice: clear, cloudy, storm)

[[rule]]
if   = "cold"
then = "coat"

[[rule]]
if   = "mild AND NOT raining"
then = "light jacket"

[[rule]]
if   = "raining AND NOT hot"
then = "raincoat"

[[rule]]
if   = "raining"
then = "umbrella"

[[rule]]
if   = "hot AND humid"
then = "t-shirt"

[[rule]]
if     = "humid OR hot"
then   = "breathable fabric"
weight = 1.0             # optional, 0 to 1; the rule's score is multiplied by it

jev '16°C, the air feels sticky, and a light drizzle has started.' \
  -q examples/rules/weather.json -r examples/rules/wear.toml

coat               0.03
light jacket       0.05
raincoat           0.95  yes
umbrella           0.95  yes
t-shirt            0.02
breathable fabric  1.00  yes
threshold 0.50
369 tokens in, 47 out, $0.000015, typesafe/jev-1.13-20260917

• Terms are lowercase names, and every word in a rule is a term or an operator. A term points at a Noul by its id, at a Score level by the question id, a ., and the level's exact text, or at a Choice option by its name.
• Operators are uppercase: AND, OR, NOT, parentheses, and the hedges VERY (x²), SOMEWHAT (√x), EXTREMELY (x³) and INDEED (pushed toward 0 or 1). Hedges and NOT bind tightest, then AND, then OR.
• [logic] picks the AND and the OR for the whole file. min and max, the defaults, are safe when answers are related, as answers about one state usually are. product and probsum treat conditions as independent, so doubts compound and reasons reinforce.
• Rules with the same then are joined by the file's OR, and an item is a yes at or over the threshold.
• Checked before the call. Every term is resolved against the questions first, so a typo costs nothing, and --dry-run catches it too. The error names what does exist: [terms] hot: `temp` has no level `hot`; its levels are `temp.Cold`, `temp.Mild`, `temp.Hot` . An answer or a probability missing from the reply is an error, never a silent zero.
• --table adds the rules behind each score, and --json prints {"reply": …, "outcome": …}, so a script keeps every answer.

Outputs: a crisp amount

When the answer is an amount ("how much to water?") rather than a yes, a rule can conclude in an output: a crisp axis with named fuzzy sets. Each rule clips its set at its score, the clipped shapes are merged with the file's OR, and the value is the centre of the merged shape. This is Mamdani inference with centroid defuzzification.

examples/rules/irrigation.toml, with examples/rules/rain.json asking how much it rained:

[terms]
scarce  = "rainfall.Scarce"
regular = "rainfall.Regular"
large   = "rainfall.Large"

[output.irrigation]
range  = [0, 100]
drops  = [0, 0, 20, 40]      # a trapezoid: rises a→b, flat b→c, falls c→d
liter  = [30, 50, 70]        # a triangle: a, peak, c
gallon = [60, 80, 100, 100]  # a shoulder, held up to the end of the range

[[rule]]
if   = "scarce"
then = "irrigation IS gallon"

[[rule]]
if   = "regular"
then = "irrigation IS liter"

[[rule]]
if   = "large"
then = "irrigation IS drops"

jev 'A fairly normal week: two moderate showers, and the soil is damp but drying at the surface.' \
  -q examples/rules/rain.json -r examples/rules/irrigation.toml

irrigation  51.02  (drops 0.00, liter 0.98, gallon 0.02)

then = "OUTPUT IS SET" concludes in an output when the file declares that output; any other then is an item, and one file can have both. When no rule for an output scores above zero, its value is - (null in JSON) rather than a made-up number.

For everything together (a Choice, hedges, parentheses, a weight, probsum, a threshold, and items alongside an output), see the support-triage example, examples/rules/triage.toml, which docs/rules.md works through by hand.

Drawing the rules

--svg PATH draws the rules as an image, and --graph draws them in the terminal. Without a state (no argument, no -f, nothing on standard input) or with --dry-run, either one draws the structure alone and makes no call, which is a free way to check a rules file. With a state, every part carries its number.

jev '16°C, the air feels sticky, and a light drizzle has started.' \
  -q examples/rules/weather.json -r examples/rules/wear.toml --svg wear.svg

That is the drawing at the top of this page. The image is laid out the way a fuzzy rule base is usually drawn, with one row per rule:

• Premises: a column per question. A Score's levels are drawn as a fuzzy partition, with the term's own level in bold, shaded up to the degree Jev gave it. The red arrow is the expected level, the reading the curves turn into degrees. Choices and Nouls are drawn as bars.
• Rules: the if as a tree of its operators, each with what it came to.
• Conclusions: an output's sets, with the rule's own set clipped at its score, or an item's bar against the threshold.
• Final: each output's merged shape with an arrow at its centroid, and every item's score.

With an output, the conclusions are its sets clipped at each rule's score, and the final column is their merged shape with an arrow at its centroid. The irrigation rules:

jev 'A fairly normal week: two moderate showers, and the soil is damp but drying at the surface.' \
  -q examples/rules/rain.json -r examples/rules/irrigation.toml --svg irrigation.svg

In the terminal, --graph prints each rule as a tree, and each term with every level's probability (the term's own in brackets):

R3  raining AND NOT hot  ⇒  raincoat
    AND (min)  0.95
    ├─ raining  0.95  ← raining: no 0.05 · [yes 0.95]
    └─ NOT (1 − x)  0.98
       └─ hot  0.02  ← temp: Cold 0.04 · Mild 0.94 · [Hot 0.02]
    ⇒ raincoat  0.95  ███████████████████

An output is drawn as a plot of its merged shape, with ↑ at its centre:

  irrigation = 51.02
  1.0 ┤░░░░░░░░░░░░░               ▃▆▆▃               ░░░░░░░░░░░░░
      │░░░░░░░░░░░░░░░░         ▁▄██████▄▁         ░░░░░░░░░░░░░░░░
      │░░░░░░░░░░░░░░░░░░     ▂▅██████████▅▂     ░░░░░░░░░░░░░░░░░░
      │░░░░░░░░░░░░░░░░░░░░░▃▇██████████████▇▃░░░░░░░░░░░░░░░░░░░░░
      │░░░░░░░░░░░░░░░░░░▁▄████████████████████▄▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
  0.0 └──────────────────────────────┬─────────────────────────────
       0                             ↑ 51.02                    100
           drops                   liter                 gallon

The Agent Skill

A coding agent asked to "sort these tickets" or "which of these need a human?" will usually read them itself and write a paragraph of opinion. The skill teaches it to reach for jev instead: one call, a probability per item, and a number it can threshold on.

cd your-project
jev add skill

created .agents/skills/jev/SKILL.md
created .agents/skills/jev/references/patterns.md
The jev skill is in .agents/skills/jev. Agents that read .agents will find it.

The two files are compiled into the binary, so an installed jev carries its own skill and needs no source tree to hand it over. Nothing is overwritten without --force: a file that is already what would be written is left alone, so running it twice says unchanged rather than churning your diff.

What it teaches is when the tool fits — classifying, routing, triaging, rating, flagging, and anything where a confidence number beats an opinion — how to write the three question types, the patterns for putting many items through one call, and how to design fuzzy rules over the answers. Read skills/jev/SKILL.md and skills/jev/references/patterns.md before installing it, as you would any instruction you're adding to a project.

As a library

[dependencies]
jev = { package = "fuzzy-jev", version = "0.2", default-features = false }

let client = jev::Client::new(&std::env::var("OPENROUTER_API_KEY")?);
let reply = client
    .decide("I was charged twice this month", [("urgent", jev::Question::noul("Is this urgent?"))])
    .await?;

default-features = false leaves out the CLI's dependencies; the library then builds for wasm32-unknown-unknown too, where requests go through the host's fetch. The command feature adds question specs (jev::spec), the command's own printing (jev::print) and the rules engine (jev::rules) without the command, for another program that wants to offer jev the way the terminal does:

let rules = jev::rules::Rules::parse(&std::fs::read_to_string("wear.toml")?, questions.iter().map(|(id, q)| (id.as_str(), q)))?;
let outcome = rules.evaluate(&reply)?;       // items and outputs, with their scores
let svg = rules.graph_svg(Some(&reply))?;    // or graph_text, for a terminal

Development

cargo test                          # offline
cargo test --tests -- --ignored     # one real call; passes without calling when the key isn't set
cargo run --example triage -- "Could you tell me what the enterprise plan costs?"

CI runs cargo fmt --check, clippy for the host and for wasm32-unknown-unknown, and the tests. Pushing a tag such as v0.2.0 builds the four binaries and puts them on a Release; the same build can be started by hand from the Actions tab, which leaves them as artifacts.

Extracted from wasm-agent, where this began as crates/jev and where dx's shell offers the same command to an agent. This repository was called jev-cli until the fuzzy rules arrived; GitHub redirects the old URLs.

License

MIT — see LICENSE. The bundled Agent Skill says the same in its own frontmatter, so a project that runs jev add skill carries it with the files.