freshcontext-mcp 0.3.16 → 0.3.18

package/dist/core/pipeline.js

@@ -0,0 +1,101 @@
+import { LAMBDA, calculateFreshnessScore } from "./decay.js";
+import { formatForLLM, toStructuredJSON } from "./envelope.js";
+import { calculateHaPriV2 } from "./provenance.js";
+import { rankSignal } from "./rank.js";
+import { normalizeSignal } from "./signal.js";
+import { calculateContextUtility } from "./utility.js";
+function ageHours(signal) {
+    if (!signal.published_at)
+        return 0;
+    const published = new Date(signal.published_at).getTime();
+    const retrieved = new Date(signal.retrieved_at).getTime();
+    if (isNaN(published) || isNaN(retrieved))
+        return 0;
+    return Math.max(0, (retrieved - published) / (1000 * 60 * 60));
+}
+function envelopeConfidence(signal) {
+    if (signal.status === "failed" || signal.date_confidence === "unknown")
+        return "low";
+    return signal.date_confidence;
+}
+function createEnvelope(signal, freshnessScore, options) {
+    if (!options.includeEnvelope || signal.content === undefined)
+        return undefined;
+    const ctx = {
+        content: signal.content.slice(0, options.envelopeMaxLength ?? 8000),
+        source_url: signal.source,
+        content_date: signal.published_at,
+        retrieved_at: signal.retrieved_at,
+        freshness_confidence: envelopeConfidence(signal),
+        freshness_score: freshnessScore,
+        adapter: signal.source_type,
+    };
+    return {
+        context: ctx,
+        text: formatForLLM(ctx, options.envelopeFormat),
+        structured: toStructuredJSON(ctx),
+    };
+}
+function createProvenance(signal, options, reasons) {
+    if (!options.includeProvenance)
+        return undefined;
+    const resultId = options.provenance?.resultId ?? signal.id;
+    const engineVersion = options.provenance?.engineVersion;
+    if (!signal.content) {
+        reasons.push("provenance was requested but content was missing");
+        return undefined;
+    }
+    if (!resultId) {
+        reasons.push("provenance was requested but resultId was missing");
+        return undefined;
+    }
+    if (!engineVersion) {
+        reasons.push("provenance was requested but engineVersion was missing");
+        return undefined;
+    }
+    return calculateHaPriV2({
+        resultId,
+        rawContent: signal.content,
+        semanticFingerprint: options.provenance?.semanticFingerprint ?? null,
+        adapter: signal.source_type,
+        publishedAt: signal.published_at,
+        retrievedAt: signal.retrieved_at,
+        engineVersion,
+    });
+}
+export function evaluateSignal(input, options = {}) {
+    const signal = normalizeSignal(input, options);
+    const freshness_score = signal.status === "failed" || signal.date_confidence === "unknown"
+        ? null
+        : calculateFreshnessScore(signal.published_at, signal.retrieved_at, signal.source_type);
+    const utility = calculateContextUtility({
+        contextualRelevance: signal.semantic_score * 100,
+        lambda: LAMBDA[signal.source_type] ?? LAMBDA.default,
+        ageHours: ageHours(signal),
+        dateConfidence: signal.date_confidence,
+        status: signal.status,
+    });
+    const ranked = rankSignal(signal, options);
+    const reasons = [...signal.reasons, ...utility.reasons];
+    const envelope = createEnvelope(signal, freshness_score, options);
+    const provenance = createProvenance(signal, options, reasons);
+    return {
+        signal,
+        freshness_score,
+        utility,
+        ranked,
+        explanation: ranked.reason,
+        envelope,
+        provenance,
+        reasons,
+    };
+}
+export function evaluateSignals(inputs, options = {}) {
+    return inputs
+        .map((input, index) => ({ evaluation: evaluateSignal(input, options), index }))
+        .sort((a, b) => {
+        const scoreDiff = b.evaluation.ranked.final_score - a.evaluation.ranked.final_score;
+        return scoreDiff !== 0 ? scoreDiff : a.index - b.index;
+    })
+        .map(({ evaluation }) => evaluation);
+}

