@appinternalleads/ui 0.3.0 → 0.4.0

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

@@ -0,0 +1,42 @@
+import type { AgentCapability, CapabilityCard } from '../types';
+import { SearchIndex } from './searchIndex';
+import type { EmbeddingProvider, ScoreBreakdown, SearchDocument, SearchOptions, SearchWeights } from './types';
+/**
+ * **Component search: intent → candidates.**
+ *
+ *   normalizeQuery → retrieveCandidates (semantic + lexical) → applyEligibility → rankCandidates → cards
+ *
+ * Semantic similarity comes from an `EmbeddingProvider` over each component's search document
+ * (`document.ts`, derived from its capability); lexical similarity is 0.3.0's scorer. If semantic
+ * retrieval is unavailable — no provider, an index that fails to build, a query with no known
+ * words — the ranking is exactly the lexical one. Eligibility (approved, and allowed by the host)
+ * is applied after retrieval and is authoritative: relevance never makes a component usable.
+ * Ties break on catalogue order, so the same query and catalogue give the same list.
+ */
+export type SearchCard = CapabilityCard & {
+    score: number;
+};
+export type ComponentSearch = {
+    search(query: string, limit?: number, options?: SearchOptions): SearchCard[];
+    /** Development: every component's scores, best first — never part of the agent's result. */
+    explain(query: string, options?: SearchOptions): ScoreBreakdown[] & {
+        mode: 'hybrid' | 'lexical';
+        version: string;
+    };
+    /** The index in use (null when searching lexically). */
+    index(): SearchIndex | null;
+};
+export declare function searchCatalog(): {
+    caps: AgentCapability[];
+    docs: SearchDocument[];
+};
+export declare function createComponentSearch(opts: {
+    provider?: EmbeddingProvider | null;
+    weights: SearchWeights;
+    /** Where the documents come from — the approved catalogue by default. */
+    catalog?: () => {
+        caps: AgentCapability[];
+        docs: SearchDocument[];
+    };
+}): ComponentSearch;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/agent/search/search.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEhE,OAAO,EAAE,WAAW,EAA6D,MAAM,eAAe,CAAC;AAGvG,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE/G;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,UAAU,EAAE,CAAC;IAC7E,4FAA4F;IAC5F,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,EAAE,GAAG;QAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACpH,wDAAwD;IACxD,KAAK,IAAI,WAAW,GAAG,IAAI,CAAC;CAC7B,CAAC;AAOF,wBAAgB,aAAa,IAAI;IAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IAAC,IAAI,EAAE,cAAc,EAAE,CAAA;CAAE,CAMnF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACpC,OAAO,EAAE,aAAa,CAAC;IACvB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM;QAAE,IAAI,EAAE,eAAe,EAAE,CAAC;QAAC,IAAI,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CACrE,GAAG,eAAe,CAkGlB"}

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

