@with-logic/intent 0.1.0 → 0.1.1

package/dist/index.mjs

@@ -0,0 +1,1102 @@
+// src/batches.ts
+function sliceIntoFixedBatches(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+function mergeTinyFinalBatch(batches, tinyThreshold) {
+  if (batches.length < 2) return batches;
+  const last = batches[batches.length - 1];
+  if (last.length === 0 || last.length > tinyThreshold) return batches;
+  const prev = batches[batches.length - 2];
+  batches[batches.length - 2] = prev.concat(last);
+  batches.pop();
+  return batches;
+}
+function createBatches(items, size, tinyFraction) {
+  const batches = sliceIntoFixedBatches(items, size);
+  const tinyThreshold = Math.ceil(tinyFraction * size);
+  return mergeTinyFinalBatch(batches, tinyThreshold);
+}
+async function batchProcess(items, size, tinyFraction, fn, logger, onError) {
+  const batches = createBatches(items, size, tinyFraction);
+  const results = await Promise.all(
+    batches.map(async (b) => {
+      try {
+        return await fn(b);
+      } catch (error) {
+        logger?.warn?.("intent reranker batch failed, preserving original order", {
+          error: error?.message
+        });
+        if (onError) {
+          return onError(b, error);
+        }
+        return b;
+      }
+    })
+  );
+  return results.flat();
+}
+
+// src/config.ts
+import "dotenv/config";
+
+// src/lib/number.ts
+function clamp(n, min, max) {
+  let out = n;
+  if (typeof min === "number" && out < min) {
+    out = min;
+  }
+  if (typeof max === "number" && out > max) {
+    out = max;
+  }
+  return out;
+}
+
+// src/lib/config.ts
+function throwRequiredEnvVar(name) {
+  throw new Error(`${name} is required.`);
+}
+function string(name, opts) {
+  const value = process.env[name];
+  const exists = value != null && value.length > 0;
+  if (exists) {
+    return value;
+  }
+  if (opts?.default !== void 0) {
+    return opts.default;
+  }
+  return throwRequiredEnvVar(name);
+}
+function enumeration(name, opts) {
+  const value = opts.default !== void 0 ? string(name, { default: opts.default }) : string(name);
+  if (opts.values.includes(value)) {
+    return value;
+  }
+  throw new Error(`${name} must be one of: ${opts.values.join(", ")}`);
+}
+function int(name, opts) {
+  const value = process.env[name];
+  const exists = value != null && value.length > 0;
+  if (exists) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed)) {
+      throw new Error(`${name} must be a valid integer`);
+    }
+    return clamp(parsed, opts?.min, opts?.max);
+  }
+  if (opts?.default !== void 0) {
+    const def = Math.trunc(opts.default);
+    return clamp(def, opts?.min, opts?.max);
+  }
+  return throwRequiredEnvVar(name);
+}
+function number(name, opts) {
+  const value = process.env[name];
+  const exists = value != null && value.length > 0;
+  if (exists) {
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed)) {
+      throw new Error(`${name} must be a valid number`);
+    }
+    return clamp(parsed, opts?.min, opts?.max);
+  }
+  if (opts?.default !== void 0) {
+    return clamp(opts.default, opts?.min, opts?.max);
+  }
+  return throwRequiredEnvVar(name);
+}
+
+// src/config.ts
+var CONFIG = {
+  GROQ: {
+    API_KEY: string("GROQ_API_KEY", { default: "" }),
+    DEFAULT_MODEL: string("GROQ_DEFAULT_MODEL", { default: "openai/gpt-oss-20b" }),
+    DEFAULT_REASONING_EFFORT: enumeration("GROQ_DEFAULT_REASONING_EFFORT", {
+      default: "medium",
+      values: ["low", "medium", "high"]
+    }),
+    JSON_REPAIR_ATTEMPTS: int("GROQ_JSON_REPAIR_ATTEMPTS", { default: 3, min: 0 })
+  },
+  INTENT: {
+    PROVIDER: enumeration("INTENT_PROVIDER", { default: "GROQ", values: ["GROQ"] }),
+    TIMEOUT_MS: int("INTENT_TIMEOUT_MS", { default: 3e3, min: 1 }),
+    MIN_SCORE: int("INTENT_MIN_SCORE", { default: 0 }),
+    MAX_SCORE: int("INTENT_MAX_SCORE", { default: 10, min: 1 }),
+    RELEVANCY_THRESHOLD: int("INTENT_RELEVANCY_THRESHOLD", { default: 0 }),
+    BATCH_SIZE: int("INTENT_BATCH_SIZE", { default: 20, min: 1 }),
+    TINY_BATCH_FRACTION: number("INTENT_TINY_BATCH_FRACTION", { default: 0.2, min: 0, max: 1 })
+  },
+  TEST: {
+    SCOPE: string("TEST_SCOPE", { default: "all" })
+  }
+};
+
+// src/extractors.ts
+function hash32(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) + hash + char | 0;
+  }
+  return hash >>> 0;
+}
+function jsonStringify(value) {
+  try {
+    const result = JSON.stringify(value, null, 2);
+    if (result === void 0) {
+      return String(value);
+    }
+    return result;
+  } catch {
+    return String(value);
+  }
+}
+function hashToString(value) {
+  const json = jsonStringify(value);
+  const hashValue = hash32(json);
+  return String(hashValue);
+}
+function DEFAULT_KEY_EXTRACTOR(item) {
+  return hashToString(item);
+}
+function DEFAULT_SUMMARY_EXTRACTOR(item) {
+  return jsonStringify(item);
+}
+
+// src/providers/groq.ts
+import Groq from "groq-sdk";
+function getNestedErrorObject(err) {
+  if (err == null || typeof err !== "object") {
+    return void 0;
+  }
+  const record = err;
+  const error = record.error;
+  if (error == null || typeof error !== "object") {
+    return void 0;
+  }
+  return error;
+}
+function mapToGroqMessages(messages) {
+  return messages.map((m) => {
+    if (m.role === "system" || m.role === "user" || m.role === "assistant") {
+      return { role: m.role, content: m.content };
+    }
+    throw new Error(`intent: '${m.role}' role messages are not supported in provider calls`);
+  });
+}
+function buildGroqRequest(outputSchema, groqMessages, config, userId, defaults) {
+  return {
+    model: config?.model ?? defaults.model,
+    reasoning_effort: config?.reasoningEffort ?? defaults.reasoningEffort,
+    messages: groqMessages,
+    ...userId ? { user: userId } : {},
+    response_format: {
+      type: "json_schema",
+      json_schema: {
+        name: "intent_relevancy",
+        schema: outputSchema,
+        strict: true
+      }
+    }
+  };
+}
+async function executeCompletion(client, request, timeoutMs) {
+  const timeout = typeof timeoutMs === "number" ? { timeout: timeoutMs } : void 0;
+  return client.chat.completions.create(request, timeout);
+}
+function getResponseContent(response) {
+  const content = response?.choices?.[0]?.message?.content;
+  if (typeof content !== "string") {
+    throw new Error("Groq did not return content");
+  }
+  return content;
+}
+function parseJson(content) {
+  try {
+    const data = JSON.parse(content);
+    return { data };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const err = new Error(`Groq returned invalid JSON: ${detail}`);
+    err.rawOutput = content;
+    throw err;
+  }
+}
+function buildJsonRepairMessages(baseMessages, rawOutput, errorMessage) {
+  return [
+    ...baseMessages,
+    { role: "assistant", content: rawOutput },
+    {
+      role: "user",
+      content: `Your previous response was invalid JSON or did not match the required JSON schema. Please correct it and return ONLY valid JSON that matches the schema.
+
+Error: ${errorMessage}`
+    }
+  ];
+}
+function buildRepairRetry(state, repair) {
+  if (state.remaining <= 1) {
+    return void 0;
+  }
+  const repairedRequest = {
+    ...state.request,
+    messages: buildJsonRepairMessages(
+      state.request.messages,
+      repair.rawOutput,
+      repair.errorMessage
+    )
+  };
+  return { remaining: state.remaining - 1, request: repairedRequest };
+}
+function parseErrorToRepairInput(rawOutput, parseError) {
+  return { rawOutput, errorMessage: String(parseError) };
+}
+function getRawOutputFromParseJsonError(error) {
+  if (!(error instanceof Error)) {
+    return void 0;
+  }
+  const record = error;
+  return typeof record.rawOutput === "string" ? record.rawOutput : void 0;
+}
+function extractJsonValidateFailedRepairInput(err) {
+  if (err instanceof Error) {
+    const match = err.message.match(/"failed_generation":"(\{.*?\})"/);
+    const failedGeneration2 = match?.[1] ? match[1].replace(/\\"/g, '"') : void 0;
+    if (err.message.includes('"code":"json_validate_failed"')) {
+      return {
+        rawOutput: failedGeneration2 ?? "(Groq did not include the rejected generation in the error payload)",
+        errorMessage: err.message
+      };
+    }
+  }
+  const errorObj = getNestedErrorObject(err);
+  const nested = errorObj && typeof errorObj.error === "object" ? errorObj.error : void 0;
+  const serverError = nested ?? errorObj;
+  if (!serverError) {
+    return void 0;
+  }
+  const code = typeof serverError.code === "string" ? serverError.code : void 0;
+  if (code !== "json_validate_failed") {
+    return void 0;
+  }
+  const message = typeof serverError.message === "string" ? serverError.message : void 0;
+  const generatedResponse = typeof serverError.generated_response === "string" ? serverError.generated_response : void 0;
+  const failedGeneration = typeof serverError.failed_generation === "string" ? serverError.failed_generation : void 0;
+  const rawOutput = generatedResponse ?? failedGeneration;
+  return {
+    rawOutput: rawOutput ?? "(Groq did not include the rejected generation in the error payload)",
+    errorMessage: message ?? String(err)
+  };
+}
+function createGroqSdkLike(apiKey) {
+  const sdk = new Groq({ apiKey });
+  return {
+    chat: {
+      completions: {
+        create: async (req, opts) => {
+          return await sdk.chat.completions.create(
+            req,
+            opts
+          );
+        }
+      }
+    }
+  };
+}
+function createDefaultGroqClient(apiKey, options) {
+  const defaults = {
+    model: options?.defaults?.model ?? CONFIG.GROQ.DEFAULT_MODEL,
+    reasoningEffort: options?.defaults?.reasoningEffort ?? CONFIG.GROQ.DEFAULT_REASONING_EFFORT
+  };
+  const makeSdk = options?.makeSdk ?? createGroqSdkLike;
+  const jsonRepairAttempts = options?.jsonRepairAttempts ?? CONFIG.GROQ.JSON_REPAIR_ATTEMPTS;
+  return {
+    /**
+     * Call Groq with JSON schema enforced response and return parsed data.
+     *
+     * Implements the LlmClient interface with Groq-specific features:
+     * - Creates a new SDK client per call with the provided API key
+     * - Maps generic messages to Groq format
+     * - Builds request with strict JSON schema response format
+     * - Retries up to 3 times on json_validate_failed errors
+     * - Parses and returns the structured response
+     *
+     * @param messages - Chat messages to send to the model
+     * @param outputSchema - JSON schema defining expected response structure
+     * @param config - Optional model, reasoning effort, and timeout overrides
+     * @param userId - Optional user ID for Groq's abuse monitoring
+     * @returns Parsed response data wrapped in { data } object
+     * @throws {Error} If all retry attempts fail or response is invalid
+     */
+    async call(messages, outputSchema, config, userId) {
+      const client = makeSdk(apiKey);
+      const groqMessages = mapToGroqMessages(messages);
+      const baseRequest = buildGroqRequest(outputSchema, groqMessages, config, userId, defaults);
+      const createWithRetry = async (state) => {
+        try {
+          const response = await executeCompletion(client, state.request, config?.timeoutMs);
+          const content = getResponseContent(response);
+          const parsed = parseJson(content);
+          return parsed;
+        } catch (err) {
+          const parseRawOutput = getRawOutputFromParseJsonError(err);
+          if (parseRawOutput !== void 0) {
+            const retry = buildRepairRetry(state, parseErrorToRepairInput(parseRawOutput, err));
+            if (retry) {
+              return createWithRetry(retry);
+            }
+            throw err;
+          }
+          const validationRepairInput = extractJsonValidateFailedRepairInput(err);
+          if (validationRepairInput) {
+            const retry = buildRepairRetry(state, validationRepairInput);
+            if (retry) {
+              return createWithRetry(retry);
+            }
+          }
+          throw err;
+        }
+      };
+      const attempts = Math.max(1, jsonRepairAttempts);
+      return createWithRetry({ remaining: attempts, request: baseRequest });
+    }
+  };
+}
+
+// src/llm_client.ts
+function selectLlmClient(ctx, config = CONFIG) {
+  if (ctx.llm) {
+    return ctx.llm;
+  }
+  const groqKey = config.GROQ.API_KEY;
+  if (groqKey && groqKey !== "") {
+    return createDefaultGroqClient(groqKey, {
+      defaults: {
+        model: config.GROQ.DEFAULT_MODEL,
+        reasoningEffort: config.GROQ.DEFAULT_REASONING_EFFORT
+      }
+    });
+  }
+  return void 0;
+}
+
+// src/messages.ts
+function buildMessages(query, candidates, scoreRange) {
+  const system = `You will receive a JSON blob containing candidate_search_results (each candidate has a key and a short summary) plus a short user request.
+
+Your task is to assess each candidate and return a JSON object that maps candidate keys to objects of the form {"explanation": string, "score": integer} avoiding ambiguity.
+
+The score must be an integer from ${scoreRange.minScore} to ${scoreRange.maxScore}:
+- ${scoreRange.minScore} means not relevant at all
+- ${scoreRange.maxScore} means highly relevant
+
+Sometimes none are relevant, sometimes all are relevant. Be decisive.
+
+It is okay to return ${scoreRange.minScore} if the candidate is not relevant to the query. It is okay to return ${scoreRange.maxScore} if the candidate is highly relevant to the query. Use the full range of scores.
+
+Every candidate MUST include an explanation. Write the explanation first, then the score. The explanation should be concise (1-3 sentences), concrete, and reference the query intent and the candidate summary.
+
+Write explanations as end-user-facing justifications:
+- Do NOT say "the query" or talk about prompt mechanics.
+- Write in a direct, item-first voice (e.g., "gpt-5.2 is best here because it specializes in feature implementation and testing.").
+- Avoid "I"/"we".
+
+Every key in candidate_search_results must be present in your output mapping. Do not add any keys that are not present in candidate_search_results.
+Every key in candidate_search_results must map to an object with:
+- explanation: string
+- score: integer from ${scoreRange.minScore} to ${scoreRange.maxScore}
+Do not, in your generated JSON, include anything other than the \`"{key}": {"explanation": "...", "score": 7}\` mappings. Do not include any other text outside the JSON.
+
+Return a JSON object that matches the enforced JSON schema for response formatting. Use the candidate.key as the property name in the output mapping.
+
+The JSON you return should be of the form: {
+    "Key for document 1": { "explanation": "...", "score": ${scoreRange.minScore} },
+    "Key for document 2": { "explanation": "...", "score": ${scoreRange.maxScore} },
+    ...
+}
+
+Pretty-print the JSON for readability.`;
+  const payload = {
+    query,
+    candidate_search_results: candidates.map((c) => ({ key: c.key, summary: c.summary }))
+  };
+  return [
+    { role: "system", content: system },
+    { role: "user", content: jsonStringify(payload) }
+  ];
+}
+function buildFilterMessages(query, candidates) {
+  const system = `You will receive a JSON blob containing candidate_search_results (each candidate has a key and a short summary) plus a short user request.
+
+Your task is to assess each candidate and return a JSON object that maps candidate keys to objects of the form {"explanation": string, "isRelevant": boolean}.
+
+Return isRelevant=true only when the candidate clearly helps satisfy the query intent. Otherwise return isRelevant=false.
+
+Every candidate MUST include an explanation. Write the explanation first, then the boolean. The explanation should be concise (1-3 sentences), concrete, and reference the query intent and the candidate summary.
+
+Write explanations as end-user-facing justifications:
+- Do NOT say "the query" or talk about prompt mechanics.
+- Write in a direct, item-first voice.
+- Avoid "I"/"we".
+
+Every key in candidate_search_results must be present in your output mapping. Do not add any keys that are not present in candidate_search_results.
+Every key in candidate_search_results must map to an object with:
+- explanation: string
+- isRelevant: boolean
+Do not include anything other than the mapping JSON object. Return only JSON matching the enforced schema.
+
+Pretty-print the JSON for readability.`;
+  const payload = {
+    query,
+    candidate_search_results: candidates.map((c) => ({ key: c.key, summary: c.summary }))
+  };
+  return [
+    { role: "system", content: system },
+    { role: "user", content: jsonStringify(payload) }
+  ];
+}
+function buildChoiceMessages(query, candidates) {
+  const system = `You will receive a JSON blob containing candidate_search_results (each candidate has a key and a short summary) plus a short user request.
+
+Your task is to choose exactly one candidate as the best match for what the user wants.
+
+You MUST choose one candidate key from the provided list. Do not choose multiple.
+
+Return ONLY JSON of the form: {"explanation": string, "selectedKey": string} where selectedKey is exactly one of the candidate keys. The explanation should be concise (1-3 sentences), concrete, and reference the query intent and the candidate summary.
+
+Write the explanation as an end-user-facing justification:
+- Do NOT say "the query" or talk about prompt mechanics.
+- Write in a direct, item-first voice.
+- Avoid "I"/"we".
+
+Do not include any other text outside the JSON. Return only JSON matching the enforced schema.
+
+Pretty-print the JSON for readability.`;
+  const payload = {
+    query,
+    candidate_search_results: candidates.map((c) => ({ key: c.key, summary: c.summary }))
+  };
+  return [
+    { role: "system", content: system },
+    { role: "user", content: jsonStringify(payload) }
+  ];
+}
+
+// src/schema.ts
+function buildCandidateEvaluationSchema() {
+  return {
+    type: "object",
+    properties: {
+      explanation: { type: "string" },
+      score: { type: "integer" }
+    },
+    required: ["explanation", "score"],
+    additionalProperties: false
+  };
+}
+function buildCandidateFilterSchema() {
+  return {
+    type: "object",
+    properties: {
+      explanation: { type: "string" },
+      isRelevant: { type: "boolean" }
+    },
+    required: ["explanation", "isRelevant"],
+    additionalProperties: false
+  };
+}
+function buildRelevancySchema(keys, minScore, maxScore) {
+  const evaluationSchema = buildCandidateEvaluationSchema();
+  const properties = {};
+  for (const k of keys) {
+    properties[k] = evaluationSchema;
+  }
+  return {
+    title: "Query / Candidate Relevancy Assessment",
+    description: `Map candidate results for a search query to relevancy scores (${minScore}-${maxScore}) with explanations.`,
+    type: "object",
+    properties,
+    required: keys,
+    additionalProperties: false
+  };
+}
+function buildFilterSchema(keys) {
+  const decisionSchema = buildCandidateFilterSchema();
+  const properties = {};
+  for (const k of keys) {
+    properties[k] = decisionSchema;
+  }
+  return {
+    title: "Query / Candidate Relevancy Filter",
+    description: "Map candidate results for a search query to boolean relevancy decisions with explanations.",
+    type: "object",
+    properties,
+    required: keys,
+    additionalProperties: false
+  };
+}
+function buildChoiceSchema(keys) {
+  return {
+    title: "Query / Candidate Single Choice",
+    description: "Choose exactly one candidate key for the query and explain why.",
+    type: "object",
+    properties: {
+      explanation: { type: "string" },
+      selectedKey: { type: "string", enum: keys }
+    },
+    required: ["explanation", "selectedKey"],
+    additionalProperties: false
+  };
+}
+
+// src/intent.ts
+var Intent = class {
+  /**
+   * Resolve the model name to use for this Intent instance.
+   *
+   * Intent is provider-driven. Today only GROQ is supported; when using GROQ
+   * we always take the model from GROQ's config defaults.
+   *
+   * @returns Provider-specific model name
+   * @private
+   */
+  resolveModel() {
+    return this.env.GROQ.DEFAULT_MODEL;
+  }
+  /**
+   * Builds the context object from options.
+   *
+   * Constructs an IntentContext with only defined properties to satisfy
+   * TypeScript's exactOptionalPropertyTypes requirement.
+   *
+   * @param options - The options object containing llm, logger, and userId
+   * @returns IntentContext with only defined properties
+   * @private
+   */
+  buildContext(options) {
+    return {
+      ...options.llm !== void 0 && { llm: options.llm },
+      ...options.logger !== void 0 && { logger: options.logger },
+      ...options.userId !== void 0 && { userId: options.userId }
+    };
+  }
+  /**
+   * Builds the extractors object from options.
+   *
+   * Uses provided extractors or falls back to generic defaults that work
+   * for any type T via JSON stringification and hashing.
+   *
+   * @param options - The options object containing key and summary extractors
+   * @returns Required extractors with defaults applied
+   * @private
+   */
+  buildExtractors(options) {
+    return {
+      key: options.key ?? DEFAULT_KEY_EXTRACTOR,
+      summary: options.summary ?? DEFAULT_SUMMARY_EXTRACTOR
+    };
+  }
+  /**
+   * Builds the configuration object from options.
+   *
+   * Merges user-provided options with environment-based CONFIG defaults.
+   *
+   * @param options - The options object containing config overrides
+   * @returns Required config with all values populated
+   * @private
+   */
+  buildConfig(options) {
+    return {
+      provider: options.provider ?? this.env.INTENT.PROVIDER,
+      timeoutMs: options.timeoutMs ?? this.env.INTENT.TIMEOUT_MS,
+      relevancyThreshold: options.relevancyThreshold ?? this.env.INTENT.RELEVANCY_THRESHOLD,
+      batchSize: options.batchSize ?? this.env.INTENT.BATCH_SIZE,
+      tinyBatchFraction: options.tinyBatchFraction ?? this.env.INTENT.TINY_BATCH_FRACTION,
+      minScore: options.minScore ?? this.env.INTENT.MIN_SCORE,
+      maxScore: options.maxScore ?? this.env.INTENT.MAX_SCORE
+    };
+  }
+  /**
+   * Validates the configuration values.
+   *
+   * Ensures the configured score range is valid and the relevancyThreshold is in range.
+   *
+   * @throws {Error} If maxScore is below minScore
+   * @throws {Error} If relevancyThreshold is not within [minScore, maxScore]
+   * @private
+   */
+  validateConfig() {
+    if (this.cfg.maxScore < this.cfg.minScore) {
+      throw new Error(
+        `intent: maxScore must be >= minScore, got minScore=${this.cfg.minScore} maxScore=${this.cfg.maxScore}`
+      );
+    }
+    if (this.cfg.relevancyThreshold < this.cfg.minScore || this.cfg.relevancyThreshold > this.cfg.maxScore) {
+      throw new Error(
+        `intent: relevancyThreshold must be between ${this.cfg.minScore} and ${this.cfg.maxScore}, got ${this.cfg.relevancyThreshold}`
+      );
+    }
+  }
+  /**
+   * Selects and validates the LLM client.
+   *
+   * Uses the provided client from context or attempts to create a default
+   * Groq client if GROQ_API_KEY is available.
+   *
+   * @returns The selected LLM client
+   * @throws {Error} If no LLM client is provided and GROQ_API_KEY is not set
+   * @private
+   */
+  selectAndValidateLlmClient() {
+    const selectedClient = selectLlmClient(this.ctx, this.env);
+    if (!selectedClient) {
+      throw new Error(
+        "intent: No LLM client provided and GROQ_API_KEY not set. Provide options.llm or set GROQ_API_KEY."
+      );
+    }
+    return selectedClient;
+  }
+  /**
+   * Creates a new Intent instance.
+   *
+   * All options are optional with sensible defaults:
+   * - llm: Auto-detected from GROQ_API_KEY environment variable if available
+   * - key: Hash-based string from JSON representation of items
+   * - summary: Pretty-printed JSON of items (2-space indentation for LLM readability)
+   * - Config values: From INTENT_* environment variables or built-in defaults
+   *
+   * @param options - Optional configuration object
+   * @param options.llm - Optional LLM client. If omitted, uses Groq client when GROQ_API_KEY is set
+   * @param options.logger - Optional logger for warnings and errors
+   * @param options.userId - Optional user identifier for LLM provider abuse monitoring
+   * @param options.key - Optional function extracting a short human-readable key from items
+   * @param options.summary - Optional function extracting a short description for LLM reasoning
+   * @param options.provider - Optional provider override (default: INTENT_PROVIDER or "GROQ")
+   * @param options.timeoutMs - Optional timeout in milliseconds (default: INTENT_TIMEOUT_MS or 3000)
+   * @param options.relevancyThreshold - Optional minimum score to include results (default: INTENT_RELEVANCY_THRESHOLD)
+   * @param options.minScore - Optional minimum score value (default: INTENT_MIN_SCORE or 0)
+   * @param options.maxScore - Optional maximum score value (default: INTENT_MAX_SCORE or 10)
+   * @param options.batchSize - Optional number of candidates per LLM call (default: INTENT_BATCH_SIZE or 20)
+   * @param options.tinyBatchFraction - Optional threshold for merging small batches (default: INTENT_TINY_BATCH_FRACTION or 0.2)
+   * @throws {Error} If no LLM client is provided and GROQ_API_KEY is not set
+   * @throws {Error} If maxScore is below minScore
+   * @throws {Error} If relevancyThreshold is not within [minScore, maxScore]
+   *
+   * @example
+   * ```typescript
+   * // Minimal - uses all defaults
+   * const intent = new Intent();
+   *
+   * // With extractors
+   * const intent = new Intent<Doc>({
+   *   key: doc => doc.title,
+   *   summary: doc => doc.content
+   * });
+   *
+   * // Full configuration
+   * const intent = new Intent<Doc>({
+   *   llm: myClient,
+   *   userId: "org-123",
+   *   key: doc => doc.title,
+   *   summary: doc => doc.content,
+   *   relevancyThreshold: 5,
+   *   batchSize: 20
+   * });
+   * ```
+   */
+  constructor(options = {}) {
+    this.env = options.config ?? CONFIG;
+    this.ctx = this.buildContext(options);
+    this.extractors = this.buildExtractors(options);
+    this.cfg = this.buildConfig(options);
+    this.validateConfig();
+    this.llm = this.selectAndValidateLlmClient();
+  }
+  async rank(query, candidates, options) {
+    try {
+      if (candidates.length === 0) {
+        return [];
+      }
+      if (candidates.length === 1) {
+        if (options?.explain) {
+          const [firstCandidate] = candidates;
+          return [{ item: firstCandidate, explanation: "" }];
+        }
+        return candidates;
+      }
+      const prepared = this.prepareCandidates(candidates);
+      const rankedWithExplanations = await batchProcess(
+        prepared,
+        this.cfg.batchSize,
+        this.cfg.tinyBatchFraction,
+        async (batch) => await this.processBatch(
+          query,
+          batch,
+          options?.userId !== void 0 ? { userId: options.userId } : void 0
+        ),
+        this.ctx.logger,
+        (batch) => batch.map(({ item }) => ({ item, explanation: "" }))
+      );
+      if (options?.explain) {
+        return rankedWithExplanations;
+      }
+      return rankedWithExplanations.map(({ item }) => item);
+    } catch (error) {
+      this.ctx.logger?.warn?.("intent reranker failed, using fallback", {
+        error: error?.message
+      });
+      if (options?.explain) {
+        return candidates.map((item) => ({ item, explanation: "" }));
+      }
+      return candidates;
+    }
+  }
+  async filter(query, candidates, options) {
+    if (candidates.length === 0) {
+      return [];
+    }
+    if (candidates.length === 1) {
+      if (options?.explain) {
+        const [firstCandidate] = candidates;
+        return [{ item: firstCandidate, explanation: "" }];
+      }
+      return candidates;
+    }
+    const prepared = this.prepareCandidates(candidates);
+    const filteredWithExplanations = await batchProcess(
+      prepared,
+      this.cfg.batchSize,
+      this.cfg.tinyBatchFraction,
+      async (batch) => await this.processFilterBatch(
+        query,
+        batch,
+        options?.userId !== void 0 ? { userId: options.userId } : void 0
+      ),
+      this.ctx.logger,
+      (batch) => batch.map(({ item }) => ({ item, explanation: "" }))
+    );
+    if (options?.explain) {
+      return filteredWithExplanations;
+    }
+    return filteredWithExplanations.map(({ item }) => item);
+  }
+  async choice(query, candidates, options) {
+    if (candidates.length === 0) {
+      throw new Error("intent: choice requires at least one candidate");
+    }
+    if (candidates.length === 1) {
+      const [firstCandidate] = candidates;
+      if (options?.explain) {
+        return { item: firstCandidate, explanation: "" };
+      }
+      return firstCandidate;
+    }
+    const prepared = this.prepareCandidates(candidates);
+    const keyed = this.ensureUniqueKeys(prepared);
+    const winners = await batchProcess(
+      keyed,
+      this.cfg.batchSize,
+      this.cfg.tinyBatchFraction,
+      async (batch) => [await this.processChoiceBatch(query, batch, options?.userId)],
+      this.ctx.logger,
+      (batch) => [{ item: batch[0].item, explanation: "" }]
+    );
+    if (winners.length === 1) {
+      const [onlyWinner] = winners;
+      if (options?.explain) {
+        return onlyWinner;
+      }
+      return onlyWinner.item;
+    }
+    const preparedFinalists = this.prepareCandidates(winners.map((w) => w.item));
+    const keyedFinalists = this.ensureUniqueKeys(preparedFinalists);
+    const final = await this.processChoiceBatch(query, keyedFinalists, options?.userId);
+    if (options?.explain) {
+      return final;
+    }
+    return final.item;
+  }
+  /**
+   * Normalize incoming items into a consistent shape for downstream processing.
+   *
+   * Extracts the key and summary from each item using the configured extractors,
+   * and attaches the original input index for stable sorting later.
+   *
+   * @param candidates - Raw items to prepare
+   * @returns Array of prepared candidates with extracted metadata and original index
+   * @private
+   */
+  prepareCandidates(candidates) {
+    return candidates.map((item, idx) => ({
+      item,
+      idx,
+      baseKey: this.extractors.key(item),
+      summary: this.extractors.summary(item)
+    }));
+  }
+  /**
+   * Ensure keys are unique by suffixing duplicates with their input index.
+   *
+   * When multiple items share the same key, subsequent occurrences are renamed
+   * to "Key (idx)" where idx is the original input index. This prevents JSON
+   * schema validation errors and ensures the LLM can score each item independently.
+   *
+   * @param itemsBase - Prepared candidates with potentially duplicate keys
+   * @returns Candidates with guaranteed unique keys
+   * @private
+   */
+  ensureUniqueKeys(itemsBase) {
+    const counts = /* @__PURE__ */ new Map();
+    return itemsBase.map(({ item, baseKey, summary, idx }) => {
+      const n = (counts.get(baseKey) ?? 0) + 1;
+      counts.set(baseKey, n);
+      const key = n === 1 ? baseKey : `${baseKey} (${idx})`;
+      return { item, idx, key, summary };
+    });
+  }
+  /**
+   * Build the JSON schema and chat messages payload for the LLM.
+   *
+   * Creates a strict JSON schema requiring one integer property (minScore-maxScore) per candidate key,
+   * and constructs system + user messages instructing the LLM to score relevance.
+   *
+   * @param query - The search query to evaluate candidates against
+   * @param items - Candidates with unique keys and summaries
+   * @returns Object containing JSON schema and chat messages array
+   * @private
+   */
+  buildRequest(query, items) {
+    const keys = items.map((x) => x.key);
+    const schema = buildRelevancySchema(keys, this.cfg.minScore, this.cfg.maxScore);
+    const messages = buildMessages(query, items, {
+      minScore: this.cfg.minScore,
+      maxScore: this.cfg.maxScore
+    });
+    return { schema, messages };
+  }
+  /**
+   * Build the JSON schema and chat messages payload for the LLM filter call.
+   *
+   * @param query - The search query to evaluate candidates against
+   * @param items - Candidates with unique keys and summaries
+   * @returns Object containing JSON schema and chat messages array
+   * @private
+   */
+  buildFilterRequest(query, items) {
+    const keys = items.map((x) => x.key);
+    const schema = buildFilterSchema(keys);
+    const messages = buildFilterMessages(query, items);
+    return { schema, messages };
+  }
+  /**
+   * Build the JSON schema and chat messages payload for the LLM choice call.
+   *
+   * @param query - The search query to choose against
+   * @param items - Candidates with unique keys and summaries
+   * @returns Object containing JSON schema and chat messages array
+   * @private
+   */
+  buildChoiceRequest(query, items) {
+    const keys = items.map((x) => x.key);
+    const schema = buildChoiceSchema(keys);
+    const messages = buildChoiceMessages(query, items);
+    return { schema, messages };
+  }
+  /**
+   * Invoke the LLM and return the parsed map of candidate scores.
+   *
+   * Calls the configured LLM client with the messages, JSON schema, model config,
+   * and user ID. Returns null if the response is invalid or missing.
+   *
+   * @param messages - Chat messages (system + user) to send to LLM
+   * @param schema - Strict JSON schema defining expected response structure
+   * @param userId - Optional user identifier for provider abuse monitoring
+   * @returns Map of candidate keys to numeric scores, or null if response invalid
+   * @private
+   */
+  async fetchEvaluations(messages, schema, userId) {
+    const config = {
+      model: this.resolveModel(),
+      reasoningEffort: "medium",
+      timeoutMs: this.cfg.timeoutMs
+    };
+    const { data } = await this.llm.call(
+      messages,
+      schema,
+      config,
+      userId ?? this.ctx.userId
+    );
+    if (data == null || typeof data !== "object") return null;
+    return data;
+  }
+  /**
+   * Invoke the LLM and return boolean relevancy decisions.
+   *
+   * @param messages - Chat messages to send
+   * @param schema - Strict JSON schema defining expected response structure
+   * @param userId - Optional user id
+   * @returns Map of candidate keys to filter decisions, or null if invalid
+   * @private
+   */
+  async fetchFilterDecisions(messages, schema, userId) {
+    const config = {
+      model: this.resolveModel(),
+      reasoningEffort: "medium",
+      timeoutMs: this.cfg.timeoutMs
+    };
+    const { data } = await this.llm.call(messages, schema, config, userId ?? this.ctx.userId);
+    if (data == null || typeof data !== "object") return null;
+    return data;
+  }
+  /**
+   * Invoke the LLM and return a single selected key.
+   *
+   * @param messages - Chat messages to send
+   * @param schema - Strict JSON schema defining expected response structure
+   * @param userId - Optional user id
+   * @returns Choice result, or null if invalid
+   * @private
+   */
+  async fetchChoice(messages, schema, userId) {
+    const config = {
+      model: this.resolveModel(),
+      reasoningEffort: "medium",
+      timeoutMs: this.cfg.timeoutMs
+    };
+    const { data } = await this.llm.call(
+      messages,
+      schema,
+      config,
+      userId ?? this.ctx.userId
+    );
+    if (data == null || typeof data !== "object") return null;
+    const record = data;
+    const explanation = typeof record.explanation === "string" ? record.explanation : "";
+    const selectedKey = typeof record.selectedKey === "string" ? record.selectedKey : "";
+    if (selectedKey === "") return null;
+    return { explanation, selectedKey };
+  }
+  /**
+   * Apply boolean filter decisions while preserving input order.
+   *
+   * @param items - Candidates with unique keys
+   * @param decisions - Map of candidate keys to decisions
+   * @returns Filtered items with explanations
+   * @private
+   */
+  applyFilter(items, decisions) {
+    const kept = [];
+    for (const it of items) {
+      const decision = decisions[it.key];
+      if (decision?.isRelevant === true) {
+        kept.push({
+          item: it.item,
+          explanation: typeof decision.explanation === "string" ? decision.explanation : ""
+        });
+      }
+    }
+    return kept;
+  }
+  /**
+   * Process a single batch of candidates through the LLM filter.
+   *
+   * @param query - Query to filter against
+   * @param batch - Prepared candidates
+   * @param options - Optional userId override
+   * @returns Filtered items (stable order), with explanations
+   * @private
+   */
+  async processFilterBatch(query, batch, options) {
+    const keyed = this.ensureUniqueKeys(batch);
+    const { schema, messages } = this.buildFilterRequest(query, keyed);
+    const decisions = await this.fetchFilterDecisions(messages, schema, options?.userId);
+    if (decisions == null) {
+      return keyed.map(({ item }) => ({ item, explanation: "" }));
+    }
+    return this.applyFilter(keyed, decisions);
+  }
+  /**
+   * Process a batch of candidates and choose a single winner.
+   *
+   * @param query - Query to choose against
+   * @param batch - Candidates with unique keys
+   * @param userId - Optional userId override
+   * @returns Winner item with explanation
+   * @private
+   */
+  async processChoiceBatch(query, batch, userId) {
+    const { schema, messages } = this.buildChoiceRequest(query, batch);
+    const choice = await this.fetchChoice(messages, schema, userId);
+    if (choice == null) {
+      return { item: batch[0].item, explanation: "" };
+    }
+    const winner = batch.find((x) => x.key === choice.selectedKey);
+    if (!winner) {
+      return { item: batch[0].item, explanation: choice.explanation };
+    }
+    return { item: winner.item, explanation: choice.explanation };
+  }
+  /**
+   * Apply relevancy threshold filtering and stable sorting.
+   *
+   * Scores are clamped to the configured score range, then filtered to keep only items with
+   * score > threshold. Results are sorted by score descending, with ties
+   * preserving original input order for deterministic results.
+   *
+   * @param items - Candidates with unique keys
+   * @param scores - Map of candidate keys to LLM-assigned scores
+   * @returns Filtered and sorted array of original items
+   * @private
+   */
+  rankAndFilter(items, evaluations) {
+    const threshold = this.cfg.relevancyThreshold;
+    const scored = items.map(({ item, idx, key }) => ({
+      item,
+      idx,
+      explanation: typeof evaluations[key]?.explanation === "string" ? evaluations[key].explanation : "",
+      score: clamp(
+        evaluations[key]?.score ?? this.cfg.minScore,
+        this.cfg.minScore,
+        this.cfg.maxScore
+      )
+    }));
+    const filtered = scored.filter(({ score }) => score > threshold);
+    const sorted = filtered.sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score;
+      return a.idx - b.idx;
+    });
+    return sorted;
+  }
+  /**
+   * Process a single batch of candidates through the LLM.
+   *
+   * Ensures unique keys, builds the request payload, fetches scores from the LLM,
+   * and returns filtered and sorted results. On any error or null response from
+   * the LLM, returns items in their original order as a fallback.
+   *
+   * @param query - The search query to evaluate candidates against
+   * @param batch - Batch of prepared candidates to process
+   * @param userId - Optional user identifier for provider abuse monitoring
+   * @returns Ranked and filtered items, or original order on error
+   * @private
+   */
+  async processBatch(query, batch, options) {
+    const keyed = this.ensureUniqueKeys(batch);
+    const { schema, messages } = this.buildRequest(query, keyed);
+    const evaluations = await this.fetchEvaluations(messages, schema, options?.userId);
+    if (evaluations == null) {
+      return keyed.map(({ item }) => ({ item, explanation: "" }));
+    }
+    const ranked = this.rankAndFilter(keyed, evaluations);
+    return ranked.map(({ item, explanation }) => ({ item, explanation }));
+  }
+};
+export {
+  CONFIG,
+  DEFAULT_KEY_EXTRACTOR,
+  DEFAULT_SUMMARY_EXTRACTOR,
+  Intent,
+  createDefaultGroqClient
+};
+//# sourceMappingURL=index.mjs.map