@wowok/agent-mcp 2.5.3 → 2.5.5

package/dist/project/semantic-assembler.d.ts

@@ -0,0 +1,93 @@
+import { type Project, type ProjectObject, type GraphEdge } from "@wowok/wowok";
+import type { ReputationData } from "./graph-builder.js";
+export interface SemanticObjectContext {
+    address: string;
+    name: string | null;
+    objectType: string | null;
+    role: string | null;
+    description: string;
+    keyFields: Record<string, unknown>;
+    cacheFreshness: "fresh" | "stale" | "unknown";
+}
+export interface SemanticGraphContext {
+    nodeCount: number;
+    edgeCount: number;
+    edgesByType: Record<string, number>;
+    edgesBySource: Record<string, number>;
+    directDependencies: Array<{
+        target: string;
+        targetType: string | null;
+        fieldName: string | null;
+        relationshipType: string;
+    }>;
+    potentialGaps: Array<{
+        target: string;
+        targetType: string | null;
+        fieldName: string;
+        reason: string;
+    }>;
+}
+export interface SemanticReputationContext {
+    address: string;
+    likes: number;
+    dislikes: number;
+    affiliations: number;
+    sentimentScore: number;
+    notableVoters: Array<{
+        who: string;
+        like: boolean;
+        dislike: boolean;
+        affiliation: boolean;
+    }>;
+}
+export interface SemanticProjectContext {
+    project: {
+        prefix: string;
+        name: string;
+        description: string | null;
+        industry: string | null;
+        perspective: string;
+        status: string;
+        network: string;
+        serviceAddress: string | null;
+        currentVersion: string | null;
+    };
+    objects: SemanticObjectContext[];
+    graph: SemanticGraphContext;
+    reputation: SemanticReputationContext[];
+    freshnessSummary: {
+        freshCount: number;
+        staleCount: number;
+        unknownCount: number;
+        oldestFetch: number | null;
+        newestFetch: number | null;
+    };
+}
+export interface EvaluationPrompt {
+    evaluationType: "risk" | "trust" | "worth_buying" | "completeness" | "value";
+    context: SemanticProjectContext;
+    prompt: string;
+    scoringCriteria: ScoringCriterion[];
+}
+export interface ScoringCriterion {
+    name: string;
+    description: string;
+    weight: number;
+    minScore: number;
+    maxScore: number;
+}
+export declare class SemanticAssembler {
+    private localProject;
+    constructor();
+    assemble(project: Project, objects: ProjectObject[], edges: GraphEdge[], reputation?: Map<string, ReputationData>): Promise<SemanticProjectContext>;
+    private assembleObjects;
+    private describeObject;
+    private extractKeyFields;
+    private assembleGraph;
+    private assembleReputation;
+    private classifyFreshness;
+    private computeFreshnessSummary;
+    buildEvaluationPrompt(evaluationType: EvaluationPrompt["evaluationType"], context: SemanticProjectContext): EvaluationPrompt;
+    private getScoringCriteria;
+    private formatPrompt;
+}

package/dist/project/semantic-assembler.js

