@kya-os/contracts 1.6.17 → 1.6.19

package/dist/reputation/schemas.js

@@ -0,0 +1,499 @@
+"use strict";
+/**
+ * Reputation Engine Schemas
+ *
+ * Zod schemas and TypeScript types for the Bayesian reputation scoring system.
+ * These schemas define the data structures for agent reputation calculation,
+ * including input data, score outputs, and configuration options.
+ *
+ * The reputation system uses a Bayesian approach:
+ *   final_score = (1 - confidence) × prior_score + confidence × empirical_score
+ *
+ * Related Spec: MCP-I §5.1 (Reputation), CLAUDE-reputation-engine.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScoreChangePredictionResponseSchema = exports.ScoreChangePredictionRequestSchema = exports.CalculatorConfigSchema = exports.CalculatorWeightsSchema = exports.CalculatorPresetSchema = exports.ReputationScoreSchema = exports.SimpleReputationLevelSchema = exports.ReputationLevelSchema = exports.ConfidenceLevelSchema = exports.ReputationFactorsSchema = exports.ScoreComponentsSchema = exports.PartialAgentDataSchema = exports.AgentDataSchema = exports.IssueMetricsSchema = exports.ReviewMetricsSchema = exports.InteractionMetricsSchema = exports.CredentialFlagsSchema = exports.MCPLevelSchema = void 0;
+exports.toSimpleReputationLevel = toSimpleReputationLevel;
+exports.getSimpleReputationLevel = getSimpleReputationLevel;
+exports.validateAgentData = validateAgentData;
+exports.validateReputationScore = validateReputationScore;
+exports.validateCalculatorConfig = validateCalculatorConfig;
+exports.getReputationLevel = getReputationLevel;
+exports.getConfidenceLevel = getConfidenceLevel;
+exports.calculateConfidence = calculateConfidence;
+exports.isProvisionalScore = isProvisionalScore;
+const zod_1 = require("zod");
+// ============================================================================
+// MCP LEVEL & CREDENTIALS
+// ============================================================================
+/**
+ * MCP Compliance Level
+ *
+ * Levels 0-3 representing increasing levels of MCP compliance:
+ * - 0: No MCP compliance
+ * - 1: Basic MCP compliance (+5 prior points)
+ * - 2: Standard MCP compliance (+10 prior points)
+ * - 3: Advanced MCP compliance (+15 prior points)
+ */
+exports.MCPLevelSchema = zod_1.z.number().int().min(0).max(3);
+/**
+ * Credential Flags Schema
+ *
+ * Boolean flags representing various verified credentials and certifications.
+ * Each flag contributes to the prior score calculation.
+ */
+exports.CredentialFlagsSchema = zod_1.z.object({
+    /** Identity has been verified through a trusted provider */
+    identityVerified: zod_1.z.boolean().default(false),
+    /** Agent has passed a security audit */
+    securityAuditPassed: zod_1.z.boolean().default(false),
+    /** Agent source code is open source */
+    openSource: zod_1.z.boolean().default(false),
+    /** GitHub account is verified */
+    githubVerified: zod_1.z.boolean().default(false),
+    /** Company email has been verified */
+    companyEmailVerified: zod_1.z.boolean().default(false),
+});
+// ============================================================================
+// INTERACTION METRICS
+// ============================================================================
+/**
+ * Interaction Metrics Schema
+ *
+ * Quantitative metrics about an agent's interactions with other agents/users.
+ * Used in calculating empirical score and confidence level.
+ */
+exports.InteractionMetricsSchema = zod_1.z.object({
+    /** Total number of interactions */
+    totalInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of successful interactions */
+    successfulInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of failed interactions */
+    failedInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of unique interaction partners */
+    uniquePartners: zod_1.z.number().int().nonnegative().default(0),
+    /** Total transaction/interaction volume (monetary or unit-based) */
+    totalVolume: zod_1.z.number().nonnegative().default(0),
+});
+// ============================================================================
+// REVIEW METRICS
+// ============================================================================
+/**
+ * Review Metrics Schema
+ *
+ * Metrics derived from user/agent reviews.
+ * Primary source for empirical score calculation.
+ */
+exports.ReviewMetricsSchema = zod_1.z.object({
+    /** Total number of reviews received */
+    totalReviews: zod_1.z.number().int().nonnegative().default(0),
+    /** Average rating (1.0 to 5.0 scale) */
+    averageRating: zod_1.z.number().min(1).max(5).optional(),
+    /** Number of positive reviews (4+ stars) */
+    positiveReviews: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of negative reviews (2 or fewer stars) */
+    negativeReviews: zod_1.z.number().int().nonnegative().default(0),
+});
+// ============================================================================
+// ISSUE METRICS
+// ============================================================================
+/**
+ * Issue Metrics Schema
+ *
+ * Metrics related to disputes, abuse reports, and other issues.
+ * Negatively impacts reputation score.
+ */
+exports.IssueMetricsSchema = zod_1.z.object({
+    /** Number of disputes filed against this agent */
+    disputesFiled: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of disputes lost (decided against this agent) */
+    disputesLost: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of verified abuse reports */
+    abuseReportsVerified: zod_1.z.number().int().nonnegative().default(0),
+});
+// ============================================================================
+// AGENT DATA (INPUT)
+// ============================================================================
+/**
+ * Agent Data Schema
+ *
+ * Complete input data structure for reputation calculation.
+ * Combines identity, credentials, interactions, reviews, and issues.
+ *
+ * This is the primary input to the reputation calculation engine.
+ */
+exports.AgentDataSchema = zod_1.z.object({
+    // === Identity ===
+    /** Decentralized Identifier (DID) of the agent */
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+    /** Timestamp when the agent was registered (ISO 8601) */
+    createdAt: zod_1.z.string().datetime().optional(),
+    // === Credentials ===
+    /** MCP compliance level (0-3) */
+    mcpLevel: exports.MCPLevelSchema.default(0),
+    /** Credential flags */
+    credentials: exports.CredentialFlagsSchema.optional().default({}),
+    // === Metrics ===
+    /** Interaction metrics */
+    interactions: exports.InteractionMetricsSchema.optional().default({}),
+    /** Review metrics */
+    reviews: exports.ReviewMetricsSchema.optional().default({}),
+    /** Issue metrics */
+    issues: exports.IssueMetricsSchema.optional().default({}),
+    // === Extensibility ===
+    /** Optional metadata for custom extensions */
+    metadata: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+/**
+ * Partial Agent Data Schema
+ *
+ * For updates and partial data scenarios.
+ * All fields are optional except DID.
+ */
+exports.PartialAgentDataSchema = exports.AgentDataSchema.partial().extend({
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+});
+// ============================================================================
+// SCORE COMPONENTS (OUTPUT)
+// ============================================================================
+/**
+ * Score Components Schema (Bayesian Algorithm)
+ *
+ * Breakdown of how the final score was calculated using the Bayesian algorithm.
+ * Provides transparency into the scoring algorithm.
+ *
+ * Formula: final_score = (1 - confidence) × prior_score + confidence × empirical_score
+ */
+exports.ScoreComponentsSchema = zod_1.z.object({
+    /** Prior score based on credentials (50-80 points) */
+    priorScore: zod_1.z.number().min(0).max(100),
+    /** Empirical score based on interactions and reviews (0-100 points) */
+    empiricalScore: zod_1.z.number().min(0).max(100),
+    /** Weight applied to confidence (derived from interactions) */
+    confidenceWeight: zod_1.z.number().min(0).max(1),
+    /** Weight applied to prior (1 - confidenceWeight) */
+    priorWeight: zod_1.z.number().min(0).max(1),
+});
+/**
+ * Reputation Factors Schema
+ *
+ * Detailed breakdown of factors contributing to the reputation score.
+ * This provides a human-readable explanation of why an agent has a particular score.
+ *
+ * Compatible with Know That AI API response format.
+ */
+exports.ReputationFactorsSchema = zod_1.z.object({
+    /** Score based on successful vs failed interactions (0-100) */
+    interactionScore: zod_1.z.number().min(0).max(100),
+    /** Score based on consistency of behavior over time (0-100) */
+    consistencyScore: zod_1.z.number().min(0).max(100),
+    /** Score based on account age / longevity (0-100) */
+    longevityScore: zod_1.z.number().min(0).max(100),
+    /** Score based on diversity of interaction partners (0-100) */
+    partnerDiversityScore: zod_1.z.number().min(0).max(100),
+    /** Score based on positive feedback received (0-100) */
+    feedbackScore: zod_1.z.number().min(0).max(100),
+});
+/**
+ * Confidence Level Schema
+ *
+ * Human-readable confidence categories.
+ */
+exports.ConfidenceLevelSchema = zod_1.z.enum([
+    "Low",
+    "Medium",
+    "High",
+    "VeryHigh",
+]);
+/**
+ * Reputation Level Schema (Detailed)
+ *
+ * Human-readable reputation categories based on score ranges.
+ * Uses granular levels for detailed reputation assessment.
+ */
+exports.ReputationLevelSchema = zod_1.z.enum([
+    "Unknown", // Score not calculable or insufficient data
+    "Poor", // 0-30
+    "BelowAverage", // 30-45
+    "Average", // 45-60
+    "Good", // 60-75
+    "Excellent", // 75-90
+    "Outstanding", // 90-100
+]);
+/**
+ * Simple Reputation Level Schema
+ *
+ * Human-readable reputation categories matching Know That AI API.
+ * Uses 5-tier levels for simplified reputation display.
+ */
+exports.SimpleReputationLevelSchema = zod_1.z.enum([
+    "Very Low", // 0-20
+    "Low", // 20-40
+    "Medium", // 40-60
+    "High", // 60-80
+    "Very High", // 80-100
+]);
+/**
+ * Convert detailed ReputationLevel to SimpleReputationLevel
+ *
+ * Maps the 7-tier detailed levels to the 5-tier simple levels.
+ */
+function toSimpleReputationLevel(level) {
+    switch (level) {
+        case "Unknown":
+        case "Poor":
+            return "Very Low";
+        case "BelowAverage":
+            return "Low";
+        case "Average":
+            return "Medium";
+        case "Good":
+            return "High";
+        case "Excellent":
+        case "Outstanding":
+            return "Very High";
+    }
+}
+/**
+ * Get simple reputation level from numeric score
+ *
+ * @param score - Numeric score (0-100)
+ * @returns Simple reputation level
+ */
+function getSimpleReputationLevel(score) {
+    if (score < 0 || !Number.isFinite(score))
+        return "Very Low";
+    if (score < 20)
+        return "Very Low";
+    if (score < 40)
+        return "Low";
+    if (score < 60)
+        return "Medium";
+    if (score < 80)
+        return "High";
+    return "Very High";
+}
+// ============================================================================
+// REPUTATION SCORE (OUTPUT)
+// ============================================================================
+/**
+ * Reputation Score Schema
+ *
+ * Complete output from the reputation calculation engine.
+ * Includes the final score, confidence metrics, and component breakdown.
+ */
+exports.ReputationScoreSchema = zod_1.z.object({
+    /** Final reputation score (0-100) */
+    score: zod_1.z.number().min(0).max(100),
+    /** Confidence in the score (0-1) */
+    confidence: zod_1.z.number().min(0).max(1),
+    /** Human-readable confidence level */
+    confidenceLevel: exports.ConfidenceLevelSchema,
+    /** Human-readable reputation level */
+    level: exports.ReputationLevelSchema,
+    /** Detailed score component breakdown (Bayesian algorithm) */
+    components: exports.ScoreComponentsSchema,
+    /** Optional detailed factors breakdown (for Know That AI API compatibility) */
+    factors: exports.ReputationFactorsSchema.optional(),
+    /** Whether this score is provisional (limited data) */
+    isProvisional: zod_1.z.boolean(),
+    /** Timestamp when the score was calculated (ISO 8601) */
+    calculatedAt: zod_1.z.string().datetime(),
+    /** DID of the agent this score belongs to */
+    agentDid: zod_1.z.string().min(1),
+});
+// ============================================================================
+// CALCULATOR CONFIGURATION
+// ============================================================================
+/**
+ * Calculator Preset Schema
+ *
+ * Pre-defined calculator configurations for different use cases.
+ */
+exports.CalculatorPresetSchema = zod_1.z.enum([
+    "Testing", // k=5, fast confidence growth (for testing)
+    "Conservative", // k=20, slow confidence growth (production default)
+    "Aggressive", // k=10, moderate confidence growth
+]);
+/**
+ * Calculator Weights Schema
+ *
+ * Weight distribution for scoring components.
+ * All weights should sum to 1.0.
+ */
+exports.CalculatorWeightsSchema = zod_1.z
+    .object({
+    /** Weight for review-based scoring */
+    reviews: zod_1.z.number().min(0).max(1).default(0.4),
+    /** Weight for interaction-based scoring */
+    interactions: zod_1.z.number().min(0).max(1).default(0.3),
+    /** Weight for consistency metrics */
+    consistency: zod_1.z.number().min(0).max(1).default(0.3),
+})
+    .refine((weights) => {
+    const sum = weights.reviews + weights.interactions + weights.consistency;
+    return Math.abs(sum - 1.0) < 0.001; // Allow small floating point variance
+}, {
+    message: "Weights must sum to 1.0",
+});
+/**
+ * Calculator Config Schema
+ *
+ * Configuration options for the reputation calculator.
+ */
+exports.CalculatorConfigSchema = zod_1.z.object({
+    /** K value for confidence calculation: confidence = n / (n + k) */
+    kValue: zod_1.z.number().positive().default(15),
+    /** Optional preset (overrides other settings) */
+    preset: exports.CalculatorPresetSchema.optional(),
+    /** Component weights */
+    weights: exports.CalculatorWeightsSchema.optional(),
+    /** Base prior score (default: 50) */
+    basePriorScore: zod_1.z.number().min(0).max(100).default(50),
+    /** Maximum prior score (default: 80) */
+    maxPriorScore: zod_1.z.number().min(0).max(100).default(80),
+});
+// ============================================================================
+// SCORE PREDICTION
+// ============================================================================
+/**
+ * Score Change Prediction Schema
+ *
+ * Input for predicting how a score would change given hypothetical changes.
+ */
+exports.ScoreChangePredictionRequestSchema = zod_1.z.object({
+    /** Current agent data */
+    current: exports.AgentDataSchema,
+    /** Hypothetical changes to apply */
+    changes: zod_1.z.object({
+        /** Additional reviews to add */
+        additionalReviews: zod_1.z.number().int().nonnegative().optional(),
+        /** New average rating after changes */
+        newAverageRating: zod_1.z.number().min(1).max(5).optional(),
+        /** Additional interactions */
+        additionalInteractions: zod_1.z.number().int().nonnegative().optional(),
+        /** Additional successful interactions */
+        additionalSuccessfulInteractions: zod_1.z.number().int().nonnegative().optional(),
+    }),
+    /** Optional calculator configuration */
+    config: exports.CalculatorConfigSchema.optional(),
+});
+/**
+ * Score Change Prediction Response Schema
+ */
+exports.ScoreChangePredictionResponseSchema = zod_1.z.object({
+    /** Current score */
+    currentScore: exports.ReputationScoreSchema,
+    /** Predicted score after changes */
+    predictedScore: exports.ReputationScoreSchema,
+    /** Score difference */
+    scoreDelta: zod_1.z.number(),
+    /** Confidence difference */
+    confidenceDelta: zod_1.z.number(),
+});
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * Validate agent data
+ *
+ * @param data - The data to validate
+ * @returns Validation result
+ */
+function validateAgentData(data) {
+    return exports.AgentDataSchema.safeParse(data);
+}
+/**
+ * Validate reputation score
+ *
+ * @param score - The score to validate
+ * @returns Validation result
+ */
+function validateReputationScore(score) {
+    return exports.ReputationScoreSchema.safeParse(score);
+}
+/**
+ * Validate calculator config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+function validateCalculatorConfig(config) {
+    return exports.CalculatorConfigSchema.safeParse(config);
+}
+// ============================================================================
+// SCORE LEVEL HELPERS
+// ============================================================================
+/**
+ * Get reputation level from score
+ *
+ * @param score - Numeric score (0-100)
+ * @returns Reputation level
+ */
+function getReputationLevel(score) {
+    if (score < 0 || !Number.isFinite(score))
+        return "Unknown";
+    if (score < 30)
+        return "Poor";
+    if (score < 45)
+        return "BelowAverage";
+    if (score < 60)
+        return "Average";
+    if (score < 75)
+        return "Good";
+    if (score < 90)
+        return "Excellent";
+    return "Outstanding";
+}
+/**
+ * Get confidence level from confidence value
+ *
+ * @param confidence - Numeric confidence (0-1)
+ * @returns Confidence level
+ */
+function getConfidenceLevel(confidence) {
+    if (confidence < 0.25)
+        return "Low";
+    if (confidence < 0.5)
+        return "Medium";
+    if (confidence < 0.75)
+        return "High";
+    return "VeryHigh";
+}
+/**
+ * Calculate confidence from interaction count using the k formula
+ *
+ * confidence = n / (n + k)
+ *
+ * @param interactionCount - Number of interactions
+ * @param kValue - K value (default: 15)
+ * @returns Confidence value (0-1)
+ */
+function calculateConfidence(interactionCount, kValue = 15) {
+    if (interactionCount < 0 || kValue <= 0)
+        return 0;
+    return interactionCount / (interactionCount + kValue);
+}
+/**
+ * Check if agent data indicates a provisional score
+ * (insufficient data for high confidence)
+ *
+ * @param data - Agent data
+ * @returns true if score should be marked provisional
+ */
+function isProvisionalScore(data) {
+    const interactions = data.interactions?.totalInteractions ?? 0;
+    const reviews = data.reviews?.totalReviews ?? 0;
+    // Provisional if less than 5 interactions AND less than 3 reviews
+    return interactions < 5 && reviews < 3;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kya-os/contracts",
-  "version": "1.6.17",
+  "version": "1.6.19",
   "description": "Shared contracts, types, and schemas for MCP-I framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,6 +72,14 @@
     "./identity": {
       "types": "./dist/identity/index.d.ts",
       "default": "./dist/identity/index.js"
+    },
+    "./deploy": {
+      "types": "./dist/deploy/index.d.ts",
+      "default": "./dist/deploy/index.js"
+    },
+    "./reputation": {
+      "types": "./dist/reputation/index.d.ts",
+      "default": "./dist/reputation/index.js"
     }
   },
   "scripts": {