@@ -0,0 +1,119 @@
+import { AGENT_COMPONENTS, describeComponent, isAgentComponent } from '../catalog';
+import { searchDocumentOf } from './document';
+import { SearchIndex, cosine, indexVersion } from './searchIndex';
+import { lexicalScore } from './lexical';
+import { normalizeQuery } from './normalize';
+const round = (x) => Math.round(x * 1000) / 1000;
+const cardOf = (c) => ({ component: c.component, name: c.name, kind: c.kind, purpose: c.purpose, signals: c.signals });
+/** The approved catalogue, in order, and its search documents — derived once per module. */
+let catalogCache = null;
+export function searchCatalog() {
+    if (!catalogCache) {
+        const caps = AGENT_COMPONENTS.map(id => describeComponent(id));
+        catalogCache = { caps, docs: caps.map((c, i) => searchDocumentOf(c, i, AGENT_COMPONENTS)) };
+    }
+    return catalogCache;
+}
+export function createComponentSearch(opts) {
+    const catalog = opts.catalog ?? searchCatalog;
+    const w = opts.weights;
+    let built = null;
+    let failed = null;
+    /* The index for the catalogue as it is now — rebuilt whenever its version (documents + provider) changes. */
+    const indexFor = (docs) => {
+        const provider = opts.provider;
+        if (!provider)
+            return null;
+        const version = indexVersion(docs, provider);
+        if (built?.version === version)
+            return built;
+        if (failed === version)
+            return null;
+        try {
+            built = new SearchIndex(provider, version).build(docs);
+            return built;
+        }
+        catch {
+            failed = version;
+            built = null;
+            return null;
+        }
+    };
+    const queryVector = (q, index) => {
+        try {
+            const v = index.provider.embed([q.text])[0];
+            if (!v || v.length !== index.mean?.length || !v.some(x => x !== 0) || v.some(x => !Number.isFinite(x)))
+                return null;
+            return v;
+        }
+        catch {
+            return null;
+        }
+    };
+    function retrieveCandidates(q) {
+        const { caps, docs } = catalog();
+        const index = q.empty ? null : indexFor(docs);
+        const qv = index ? queryVector(q, index) : null;
+        const centring = { mean: w.centre !== 'none' ? index?.mean ?? null : null, principal: w.centre === 'pc' ? index?.principal ?? null : null };
+        return {
+            mode: (qv ? 'hybrid' : 'lexical'),
+            version: index?.version ?? '',
+            candidates: caps.map((c, order) => {
+                const lexical = q.empty ? 0 : lexicalScore(c, q.original);
+                if (!qv || !index)
+                    return { cap: c, order, lexical, semantic: null, negative: null };
+                const e = index.entries.get(c.component);
+                if (!e)
+                    return { cap: c, order, lexical, semantic: null, negative: null };
+                const { pos, posMax } = fieldScore(qv, e, centring);
+                const neg = e.negative.length ? Math.max(...e.negative.map(n => cosine(qv, n, centring))) : 0;
+                return { cap: c, order, lexical, semantic: pos - w.negative * Math.max(0, neg - posMax), negative: neg };
+            }),
+        };
+    }
+    /* How close a query vector is to a component: the mean of its `topK` closest fields (weighted by kind), and the closest one. */
+    function fieldScore(qv, e, centring) {
+        const sims = e.positive.filter(p => w.fields[p.type] > 0).map(p => { const raw = cosine(qv, p.vector, centring); return { raw, weighted: w.fields[p.type] * raw }; });
+        const top = sims.map(x => x.weighted).sort((a, b) => b - a).slice(0, w.topK);
+        return { pos: top.length ? top.reduce((a, b) => a + b, 0) / top.length : 0, posMax: sims.length ? Math.max(...sims.map(x => x.raw)) : 0 };
+    }
+    const applyEligibility = (list, options = {}) => list.map(x => ({
+        ...x,
+        availability: isAgentComponent(x.cap.component) && (!options.available || options.available.includes(x.cap.component)) ? 1 : 0,
+        metadata: !options.kinds || options.kinds.includes(x.cap.kind) ? 1 : 0,
+    }));
+    function rankCandidates(query, options) {
+        const q = normalizeQuery(query);
+        const r = retrieveCandidates(q);
+        const scored = applyEligibility(r.candidates, options).map(x => ({
+            ...x,
+            final: r.mode === 'lexical' || x.semantic === null
+                ? x.lexical
+                : w.semantic * x.semantic + w.lexical * (x.lexical / (x.lexical + w.lexicalHalf)),
+        }));
+        scored.sort((a, b) => b.final - a.final || a.order - b.order);
+        return { ...r, scored };
+    }
+    return {
+        search(query, limit = 5, options) {
+            const r = rankCandidates(query, options);
+            const eligible = r.scored.filter(x => x.availability && x.metadata);
+            const kept = r.mode === 'lexical'
+                ? eligible.filter(x => x.final > 0)
+                : (() => { const best = eligible[0]?.final ?? 0; return eligible.filter(x => x.final >= w.minScore && (best <= 0 || x.final >= best * w.relative)); })();
+            return kept.slice(0, Math.max(0, limit)).map(x => ({ ...cardOf(x.cap), score: round(x.final) }));
+        },
+        explain(query, options) {
+            const r = rankCandidates(query, options);
+            const out = r.scored.map(x => ({
+                component: x.cap.component, semantic: x.semantic === null ? null : round(x.semantic), negative: x.negative === null ? null : round(x.negative),
+                lexical: round(x.lexical), metadata: x.metadata, availability: x.availability, final: round(x.final),
+            }));
+            out.mode = r.mode;
+            out.version = r.version;
+            return out;
+        },
+        index: () => indexFor(catalog().docs),
+    };
+}
+//# sourceMappingURL=search.js.map

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

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

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

