@with-logic/intent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Logic App, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# Intent
+
+`intent` is an LLM-based reranker library that offers ranking, filtering, and choice all with explicit, inspectable reasoning.
+
+Unlike black-box models, `intent` generates an explanation alongside every score. This transparency allows for easier debugging and enables you to surface reasoning directly to users.
+
+By being LLM powered, it also offers flexibility and dynamic tunability to
+your ranking logic without needing to come up with custom embedding models or
+retrain existing ones.
+
+## Install
+
+```bash
+npm install @with-logic/intent
+```
+
+## Quickstart
+
+```ts
+import { Intent } from "@with-logic/intent";
+
+const intent = new Intent({ relevancyThreshold: 1 });
+
+const docs = [
+  "Many network requests can fail intermittently due to transient issues.",
+  "To reduce flaky tests, add exponential backoff with jitter to HTTP retries.",
+  "Citrus fruits like oranges and lemons are high in vitamin C.",
+];
+
+const ranked = await intent.rank("exponential backoff retries", docs);
+// => [doc1, doc2] (doc3 is filtered out via relevancy threshold)
+```
+
+Intent will use a default Groq client when `GROQ_API_KEY` is set.
+
+## Core API
+
+- `rank(query, candidates)` → rerank + threshold filter (score-based)
+- `filter(query, candidates)` → keep only relevant items (boolean)
+- `choice(query, candidates)` → choose exactly one best item
+
+All three support `{ explain: true }` to return explanations.
+
+## Example Use Cases
+
+### 1) Ordering search results with `rank()`
+
+Use `rank()` when you want ranked, ordered results.
+
+```ts
+import { Intent } from "@with-logic/intent";
+
+type Doc = {
+  id: string;
+  title: string;
+  body: string;
+  tags: string[];
+};
+
+const intent = new Intent<Doc>({
+  key: (d) => d.id,
+  relevancyThreshold: 5,
+});
+
+const docs: Doc[] = [
+  { id: "1", title: "Q2 expenses", body: "Travel, meals, ...", tags: ["finance"] },
+  { id: "2", title: "OKR planning", body: "Goals for ...", tags: ["strategy"] },
+  { id: "3", title: "Laptop purchases", body: "New laptops ...", tags: ["finance", "it"] },
+];
+
+const results = await intent.rank("Find expense reports and anything about spend approvals", docs);
+```
+
+### Include explanations
+
+```ts
+const results = await intent.rank("expense reports", docs, { explain: true });
+// => [{ item: Doc, explanation: string }, ...]
+```
+
+## 2) Tool filtering with `filter()`
+
+Use `filter()` when you want to keep the subset of items in a collection that
+are relevant to a query.
+
+```ts
+import { Intent } from "@with-logic/intent";
+
+type Tool = {
+  name: string;
+  description: string;
+};
+
+const intent = new Intent<Tool>({
+  key: (t) => t.name,
+  summary: (t) => t.description,
+});
+
+const tools: Tool[] = [
+  { name: "search", description: "Search the web for up-to-date information" },
+  { name: "sendEmail", description: "Send an email to a recipient" },
+  { name: "runSQL", description: "Run a SQL query against the analytics DB" },
+  { name: "createInvoice", description: "Create an invoice for a customer" },
+];
+
+const task = "Find the customer's last invoice total and email it to them.";
+
+const relevantTools = await intent.filter(task, tools);
+// [sendEmail, runSQL]
+```
+
+### Filter with explanations
+
+```ts
+const relevantTools = await intent.filter(task, tools, { explain: true });
+// => [{ item: Tool, explanation: string }, ...]
+```
+
+## 3) Model routing with `choice()`
+
+Use `choice()` when you need exactly one selection from a set of items.
+
+```ts
+import { Intent } from "@with-logic/intent";
+
+type Model = {
+  id: string;
+  strengths: string;
+};
+
+const intent = new Intent<Model>({
+  key: (m) => m.id,
+  summary: (m) => m.strengths,
+});
+
+const models: Model[] = [
+  {
+    id: "gemini-3-pro",
+    strengths: "Hard reasoning, math, complex debugging. Slower but very strong.",
+  },
+  {
+    id: "gpt-5.2",
+    strengths: "Best for code generation, refactors, feature implementation.",
+  },
+  {
+    id: "haiku-4.5"
+    strengths: "Fast and cheap. Good for triage and simple edits.",
+  },
+  {
+    id: "nano-banana-pro",
+    strengths: "Image generation and visual content.",
+  },
+];
+
+const task = "Implement a feature to add retries with exponential backoff and tests.";
+
+const { item: selected, explanation } = await intent.choice(task, models, { explain: true });
+// selected.id => gpt-5.2
+```
+
+## Configuration
+
+Intent reads `.env` automatically when imported.
+
+```env
+GROQ_API_KEY=your_groq_api_key_here
+
+# Optional defaults
+GROQ_DEFAULT_MODEL=openai/gpt-oss-20b
+GROQ_DEFAULT_REASONING_EFFORT=medium
+INTENT_TIMEOUT_MS=3000
+INTENT_MIN_SCORE=0
+INTENT_MAX_SCORE=10
+INTENT_RELEVANCY_THRESHOLD=0
+INTENT_BATCH_SIZE=20
+INTENT_TINY_BATCH_FRACTION=0.2
+```
+
+### How configuration works
+
+- You can configure Intent via **environment variables** (shown above) or via the `Intent` constructor.
+- Constructor options override environment defaults for that instance.
+- Most tuning is a trade-off between **quality**, **latency**, and **cost**.
+
+### Provider + model
+
+#### `GROQ_API_KEY`
+
+If you don't pass a custom `llm` client, Intent will create a default Groq client when this is set.
+
+#### `GROQ_DEFAULT_MODEL`
+
+Sets the model name used by the built-in Groq client.
+
+- Choose a stronger model when you care about nuanced ranking or long candidate summaries.
+- Choose a smaller model when you want lower latency/cost and your candidates are simple.
+
+#### `GROQ_DEFAULT_REASONING_EFFORT`
+
+Controls how much reasoning the model should do (`low | medium | high`).
+
+- `low`: fastest; best for obvious matches.
+- `medium`: good default.
+- `high`: better for subtle intent, but typically slower/more expensive.
+
+### Ranking behavior
+
+#### `INTENT_RELEVANCY_THRESHOLD`
+
+Controls how selective the output is.
+
+- Higher threshold → fewer results (higher precision)
+- Lower threshold → more results (higher recall)
+
+Important: threshold filtering is **strictly greater-than** (`score > threshold`).
+So with the default score range `0..10`:
+
+- `relevancyThreshold=0` keeps scores `1..10`
+- `relevancyThreshold=5` keeps scores `6..10`
+
+#### `INTENT_MIN_SCORE` / `INTENT_MAX_SCORE`
+
+Controls the score range given to the LLM.
+
+- Narrower ranges (e.g. `1..5`) can make scoring easier to calibrate.
+- Wider ranges (e.g. `0..10`) give more resolution for ranking.
+
+Note: Since the is an LLM's judgement, as opposed to an objective measurement,
+scores may not use the full range perfectly and you may seem similar biases
+that you'd see with human raters.
+
+This also means that massive ranges (e.g. `0..1000`) may not yield more
+precise results.
+
+If you change the range, ensure your `relevancyThreshold` stays within it.
+
+### Performance knobs
+
+#### `INTENT_TIMEOUT_MS`
+
+Hard timeout per LLM call.
+
+- Increase it when you have larger batches, longer summaries, or slower models.
+- Decrease it when you prefer quick fallbacks over waiting.
+
+If we timeout, we never throw an error; instead, we return the original
+results.
+
+#### `INTENT_BATCH_SIZE`
+
+How many candidates are evaluated per LLM call.
+
+- Larger batch size → fewer calls (often cheaper/faster), but higher token usage per call.
+- Smaller batch size → more calls (often slower), but each call is smaller.
+
+#### `INTENT_TINY_BATCH_FRACTION`
+
+When the last batch is “too small”, Intent will merge it into the previous batch.
+
+- Increase to avoid tiny extra calls (better latency/cost).
+- Decrease if you frequently run near context limits.
+
+### Programmatic configuration (constructor)
+
+Everything above can be set per instance:
+
+```ts
+import { Intent } from "intent";
+
+const intent = new Intent({
+  timeoutMs: 10_000,
+  batchSize: 25,
+  relevancyThreshold: 3,
+  minScore: 0,
+  maxScore: 10,
+});
+```

