@indexnetwork/protocol 22.0.0-rc.499.1 → 64.0.0

package/dist/opportunities/opportunity.enricher.js

@@ -1,280 +0,0 @@
-/**
- * Opportunity enricher: when creating an opportunity, find overlapping existing
- * opportunities (by non-introducer actor userId), check semantic relatedness, and
- * optionally merge into a single enriched opportunity and expire the old one(s).
- */
-import { getAbortSignalConfig } from '../shared/agent/model-signal.js';
-import { protocolLogger } from '../shared/observability/protocol.logger.js';
-const logger = protocolLogger('OpportunityEnricher');
-const DEFAULT_SIMILARITY_THRESHOLD = 0.7;
-const MIN_REASONING_LENGTH_FOR_EMBEDDING = 10;
-/**
- * Statuses excluded from the merge-candidate pool by default.
- *
- * - 'accepted': the pair already connected — do NOT fold a new discovery into
- *   the historical opp. IND-237 surfaces the existing conversation separately.
- * - 'negotiating': a negotiation is in-flight for this pair; rolling a new
- *   candidate into it would blur the outcome of the active turn. Wait for the
- *   negotiation to finalize (→ draft/pending/rejected/stalled) first, then
- *   enrichment can pick it up on the next pass.
- * - 'expired': already superseded by a later enriched opportunity. Without this
- *   exclusion, each enrichment cycle re-merges previously-expired enriched
- *   opportunities, compounding their actor arrays into 100+ entries.
- *
- * Exported for callers that want to extend rather than replace the default.
- */
-export const DEFAULT_ENRICHER_EXCLUDE_STATUSES = ['accepted', 'negotiating', 'expired'];
-/**
- * Cosine similarity between two vectors (0–1).
- */
-function cosineSimilarity(a, b) {
-    if (a.length !== b.length || a.length === 0)
-        return 0;
-    let dot = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dot += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    const denom = Math.sqrt(normA) * Math.sqrt(normB);
-    if (denom === 0)
-        return 0;
-    const sim = dot / denom;
-    return Math.max(0, Math.min(1, sim));
-}
-/**
- * Resolve enriched opportunity status from related opportunities' statuses and the incoming status.
- * Priority: accepted > pending > rejected > stalled > draft (only when incoming is draft) > latent.
- * The incoming status is included so we do not wrongly downgrade when the new opportunity has a higher-priority status.
- * When incoming is 'draft' (e.g. from in-chat discovery), we preserve draft so the opportunity stays chat-only and
- * does not appear on the radar view (radar excludes draft).
- * When incoming is NOT draft (e.g. 'latent' from the background broker), existing draft status does NOT contaminate
- * the result — the broker-created opportunity retains its own status and can appear on the radar view.
- */
-function resolveEnrichedStatus(relatedStatuses, incomingStatus) {
-    const statuses = incomingStatus ? [...relatedStatuses, incomingStatus] : relatedStatuses;
-    if (statuses.includes('accepted'))
-        return 'accepted';
-    if (statuses.includes('pending'))
-        return 'pending';
-    if (statuses.includes('rejected'))
-        return 'rejected';
-    if (statuses.includes('stalled'))
-        return 'stalled';
-    if (incomingStatus === 'draft')
-        return 'draft';
-    return 'latent';
-}
-/**
- * Extract non-introducer actor userIds from create data.
- */
-function getNonIntroducerUserIds(data) {
-    const ids = data.actors
-        .filter((a) => a.role !== 'introducer')
-        .map((a) => a.userId);
-    return [...new Set(ids)];
-}
-/**
- * Extract intent IDs from actors.
- */
-function belongsToOwnedIntent(opportunity, scope) {
-    if (opportunity.detection.triggeredBy === scope.triggerIntentId)
-        return true;
-    return opportunity.actors.some((actor) => actor.userId === scope.ownerUserId && actor.intent === scope.triggerIntentId);
-}
-function getIntentIdsFromActors(actors) {
-    const ids = new Set();
-    for (const a of actors) {
-        if (a.intent)
-            ids.add(a.intent);
-    }
-    return ids;
-}
-/**
- * Check if two opportunities share at least one intent ID.
- */
-function shareIntentIds(newData, existing) {
-    const newIntents = getIntentIdsFromActors(newData.actors);
-    const existingIntents = getIntentIdsFromActors(existing.actors);
-    for (const id of newIntents) {
-        if (existingIntents.has(id))
-            return true;
-    }
-    return false;
-}
-/**
- * Merge actors from new data and existing opportunities: union by (networkId, userId, intent),
- * preserving all unique introducers and preferring newer role on conflict.
- */
-function mergeActors(newData, existingList) {
-    const key = (a) => `${a.networkId}:${a.userId}:${a.intent ?? ''}`;
-    const map = new Map();
-    // Add all from existing first (older)
-    for (const opp of existingList) {
-        for (const a of opp.actors) {
-            map.set(key(a), a);
-        }
-    }
-    // Add/overwrite with new (newer wins for same key, e.g. role)
-    for (const a of newData.actors) {
-        map.set(key(a), a);
-    }
-    return [...map.values()];
-}
-/**
- * Merge interpretation: single reasoning (new data only), max confidence, merged signals.
- * We use only the new opportunity's reasoning to avoid repetitive concatenation when
- * multiple overlapping opportunities share the same or similar text (e.g. same pair
- * across indexes), which previously produced long duplicated paragraphs in chat cards.
- */
-function mergeInterpretation(newData, existingList) {
-    const reasoning = newData.interpretation.reasoning;
-    let maxConf = typeof newData.interpretation.confidence === 'number'
-        ? newData.interpretation.confidence
-        : parseFloat(String(newData.interpretation.confidence ?? 0));
-    for (const o of existingList) {
-        const c = o.interpretation?.confidence;
-        const cNum = typeof c === 'number' ? c : parseFloat(String(c ?? 0));
-        if (cNum > maxConf)
-            maxConf = cNum;
-    }
-    const confidence = maxConf;
-    const signals = [
-        ...(newData.interpretation.signals ?? []),
-        ...existingList.flatMap((o) => o.interpretation?.signals ?? []),
-    ];
-    const seen = new Set();
-    const dedupedSignals = signals.filter((s) => {
-        const k = `${s.type}:${s.detail ?? ''}`;
-        if (seen.has(k))
-            return false;
-        seen.add(k);
-        return true;
-    });
-    return {
-        category: newData.interpretation.category,
-        reasoning,
-        confidence: typeof confidence === 'string' ? parseFloat(confidence) : confidence,
-        signals: dedupedSignals.length > 0 ? dedupedSignals : newData.interpretation.signals,
-    };
-}
-/**
- * Enrich or create: find overlapping opportunities, filter by semantic relatedness
- * using a two-phase approach, merge actors and interpretation into a single
- * CreateOpportunityData, and return the data plus IDs to expire. If no related
- * overlap, return original data unchanged.
- *
- * Phase 1 — Intent check (free, no API call):
- *   Shared intent IDs mean the same declared user goal drove both opportunities.
- *   This is rare because the IntentReconciler already deduplicates intents per-user
- *   upstream, but when it fires it is definitive.
- *
- * Phase 2 — Batched embedding similarity (one API call for all remaining):
- *   For opportunities without shared intents, embed all reasoning texts in a single
- *   batch call and compare cosine similarity. Cross-user intent comparison (e.g.
- *   Alice's "find ML co-founder" vs Bob's "join ML startup") is implicitly handled
- *   here since reasoning text synthesizes both users' intents.
- */
-export async function enrichOrCreate(database, embedder, newData, options) {
-    const actorUserIds = getNonIntroducerUserIds(newData);
-    if (actorUserIds.length === 0) {
-        return { enriched: false, data: newData };
-    }
-    const excludeStatuses = options?.excludeStatuses ?? DEFAULT_ENRICHER_EXCLUDE_STATUSES;
-    const pairOverlaps = await database.findOpportunitiesByActors(actorUserIds, { excludeStatuses });
-    const ownedIntentScope = options?.ownedIntentScope;
-    const overlapping = ownedIntentScope
-        ? pairOverlaps.filter((opportunity) => belongsToOwnedIntent(opportunity, ownedIntentScope))
-        : pairOverlaps;
-    if (ownedIntentScope && pairOverlaps.length > overlapping.length) {
-        logger.info('Excluded cross-trigger overlaps from owned-intent enrichment', {
-            triggerIntentId: ownedIntentScope.triggerIntentId,
-            pairOverlapCount: pairOverlaps.length,
-            sameTriggerOverlapCount: overlapping.length,
-        });
-    }
-    if (overlapping.length === 0) {
-        return { enriched: false, data: newData };
-    }
-    const threshold = options?.similarityThreshold ?? DEFAULT_SIMILARITY_THRESHOLD;
-    // Phase 1: Intent-based relatedness (free, strongest signal)
-    const related = [];
-    const remaining = [];
-    for (const opp of overlapping) {
-        if (shareIntentIds(newData, opp)) {
-            related.push(opp);
-        }
-        else {
-            remaining.push(opp);
-        }
-    }
-    // Phase 2: Batched embedding similarity (one API call for all remaining)
-    if (remaining.length > 0) {
-        const newReasoning = (newData.interpretation?.reasoning ?? '').trim();
-        // Only embed opps where both reasonings are long enough
-        const embeddable = [];
-        for (const opp of remaining) {
-            const existingReasoning = (opp.interpretation?.reasoning ?? '').trim();
-            if (newReasoning.length >= MIN_REASONING_LENGTH_FOR_EMBEDDING &&
-                existingReasoning.length >= MIN_REASONING_LENGTH_FOR_EMBEDDING) {
-                embeddable.push(opp);
-            }
-            // Short reasoning + no shared intents (Phase 1 missed) → not related
-        }
-        if (embeddable.length > 0) {
-            try {
-                const textsToEmbed = [
-                    newReasoning,
-                    ...embeddable.map((o) => (o.interpretation?.reasoning ?? '').trim()),
-                ];
-                const vectors = (await embedder.generate(textsToEmbed, undefined, getAbortSignalConfig()));
-                const newVec = vectors[0];
-                if (newVec?.length) {
-                    for (let i = 0; i < embeddable.length; i++) {
-                        const existingVec = vectors[i + 1];
-                        if (existingVec?.length && cosineSimilarity(newVec, existingVec) >= threshold) {
-                            related.push(embeddable[i]);
-                        }
-                    }
-                }
-            }
-            catch (e) {
-                logger.warn('Embedding check failed; intent-matched opportunities already captured', { error: e });
-                // Phase 1 matches are preserved; remaining opps without shared intents are not related
-            }
-        }
-    }
-    if (related.length === 0) {
-        return { enriched: false, data: newData };
-    }
-    const mergedActors = mergeActors(newData, related);
-    const mergedInterpretation = mergeInterpretation(newData, related);
-    const enrichedFrom = related.map((o) => o.id);
-    const mergedConfidence = typeof mergedInterpretation.confidence === 'number'
-        ? String(mergedInterpretation.confidence)
-        : mergedInterpretation.confidence;
-    const enrichedData = {
-        ...newData,
-        detection: {
-            ...newData.detection,
-            source: 'enrichment',
-            enrichedFrom,
-        },
-        actors: mergedActors,
-        interpretation: mergedInterpretation,
-        confidence: mergedConfidence,
-    };
-    const resolvedStatus = resolveEnrichedStatus(related.map((o) => o.status), newData.status);
-    logger.verbose('Enriched opportunity', {
-        enrichedFrom,
-        actorCount: mergedActors.length,
-    });
-    return {
-        enriched: true,
-        data: enrichedData,
-        expiredIds: enrichedFrom,
-        resolvedStatus,
-    };
-}

