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

package/dist/opportunities/opportunity.evaluator.js

@@ -1,516 +0,0 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-import { HumanMessage, SystemMessage } from "@langchain/core/messages";
-import { tool } from "@langchain/core/tools";
-import { z } from "zod";
-import { protocolLogger } from "../shared/observability/protocol.logger.js";
-import { Timed } from "../shared/observability/performance.js";
-import { stripUuids } from "./opportunity.presentation.js";
-import { createStructuredModel } from "../shared/agent/model.config.js";
-import { invokeWithAbortSignal } from "../shared/agent/model-signal.js";
-import { renderOpportunityEvidenceForPrompt } from './opportunity.evidence.js';
-import { hasUnsupportedOpportunityClaim } from '../shared/utils/claim-safety.js';
-import { normalizeOpportunityActorIntent } from './opportunity.actor.js';
-const logger = protocolLogger("OpportunityEvaluator");
-const invokeLog = protocolLogger("OpportunityEvaluator:invoke");
-const invokeEntityBundleLog = protocolLogger("OpportunityEvaluator:invokeEntityBundle");
-// ──────────────────────────────────────────────────────────────
-// 1. SYSTEM PROMPT
-// ──────────────────────────────────────────────────────────────
-const systemPrompt = `
-    You are an expert "Opportunity Matcher" and super-connector.
-    Your Goal: Analyze a Source User's profile against a Candidate User's profile to identify A SINGLE HIGH-VALUE opportunity.
-
-    Input:
-    - Source Context: The Source User's own Profile.
-    - Candidate Profile (JSON)
-    - Existing Opportunities (Context of matches already made)
-
-    Output:
-    - A list containing EXACTLY ONE "Opportunity" if a match exists.
-    - If NO match exists, return an empty list.
-    - Score (0-100): How strong is this match?
-      - 90-100: "Must Meet" (Perfect alignment).
-      - 70-89: "Should Meet" (Strong overlaps, clear potential).
-      - <70: No opportunity (Return empty list).
-
-    **CRITICAL: VALENCY & REASONING**
-
-    1. **Valency Analysis**:
-       - Determine the semantic role of the Candidate relative to the Source's goal.
-       - "Agent": The Candidate CAN DO something for the Source (e.g., Source needs a dev, Candidate IS a dev).
-       - "Patient": The Candidate NEEDS something from the Source (e.g., Source is a mentor, Candidate needs mentoring).
-       - "Peer": Symmetric collaboration.
-
-    2. **Reasoning (Third-Party Analytical Perspective)**:
-       - **reasoning**: A neutral, third-party explanation of why this opportunity exists. Written for other LLM agents to read and understand.
-       - Mention BOTH users by their roles (e.g. "The source user" and "The candidate") and explain why they are a match.
-       - Do NOT address either user as "you". Write from an objective observer's perspective.
-       - Include what each side brings to the connection and why it is mutually valuable.
-       - NEVER leak private intents. If someone's intent is confidential, describe their relevant attributes instead.
-
-    **VISIBILITY IMPLICATIONS OF ROLE ASSIGNMENT**
-
-    The valency role you assign directly controls who sees the opportunity and when:
-    - "Agent" (helper/provider): LAST to see the opportunity — only after the Patient has committed to reaching out. Agents are protected from noise; they only see high-intent connections.
-    - "Patient" (seeker/requester): Sees the opportunity early and decides whether to reach out.
-    - "Peer" (symmetric): Both parties see the opportunity immediately and either can initiate.
-
-    Choose the role carefully — it determines the entire flow of how the connection unfolds.
-
-    Rules:
-    1. SYNTHESIS (CRITICAL): If multiple distinct match angles exist, SYNTHESIZE them into a SINGLE, robust opportunity.
-    2. NEVER address either user directly — always use third-party references ("the source", "the candidate").
-    3. COMPREHENSIVE: The single opportunity must capture ALL the value of the connection.
-    4. Be specific about the "Why" for BOTH sides in the reasoning.
-    5. DEDUPLICATION: Do NOT suggest opportunities that duplicate "Existing Opportunities".
-    6. Do not suggest an opportunity if the source and candidate clearly already know each other (e.g. same company, co-founders, same team).
-    7. SAME-SIDE MATCHING: If both the source and candidate are SEEKING the same resource (e.g., both looking for investors, both seeking a co-founder), this is not an opportunity. Return an empty list unless one side clearly OFFERS what the other SEEKS.
-    8. NETWORK CONTEXT IS NOT PERSON EVIDENCE: A network assignment, title, type, or metadata is retrieval and thematic context only. It is never proof that a person attended an event, belongs to a group, resides in a place, knows anyone else from the network, or shared a session, time, or location with anyone. Do not state or infer those claims in opportunity reasoning.
-`;
-// Entity-bundle system prompt (C2): entities + four match patterns + actors output
-// NOTE: entityBundleSystemPrompt uses a >= 30 threshold (permissive) while
-// systemPrompt uses >= 70 (strict). This is intentional: batch mode casts a wide
-// net so the calling pipeline can apply its own filters; pairwise mode is strict
-// because it returns a single yes/no decision per candidate pair.
-const entityBundleSystemPrompt = `
-You are an expert "Opportunity Matcher" and super-connector.
-Your Goal: Analyze a set of entities (people), each with a profile and optional intents, and identify HIGH-VALUE opportunities among them.
-
-Input:
-- DISCOVERER: The user ID who triggered discovery (for context; they may or may not be in the entity list).
-- ENTITIES: A set of entities. Each entity has:
-  - userId, networkId (the index through which they were found)
-  - evidenceKey (stable key for the matched resource when available)
-  - profile: name, bio, location, interests, skills, context
-  - intents (optional): list of { intentId, payload, summary } — some entities are profile-only, some have intents
-  - ragScore, matchedVia (how they were found)
-  - evidence (typed retrieval evidence: discovery kind, network, score, lens, source/candidate ids)
-- EXISTING OPPORTUNITIES: Context of matches already made (for deduplication).
-
-BEFORE SCORING — determine role satisfiability:
-
-Definitions:
-  SUBSTITUTIVE ROLE: The candidate can directly fill the open position in the discoverer's intent. The candidate IS the person/entity the discoverer is seeking. Example: discoverer seeks "co-founder" → candidate is an engineer willing to co-found.
-  COMPLEMENTARY ROLE: The candidate's contribution is defined relative to the seeker-sought relation from the outside — they fund, advise, recruit for, or enable the sought relationship rather than participating in it as the target. Example: discoverer seeks "co-founder" → candidate is a VC (funds the company, does not co-found it).
-
-Step 1 — Identify the open argument in each discoverer intent: what type of person or entity would satisfy the intent if found?
-Step 2 — For each candidate, ask: can this candidate directly fill that open argument position?
-  YES → substitutive role. Proceed to scoring.
-  NO → complementary role. Apply Rule 7 (score ≤ 30, return no opportunity).
-Step 3 — Contextual override: if the candidate's profile contains explicit evidence that they currently function in the substitutive role (e.g., a former investor who is now building full-time as a technical co-founder), re-evaluate Step 2 against their current role, not their categorical label.
-
-Match patterns to consider:
-1. Profile-to-profile: Complementary backgrounds (skills, interests, location).
-2. Profile-to-intents+profile: Someone's skills/background match another's stated goals (intents).
-3. Intents+profile-to-profile: Someone's stated goals match another's skills/background.
-4. Intents+profile-to-intents+profile: Complementary or reciprocal goals between two or more people.
-
-Output:
-- A list of verdicts with EXACTLY ONE verdict for EVERY candidate entity (never omit a candidate).
-- Each verdict has candidateId (the candidate USER ID), accepted, reasoning, score, and actors.
-- accepted=true verdicts must include exactly the source and that candidate as actors. accepted=false verdicts may use an empty actor list.
-- Rejected candidates still require a verdict: set accepted=false and score below the appropriate threshold.
-- A verdict score is 0-100:
-  - 90-100: Must Meet — candidate's PRIMARY role directly matches what the discoverer seeks.
-  - 70-89: Should Meet — meaningful overlap on role type AND complementary intent.
-  - 50-69: Worth Considering — tangential overlap only.
-  - <30: Complementary-role mismatch (candidate cannot fill the discoverer's open argument position), same-side match, or already acquainted.
-- IMPORTANT: Every candidate must be represented once and only once. Do not return an opportunity list and do not omit rejected candidates.
-- Actors in accepted verdicts:
-    - userId
-    - role: "agent" (can do something for others), "patient" (needs something from others), "peer" (symmetric collaboration)
-    - intentId (optional): if the match is intent-driven, the specific intent ID for that user
-    - evidenceKey (optional): copy the entity evidenceKey when the actor is driven by a specific listed entity
-
-VISIBILITY (role controls who sees the opportunity when):
-- agent: Last to see — after the patient has committed to reaching out.
-- patient: Sees early and decides whether to reach out.
-- peer: Both see immediately; either can initiate.
-
-Rules:
-1. ONE OPPORTUNITY PER CANDIDATE: Create a SEPARATE opportunity for EACH candidate who matches. Do NOT combine multiple candidates into one opportunity. Each opportunity should have exactly 2 actors: the DISCOVERER and ONE candidate.
-2. INDIVIDUAL REASONING: Write specific reasoning for EACH candidate individually. Do NOT mention other candidates in the reasoning. Focus on why THIS specific candidate matches THIS specific discoverer.
-3. DEDUPLICATION: Do not suggest opportunities that duplicate Existing Opportunities.
-4. Write reasoning from an objective observer's perspective; be specific about the "Why" for each side.
-5. When in introduction mode, each opportunity must have exactly two actors — the two people being introduced. The discoverer (introducer) is added by the system and must not be included in your actors list.
-6. ALREADY KNOW EACH OTHER: Do NOT suggest an opportunity if the entities clearly already know each other. Examples: co-founders of the same company, same team at the same organization, same employer, or any relationship that is obviously existing from their profiles (bio, context). When in doubt, if both profiles mention the same company/org/team in a way that implies they work together, return an empty list for that pair.
-7. ROLE-SATISFIABILITY (evaluate before scoring): A candidate satisfies a discoverer's intent only if they can fill the SUBSTITUTIVE ROLE — the open argument position in the intent (the type of person the discoverer is seeking). A candidate in a COMPLEMENTARY ROLE (one that funds, advises, recruits for, or otherwise enables the sought relation from outside it) does not satisfy the intent, regardless of how closely associated their domain is.
-   COMPLEMENTARY-ROLE CAP: If the candidate occupies a complementary rather than substitutive role relative to the discoverer's intent, score below 30 (e.g. 0–20). Return no opportunity. A "reject" score must be strictly below 30 so the candidate is not surfaced — never park a rejected candidate at exactly 30.
-   CONTEXTUAL OVERRIDE: If the candidate's profile contains explicit evidence that they currently function in the substitutive role (not merely historically or tangentially), treat them as substitutive and score normally.
-8. SAME-SIDE MATCHING: Before scoring, check whether the DISCOVERER and CANDIDATE are both SEEKING the same thing. Look at both parties' intents for directionality:
-   - SEEKING signals: "looking for", "seeking", "want to find", "need", "raising", "hiring"
-   - OFFERING signals: "can offer", "expert in", "investing in", "mentoring", "available for"
-   If both parties have SEEKING intents targeting the same resource (e.g., both seeking investors, both seeking co-founders, both seeking mentorship), this is NOT an opportunity — score <30. An opportunity requires one side to OFFER what the other SEEKS.
-9. LOCATION MATCHING: When the DISCOVERY REQUEST mentions a specific location (city, region, or country):
-   a. If a candidate's profile.location is KNOWN and clearly does NOT match the requested location (different city/region), score below 30 (e.g. 0–25) and return no opportunity. An explicitly requested location is a hard constraint: a known geographic mismatch excludes the candidate.
-   b. If a candidate's profile.location is UNKNOWN, EMPTY, or AMBIGUOUS, do NOT penalize — allow them through and score based on other factors. Note in reasoning that their location is unverified.
-   c. If a candidate's profile.location matches or is reasonably close (e.g., "Bay Area" matches "San Francisco", "Remote" matches any location), score normally.
-   d. "Remote" or "Global" locations are compatible with any requested location.
-10. EVENT NETWORK CONTEXT: When NETWORK CONTEXTS includes an event-type network (identified by dates, location, schedule, or themes):
-   a. TEMPORAL RELEVANCE: Event start/end dates may affect whether an explicitly stated event-related intent is timely. After an event ends, event-specific intents lose relevance unless the connection has lasting value.
-   b. THEME ALIGNMENT: Event themes or tracks may be used as thematic retrieval context when a person's own profile or intent independently aligns with them.
-   c. PROHIBITED INFERENCE: Network assignment, title, type, schedule, location, and metadata are retrieval context only. They are never proof that any person attended or will attend, belongs to the event or network, resides in its location, knows another person from it, or shared a session, time, place, or location with anyone. Do not infer co-attendance, same-place/same-time presence, session attendance, or peer roles from network co-membership.
-`;
-// ──────────────────────────────────────────────────────────────
-// 2. RESPONSE SCHEMA (Zod)
-// ──────────────────────────────────────────────────────────────
-const OpportunitySchema = z.object({
-    reasoning: z.string().describe('Third-party analytical explanation of why this opportunity exists. Mentions both users by role. Written for other LLM agents to understand the match.'),
-    score: z.number().min(0).max(100).describe('Relevance score 0-100'),
-    valencyRole: z.enum(['Agent', 'Patient', 'Peer']).describe("The semantic role of the Candidate relative to the Source"),
-    sourceId: z.string().describe('The user ID of the source'),
-    candidateId: z.string().describe('The user ID of the candidate'),
-});
-const responseFormat = z.object({
-    opportunities: z.array(OpportunitySchema).describe("List of opportunities identified"),
-});
-const ActorSchema = z.object({
-    userId: z.string(),
-    role: z.enum(['agent', 'patient', 'peer']),
-    intentId: z.string().nullable()
-        .transform((value) => normalizeOpportunityActorIntent(value) ?? null)
-        .describe('If the match is intent-driven, the specific intent ID; null otherwise'),
-    evidenceKey: z.string().nullable().optional().describe('Stable evidence key for the matched entity; null if unknown'),
-});
-const _OpportunityWithActorsSchema = z.object({
-    reasoning: z.string(),
-    score: z.number().min(0).max(100),
-    actors: z.array(ActorSchema).min(2).describe('All actors in this opportunity with their roles'),
-});
-const EvaluatorVerdictSchema = z.object({
-    candidateId: z.string().describe('The candidate USER ID being evaluated'),
-    accepted: z.boolean().describe('Whether this candidate is a qualifying opportunity'),
-    score: z.number().min(0).max(100),
-    reasoning: z.string(),
-    actors: z.array(ActorSchema).describe('Accepted verdicts include source and candidate actors; rejected verdicts may use an empty list'),
-});
-const entityBundleResponseFormat = z.object({
-    verdicts: z.array(EvaluatorVerdictSchema).describe('Exactly one verdict for every candidate entity; include rejected candidates'),
-});
-/** Raised only after both bounded attempts return an incomplete evaluator batch. */
-export class EvaluatorIncompleteError extends Error {
-    constructor() {
-        super('evaluator-incomplete');
-        this.name = 'EvaluatorIncompleteError';
-    }
-}
-function reconcileEvaluatorVerdicts(verdicts, candidateIds, discovererId, introductionMode) {
-    const expected = new Set(candidateIds);
-    const seen = new Set();
-    for (const verdict of verdicts) {
-        if (!expected.has(verdict.candidateId) || seen.has(verdict.candidateId)) {
-            throw new EvaluatorIncompleteError();
-        }
-        if (verdict.accepted) {
-            const expectedActorIds = introductionMode
-                ? expected
-                : new Set([discovererId, verdict.candidateId]);
-            const actorIds = verdict.actors.map((actor) => actor.userId);
-            if (actorIds.length !== expectedActorIds.size ||
-                new Set(actorIds).size !== expectedActorIds.size ||
-                actorIds.some((actorId) => !expectedActorIds.has(actorId))) {
-                throw new EvaluatorIncompleteError();
-            }
-        }
-        seen.add(verdict.candidateId);
-    }
-    if (seen.size !== expected.size)
-        throw new EvaluatorIncompleteError();
-    return verdicts;
-}
-function isEvaluatorOutputError(error) {
-    return error instanceof z.ZodError || error instanceof EvaluatorIncompleteError;
-}
-export class OpportunityEvaluator {
-    constructor(options) {
-        this.model = createStructuredModel("opportunityEvaluator", responseFormat, {
-            name: "opportunity_evaluator"
-        });
-        this.entityBundleModel = options?.entityBundleModel ?? createStructuredModel("opportunityEvaluator", entityBundleResponseFormat, {
-            name: "opportunity_evaluator_entity_bundle"
-        });
-    }
-    /**
-     * 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.
-     */
-    async invoke(sourceProfileContext, candidates, options) {
-        const minScore = options.minScore || 70;
-        invokeLog.verbose('Analyzing candidates', { count: candidates.length });
-        if (candidates.length === 0) {
-            logger.verbose('No candidates provided.');
-            return [];
-        }
-        const opportunities = [];
-        // Analyze each candidate in parallel (bounded)
-        const promises = candidates.map(async (candidate) => {
-            // Pass existing opportunities context if provided
-            const existingContext = options.existingOpportunities || '';
-            return this.analyzeMatch(sourceProfileContext, candidate, candidate.userId, existingContext, options.signal);
-        });
-        const results = await Promise.all(promises);
-        results.flat().forEach(op => {
-            if (op.score >= minScore) {
-                opportunities.push(op);
-            }
-        });
-        // Sort by score and take top 1
-        const out = opportunities.sort((a, b) => b.score - a.score).slice(0, 1);
-        invokeLog.verbose('Done', { accepted: out.length });
-        return out;
-    }
-    /**
-     * Analyze a single match pair using the primary Agent model.
-     */
-    async analyzeMatch(sourceProfileContext, candidateProfile, candidateUserId, existingOpportunities, signal) {
-        try {
-            // Construct the source context part of the prompt
-            const sourceContext = `SOURCE PROFILE:\n${sourceProfileContext}`;
-            const existingContextPart = existingOpportunities
-                ? `\nEXISTING OPPORTUNITIES (Deduplication Context):\n${existingOpportunities}\n`
-                : '';
-            // Create candidate context using template string
-            const candidateContext = `
-            ID: ${candidateUserId}
-            Name: ${candidateProfile.identity?.name || 'Unknown'}
-            Bio: ${candidateProfile.identity?.bio || ''}
-            Location: ${candidateProfile.identity?.location || ''}
-            Interests: ${candidateProfile.attributes?.interests?.join(', ') || ''}
-            Skills: ${candidateProfile.attributes?.skills?.join(', ') || ''}
-
-            Context: ${candidateProfile.narrative?.context || ''}
-            `;
-            const messages = [
-                new SystemMessage(systemPrompt),
-                new HumanMessage(`${sourceContext}\n${existingContextPart}\nCANDIDATE PROFILE:\n${candidateContext}`)
-            ];
-            const result = await invokeWithAbortSignal(this.model, messages, signal);
-            const output = responseFormat.parse(result);
-            const mappedOpportunities = output.opportunities.map((op) => ({
-                ...op,
-                reasoning: stripUuids(op.reasoning),
-                candidateId: candidateUserId,
-            }));
-            return mappedOpportunities;
-        }
-        catch (e) {
-            const message = e instanceof Error ? e.message : String(e);
-            logger.warn('Analysis failed for candidate', { candidateUserId, message });
-            throw e;
-        }
-    }
-    /**
-     * Entity-bundle entry point (C3): single LLM call with all entities, returns 0..N opportunities with actors.
-     */
-    async invokeEntityBundle(input, options = {}) {
-        const minScore = options.minScore ?? 70;
-        const returnAll = options.returnAll ?? false;
-        const totalEntities = input.entities?.length ?? 0;
-        if (!input.entities?.length) {
-            invokeEntityBundleLog.verbose('No entities.');
-            return [];
-        }
-        const existingPart = input.existingOpportunities
-            ? `\nEXISTING OPPORTUNITIES:\n${input.existingOpportunities}\n`
-            : '';
-        const introModePart = input.introductionMode
-            ? `\nINTRODUCTION MODE: This is a human-curated introduction. ${input.introducerName ?? 'The introducer'} (DISCOVERER: ${input.discovererId}) explicitly wants these people to connect. This is NOT an automatic discovery — a real person saw value in this connection.
-
-CRITICAL REASONING INSTRUCTIONS FOR INTRODUCTIONS:
-- Your reasoning MUST acknowledge that this is an introduction initiated by ${input.introducerName ?? 'the introducer'}, not a system-discovered match.
-- Start reasoning with something like "${input.introducerName ?? 'The introducer'} is connecting [Name A] and [Name B] because..." or "This introduction by ${input.introducerName ?? 'the introducer'} brings together..."
-- Even if the parties' intents or profiles don't obviously overlap, the introduction is still valid because the introducer saw the connection. Explain what the introducer likely sees in this match.
-- If explicit intents align, mention them — but frame it as supporting the introducer's judgment, not as the primary reason.${input.introductionHint ? `\nINTRODUCER'S CONTEXT: "${input.introductionHint}" — use this to inform your reasoning about why the introducer made this connection.` : ''}
-- Actors must refer ONLY to the ENTITIES below (the people being introduced). Do not include the DISCOVERER as an actor.
-- You must output exactly two actors per opportunity (the two people being introduced). The introducer is added separately; do not include them in actors.
-- Be generous with scoring (70+ for any introduction with a plausible basis, since a human made the judgment).
-`
-            : '';
-        const discoveryQueryPart = input.discoveryQuery?.trim()
-            ? `\nDISCOVERY REQUEST: The user asked: "${input.discoveryQuery.trim()}"
-
-CRITICAL SCORING RULES FOR DISCOVERY REQUESTS:
-
-0. QUERY IS PRIMARY: The DISCOVERY REQUEST above is the primary evaluation criterion. The source user's stored INTENTS (if listed below) are background context — use them ONLY to fill in blanks when the query is too broad or vague to evaluate on its own. If the query is specific enough to score candidates, score strictly against the query and IGNORE stored intents. Never let a stored intent override or replace the query as the basis for scoring. When a specific query imposes a hard identity, role, capability, or location constraint, candidates that only match background context or thematic adjacency must score strictly below 30 and be omitted.
-
-1. CLASSIFY THE QUERY TYPE — determine the predication type before scoring:
-
-   IDENTITY/ROLE QUERY: The query term is a count noun or sortal that can serve as a predicate nominal — "X IS A [query]" is grammatical and meaningful. Examples: "samurai", "investors", "designers", "nurses", "founders". The user wants someone who IS that thing — not someone who works with, creates content about, or is tangentially associated with it.
-   → Test: Can you say "this person IS a [query term]"? If yes, this is an identity query.
-   → CRITICAL: Subject-matter contact is NOT identity. A character designer who draws samurai IS NOT a samurai. An engineer who raised funding IS NOT an investor. A journalist who covers finance IS NOT an investor. IS-A is not transitive through creative subject matter, professional adjacency, or domain familiarity.
-
-   TOPICAL/DOMAIN QUERY: The query is a field, domain, or abstract topic — "X IS A [query]" is ungrammatical. Examples: "machine learning", "sustainability", "blockchain". The user wants someone who works in or has expertise in this domain.
-   → Test: "This person IS a machine learning" makes no sense → topical query.
-
-   NEED/CAPABILITY QUERY: The query contains a purposive frame — "someone to help with X", "need a Y", "looking for Z". The user describes a specific need.
-
-2. APPLY TYPE-SPECIFIC SCORING:
-
-   For IDENTITY/ROLE queries — apply a categorical gate:
-   - First, make a binary IS-A judgment for each candidate: does this person's PRIMARY professional identity or self-description place them within the extension of the query term?
-   - IS-A = TRUE → score 75-100 (modulated by intent alignment and profile richness)
-   - IS-A = FALSE → score <30. Hard ceiling. Return no opportunity. Do NOT award surfacing credit for subject-matter adjacency, thematic association, creative output involving the query term, having received the thing, or being adjacent to people who are the thing.
-   - Do NOT rescue a failed IS-A judgment with background intents. If the user searched "samurai" and the candidate is a visual artist (IS-A = false), the candidate's alignment with a background intent like "connect with visual artists" does not matter — the explicit query takes priority. If the user searched "investors" and the candidate merely raised money, score <30. If the user searched "scouts" and the candidate was scouted, score <30. If the user searched "art director", a solo illustrator is not enough: require explicit evidence that the candidate owns visual direction, leads/briefs other artists, manages a visual system, or is described as an art/creative director. General visual taste, composition skill, or illustration output alone is a failed IS-A judgment and must score <30.
-
-   For TOPICAL/DOMAIN queries — apply gradient scoring:
-   - 90-100: Deep expertise, primary focus area
-   - 70-89: Substantial engagement, meaningful work in the domain
-   - 50-69: Peripheral involvement, tangential connection
-   - <50: No meaningful engagement
-
-   For NEED/CAPABILITY queries — apply capability + availability scoring:
-   - Score based on both capability match AND openness to the described collaboration
-   - 90-100: Perfect capability match with explicit availability
-   - 70-89: Strong capability, plausible availability
-
-3. SAME-SIDE CHECK: If the candidate's intents show they are ALSO SEEKING what the discoverer is seeking (e.g., both looking for investors, both looking for co-founders), this is a same-side match. Score <30 regardless of keyword overlap in bios. The candidate must BE or OFFER what the discoverer is looking for, not also be looking for it.
-
-4. LOCATION ENFORCEMENT: If the discovery request mentions a specific location (e.g., "in SF", "based in London", "Istanbul"), check each candidate's profile.location:
-   - KNOWN MISMATCH (e.g., request says "SF" but candidate is "New York"): Score <30 and return no opportunity. State the mismatch in reasoning if returning diagnostic output. A known location mismatch is a hard query failure, even when the candidate otherwise matches the source's background interests.
-   - UNKNOWN/EMPTY location: Do not penalize, and do NOT reject solely because the query contains a location. Treat location as unverified/missing evidence, then score on the non-location parts of the query. If the candidate strongly satisfies the requested role/domain (e.g., query "Unreal Engine developers in SF" and candidate is clearly an Unreal Engine developer with empty location), score normally enough to surface (typically 60-89) and note that location is unverified.
-   - MATCH or COMPATIBLE (e.g., "Bay Area" ≈ "SF", "Remote" ≈ any): Score normally.
-`
-            : '';
-        const hasDiscoveryQuery = !!input.discoveryQuery?.trim();
-        const entitiesBlock = input.entities.map((e) => {
-            const isSource = e.userId === input.discovererId;
-            // When an explicit discovery query is active, label the source user's stored
-            // intents as background context so the LLM treats the query as primary.
-            const intentsLabel = isSource && hasDiscoveryQuery ? 'BACKGROUND INTENTS (use only if query is too vague)' : 'INTENTS';
-            const intentsPart = e.intents?.length
-                ? `\n  ${intentsLabel}:\n${e.intents.map((i) => `    - ${i.intentId}: ${i.payload}`).join('\n')}`
-                : '';
-            // Mask the discoverer's name so the LLM cannot leak it into reasoning.
-            // The system prompt already says "use third-party references", but the LLM
-            // ignores this when the actual name is visible. Masking it forces role-based
-            // language ("the source user is looking…" instead of "Alice is looking…").
-            const displayName = e.userId === input.discovererId
-                ? '(source user)'
-                : (e.profile.name ?? '');
-            return `
-  USER: ${e.userId}
-  INDEX: ${e.networkId}
-  EVIDENCE KEY: ${e.evidenceKey ?? '—'}
-  PROFILE: Name: ${displayName} | Bio: ${e.profile.bio ?? ''} | Location: ${e.profile.location ?? ''} | Interests: ${e.profile.interests?.join(', ') ?? ''} | Skills: ${e.profile.skills?.join(', ') ?? ''} | Context: ${e.profile.context ?? ''}${intentsPart}
-  RAG SCORE: ${e.ragScore ?? '—'}
-  MATCHED VIA: ${e.matchedVia ?? '—'}
-  EVIDENCE:
-${renderOpportunityEvidenceForPrompt(e.evidence ?? [])}`;
-        }).join('\n');
-        const networkContextPart = input.networkContexts && Object.keys(input.networkContexts).length > 0
-            ? `\n\nNETWORK CONTEXTS:\n${Object.entries(input.networkContexts).map(([nid, ctx]) => `[INDEX: ${nid}]\n${ctx}`).join('\n\n')}`
-            : '';
-        const humanContent = `DISCOVERER: ${input.discovererId}${introModePart}${discoveryQueryPart}${networkContextPart}\n\nENTITIES:\n${entitiesBlock}${existingPart}`;
-        const messages = [
-            new SystemMessage(entityBundleSystemPrompt),
-            new HumanMessage(humanContent),
-        ];
-        const candidateIds = input.entities
-            .filter((entity) => entity.userId !== input.discovererId)
-            .map((entity) => entity.userId);
-        if (new Set(candidateIds).size !== candidateIds.length) {
-            throw new EvaluatorIncompleteError();
-        }
-        let parsedTotal = 0;
-        let incompleteReason;
-        for (let attempt = 0; attempt < 2; attempt++) {
-            try {
-                const result = await invokeWithAbortSignal(this.entityBundleModel, messages, options.signal);
-                const parsed = entityBundleResponseFormat.parse(result);
-                parsedTotal = parsed.verdicts.length;
-                const verdicts = reconcileEvaluatorVerdicts(parsed.verdicts, candidateIds, input.discovererId, input.introductionMode ?? false);
-                const accepted = verdicts
-                    .filter((verdict) => verdict.accepted)
-                    .map((verdict) => ({
-                    reasoning: stripUuids(verdict.reasoning),
-                    score: verdict.score,
-                    actors: verdict.actors,
-                }))
-                    .filter((op) => op.actors.length >= 2);
-                // Persistence safety is deterministic and precedes every score/returnAll
-                // path. Network/context placement is not typed support provenance, so an
-                // unsupported affiliation or presence claim rejects the whole result.
-                const claimSafe = accepted.filter((op) => !hasUnsupportedOpportunityClaim(op.reasoning));
-                const introGuard = input.introductionMode ? claimSafe.filter((op) => op.actors.length === 2) : claimSafe;
-                const filtered = introGuard.filter((op) => op.score >= minScore);
-                invokeEntityBundleLog.verbose('Done', {
-                    total: verdicts.length,
-                    afterClaimGuard: claimSafe.length,
-                    afterIntroGuard: introGuard.length,
-                    accepted: filtered.length,
-                    returnAll,
-                });
-                return returnAll ? introGuard : filtered;
-            }
-            catch (error) {
-                if (!isEvaluatorOutputError(error))
-                    throw error;
-                incompleteReason = error instanceof Error ? error.message : 'invalid output';
-            }
-        }
-        invokeEntityBundleLog.error('Evaluator batch incomplete', {
-            discovererId: input.discovererId,
-            totalEntities,
-            parsedTotal,
-            minScore,
-            reason: incompleteReason,
-        });
-        throw new EvaluatorIncompleteError();
-    }
-    /**
-     * 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() {
-        return tool(async (args) => {
-            const agent = new OpportunityEvaluator();
-            const sourceProfileContext = args.sourceProfileContext;
-            let candidates = [];
-            if (args.candidatesJson) {
-                try {
-                    candidates = JSON.parse(args.candidatesJson);
-                }
-                catch {
-                    logger.error("Failed to parse candidates JSON");
-                }
-            }
-            const options = {
-                minScore: args.minScore,
-            };
-            return await agent.invoke(sourceProfileContext, candidates, options);
-        }, {
-            name: 'opportunity_evaluator',
-            description: 'Evaluates candidates against a source profile. SOURCE PROFILE CONTEXT MUST BE PROVIDED.',
-            schema: z.object({
-                sourceProfileContext: z.string().describe('The resolved source user profile context'),
-                candidatesJson: z.string().optional().describe('JSON string list of Candidates'),
-                minScore: z.number().optional().describe('Minimum score to accept a match')
-            })
-        });
-    }
-}
-__decorate([
-    Timed(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Array, Object]),
-    __metadata("design:returntype", Promise)
-], OpportunityEvaluator.prototype, "invoke", null);
-__decorate([
-    Timed(),
-    __metadata("design:type", Function),
-    __metadata("design:paramtypes", [Object, Object]),
-    __metadata("design:returntype", Promise)
-], OpportunityEvaluator.prototype, "invokeEntityBundle", null);

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

@@ -1,22 +0,0 @@
-import type { OpportunityEvidence } from '../shared/schemas/network-assignment.schema.js';
-export interface EvidenceCandidateInput {
-    networkId: string;
-    similarity: number;
-    lens: string;
-    discoverySource?: 'query' | 'premise-similarity' | 'context-to-intent' | 'context-similarity';
-    matchedStrategies?: string[];
-    sourcePremiseId?: string;
-    candidatePremiseId?: string;
-    candidateIntentId?: string;
-    sourceContextId?: string;
-    candidateContextId?: string;
-    candidatePayload?: string;
-    candidateSummary?: string;
-}
-export declare function buildCandidateEvidence(candidate: EvidenceCandidateInput): OpportunityEvidence;
-export declare function withCandidateEvidence<T extends EvidenceCandidateInput>(candidate: T): T & {
-    evidence: OpportunityEvidence[];
-};
-export declare function mergeOpportunityEvidence(...groups: Array<OpportunityEvidence[] | undefined>): OpportunityEvidence[];
-export declare function withMatchedStrategies(evidence: OpportunityEvidence[], strategies: string[]): OpportunityEvidence[];
-export declare function renderOpportunityEvidenceForPrompt(evidence: OpportunityEvidence[]): string;

package/dist/opportunities/opportunity.evidence.js

@@ -1,87 +0,0 @@
-export function buildCandidateEvidence(candidate) {
-    const kind = resolveEvidenceKind(candidate);
-    return {
-        kind,
-        networkId: candidate.networkId,
-        score: candidate.similarity,
-        lens: candidate.lens,
-        discoverySource: candidate.discoverySource,
-        matchedStrategies: candidate.matchedStrategies,
-        sourcePremiseId: candidate.sourcePremiseId,
-        candidatePremiseId: candidate.candidatePremiseId,
-        candidateIntentId: candidate.candidateIntentId,
-        sourceContextId: candidate.sourceContextId,
-        candidateContextId: candidate.candidateContextId,
-        payload: candidate.candidatePayload,
-        summary: candidate.candidateSummary,
-        assertionText: candidate.candidatePremiseId ? candidate.candidatePayload : undefined,
-    };
-}
-export function withCandidateEvidence(candidate) {
-    return { ...candidate, evidence: [buildCandidateEvidence(candidate)] };
-}
-export function mergeOpportunityEvidence(...groups) {
-    const byKey = new Map();
-    for (const evidence of groups.flatMap((group) => group ?? [])) {
-        const key = [
-            evidence.kind,
-            evidence.networkId,
-            evidence.sourcePremiseId ?? '',
-            evidence.candidatePremiseId ?? '',
-            evidence.candidateIntentId ?? '',
-            evidence.sourceContextId ?? '',
-            evidence.candidateContextId ?? '',
-            evidence.lens ?? '',
-        ].join('|');
-        const existing = byKey.get(key);
-        if (!existing || (evidence.score ?? 0) > (existing.score ?? 0))
-            byKey.set(key, evidence);
-    }
-    return Array.from(byKey.values());
-}
-export function withMatchedStrategies(evidence, strategies) {
-    return evidence.map((item) => ({
-        ...item,
-        matchedStrategies: Array.from(new Set([...(item.matchedStrategies ?? []), ...strategies])),
-    }));
-}
-export function renderOpportunityEvidenceForPrompt(evidence) {
-    if (evidence.length === 0)
-        return '    —';
-    return evidence.map((item) => {
-        const refs = [
-            item.sourcePremiseId ? `sourcePremise=${item.sourcePremiseId}` : undefined,
-            item.candidatePremiseId ? `candidatePremise=${item.candidatePremiseId}` : undefined,
-            item.candidateIntentId ? `candidateIntent=${item.candidateIntentId}` : undefined,
-            item.sourceContextId ? `sourceContext=${item.sourceContextId}` : undefined,
-            item.candidateContextId ? `candidateContext=${item.candidateContextId}` : undefined,
-            item.matchedStrategies?.length ? `strategies=${item.matchedStrategies.join(',')}` : undefined,
-        ].filter(Boolean).join(', ');
-        const text = item.summary ?? item.payload ?? item.assertionText ?? '';
-        // IND-567 Fix B: when a query_premise entry has no text, warn the evaluator
-        // so it does not treat a high RAG score as domain confirmation.
-        // (text should be populated by Fix A; this fallback fires if the DB fetch
-        //  failed or the adapter omitted getPremise).
-        const domainCaution = (item.kind === 'query_premise' && !text)
-            ? ' [premise text unavailable — do NOT infer domain match from RAG score alone; verify domain alignment from profile]'
-            : (item.kind === 'query_context' && !text)
-                ? ' [context text unavailable — do NOT infer domain match from RAG score alone; verify domain alignment from profile]'
-                : '';
-        return `    - ${item.kind} on ${item.networkId} via ${item.lens ?? 'unknown'} score=${item.score?.toFixed(3) ?? '—'}${refs ? ` (${refs})` : ''}${text ? `: ${text}` : ''}${domainCaution}`;
-    }).join('\n');
-}
-function resolveEvidenceKind(candidate) {
-    if (candidate.discoverySource === 'premise-similarity')
-        return 'premise_similarity';
-    if (candidate.discoverySource === 'context-similarity')
-        return 'context_similarity';
-    if (candidate.discoverySource === 'context-to-intent')
-        return 'context_to_intent';
-    if (candidate.candidatePremiseId)
-        return 'query_premise';
-    if (candidate.candidateContextId)
-        return 'query_context';
-    if (candidate.candidateIntentId)
-        return 'query_intent';
-    return 'profile';
-}