package/dist/batches.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Utilities for creating and maintaining batches of items.
+ */
+/**
+ * Slice a list into fixed-size batches.
+ *
+ * Divides the input array into chunks of the specified size. The final batch
+ * may be smaller than the requested size if items don't divide evenly.
+ *
+ * @param items - Array of items to batch
+ * @param size - Maximum number of items per batch
+ * @returns Array of batches, each containing up to `size` items
+ */
+export declare function sliceIntoFixedBatches<T>(items: T[], size: number): T[][];
+/**
+ * Merge the final batch into the previous when it's tiny (but non-empty).
+ *
+ * Small trailing batches are inefficient for LLM calls due to fixed overhead.
+ * This function merges the last batch into the second-to-last when the final
+ * batch is smaller than the threshold.
+ *
+ * @param batches - Array of batches to potentially merge
+ * @param tinyThreshold - Maximum size for a batch to be considered "tiny"
+ * @returns Modified array with tiny final batch merged, or original if no merge needed
+ */
+export declare function mergeTinyFinalBatch<T>(batches: T[][], tinyThreshold: number): T[][];
+/**
+ * Create batches then merge a tiny trailing batch.
+ *
+ * Combines sliceIntoFixedBatches and mergeTinyFinalBatch to efficiently
+ * partition items while avoiding wasteful small final batches.
+ *
+ * @param items - Array of items to batch
+ * @param size - Target batch size
+ * @param tinyFraction - Fraction of batch size (0-1) below which final batch is merged
+ * @returns Array of batches with no tiny trailing batch
+ */
+export declare function createBatches<T>(items: T[], size: number, tinyFraction: number): T[][];
+import type { LoggerLike } from "./types";
+/**
+ * Split items into batches, process each batch with an async function, handle errors, and flatten results.
+ *
+ * Batches are processed in parallel using Promise.all. If a batch fails, the error
+ * handler (or fallback to original items) is used for that batch, while successful
+ * batches proceed normally.
+ *
+ * @param items - Array of items to process in batches
+ * @param size - Target batch size
+ * @param tinyFraction - Fraction of batch size below which final batch is merged
+ * @param fn - Async function to process each batch
+ * @param logger - Optional logger for warnings
+ * @param onError - Optional error handler returning fallback results for failed batch
+ * @returns Flattened array of all batch results
+ */
+export declare function batchProcess<I, O = I>(items: I[], size: number, tinyFraction: number, fn: (batch: I[]) => Promise<O[]>, logger?: LoggerLike, onError?: (batch: I[], error: unknown) => O[]): Promise<O[]>;

