@indexnetwork/protocol 0.1.0

package/dist/tools/tool.helpers.d.ts

@@ -0,0 +1,225 @@
+import { z } from "zod";
+import type { ModelConfig } from "../agents/model.config.js";
+import type { ProfileDocument } from "../agents/profile.generator.js";
+import type { ChatGraphCompositeDatabase, IndexMembership, UserRecord, UserDatabase, SystemDatabase, NegotiationDatabase } from "../interfaces/database.interface.js";
+import type { Scraper } from "../interfaces/scraper.interface.js";
+import type { Cache, HydeCache } from "../interfaces/cache.interface.js";
+import type { CompiledOpportunityGraph } from "../support/opportunity.discover.js";
+import type { IntegrationAdapter } from "../interfaces/integration.interface.js";
+import type { ContactServiceAdapter } from "../interfaces/contact.interface.js";
+import type { ProfileEnricher } from "../interfaces/enrichment.interface.js";
+import type { IntentGraphQueue } from "../interfaces/queue.interface.js";
+import type { ChatSessionReader } from "../interfaces/chat-session.interface.js";
+import type { Embedder } from "../interfaces/embedder.interface.js";
+/** Profile without embedding — used in resolved context to avoid bloating prompts and memory. */
+export type ProfileContext = Omit<ProfileDocument, "embedding"> | null;
+/** Minimal interface for an invokable compiled LangGraph. */
+export type CompiledGraph = {
+    invoke: (input: any) => Promise<any>;
+};
+/**
+ * Resolved context available to every tool handler.
+ * Contains the current user and optional index identity, resolved from DB at init.
+ * The LLM can see this context (via system prompt) but cannot change it.
+ */
+export interface ResolvedToolContext {
+    userId: string;
+    userName: string;
+    userEmail: string;
+    indexId?: string;
+    indexName?: string;
+    /** True when chat is index-scoped and the user owns the index. */
+    isOwner?: boolean;
+    user: UserRecord;
+    userProfile: ProfileContext;
+    userIndexes: IndexMembership[];
+    scopedIndex?: {
+        id: string;
+        title: string;
+        prompt: string | null;
+    };
+    scopedMembershipRole?: "owner" | "member";
+    /** True when user has not completed onboarding (onboarding.completedAt is null). */
+    isOnboarding: boolean;
+    /** True when the user has a non-empty name. */
+    hasName: boolean;
+    /** Chat session ID when tools are used in a chat; used for draft opportunities (context.conversationId). */
+    sessionId?: string;
+}
+/**
+ * Dependencies passed when creating tools for a user session.
+ * Includes DB adapters, embedder, and scraper.
+ *
+ * Note: userDb and systemDb are optional inputs - if not provided, createChatTools
+ * will create them internally from the chatDatabaseAdapter singleton.
+ */
+export interface ToolContext {
+    userId: string;
+    /** @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. */
+    database: ChatGraphCompositeDatabase;
+    /** Context-bound database for accessing the authenticated user's own resources. Created internally if not provided. */
+    userDb?: UserDatabase;
+    /** Context-bound database for LLM/system operations on cross-user resources within shared indexes. Created internally if not provided. */
+    systemDb?: SystemDatabase;
+    embedder: Embedder;
+    scraper: Scraper;
+    /** When set, chat is scoped to this index; tools use it as default for read_intents and create_intent. */
+    indexId?: string;
+    /** Chat session ID when creating tools for a chat; enables draft opportunities with context.conversationId. */
+    sessionId?: string;
+    /** General-purpose cache (e.g. for tool results). */
+    cache: Cache;
+    /** Dedicated cache for HyDE graph (may be same instance as cache). */
+    hydeCache: HydeCache;
+    /** External integration platform adapter (OAuth, tool actions). */
+    integration: IntegrationAdapter;
+    /** Queue for enqueuing follow-up intent processing (HyDE generation/deletion). */
+    intentQueue: IntentGraphQueue;
+    /** Contact management operations. */
+    contactService: ContactServiceAdapter;
+    /** Chat session reader for loading conversation history. */
+    chatSession: ChatSessionReader;
+    /** Profile enrichment from external data sources. */
+    enricher: ProfileEnricher;
+    /** Database adapter for negotiation/conversation operations. */
+    negotiationDatabase: NegotiationDatabase;
+    /** Integration importer for bulk contact import from toolkits. */
+    integrationImporter: {
+        importContacts(userId: string, toolkit: string): Promise<{
+            imported: number;
+            skipped: number;
+            newContacts: number;
+            existingContacts: number;
+        }>;
+    };
+    /** Factory for user-scoped database access. */
+    createUserDatabase: (db: ChatGraphCompositeDatabase, userId: string) => UserDatabase;
+    /** Factory for system-scoped database access. */
+    createSystemDatabase: (db: ChatGraphCompositeDatabase, userId: string, indexScope: string[], embedder?: Embedder) => SystemDatabase;
+    /** Optional runtime LLM config. Pass to override env vars for API key, model, etc. */
+    modelConfig?: ModelConfig;
+}
+/**
+ * All external dependencies needed to initialize the protocol tool engine.
+ * The host application (composition root) must provide concrete implementations.
+ * This is the subset of ToolContext that is NOT per-request (no userId, indexId, sessionId).
+ */
+export type ProtocolDeps = Omit<ToolContext, 'userId' | 'indexId' | 'sessionId' | 'userDb' | 'systemDb'>;
+/**
+ * Thrown when a requested chat scope is invalid for the authenticated user.
+ * Controllers can map this to an HTTP status code.
+ */
+export declare class ChatContextAccessError extends Error {
+    readonly statusCode: number;
+    readonly code: "USER_NOT_FOUND" | "INDEX_NOT_FOUND" | "INDEX_MEMBERSHIP_REQUIRED";
+    constructor(message: string, statusCode: number, code: "USER_NOT_FOUND" | "INDEX_NOT_FOUND" | "INDEX_MEMBERSHIP_REQUIRED");
+}
+/**
+ * Resolve the canonical context used by chat tools and system prompt.
+ * This preloads user identity, profile, index memberships, and scoped index role.
+ */
+export declare function resolveChatContext(params: {
+    database: Pick<ChatGraphCompositeDatabase, "getUser" | "getProfile" | "getIndexMemberships" | "getIndexMembership" | "getIndex" | "isIndexOwner" | "isIndexMember">;
+    userId: string;
+    indexId?: string;
+    /** Chat session ID for draft opportunities (stored as context.conversationId). */
+    sessionId?: string;
+}): Promise<ResolvedToolContext>;
+/**
+ * Type for the `defineTool` closure created in `createChatTools`.
+ * Auto-injects resolved context and provides uniform logging / error handling.
+ */
+export type DefineTool = <T extends z.ZodType>(opts: {
+    name: string;
+    description: string;
+    querySchema: T;
+    handler: (input: {
+        context: ResolvedToolContext;
+        query: z.infer<T>;
+    }) => Promise<string>;
+}) => any;
+/**
+ * A raw tool definition before LangChain wrapping.
+ * Used by the tool registry for direct HTTP invocation.
+ */
+export interface RawToolDefinition {
+    name: string;
+    description: string;
+    schema: z.ZodType;
+    handler: (input: {
+        context: ResolvedToolContext;
+        query: unknown;
+    }) => Promise<string>;
+}
+/**
+ * Registry mapping tool names to their raw definitions.
+ */
+export type ToolRegistry = Map<string, RawToolDefinition>;
+/**
+ * Shared dependencies available to all tool domain factories.
+ * Passed by `createChatTools` after compiling all subgraphs.
+ */
+export interface ToolDeps {
+    /** @deprecated Use userDb or systemDb instead. Kept for backwards compatibility. */
+    database: ChatGraphCompositeDatabase;
+    /** Context-bound database for accessing the authenticated user's own resources. */
+    userDb: UserDatabase;
+    /** Context-bound database for LLM/system operations on cross-user resources within shared indexes. */
+    systemDb: SystemDatabase;
+    scraper: Scraper;
+    embedder: import('../interfaces/embedder.interface.js').Embedder;
+    cache: Cache;
+    integration: IntegrationAdapter;
+    contactService: ContactServiceAdapter;
+    integrationImporter: {
+        importContacts(userId: string, toolkit: string): Promise<{
+            imported: number;
+            skipped: number;
+            newContacts: number;
+            existingContacts: number;
+        }>;
+    };
+    enricher: ProfileEnricher;
+    graphs: {
+        profile: CompiledGraph;
+        intent: CompiledGraph;
+        index: CompiledGraph;
+        indexMembership: CompiledGraph;
+        intentIndex: CompiledGraph;
+        opportunity: CompiledOpportunityGraph;
+    };
+}
+export declare function success<T>(data: T): string;
+export declare function error(message: string, debugSteps?: Array<{
+    step: string;
+    detail?: string;
+    data?: Record<string, unknown>;
+}>): string;
+/** Return needsClarification for missing required fields. */
+export declare function needsClarification(params: {
+    missingFields: string[];
+    message: string;
+}): string;
+/** UUID v4 format: 8-4-4-4-12 hex chars (e.g. c2505011-2e45-426e-81dd-b9abb9b72023) */
+export declare const UUID_REGEX: RegExp;
+/**
+ * Resolves an array of index IDs to their display titles.
+ * Skips any IDs that don't resolve (deleted or invalid indexes).
+ */
+export declare function resolveIndexNames(database: {
+    getIndex(id: string): Promise<{
+        id: string;
+        title: string;
+    } | null>;
+}, indexIds: string[]): Promise<string[]>;
+/**
+ * Normalize a URL string: if it lacks a protocol, prepend "https://".
+ * Returns the normalized URL or null if the result is not a valid URL.
+ */
+export declare function normalizeUrl(raw: string): string | null;
+/**
+ * Extract unique, valid URLs from a string (e.g. user message or details).
+ * Handles both full URLs (https://...) and bare domains (github.com/...).
+ */
+export declare function extractUrls(text: string): string[];
+//# sourceMappingURL=tool.helpers.d.ts.map

