@with-logic/intent 0.1.0

package/dist/lib/config.js.map

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

package/dist/lib/number.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Clamp a number to the provided [min, max] range. If min or max are
+ * undefined, only the defined bound(s) are applied.
+ */
+export declare function clamp(n: number, min?: number, max?: number): number;

package/dist/lib/number.js

@@ -0,0 +1,15 @@
+/**
+ * Clamp a number to the provided [min, max] range. If min or max are
+ * undefined, only the defined bound(s) are applied.
+ */
+export 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;
+}
+//# sourceMappingURL=number.js.map

package/dist/lib/number.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number.js","sourceRoot":"","sources":["../../src/lib/number.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,KAAK,CAAC,CAAS,EAAE,GAAY,EAAE,GAAY;IACzD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,GAAG,GAAG,EAAE,CAAC;QACzC,GAAG,GAAG,GAAG,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,GAAG,GAAG,EAAE,CAAC;QACzC,GAAG,GAAG,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/llm_client.d.ts

@@ -0,0 +1,14 @@
+import { CONFIG } from "./config";
+import type { LlmClient, IntentContext } from "./types";
+/**
+ * Select an LLM client to use for reranking.
+ *
+ * Implements the client selection logic:
+ * 1. If ctx.llm is provided, use it directly
+ * 2. Else if GROQ_API_KEY environment variable is set, create default Groq client
+ * 3. Else return undefined (caller must handle error)
+ *
+ * @param ctx - Context object potentially containing an LLM client
+ * @returns Selected LLM client, or undefined if none available
+ */
+export declare function selectLlmClient(ctx: IntentContext, config?: typeof CONFIG): LlmClient | undefined;

package/dist/llm_client.js

@@ -0,0 +1,29 @@
+import { CONFIG } from "./config";
+import { createDefaultGroqClient } from "./providers/groq";
+/**
+ * Select an LLM client to use for reranking.
+ *
+ * Implements the client selection logic:
+ * 1. If ctx.llm is provided, use it directly
+ * 2. Else if GROQ_API_KEY environment variable is set, create default Groq client
+ * 3. Else return undefined (caller must handle error)
+ *
+ * @param ctx - Context object potentially containing an LLM client
+ * @returns Selected LLM client, or undefined if none available
+ */
+export 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 undefined;
+}
+//# sourceMappingURL=llm_client.js.map

package/dist/llm_client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_client.js","sourceRoot":"","sources":["../src/llm_client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAI3D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAkB,EAClB,SAAwB,MAAM;IAE9B,IAAI,GAAG,CAAC,GAAG,EAAE,CAAC;QACZ,OAAO,GAAG,CAAC,GAAG,CAAC;IACjB,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;IACpC,IAAI,OAAO,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC9B,OAAO,uBAAuB,CAAC,OAAO,EAAE;YACtC,QAAQ,EAAE;gBACR,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,aAAa;gBAChC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,wBAAwB;aACtD;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/messages.d.ts