package/dist/batches.js

@@ -0,0 +1,91 @@
+/**
+ * Utilities for creating and maintaining batches of items.
+ */
+/**
+ * Slice a list into fixed-size batches.
+ *
+ * Divides the input array into chunks of the specified size. The final batch
+ * may be smaller than the requested size if items don't divide evenly.
+ *
+ * @param items - Array of items to batch
+ * @param size - Maximum number of items per batch
+ * @returns Array of batches, each containing up to `size` items
+ */
+export function sliceIntoFixedBatches(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/**
+ * Merge the final batch into the previous when it's tiny (but non-empty).
+ *
+ * Small trailing batches are inefficient for LLM calls due to fixed overhead.
+ * This function merges the last batch into the second-to-last when the final
+ * batch is smaller than the threshold.
+ *
+ * @param batches - Array of batches to potentially merge
+ * @param tinyThreshold - Maximum size for a batch to be considered "tiny"
+ * @returns Modified array with tiny final batch merged, or original if no merge needed
+ */
+export 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;
+}
+/**
+ * Create batches then merge a tiny trailing batch.
+ *
+ * Combines sliceIntoFixedBatches and mergeTinyFinalBatch to efficiently
+ * partition items while avoiding wasteful small final batches.
+ *
+ * @param items - Array of items to batch
+ * @param size - Target batch size
+ * @param tinyFraction - Fraction of batch size (0-1) below which final batch is merged
+ * @returns Array of batches with no tiny trailing batch
+ */
+export function createBatches(items, size, tinyFraction) {
+    const batches = sliceIntoFixedBatches(items, size);
+    const tinyThreshold = Math.ceil(tinyFraction * size);
+    return mergeTinyFinalBatch(batches, tinyThreshold);
+}
+/**
+ * Split items into batches, process each batch with an async function, handle errors, and flatten results.
+ *
+ * Batches are processed in parallel using Promise.all. If a batch fails, the error
+ * handler (or fallback to original items) is used for that batch, while successful
+ * batches proceed normally.
+ *
+ * @param items - Array of items to process in batches
+ * @param size - Target batch size
+ * @param tinyFraction - Fraction of batch size below which final batch is merged
+ * @param fn - Async function to process each batch
+ * @param logger - Optional logger for warnings
+ * @param onError - Optional error handler returning fallback results for failed batch
+ * @returns Flattened array of all batch results
+ */
+export 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();
+}
+//# sourceMappingURL=batches.js.map

