jev/lib.rs
1//! # jev
2//!
3//! A typed Rust SDK for the [Jev](https://openrouter.ai/docs/guides/community/jev)
4//! decision model — a *System One* model that answers typed questions about a state
5//! you send it, with calibrated probabilities, instead of prose.
6//!
7//! Three primitives, three questions:
8//!
9//! | Primitive | Question | Answer shape |
10//! |-----------|----------|--------------|
11//! | [`Noul`] | Does this condition hold? | `P(yes)` |
12//! | [`Choice<T>`] | Which one of these options? | an enum variant, plus confidence |
13//! | [`Score<T>`] | Where on an ordered scale? | a continuous position, plus the nearest level |
14//!
15//! ## The typed path
16//!
17//! One Rust type is one request and one answer struct. `///` doc comments on struct
18//! fields become `instructions`; `///` on enum variants become that option's
19//! criteria — there is exactly one copy of the prompt, and `cargo doc` shows a
20//! reviewer precisely what the model is asked.
21//!
22//! ```no_run
23//! # #[cfg(feature = "derive")]
24//! # async fn run() -> Result<(), jev::Error> {
25//! use jev::{Choice, ChoiceOptions, Client, Decision, Noul, Score, ScoreLevels};
26//!
27//! /// A support ticket triage decision.
28//! #[derive(Debug, Decision)]
29//! struct Triage {
30//! /// Is the customer reporting a software defect?
31//! #[jev(yes = "The customer describes broken or unexpected product behavior.",
32//! no = "The customer is asking a question or requesting a feature.")]
33//! is_bug: Noul,
34//!
35//! /// Which team should own this ticket?
36//! team: Choice<Team>,
37//!
38//! /// How urgent is this ticket?
39//! urgency: Score<Urgency>,
40//! }
41//!
42//! /// Owning team for a ticket.
43//! #[derive(Debug, Clone, Copy, PartialEq, Eq, ChoiceOptions)]
44//! enum Team {
45//! /// Checkout, billing, or payment processing issues.
46//! Payments,
47//! /// Rendering, layout, or browser compatibility issues.
48//! Frontend,
49//! /// Login, permissions, or profile issues.
50//! Account,
51//! }
52//!
53//! /// Ordered urgency scale, lowest first.
54//! #[derive(Debug, Clone, Copy, PartialEq, Eq, ScoreLevels)]
55//! enum Urgency {
56//! /// Can wait for the next release.
57//! NextRelease,
58//! /// Should be fixed this week.
59//! ThisWeek,
60//! /// Blocking revenue right now.
61//! BlockingRevenue,
62//! }
63//!
64//! let client = Client::from_env()?;
65//! let triage: Triage = client.decide("a customer ticket about a checkout error").await?;
66//!
67//! if triage.is_bug.is_yes(0.9) {
68//! if let Some(team) = triage.team.accept(0.7) {
69//! println!("route to {team:?}");
70//! }
71//! }
72//! let urgency: Urgency = triage.urgency.nearest();
73//! println!("{urgency:?}");
74//! # Ok(())
75//! # }
76//! ```
77//!
78//! ## Providers and API keys
79//!
80//! Construct a client with a key loaded by your application:
81//!
82//! ```no_run
83//! # fn run(openrouter_key: String, typesafe_key: String) -> Result<(), jev::Error> {
84//! let openrouter = jev::Client::openrouter(openrouter_key)?;
85//! let typesafe = jev::Client::typesafe(typesafe_key)?;
86//! # Ok(())
87//! # }
88//! ```
89//!
90//! [`Client::new`] defaults to `OpenRouter`. [`Client::for_provider`] accepts a
91//! runtime [`Provider`]; [`Config::provider`] supports YAML configuration.
92//! `TypeSafe` uses `/v1/systemone` with `jev-1.13.0` for the pinned default model,
93//! and `jev-latest` for [`Model::Latest`]. `OpenRouter` retains its existing paths
94//! and model IDs. Custom model IDs are never rewritten.
95//!
96//! [`Client::from_env`] reads `JEV_PROVIDER=openrouter|typesafe` when set and
97//! uses `JEV_API_KEY` or the selected provider's key variable. Without an explicit
98//! provider, key precedence is `JEV_API_KEY` (`OpenRouter`), `OPENROUTER_API_KEY`,
99//! then `TYPESAFE_API_KEY` (`TypeSafe`).
100//!
101//! ## Predefined cases from YAML/JSON
102//!
103//! For a fixed batch of `(state, questions)` pairs — a fixture file of support
104//! tickets, a regression suite of prior decisions — [`CaseSet`] loads them from one
105//! YAML/JSON document instead of assembling each [`Questions`] value in code:
106//!
107//! ```
108//! use jev::CaseSet;
109//!
110//! let json = r#"{"cases": [{
111//! "id": "ticket-001",
112//! "state": "Customer wants a refund for a duplicate charge.",
113//! "questions": {
114//! "refund": {"type": "noul", "instructions": "Is the customer asking for money back?"}
115//! }
116//! }]}"#;
117//! let cases = CaseSet::from_json_str(json).unwrap();
118//! # let _ = cases;
119//! ```
120//!
121//! ```no_run
122//! # #[cfg(feature = "yaml")]
123//! # async fn run() -> Result<(), jev::Error> {
124//! use jev::{CaseSet, Client};
125//!
126//! let cases = CaseSet::from_file("cases.yaml").await?;
127//! let client = Client::from_env()?;
128//! for case in &cases {
129//! let result = client.run_case(case).await?;
130//! println!("{}: {:?}", result.id, result.response.answers);
131//! }
132//! # Ok(())
133//! # }
134//! ```
135//!
136//! See [`CaseSet`]'s docs for the file format, and [`run_cases`] (behind the `batch`
137//! feature) for running the whole set with bounded concurrency.
138//!
139//! ## The dynamic path
140//!
141//! For question sets assembled at runtime from configuration, [`Questions::builder`]
142//! is the same wire logic the derive uses, minus the compile-time checks:
143//!
144//! ```
145//! use jev::Questions;
146//!
147//! let questions = Questions::builder()
148//! .noul("refund", "Is the customer asking for money back?")
149//! .choice("team", "Which team should own this?", [("payments", "Billing."), ("frontend", "UI.")])
150//! .build()
151//! .unwrap();
152//! ```
153//!
154//! ## Choosing thresholds
155//!
156//! `confidence` is a *calibration* signal, not accuracy: a `Choice<T>` with
157//! `confidence = 0.95` means the model is well-calibrated to be right about 95% of
158//! the time on inputs like this one, assuming the model's calibration holds for your
159//! distribution of states. The SDK never picks a threshold for you — see [`Noul::decide`],
160//! [`Choice::accept`], and [`crate::Thresholds`] — because the right threshold trades
161//! off automation rate against error tolerance, which is a product decision, not an
162//! SDK one. Escalate the ambiguous band (between `is_yes`/`is_no`, or below
163//! `accept`'s threshold) to a human reviewer rather than picking a default that
164//! silently mispredicts on the cases the model itself is uncertain about.
165//!
166//! ## Feature flags
167//!
168//! | Feature | Default | Effect |
169//! |---|---|---|
170//! | `derive` | yes | Re-exports the `Decision`/`ChoiceOptions`/`ScoreLevels` derives. |
171//! | `retry` | yes | Bounded retry loop honouring `Retry-After`. |
172//! | `rustls-tls` | yes | `reqwest` over `rustls` with the `aws-lc-rs` backend. |
173//! | `native-tls` | no | `reqwest` over the platform TLS stack. |
174//! | `batch` | no | [`decide_all`] and [`run_cases`], bounded-concurrency helpers. |
175//! | `yaml` | no | [`CaseSet::from_yaml_str`] / [`CaseSet::from_file`] for `.yaml`/`.yml`. |
176
177#![forbid(unsafe_code)]
178#![warn(missing_docs, missing_debug_implementations)]
179#![warn(rust_2024_compatibility)]
180
181mod answer;
182#[cfg(feature = "batch")]
183mod batch;
184mod cases;
185mod client;
186mod config;
187mod error;
188mod guidance;
189mod model;
190mod provider;
191mod question;
192mod state;
193mod typed;
194mod util;
195mod wire;
196
197pub use answer::{Answer, Answers, ChoiceAnswer, NoulAnswer, ScoreAnswer};
198#[cfg(feature = "batch")]
199pub use batch::{decide_all, run_cases};
200pub use cases::{Case, CaseNoulCriteria, CaseQuestion, CaseResult, CaseSet};
201pub use client::{Client, Decided, RequestOptions};
202pub use config::{Config, RetryConfig, Surface, Thresholds};
203pub use error::Error;
204pub use guidance::Guidance;
205#[cfg(feature = "derive")]
206pub use jev_macros::{ChoiceOptions, Decision, ScoreLevels};
207pub use model::{DEFAULT_MODEL, Model};
208pub use provider::Provider;
209pub use question::{NoulCriteria, Question, Questions, QuestionsBuilder};
210pub use state::State;
211pub use typed::{Choice, ChoiceOptions, Decision, Noul, Score, ScoreLevels, Verdict};
212pub use wire::{Response, ResponseMeta, TraceConfig, Usage};