package/dist/core/provenance.js

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+const HA_PRI_V2_VERSION = "FRESHCONTEXT_HA_PRI_V2";
+const NULL_SENTINEL = "null";
+function fieldValue(value) {
+    return value ?? NULL_SENTINEL;
+}
+export function canonicalizeHaPriContent(input) {
+    return input
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+}
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+export function calculateHaPriV2(input) {
+    const canonicalContentSha256 = sha256Hex(canonicalizeHaPriContent(input.rawContent));
+    const semanticFingerprintSha256 = sha256Hex(fieldValue(input.semanticFingerprint));
+    const resultId = fieldValue(input.resultId);
+    const adapter = fieldValue(input.adapter);
+    const publishedAt = fieldValue(input.publishedAt);
+    const retrievedAt = fieldValue(input.retrievedAt);
+    const engineVersion = fieldValue(input.engineVersion);
+    const signingPayload = [
+        HA_PRI_V2_VERSION,
+        `result_id=${resultId}`,
+        `canonical_content_sha256=${canonicalContentSha256}`,
+        `semantic_fingerprint_sha256=${semanticFingerprintSha256}`,
+        `adapter=${adapter}`,
+        `published_at=${publishedAt}`,
+        `retrieved_at=${retrievedAt}`,
+        `engine_version=${engineVersion}`,
+    ].join("\n");
+    return {
+        version: HA_PRI_V2_VERSION,
+        resultId,
+        canonicalContentSha256,
+        semanticFingerprintSha256,
+        adapter,
+        publishedAt,
+        retrievedAt,
+        engineVersion,
+        signingPayload,
+        haPriSigV2: sha256Hex(signingPayload),
+    };
+}
+export function verifyHaPriV2(input, actualSig) {
+    if (actualSig === null || actualSig === undefined || actualSig.trim() === "") {
+        return {
+            status: "unknown",
+            expected: null,
+            actual: actualSig ?? null,
+            reasons: ["missing ha_pri_sig_v2; verification status unknown"],
+        };
+    }
+    const expected = calculateHaPriV2(input).haPriSigV2;
+    if (actualSig === expected) {
+        return {
+            status: "valid",
+            expected,
+            actual: actualSig,
+            reasons: [],
+        };
+    }
+    return {
+        status: "invalid",
+        expected,
+        actual: actualSig,
+        reasons: ["stored ha_pri_sig_v2 did not match recomputed signature"],
+    };
+}

package/dist/core/rank.js

@@ -0,0 +1,84 @@
+import { calculateFreshnessScore } from "./decay.js";
+import { explainSignal } from "./explain.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+const DEFAULT_SEMANTIC_WEIGHT = 0.7;
+const DEFAULT_FRESHNESS_WEIGHT = 0.3;
+export function clampScore(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(1, Math.max(0, value));
+}
+function positiveNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+function resolveWeights(options) {
+    let semantic = positiveNumber(options.semanticWeight);
+    let freshness = positiveNumber(options.freshnessWeight);
+    if (semantic === 0 && freshness === 0) {
+        semantic = DEFAULT_SEMANTIC_WEIGHT;
+        freshness = DEFAULT_FRESHNESS_WEIGHT;
+    }
+    const total = semantic + freshness;
+    return {
+        semantic: semantic / total,
+        freshness: freshness / total,
+    };
+}
+function resolveRetrievedAt(signal, options) {
+    if (signal.retrieved_at)
+        return signal.retrieved_at;
+    if (options.now instanceof Date)
+        return options.now.toISOString();
+    if (typeof options.now === "string")
+        return options.now;
+    return new Date().toISOString();
+}
+function resolveSourceType(signal, options) {
+    return signal.source_type ?? options.defaultSourceType ?? signal.source ?? "default";
+}
+function isFailedSignal(signal) {
+    return signal.status === "failed"
+        || (signal.content !== undefined && looksLikeFailedAdapterContent(signal.content));
+}
+function confidenceFor(signal, semanticScore, freshnessScore) {
+    if (isFailedSignal(signal)) {
+        return "low";
+    }
+    if (freshnessScore !== null && semanticScore >= 0.7) {
+        return "high";
+    }
+    if (freshnessScore !== null || semanticScore >= 0.5) {
+        return "medium";
+    }
+    return "low";
+}
+export function rankSignal(signal, options = {}) {
+    const weights = resolveWeights(options);
+    const semantic_score = clampScore(signal.semantic_score);
+    const freshness_score = isFailedSignal(signal) || signal.date_confidence === "unknown"
+        ? null
+        : calculateFreshnessScore(signal.published_at ?? signal.content_date ?? null, resolveRetrievedAt(signal, options), resolveSourceType(signal, options));
+    const freshnessComponent = freshness_score === null ? 0 : clampScore(freshness_score / 100);
+    const final_score = clampScore(semantic_score * weights.semantic + freshnessComponent * weights.freshness);
+    const confidence = confidenceFor(signal, semantic_score, freshness_score);
+    const ranked = {
+        ...signal,
+        semantic_score,
+        freshness_score,
+        final_score,
+        confidence,
+    };
+    return {
+        ...ranked,
+        reason: explainSignal(ranked),
+    };
+}
+export function rankSignals(signals, options = {}) {
+    return signals
+        .map((signal, index) => ({ ranked: rankSignal(signal, options), index }))
+        .sort((a, b) => {
+        const scoreDiff = b.ranked.final_score - a.ranked.final_score;
+        return scoreDiff !== 0 ? scoreDiff : a.index - b.index;
+    })
+        .map(({ ranked }) => ranked);
+}

