@appinternalleads/ui 0.3.0 → 0.4.0

package/src/agent/search/types.ts

@@ -0,0 +1,68 @@
+/**
+ * **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[];
+};

package/src/agent/search/weights.ts

@@ -0,0 +1,32 @@
+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 const DEFAULT_WEIGHTS: SearchWeights = {
+  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,
+};

package/src/index.ts

@@ -16,5 +16,5 @@ export * from './widgets';
    nothing is implemented. See docs/architecture/COMPONENT-FAMILIES.md. */
 export * from './components';
 export * from './sheets';
-/* The agent component contract: search, describe, render/1, validation, result/1. */
+/* The agent component contract for the renderer: AgentComponent, describe, render/1 validation, result/1. Search is in `@appinternalleads/ui/agent`. */
 export * from './agent';