@indexnetwork/protocol 22.0.0-rc.498.1 → 64.0.0-rc.604.2

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

@@ -1,397 +0,0 @@
-/**
- * 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 './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/opportunity.graph.evaluation.d.ts

@@ -1,82 +0,0 @@
-/**
- * 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/agent.module.js';
-import type { CandidateMatch, EvaluatedOpportunity } from './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;