API reference

defineSearch(schema)

function defineSearch<const F extends Fields>(schema: {
  resource: string;
  version?: string;
  fields: F;
}): SearchSchema<F>

Throws when there are no fields, more than 16 fields, a field name that does not match /^[A-Za-z][A-Za-z0-9_]{0,63}$/, or more than one entity field. The returned schema and its fields object are frozen.

enumField(values, options?)

function enumField<const V extends string>(
  values: readonly V[] | Readonly<Record<V, string | null>>,
  options?: FieldBase,
): EnumField<V>

Pass an array of allowed values, or an object that maps each value to a description. The description is sent to the model, so it is where business synonyms go: { high: "urgent, critical, P1" } is the only reason "urgent" can mean high. Throws with no values, more than 100 values, or a value that is blank or longer than 100 characters.

Filter value: "open" or { not: "closed" }.

booleanField(options?)

function booleanField(options?: FieldBase): BooleanField

A yes/no flag. Filter value: true or false. Use description to say what "yes" means, for example "escalated to a manager".

numberField(options?)

function numberField(options?: FieldBase & { unit?: string }): NumberField

Filter value: a NumberRange such as { lt: 500 }. unit is a currency code or a unit label. When both the field and the request name a unit and they differ (compared case-insensitively), prepare returns unsupported with reason unit_mismatch. The parser only recognizes USD, EUR, GBP and INR, so a field with unit: "replies" accepts plain numbers and refuses currency amounts such as "$5". A request number with no unit is accepted for any field.

dateField(options?)

function dateField(options?: FieldBase): DateField

Filter value: a half-open DateRange of calendar dates, { gte: "2026-08-01", lt: "2026-09-01" }, in the request time zone.

entityField(options)

function entityField<Ctx = unknown>(
  options: FieldBase & Pick<EntityField<Ctx>, "resolve" | "verify">,
): EntityField<Ctx>

resolve: (phrase: string, context: Ctx) => Promise<EntityCandidate[]> | EntityCandidate[];
verify?: (id: string, context: Ctx) => Promise<boolean> | boolean;

A named record, such as a customer or an owner. The model picks which phrase of the request names it. Your resolve function looks that phrase up within what context may see and returns { id, label } candidates:

• exactly one candidate binds, and its id becomes the filter value;
• zero candidates give a no_match clarification;
• two or more give a choose_entity clarification listing them.

Candidates are deduplicated by id, labels are cut to 200 characters, and the list stops at 20 (LIMITS.maxEntityCandidates). A result that is not an array, or has an item without a non-empty string id and a string label, gives unavailable with reason resolver_error. Candidate labels and ids are never sent to the model.

verify is optional. When present, execute calls it for the entity id in the filters and treats anything other than true, or a throw, as "not found". Throws at build time when resolve is not a function.

LIMITS

const LIMITS = {
  maxFields: 16,
  maxEnumValues: 100,
  maxEntityCandidates: 20,
} as const;

The full list of hard limits is in Limits.

Schema types

interface FieldBase {
  label?: string;        // shown in chips and questions; defaults to the field key
  description?: string;  // plain-language meaning, sent to the model
}

interface EnumField<V extends string = string> extends FieldBase {
  kind: "enum"; values: Readonly<Record<V, string | null>>;
}
interface BooleanField extends FieldBase { kind: "boolean" }
interface NumberField extends FieldBase { kind: "number"; unit?: string }
interface DateField extends FieldBase { kind: "date" }
interface EntityField<Ctx = unknown> extends FieldBase {
  kind: "entity";
  resolve: (phrase: string, context: Ctx) => Promise<EntityCandidate[]> | EntityCandidate[];
  verify?: (id: string, context: Ctx) => Promise<boolean> | boolean;
}
interface EntityCandidate {
  id: string;     // opaque handle your executor understands; ends up in filters
  label: string;  // shown to the user in a chooser; never sent to the model
}

type Field<Ctx = any> = EnumField<string> | BooleanField | NumberField | DateField | EntityField<Ctx>;
type Fields<Ctx = any> = Record<string, Field<Ctx>>;

