jev4k/com.pambrose.jev4k

Package-level declarations

Types

Answer

sealed interface Answer

A typed answer to one question.

BlockingJev

class BlockingJev

JevApi as blocking calls, for scripts, main, and tests.

ChoiceAnswer

data class ChoiceAnswer<K : Any>(val choice: K, val probabilities: Map<K, Double>, val confidence: Double) : Answer

The answer to a Choice: the highest-probability option, the probability of every option, and a confidence from 0 to 1 derived from how concentrated probabilities is. Confidence is not the winner's probability.

ChoiceBuilder

class ChoiceBuilder

A Choice's options, in order. Option keys and descriptions are both sent to the model.

ChoiceQuestion

data class ChoiceQuestion(val instructions: JsonElement, val options: Map<String, JsonElement>) : Question

Pick one of options, in order; a JsonNull description sends the option undescribed.

JevApi

interface JevApi

The Jev API. evaluate is the only call that sends questions; query and ask are conveniences on top of it, so application code that depends on JevApi can be tested with a fake or mock.

JevApiException

open class JevApiException(val status: Int, val body: String?, val headers: Map<String, List<String>>, val requestId: String?, val endpoint: String, message: String, cause: Throwable? = null) : JevException

The API answered with an error, or with a body jev4k couldn't use. body is the raw response body, requestId the x-typesafe-request-id header, and endpoint the method and URL called.

JevAuthenticationException

class JevAuthenticationException : JevApiException

401: the API key is missing or invalid.

JevBadRequestException

class JevBadRequestException : JevApiException

400: the request was malformed.

JevClient

class JevClient(val config: JevConfig) : JevApi, AutoCloseable

A Jev client over Ktor (CIO). Configure it inline, or rely on TYPESAFE_API_KEY:

JevConfig

class JevConfig

Resolved client settings. Build one with JevConfigBuilder or the JevClient { } constructor.

JevConfigBuilder

class JevConfigBuilder

Builder for JevConfig. Each setting resolves as: explicit value, then environment variable, then default.

JevConfigException

class JevConfigException(message: String) : JevException

The client could not be configured, e.g. no API key was supplied.

JevConnectionException

open class JevConnectionException(message: String, cause: Throwable? = null) : JevException

No HTTP response was received (DNS, TLS, refused or dropped connection).

JevDefaults

object JevDefaults

Environment variable names, defaults, and header names shared with the official TypeSafe SDKs.

JevDsl

@DslMarker

annotation class JevDsl

Marks jev4k's DSL receivers so nested builder lambdas can't call an outer builder by accident.

JevException

sealed class JevException : RuntimeException

Base class for every error raised by jev4k.

JevInternalServerException

open class JevInternalServerException : JevApiException

5xx: a server-side failure.

JevNotFoundException

class JevNotFoundException : JevApiException

404: unknown endpoint or resource.

JevOption

interface JevOption

Optional metadata for enum constants used as Choice options. By default an option's key is the constant's name and it is sent undescribed.

JevOverloadedException

class JevOverloadedException : JevInternalServerException

529: TypeSafe is temporarily overloaded.

JevPermissionDeniedException

class JevPermissionDeniedException : JevApiException

403: the API key may not do this.

JevQuery

abstract class JevQuery

A reusable set of questions declared as properties; each property name becomes the question id.

JevRateLimitException

class JevRateLimitException : JevApiException

429: rate limited. retryAfter is the server's hint, when it sent one.

JevResponseValidationException

class JevResponseValidationException(detail: String, val fieldPath: String?, body: String?, requestId: String?, endpoint: String, status: Int = 200, headers: Map<String, List<String>> = emptyMap(), cause: Throwable? = null) : JevApiException

A successful response was missing data or didn't match the questions asked; fieldPath locates the problem.

JevResult

class JevResult

The answers to one request. Read them with the handles you declared (result[Triage.department]) or by id (result.noul("urgent")). A missing or mismatched answer raises JevResponseValidationException when it is read; an id or handle that wasn't part of the request raises IllegalArgumentException.

JevTimeoutException

class JevTimeoutException(message: String, cause: Throwable? = null) : JevConnectionException

A request attempt exceeded the configured timeout.

JevUnprocessableEntityException

class JevUnprocessableEntityException : JevApiException

422: the request failed server-side validation; body names the offending field.

JevValidationException

class JevValidationException(val problems: List<String>, cause: Throwable? = null) : JevException

A request was rejected locally, before anything was sent. problems lists every issue found.

ModelInfo

data class ModelInfo(val name: String, val description: String?, val releaseDate: String?)

One entry from GET /v1/models.

NoulAnswer

data class NoulAnswer(val noul: Double) : Answer

The answer to a Noul: noul is the probability, from 0 to 1, that the answer is yes. Nouls have no confidence.

NoulBand

enum NoulBand : Enum<NoulBand>

NoulBuilder

class NoulBuilder

Optional descriptions of what a Noul's yes and no mean.

NoulQuestion

data class NoulQuestion(val instructions: JsonElement, val whenTrue: JsonElement? = null, val whenFalse: JsonElement? = null) : Question

A yes/no question; whenTrue and whenFalse optionally define what yes and no mean.

QueryBuilder

class QueryBuilder

Collects the questions for one request, keyed by ids you choose. Every function returns a QuestionRef handle, so val urgent = noul(...) then result[urgent] works too.

Question

sealed interface Question

What one question asks, independent of its id: instructions plus criteria, each arbitrary JSON (usually a string). Named after the TypeSafe JS SDK's Question / NoulQuestion / ChoiceQuestion / ScoreQuestion. A QuestionRef pairs one with an id.