@@ -0,0 +1,42 @@
+import type { EmbeddingProvider, FieldType, SearchDocument } from './types';
+/**
+ * **The search index — derived, rebuildable, never the source of truth.** Each component's document
+ * fields as vectors, plus the catalogue mean (for centring). Its `version` is the documents' hash
+ * plus the provider's id: if the catalogue or the model changes, the version does, and a cached
+ * index for the old one is never served (`indexFor`).
+ */
+export type IndexedDocument = {
+    component: string;
+    order: number;
+    positive: {
+        type: FieldType;
+        vector: Float32Array;
+    }[];
+    negative: Float32Array[];
+};
+export declare class SearchIndex {
+    readonly provider: EmbeddingProvider;
+    version: string;
+    readonly entries: Map<string, IndexedDocument>;
+    mean: Float32Array | null;
+    /** The first principal component of the (centred) document vectors — the direction every text shares most (SIF's common-component removal). */
+    principal: Float32Array | null;
+    constructor(provider: EmbeddingProvider, version: string);
+    /** Throw away everything and index these documents. */
+    build(docs: readonly SearchDocument[]): this;
+    /** Add or replace one component. */
+    upsert(doc: SearchDocument, allDocs?: readonly SearchDocument[]): this;
+    remove(component: string, allDocs?: readonly SearchDocument[]): this;
+    private put;
+    /** The mean of every positive field vector: what all documents share, subtracted before comparing when centring. */
+    private recentre;
+}
+export declare const indexVersion: (docs: readonly SearchDocument[], provider: EmbeddingProvider) => string;
+/** What is compared: the vector less the shared mean and, if given, less its projection on the shared direction. */
+export type Centring = {
+    mean: Float32Array | null;
+    principal: Float32Array | null;
+};
+/** Cosine similarity after centring. */
+export declare function cosine(a: Float32Array, b: Float32Array, c?: Centring): number;
+//# sourceMappingURL=searchIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"searchIndex.d.ts","sourceRoot":"","sources":["../../../../src/agent/search/searchIndex.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,CAAC;IACtD,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B,CAAC;AAEF,qBAAa,WAAW;IAKV,QAAQ,CAAC,QAAQ,EAAE,iBAAiB;IAAS,OAAO,EAAE,MAAM;IAJxE,QAAQ,CAAC,OAAO,+BAAsC;IACtD,IAAI,EAAE,YAAY,GAAG,IAAI,CAAQ;IACjC,+IAA+I;IAC/I,SAAS,EAAE,YAAY,GAAG,IAAI,CAAQ;gBACjB,QAAQ,EAAE,iBAAiB,EAAS,OAAO,EAAE,MAAM;IAExE,uDAAuD;IACvD,KAAK,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAQ5C,oCAAoC;IACpC,MAAM,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAMtE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAMpE,OAAO,CAAC,GAAG;IAWX,oHAAoH;IACpH,OAAO,CAAC,QAAQ;CAYjB;AAED,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,cAAc,EAAE,EAAE,UAAU,iBAAiB,WAAwC,CAAC;AAmBlI,oHAAoH;AACpH,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,CAAC;AASrF,wCAAwC;AACxC,wBAAgB,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,GAAE,QAA0C,GAAG,MAAM,CAK9G"}

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