interface SearchSchema<F extends Fields = Fields> {
  resource: string; version: string; fields: F;
}

interface NumberRange { eq?: number; gt?: number; gte?: number; lt?: number; lte?: number }
interface DateRange { gte?: string; lt?: string }   // YYYY-MM-DD, half-open

type FilterValue<F> =                // enum: V | { not: V }
                                      // boolean: boolean
                                      // number: NumberRange
                                      // date: DateRange
                                      // entity: string (the id)
type Filters<F extends Fields> = { [K in keyof F]?: FilterValue<F[K]> };

Filters is the typed object your executor receives. Every key is optional, and every present bound of a NumberRange must hold.

createNaturalFilter(config)

function createNaturalFilter<F extends Fields, Ctx = unknown, R = unknown>(
  config: NaturalFilterConfig<F, Ctx, R>,
): NaturalFilter<F, Ctx, R>

interface NaturalFilter<F extends Fields, Ctx, R> {
  readonly schema: SearchSchema<F>;
  prepare(text: string, options?: PrepareOptions<Ctx>): Promise<NaturalFilterResult<F>>;
  execute(filters: unknown, options?: { context?: Ctx }): Promise<ExecuteResult<F, R>>;
  validate(filters: unknown): ValidationResult<F>;
}

Ctx is your trusted server context, usually the session. R is whatever your executor returns. Throws a TypeError when schema has no fields, when provider has no choose function, or when authorize is missing and allowUnauthenticated is not exactly true.

NaturalFilterConfig

prepare(text, options?)

prepare(text: string, options?: PrepareOptions<Ctx>): Promise<NaturalFilterResult<F>>

interface PrepareOptions<Ctx> {
  context?: Ctx;
  now?: Date;
  timeZone?: string;
  signal?: AbortSignal;
}

Interprets the text and never calls the executor. It makes one provider call, plus one call to your resolver when the request names an entity. Checks run in this order: empty input, length, authorize, then the count of dates and numbers (more than 4 of either is too_complex). None of these reach the provider. prepare does not throw for bad input; every outcome is a result.

Two thresholds keep conditions from disappearing quietly. If code found a date or number, the model must be at least 90% sure it is not a filter before it is ignored; otherwise the user is asked. If the model says an enum or boolean field is not mentioned but gives some value a probability of 0.15 or more, the user is asked too.

execute(filters, options?)

execute(filters: unknown, options?: { context?: Ctx }): Promise<ExecuteResult<F, R>>

Accepts filters from prepare, from an answered clarification, or from manual edits in your UI, and treats all of them as untrusted. In order, it:

1. throws Error("createNaturalFilter: no executor configured") when there is no executor;
2. validates with validateFilters and returns { status: "invalid", errors } on failure;
3. returns invalid with ["no filters"] for an empty object, unless allowEmptyFilters is set;
4. runs authorize(context) and returns { status: "blocked", reason: "unauthorized" } on denial, so a permission revoked after the preview blocks the search;
5. calls verify(id, context) for the entity field if you gave one, returning invalid with ["<field>: not found"] when it does not return true;
6. calls your executor with the validated copy and returns { status: "ok", filters, results }.

execute never calls a model, so manual filter edits add no tokens and no model latency.

validate(filters)

validate(filters: unknown): ValidationResult<F>

Strict validation only, against this search's schema. The same as validateFilters(schema, filters).

NaturalFilterResult

type NaturalFilterResult<F extends Fields = Fields> =
  | { status: "ready"; filters: Filters<F>; interpretation: FilterChip[]; meta: ResultMeta }
  | {
      status: "needs_clarification";
      filters: Filters<F>;            // understood so far; not executable yet
      interpretation: FilterChip[];
      questions: Clarification<F>[];
      meta: ResultMeta;
    }
  | { status: "unsupported"; reason: UnsupportedReason; message: string; field?: string; meta?: ResultMeta }
  | { status: "blocked"; reason: "unauthorized" | "empty_input" | "input_too_long"; message: string }
  | {
      status: "unavailable";
      reason: "provider_error" | "timeout" | "invalid_provider_output" | "resolver_error";
      retryable: boolean;
      message: string;
    };