package/dist/batches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.js","sourceRoot":"","sources":["../src/batches.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAI,KAAU,EAAE,IAAY;IAC/D,MAAM,GAAG,GAAU,EAAE,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,IAAI;QAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAChF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAI,OAAc,EAAE,aAAqB;IAC1E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,aAAa;QAAE,OAAO,OAAO,CAAC;IACrE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;IAC1C,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAI,KAAU,EAAE,IAAY,EAAE,YAAoB;IAC7E,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IACrD,OAAO,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;AACrD,CAAC;AAID;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAU,EACV,IAAY,EACZ,YAAoB,EACpB,EAAgC,EAChC,MAAmB,EACnB,OAA6C;IAE7C,MAAM,OAAO,GAAG,aAAa,CAAI,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QACtB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,EAAE,IAAI,EAAE,CAAC,yDAAyD,EAAE;gBACxE,KAAK,EAAG,KAAe,EAAE,OAAO;aACjC,CAAC,CAAC;YAEH,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC3B,CAAC;YAED,OAAO,CAAmB,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IACF,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+import "dotenv/config";
+/**
+ * Exported config object (no function call required) following API patterns.
+ */
+export declare const CONFIG: {
+    readonly GROQ: {
+        readonly API_KEY: string;
+        readonly DEFAULT_MODEL: string;
+        readonly DEFAULT_REASONING_EFFORT: "low" | "medium" | "high";
+        readonly JSON_REPAIR_ATTEMPTS: number;
+    };
+    readonly INTENT: {
+        readonly PROVIDER: "GROQ";
+        readonly TIMEOUT_MS: number;
+        readonly MIN_SCORE: number;
+        readonly MAX_SCORE: number;
+        readonly RELEVANCY_THRESHOLD: number;
+        readonly BATCH_SIZE: number;
+        readonly TINY_BATCH_FRACTION: number;
+    };
+    readonly TEST: {
+        readonly SCOPE: string;
+    };
+};

package/dist/config.js

@@ -0,0 +1,29 @@
+import "dotenv/config";
+import { enumeration, int, number, string } from "./lib/config";
+/**
+ * Exported config object (no function call required) following API patterns.
+ */
+export const 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: 3000, 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" }),
+    },
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEhE;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE;QACJ,OAAO,EAAE,MAAM,CAAC,cAAc,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAChD,aAAa,EAAE,MAAM,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;QAC9E,wBAAwB,EAAE,WAAW,CAAC,+BAA+B,EAAE;YACrE,OAAO,EAAE,QAAQ;YACjB,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU;SAC3C,CAAC;QACF,oBAAoB,EAAE,GAAG,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;KAC/E;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,WAAW,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,CAAU,EAAE,CAAC;QACxF,UAAU,EAAE,GAAG,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/D,SAAS,EAAE,GAAG,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAClD,SAAS,EAAE,GAAG,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAC3D,mBAAmB,EAAE,GAAG,CAAC,4BAA4B,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACtE,UAAU,EAAE,GAAG,CAAC,mBAAmB,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;QAC7D,mBAAmB,EAAE,MAAM,CAAC,4BAA4B,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;KAC5F;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAChD;CACO,CAAC"}

package/dist/extractors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Default extractor functions for Intent.
+ *
+ * These provide sensible defaults when users don't specify custom key/summary extractors.
+ */
+/**
+ * Converts any value to a pretty-printed JSON string with error handling.
+ *
+ * This is the canonical helper for all JSON stringification in the codebase.
+ * Pretty-prints with 2-space indentation for better LLM readability.
+ * Falls back to String(value) if JSON.stringify fails (e.g., circular references).
+ * Handles undefined explicitly since JSON.stringify(undefined) returns undefined.
+ *
+ * @param value - The value to stringify
+ * @returns Pretty-printed JSON string, or String() fallback
+ * @throws Never throws - gracefully falls back to String() on any error
+ */
+export declare function jsonStringify(value: unknown): string;
+/**
+ * Converts any value to a hash-based string key.
+ *
+ * Serializes the value to JSON, computes a 32-bit hash, and returns it as a string.
+ * This provides unique-enough keys for items without requiring explicit key extractors.
+ *
+ * @param value - The value to convert to a key
+ * @returns A string representation of the hash (e.g., "2847561")
+ * @throws Never throws - uses jsonStringify which handles all errors internally
+ */
+export declare function hashToString<T>(value: T): string;
+/**
+ * Default key extractor: generates hash-based string keys from items.
+ *
+ * Generic function that works with any item type T. The generic parameter
+ * enables type-safe usage without type casts when assigned to typed extractors.
+ *
+ * @param item - The item to extract a key from
+ * @returns A hash-based string key
+ * @throws Never throws - uses hashToString which handles all errors internally
+ */
+export declare function DEFAULT_KEY_EXTRACTOR<T>(item: T): string;
+/**
+ * Default summary extractor: converts items to pretty-printed JSON strings.
+ *
+ * Uses 2-space indentation for better LLM readability.
+ * Generic function that works with any item type T. The generic parameter
+ * enables type-safe usage without type casts when assigned to typed extractors.
+ *
+ * @param item - The item to extract a summary from
+ * @returns A pretty-printed JSON string representation of the item
+ * @throws Never throws - uses jsonStringify which handles all errors internally
+ */
+export declare function DEFAULT_SUMMARY_EXTRACTOR<T>(item: T): string;