@@ -0,0 +1,345 @@
+import { LocalProject, } from "@wowok/wowok";
+const FRESH_THRESHOLD_MS = 1 * 60 * 60 * 1000;
+const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+export class SemanticAssembler {
+    localProject;
+    constructor() {
+        this.localProject = LocalProject.Instance();
+    }
+    async assemble(project, objects, edges, reputation) {
+        const objectContexts = await this.assembleObjects(objects);
+        const graphContext = this.assembleGraph(edges);
+        const reputationContexts = this.assembleReputation(objects, reputation);
+        const freshnessSummary = this.computeFreshnessSummary(objectContexts);
+        return {
+            project: {
+                prefix: project.prefix,
+                name: project.name,
+                description: project.description,
+                industry: project.industry,
+                perspective: project.perspective,
+                status: project.status,
+                network: project.network,
+                serviceAddress: project.serviceAddress,
+                currentVersion: project.currentVersion,
+            },
+            objects: objectContexts,
+            graph: graphContext,
+            reputation: reputationContexts,
+            freshnessSummary,
+        };
+    }
+    async assembleObjects(objects) {
+        const result = [];
+        for (const obj of objects) {
+            const cached = await this.localProject.getCachedObject(obj.objectAddress);
+            const description = cached
+                ? this.describeObject(obj, cached)
+                : `Object ${obj.objectAddress} (no cached on-chain data)`;
+            const keyFields = cached
+                ? this.extractKeyFields(obj.objectType, cached)
+                : {};
+            const cacheFreshness = cached
+                ? this.classifyFreshness(cached.fetchedAt)
+                : "unknown";
+            result.push({
+                address: obj.objectAddress,
+                name: obj.objectName,
+                objectType: obj.objectType,
+                role: obj.role,
+                description,
+                keyFields,
+                cacheFreshness,
+            });
+        }
+        return result;
+    }
+    describeObject(obj, cached) {
+        const type = obj.objectType ?? "unknown";
+        const name = obj.objectName ?? abbreviateAddress(obj.objectAddress);
+        let desc = `${type} "${name}" at ${abbreviateAddress(obj.objectAddress)}`;
+        try {
+            const data = JSON.parse(cached.data);
+            switch (type) {
+                case "Service": {
+                    const published = data.bPublished;
+                    const paused = data.bPaused;
+                    const sales = data.sales;
+                    desc += published
+                        ? paused
+                            ? " (published but PAUSED)"
+                            : " (published, active)"
+                        : " (not yet published)";
+                    if (sales && Array.isArray(sales) && sales.length > 0) {
+                        desc += ` with ${sales.length} sale option(s)`;
+                    }
+                    break;
+                }
+                case "Machine": {
+                    const nodeCount = data.node_count ?? data.nodeCount;
+                    const published = data.bPublished;
+                    desc += published
+                        ? ` (published, ${nodeCount} nodes)`
+                        : ` (draft, ${nodeCount} nodes)`;
+                    break;
+                }
+                case "Treasury": {
+                    desc += " (compensation fund)";
+                    break;
+                }
+                case "Guard": {
+                    desc += " (validation rules)";
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+        catch {
+        }
+        return desc;
+    }
+    extractKeyFields(objectType, cached) {
+        const fields = {};
+        try {
+            const data = JSON.parse(cached.data);
+            switch (objectType) {
+                case "Service":
+                    fields.bPublished = data.bPublished;
+                    fields.bPaused = data.bPaused;
+                    fields.sales = data.sales;
+                    fields.machine = data.machine;
+                    fields.buy_guard = data.buy_guard;
+                    fields.permission = data.permission;
+                    fields.compensation_fund = data.compensation_fund;
+                    fields.order_allocators = data.order_allocators;
+                    fields.arbitrations = data.arbitrations;
+                    fields.rewards = data.rewards;
+                    fields.repositories = data.repositories;
+                    break;
+                case "Machine":
+                    fields.bPublished = data.bPublished;
+                    fields.bPaused = data.bPaused;
+                    fields.node_count = data.node_count ?? data.nodeCount;
+                    fields.permission = data.permission;
+                    break;
+                case "Treasury":
+                    fields.permission = data.permission;
+                    fields.guard = data.guard;
+                    break;
+                case "Allocation":
+                case "Arbitration":
+                case "Reward":
+                case "Repository":
+                case "Demand":
+                    fields.permission = data.permission;
+                    fields.guard = data.guard;
+                    break;
+                default:
+                    break;
+            }
+        }
+        catch {
+        }
+        return fields;
+    }
+    assembleGraph(edges) {
+        const edgesByType = {};
+        const edgesBySource = {};
+        const directDependencies = [];
+        const potentialGaps = [];
+        for (const edge of edges) {
+            edgesByType[edge.relationshipType] = (edgesByType[edge.relationshipType] ?? 0) + 1;
+            edgesBySource[edge.edgeSource] = (edgesBySource[edge.edgeSource] ?? 0) + 1;
+            if (edge.edgeSource === "internal" && edge.depth === 0) {
+                directDependencies.push({
+                    target: edge.targetObject,
+                    targetType: null,
+                    fieldName: edge.fieldName,
+                    relationshipType: edge.relationshipType,
+                });
+            }
+            if (edge.edgeSource === "potential") {
+                const reason = edge.metadata?.reason;
+                potentialGaps.push({
+                    target: edge.targetObject,
+                    targetType: edge.metadata?.expected_target_type,
+                    fieldName: edge.fieldName ?? "unknown",
+                    reason: typeof reason === "string" ? reason : "expected_relationship_missing",
+                });
+            }
+        }
+        return {
+            nodeCount: new Set([...edges.map((e) => e.sourceObject), ...edges.map((e) => e.targetObject)]).size,
+            edgeCount: edges.length,
+            edgesByType,
+            edgesBySource,
+            directDependencies,
+            potentialGaps,
+        };
+    }
+    assembleReputation(objects, reputation) {
+        if (!reputation || reputation.size === 0)
+            return [];
+        const result = [];
+        for (const obj of objects) {
+            const rep = reputation.get(obj.objectAddress);
+            if (!rep)
+                continue;
+            const total = rep.likes + rep.dislikes;
+            const sentimentScore = total > 0 ? rep.likes / total : 0.5;
+            result.push({
+                address: obj.objectAddress,
+                likes: rep.likes,
+                dislikes: rep.dislikes,
+                affiliations: rep.affiliations,
+                sentimentScore,
+                notableVoters: rep.voters.slice(0, 5).map((v) => ({
+                    who: abbreviateAddress(v.who),
+                    like: v.like,
+                    dislike: v.dislike,
+                    affiliation: v.affiliation,
+                })),
+            });
+        }
+        return result;
+    }
+    classifyFreshness(fetchedAt) {
+        const age = Date.now() - fetchedAt;
+        if (age < FRESH_THRESHOLD_MS)
+            return "fresh";
+        if (age < STALE_THRESHOLD_MS)
+            return "stale";
+        return "stale";
+    }
+    computeFreshnessSummary(objects) {
+        let freshCount = 0;
+        let staleCount = 0;
+        let unknownCount = 0;
+        let oldestFetch = null;
+        let newestFetch = null;
+        for (const obj of objects) {
+            switch (obj.cacheFreshness) {
+                case "fresh":
+                    freshCount++;
+                    break;
+                case "stale":
+                    staleCount++;
+                    break;
+                case "unknown":
+                    unknownCount++;
+                    break;
+            }
+        }
+        return { freshCount, staleCount, unknownCount, oldestFetch, newestFetch };
+    }
+    buildEvaluationPrompt(evaluationType, context) {
+        const criteria = this.getScoringCriteria(evaluationType);
+        const prompt = this.formatPrompt(evaluationType, context, criteria);
+        return {
+            evaluationType,
+            context,
+            prompt,
+            scoringCriteria: criteria,
+        };
+    }
+    getScoringCriteria(evaluationType) {
+        switch (evaluationType) {
+            case "risk":
+                return [
+                    { name: "structural_risk", description: "Risk from missing bindings, broken workflows, incomplete setup", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "fund_safety", description: "Risk from Treasury/Allocation misconfiguration, missing compensation fund", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "operational_risk", description: "Risk from Machine/Guard complexity, pause state, missing arbitration", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "governance_risk", description: "Risk from Permission setup, missing UM, overly permissive rules", weight: 0.2, minScore: 0, maxScore: 100 },
+                ];
+            case "trust":
+                return [
+                    { name: "reputation", description: "Registrar like/dislike ratio and affiliation count", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "arbitration_coverage", description: "Presence and quality of arbitration arrangements", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "guard_quality", description: "Guard rule complexity and coverage of business scenarios", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "transparency", description: "Object descriptions, repository data, contact information availability", weight: 0.2, minScore: 0, maxScore: 100 },
+                ];
+            case "worth_buying":
+                return [
+                    { name: "price_reasonableness", description: "Service pricing vs. comparable services and market norms", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "refund_protection", description: "Compensation fund balance, lock duration, refund workflow availability", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "risk_adjusted_value", description: "Value proposition adjusted for project risk score", weight: 0.25, minScore: 0, maxScore: 100 },
+                    { name: "trust_adjusted_value", description: "Value proposition adjusted for merchant trust score", weight: 0.2, minScore: 0, maxScore: 100 },
+                ];
+            case "completeness":
+                return [
+                    { name: "object_coverage", description: "Expected objects present vs. missing (based on EXPECTED_RELATIONSHIPS)", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "binding_completeness", description: "Required bindings established (Service→Machine, Guard, Permission, etc.)", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "workflow_rationality", description: "Machine node topology is sound, no dangling nodes or cycles", weight: 0.2, minScore: 0, maxScore: 100 },
+                    { name: "deployment_readiness", description: "Service publishable, all prerequisites met", weight: 0.2, minScore: 0, maxScore: 100 },
+                ];
+            case "value":
+                return [
+                    { name: "market_positioning", description: "Service differentiation and competitive positioning", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "revenue_potential", description: "Pricing strategy and revenue model viability", weight: 0.3, minScore: 0, maxScore: 100 },
+                    { name: "scalability", description: "Ability to handle growth (Machine capacity, Allocation flexibility)", weight: 0.2, minScore: 0, maxScore: 100 },
+                    { name: "ecosystem_fit", description: "Integration with WoWok ecosystem (rewards, demands, repositories)", weight: 0.2, minScore: 0, maxScore: 100 },
+                ];
+        }
+    }
+    formatPrompt(evaluationType, context, criteria) {
+        const lines = [];
+        lines.push(`# Project Evaluation: ${evaluationType.toUpperCase()}`);
+        lines.push("");
+        lines.push(`## Project: ${context.project.name} (${context.project.prefix})`);
+        lines.push(`- Perspective: ${context.project.perspective}`);
+        lines.push(`- Status: ${context.project.status}`);
+        lines.push(`- Network: ${context.project.network}`);
+        lines.push(`- Industry: ${context.project.industry ?? "unspecified"}`);
+        lines.push(`- Service: ${context.project.serviceAddress ?? "not set"}`);
+        lines.push("");
+        lines.push("## Objects");
+        for (const obj of context.objects) {
+            lines.push(`- ${obj.description}`);
+        }
+        lines.push("");
+        lines.push("## Relationship Graph");
+        lines.push(`- Total nodes: ${context.graph.nodeCount}`);
+        lines.push(`- Total edges: ${context.graph.edgeCount}`);
+        lines.push(`- Edge sources: ${JSON.stringify(context.graph.edgesBySource)}`);
+        lines.push(`- Edge types: ${JSON.stringify(context.graph.edgesByType)}`);
+        lines.push(`- Direct dependencies: ${context.graph.directDependencies.length}`);
+        if (context.graph.potentialGaps.length > 0) {
+            lines.push(`- **Missing relationships (potential gaps): ${context.graph.potentialGaps.length}**`);
+            for (const gap of context.graph.potentialGaps.slice(0, 10)) {
+                lines.push(`  - ${gap.fieldName} → ${gap.targetType ?? "unknown"} (${gap.reason})`);
+            }
+        }
+        lines.push("");
+        if (context.reputation.length > 0) {
+            lines.push("## Reputation Data (from Registrar)");
+            for (const rep of context.reputation) {
+                lines.push(`- ${abbreviateAddress(rep.address)}: ${rep.likes} likes, ${rep.dislikes} dislikes, ${rep.affiliations} affiliations (sentiment: ${(rep.sentimentScore * 100).toFixed(0)}%)`);
+            }
+            lines.push("");
+        }
+        lines.push("## Cache Freshness");
+        lines.push(`- Fresh: ${context.freshnessSummary.freshCount}`);
+        lines.push(`- Stale: ${context.freshnessSummary.staleCount}`);
+        lines.push(`- Unknown: ${context.freshnessSummary.unknownCount}`);
+        lines.push("");
+        lines.push("## Scoring Criteria");
+        lines.push("Please score each criterion (0-100, higher = better) and provide a brief justification:");
+        for (const c of criteria) {
+            lines.push(`- **${c.name}** (weight: ${c.weight}): ${c.description}`);
+        }
+        lines.push("");
+        lines.push("## Instructions");
+        lines.push(`1. Analyze the project from the "${evaluationType}" perspective.`);
+        lines.push("2. Score each criterion above (0-100).");
+        lines.push("3. Compute a weighted overall score.");
+        lines.push("4. Provide a 1-2 sentence summary of your assessment.");
+        lines.push("5. Return the result as JSON: { score: number, summary: string, details: { criterion_scores: {...}, justification: string } }");
+        return lines.join("\n");
+    }
+}
+function abbreviateAddress(address) {
+    if (!address || address.length < 12)
+        return address;
+    return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}