type UnsupportedReason =
  | "no_filters" | "out_of_scope" | "multiple_values"
  | "contradictory" | "unit_mismatch" | "too_complex";

Reason codes

Clarification

interface Clarification<F extends Fields = Fields> {
  kind: "choose_value" | "choose_entity" | "choose_field" | "no_match" | "ambiguous_date";
  field?: string;
  question: string;                    // suggested text to show
  phrase?: string;                     // the part of the request that needs clarifying
  options: ClarificationOption<F>[];   // empty for no_match and ambiguous_date
}

interface ClarificationOption<F extends Fields = Fields> {
  value: string;        // enum value, entity id, or field name, depending on kind
  label: string;
  filters: Filters<F>;  // merge into result.filters when picked
}

Answering a question

When the user picks an option, merge its filters into result.filters and call execute. With several questions, merge the chosen option of each. For no_match and ambiguous_date there is nothing to pick: ask the user to rephrase, or open your manual filters.

if (result.status === "needs_clarification") {
  const q = result.questions[0];
  const picked = q.options.find((o) => o.value === userChoice);
  const filters = { ...result.filters, ...picked.filters };
  const page = await search.execute(filters, { context: session });
}

The "Any" and "Don't filter by this" options add nothing. If nothing else was understood, the merged object is empty and execute returns invalid unless allowEmptyFilters is set.

FilterChip

interface FilterChip {
  field: string;
  text: string;     // human-readable
  source?: string;  // the part of the request it came from, when there is one
}

Chip text uses the field's label, or its key:

