@with-logic/intent 0.1.0

package/dist/providers/groq.js

@@ -0,0 +1,335 @@
+import Groq from "groq-sdk";
+import { CONFIG } from "../config";
+/**
+ * Return a best-effort nested error record from groq-sdk.
+ *
+ * @param err - Any thrown value
+ * @returns Nested `error` object when present
+ * @private
+ */
+function getNestedErrorObject(err) {
+    if (err == null || typeof err !== "object") {
+        return undefined;
+    }
+    const record = err;
+    const error = record.error;
+    if (error == null || typeof error !== "object") {
+        return undefined;
+    }
+    return error;
+}
+/**
+ * Map internal ChatMessage to groq-sdk ChatCompletionMessageParam.
+ *
+ * Converts our generic message format to Groq's expected format.
+ * Only supports system, user, and assistant roles. Throws on unsupported
+ * roles (like "tool") to ensure predictable provider behavior.
+ *
+ * @param messages - Array of generic chat messages
+ * @returns Array of Groq-formatted messages
+ * @throws {Error} If message contains unsupported role
+ * @private
+ */
+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`);
+    });
+}
+/**
+ * Build the request payload expected by groq-sdk with strict JSON schema.
+ *
+ * Constructs the complete request object including model, reasoning effort, messages,
+ * optional user ID, and the response_format configuration that enforces strict
+ * JSON schema validation on the model's output.
+ *
+ * @param outputSchema - JSON schema defining expected response structure
+ * @param groqMessages - Formatted chat messages
+ * @param config - Optional config overriding model and reasoning effort
+ * @param userId - Optional user identifier for Groq's abuse monitoring
+ * @returns Request payload ready for groq-sdk
+ * @private
+ */
+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,
+            },
+        },
+    };
+}
+/**
+ * Execute the chat completion with an optional timeout.
+ *
+ * Wraps the Groq SDK's chat.completions.create call with optional timeout support.
+ *
+ * @param client - Initialized Groq SDK client
+ * @param request - Complete request payload
+ * @param timeoutMs - Optional timeout in milliseconds
+ * @returns Raw completion response from Groq
+ * @private
+ */
+async function executeCompletion(client, request, timeoutMs) {
+    const timeout = typeof timeoutMs === "number" ? { timeout: timeoutMs } : undefined;
+    return client.chat.completions.create(request, timeout);
+}
+/**
+ * Extract and validate the content string from a Groq response.
+ *
+ * Safely navigates the response structure to find the message content.
+ * Throws if content is missing or not a string.
+ *
+ * @param response - Raw completion response from Groq SDK
+ * @returns The message content as a string
+ * @throws {Error} If content is missing or invalid
+ * @private
+ */
+function getResponseContent(response) {
+    const content = response?.choices?.[0]?.message?.content;
+    if (typeof content !== "string") {
+        throw new Error("Groq did not return content");
+    }
+    return content;
+}
+/**
+ * Parse the model's JSON content, throwing a clear error on failure.
+ *
+ * Attempts to parse the string content as JSON and wraps it in a { data } object
+ * to match the expected LlmClient return type.
+ *
+ * @param content - JSON string from model response
+ * @returns Wrapped parsed data
+ * @throws {Error} If content is not valid JSON
+ * @private
+ */
+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;
+    }
+}
+/**
+ * Build a repair conversation turn to help the model correct invalid JSON.
+ *
+ * We include the raw output and the error message, then remind the model to
+ * return only valid JSON that matches the already-provided schema.
+ *
+ * @param baseMessages - Original Groq-formatted messages
+ * @param rawOutput - Raw model output that failed parsing
+ * @param errorMessage - Parse/validation error message
+ * @returns New messages array including a repair request
+ * @private
+ */
+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.\n\n" +
+                `Error: ${errorMessage}`,
+        },
+    ];
+}
+/**
+ * Build a repair request object if we still have attempts remaining.
+ *
+ * @param remaining - Attempts remaining for the overall call
+ * @param request - The current Groq request
+ * @param repair - Repair context
+ * @returns The repaired request and decremented remaining attempts, or undefined
+ * @private
+ */
+function buildRepairRetry(state, repair) {
+    if (state.remaining <= 1) {
+        return undefined;
+    }
+    const repairedRequest = {
+        ...state.request,
+        messages: buildJsonRepairMessages(state.request.messages, repair.rawOutput, repair.errorMessage),
+    };
+    return { remaining: state.remaining - 1, request: repairedRequest };
+}
+/**
+ * Convert a JSON parse error into a repair input.
+ *
+ * @param rawOutput - Raw model output
+ * @param parseError - JSON.parse error
+ * @returns Repair input
+ * @private
+ */
+function parseErrorToRepairInput(rawOutput, parseError) {
+    return { rawOutput, errorMessage: String(parseError) };
+}
+/**
+ * Extract raw output from a JSON parse error thrown by parseJson.
+ *
+ * @param error - Error thrown by parseJson
+ * @returns Raw output when present
+ * @private
+ */
+function getRawOutputFromParseJsonError(error) {
+    if (!(error instanceof Error)) {
+        return undefined;
+    }
+    const record = error;
+    return typeof record.rawOutput === "string" ? record.rawOutput : undefined;
+}
+/**
+ * Extract repair inputs from a Groq schema-validation failure.
+ *
+ * Groq can return a rich error payload for `json_validate_failed`, sometimes
+ * including the model's `generated_response`. We use this to ask the model to
+ * correct its output without re-sending the schema.
+ *
+ * @param err - Unknown thrown error from groq-sdk
+ * @returns Repair inputs when present; otherwise undefined
+ * @private
+ */
+function extractJsonValidateFailedRepairInput(err) {
+    if (err instanceof Error) {
+        const match = err.message.match(/"failed_generation":"(\{.*?\})"/);
+        const failedGeneration = match?.[1] ? match[1].replace(/\\"/g, '"') : undefined;
+        if (err.message.includes('"code":"json_validate_failed"')) {
+            return {
+                rawOutput: failedGeneration ?? "(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
+        : undefined;
+    const serverError = nested ?? errorObj;
+    if (!serverError) {
+        return undefined;
+    }
+    const code = typeof serverError.code === "string" ? serverError.code : undefined;
+    if (code !== "json_validate_failed") {
+        return undefined;
+    }
+    const message = typeof serverError.message === "string" ? serverError.message : undefined;
+    const generatedResponse = typeof serverError.generated_response === "string" ? serverError.generated_response : undefined;
+    const failedGeneration = typeof serverError.failed_generation === "string" ? serverError.failed_generation : undefined;
+    const rawOutput = generatedResponse ?? failedGeneration;
+    return {
+        rawOutput: rawOutput ?? "(Groq did not include the rejected generation in the error payload)",
+        errorMessage: message ?? String(err),
+    };
+}
+/**
+ * Create a GroqSdkLike wrapper around groq-sdk.
+ *
+ * This keeps our provider surface strongly typed while isolating groq-sdk's
+ * broader request/response types to a single boundary.
+ *
+ * @param apiKey - Groq API key
+ * @returns GroqSdkLike wrapper
+ * @private
+ */
+export function createGroqSdkLike(apiKey) {
+    const sdk = new Groq({ apiKey });
+    return {
+        chat: {
+            completions: {
+                create: async (req, opts) => {
+                    // groq-sdk's types lag behind json_schema support; keep the boundary localized.
+                    return (await sdk.chat.completions.create(req, opts));
+                },
+            },
+        },
+    };
+}
+/**
+ * Create the underlying Groq SDK client.
+ *
+ * This wrapper exists to make the default SDK construction path unit-testable.
+ *
+ * @param options - Groq SDK constructor options
+ * @returns Groq SDK client
+ * @private
+ */
+export function createGroqSdk(options) {
+    return new Groq(options);
+}
+export 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) {
+                    // If the model returned bad JSON, retry by appending a repair turn.
+                    const parseRawOutput = getRawOutputFromParseJsonError(err);
+                    if (parseRawOutput !== undefined) {
+                        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);
+                        }
+                    }
+                    // Non-JSON errors are terminal (quota/outage/etc.).
+                    throw err;
+                }
+            };
+            const attempts = Math.max(1, jsonRepairAttempts);
+            return createWithRetry({ remaining: attempts, request: baseRequest });
+        },
+    };
+}
+//# sourceMappingURL=groq.js.map

package/dist/providers/groq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"groq.js","sourceRoot":"","sources":["../../src/providers/groq.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,82 @@
+import type { JSONObject } from "./types";
+type IntegerSchema = {
+    type: "integer";
+};
+type StringSchema = {
+    type: "string";
+};
+type BooleanSchema = {
+    type: "boolean";
+};
+type CandidateEvaluationSchema = {
+    type: "object";
+    properties: {
+        explanation: StringSchema;
+        score: IntegerSchema;
+    };
+    required: ["explanation", "score"];
+    additionalProperties: false;
+};
+type CandidateFilterSchema = {
+    type: "object";
+    properties: {
+        explanation: StringSchema;
+        isRelevant: BooleanSchema;
+    };
+    required: ["explanation", "isRelevant"];
+    additionalProperties: false;
+};
+/**
+ * Build the schema used for a single candidate's evaluation.
+ *
+ * Property order is intentional: `explanation` is defined before `score` to
+ * encourage structured-output models to generate explanations first.
+ *
+ * @returns JSON schema for a single candidate evaluation
+ */
+export declare function buildCandidateEvaluationSchema(): CandidateEvaluationSchema;
+/**
+ * Build the schema used for a single candidate's filter decision.
+ *
+ * Property order is intentional: `explanation` is defined before `isRelevant`.
+ *
+ * @returns JSON schema for a single candidate filter decision
+ */
+export declare function buildCandidateFilterSchema(): CandidateFilterSchema;
+/**
+ * Build a strict JSON schema mapping candidate keys to evaluation objects.
+ *
+ * Each candidate key maps to an object containing:
+ * - explanation: a short justification of the score
+ * - score: an integer within the configured range
+ *
+ * Property order is intentional (`explanation` then `score`) to encourage the
+ * model to generate explanations before scores in structured-output modes.
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema object enforcing exact structure of response
+ */
+export declare function buildRelevancySchema(keys: string[], minScore: number, maxScore: number): JSONObject;
+/**
+ * Build a strict JSON schema mapping candidate keys to boolean relevancy decisions.
+ *
+ * Each candidate key maps to an object containing:
+ * - explanation: a short justification
+ * - isRelevant: boolean
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema object enforcing exact structure of response
+ */
+export declare function buildFilterSchema(keys: string[]): JSONObject;
+/**
+ * Build a strict JSON schema for choosing a single candidate key.
+ *
+ * The model must return:
+ * - explanation: string
+ * - selectedKey: one of the provided candidate keys (enum)
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema enforcing a single selected key
+ */
+export declare function buildChoiceSchema(keys: string[]): JSONObject;
+export {};

package/dist/schema.js

@@ -0,0 +1,114 @@
+/**
+ * Build the schema used for a single candidate's evaluation.
+ *
+ * Property order is intentional: `explanation` is defined before `score` to
+ * encourage structured-output models to generate explanations first.
+ *
+ * @returns JSON schema for a single candidate evaluation
+ */
+export function buildCandidateEvaluationSchema() {
+    return {
+        type: "object",
+        properties: {
+            explanation: { type: "string" },
+            score: { type: "integer" },
+        },
+        required: ["explanation", "score"],
+        additionalProperties: false,
+    };
+}
+/**
+ * Build the schema used for a single candidate's filter decision.
+ *
+ * Property order is intentional: `explanation` is defined before `isRelevant`.
+ *
+ * @returns JSON schema for a single candidate filter decision
+ */
+export function buildCandidateFilterSchema() {
+    return {
+        type: "object",
+        properties: {
+            explanation: { type: "string" },
+            isRelevant: { type: "boolean" },
+        },
+        required: ["explanation", "isRelevant"],
+        additionalProperties: false,
+    };
+}
+/**
+ * Build a strict JSON schema mapping candidate keys to evaluation objects.
+ *
+ * Each candidate key maps to an object containing:
+ * - explanation: a short justification of the score
+ * - score: an integer within the configured range
+ *
+ * Property order is intentional (`explanation` then `score`) to encourage the
+ * model to generate explanations before scores in structured-output modes.
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema object enforcing exact structure of response
+ */
+export 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,
+    };
+}
+/**
+ * Build a strict JSON schema mapping candidate keys to boolean relevancy decisions.
+ *
+ * Each candidate key maps to an object containing:
+ * - explanation: a short justification
+ * - isRelevant: boolean
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema object enforcing exact structure of response
+ */
+export 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,
+    };
+}
+/**
+ * Build a strict JSON schema for choosing a single candidate key.
+ *
+ * The model must return:
+ * - explanation: string
+ * - selectedKey: one of the provided candidate keys (enum)
+ *
+ * @param keys - Array of unique candidate keys
+ * @returns JSON schema enforcing a single selected key
+ */
+export 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,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAoCA;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC/B,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;SAC3B;QACD,QAAQ,EAAE,CAAC,aAAa,EAAE,OAAO,CAAC;QAClC,oBAAoB,EAAE,KAAK;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC/B,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;SAChC;QACD,QAAQ,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC;QACvC,oBAAoB,EAAE,KAAK;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAc,EACd,QAAgB,EAChB,QAAgB;IAEhB,MAAM,gBAAgB,GAAG,8BAA8B,EAAE,CAAC;IAE1D,MAAM,UAAU,GAA8C,EAAE,CAAC;IACjE,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC;IACnC,CAAC;IAED,OAAO;QACL,KAAK,EAAE,wCAAwC;QAC/C,WAAW,EAAE,iEAAiE,QAAQ,IAAI,QAAQ,sBAAsB;QACxH,IAAI,EAAE,QAAQ;QACd,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,oBAAoB,EAAE,KAAK;KACd,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,MAAM,cAAc,GAAG,0BAA0B,EAAE,CAAC;IAEpD,MAAM,UAAU,GAA0C,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,UAAU,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC;IACjC,CAAC;IAED,OAAO;QACL,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EACT,4FAA4F;QAC9F,IAAI,EAAE,QAAQ;QACd,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,oBAAoB,EAAE,KAAK;KACd,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,OAAO;QACL,KAAK,EAAE,iCAAiC;QACxC,WAAW,EAAE,iEAAiE;QAC9E,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC/B,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE;SAC5C;QACD,QAAQ,EAAE,CAAC,aAAa,EAAE,aAAa,CAAC;QACxC,oBAAoB,EAAE,KAAK;KACE,CAAC;AAClC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+export type JSONPrimitive = boolean | number | string | null;
+export type JSONValue = JSONPrimitive | JSONObject | JSONArray;
+export type JSONObject = {
+    [key: string]: JSONValue;
+};
+export type JSONArray = JSONValue[];
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+export type ChatMessage = {
+    role: ChatRole;
+    content: string;
+};
+export type LlmCallConfig = {
+    model?: string;
+    reasoningEffort?: "low" | "medium" | "high";
+    timeoutMs?: number;
+};
+export interface LlmClient {
+    call<T>(messages: ChatMessage[], outputSchema: JSONObject, config?: LlmCallConfig, userId?: string): Promise<{
+        data: T;
+    }>;
+}
+export interface LoggerLike {
+    info?(msg: string, meta?: unknown): void;
+    warn?(msg: string, meta?: unknown): void;
+    error?(msg: string, meta?: unknown): void;
+}
+export type IntentCandidate = {
+    key: string;
+    summary: string;
+};
+export type IntentExtractors<T> = {
+    key?: (item: T) => string;
+    summary?: (item: T) => string;
+};
+export type IntentContext = {
+    llm?: LlmClient;
+    logger?: LoggerLike;
+    userId?: string;
+};
+export type CamelCase<S extends string> = S extends `${infer H}_${infer T}` ? `${Lowercase<H>}${Capitalize<CamelCase<T>>}` : S extends `${infer H}-${infer T}` ? `${Lowercase<H>}${Capitalize<CamelCase<T>>}` : Lowercase<S>;
+export type CamelCasedProps<T> = {
+    [K in keyof T as K extends string ? CamelCase<K> : K]: T[K];
+};
+/**
+ * Configuration options for Intent.
+ *
+ * This is a camelCase version of the INTENT config object from config.ts.
+ */
+export type IntentConfig = {
+    provider?: "GROQ";
+    timeoutMs?: number;
+    relevancyThreshold?: number;
+    batchSize?: number;
+    tinyBatchFraction?: number;
+    minScore?: number;
+    maxScore?: number;
+};
+/**
+ * Complete options object for Intent constructor.
+ *
+ * Merges all configuration into a single, fully optional object:
+ * - LLM client and runtime context (llm, logger, userId)
+ * - Item extractors (key, summary)
+ * - Intent configuration (model, timeoutMs, relevancyThreshold, batchSize, tinyBatchFraction)
+ *
+ * All fields are optional with sensible defaults:
+ * - llm: Auto-detected from GROQ_API_KEY if available
+ * - key: Hash-based string from JSON representation
+ * - summary: Pretty-printed JSON of the item (2-space indentation for LLM readability)
+ * - Config values: From environment variables or built-in defaults
+ *
+ * @template T - The type of items to rerank
+ */
+export type IntentOptions<T> = IntentContext & IntentExtractors<T> & IntentConfig;

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}