@lsctech/polaris 0.5.4 → 0.5.6

package/dist/autoresearch/sol-recommendations.js

@@ -0,0 +1,300 @@
+"use strict";
+/**
+ * SOL recommendation engine.
+ *
+ * Generates explainable routing recommendations and Polaris-specific
+ * self-improvement proposals from historical SOL score snapshots.
+ *
+ * Design rules:
+ *   - Output is advisory by default; no tracker or filesystem mutation happens
+ *     during recommendation generation.
+ *   - Filing tracker issues requires an explicit opt-in and is gated to the
+ *     Polaris development context (see src/cli/autoresearch.ts).
+ *   - Each recommendation carries evidence references, affected routing
+ *     dimensions, confidence, and a proposed policy action.
+ *   - Deterministic: same snapshot input produces the same recommendation set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRecommendations = generateRecommendations;
+exports.recommendationToProposal = recommendationToProposal;
+exports.recommendationsToProposals = recommendationsToProposals;
+exports.formatRecommendationsCli = formatRecommendationsCli;
+const sol_report_js_1 = require("./sol-report.js");
+// ──────────────────────────────────────────────
+// Constants and helpers
+// ──────────────────────────────────────────────
+const DEFAULT_THRESHOLD = 0.7;
+const DEFAULT_MIN_SAMPLES = 2;
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+function parseGroupKey(groupKey) {
+    const affected = {};
+    for (const part of groupKey.split("|")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq);
+        const value = part.slice(eq + 1);
+        if (!value || value === "unknown")
+            continue;
+        if (key === "route")
+            affected.route = value;
+        else if (key === "task_type")
+            affected.task_type = value;
+        else if (key === "role")
+            affected.role = value;
+        else if (key === "provider")
+            affected.provider = value;
+        else if (key === "model")
+            affected.model = value;
+    }
+    return affected;
+}
+function snapshotGroupKey(snapshot, dimension) {
+    const keys = snapshot.grouping_keys;
+    switch (dimension) {
+        case "repo":
+            return keys.repo ?? "unknown";
+        case "route":
+            return keys.route ?? "unknown";
+        case "task_type":
+            return keys.task_type ?? "unknown";
+        case "role":
+            return keys.role ?? "unknown";
+        case "risk":
+            return keys.risk ?? "unknown";
+        case "provider":
+            return keys.provider ?? "unknown";
+        case "model":
+            return keys.model ?? "unknown";
+        case "worker_id":
+            return snapshot.worker_ids.length > 0 ? snapshot.worker_ids.join(",") : "unknown";
+        case "run_id":
+            return snapshot.report.run_id;
+        case "time_window": {
+            const d = new Date(snapshot.report.scored_at);
+            if (isNaN(d.getTime()))
+                return "unknown";
+            // Default windowDays = 7 to match generateReport default.
+            const WINDOW_DAYS = 7;
+            const daysSinceEpoch = Math.floor(d.getTime() / (86400000 * WINDOW_DAYS));
+            const bucketStart = new Date(daysSinceEpoch * 86400000 * WINDOW_DAYS);
+            return bucketStart.toISOString().slice(0, 10);
+        }
+    }
+}
+function groupValueFromLabel(label, dimension) {
+    for (const part of label.split("|")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = part.slice(0, eq);
+        const value = part.slice(eq + 1);
+        if (key === dimension)
+            return value ?? "unknown";
+    }
+    return "unknown";
+}
+function isWorkerSignal(evidence) {
+    const workerMean = evidence.mean_worker_composite ?? null;
+    const foremanMean = evidence.mean_foreman_composite ?? null;
+    if (workerMean === null || foremanMean === null)
+        return true; // default to worker-facing
+    return workerMean <= foremanMean;
+}
+function buildProposedAction(dimension, affected, evidence) {
+    const target = affected.provider ?? affected.model ?? affected.role ?? affected.route ?? affected.task_type ?? dimension;
+    const workerFocus = isWorkerSignal(evidence);
+    switch (dimension) {
+        case "provider":
+            return `Review provider eligibility and role assignment for provider '${target}'; consider updating execution.providerPolicy or provider trust/cost thresholds.`;
+        case "model":
+            return `Review model selection for model '${target}'; update role model mapping if the trend persists.`;
+        case "role":
+            return `Review role assignment for role '${target}'; verify provider capabilities, packet scope, and routing policy.`;
+        case "route":
+            return workerFocus
+                ? `Analyze route health for '${target}'; inspect worker templates and validation commands.`
+                : `Analyze route health for '${target}'; inspect scoring rules and foreman/runtime configuration.`;
+        case "task_type":
+            return `Review task-type routing for '${target}'; verify provider capabilities and role mapping.`;
+        case "risk":
+            return `Review trust/cost thresholds for risk tier '${target}'; adjust policy filters if this tier is consistently underperforming.`;
+        case "worker_id":
+            return `Review worker behavior for '${target}'; consider tightening packet scope or validation commands.`;
+        default:
+            return `Investigate ${workerFocus ? "worker" : "runtime"} performance for '${target}' and update the relevant ${workerFocus ? "worker template/policy" : "runtime config/scoring rules"}.`;
+    }
+}
+function categoryFor(dimension) {
+    const map = {
+        provider: "provider_policy",
+        model: "provider_policy",
+        role: "role_assignment",
+        route: "routing",
+        task_type: "routing",
+        repo: "routing",
+        risk: "trust_threshold",
+    };
+    return map[dimension] ?? "runtime_improvement";
+}
+function actionTypeFor(evidence) {
+    return isWorkerSignal(evidence) ? "implement" : "analyze";
+}
+function artifactTypeFor(dimension, evidence) {
+    const workerFocus = isWorkerSignal(evidence);
+    switch (dimension) {
+        case "provider":
+        case "model":
+            return "provider-role-recommendation";
+        case "route":
+            return workerFocus ? "worker-template" : "scoring-rule";
+        case "task_type":
+        case "role":
+        case "risk":
+            return workerFocus ? "worker-template" : "runtime-config";
+        case "repo":
+        case "worker_id":
+        case "run_id":
+        case "time_window":
+        default:
+            return workerFocus ? "worker-template" : "runtime-config";
+    }
+}
+function confidenceFor(mean, threshold, count) {
+    const gap = Math.max(0, threshold - mean);
+    const sampleBoost = Math.min(count / 10, 0.2);
+    return clamp01(gap + sampleBoost);
+}
+// ──────────────────────────────────────────────
+// Recommendation generation
+// ──────────────────────────────────────────────
+/**
+ * Scan historical SOL snapshots for underperforming groups and emit
+ * review-gated recommendations.
+ *
+ * The function is pure: it does not read files, call APIs, or mutate inputs.
+ */
+function generateRecommendations(snapshots, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+    const minSamples = options.minSamples ?? DEFAULT_MIN_SAMPLES;
+    const dimensions = options.groupBy ?? ["provider", "model", "role", "route", "task_type"];
+    const recommendations = [];
+    for (const dim of dimensions) {
+        const report = (0, sol_report_js_1.generateReport)(snapshots, { groupBy: [dim] });
+        for (const group of report.groups) {
+            const mean = group.mean_composite;
+            if (mean === null || mean >= threshold || group.count < minSamples)
+                continue;
+            const affected = parseGroupKey(group.group_key);
+            const evidence = {
+                group_key: group.group_key,
+                grouped_by: [dim],
+                count: group.count,
+                mean_composite: group.mean_composite,
+                min_composite: group.min_composite,
+                max_composite: group.max_composite,
+                mean_foreman_composite: group.mean_foreman_composite,
+                mean_worker_composite: group.mean_worker_composite,
+                run_ids: [
+                    ...new Set(snapshots
+                        .filter((s) => snapshotGroupKey(s, dim) === groupValueFromLabel(group.group_key, dim))
+                        .map((s) => s.report.run_id)),
+                ].sort(),
+            };
+            recommendations.push({
+                id: `${dim}:${group.group_key}`,
+                category: categoryFor(dim),
+                action_type: actionTypeFor(evidence),
+                affected,
+                proposed_action: buildProposedAction(dim, affected, evidence),
+                confidence: confidenceFor(mean, threshold, group.count),
+                evidence,
+                rationale: `Mean composite score ${mean.toFixed(4)} is below threshold ${threshold.toFixed(2)} across ${group.count} snapshots.`,
+            });
+        }
+    }
+    // Deterministic ordering: highest confidence first, then stable id sort.
+    recommendations.sort((a, b) => b.confidence - a.confidence || a.id.localeCompare(b.id));
+    return {
+        generated_at: new Date().toISOString(),
+        total_snapshots: snapshots.length,
+        threshold,
+        min_samples: minSamples,
+        recommendations,
+    };
+}
+// ──────────────────────────────────────────────
+// Proposal conversion (tracker filing)
+// ──────────────────────────────────────────────
+/**
+ * Convert a single recommendation into an AutresearchProposal suitable for
+ * `routeProposals()`. This is the bridge from advisory SOL output to
+ * review-gated tracker issues.
+ */
+function recommendationToProposal(recommendation, runId) {
+    const { evidence, affected, proposed_action, confidence, id, action_type, rationale } = recommendation;
+    const dim = evidence.grouped_by[0] ?? "run_id";
+    const artifactType = artifactTypeFor(dim, evidence);
+    const affectedLabel = affected.provider ?? affected.model ?? affected.role ?? affected.route ?? affected.task_type ?? dim;
+    const gateId = `sol-recommendation:${id}`;
+    return {
+        gate_id: gateId,
+        artifact_type: artifactType,
+        hint: `[${action_type}] ${proposed_action}\n\nRationale: ${rationale}\nEvidence: group=${evidence.group_key}, mean=${evidence.mean_composite?.toFixed(4) ?? "N/A"}, count=${evidence.count}, run_ids=${evidence.run_ids.join(",")}`,
+        run_id: runId ?? evidence.run_ids[0] ?? "sol-history",
+        evidence_run_ids: evidence.run_ids,
+        confidence,
+        fix_zone: `${artifactType}/${gateId}`,
+    };
+}
+/**
+ * Convert recommendations to tracker proposals.
+ */
+function recommendationsToProposals(recommendations, runId) {
+    return recommendations.map((r) => recommendationToProposal(r, runId));
+}
+// ──────────────────────────────────────────────
+// Human-readable formatter
+// ──────────────────────────────────────────────
+function fmtScore(v) {
+    return v !== null ? v.toFixed(4) : "N/A";
+}
+function fmtAffected(affected) {
+    const parts = [];
+    if (affected.provider)
+        parts.push(`provider=${affected.provider}`);
+    if (affected.model)
+        parts.push(`model=${affected.model}`);
+    if (affected.role)
+        parts.push(`role=${affected.role}`);
+    if (affected.route)
+        parts.push(`route=${affected.route}`);
+    if (affected.task_type)
+        parts.push(`task_type=${affected.task_type}`);
+    return parts.length > 0 ? parts.join(", ") : "global";
+}
+function formatRecommendationsCli(report) {
+    const lines = [];
+    lines.push("SOL Routing Recommendations");
+    lines.push(`Generated: ${report.generated_at}`);
+    lines.push(`Total snapshots: ${report.total_snapshots}`);
+    lines.push(`Threshold: ${report.threshold.toFixed(2)}, min samples: ${report.min_samples}`);
+    lines.push("");
+    if (report.recommendations.length === 0) {
+        lines.push("No underperforming groups detected.");
+        return lines.join("\n") + "\n";
+    }
+    for (const r of report.recommendations) {
+        lines.push(`[${r.action_type}] ${r.id}`);
+        lines.push(`  Category:    ${r.category}`);
+        lines.push(`  Affected:    ${fmtAffected(r.affected)}`);
+        lines.push(`  Confidence:  ${(r.confidence * 100).toFixed(1)}%`);
+        lines.push(`  Evidence:    ${r.evidence.group_key} | mean=${fmtScore(r.evidence.mean_composite)} min=${fmtScore(r.evidence.min_composite)} max=${fmtScore(r.evidence.max_composite)} count=${r.evidence.count}`);
+        lines.push(`  Action:      ${r.proposed_action}`);
+        lines.push(`  Rationale:   ${r.rationale}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/autoresearch/sol-report.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * SOL report generator.
+ *
+ * Groups historical SOL score snapshots by configurable dimensions and
+ * produces summary reports in JSON or human-readable CLI format.
+ *
+ * Grouping dimensions: repo, route, task_type, role, risk, provider,
+ * model, worker_id, run_id, and time window.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateReport = generateReport;
+exports.formatReportCli = formatReportCli;
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function getGroupKey(snapshot, dimension, windowDays) {
+    const keys = snapshot.grouping_keys;
+    switch (dimension) {
+        case "repo": return keys.repo ?? "unknown";
+        case "route": return keys.route ?? "unknown";
+        case "task_type": return keys.task_type ?? "unknown";
+        case "role": return keys.role ?? "unknown";
+        case "risk": return keys.risk ?? "unknown";
+        case "provider": return keys.provider ?? "unknown";
+        case "model": return keys.model ?? "unknown";
+        case "worker_id":
+            return snapshot.worker_ids.length > 0 ? snapshot.worker_ids.join(",") : "unknown";
+        case "run_id": return snapshot.report.run_id;
+        case "time_window": {
+            const d = new Date(snapshot.report.scored_at);
+            if (isNaN(d.getTime()))
+                return "unknown";
+            // Bucket by windowDays from epoch
+            const daysSinceEpoch = Math.floor(d.getTime() / (86400000 * windowDays));
+            const bucketStart = new Date(daysSinceEpoch * 86400000 * windowDays);
+            return bucketStart.toISOString().slice(0, 10);
+        }
+    }
+}
+function compositeGroupKey(snapshot, dimensions, windowDays) {
+    return dimensions.map((d) => `${d}=${getGroupKey(snapshot, d, windowDays)}`).join("|");
+}
+function meanOrNull(nums) {
+    const valid = nums.filter((n) => n !== null);
+    if (valid.length === 0)
+        return null;
+    return Number((valid.reduce((a, b) => a + b, 0) / valid.length).toFixed(4));
+}
+function minOrNull(nums) {
+    const valid = nums.filter((n) => n !== null);
+    return valid.length > 0 ? Math.min(...valid) : null;
+}
+function maxOrNull(nums) {
+    const valid = nums.filter((n) => n !== null);
+    return valid.length > 0 ? Math.max(...valid) : null;
+}
+// ──────────────────────────────────────────────
+// Report generation
+// ──────────────────────────────────────────────
+function generateReport(snapshots, options = {}) {
+    const groupBy = options.groupBy ?? ["run_id"];
+    const windowDays = options.windowDays ?? 7;
+    // Group snapshots
+    const groups = new Map();
+    for (const s of snapshots) {
+        const key = compositeGroupKey(s, groupBy, windowDays);
+        const arr = groups.get(key);
+        if (arr)
+            arr.push(s);
+        else
+            groups.set(key, [s]);
+    }
+    // Build summaries
+    const summaries = [];
+    for (const [key, snaps] of groups) {
+        const composites = snaps.map((s) => s.report.run_composite_score);
+        const foremanComposites = snaps.map((s) => s.report.foreman.composite_score);
+        // Flatten all worker composites across snapshots
+        const workerComposites = [];
+        for (const s of snaps) {
+            for (const w of Object.values(s.report.workers)) {
+                workerComposites.push(w.composite_score);
+            }
+        }
+        const scoredAts = snaps
+            .map((s) => s.report.scored_at)
+            .filter((t) => t)
+            .sort();
+        summaries.push({
+            group_key: key,
+            count: snaps.length,
+            mean_composite: meanOrNull(composites),
+            min_composite: minOrNull(composites),
+            max_composite: maxOrNull(composites),
+            mean_foreman_composite: meanOrNull(foremanComposites),
+            mean_worker_composite: meanOrNull(workerComposites),
+            earliest: scoredAts[0] ?? null,
+            latest: scoredAts[scoredAts.length - 1] ?? null,
+        });
+    }
+    // Sort groups by key for deterministic output
+    summaries.sort((a, b) => a.group_key.localeCompare(b.group_key));
+    const allComposites = snapshots.map((s) => s.report.run_composite_score);
+    return {
+        total_snapshots: snapshots.length,
+        grouped_by: groupBy,
+        groups: summaries,
+        overall_mean_composite: meanOrNull(allComposites),
+        generated_at: new Date().toISOString(),
+    };
+}
+// ──────────────────────────────────────────────
+// Human-readable formatter
+// ──────────────────────────────────────────────
+function fmtScore(v) {
+    return v !== null ? v.toFixed(4) : "N/A";
+}
+function formatReportCli(report) {
+    const lines = [];
+    lines.push(`SOL History Report`);
+    lines.push(`Generated: ${report.generated_at}`);
+    lines.push(`Total snapshots: ${report.total_snapshots}`);
+    lines.push(`Grouped by: ${report.grouped_by.join(", ")}`);
+    lines.push(`Overall mean composite: ${fmtScore(report.overall_mean_composite)}`);
+    lines.push("");
+    if (report.groups.length === 0) {
+        lines.push("No data.");
+        return lines.join("\n");
+    }
+    // Table header
+    lines.push(padRight("Group", 40) +
+        padRight("Count", 7) +
+        padRight("Mean", 8) +
+        padRight("Min", 8) +
+        padRight("Max", 8) +
+        padRight("Foreman", 9) +
+        "Worker");
+    lines.push("-".repeat(88));
+    for (const g of report.groups) {
+        lines.push(padRight(g.group_key.slice(0, 39), 40) +
+            padRight(String(g.count), 7) +
+            padRight(fmtScore(g.mean_composite), 8) +
+            padRight(fmtScore(g.min_composite), 8) +
+            padRight(fmtScore(g.max_composite), 8) +
+            padRight(fmtScore(g.mean_foreman_composite), 9) +
+            fmtScore(g.mean_worker_composite));
+    }
+    return lines.join("\n") + "\n";
+}
+function padRight(s, n) {
+    return s.length >= n ? s : s + " ".repeat(n - s.length);
+}