# jev4k

> A Kotlin DSL and client for TypeSafe's Jev model. Jev is a *System One* model: it returns fast, calibrated
> judgments rather than generated text. You give it a state (a message, a document, a record) and a set of typed
> questions, and it answers each one with a typed value and the probabilities behind it.

jev4k declares those questions in Kotlin, sends them in one HTTP request, and reads the answers back as typed
values, down to enum-valued choices that work with an exhaustive `when`. It is built on the Ktor client (CIO) and
kotlinx.serialization, has a suspend-first API with a blocking mirror, and targets Java 17.

There are three kinds of question. A **Noul** asks whether something is true and answers with a probability. A
**Choice** picks one of a set of options and reports a probability per option plus a confidence. A **Score**
places the state on ordered levels and can fall between them. Questions can be written inline with string ids or
declared once as a typed `JevQuery` object whose property names become the ids.

## Start here

- [Home](https://jev4k.com/): what the library does, with a first example and a diagram of the request flow
- [Concepts](https://jev4k.com/concepts/): state, questions, answers, calibrated confidence, and the wire format behind them
- [Installation](https://jev4k.com/getting-started/installation/): requirements, embedding notes, dependencies, and calling jev4k from Java
- [Quick Start](https://jev4k.com/getting-started/quick-start/): an API key and a first query in a few lines

## Questions

- [Choosing a type](https://jev4k.com/questions/): which of Noul, Choice, or Score fits a given judgment
- [Noul](https://jev4k.com/questions/noul/): yes/no probability, thresholds, bands, and counting in code
- [Choice](https://jev4k.com/questions/choice/): one option from a set, with a distribution and confidence
- [Score](https://jev4k.com/questions/score/): a position on ordered levels, normalized scores, and per-level probabilities
- [Structured criteria](https://jev4k.com/questions/structured/): contrastive rubrics, examples, and JSON field specs

## Building queries

- [Inline DSL](https://jev4k.com/queries/inline/): `jev.query(state) { ... }` with string ids
- [Typed queries](https://jev4k.com/queries/typed/): reusable `JevQuery` objects whose property names become question ids
- [Enum choices](https://jev4k.com/queries/enums/): `choice<E>()` answering with an enum constant, via the `JevOption` interface
- [State](https://jev4k.com/queries/state/): passing a String, a JsonElement, or any `@Serializable` value

## Reading results

- [Reading results](https://jev4k.com/results/reading/): typed handles, by-id accessors, and listing answers by kind
- [Confidence and thresholds](https://jev4k.com/results/confidence/): what confidence means, and how to gate on it

## Client

- [Configuration](https://jev4k.com/client/configuration/): API key, base URL, model, timeout, and supplying a custom Ktor engine
- [Making calls](https://jev4k.com/client/calls/): the suspend API, the blocking mirror, and concurrency
- [Retries and errors](https://jev4k.com/client/errors/): the exception hierarchy, retry rules, and server retry hints

## Patterns

- [Overview](https://jev4k.com/patterns/): how the patterns relate and when to reach for each
- [Speculative fan-out](https://jev4k.com/patterns/fan-out/): ask every branch's question in one request, then use the answers that apply
- [Routing](https://jev4k.com/patterns/routing/): pick a handler and a model tier from a message
- [Composite scoring](https://jev4k.com/patterns/composite-scoring/): score dimensions once, then reweight in code
- [Verification](https://jev4k.com/patterns/verification/): check claims against their evidence and escalate the uncertain ones
- [Extraction](https://jev4k.com/patterns/extraction/): select values from candidates found in code, rather than generating them
- [Search and ranking](https://jev4k.com/patterns/search/): rerank retrieved passages by graded relevance
- [Guardrails and moderation](https://jev4k.com/patterns/guardrails/): policy thresholds over reusable judgments
- [Classification](https://jev4k.com/patterns/classification/): flat and hierarchical labelling

## Reference

- [KDocs index](https://jev4k.com/api/): a guided map of the API reference, grouped into entry points, question building, and reading answers
- [API reference (KDocs)](https://jev4k.com/kdocs/): the full Dokka-generated API, every public type and function
- [Writing good questions](https://jev4k.com/guides/best-practices/): the habits that make Jev's answers accurate and useful
- [Development](https://jev4k.com/guides/development/): building, testing, and how the documentation examples are compiled
- [Source repository](https://github.com/pambrose/jev4k): Apache 2.0, with the README covering the same API in one page

## Optional

- [TypeSafe documentation](https://docs.typesafe.ai): the model's own docs, the authority on Jev's behaviour, primitives, and limits
- [TypeSafe llms.txt](https://docs.typesafe.ai/llms.txt): the same in this format, for the API and model rather than this client