package/dist/extractors.js

@@ -0,0 +1,88 @@
+/**
+ * Default extractor functions for Intent.
+ *
+ * These provide sensible defaults when users don't specify custom key/summary extractors.
+ */
+/**
+ * Computes a simple 32-bit hash from a string using the djb2 algorithm.
+ *
+ * @param str - The string to hash
+ * @returns A 32-bit hash value
+ * @private
+ */
+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; // hash * 33 + char, keep in 32-bit range
+    }
+    return hash >>> 0; // Convert to unsigned 32-bit integer
+}
+/**
+ * Converts any value to a pretty-printed JSON string with error handling.
+ *
+ * This is the canonical helper for all JSON stringification in the codebase.
+ * Pretty-prints with 2-space indentation for better LLM readability.
+ * Falls back to String(value) if JSON.stringify fails (e.g., circular references).
+ * Handles undefined explicitly since JSON.stringify(undefined) returns undefined.
+ *
+ * @param value - The value to stringify
+ * @returns Pretty-printed JSON string, or String() fallback
+ * @throws Never throws - gracefully falls back to String() on any error
+ */
+export function jsonStringify(value) {
+    try {
+        const result = JSON.stringify(value, null, 2);
+        // JSON.stringify returns undefined for undefined values
+        if (result === undefined) {
+            return String(value);
+        }
+        return result;
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Converts any value to a hash-based string key.
+ *
+ * Serializes the value to JSON, computes a 32-bit hash, and returns it as a string.
+ * This provides unique-enough keys for items without requiring explicit key extractors.
+ *
+ * @param value - The value to convert to a key
+ * @returns A string representation of the hash (e.g., "2847561")
+ * @throws Never throws - uses jsonStringify which handles all errors internally
+ */
+export function hashToString(value) {
+    const json = jsonStringify(value);
+    const hashValue = hash32(json);
+    return String(hashValue);
+}
+/**
+ * Default key extractor: generates hash-based string keys from items.
+ *
+ * Generic function that works with any item type T. The generic parameter
+ * enables type-safe usage without type casts when assigned to typed extractors.
+ *
+ * @param item - The item to extract a key from
+ * @returns A hash-based string key
+ * @throws Never throws - uses hashToString which handles all errors internally
+ */
+export function DEFAULT_KEY_EXTRACTOR(item) {
+    return hashToString(item);
+}
+/**
+ * Default summary extractor: converts items to pretty-printed JSON strings.
+ *
+ * Uses 2-space indentation for better LLM readability.
+ * Generic function that works with any item type T. The generic parameter
+ * enables type-safe usage without type casts when assigned to typed extractors.
+ *
+ * @param item - The item to extract a summary from
+ * @returns A pretty-printed JSON string representation of the item
+ * @throws Never throws - uses jsonStringify which handles all errors internally
+ */
+export function DEFAULT_SUMMARY_EXTRACTOR(item) {
+    return jsonStringify(item);
+}
+//# sourceMappingURL=extractors.js.map

package/dist/extractors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extractors.js","sourceRoot":"","sources":["../src/extractors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,GAAW;IACzB,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,yCAAyC;IACnF,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,qCAAqC;AAC1D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC9C,wDAAwD;QACxD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAI,KAAQ;IACtC,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAI,IAAO;IAC9C,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAI,IAAO;IAClD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Intent } from "./intent";
+export type { ChatMessage, LlmClient, LlmCallConfig, LoggerLike, IntentCandidate, IntentExtractors, IntentOptions, IntentConfig, IntentContext, } from "./types";
+export { CONFIG } from "./config";
+export { createDefaultGroqClient } from "./providers/groq";
+export { DEFAULT_KEY_EXTRACTOR, DEFAULT_SUMMARY_EXTRACTOR } from "./extractors";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Intent } from "./intent";
+export { CONFIG } from "./config";
+export { createDefaultGroqClient } from "./providers/groq";
+export { DEFAULT_KEY_EXTRACTOR, DEFAULT_SUMMARY_EXTRACTOR } from "./extractors";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAYlC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC"}