@indexnetwork/protocol 0.1.0

package/dist/agents/opportunity.evaluator.js

@@ -0,0 +1,413 @@
+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 "../support/protocol.logger.js";
+import { Timed } from "../support/performance.js";
+import { stripUuids } from "../support/opportunity.sanitize.js";
+import { createModel } from "./model.config.js";
+const logger = protocolLogger("OpportunityEvaluator");
+/**
+ * Config
+ */
+import { config } from "dotenv";
+config({ path: '.env.development' });
+const model = createModel("opportunityEvaluator");
+// ──────────────────────────────────────────────────────────────
+// 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.
+`;
+// 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, indexId (the index through which they were found)
+  - 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)
+- 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 0..N opportunities. Each opportunity has:
+  - reasoning: Third-party analytical explanation (for other LLM agents). Mention entities by role. Do NOT use "you". Never leak private intents.
+  - score: 0-100.
+    - 90-100: Must Meet — candidate's PRIMARY role directly matches what the discoverer seeks.
+      Example: discoverer seeks "AI/ML co-founder" → candidate IS an AI/ML engineer who wants to co-found.
+    - 70-89: Should Meet — meaningful overlap on role type AND complementary intent.
+    - 50-69: Worth Considering — tangential overlap only.
+    - <30 (return empty): Complementary-role mismatch (candidate cannot fill the discoverer's open argument position), same-side match, or already acquainted.
+      Example: discoverer seeks "co-founder" → candidate is a VC investor. The investor's contribution is external to the co-founding relation; they cannot substitute into it. Score 0.
+  - IMPORTANT: Include ALL reasonable matches with scores >= 30. Let the system filter by threshold.
+  - actors: At least 2 actors per opportunity. Each actor has:
+    - 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
+
+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 ≤ 30. Return no opportunity.
+   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 ≤ 40 for that candidate. Geographic mismatch is a strong negative signal when the user explicitly requested a location.
+   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.
+`;
+// ──────────────────────────────────────────────────────────────
+// 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().describe('If the match is intent-driven, the specific intent ID; null otherwise'),
+});
+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 entityBundleResponseFormat = z.object({
+    opportunities: z.array(OpportunityWithActorsSchema).describe('List of opportunities (0..N)'),
+});
+export class OpportunityEvaluator {
+    constructor(options) {
+        this.model = model.withStructuredOutput(responseFormat, {
+            name: "opportunity_evaluator"
+        });
+        this.entityBundleModel = options?.entityBundleModel ?? model.withStructuredOutput(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;
+        logger.verbose(`[OpportunityEvaluator.invoke] Analyzing ${candidates.length} candidates...`);
+        if (candidates.length === 0) {
+            logger.verbose('[OpportunityEvaluator] 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);
+        });
+        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);
+        logger.verbose('[OpportunityEvaluator.invoke] Done', { accepted: out.length });
+        return out;
+    }
+    /**
+     * Analyze a single match pair using the primary Agent model.
+     */
+    async analyzeMatch(sourceProfileContext, candidateProfile, candidateUserId, existingOpportunities) {
+        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 this.model.invoke(messages);
+            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(`[OpportunityEvaluator] 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) {
+            logger.verbose('[OpportunityEvaluator.invokeEntityBundle] 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.
+1. MATCH THE REQUEST TYPE FIRST: If the user asks for "investors", prioritize candidates who are ACTUALLY investors (VCs, angels, fund partners). Engineers and collaborators should score LOWER unless they are also investors.
+2. ROLE KEYWORDS MATTER: Look for keywords in bios like "investor", "VC", "venture", "fund", "partner at [fund]", "angel", "mentor", etc. that match what the user asked for.
+3. SCORING HIERARCHY:
+   - 90-100: Candidate's PRIMARY role matches the request (e.g., "investor" request → actual investor/VC partner)
+   - 70-89: Candidate has SOME relevance to the request (e.g., "investor" request → someone who occasionally invests but is primarily a builder)
+   - 50-69: Weak match - candidate is tangentially related but doesn't fit the primary request
+   - <50: Does not match the request - exclude or heavily down-rank
+4. DO NOT score collaborators/builders highly when the user explicitly asks for investors, and vice versa.
+5. 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.
+6. 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 ≤ 40. State the mismatch in reasoning.
+   - UNKNOWN/EMPTY location: Do not penalize. 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.indexId}
+  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 ?? '—'}`;
+        }).join('\n');
+        const humanContent = `DISCOVERER: ${input.discovererId}${introModePart}${discoveryQueryPart}\n\nENTITIES:\n${entitiesBlock}${existingPart}`;
+        const messages = [
+            new SystemMessage(entityBundleSystemPrompt),
+            new HumanMessage(humanContent),
+        ];
+        let parsedTotal = 0;
+        try {
+            const result = await this.entityBundleModel.invoke(messages);
+            const parsed = entityBundleResponseFormat.parse(result);
+            for (const op of parsed.opportunities) {
+                op.reasoning = stripUuids(op.reasoning);
+            }
+            parsedTotal = parsed.opportunities.length;
+            const introGuard = input.introductionMode
+                ? parsed.opportunities.filter((op) => op.actors.length === 2)
+                : parsed.opportunities;
+            const filtered = introGuard.filter((op) => op.score >= minScore);
+            logger.verbose('[OpportunityEvaluator.invokeEntityBundle] Done', {
+                total: parsed.opportunities.length,
+                afterIntroGuard: introGuard.length,
+                accepted: filtered.length,
+                returnAll,
+            });
+            return returnAll ? introGuard : filtered;
+        }
+        catch (llmError) {
+            logger.error('[OpportunityEvaluator.invokeEntityBundle] Failed', {
+                discovererId: input.discovererId,
+                totalEntities,
+                parsedTotal,
+                minScore,
+                llmError,
+            });
+            throw llmError;
+        }
+    }
+    /**
+     * 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 (e) {
+                    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);
+//# sourceMappingURL=opportunity.evaluator.js.map

package/dist/agents/opportunity.evaluator.js.map

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

package/dist/agents/opportunity.presenter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Opportunity Presenter Agent
+ *
+ * Generates personalized, second-person explanations of why an opportunity
+ * matters to the viewing user. Uses full opportunity data (interpretation,
+ * actors, profiles, intents, index) to produce headline, personalizedSummary,
+ * and suggestedAction for chat tools and user-facing surfaces.
+ */
+import { z } from "zod";
+import type { Opportunity } from "../interfaces/database.interface.js";
+import type { ChatGraphCompositeDatabase } from "../interfaces/database.interface.js";
+/**
+ * Minimal database interface required by gatherPresenterContext.
+ * Any database adapter that implements these three methods can be passed.
+ */
+export type PresenterDatabase = Pick<ChatGraphCompositeDatabase, "getProfile" | "getActiveIntents" | "getIndex">;
+declare const PresentationSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+}, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+}>;
+export type OpportunityPresentationResult = z.infer<typeof PresentationSchema>;
+/** Input for home-card presenter call; extends PresenterInput with optional mutual intent count. */
+export interface HomeCardPresenterInput extends PresenterInput {
+    /** Number of overlapping intents (for generating mutualIntentsLabel). */
+    mutualIntentCount?: number;
+}
+/** LLM-generated fields for home-card presentation (buttons are hardcoded by callers, not LLM-generated). */
+export declare const HomeCardLLMSchema: z.ZodObject<{
+    headline: z.ZodString;
+    personalizedSummary: z.ZodString;
+    suggestedAction: z.ZodString;
+    narratorRemark: z.ZodString;
+    mutualIntentsLabel: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    narratorRemark: string;
+    mutualIntentsLabel: string;
+}, {
+    headline: string;
+    personalizedSummary: string;
+    suggestedAction: string;
+    narratorRemark: string;
+    mutualIntentsLabel: string;
+}>;
+/** LLM-generated result from presentHomeCard (callers append button labels from opportunity.constants). */
+export type HomeCardLLMResult = z.infer<typeof HomeCardLLMSchema>;
+/** Full home-card display contract including hardcoded button labels (assembled by callers). */
+export type HomeCardPresentationResult = HomeCardLLMResult & {
+    primaryActionLabel: string;
+    secondaryActionLabel: string;
+};
+/** Input for a single presenter call (all context pre-assembled). */
+export interface PresenterInput {
+    viewerContext: string;
+    otherPartyContext: string;
+    matchReasoning: string;
+    category: string;
+    confidence: number;
+    signalsSummary: string;
+    indexName: string;
+    viewerRole: string;
+    opportunityStatus?: string;
+    /** True when this opportunity was created via an explicit introduction (not automatic discovery). */
+    isIntroduction?: boolean;
+    /** Name of the person who made the introduction, if applicable. */
+    introducerName?: string;
+}
+export declare class OpportunityPresenter {
+    private model;
+    private homeCardModel;
+    constructor();
+    private invokeWithTimeout;
+    /**
+     * Generate personalized presentation for a single opportunity.
+     */
+    present(input: PresenterInput): Promise<OpportunityPresentationResult>;
+    /**
+     * Generate LLM-powered home-card content (headline, body, narrator remark, mutual-intent label).
+     * Callers append button labels from opportunity.constants.
+     */
+    presentHomeCard(input: HomeCardPresenterInput): Promise<HomeCardLLMResult>;
+    /**
+     * Process multiple opportunities in parallel with bounded concurrency.
+     */
+    presentBatch(inputs: PresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<OpportunityPresentationResult[]>;
+    /**
+     * Process multiple opportunities as home cards in parallel with bounded concurrency.
+     * Returns full home-card display contracts (headline, body, narrator remark, action labels, mutual-intent label).
+     */
+    presentHomeCardBatch(inputs: HomeCardPresenterInput[], options?: {
+        concurrency?: number;
+    }): Promise<HomeCardLLMResult[]>;
+}
+/**
+ * Gather all context needed for the presenter from the database.
+ * Fetches viewer profile, viewer intents, other party profile(s), and index in parallel.
+ *
+ * @param displayCounterpartUserId - When set (e.g. for home card), only this counterpart is included in otherPartyContext so the presenter writes about the person on the card. Omitted for introducer view (card shows both parties).
+ */
+export declare function gatherPresenterContext(database: PresenterDatabase, opportunity: Opportunity, viewerId: string, displayCounterpartUserId?: string): Promise<PresenterInput>;
+export {};
+//# sourceMappingURL=opportunity.presenter.d.ts.map

package/dist/agents/opportunity.presenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opportunity.presenter.d.ts","sourceRoot":"","sources":["../../src/agents/opportunity.presenter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAGtF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,0BAA0B,EAC1B,YAAY,GAAG,kBAAkB,GAAG,UAAU,CAC/C,CAAC;AAWF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;EAYtB,CAAC;AAMH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE/E,oGAAoG;AACpG,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,6GAA6G;AAC7G,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;EAwB5B,CAAC;AAEH,2GAA2G;AAC3G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,gGAAgG;AAChG,MAAM,MAAM,0BAA0B,GAAG,iBAAiB,GAAG;IAC3D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAMF,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qGAAqG;IACrG,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA8GD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,aAAa,CAAW;;YAWlB,iBAAiB;IA4B/B;;OAEG;IAEU,OAAO,CAClB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,6BAA6B,CAAC;IAkDzC;;;OAGG;IAEU,eAAe,CAC1B,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,iBAAiB,CAAC;IAgF7B;;OAEG;IAEU,YAAY,CACvB,MAAM,EAAE,cAAc,EAAE,EACxB,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,6BAA6B,EAAE,CAAC;IAa3C;;;OAGG;IAEU,oBAAoB,CAC/B,MAAM,EAAE,sBAAsB,EAAE,EAChC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjC,OAAO,CAAC,iBAAiB,EAAE,CAAC;CAYhC;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,iBAAiB,EAC3B,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,EAChB,wBAAwB,CAAC,EAAE,MAAM,GAChC,OAAO,CAAC,cAAc,CAAC,CAmLzB"}