@indexnetwork/protocol 14.3.2-rc.477.1 → 17.0.0-rc.479.1

package/dist/opportunities/application/opportunity.graph.discovery.js

@@ -0,0 +1,397 @@
+/**
+ * Discovery pipeline, stage 3: candidate retrieval.
+ *
+ * Three shapes share this node — a direct-connection fast path, a
+ * context-sourced path, and the intent/query HyDE path. The retrieval
+ * strategies themselves live in `opportunity.graph.discovery-strategies.ts`.
+ */
+import { getModelName } from '../../shared/agent/model.config.js';
+import { timed } from '../../shared/observability/performance.js';
+import { withCandidateEvidence } from '../domain/opportunity.evidence.js';
+import { discoveryIntentMatchingEnabled, discoveryProfileMatchingEnabled, discoveryProfileSource } from '../discovery.env.js';
+import { buildDiscovererContext, discoveryLog } from './opportunity.graph.shared.js';
+import { auxiliaryStrategyTraces, collectHydeResults, computeLensStats, mergeStrategyCandidates, runAuxiliaryStrategies, runQueryHydeDiscovery, toLensEmbeddings } from './opportunity.graph.discovery-strategies.js';
+// Search limits - fixed values for candidate retrieval
+// (The options.limit controls final output, not search pool)
+const LIMIT_PER_STRATEGY = 30;
+const PER_INDEX_LIMIT = 80;
+/**
+ * Node 3: Discovery
+ * Generates HyDE embeddings and performs semantic search.
+ */
+export async function discoveryNode(state, deps) {
+    return timed("OpportunityGraph.discovery", async () => {
+        const startTime = Date.now();
+        const discoveryUserId = state.onBehalfOfUserId ?? state.userId;
+        /** Filter candidates to targetUserId when set (direct-connection mode). */
+        const filterByTarget = (candidates) => {
+            if (!state.targetUserId)
+                return candidates;
+            const filtered = candidates.filter(c => c.candidateUserId === state.targetUserId);
+            discoveryLog.verbose('targetUserId filter applied', {
+                targetUserId: state.targetUserId,
+                before: candidates.length,
+                after: filtered.length,
+            });
+            return filtered;
+        };
+        discoveryLog.verbose('Starting semantic search', {
+            targetIndexesCount: state.targetNetworks.length,
+            discoverySource: state.discoverySource,
+            searchQueryPreview: state.searchQuery?.trim().slice(0, 60) ?? '(none)',
+        });
+        try {
+            if (state.targetNetworks.length === 0) {
+                discoveryLog.warn('No target indexes for search');
+                return { candidates: [] };
+            }
+            if (state.targetUserId) {
+                return await discoverDirectConnection(state, deps, discoveryUserId, startTime);
+            }
+            // Discovery match-type gating (DISCOVERY_ALLOWED_TYPES / DISCOVERY_PROFILE_SOURCE).
+            const ctx = {
+                state,
+                deps,
+                discoveryUserId,
+                limitPerStrategy: LIMIT_PER_STRATEGY,
+                perIndexLimit: PER_INDEX_LIMIT,
+                corpusGating: {
+                    intents: discoveryIntentMatchingEnabled(),
+                    profile: discoveryProfileMatchingEnabled(),
+                    profileCorpus: discoveryProfileSource(),
+                },
+                intentResultsEnabled: discoveryIntentMatchingEnabled(),
+                premiseResultsEnabled: discoveryProfileMatchingEnabled() && discoveryProfileSource() === 'premise',
+                contextResultsEnabled: discoveryProfileMatchingEnabled() && discoveryProfileSource() === 'user_context',
+            };
+            if (state.discoverySource === 'context') {
+                return await discoverFromContext(ctx, filterByTarget, startTime);
+            }
+            return await discoverFromIntent(ctx, filterByTarget, startTime);
+        }
+        catch (error) {
+            const errMsg = error instanceof Error ? error.message : String(error);
+            discoveryLog.error('Failed', { error });
+            return {
+                candidates: [],
+                error: 'Failed to search for candidates.',
+                trace: [{
+                        node: "discovery_fatal",
+                        detail: `Discovery failed: ${errMsg}`,
+                        data: { error: errMsg },
+                    }],
+            };
+        }
+    });
+}
+/**
+ * Direct-connection fast path.
+ * When targetUserId is set (user @-mentioned someone), bypass vector search
+ * and construct candidates directly from shared networks.
+ */
+async function discoverDirectConnection(state, deps, discoveryUserId, startTime) {
+    const targetUserId = state.targetUserId;
+    if (targetUserId === discoveryUserId) {
+        discoveryLog.warn('Direct-connection target matches discoverer; skipping self-match', { targetUserId });
+        return {
+            candidates: [],
+            trace: [{
+                    node: "discovery",
+                    detail: "Direct connection skipped: target user is discoverer",
+                    data: { targetUserId },
+                }],
+        };
+    }
+    discoveryLog.verbose('Direct-connection mode — bypassing vector search', { targetUserId });
+    const targetMemberships = await deps.database.getNetworkMemberships(targetUserId);
+    const targetUserIndexIds = targetMemberships.map(m => m.networkId);
+    const sharedIndexIds = state.targetNetworks
+        .filter(ti => targetUserIndexIds.includes(ti.networkId))
+        .map(ti => ti.networkId);
+    if (sharedIndexIds.length === 0) {
+        discoveryLog.warn('Target user shares no indexes with discoverer', {
+            targetUserId,
+            discovererIndexes: state.targetNetworks.map(ti => ti.networkId),
+        });
+        return {
+            candidates: [],
+            trace: [{
+                    node: "discovery",
+                    detail: `Direct connection: target user shares no indexes`,
+                    data: { targetUserId },
+                }],
+        };
+    }
+    // Fetch target user's active intents to build intent-level candidates
+    const targetIntents = await deps.database.getActiveIntents(targetUserId);
+    const directCandidates = [];
+    if (targetIntents.length > 0) {
+        // Build one candidate per intent per shared network it belongs to
+        for (const intent of targetIntents) {
+            const intentNetworkIds = await deps.database.getNetworkIdsForIntent(intent.id);
+            const overlapping = sharedIndexIds.filter(id => intentNetworkIds.includes(id));
+            for (const networkId of overlapping) {
+                directCandidates.push(withCandidateEvidence({
+                    candidateUserId: targetUserId,
+                    candidateIntentId: intent.id,
+                    networkId,
+                    similarity: 1.0,
+                    lens: 'explicit_mention',
+                    candidatePayload: intent.payload,
+                    candidateSummary: intent.summary ?? undefined,
+                    discoverySource: 'query',
+                }));
+            }
+        }
+    }
+    // Always add a profile-level candidate (so evaluation runs even without intents)
+    if (directCandidates.length === 0) {
+        directCandidates.push(withCandidateEvidence({
+            candidateUserId: targetUserId,
+            networkId: sharedIndexIds[0],
+            similarity: 1.0,
+            lens: 'explicit_mention',
+            candidatePayload: '',
+            candidateSummary: undefined,
+            discoverySource: 'query',
+        }));
+    }
+    discoveryLog.verbose('Direct candidates constructed', {
+        count: directCandidates.length,
+        sharedIndexes: sharedIndexIds.length,
+        targetIntents: targetIntents.length,
+    });
+    return {
+        candidates: directCandidates,
+        trace: [{
+                node: "discovery",
+                detail: `Direct connection → ${directCandidates.length} candidate(s) from ${sharedIndexIds.length} shared network(es)`,
+                data: {
+                    targetUserId,
+                    candidateCount: directCandidates.length,
+                    sharedIndexes: sharedIndexIds.length,
+                    durationMs: Date.now() - startTime,
+                },
+            }],
+    };
+}
+/**
+ * Context source: HyDE (when a search query exists) plus the additive
+ * premise/context strategies.
+ */
+async function discoverFromContext(ctx, filterByTarget, startTime) {
+    const { state } = ctx;
+    if (state.searchQuery?.trim()) {
+        discoveryLog.verbose('Context source with searchQuery → running query HyDE + premise paths', {
+            searchQuery: state.searchQuery.trim().substring(0, 80),
+        });
+        const queryResult = await runQueryHydeDiscovery(ctx);
+        const queryCandidates = queryResult?.candidates ?? [];
+        discoveryLog.verbose('Query HyDE path complete', { candidatesFound: queryCandidates.length });
+        const traceEntries = [];
+        // Lens input trace (captured from runQueryHydeDiscovery)
+        if (queryResult) {
+            traceEntries.push({
+                node: "lens_input",
+                detail: "Profile context for lens inference",
+                data: queryResult.lensInput,
+            });
+            // Lens output and HyDE document traces
+            if (queryResult.hydeOutput.lenses.length > 0) {
+                traceEntries.push({
+                    node: "lens_output",
+                    detail: `Inferred ${queryResult.hydeOutput.lenses.length} lens(es): ${queryResult.hydeOutput.lenses.map(l => l.label).join(', ')}`,
+                    data: { lenses: queryResult.hydeOutput.lenses, model: getModelName("lensInferrer") },
+                });
+            }
+            for (const [lens, doc] of Object.entries(queryResult.hydeOutput.hydeDocuments)) {
+                if (doc?.hydeText) {
+                    traceEntries.push({
+                        node: "hyde_query",
+                        detail: `[${lens}] "${doc.hydeText.slice(0, 120)}${doc.hydeText.length > 120 ? '...' : ''}"`,
+                        data: { lens, hydeTextPreview: doc.hydeText.slice(0, 300) + (doc.hydeText.length > 300 ? '...' : '') },
+                    });
+                }
+            }
+        }
+        traceEntries.push({
+            node: "discovery",
+            detail: `HyDE search → ${queryCandidates.length} candidate(s) from query path`,
+            data: {
+                candidateCount: queryCandidates.length,
+                byLens: computeLensStats(queryCandidates),
+                searchQuery: state.searchQuery?.trim().slice(0, 80),
+                durationMs: Date.now() - startTime,
+                model: getModelName("hydeGenerator"),
+            },
+        });
+        const [premiseCands, contextCands, contextSimCands] = await runAuxiliaryStrategies(ctx);
+        const withPremisesAndContext = mergeStrategyCandidates(queryCandidates, premiseCands, contextCands, contextSimCands);
+        traceEntries.push(...auxiliaryStrategyTraces(premiseCands, contextCands, contextSimCands));
+        return { candidates: filterByTarget(withPremisesAndContext), trace: traceEntries };
+    }
+    // No search query — premise-to-premise + context-to-intent discovery
+    const [premiseCands, contextCands, contextSimCands] = await runAuxiliaryStrategies(ctx);
+    if (premiseCands.length > 0 || contextCands.length > 0 || contextSimCands.length > 0) {
+        const merged = mergeStrategyCandidates(premiseCands, contextCands, contextSimCands);
+        const traceEntries = auxiliaryStrategyTraces(premiseCands, contextCands, contextSimCands);
+        traceEntries.push({
+            node: "discovery",
+            detail: `${[premiseCands.length > 0 && 'premise-to-premise', contextCands.length > 0 && 'context-to-intent', contextSimCands.length > 0 && 'context-to-context'].filter(Boolean).length} strategies → ${premiseCands.length + contextCands.length + contextSimCands.length} raw, ${merged.length} after dedup`,
+        });
+        return { candidates: filterByTarget(merged), trace: traceEntries };
+    }
+    return { candidates: [] };
+}
+/**
+ * Intent source: HyDE over the resolved intent's payload (or the search query),
+ * then the additive strategies on top.
+ */
+async function discoverFromIntent(ctx, filterByTarget, startTime) {
+    const { state, deps, discoveryUserId } = ctx;
+    const resolvedIntent = state.resolvedTriggerIntentId
+        ? state.indexedIntents.find((i) => i.intentId === state.resolvedTriggerIntentId)
+        : state.indexedIntents[0];
+    const searchText = state.searchQuery ?? resolvedIntent?.payload ?? '';
+    if (!searchText) {
+        discoveryLog.warn('No search text available for intent path');
+        const [premiseCands, contextCands, contextSimCands] = await runAuxiliaryStrategies(ctx);
+        const merged = mergeStrategyCandidates(premiseCands, contextCands, contextSimCands);
+        if (merged.length > 0) {
+            return {
+                candidates: filterByTarget(merged),
+                trace: [{ node: "discovery", detail: `No search text; premise → ${premiseCands.length}, context → ${contextCands.length}, context-sim → ${contextSimCands.length}, merged → ${merged.length} candidate(s)` }],
+            };
+        }
+        return { candidates: [] };
+    }
+    const discovererContext = buildDiscovererContext(state.sourceProfile, state.indexedIntents);
+    const discoveryLensInput = {
+        profileContext: discovererContext,
+        model: getModelName("lensInferrer"),
+    };
+    const hydeResult = await deps.hydeGenerator.invoke({
+        sourceType: 'query',
+        sourceText: searchText,
+        forceRegenerate: false,
+        profileContext: discovererContext,
+    });
+    const hydeEmbeddings = hydeResult.hydeEmbeddings;
+    const lenses = hydeResult.lenses ?? [];
+    if (!hydeEmbeddings || Object.keys(hydeEmbeddings).length === 0) {
+        const [premiseCands, contextCands, contextSimCands] = await runAuxiliaryStrategies(ctx);
+        const merged = mergeStrategyCandidates(premiseCands, contextCands, contextSimCands);
+        if (merged.length > 0) {
+            return {
+                hydeEmbeddings: {},
+                candidates: filterByTarget(merged),
+                trace: [{ node: "discovery", detail: `No HyDE embeddings; premise → ${premiseCands.length}, context → ${contextCands.length}, context-sim → ${contextSimCands.length}, merged → ${merged.length} candidate(s)` }],
+            };
+        }
+        return { hydeEmbeddings: {}, candidates: [] };
+    }
+    const lensEmbeddings = toLensEmbeddings(hydeEmbeddings, lenses);
+    const allCandidates = [];
+    await Promise.all(state.targetNetworks.map(async (targetIndex) => {
+        const results = await deps.embedder.searchWithHydeEmbeddings(lensEmbeddings, {
+            indexScope: [targetIndex.networkId],
+            excludeUserId: discoveryUserId,
+            limitPerStrategy: ctx.limitPerStrategy,
+            limit: ctx.perIndexLimit,
+            minScore: deps.retrievalMinSimilarity,
+            corpusGating: ctx.corpusGating,
+        });
+        allCandidates.push(...collectHydeResults(results, targetIndex.networkId, ctx));
+    }));
+    const byUserAndIndex = new Map();
+    for (const c of allCandidates) {
+        const entityKey = c.candidateIntentId
+            ? `intent:${c.candidateIntentId}`
+            : c.candidatePremiseId
+                ? `premise:${c.candidatePremiseId}`
+                : `context:${c.candidateContextId}`;
+        const key = `${c.candidateUserId}:${c.networkId}:${entityKey}`;
+        if (!byUserAndIndex.has(key) || c.similarity > (byUserAndIndex.get(key)?.similarity ?? 0)) {
+            byUserAndIndex.set(key, c);
+        }
+    }
+    const candidates = Array.from(byUserAndIndex.values());
+    discoveryLog.verbose('Intent-path discovery complete', { candidatesFound: candidates.length });
+    const usedLenses = Object.keys(hydeEmbeddings);
+    // Build trace with individual candidate similarity scores
+    const traceEntries = [{
+            node: "lens_input",
+            detail: "Profile context for lens inference",
+            data: discoveryLensInput,
+        }];
+    if (lenses.length > 0) {
+        traceEntries.push({
+            node: "lens_output",
+            detail: `Inferred ${lenses.length} lens(es): ${lenses.map(l => l.label).join(', ')}`,
+            data: { lenses, model: getModelName("lensInferrer") },
+        });
+    }
+    traceEntries.push({
+        node: "discovery",
+        detail: `Query: "${searchText.slice(0, 50)}${searchText.length > 50 ? '...' : ''}" → ${candidates.length} candidate(s)`,
+        data: {
+            query: searchText.slice(0, 100),
+            lenses: usedLenses,
+            candidateCount: candidates.length,
+            byLens: computeLensStats(candidates),
+            durationMs: Date.now() - startTime,
+            model: getModelName("hydeGenerator"),
+        },
+    });
+    // Show the HyDE-generated hypothetical documents used for search
+    const hydeDocuments = hydeResult.hydeDocuments;
+    if (hydeDocuments) {
+        for (const [lens, doc] of Object.entries(hydeDocuments)) {
+            if (doc?.hydeText) {
+                traceEntries.push({
+                    node: "hyde_query",
+                    detail: `[${lens}] "${doc.hydeText.slice(0, 120)}${doc.hydeText.length > 120 ? '...' : ''}"`,
+                    data: {
+                        lens,
+                        hydeTextPreview: doc.hydeText.slice(0, 160) + (doc.hydeText.length > 160 ? '...' : ''),
+                    },
+                });
+            }
+        }
+    }
+    // Add top candidates with similarity scores
+    const sortedCandidates = [...candidates].sort((a, b) => b.similarity - a.similarity).slice(0, 10);
+    for (const c of sortedCandidates) {
+        traceEntries.push({
+            node: "match",
+            detail: `Similarity ${Math.round(c.similarity * 100)}% via ${c.lens}`,
+            data: {
+                userId: c.candidateUserId,
+                similarity: Math.round(c.similarity * 100),
+                lens: c.lens,
+                hasIntent: !!c.candidateIntentId,
+            },
+        });
+    }
+    const [premiseCands, contextCands, contextSimCands] = await runAuxiliaryStrategies(ctx);
+    const allStrategies = mergeStrategyCandidates(candidates, premiseCands, contextCands, contextSimCands);
+    if (premiseCands.length > 0 || contextCands.length > 0 || contextSimCands.length > 0) {
+        traceEntries.push({
+            node: "discovery",
+            detail: `+ Premise → ${premiseCands.length}, Context → ${contextCands.length}, Context-sim → ${contextSimCands.length}, merged to ${allStrategies.length} candidate(s)`,
+        });
+    }
+    return {
+        hydeEmbeddings: hydeEmbeddings,
+        candidates: filterByTarget(allStrategies),
+        trace: traceEntries,
+    };
+}
+/** Trace summary for {@link discoveryNode}. */
+export function discoveryTraceSummary(result) {
+    const r = result;
+    if (r?.error)
+        return `error: ${r.error}`;
+    const candidates = r?.candidates;
+    return candidates ? `Found ${candidates.length} candidate(s)` : undefined;
+}