@@ -0,0 +1,41 @@
+import type { ChatMessage, IntentCandidate } from "./types";
+/**
+ * Build system + user messages instructing the model to score candidates.
+ *
+ * Constructs a two-message conversation:
+ * 1. System message: Defines the scoring task, output format, and constraints
+ * 2. User message: Contains the query and candidate items as JSON
+ *
+ * The system prompt emphasizes using the full configured score range and being decisive
+ * about relevance, with strict instructions to return only the score mapping.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export declare function buildMessages(query: string, candidates: IntentCandidate[], scoreRange: {
+    minScore: number;
+    maxScore: number;
+}): ChatMessage[];
+/**
+ * Build system + user messages instructing the model to filter candidates.
+ *
+ * The model must output a JSON object mapping each candidate key to:
+ * Example: {"Some key": {"explanation": "...", "isRelevant": true}}.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export declare function buildFilterMessages(query: string, candidates: IntentCandidate[]): ChatMessage[];
+/**
+ * Build system + user messages instructing the model to choose exactly one candidate.
+ *
+ * The model must output a JSON object of the form:
+ * Example: {"explanation": "...", "selectedKey": "Some key"}.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export declare function buildChoiceMessages(query: string, candidates: IntentCandidate[]): ChatMessage[];

package/dist/messages.js

@@ -0,0 +1,136 @@
+import { jsonStringify } from "./extractors";
+/**
+ * Build system + user messages instructing the model to score candidates.
+ *
+ * Constructs a two-message conversation:
+ * 1. System message: Defines the scoring task, output format, and constraints
+ * 2. User message: Contains the query and candidate items as JSON
+ *
+ * The system prompt emphasizes using the full configured score range and being decisive
+ * about relevance, with strict instructions to return only the score mapping.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export 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) },
+    ];
+}
+/**
+ * Build system + user messages instructing the model to filter candidates.
+ *
+ * The model must output a JSON object mapping each candidate key to:
+ * Example: {"Some key": {"explanation": "...", "isRelevant": true}}.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export 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) },
+    ];
+}
+/**
+ * Build system + user messages instructing the model to choose exactly one candidate.
+ *
+ * The model must output a JSON object of the form:
+ * Example: {"explanation": "...", "selectedKey": "Some key"}.
+ *
+ * @param query - The search query or user intent
+ * @param candidates - Array of candidates with keys and summaries
+ * @returns Array of chat messages ready for LLM consumption
+ */
+export 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) },
+    ];
+}
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,UAA6B,EAC7B,UAAkD;IAElD,MAAM,MAAM,GAAG;;;;oCAImB,UAAU,CAAC,QAAQ,OAAO,UAAU,CAAC,QAAQ;IAC7E,UAAU,CAAC,QAAQ;IACnB,UAAU,CAAC,QAAQ;;;;uBAIA,UAAU,CAAC,QAAQ,wEAAwE,UAAU,CAAC,QAAQ;;;;;;;;;;;;wBAY7G,UAAU,CAAC,QAAQ,OAAO,UAAU,CAAC,QAAQ;;;;;;6DAMR,UAAU,CAAC,QAAQ;6DACnB,UAAU,CAAC,QAAQ;;;;uCAIzC,CAAC;IAEtC,MAAM,OAAO,GAAG;QACd,KAAK;QACL,wBAAwB,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KAC7E,CAAC;IAEX,OAAO;QACL,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;QACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,UAA6B;IAC9E,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;uCAmBsB,CAAC;IAEtC,MAAM,OAAO,GAAG;QACd,KAAK;QACL,wBAAwB,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KAC7E,CAAC;IAEX,OAAO;QACL,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;QACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa,EAAE,UAA6B;IAC9E,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;uCAesB,CAAC;IAEtC,MAAM,OAAO,GAAG;QACd,KAAK;QACL,wBAAwB,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;KAC7E,CAAC;IAEX,OAAO;QACL,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;QACnC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE;KAClD,CAAC;AACJ,CAAC"}

package/dist/providers/groq.d.ts

@@ -0,0 +1,84 @@
+import type { JSONObject, LlmClient } from "../types";
+import type { ChatCompletionMessageParam } from "groq-sdk/resources/chat/completions";
+type GroqTimeoutOptions = {
+    timeout?: number;
+};
+type GroqJsonSchemaResponseFormat = {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        schema: JSONObject;
+        strict: true;
+    };
+};
+type GroqChatCompletionRequest = {
+    model: string;
+    reasoning_effort: "low" | "medium" | "high";
+    messages: ChatCompletionMessageParam[];
+    user?: string;
+    response_format: GroqJsonSchemaResponseFormat;
+};
+type GroqChatCompletionResponse = {
+    choices: Array<{
+        message?: {
+            content?: string | null;
+        };
+    }>;
+};
+/**
+ * Create a default Groq LLM client with retry logic.
+ *
+ * Returns an LlmClient implementation that uses the Groq SDK with:
+ * - Strict JSON schema enforcement via response_format
+ * - Automatic retry on schema validation failures (up to 3 attempts)
+ * - Support for custom model, reasoning effort, timeout, and user ID
+ *
+ * @param apiKey - Groq API key
+ * @returns LlmClient implementation for Groq
+ *
+ * @example
+ * ```typescript
+ * import { CONFIG } from "../config";
+ * const client = createDefaultGroqClient(CONFIG.GROQ.API_KEY);
+ * const result = await client.call(messages, schema, { model: "llama-3.3-70b" });
+ * ```
+ */
+export type GroqSdkLike = {
+    chat: {
+        completions: {
+            create: (req: GroqChatCompletionRequest, opts?: GroqTimeoutOptions) => Promise<GroqChatCompletionResponse>;
+        };
+    };
+};
+/**
+ * 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 declare function createGroqSdkLike(apiKey: string): GroqSdkLike;
+/**
+ * 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 declare function createGroqSdk(options: {
+    apiKey: string;
+}): unknown;
+export declare function createDefaultGroqClient(apiKey: string, options?: {
+    defaults?: {
+        model?: string;
+        reasoningEffort?: "low" | "medium" | "high";
+    };
+    makeSdk?: (apiKey: string) => GroqSdkLike;
+    jsonRepairAttempts?: number;
+}): LlmClient;
+export {};