package/dist/core/signal.js

@@ -0,0 +1,101 @@
+import { isMeaningfullyFutureDate } from "./decay.js";
+import { looksLikeFailedAdapterContent } from "./guards.js";
+export const SIGNAL_CONTRACT_VERSION = "freshcontext.signal.v1";
+const DATE_CONFIDENCE_VALUES = new Set(["high", "medium", "low", "unknown"]);
+const STATUS_VALUES = new Set(["success", "partial", "stale", "failed", "unknown"]);
+function isSignalDateConfidence(value) {
+    return typeof value === "string" && DATE_CONFIDENCE_VALUES.has(value);
+}
+function isContextUtilityStatus(value) {
+    return typeof value === "string" && STATUS_VALUES.has(value);
+}
+function normalizeDate(value) {
+    if (!value)
+        return null;
+    const timestamp = new Date(value).getTime();
+    if (isNaN(timestamp))
+        return null;
+    return new Date(timestamp).toISOString();
+}
+function resolveRetrievedAt(input, options, reasons) {
+    const retrievedAt = normalizeDate(input.retrieved_at);
+    if (retrievedAt)
+        return retrievedAt;
+    if (input.retrieved_at) {
+        reasons.push("retrieved_at was invalid; used normalization time");
+    }
+    const optionNow = options.now instanceof Date
+        ? (isNaN(options.now.getTime()) ? null : options.now.toISOString())
+        : normalizeDate(options.now);
+    return optionNow ?? new Date().toISOString();
+}
+function normalizeSemanticScore(value, reasons) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        reasons.push("semantic_score was missing or invalid; clamped to 0");
+        return 0;
+    }
+    if (value < 0) {
+        reasons.push("semantic_score was below 0; clamped to 0");
+        return 0;
+    }
+    if (value > 1) {
+        reasons.push("semantic_score exceeded 1; clamped to 1");
+        return 1;
+    }
+    return value;
+}
+function resolveDateConfidence(input, hasTrustedDate) {
+    if (!hasTrustedDate)
+        return "unknown";
+    if (isSignalDateConfidence(input.date_confidence))
+        return input.date_confidence;
+    if (input.freshness_confidence)
+        return input.freshness_confidence;
+    return "medium";
+}
+function resolveStatus(input, failedContent) {
+    if (failedContent)
+        return "failed";
+    if (isContextUtilityStatus(input.status))
+        return input.status;
+    return "success";
+}
+export function normalizeSignal(input, options = {}) {
+    const reasons = [];
+    const retrieved_at = resolveRetrievedAt(input, options, reasons);
+    const rawPublishedAt = input.published_at ?? input.content_date ?? null;
+    let published_at = normalizeDate(rawPublishedAt);
+    if (!input.published_at && input.content_date) {
+        reasons.push("content_date alias was normalized to published_at");
+    }
+    if (rawPublishedAt && !published_at) {
+        reasons.push("published_at/content_date was invalid; cleared");
+    }
+    if (published_at && isMeaningfullyFutureDate(published_at, retrieved_at)) {
+        published_at = null;
+        reasons.push("published_at/content_date was meaningfully future-dated; cleared");
+    }
+    const failedContent = input.content !== undefined && looksLikeFailedAdapterContent(input.content);
+    if (failedContent) {
+        reasons.push("content looked like failed adapter output; status set to failed");
+    }
+    const source_type = input.source_type ?? options.defaultSourceType ?? "default";
+    if (!input.source_type && !options.defaultSourceType) {
+        reasons.push("source_type was missing; defaulted to default");
+    }
+    return {
+        contract_version: SIGNAL_CONTRACT_VERSION,
+        id: input.id,
+        source: input.source,
+        source_type,
+        title: input.title,
+        content: input.content,
+        published_at,
+        retrieved_at,
+        semantic_score: normalizeSemanticScore(input.semantic_score, reasons),
+        date_confidence: resolveDateConfidence(input, published_at !== null),
+        status: resolveStatus(input, failedContent),
+        metadata: input.metadata ? { ...input.metadata } : {},
+        reasons,
+    };
+}