package/dist/opportunities/application/opportunity.graph.evaluation.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Discovery pipeline, stages 4–5: evaluation and ranking.
+ *
+ * Evaluation builds an entity bundle from the discoverer plus the top candidates,
+ * asks the evaluator to score them, and maps the verdicts back onto graph state.
+ */
+import type { DebugMetaAgent } from '../../agents/index.js';
+import type { CandidateMatch, EvaluatedOpportunity } from '../domain/opportunity.state.js';
+import { type OpportunityGraphDeps, type OpportunityState } from './opportunity.graph.shared.js';
+/**
+ * Node 3: Evaluation (Entity bundle)
+ * Builds entity bundle from source + candidates, invokes entity-bundle evaluator, maps to EvaluatedOpportunity with networkId from entities.
+ */
+export declare function evaluationNode(state: OpportunityState, deps: OpportunityGraphDeps): Promise<{
+    evaluatedOpportunities: never[];
+    agentTimings: never[];
+    candidates?: undefined;
+    remainingCandidates?: undefined;
+    error?: undefined;
+    trace?: undefined;
+} | {
+    candidates: never[];
+    evaluatedOpportunities: never[];
+    remainingCandidates: never[];
+    error: string;
+    agentTimings: never[];
+    trace?: undefined;
+} | {
+    candidates: never[];
+    evaluatedOpportunities: never[];
+    remainingCandidates: never[];
+    agentTimings: never[];
+    error?: undefined;
+    trace?: undefined;
+} | {
+    candidates: CandidateMatch[];
+    evaluatedOpportunities: EvaluatedOpportunity[];
+    remainingCandidates: CandidateMatch[];
+    trace: {
+        node: string;
+        detail?: string;
+        data?: Record<string, unknown>;
+    }[];
+    agentTimings: DebugMetaAgent[];
+    error?: undefined;
+} | {
+    evaluatedOpportunities: never[];
+    error: string;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+            candidateCount: number;
+            durationMs: number;
+        };
+    }[];
+    agentTimings: DebugMetaAgent[];
+    candidates?: undefined;
+    remainingCandidates?: undefined;
+}>;
+/**
+ * Node 4: Ranking
+ * Sorts evaluated opportunities by score, applies limit, dedupes by actor-set hash.
+ */
+export declare function rankingNode(state: OpportunityState): Promise<{
+    evaluatedOpportunities: EvaluatedOpportunity[];
+    error?: undefined;
+    trace?: undefined;
+} | {
+    evaluatedOpportunities: never[];
+    error: string;
+    trace: {
+        node: string;
+        detail: string;
+        data: {
+            error: string;
+        };
+    }[];
+}>;
+/** Trace summary for {@link rankingNode}. */
+export declare function rankingTraceSummary(result: unknown): string | undefined;