@appinternalleads/ui 0.3.0 → 0.4.1

package/dist/esm/agent/search/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * **Component search — its internal types.** None of this is part of the agent contract: the agent
+ * calls `searchComponents(query)` and gets cards. How candidates are found — lexical, semantic,
+ * in memory or not — can change without it knowing.
+ */
+/** Turns text into vectors. Swap it for a hosted model without touching the search. */
+export interface EmbeddingProvider {
+    /** Changes whenever the vectors would: part of the index version. */
+    readonly id: string;
+    embed(texts: readonly string[]): Float32Array[];
+}
+/** The same, for a provider that has to wait (a hosted embedding API). */
+export interface AsyncEmbeddingProvider {
+    readonly id: string;
+    embed(texts: readonly string[]): Promise<Float32Array[]>;
+}
+/** What each piece of a component's search document says about it. */
+export type FieldType = 'name' | 'purpose' | 'signal' | 'useWhen' | 'scenario' | 'action' | 'state' | 'event' | 'data';
+/** A component, as search sees it: what problem it solves (positive) and what it is not for (negative). Built from its capability — nothing is written for search alone. */
+export type SearchDocument = {
+    component: string;
+    /** Catalogue order: the stable tie-break. */
+    order: number;
+    positive: {
+        type: FieldType;
+        text: string;
+    }[];
+    negative: {
+        text: string;
+    }[];
+};
+export type SearchWeights = {
+    /** How much each kind of field counts when it is the closest to the query (0 leaves it out). */
+    fields: Record<FieldType, number>;
+    /** The semantic score is the mean of the best `topK` field similarities. */
+    topK: number;
+    /** How hard a query nearer to what a component is *not* for pushes it down. */
+    negative: number;
+    /** Before comparing: subtract the catalogue's mean vector (`mean`), and also its first principal component (`pc`) — what every document shares. */
+    centre: 'none' | 'mean' | 'pc';
+    semantic: number;
+    lexical: number;
+    /** The lexical score saturates: `s / (s + lexicalHalf)`. */
+    lexicalHalf: number;
+    /** Below this final score a component is not a candidate. */
+    minScore: number;
+    /** …nor if it scores below this share of the best one. */
+    relative: number;
+};
+export type ScoreBreakdown = {
+    component: string;
+    semantic: number | null;
+    negative: number | null;
+    lexical: number;
+    /** 1 when the component passes the request's filters (kinds), else 0. */
+    metadata: number;
+    /** 1 when the host may use it, else 0. */
+    availability: number;
+    final: number;
+};
+export type SearchOptions = {
+    /** Host policy: only these components may be offered. Absent → every approved component. */
+    available?: readonly string[];
+    /** Only components of these kinds. */
+    kinds?: readonly string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/agent/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/agent/search/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;CACjD;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAC1D;AAED,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAEvH,4KAA4K;AAC5K,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,gGAAgG;IAChG,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,mJAAmJ;IACnJ,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4FAA4F;IAC5F,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,sCAAsC;IACtC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC"}

package/dist/esm/agent/search/types.js

@@ -0,0 +1,7 @@
+/**
+ * **Component search — its internal types.** None of this is part of the agent contract: the agent
+ * calls `searchComponents(query)` and gets cards. How candidates are found — lexical, semantic,
+ * in memory or not — can change without it knowing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/agent/search/types.js.map

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

package/dist/esm/agent/search/weights.d.ts

@@ -0,0 +1,22 @@
+import type { SearchWeights } from './types';
+/**
+ * **The ranking weights — measured, not guessed.** Chosen on the dev half of the evaluation set
+ * (`tests/agent/search-eval.ts`) with `tools/search/tune.ts` and a threshold sweep; the test half is
+ * reported, never tuned on. The record of why is in docs/DECISIONS.md §19.
+ *
+ * - Every document field counts; the ones about what a person does with the component (actions,
+ *   states, events, data) a little less than what it is for.
+ * - The semantic score is the mean of the three closest fields, after removing the catalogue mean.
+ * - A query closer to a component's `avoidWhen` than to anything it is for is pushed down by half
+ *   the difference.
+ * - Lexical matching adds up to 0.3 — a confident phrase or name match keeps its place; a shared
+ *   word alone cannot outvote meaning.
+ * - A candidate needs 0.3, and 60% of the best — so an ambiguous request keeps its alternatives and
+ *   a clear one does not trail five weak ones. (Off-topic and on-topic scores overlap; 0.3 rejects
+ *   about half the off-topic requests without losing on-topic ones.)
+ *
+ * Measured and not adopted: word-level alignment, reciprocal rank fusion, hubness (CSLS) correction
+ * and principal-component removal — none beat this on the development data.
+ */
+export declare const DEFAULT_WEIGHTS: SearchWeights;
+//# sourceMappingURL=weights.d.ts.map

package/dist/esm/agent/search/weights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weights.d.ts","sourceRoot":"","sources":["../../../../src/agent/search/weights.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,EAAE,aAU7B,CAAC"}

package/dist/esm/agent/search/weights.js

@@ -0,0 +1,31 @@
+/**
+ * **The ranking weights — measured, not guessed.** Chosen on the dev half of the evaluation set
+ * (`tests/agent/search-eval.ts`) with `tools/search/tune.ts` and a threshold sweep; the test half is
+ * reported, never tuned on. The record of why is in docs/DECISIONS.md §19.
+ *
+ * - Every document field counts; the ones about what a person does with the component (actions,
+ *   states, events, data) a little less than what it is for.
+ * - The semantic score is the mean of the three closest fields, after removing the catalogue mean.
+ * - A query closer to a component's `avoidWhen` than to anything it is for is pushed down by half
+ *   the difference.
+ * - Lexical matching adds up to 0.3 — a confident phrase or name match keeps its place; a shared
+ *   word alone cannot outvote meaning.
+ * - A candidate needs 0.3, and 60% of the best — so an ambiguous request keeps its alternatives and
+ *   a clear one does not trail five weak ones. (Off-topic and on-topic scores overlap; 0.3 rejects
+ *   about half the off-topic requests without losing on-topic ones.)
+ *
+ * Measured and not adopted: word-level alignment, reciprocal rank fusion, hubness (CSLS) correction
+ * and principal-component removal — none beat this on the development data.
+ */
+export const DEFAULT_WEIGHTS = {
+    fields: { name: 1, purpose: 1, signal: 1, useWhen: 1, scenario: 1, action: 0.8, state: 0.8, event: 0.8, data: 0.8 },
+    topK: 3,
+    negative: 0.5,
+    centre: 'mean',
+    semantic: 1,
+    lexical: 0.3,
+    lexicalHalf: 6,
+    minScore: 0.3,
+    relative: 0.6,
+};
+//# sourceMappingURL=weights.js.map

package/dist/esm/agent/search/weights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weights.js","sourceRoot":"","sources":["../../../../src/agent/search/weights.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAkB;IAC5C,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE;IACnH,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,GAAG;IACb,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,GAAG;IACZ,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,GAAG;IACb,QAAQ,EAAE,GAAG;CACd,CAAC"}