QuestionProvider

class QuestionProvider<out A : Answer> : PropertyDelegateProvider<JevQuery, QuestionRef<A>>

Creates a question when it is bound to a JevQuery property, using the property name as the default id.

QuestionRef

class QuestionRef<out A : Answer>

A handle to one question. The same handle reads its typed answer back from a JevResult, and it can be used as a property delegate so val urgent by noul(...) works in a JevQuery.

QuestionSet

class QuestionSet : Iterable<QuestionRef<*>>

An ordered, validated set of questions: everything one request asks about a single state.

RetryPolicy

data class RetryPolicy(val maxRetries: Int = 2, val initialBackoff: Duration = 500.milliseconds, val maxBackoff: Duration = 5.seconds, val jitter: Double = 0.25, val retryStatuses: Set<Int> = setOf(408, 429) + (500..599), val respectRetryAfter: Boolean = true, val maxRetryAfter: Duration = 60.seconds, val retryOnConnectionError: Boolean = true, val retryOnTimeout: Boolean = true)

When and how failed requests are retried. The defaults match the official Python and JS SDKs: two retries, 0.5 s backoff doubling to a 5 s cap with up to 25% subtracted as jitter, and server retry-after-ms / Retry-After hints honored up to maxRetryAfter.

ScoreAnswer

data class ScoreAnswer(val score: Double, val probabilities: Map<Int, Double>, val legend: Map<Int, JsonElement>, val confidence: Double, val levelCount: Int) : Answer

The answer to a Score: score is the probability-weighted level (Σ level × p), so it can fall between levels. probabilities and legend are keyed by level number; the legend holds the level entries that were sent. levelCount is the number of levels asked about.

ScoreBuilder

class ScoreBuilder

A Score's levels, lowest first. Describe situations, not degrees; each level is judged on its own.

ScoreQuestion

data class ScoreQuestion(val instructions: JsonElement, val levels: List<JsonElement>) : Question

Rate along ordered levels; a level's number is its index.

UnknownAnswer

data class UnknownAnswer(val type: String?, val raw: JsonObject) : Answer

An answer of a type this version of jev4k doesn't know; raw is the answer object as received.

Usage

data class Usage(val inputTokens: Long?, val outputTokens: Long?)

Token counts reported by the API; either may be absent.

Properties

MAX_CHOICE_OPTIONS

const val MAX_CHOICE_OPTIONS: Int = 255

Most options a Choice may offer.

MAX_SCORE_LEVELS

const val MAX_SCORE_LEVELS: Int = 10

Most levels a Score may have.

MIN_SCORE_LEVELS

const val MIN_SCORE_LEVELS: Int = 2

Fewest levels a Score may have.

Functions

ask

inline suspend fun <T : Any> JevApi.ask(query: JevQuery, state: T, model: String? = null): JevResult

Asks a JevQuery's questions about a @Serializable state.

suspend fun JevApi.ask(query: JevQuery, state: String, model: String? = null): JevResult

Asks a JevQuery's questions about a text state.

suspend fun JevApi.ask(query: JevQuery, state: JsonElement, model: String? = null): JevResult

Asks a JevQuery's questions about a JSON state.

entry

fun entry(vararg fields: Pair<String, Any?>): JsonObject

Builds a structured JSON entry for instructions, option descriptions, or levels, e.g. entry("question" to "Which team?", "focus" to "The primary request"). Keys keep their order, and the model sees both the keys and the values.

jevApiException

@JvmOverloads

fun jevApiException(status: Int, body: String? = null, requestId: String? = null, retryAfter: Duration? = null, headers: Map<String, List<String>> = emptyMap()): JevApiException

The JevApiException subclass the client raises for HTTP status, for testing a caller's error handling: 429 gives a JevRateLimitException, 401 a JevAuthenticationException, and so on.

jevResult

fun jevResult(body: String, questions: QuestionSet, model: String = JevDefaults.MODEL, requestId: String? = null): JevResult

The same, from the response body as JSON text.

fun jevResult(body: JsonObject, questions: QuestionSet, model: String = JevDefaults.MODEL, requestId: String? = null): JevResult

A JevResult built from a raw response body, as JevApi.evaluate would have returned it for questions.

jsonEntry

inline fun <T> jsonEntry(value: T): JsonElement

Encodes a @Serializable value as JSON, keeping fields that equal their defaults.

jsonOf

fun jsonOf(value: Any?): JsonElement

Converts plain Kotlin values (null, strings, numbers, booleans, enums, maps with string keys, iterables, arrays, and JSON elements) to JSON. Use jsonEntry for @Serializable values.

query

inline suspend fun <T : Any> JevApi.query(state: T, model: String? = null, noinline block: QueryBuilder.() -> Unit): JevResult

Asks inline questions about a @Serializable state.

suspend fun JevApi.query(state: String, model: String? = null, block: QueryBuilder.() -> Unit): JevResult

Asks inline questions about a text state.

suspend fun JevApi.query(state: JsonElement, model: String? = null, block: QueryBuilder.() -> Unit): JevResult

Asks inline questions about a JSON state.

questions

fun questions(block: QueryBuilder.() -> Unit): QuestionSet

Builds a validated QuestionSet inline.

rubric

fun rubric(what: String, notFor: String? = null, examples: List<String> = emptyList()): JsonObject

A contrastive option or level description, {"what", "not_for", "examples"}, the shape the TypeSafe docs use to sharpen boundaries between similar options.