• enum: priority is high, status is not closed
• boolean: escalated: yes
• date: created from 2026-09-14 to before 2026-09-21, created on or after 2026-09-01, created before 2026-09-22
• number: amount < 500 USD, with =, >, ≥, <, ≤ joined by "and"
• entity: customer is Sam Wilson (the candidate's label)

Date, number and entity chips carry source.

ResultMeta

interface ResultMeta {
  schemaVersion: string;
  provider: string;
  model?: string;
  usage?: { inputTokens: number; outputTokens?: number };
  cached?: boolean;
}

ready and needs_clarification always carry meta. unsupported carries it except for too_complex. blocked and unavailable never do.

ExecuteResult

type ExecuteResult<F extends Fields, R> =
  | { status: "ok"; filters: Filters<F>; results: R }
  | { status: "invalid"; errors: string[] }
  | { status: "blocked"; reason: "unauthorized"; message: string };

ok with an empty result set is still ok. The filters are never broadened to find something.

validateFilters(schema, input)

function validateFilters<F extends Fields>(
  schema: SearchSchema<F>,
  input: unknown,
): ValidationResult<F>

type ValidationResult<F extends Fields> =
  | { ok: true; filters: Filters<F> }
  | { ok: false; errors: string[] };

On success, filters is a fresh copy that holds only validated keys. It rejects:

All errors are collected, not just the first. Validation does not check that an entity id exists; that is what verify is for.

parseDates(text, opts)

function parseDates(
  text: string,
  opts: { now: Date; timeZone: string; weekStartsOn?: number },   // weekStartsOn default 1
): DateCandidate[]

interface Span { start: number; end: number; text: string }
interface DateCandidate extends Span {
  range?: DateRange;   // undefined when the phrase is ambiguous (03/04/2026)
}

parseDates("tickets from last week", { now: new Date("2026-09-23T10:00:00Z"), timeZone: "UTC" })
// [{ start: 8, end: 22, text: "from last week", range: { gte: "2026-09-14", lt: "2026-09-21" } }]

text is the exact source text, including the preposition.

parseNumbers(text, exclude?)

function parseNumbers(text: string, exclude?: Span[]): NumberCandidate[]

interface NumberCandidate extends Span {
  range: NumberRange;
  unit?: string;   // upper-case currency code when the text named one
}

const text = "since 2026-09-01 under $50";
parseNumbers(text, parseDates(text, { now, timeZone: "UTC" }))
// [{ start: 17, end: 26, text: "under $50", range: { lt: 50 }, unit: "USD" }]

Numbers that overlap an exclude span are skipped. Pass the date candidates so the digits of a date are not read as numbers.

todayIn(now, timeZone)

function todayIn(now: Date, timeZone: string): string   // "YYYY-MM-DD"

todayIn(new Date("2026-09-23T20:00:00Z"), "Asia/Kolkata")   // "2026-09-24"

FilterProvider

interface FilterProvider<Ctx = unknown> {
  readonly name: string;
  readonly model?: string;   // part of the cache key
  choose(request: ProviderRequest, options: ProviderCallOptions<Ctx>): Promise<ProviderResponse>;
}

interface ProviderRequest {
  state: { search_request: string };        // the untrusted user text, kept apart from instructions
  questions: Record<string, ChoiceSpec>;    // question id → question
}

interface ChoiceSpec {
  instructions: string;                     // trusted, compiled from the schema
  options: Record<string, string | null>;   // option label → description
}

interface ProviderCallOptions<Ctx = unknown> {
  context: Ctx;          // trusted server context; never send it to a model
  signal: AbortSignal;   // aborts at the prepare() deadline or with the caller's signal
}

interface ProviderResponse {
  answers: Record<string, ProviderAnswer>;
  model?: string;
  usage?: { inputTokens: number; outputTokens?: number };
  cached?: boolean;
}

interface ProviderAnswer {
  choice: string;                          // must be one of the question's option labels
  probabilities: Record<string, number>;   // label → 0..1; include at least the chosen label
}

The contract:

• Answer every question id with one of its option labels. A missing answer or an unknown label makes the whole result unavailable with reason invalid_provider_output. Extra answers are ignored.
• Report a probability for at least the chosen label. When it is missing, or not a number from 0 to 1, core treats the answer as unknown confidence (0). Answers other than "not mentioned" then become clarification questions instead of being accepted.
• Set model on the provider so a model upgrade changes the cache key.
• Throw ProviderError to say whether a retry could help.

import type { FilterProvider } from "jevfilter";

const myProvider: FilterProvider = {
  name: "my-llm",
  model: "my-llm-2026-09",
  async choose({ state, questions }, { signal }) {
    // questions: { [id]: { instructions, options: { [label]: description } } }
    return { answers: { /* [id]: { choice: label, probabilities: { [label]: p } } */ } };
  },
};

Question ids and option labels

Ids are stable, so tests and custom providers can rely on them.

ProviderError

class ProviderError extends Error {
  readonly retryable: boolean;
  constructor(message: string, options: { retryable: boolean; cause?: unknown });
}

Its name is "ProviderError". prepare copies retryable into the unavailable result. Any other error counts as retryable, and an error named TimeoutError or APITimeoutError becomes reason timeout. The message goes to onError only.

mockProvider(answer, name?)

function mockProvider(
  answer: (q: { id: string; question: ChoiceSpec; text: string }) => MockAnswer | undefined,
  name?: string,   // default "mock"
): FilterProvider<any>

type MockAnswer = string | { choice: string; probability?: number };

An offline provider for tests. Your function answers each question with an option label. undefined picks the first option, and the probability defaults to 1. It makes no network calls and reports no model or usage.

mockProvider(({ id }) => ({ intent: "filter", field_status: 'is "open"' })[id])

keywordProvider()

function keywordProvider(): FilterProvider<any>   // name "keyword-baseline"

A naive keyword baseline built on mockProvider. It is not a language model. Use it to try the library without a key and as the baseline in evals. It matches enum values and short comma-separated synonyms from their descriptions, treats "not", "except", "excluding", "without" or "non" before a value as an exclusion, gives each date and number to the first field of its kind, and picks a capitalized phrase for an entity. Words such as "ignore", "tenant", "admin", "delete", "permission", "count" or "how many" make it answer other to the intent question.

jev(options?)

import { jev, DEFAULT_JEV_MODEL } from "jevfilter/jev";

function jev<Ctx = unknown>(options?: JevOptions<Ctx>): FilterProvider<Ctx>   // name "jev"

Needs the @typesafe-ai/sdk peer dependency. JevFilter never ships a key or sends requests through a key of its own.

JevOptions

jev()                                                  // TYPESAFE_API_KEY from the environment
jev({ apiKey: process.env.JEV_API_KEY })               // one key for your app
jev({ apiKey: (session) => session.workspace.jevKey }) // each customer brings their own key
jev({ client: new TypeSafeClient({ /* … */ }) })       // full control

Clients built by jev() have SDK logging turned off, because request bodies contain the user's search text. Errors are mapped like this:

• SDK timeout: reason timeout, retryable.
• Rate limit, connection error or HTTP 500 and above: provider_error, retryable.
• Other API errors, such as HTTP 401: provider_error, not retryable.
• No key configured: provider_error, not retryable.

Messages passed to onError are sanitized (for example Jev request failed (HTTP 401)) and never contain keys, headers or request bodies.

DEFAULT_JEV_MODEL

const DEFAULT_JEV_MODEL = "jev-1.13.0";

The pinned default model. Upgrading it changes interpretations, so rerun your evals before you do.

withCache(provider, options)

function withCache<Ctx>(provider: FilterProvider<Ctx>, options: CacheOptions<Ctx>): FilterProvider<Ctx>

type CacheOptions<Ctx> = {
  store: CacheStore;
  ttlMs?: number;
  storeTimeoutMs?: number;
} & (
  | { scope: (context: Ctx) => string; shared?: never }
  | { shared: true; scope?: never }
);

Only the provider's answers are cached. authorize, answer validation, entity resolution and your executor run on every search, and dates such as "last week" are recomputed from today, so a hit cannot skip security or go stale on the calendar. The wrapped provider keeps the inner provider's name and model.

The key is a SHA-256 hash of the provider's name and model, the scope (or shared), the search text, and the questions compiled from your schema. Editing a field's description or values changes the questions, so it misses the cache.

Failure rules:

• Building throws a TypeError without a store that has get and set, without scope or shared: true, or when ttlMs or storeTimeoutMs is not a finite number of at least 1.
• If scope(context) returns anything but a non-empty string, the search fails (unavailable, provider_error) instead of sharing a cache.
• A store read that throws, or takes longer than storeTimeoutMs, counts as a miss. Writes run in the background, and a failing write is ignored.
• Only complete responses are stored, with a valid option for every question. Errors and invalid answers are never cached. What is stored is the answers and the model.
• Identical concurrent searches share one provider call. If that call fails, is abandoned or returns an incomplete answer, a waiting caller makes the call itself instead of inheriting the failure. After 3 such rounds it calls the provider directly.
• A hit returns cached: true and zero usage, which reaches you as meta.cached.

With per-tenant keys, a cached answer inside one scope can be served to a user whose search would have been paid with a different key. If each tenant brings its own key, scope by tenant.

import { memoryCache, withCache } from "jevfilter";
import { jev } from "jevfilter/jev";

const provider = withCache(jev(), {
  store: memoryCache({ maxEntries: 1000 }),
  scope: (session) => session.tenantId,
  ttlMs: 10 * 60_000,
});

memoryCache(options?)

function memoryCache(options?: { maxEntries?: number; ttlMs?: number }): CacheStore

An in-process LRU cache, good for a single server or a Worker isolate. Reads and writes copy the value with structuredClone, so a caller that mutates an answer cannot change the cache. A write with a TTL of zero, a negative TTL or NaN is not stored. Invalid options throw a TypeError.

CacheStore

interface CacheStore {
  get(key: string): Promise<ProviderResponse | undefined> | ProviderResponse | undefined;
  set(key: string, value: ProviderResponse, ttlMs: number): Promise<void> | void;
}

Keys are 64-character hex strings. Return undefined for a miss.