@@ -0,0 +1,114 @@
+import { versionOf } from './document';
+export class SearchIndex {
+    provider;
+    version;
+    entries = new Map();
+    mean = null;
+    /** The first principal component of the (centred) document vectors — the direction every text shares most (SIF's common-component removal). */
+    principal = null;
+    constructor(provider, version) {
+        this.provider = provider;
+        this.version = version;
+    }
+    /** Throw away everything and index these documents. */
+    build(docs) {
+        this.entries.clear();
+        for (const d of docs)
+            this.put(d);
+        this.version = indexVersion(docs, this.provider);
+        return this.recentre();
+    }
+    /** Add or replace one component. */
+    upsert(doc, allDocs) {
+        this.put(doc);
+        if (allDocs)
+            this.version = indexVersion(allDocs, this.provider);
+        return this.recentre();
+    }
+    remove(component, allDocs) {
+        this.entries.delete(component);
+        if (allDocs)
+            this.version = indexVersion(allDocs, this.provider);
+        return this.recentre();
+    }
+    put(d) {
+        const vectors = this.provider.embed([...d.positive.map(p => p.text), ...d.negative.map(n => n.text)]);
+        if (vectors.length !== d.positive.length + d.negative.length)
+            throw new Error(`${this.provider.id} returned ${vectors.length} vectors for ${d.component}`);
+        this.entries.set(d.component, {
+            component: d.component,
+            order: d.order,
+            positive: d.positive.map((p, i) => ({ type: p.type, vector: vectors[i] })),
+            negative: vectors.slice(d.positive.length),
+        });
+    }
+    /** The mean of every positive field vector: what all documents share, subtracted before comparing when centring. */
+    recentre() {
+        let sum = null;
+        let n = 0;
+        for (const e of this.entries.values())
+            for (const p of e.positive) {
+                sum ??= new Float32Array(p.vector.length);
+                for (let i = 0; i < sum.length; i++)
+                    sum[i] += p.vector[i];
+                n++;
+            }
+        if (sum && n)
+            for (let i = 0; i < sum.length; i++)
+                sum[i] /= n;
+        this.mean = sum;
+        this.principal = sum ? firstComponent([...this.entries.values()].flatMap(e => e.positive.map(p => p.vector)), sum) : null;
+        return this;
+    }
+}
+export const indexVersion = (docs, provider) => `${versionOf(docs)}:${provider.id}`;
+/** Power iteration — deterministic start, fixed iterations. */
+function firstComponent(vectors, mean) {
+    const d = mean.length;
+    let u = new Float32Array(d).fill(1 / Math.sqrt(d));
+    for (let it = 0; it < 30; it++) {
+        const next = new Float32Array(d);
+        for (const v of vectors) {
+            let dot = 0;
+            for (let i = 0; i < d; i++)
+                dot += (v[i] - mean[i]) * u[i];
+            for (let i = 0; i < d; i++)
+                next[i] += dot * (v[i] - mean[i]);
+        }
+        let n = 0;
+        for (const x of next)
+            n += x * x;
+        n = Math.sqrt(n) || 1;
+        for (let i = 0; i < d; i++)
+            next[i] /= n;
+        u = next;
+    }
+    return u;
+}
+function centred(v, c) {
+    if (!c.mean && !c.principal)
+        return v;
+    const out = new Float32Array(v.length);
+    for (let i = 0; i < v.length; i++)
+        out[i] = v[i] - (c.mean ? c.mean[i] : 0);
+    if (c.principal) {
+        let dot = 0;
+        for (let i = 0; i < v.length; i++)
+            dot += out[i] * c.principal[i];
+        for (let i = 0; i < v.length; i++)
+            out[i] -= dot * c.principal[i];
+    }
+    return out;
+}
+/** Cosine similarity after centring. */
+export function cosine(a, b, c = { mean: null, principal: null }) {
+    const x = centred(a, c), y = centred(b, c);
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < x.length; i++) {
+        dot += x[i] * y[i];
+        na += x[i] * x[i];
+        nb += y[i] * y[i];
+    }
+    return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
+//# sourceMappingURL=searchIndex.js.map

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

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

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"}