package/dist/core/sourceProfiles.js

@@ -0,0 +1,126 @@
+import { LAMBDA } from "./decay.js";
+function halfLifeHours(lambda) {
+    return Number((Math.log(2) / lambda).toFixed(2));
+}
+function profile(input) {
+    return {
+        ...input,
+        half_life_hours: halfLifeHours(input.default_decay_lambda),
+    };
+}
+function copyProfile(profile) {
+    return {
+        ...profile,
+        source_types: [...profile.source_types],
+        recommended_surfaces: [...profile.recommended_surfaces],
+    };
+}
+export const BUILT_IN_SOURCE_PROFILES = Object.freeze({
+    official_docs: profile({
+        profile_id: "official_docs",
+        source_types: ["official_docs", "changelog", "packagetrends"],
+        purpose: "Official product docs, API docs, standards, changelogs, and canonical source material.",
+        default_decay_lambda: LAMBDA.github,
+        authority_hint: "high",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["rest", "sdk", "cli", "operator"],
+    }),
+    code_activity: profile({
+        profile_id: "code_activity",
+        source_types: ["github", "reposearch", "changelog", "packagetrends"],
+        purpose: "Repository activity, release cadence, dependency health, and implementation evidence.",
+        default_decay_lambda: LAMBDA.github,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    social_pulse: profile({
+        profile_id: "social_pulse",
+        source_types: ["hackernews", "reddit", "producthunt"],
+        purpose: "Community awareness, social proof, launch momentum, and early-market signal.",
+        default_decay_lambda: LAMBDA.hackernews,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    academic_research: profile({
+        profile_id: "academic_research",
+        source_types: ["google_scholar", "arxiv"],
+        purpose: "Scholarly material, papers, research abstracts, and citation-oriented context.",
+        default_decay_lambda: LAMBDA.arxiv,
+        authority_hint: "high",
+        date_policy: "lenient",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    market_finance: profile({
+        profile_id: "market_finance",
+        source_types: ["finance", "finance_landscape"],
+        purpose: "Market prices, quotes, financial movement, and finance-specific situational awareness.",
+        default_decay_lambda: LAMBDA.finance,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "exclude",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    jobs_opportunities: profile({
+        profile_id: "jobs_opportunities",
+        source_types: ["jobs"],
+        purpose: "Job listings, openings, hiring signals, and opportunity windows.",
+        default_decay_lambda: LAMBDA.jobs,
+        authority_hint: "medium",
+        date_policy: "strict",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "cli", "operator"],
+    }),
+    government_regulatory: profile({
+        profile_id: "government_regulatory",
+        source_types: ["govcontracts", "sec_filings", "gebiz", "gdelt", "gov_landscape"],
+        purpose: "Public-sector contracts, official filings, tenders, regulatory disclosures, and global news intelligence.",
+        default_decay_lambda: LAMBDA.govcontracts,
+        authority_hint: "high",
+        date_policy: "strict",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    company_intel: profile({
+        profile_id: "company_intel",
+        source_types: ["yc", "company_landscape"],
+        purpose: "Company research, product velocity, ecosystem activity, and competitive context.",
+        default_decay_lambda: LAMBDA.company_landscape,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "downgrade",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    composite_landscape: profile({
+        profile_id: "composite_landscape",
+        source_types: ["landscape", "idea_landscape", "gov_landscape", "finance_landscape", "company_landscape"],
+        purpose: "Multi-source validation and idea, company, market, government, or finance landscape checks.",
+        default_decay_lambda: LAMBDA.landscape,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["mcp", "rest", "sdk", "operator"],
+    }),
+    local_custom: profile({
+        profile_id: "local_custom",
+        source_types: ["local_custom", "user_provided", "custom"],
+        purpose: "User-provided content and custom signals supplied explicitly by a host or caller.",
+        default_decay_lambda: LAMBDA.default,
+        authority_hint: "medium",
+        date_policy: "balanced",
+        failure_policy: "warn",
+        recommended_surfaces: ["rest", "sdk", "cli", "operator"],
+    }),
+});
+export function listSourceProfiles() {
+    return Object.values(BUILT_IN_SOURCE_PROFILES).map(copyProfile);
+}
+export function getSourceProfile(profileId) {
+    const profile = BUILT_IN_SOURCE_PROFILES[profileId];
+    return profile ? copyProfile(profile) : undefined;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/utility.js

@@ -0,0 +1,90 @@
+const DATE_CONFIDENCE_FACTORS = {
+    high: 1.0,
+    medium: 0.75,
+    low: 0.4,
+    unknown: 0.0,
+};
+const STATUS_FACTORS = {
+    success: 1.0,
+    partial: 0.65,
+    stale: 0.4,
+    failed: 0.0,
+    unknown: 0.5,
+};
+function clampRelevance(value, reasons) {
+    if (!Number.isFinite(value)) {
+        reasons.push("contextual relevance was not finite; clamped to 0");
+        return 0;
+    }
+    if (value > 100) {
+        reasons.push("contextual relevance exceeded 100; clamped to 100");
+        return 100;
+    }
+    if (value < 0) {
+        reasons.push("contextual relevance was below 0; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+function safeLambda(value, reasons) {
+    if (!Number.isFinite(value) || value < 0) {
+        reasons.push("lambda was invalid; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+function safeAgeHours(value, reasons) {
+    if (!Number.isFinite(value)) {
+        reasons.push("ageHours was not finite; clamped to 0");
+        return 0;
+    }
+    if (value < 0) {
+        reasons.push("ageHours was negative; clamped to 0");
+        return 0;
+    }
+    return value;
+}
+export function calculateContextUtility(input) {
+    const reasons = [];
+    const contextualRelevance = clampRelevance(input.contextualRelevance, reasons);
+    const lambda = safeLambda(input.lambda, reasons);
+    const ageHours = safeAgeHours(input.ageHours, reasons);
+    const dateConfidence = input.dateConfidence ?? "unknown";
+    const status = input.status ?? "unknown";
+    const decayFactor = Math.exp(-lambda * ageHours);
+    const dateConfidenceFactor = DATE_CONFIDENCE_FACTORS[dateConfidence];
+    const statusFactor = STATUS_FACTORS[status];
+    if (dateConfidence === "medium") {
+        reasons.push("timestamp confidence is medium; utility reduced");
+    }
+    else if (dateConfidence === "low") {
+        reasons.push("timestamp confidence is low; utility reduced");
+    }
+    else if (dateConfidence === "unknown") {
+        reasons.push("timestamp confidence is unknown; utility reduced to zero");
+    }
+    if (status === "partial") {
+        reasons.push("signal status is partial; utility reduced");
+    }
+    else if (status === "stale") {
+        reasons.push("signal status is stale; utility reduced");
+    }
+    else if (status === "failed") {
+        reasons.push("signal status is failed; utility reduced to zero");
+    }
+    else if (status === "unknown") {
+        reasons.push("signal status is unknown; utility reduced");
+    }
+    const score = Math.min(100, Math.max(0, contextualRelevance * decayFactor * dateConfidenceFactor * statusFactor));
+    return {
+        score,
+        contextualRelevance,
+        decayFactor,
+        dateConfidenceFactor,
+        statusFactor,
+        lambda,
+        ageHours,
+        status,
+        reasons,
+    };
+}