package/dist/tools/tool.helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.helpers.d.ts","sourceRoot":"","sources":["../../src/tools/tool.helpers.ts"],"names":[],"mappings":"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"}

package/dist/tools/tool.helpers.js

@@ -0,0 +1,172 @@
+/**
+ * Thrown when a requested chat scope is invalid for the authenticated user.
+ * Controllers can map this to an HTTP status code.
+ */
+export class ChatContextAccessError extends Error {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.name = "ChatContextAccessError";
+    }
+}
+/**
+ * Resolve the canonical context used by chat tools and system prompt.
+ * This preloads user identity, profile, index memberships, and scoped index role.
+ */
+export async function resolveChatContext(params) {
+    const { database, userId, indexId, sessionId } = params;
+    const [user, rawProfile, userIndexes] = await Promise.all([
+        database.getUser(userId),
+        database.getProfile(userId),
+        database.getIndexMemberships(userId),
+    ]);
+    // Omit embedding from profile so resolved context stays lean (embedding is for search only).
+    let userProfile = null;
+    if (rawProfile) {
+        const { embedding: _omit, ...rest } = rawProfile;
+        userProfile = rest;
+    }
+    if (!user) {
+        throw new ChatContextAccessError("User not found", 404, "USER_NOT_FOUND");
+    }
+    let scopedIndex = undefined;
+    let scopedMembershipRole = undefined;
+    let isOwner = false;
+    let indexName;
+    if (indexId) {
+        const [index, isMember, owner] = await Promise.all([
+            database.getIndex(indexId),
+            database.isIndexMember(indexId, userId),
+            database.isIndexOwner(indexId, userId),
+        ]);
+        if (!index) {
+            throw new ChatContextAccessError("Index not found", 404, "INDEX_NOT_FOUND");
+        }
+        if (!isMember) {
+            throw new ChatContextAccessError("You are not a member of this index", 403, "INDEX_MEMBERSHIP_REQUIRED");
+        }
+        let membership = userIndexes.find((m) => m.indexId === index.id);
+        if (membership === undefined) {
+            membership = (await database.getIndexMembership(index.id, userId)) ?? undefined;
+        }
+        scopedIndex = {
+            id: index.id,
+            title: index.title,
+            prompt: membership?.indexPrompt ?? null,
+        };
+        isOwner = owner;
+        indexName = index.title;
+        scopedMembershipRole = owner ? "owner" : "member";
+    }
+    const userName = user.name ?? "Unknown";
+    const userEmail = user.email ?? "";
+    const hasName = !!user.name?.trim();
+    return {
+        userId,
+        userName,
+        userEmail,
+        indexId,
+        indexName,
+        isOwner,
+        user,
+        userProfile,
+        userIndexes,
+        scopedIndex,
+        scopedMembershipRole,
+        isOnboarding: !(user.onboarding?.completedAt),
+        hasName,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// TOOL RESULT HELPERS
+// ═══════════════════════════════════════════════════════════════════════════════
+export function success(data) {
+    return JSON.stringify({ success: true, data });
+}
+export function error(message, debugSteps) {
+    return JSON.stringify({
+        success: false,
+        error: message,
+        ...(debugSteps?.length ? { debugSteps } : {}),
+    });
+}
+/** Return needsClarification for missing required fields. */
+export function needsClarification(params) {
+    return JSON.stringify({
+        success: false,
+        needsClarification: true,
+        ...params,
+    });
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS & UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+/** Matches http/https URLs in text; captures full URL. */
+const URL_IN_TEXT_REGEX = /https?:\/\/[^\s"'<>)\]]+/gi;
+/**
+ * Matches bare domain URLs without protocol (e.g. github.com/foo, www.example.com).
+ * Requires at least a SLD.TLD pattern followed by optional path.
+ * Negative lookbehind ensures we don't double-match URLs already caught by URL_IN_TEXT_REGEX.
+ */
+const BARE_URL_REGEX = /(?<!\w:\/\/)(?<![/\w])(?:www\.)?[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.(?:com|org|net|io|dev|co|ai|app|xyz|me|info|gg|so|sh|cc|ly|fm|tv|to|tech|design|network|world|edu|gov|mil|int|us|uk|eu|de|fr|ca|au|jp|cn|in|br|nl|se|no|fi|dk|ch|at|be|it|es|pt|pl|cz|ru|kr|tw|hk|sg|nz|za|mx|ar|cl|id|ph|th|vn|my|ie)(?:\/[^\s"'<>)\]]*)?/gi;
+/** UUID v4 format: 8-4-4-4-12 hex chars (e.g. c2505011-2e45-426e-81dd-b9abb9b72023) */
+export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Resolves an array of index IDs to their display titles.
+ * Skips any IDs that don't resolve (deleted or invalid indexes).
+ */
+export async function resolveIndexNames(database, indexIds) {
+    if (indexIds.length === 0)
+        return [];
+    const results = await Promise.all(indexIds.map(id => database.getIndex(id)));
+    return results.filter(Boolean).map(idx => idx.title);
+}
+/**
+ * Normalize a URL string: if it lacks a protocol, prepend "https://".
+ * Returns the normalized URL or null if the result is not a valid URL.
+ */
+export function normalizeUrl(raw) {
+    let url = raw.replace(/[.,;:!?)]+$/, "").trim();
+    if (!/^https?:\/\//i.test(url)) {
+        url = `https://${url}`;
+    }
+    try {
+        new URL(url);
+        return url;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract unique, valid URLs from a string (e.g. user message or details).
+ * Handles both full URLs (https://...) and bare domains (github.com/...).
+ */
+export function extractUrls(text) {
+    if (!text || typeof text !== "string")
+        return [];
+    const seen = new Set();
+    const out = [];
+    // Pass 1: full protocol URLs
+    const fullMatches = text.match(URL_IN_TEXT_REGEX) ?? [];
+    for (const raw of fullMatches) {
+        const url = normalizeUrl(raw);
+        if (url && !seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    }
+    // Pass 2: bare domain URLs (e.g. github.com/foo)
+    const bareMatches = text.match(BARE_URL_REGEX) ?? [];
+    for (const raw of bareMatches) {
+        const url = normalizeUrl(raw);
+        if (url && !seen.has(url)) {
+            seen.add(url);
+            out.push(url);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=tool.helpers.js.map

package/dist/tools/tool.helpers.js.map

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

package/dist/tools/tool.registry.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDeps, ToolRegistry } from './tool.helpers.js';
+/**
+ * Creates a tool registry containing all tool handlers indexed by name.
+ * Handlers are raw async functions (not LangChain tool() wrappers) that
+ * accept { context, query } and return a JSON string.
+ *
+ * @param deps - Shared tool dependencies (graphs, database, embedder, etc.)
+ * @param context - Resolved user context for this request.
+ * @returns Map of tool name to raw tool definition.
+ */
+export declare function createToolRegistry(deps: ToolDeps): ToolRegistry;
+//# sourceMappingURL=tool.registry.d.ts.map

package/dist/tools/tool.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.registry.d.ts","sourceRoot":"","sources":["../../src/tools/tool.registry.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAmC,QAAQ,EAAqB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAapH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAkD/D"}

package/dist/tools/tool.registry.js

@@ -0,0 +1,62 @@
+import { createProfileTools } from './profile.tools.js';
+import { createIntentTools } from './intent.tools.js';
+import { createIndexTools } from './index.tools.js';
+import { createOpportunityTools } from './opportunity.tools.js';
+import { createUtilityTools } from './utility.tools.js';
+import { createIntegrationTools } from './integration.tools.js';
+import { createContactTools } from './contact.tools.js';
+import { protocolLogger } from '../support/protocol.logger.js';
+import { error } from './tool.helpers.js';
+const logger = protocolLogger('ToolRegistry');
+/**
+ * Creates a tool registry containing all tool handlers indexed by name.
+ * Handlers are raw async functions (not LangChain tool() wrappers) that
+ * accept { context, query } and return a JSON string.
+ *
+ * @param deps - Shared tool dependencies (graphs, database, embedder, etc.)
+ * @param context - Resolved user context for this request.
+ * @returns Map of tool name to raw tool definition.
+ */
+export function createToolRegistry(deps) {
+    const registry = new Map();
+    // defineTool that captures raw handlers into the registry
+    function defineTool(opts) {
+        const entry = {
+            name: opts.name,
+            description: opts.description,
+            schema: opts.querySchema,
+            handler: async (input) => {
+                logger.verbose(`Tool: ${opts.name}`, {
+                    context: { userId: input.context.userId, indexId: input.context.indexId },
+                    query: input.query,
+                });
+                try {
+                    return await opts.handler({ context: input.context, query: input.query });
+                }
+                catch (err) {
+                    logger.error(`${opts.name} failed`, {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    return error(`Failed to execute ${opts.name}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            },
+        };
+        registry.set(opts.name, entry);
+        // Return a dummy — create*Tools functions collect return values into arrays,
+        // but for the registry path we only need the side-effect on the Map.
+        return null;
+    }
+    // Create all tool domains -- each one calls defineTool() which populates the registry.
+    // The local defineTool is compatible with DefineTool (which returns any).
+    const dt = defineTool;
+    createProfileTools(dt, deps);
+    createIntentTools(dt, deps);
+    createIndexTools(dt, deps);
+    createOpportunityTools(dt, deps);
+    createUtilityTools(dt, deps);
+    createIntegrationTools(dt, deps);
+    createContactTools(dt, deps);
+    logger.verbose(`Tool registry created with ${registry.size} tools`);
+    return registry;
+}
+//# sourceMappingURL=tool.registry.js.map

package/dist/tools/tool.registry.js.map

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

package/dist/tools/utility.tools.d.ts

@@ -0,0 +1,3 @@
+import type { DefineTool, ToolDeps } from "./tool.helpers.js";
+export declare function createUtilityTools(defineTool: DefineTool, deps: ToolDeps): readonly [any, any];
+//# sourceMappingURL=utility.tools.d.ts.map

package/dist/tools/utility.tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.tools.d.ts","sourceRoot":"","sources":["../../src/tools/utility.tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG9D,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,uBAuHxE"}

package/dist/tools/utility.tools.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { success, error, normalizeUrl } from "./tool.helpers.js";
+export function createUtilityTools(defineTool, deps) {
+    const { scraper } = deps;
+    const scrapeUrl = defineTool({
+        name: "scrape_url",
+        description: "Extracts text content from a URL (articles, profiles, documentation, etc.). Use this to read web pages, LinkedIn/GitHub profiles, or any public web content. The URL does not need http:// or https:// — bare domains like github.com/user/repo work fine. Pass 'objective' when you know the downstream use: e.g. 'User wants to create an intent from this link (project/repo).' or 'User wants to update their profile from this page.' — this returns content better suited for that use.",
+        querySchema: z.object({
+            url: z.string().describe("The URL to scrape (protocol optional — e.g. 'github.com/user/repo' is fine)"),
+            objective: z.string().optional().describe("Optional: why we're scraping. E.g. 'User wants to create an intent from this link' or 'User wants to update their profile from this page'. Omit for generic extraction."),
+        }),
+        handler: async ({ context: _context, query }) => {
+            const normalizedUrl = normalizeUrl(query.url);
+            if (!normalizedUrl) {
+                return error("Invalid URL format. Please provide a valid URL (e.g. 'github.com/user/repo' or 'https://example.com').");
+            }
+            const content = await scraper.extractUrlContent(normalizedUrl, {
+                objective: query.objective?.trim() || undefined,
+            });
+            if (!content) {
+                return error("Couldn't extract content from that URL. It may be blocked, require login, or have no extractable text.");
+            }
+            const truncatedContent = content.length > 10000
+                ? content.substring(0, 10000) + "\n\n[Content truncated...]"
+                : content;
+            return success({
+                url: normalizedUrl,
+                contentLength: content.length,
+                content: truncatedContent,
+            });
+        },
+    });
+    const readDocs = defineTool({
+        name: "read_docs",
+        description: "Returns the protocol's business logic documentation: entity model, intent lifecycle, opportunity lifecycle, discovery mechanics, and key workflows. Call this when you need to understand how the system works or explain it to the user.",
+        querySchema: z.object({
+            topic: z.string().optional().describe("Optional: narrow to a specific topic (e.g. 'opportunities', 'intents', 'indexes', 'profiles', 'discovery')."),
+        }),
+        handler: async ({ context: _context, query }) => {
+            const topic = query.topic?.trim().toLowerCase();
+            const sections = {
+                entities: `## Entity Model
+
+- **Users**: People on the platform. Authenticated via session (Better Auth).
+- **Profiles**: A user's identity — bio, skills, interests, location, social links. Generated from account data or social URLs. Has a vector embedding for semantic matching.
+- **Indexes**: Communities or groups. Each has a title, optional prompt (purpose description), and a join policy (anyone or invite_only). Users join indexes as members; the creator is the owner.
+- **Index Members**: Junction between Users and Indexes. Tracks permissions, join date, auto-assign setting, and optional member prompt.
+- **Intents**: What a user is looking for — wants, needs, and priorities. Each has a description (payload), summary, confidence score, and vector embedding. Intents belong to a user but are linked to indexes via IntentIndexes (many-to-many).
+- **IntentIndexes**: Junction between Intents and Indexes. An intent can be in multiple indexes. When an intent is created, it is evaluated against index prompts and linked to relevant ones.
+- **Opportunities**: Discovered connections between users based on intent overlap. Have roles (introducer, patient, agent, peer), status lifecycle, reasoning, and presentation data.
+- **HyDE Documents**: Hypothetical Document Embeddings — generated synthetic documents used for semantic retrieval of intents and profiles`,
+                intents: `## Intent Lifecycle
+
+1. **Creation**: User describes what they're looking for. The IntentClarifier checks if it's specific enough — vague intents get a refinement suggestion before persisting.
+2. **Inference**: The intent graph extracts structured intents from free text. It can infer multiple intents from a single input and reconcile with existing ones (update if similar, create if new).
+3. **Semantic Governance**: Each intent gets a confidence score, semantic entropy measure, speech act type (commissive, directive, assertive), referential anchor, and felicity conditions (sincerity, authority).
+4. **Index Assignment**: After creation, the intent is evaluated against all indexes the user belongs to (using the index prompt as criteria). It's automatically linked to matching indexes via IntentIndexes.
+5. **Discovery**: Creating an intent triggers background opportunity detection — the system looks for other users in shared indexes whose intents complement this one.
+6. **Update/Archive**: Intents can be updated (re-processed through the graph) or archived (soft delete).`,
+                opportunities: `## Opportunity Lifecycle
+
+1. **Detection**: The opportunity graph finds users whose intents semantically complement each other within shared indexes. Uses HyDE embeddings for retrieval and an evaluator agent for scoring.
+2. **Roles**: Each opportunity assigns roles — introducer (who triggered it), patient (seeker), agent (helper), or peer (mutual). The current user's role determines what they see.
+3. **Status Flow**: latent (draft) → pending (sent) → accepted/rejected/expired. Users see "draft", "sent", "connected" in natural language.
+4. **Visibility**: Role-based. The introducer sees the draft first. After sending, the next person in the reveal chain sees it. Not all parties see all details at every stage.
+5. **Presentation**: Each opportunity gets a personalized summary, suggested action, and reasoning — generated by an LLM presenter agent.
+6. **Two Modes**:
+   - **Discovery**: System finds matches for the user's intents in an index (or all indexes). Triggered by create_intent or create_opportunities with searchQuery.
+   - **Introduction**: A user introduces two specific people. The system gathers both profiles and intents from shared indexes and creates the opportunity.`,
+                indexes: `## Index Mechanics
+
+- Indexes are communities where members share what they're looking for.
+- Each index has a **prompt** that describes its purpose (e.g. "AI/ML co-founders in Berlin"). This prompt is used by the intent indexer agent to evaluate whether an intent belongs.
+- **Join policy**: "anyone" (open) or "invite_only" (owner adds members).
+- Members can see all intents in the index (not just their own).
+- The **auto-assign** setting on a membership means new intents by that user are automatically evaluated against the index.
+- Index owners can update settings, add/remove members, and delete the index (if sole member).`,
+                profiles: `## Profile System
+
+- Profiles are auto-generated from user account data (name, email, social links).
+- Can be enriched by scraping LinkedIn, GitHub, Twitter, or personal websites.
+- The profile graph generates a structured identity (bio, skills, interests, location), narrative context, and attributes.
+- Profiles have vector embeddings used for semantic matching in opportunity detection.
+- HyDE (Hypothetical Document Embedding) generates synthetic documents from profiles for better retrieval: Mirror (self-description), Reciprocal (what they'd look for), and Neighborhood (related community context).`,
+                discovery: `## Discovery Mechanics
+
+- Discovery runs when an intent is created (automatic) or when create_opportunities is called explicitly.
+- The opportunity graph pipeline: Preparation (gather context) → Scope (determine indexes) → Discovery (semantic matching of intents) → Evaluation (LLM scores relevance) → Ranking → Persist.
+- Semantic matching uses HyDE embeddings to find candidate intents that complement the source intent.
+- The evaluator agent scores each match on relevance, complementarity, and actionability.
+- Results are persisted as opportunities with appropriate roles and presentation.
+- Background processing: after intent creation, a queue job continues looking for matches asynchronously.`,
+            };
+            if (topic) {
+                const matched = Object.entries(sections).find(([key]) => key.includes(topic) || topic.includes(key));
+                if (matched) {
+                    return success({ topic: matched[0], content: matched[1] });
+                }
+                // If topic not found, return all
+            }
+            const fullDoc = Object.values(sections).join("\n\n");
+            return success({ content: fullDoc });
+        },
+    });
+    return [scrapeUrl, readDocs];
+}
+//# sourceMappingURL=utility.tools.js.map

package/dist/tools/utility.tools.js.map

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