Reference

API reference

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

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

Instances#

`semantic`#

const semantic: Semantic

The module-level instance, configured with configureSemantic() or from JEV_API_KEY. Configuration →

`createSemantic()`#

function createSemantic(config?: SemanticConfig): Semantic

A private instance with its own provider, cache, defaults and hooks. Configuration →

`Semantic`#

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()`#

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

`createRuntime()`#

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`#

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()`#

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 →

`.score()`#

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

Primitives →

`.choose()`#

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 →

`.batch()`#

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

Every question in one request. Batching →

`.rank()`#

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 →

Detailed results#

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()`#

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

`score()`#

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 →

`choose()`#

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`#

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

Option types#

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()`#

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 →

`defineMetric()`#

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 →

`defineSchema()`#

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 →

`evaluate()`#

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 →

Outputs#

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 →

Collections#

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 →

Cache#

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 →

Runner#

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

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#

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 →

Questions and answers#

The provider-neutral wire vocabulary.

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#

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 →

Observability#

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 →

Errors#

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 →

`jevascript/testing`#

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 →

Instances#

semantic#

createSemantic()#

Semantic#

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

createRuntime()#

BUILTIN_DEFAULTS#

Context#

SemanticContext#

.is()#

.score()#

.choose()#

.batch()#

.rank()#

Detailed results#

Question builders#

is()#

score()#

choose()#

DEFAULT_SCORE_FRAME#

Option types#

Definitions#

defineRule()#

defineMetric()#

defineSchema()#

evaluate()#

Outputs#

Collections#

Cache#

Runner#

Providers#

Questions and answers#

Configuration types#

Observability#

Errors#

jevascript/testing#

`semantic`#

`createSemantic()`#

`Semantic`#

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

`createRuntime()`#

`BUILTIN_DEFAULTS`#

`SemanticContext`#

`.is()`#

`.score()`#

`.choose()`#

`.batch()`#

`.rank()`#

`is()`#

`score()`#

`choose()`#

`DEFAULT_SCORE_FRAME`#

`defineRule()`#

`defineMetric()`#

`defineSchema()`#

`evaluate()`#

`jevascript/testing`#