# API reference

> Every export of jevascript and jevascript/testing, with its signature and a link to the page that explains it.

Section: Reference · HTML: https://jevascript.org/docs/api · Markdown: https://jevascript.org/docs/api.md

Signatures are abbreviated for reading; the shipped `.d.ts` files are authoritative. Everything below is exported from `jevascript` unless marked otherwise.

## Instances

### `semantic`

```ts
const semantic: Semantic
```

The module-level instance, configured with `configureSemantic()` or from `JEV_API_KEY`. [Configuration →](https://jevascript.org/docs/configuration)

### `createSemantic()`

```ts
function createSemantic(config?: SemanticConfig): Semantic
```

A private instance with its own provider, cache, defaults and hooks. [Configuration →](https://jevascript.org/docs/configuration#createsemantic--a-private-instance)

### `Semantic`

```ts
interface Semantic extends Collections {
  (state: State): SemanticContext
  evaluate<O extends AnyOutput>(request: EvaluateRequest<O>): Promise<OutputValue<O>>
  defineMetric(definition: MetricDefinition): Metric
  defineRule(definition: RuleDefinition): Rule
  defineSchema<const O extends AnyOutput>(definition: SchemaDefinition<O>): Evaluator<O>
  readonly config: SemanticConfig
  configure(config: SemanticConfig): void
}
```

`SemanticFn` is a deprecated alias.

### `configureSemantic()`, `resetSemantic()`, `getConfig()`

```ts
function configureSemantic(config: SemanticConfig): void   // merges into the module-level runtime
function resetSemantic(): void                             // clears config, new in-memory cache
function getConfig(): SemanticConfig
```

### `createRuntime()`

```ts
function createRuntime(config?: SemanticConfig): Runtime

interface Runtime {
  readonly config: SemanticConfig
  readonly store: SemanticCache
  provider(override?: SemanticProvider): SemanticProvider
  configure(config: SemanticConfig): void
}
```

The object behind an instance. Needed only with the `*With` functions below.

### `BUILTIN_DEFAULTS`

```ts
const BUILTIN_DEFAULTS: { timeoutMs: 10_000; samples: 3; threshold: 0.5; uncertaintyBand: [0.3, 0.7] }
```

## Context

### `SemanticContext`

Returned by `semantic(state)`. Constructible directly as `new SemanticContext(state, runtime?)`.

### `.is()`

```ts
is(condition: string, options?: IsOptions): Promise<boolean>
is(condition: string, options: IsOptions & { detailed: true }): Promise<DetailedTruth>
is(condition: string, options: IsOptions & { allowUnknown: true }): Promise<boolean | "unknown">
```

[Primitives →](https://jevascript.org/docs/primitives#is--a-proposition-is-true)

### `.score()`

```ts
score(criterion: string, options?: ScoreOptions): Promise<number>
score(criterion: string, options: ScoreOptions & { detailed: true }): Promise<DetailedScore>
```

[Primitives →](https://jevascript.org/docs/primitives#score--how-strongly-a-proposition-holds)

### `.choose()`

```ts
choose<const T extends readonly string[]>(options: T, extra?: ChooseOptions): Promise<T[number]>
choose<const T extends Record<string, string | ChoiceOptionSpec>>(options: T, extra?: ChooseOptions): Promise<keyof T & string>
// with { detailed: true }: Promise<DetailedChoice<...>>
```

[Primitives →](https://jevascript.org/docs/primitives#choose--one-of-a-fixed-set)

### `.batch()`

```ts
batch<S extends Record<string, QuestionSpec>>(spec: S): Promise<{ [K in keyof S]: ValueOf<S[K]> }>
```

Every question in one request. [Batching →](https://jevascript.org/docs/batching)

### `.rank()`

```ts
rank<T>(items: readonly T[], options: Omit<RankOptions, "context">): Promise<Ranked<T>[]>
```

Orders items by fit against the wrapped state, one request per item. [Collections →](https://jevascript.org/docs/collections#rank--order-by-fit)

### Detailed results

```ts
interface DetailedTruth  { value: boolean; probability: number; confidence?: number }
interface DetailedScore  { value: number; probability?: number; level?: number; confidence?: number }
interface DetailedChoice<T extends string> { value: T; confidence: number; probabilities: Record<string, number> }
```

## Question builders

Standalone forms for composing inside `batch()`.

### `is()`

```ts
function is(condition: string, options?: IsOptions): QuestionSpec<boolean>
```

### `score()`

```ts
function score(criterion: string, options?: ScoreOptions): QuestionSpec<number>   // question form
function score(min?: number, max?: number, describe?: string): NumberOutput       // output form
```

Two functions disambiguated by the first argument. The output form is for `defineSchema` and `evaluate`. [Definitions →](https://jevascript.org/docs/definitions#output-helpers)

### `choose()`

```ts
function choose<const T extends readonly string[]>(options: T, extra?: ChooseOptions): QuestionSpec<T[number]>
function choose<const T extends Record<string, string | ChoiceOptionSpec>>(options: T, extra?: ChooseOptions): QuestionSpec<keyof T & string>
```

### `DEFAULT_SCORE_FRAME`

```ts
const DEFAULT_SCORE_FRAME: (criterion: string) => string   // c => `This has high ${c}.`
```

### Option types

```ts
interface SharedOptions {
  provider?: SemanticProvider
  timeoutMs?: number
  cache?: string | number
  samples?: number
  minConfidence?: number
  detailed?: boolean
  metric?: { name: string; version?: string }
}
interface TruthCriteria { trueWhen?: string | JsonValue; falseWhen?: string | JsonValue }

interface IsOptions extends SharedOptions, TruthCriteria {
  threshold?: number
  allowUnknown?: boolean
  uncertaintyBand?: readonly [number, number]
  fallback?: boolean | (() => boolean | Promise<boolean>)
}
interface ScoreOptions extends SharedOptions, TruthCriteria {
  range?: readonly [number, number]
  levels?: readonly (string | LevelSpec)[]
  asProposition?: boolean
  fallback?: number | (() => number | Promise<number>)
}
interface ChooseOptions extends SharedOptions {
  instructions?: string
  fallback?: string | (() => string | Promise<string>)
}
interface QuestionSpec<TValue = unknown> { readonly build: (frame: (c: string) => string) => BuiltQuestion }
type ChoiceInput = readonly string[] | Readonly<Record<string, string | ChoiceOptionSpec>>
```

## Definitions

### `defineRule()`

```ts
function defineRule(definition: RuleDefinition): Rule
function defineRuleWith(runtime: Runtime, definition: RuleDefinition): Rule

interface RuleDefinition {
  name: string; version?: string
  condition: string
  trueWhen?: string | JsonValue; falseWhen?: string | JsonValue
  defaults?: SharedOptions & { threshold?: number; allowUnknown?: boolean }
}
interface Rule {
  (state: State, options?: IsOptions): Promise<boolean>
  readonly name: string; readonly version: string | undefined; readonly definition: RuleDefinition
  question(options?: IsOptions): QuestionSpec<boolean>
}
```

[Definitions →](https://jevascript.org/docs/definitions#definerule--a-reusable-is)

### `defineMetric()`

```ts
function defineMetric(definition: MetricDefinition): Metric
function defineMetricWith(runtime: Runtime, definition: MetricDefinition): Metric

interface MetricDefinition {
  name: string; version?: string
  description: string
  trueWhen?: string | JsonValue; falseWhen?: string | JsonValue
  output?: NumberOutput
  defaults?: Omit<ScoreOptions, "range" | "levels">
}
interface Metric {
  (state: State, options?: ScoreOptions): Promise<number>
  readonly name: string; readonly version: string | undefined; readonly definition: MetricDefinition
  question(options?: ScoreOptions): QuestionSpec<number>
}
```

[Definitions →](https://jevascript.org/docs/definitions#definemetric--a-reusable-score)

### `defineSchema()`

```ts
function defineSchema<const O extends AnyOutput>(definition: SchemaDefinition<O>): Evaluator<O>
function defineSchemaWith<const O extends AnyOutput>(runtime: Runtime, definition: SchemaDefinition<O>): Evaluator<O>

interface SchemaDefinition<O extends AnyOutput> {
  name: string; version?: string
  instructions: string
  context?: Record<string, unknown>
  output: O
  defaults?: { timeoutMs?: number; cache?: string | number; samples?: number }
}
interface SchemaOptions { provider?: SemanticProvider; timeoutMs?: number; cache?: string | number; samples?: number }
interface Evaluator<O extends AnyOutput> {
  (data: State, options?: SchemaOptions): Promise<OutputValue<O>>
  readonly name: string; readonly version: string | undefined; readonly definition: SchemaDefinition<O>
}
```

[Definitions →](https://jevascript.org/docs/definitions#defineschema--many-fields-one-request)

### `evaluate()`

```ts
function evaluate<O extends AnyOutput>(request: EvaluateRequest<O>): Promise<OutputValue<O>>
function evaluateWith<O extends AnyOutput>(runtime: Runtime, request: EvaluateRequest<O>): Promise<OutputValue<O>>

interface EvaluateRequest<O extends AnyOutput> {
  data: State
  question: string
  context?: Record<string, unknown>
  output: O
  provider?: SemanticProvider; timeoutMs?: number; cache?: string | number; samples?: number
  metric?: { name: string; version?: string }
}
```

[Definitions →](https://jevascript.org/docs/definitions#evaluate--the-low-level-form)

## Outputs

```ts
function boolean(options?: { describe?: string; trueWhen?: string | JsonValue; falseWhen?: string | JsonValue }): BooleanOutput
function number(options?: { min?: number; max?: number; describe?: string; levels?: readonly string[] }): NumberOutput
function enumOf<const T extends readonly string[]>(options: T, describe?: string): EnumOutput<T[number]>
function enumOf<const T extends Record<string, string | ChoiceOptionSpec>>(options: T, describe?: string): EnumOutput<keyof T & string>
function object<const F extends Record<string, AnyOutput>>(fields: F): ObjectOutput<F>
function numberRange(min?: number, max?: number, describe?: string): NumberOutput

type AnyOutput = BooleanOutput | NumberOutput | EnumOutput | ObjectOutput
type OutputValue<O>   // boolean | number | literal union | mapped object
```

[Definitions →](https://jevascript.org/docs/definitions#output-helpers)

## Collections

```ts
function filter<T>(items: readonly T[], condition: string, options?: CollectionOptions & TruthCriteria): Promise<T[]>
function some<T>(items: readonly T[], condition: string, options?: CollectionOptions): Promise<boolean>
function every<T>(items: readonly T[], condition: string, options?: CollectionOptions): Promise<boolean>
function rank<T>(items: readonly T[], options: RankOptions): Promise<Ranked<T>[]>
function find<T>(items: readonly T[], condition: string, options?: CollectionOptions): Promise<T | undefined>
function compare<T>(left: T, right: T, options: { by: string; label?: (item: T) => string } & CollectionOptions): Promise<Comparison>
function bindCollections(runtime: Runtime): Collections

interface CollectionOptions {
  provider?: SemanticProvider; timeoutMs?: number; cache?: string | number; samples?: number; threshold?: number
  label?: (item: never, index: number) => string
  concurrency?: number
}
interface RankOptions extends CollectionOptions { by: string; trueWhen?: string; falseWhen?: string; context?: State }
interface Ranked<T> { item: T; score: number }
type Comparison = "left" | "right" | "equal"
```

The bare functions bind to the module-level instance; the same methods exist on every `Semantic`. [Collections →](https://jevascript.org/docs/collections)

## Cache

```ts
interface SemanticCache {
  get(key: string): Promise<SemanticAnswer | undefined> | SemanticAnswer | undefined
  set(key: string, value: SemanticAnswer, ttlMs: number): Promise<void> | void
}
class MemoryCache implements SemanticCache {
  constructor(maxEntries?: number)   // default 5_000
  clear(): void
}
function parseTtl(ttl: string | number): number    // "5m" → 300_000
function hashKey(input: string): string
function cacheKeyFor(provider: SemanticProvider, state: State, question: SemanticQuestion, samples: number): string
```

[Caching →](https://jevascript.org/docs/caching)

## Runner

Lower-level pieces, exported for provider authors and custom runtimes.

```ts
function runPlan(
  provider: SemanticProvider,
  state: State,
  planned: readonly PlannedQuestion[],
  options?: { timeoutMs?: number; signal?: AbortSignal; store?: SemanticCache },
): Promise<RunResult>

function assertSupported(provider: SemanticProvider, question: SemanticQuestion): void
function confidenceFromSpread(samples: readonly number[]): number   // 1 − 2·stdev, clamped to [0, 1]

interface PlannedQuestion { key: string; question: SemanticQuestion; samples: number; cacheTtlMs?: number }
interface RunResult {
  answers: Record<string, SemanticAnswer>
  measured: Record<string, number | undefined>
  cachedKeys: Set<string>
  usage: Usage
  latencyMs: number
  requestCount: number
}
```

## Providers

```ts
function jev(options?: JevOptions): SemanticProvider
interface JevOptions { apiKey?: string; model?: string; baseUrl?: string; fetch?: typeof fetch; maxRetries?: number }
const DEFAULT_MODEL: "jev-1.13.0"
const DEFAULT_BASE_URL: string   // the Jev API endpoint; see Providers
const JEV_CAPABILITIES: ProviderCapabilities

interface SemanticProvider {
  readonly name: string
  readonly model: string
  readonly capabilities: ProviderCapabilities
  evaluate(request: SemanticRequest): Promise<SemanticProviderResponse>
}
interface ProviderCapabilities {
  readonly maxChoiceOptions: number
  readonly levelRange: readonly [number, number]
  readonly maxStateTokens?: number
  readonly maxTotalTokens?: number
  readonly generatesText: boolean
  readonly batching: boolean
}
interface SemanticRequest { readonly state: State; readonly questions: Record<string, SemanticQuestion>; readonly signal?: AbortSignal; readonly timeoutMs?: number }
interface SemanticProviderResponse { readonly answers: Record<string, SemanticAnswer>; readonly usage?: Usage; readonly model?: string }
```

[Providers →](https://jevascript.org/docs/providers)

## Questions and answers

The provider-neutral wire vocabulary.

```ts
type State = string | readonly string[] | object
type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue }

interface TruthQuestion  { kind: "truth";  instructions: string | JsonValue; trueWhen?: string | JsonValue; falseWhen?: string | JsonValue }
interface ChoiceQuestion { kind: "choice"; instructions: string | JsonValue; options: Record<string, string | ChoiceOptionSpec> }
interface LevelQuestion  { kind: "level";  instructions: string | JsonValue; levels: readonly (string | LevelSpec)[] }
type SemanticQuestion = TruthQuestion | ChoiceQuestion | LevelQuestion

interface ChoiceOptionSpec { what: string; not_for?: string; examples?: readonly string[] }
interface LevelSpec { summary: string; signals?: readonly string[] }

interface TruthAnswer  { kind: "truth";  probability: number }
interface ChoiceAnswer { kind: "choice"; choice: string; probabilities: Record<string, number>; confidence: number }
interface LevelAnswer  { kind: "level";  level: number; probabilities: readonly number[]; confidence: number }   // level is 0-indexed
type SemanticAnswer = TruthAnswer | ChoiceAnswer | LevelAnswer

interface Usage { inputTokens?: number; outputTokens?: number }
```

## Configuration types

```ts
interface SemanticConfig {
  provider?: SemanticProvider
  defaults?: SemanticDefaults
  observability?: Observability
  cacheStore?: SemanticCache
  warnUnbatched?: boolean
}
interface SemanticDefaults {
  timeoutMs?: number; minConfidence?: number; cache?: string | number; samples?: number
  threshold?: number; uncertaintyBand?: readonly [number, number]
  scoreFrame?: (criterion: string) => string
}
```

[Configuration →](https://jevascript.org/docs/configuration)

## Observability

```ts
interface Observability {
  onEvaluation?(event: EvaluationEvent): void
  onUnbatched?(info: { context: string; flushCount: number }): void
}
interface EvaluationEvent {
  operation: "is" | "score" | "choose" | "batch" | "evaluate" | "rank" | "filter" | "find" | "compare"
  keys: readonly string[]
  provider: string; model: string
  latencyMs: number; cached: boolean; batched: boolean
  questionCount: number; requestCount: number; samples: number
  usage?: Usage
  metric?: { name: string; version?: string }
}
```

[Observability →](https://jevascript.org/docs/observability)

## Errors

```ts
class SemanticError extends Error
class NotConfiguredError extends SemanticError
class UnsupportedByProviderError extends SemanticError { readonly provider: string; readonly feature: string }
class LowConfidenceError extends SemanticError { readonly confidence: number; readonly minConfidence: number; readonly value: unknown }
class ProviderError extends SemanticError { readonly status?: number }
class SemanticValidationError extends SemanticError { readonly condition: string; readonly probability: number }   // reserved
```

[Errors →](https://jevascript.org/docs/errors)

## `jevascript/testing`

```ts
function createMockSemanticProvider(rules?: Record<string, MockValue>, options?: MockProviderOptions): MockProvider

type MockValue = number | boolean | string | SemanticAnswer
interface MockProviderOptions { capabilities?: Partial<ProviderCapabilities>; model?: string; fallback?: MockValue; jitter?: number }
interface MockProvider extends SemanticProvider {
  readonly calls: { state: State; questions: Record<string, SemanticQuestion> }[]
  readonly requestCount: number
  reset(): void
}
```

[Testing →](https://jevascript.org/docs/testing)