package/dist/opportunities/opportunity.evaluator.d.ts

@@ -1,289 +0,0 @@
-import type { Runnable } from "@langchain/core/runnables";
-import { z } from "zod";
-import type { Lens } from "../discovery/index.js";
-import type { OpportunityStatus } from "../shared/interfaces/database.interface.js";
-import type { OpportunityEvidence } from '../shared/schemas/network-assignment.schema.js';
-declare const OpportunitySchema: z.ZodObject<{
-    reasoning: z.ZodString;
-    score: z.ZodNumber;
-    valencyRole: z.ZodEnum<["Agent", "Patient", "Peer"]>;
-    sourceId: z.ZodString;
-    candidateId: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    reasoning: string;
-    score: number;
-    sourceId: string;
-    valencyRole: "Agent" | "Patient" | "Peer";
-    candidateId: string;
-}, {
-    reasoning: string;
-    score: number;
-    sourceId: string;
-    valencyRole: "Agent" | "Patient" | "Peer";
-    candidateId: string;
-}>;
-export interface EvaluatorEntity {
-    userId: string;
-    profile: {
-        name?: string;
-        bio?: string;
-        location?: string;
-        interests?: string[];
-        skills?: string[];
-        context?: string;
-    };
-    intents?: Array<{
-        intentId: string;
-        payload: string;
-        summary?: string;
-    }>;
-    networkId: string;
-    evidenceKey?: string;
-    ragScore?: number;
-    matchedVia?: string;
-    evidence?: OpportunityEvidence[];
-}
-export interface EvaluatorInput {
-    /** The user who triggered discovery (for context, not special treatment). */
-    discovererId: string;
-    /** All relevant entities. In introduction mode, only the people being introduced (no introducer). */
-    entities: EvaluatorEntity[];
-    /** Existing opportunities for deduplication. */
-    existingOpportunities?: string;
-    /** When true, DISCOVERER is the introducer; reasoning and actors must be only among ENTITIES. */
-    introductionMode?: boolean;
-    /** Name of the introducer (for attribution in reasoning when introductionMode is true). */
-    introducerName?: string;
-    /** Optional hint/context from the introducer about why these people should meet. */
-    introductionHint?: string;
-    /** Optional discovery query (e.g. from chat). When set, only suggest opportunities where candidates clearly match this request. */
-    discoveryQuery?: string;
-    /** Pre-rendered network context markdown, keyed by networkId. */
-    networkContexts?: Record<string, string>;
-}
-declare const ActorSchema: z.ZodObject<{
-    userId: z.ZodString;
-    role: z.ZodEnum<["agent", "patient", "peer"]>;
-    intentId: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, string | null>;
-    evidenceKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    userId: string;
-    role: "agent" | "patient" | "peer";
-    intentId: string | null;
-    evidenceKey?: string | null | undefined;
-}, {
-    userId: string;
-    role: "agent" | "patient" | "peer";
-    intentId: string | null;
-    evidenceKey?: string | null | undefined;
-}>;
-declare const _OpportunityWithActorsSchema: z.ZodObject<{
-    reasoning: z.ZodString;
-    score: z.ZodNumber;
-    actors: z.ZodArray<z.ZodObject<{
-        userId: z.ZodString;
-        role: z.ZodEnum<["agent", "patient", "peer"]>;
-        intentId: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, string | null>;
-        evidenceKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, "strip", z.ZodTypeAny, {
-        userId: string;
-        role: "agent" | "patient" | "peer";
-        intentId: string | null;
-        evidenceKey?: string | null | undefined;
-    }, {
-        userId: string;
-        role: "agent" | "patient" | "peer";
-        intentId: string | null;
-        evidenceKey?: string | null | undefined;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    reasoning: string;
-    score: number;
-    actors: {
-        userId: string;
-        role: "agent" | "patient" | "peer";
-        intentId: string | null;
-        evidenceKey?: string | null | undefined;
-    }[];
-}, {
-    reasoning: string;
-    score: number;
-    actors: {
-        userId: string;
-        role: "agent" | "patient" | "peer";
-        intentId: string | null;
-        evidenceKey?: string | null | undefined;
-    }[];
-}>;
-declare const entityBundleResponseFormat: z.ZodObject<{
-    verdicts: z.ZodArray<z.ZodObject<{
-        candidateId: z.ZodString;
-        accepted: z.ZodBoolean;
-        score: z.ZodNumber;
-        reasoning: z.ZodString;
-        actors: z.ZodArray<z.ZodObject<{
-            userId: z.ZodString;
-            role: z.ZodEnum<["agent", "patient", "peer"]>;
-            intentId: z.ZodEffects<z.ZodNullable<z.ZodString>, string | null, string | null>;
-            evidenceKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-        }, "strip", z.ZodTypeAny, {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }, {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }>, "many">;
-    }, "strip", z.ZodTypeAny, {
-        reasoning: string;
-        score: number;
-        accepted: boolean;
-        actors: {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }[];
-        candidateId: string;
-    }, {
-        reasoning: string;
-        score: number;
-        accepted: boolean;
-        actors: {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }[];
-        candidateId: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    verdicts: {
-        reasoning: string;
-        score: number;
-        accepted: boolean;
-        actors: {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }[];
-        candidateId: string;
-    }[];
-}, {
-    verdicts: {
-        reasoning: string;
-        score: number;
-        accepted: boolean;
-        actors: {
-            userId: string;
-            role: "agent" | "patient" | "peer";
-            intentId: string | null;
-            evidenceKey?: string | null | undefined;
-        }[];
-        candidateId: string;
-    }[];
-}>;
-export type EvaluatorActor = z.infer<typeof ActorSchema>;
-export type EvaluatedOpportunityWithActors = z.infer<typeof _OpportunityWithActorsSchema>;
-export type EvaluatorOutputBundle = z.infer<typeof entityBundleResponseFormat>;
-/** Raised only after both bounded attempts return an incomplete evaluator batch. */
-export declare class EvaluatorIncompleteError extends Error {
-    constructor();
-}
-type Opportunity = z.infer<typeof OpportunitySchema>;
-export interface CandidateProfile {
-    userId: string;
-    identity?: {
-        name?: string;
-        bio?: string;
-        location?: string;
-    };
-    attributes?: {
-        interests?: string[];
-        skills?: string[];
-    };
-    narrative?: {
-        context?: string;
-    };
-    score?: number;
-}
-interface OpportunityEvaluatorOptions {
-    minScore?: number;
-    limit?: number;
-    hydeDescription?: string;
-    /** Pre-inferred lenses (if not provided, lens inference runs automatically in HyDE graph). */
-    lenses?: Lens[];
-    existingOpportunities?: string;
-    candidates?: CandidateProfile[];
-    filter?: Record<string, unknown>;
-    initialStatus?: OpportunityStatus;
-    /** Optional caller cancellation; does not change retry/fallback policy. */
-    signal?: AbortSignal;
-}
-/** Optional test double for entity-bundle model (avoids live LLM in unit tests). */
-export type OpportunityEvaluatorOptionsConstructor = {
-    entityBundleModel?: Runnable;
-};
-export declare class OpportunityEvaluator {
-    private model;
-    private entityBundleModel;
-    constructor(options?: OpportunityEvaluatorOptionsConstructor);
-    /**
-     * Main Entry Point: Batch analysis of candidates.
-     *
-     * @param sourceProfileContext - The profile context string of the user we are finding opportunities FOR.
-     * @param candidates - List of potential matches to evaluate.
-     * @param options - Config (minScore, valid types, etc).
-     * @returns A sorted list of high-value `Opportunity` objects.
-     */
-    invoke(sourceProfileContext: string, candidates: CandidateProfile[], options: OpportunityEvaluatorOptions): Promise<Opportunity[]>;
-    /**
-     * Analyze a single match pair using the primary Agent model.
-     */
-    private analyzeMatch;
-    /**
-     * Entity-bundle entry point (C3): single LLM call with all entities, returns 0..N opportunities with actors.
-     */
-    invokeEntityBundle(input: EvaluatorInput, options?: {
-        minScore?: number;
-        returnAll?: boolean;
-        signal?: AbortSignal;
-    }): Promise<EvaluatedOpportunityWithActors[]>;
-    /**
-     * Factory method to expose the agent as a LangChain tool.
-     * Simplified to only accept direct evaluation arguments.
-     * PURE: Does not perform any database lookups.
-     */
-    static asTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
-        sourceProfileContext: z.ZodString;
-        candidatesJson: z.ZodOptional<z.ZodString>;
-        minScore: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        sourceProfileContext: string;
-        minScore?: number | undefined;
-        candidatesJson?: string | undefined;
-    }, {
-        sourceProfileContext: string;
-        minScore?: number | undefined;
-        candidatesJson?: string | undefined;
-    }>, {
-        sourceProfileContext: string;
-        minScore?: number | undefined;
-        candidatesJson?: string | undefined;
-    }, {
-        sourceProfileContext: string;
-        minScore?: number | undefined;
-        candidatesJson?: string | undefined;
-    }, {
-        reasoning: string;
-        score: number;
-        sourceId: string;
-        valencyRole: "Agent" | "Patient" | "Peer";
-        candidateId: string;
-    }[], unknown, "opportunity_evaluator">;
-}
-export {};