@nexus-cortex/core 4.45.0 → 4.47.0

package/dist/training/TurnPredictionStore.d.ts

@@ -0,0 +1,58 @@
+/**
+ * How the ACTUAL next message relates to the displayed prediction (the TUI
+ * ghost-text prefill). Spec §5.1 tri-state — splits the exam stream from
+ * suggestion telemetry:
+ * - 'none'     — the prediction was never rendered to the user (late helper,
+ *                display-holdout, or a non-TUI surface). Cleanest exam grade.
+ * - 'shown'    — the ghost was rendered but the user typed independently.
+ *                Exam-eligible; the shown-vs-none score gap measures semantic
+ *                anchoring at the population level.
+ * - 'inserted' — the user Tab/→-accepted the ghost (edited or not). Excluded
+ *                from the graduation exam; match_score re-reads as suggestion
+ *                retention/usefulness (1.0 = accepted verbatim).
+ */
+export type PrefillProvenance = 'none' | 'shown' | 'inserted';
+export interface TurnPredictionRecord {
+    /** deterministic id: <sessionId>:<turnNumber> */
+    record_id: string;
+    session_id: string;
+    turn_number: number;
+    /** model that produced the prediction (helper today; the apprentice later). */
+    predictor_model: string;
+    /** the one-line turn summary generated alongside the prediction. */
+    summary: string | null;
+    predicted_next: string;
+    /** the user's ACTUAL next message (flattened to text). */
+    actual_next: string;
+    /** deterministic token-F1 in [0,1] — see predictionMatchScore. */
+    match_score: number;
+    predicted_at_ms: number;
+    scored_at_ms: number;
+    /** §5.1 provenance of actual_next relative to the displayed prediction. */
+    prefill_provenance: PrefillProvenance;
+}
+/** Pending prediction held between turns (in-memory on the orchestrator). */
+export interface PendingTurnPrediction {
+    sessionId: string;
+    turnNumber: number;
+    predictorModel: string;
+    summary: string | null;
+    prediction: string;
+    predictedAtMs: number;
+}
+/**
+ * Deterministic prediction↔actual similarity: token-level F1 (harmonic mean of
+ * precision and recall over unique tokens). 0 = no overlap, 1 = identical token
+ * sets. Chosen over embeddings/LLM-judge for reproducibility and zero cost — the
+ * spec upgrades the metric only if this under-separates.
+ */
+export declare function predictionMatchScore(predicted: string, actual: string): number;
+/** Flatten a user message (string or content-block array) to comparable text. */
+export declare function flattenUserContent(content: string | unknown[]): string;
+/**
+ * Score a pending prediction against the actual next user message and append
+ * the completed record. Truncates stored texts (the raw payload belongs in R2,
+ * not the hot store). Never throws — recording must not affect the turn.
+ */
+export declare function scoreAndRecordTurnPrediction(projectRoot: string, pending: PendingTurnPrediction, actualNext: string, nowMs: number, prefillProvenance?: PrefillProvenance): TurnPredictionRecord | null;
+//# sourceMappingURL=TurnPredictionStore.d.ts.map

package/dist/training/TurnPredictionStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TurnPredictionStore.d.ts","sourceRoot":"","sources":["../../src/training/TurnPredictionStore.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,kBAAkB,EAAE,iBAAiB,CAAC;CACvC;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAU9E;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,MAAM,CAOtE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,qBAAqB,EAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,iBAAiB,GAAE,iBAA0B,GAC5C,oBAAoB,GAAG,IAAI,CAoB7B"}

package/dist/training/TurnPredictionStore.js

@@ -0,0 +1,85 @@
+/**
+ * Turn-prediction records — the graduation signal (Decision Capture Layer §5).
+ *
+ * TURN_SUMMARY_PREDICTION has the helper model predict the user's next message
+ * post-turn; historically that prediction was attached to the response and then
+ * THROWN AWAY. This store completes the loop: when the next user message arrives,
+ * the pending prediction is scored against it (cheap deterministic token-F1) and
+ * the `(predicted, actual, match_score)` pair is appended to
+ * `.cortex/training/turn-predictions.jsonl`.
+ *
+ * Why it matters: the apprentice-model graduation gate is "predict the next
+ * turn; graduate when accuracy clears the stage bar." These records are that
+ * metric's raw material — today's predictor is the helper model (the baseline);
+ * the apprentice fills the same slot later and is scored the same way.
+ *
+ * OSS boundary: local JSONL only (no STDB). The nexus-side capture layer mirrors
+ * this stream up (`ingest_turn_prediction`), same as the other `.cortex` stores.
+ */
+import { join } from 'path';
+import { appendJsonlRotating } from '../orchestrator/cortexTrainingRecord.js';
+const STORE_RELATIVE_PATH = join('.cortex', 'training', 'turn-predictions.jsonl');
+/** Lowercased alphanumeric tokens — the comparison alphabet for the match score. */
+function tokens(s) {
+    return (s.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((t) => t.length > 0);
+}
+/**
+ * Deterministic prediction↔actual similarity: token-level F1 (harmonic mean of
+ * precision and recall over unique tokens). 0 = no overlap, 1 = identical token
+ * sets. Chosen over embeddings/LLM-judge for reproducibility and zero cost — the
+ * spec upgrades the metric only if this under-separates.
+ */
+export function predictionMatchScore(predicted, actual) {
+    const p = new Set(tokens(predicted));
+    const a = new Set(tokens(actual));
+    if (p.size === 0 || a.size === 0)
+        return 0;
+    let overlap = 0;
+    for (const t of p)
+        if (a.has(t))
+            overlap++;
+    if (overlap === 0)
+        return 0;
+    const precision = overlap / p.size;
+    const recall = overlap / a.size;
+    return Math.round(((2 * precision * recall) / (precision + recall)) * 1000) / 1000;
+}
+/** Flatten a user message (string or content-block array) to comparable text. */
+export function flattenUserContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return String(content ?? '');
+    return content
+        .map((b) => (typeof b === 'string' ? b : typeof b?.text === 'string' ? b.text : ''))
+        .filter(Boolean)
+        .join('\n');
+}
+/**
+ * Score a pending prediction against the actual next user message and append
+ * the completed record. Truncates stored texts (the raw payload belongs in R2,
+ * not the hot store). Never throws — recording must not affect the turn.
+ */
+export function scoreAndRecordTurnPrediction(projectRoot, pending, actualNext, nowMs, prefillProvenance = 'none') {
+    try {
+        const record = {
+            record_id: `${pending.sessionId}:${pending.turnNumber}`,
+            session_id: pending.sessionId,
+            turn_number: pending.turnNumber,
+            predictor_model: pending.predictorModel,
+            summary: pending.summary ? pending.summary.slice(0, 300) : null,
+            predicted_next: pending.prediction.slice(0, 500),
+            actual_next: actualNext.slice(0, 500),
+            match_score: predictionMatchScore(pending.prediction, actualNext),
+            predicted_at_ms: pending.predictedAtMs,
+            scored_at_ms: nowMs,
+            prefill_provenance: prefillProvenance,
+        };
+        appendJsonlRotating(join(projectRoot, STORE_RELATIVE_PATH), JSON.stringify(record));
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=TurnPredictionStore.js.map

package/dist/training/TurnPredictionStore.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-cortex/core",
-  "version": "4.45.0",
+  "version": "4.47.0",
   "description": "Core orchestration library implementing Claude CLI architecture patterns",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,9 +45,10 @@
     "@anthropic-ai/tokenizer": "^0.0.4",
     "@google/genai": "^1.27.0",
     "@google/generative-ai": "^0.2.1",
+    "@gradio/client": "^2.3.1",
     "@modelcontextprotocol/sdk": "^1.20.2",
-    "@nexus-cortex/executors": "4.45.0",
-    "@nexus-cortex/types": "4.45.0",
+    "@nexus-cortex/executors": "4.47.0",
+    "@nexus-cortex/types": "4.47.0",
     "@types/uuid": "^10.0.0",
     "chokidar": "^3.6.0",
     "openai": "^4.104.0",

package/dist/models/cards/huggingface/llama-3-8b-instruct.d.ts

@@ -1,17 +0,0 @@
-/**
- * Llama 3 8B Instruct (Hugging Face)
- * Meta's Llama 3 8B via Hugging Face Inference API
- *
- * Best for: Open-source alternative, serverless inference
- * Cost: FREE (serverless API, rate-limited)
- *
- * Setup:
- * 1. Get API key from: https://huggingface.co/settings/tokens
- * 2. Set HUGGINGFACE_API_KEY environment variable
- * 3. Model loads on first request (may take 20-30 seconds)
- *
- * Note: Serverless API is rate-limited. For production, use dedicated endpoints.
- */
-import type { ModelConfig } from '../../ModelConfig.interface.js';
-export declare const llama38bInstructHF: ModelConfig;
-//# sourceMappingURL=llama-3-8b-instruct.d.ts.map

package/dist/models/cards/huggingface/llama-3-8b-instruct.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"llama-3-8b-instruct.d.ts","sourceRoot":"","sources":["../../../../src/models/cards/huggingface/llama-3-8b-instruct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE,eAAO,MAAM,kBAAkB,EAAE,WAQ/B,CAAC"}

package/dist/models/cards/huggingface/llama-3-8b-instruct.js

@@ -1,25 +0,0 @@
-/**
- * Llama 3 8B Instruct (Hugging Face)
- * Meta's Llama 3 8B via Hugging Face Inference API
- *
- * Best for: Open-source alternative, serverless inference
- * Cost: FREE (serverless API, rate-limited)
- *
- * Setup:
- * 1. Get API key from: https://huggingface.co/settings/tokens
- * 2. Set HUGGINGFACE_API_KEY environment variable
- * 3. Model loads on first request (may take 20-30 seconds)
- *
- * Note: Serverless API is rate-limited. For production, use dedicated endpoints.
- */
-import { createHuggingFaceModelConfig } from '../../configurators/HuggingFaceConfigurator.js';
-export const llama38bInstructHF = createHuggingFaceModelConfig({
-    id: 'llama-3-8b-instruct-hf',
-    displayName: 'Llama 3 8B Instruct (HF)',
-    family: 'llama-3',
-    huggingFaceModelId: 'meta-llama/Meta-Llama-3-8B-Instruct',
-    contextWindow: 8192,
-    outputTokens: 2048,
-    supportsTools: false
-});
-//# sourceMappingURL=llama-3-8b-instruct.js.map

package/dist/models/cards/huggingface/llama-3-8b-instruct.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"llama-3-8b-instruct.js","sourceRoot":"","sources":["../../../../src/models/cards/huggingface/llama-3-8b-instruct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,gDAAgD,CAAC;AAG9F,MAAM,CAAC,MAAM,kBAAkB,GAAgB,4BAA4B,CAAC;IAC1E,EAAE,EAAE,wBAAwB;IAC5B,WAAW,EAAE,0BAA0B;IACvC,MAAM,EAAE,SAAS;IACjB,kBAAkB,EAAE,qCAAqC;IACzD,aAAa,EAAE,IAAI;IACnB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC"}

package/dist/models/cards/huggingface/mistral-7b-instruct.d.ts

@@ -1,10 +0,0 @@
-/**
- * Mistral 7B Instruct (Hugging Face)
- * Mistral AI's 7B model via Hugging Face Inference API
- *
- * Best for: Fast inference, balanced performance
- * Cost: FREE (serverless API, rate-limited)
- */
-import type { ModelConfig } from '../../ModelConfig.interface.js';
-export declare const mistral7bInstructHF: ModelConfig;
-//# sourceMappingURL=mistral-7b-instruct.d.ts.map

package/dist/models/cards/huggingface/mistral-7b-instruct.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mistral-7b-instruct.d.ts","sourceRoot":"","sources":["../../../../src/models/cards/huggingface/mistral-7b-instruct.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE,eAAO,MAAM,mBAAmB,EAAE,WAQhC,CAAC"}

package/dist/models/cards/huggingface/mistral-7b-instruct.js

@@ -1,18 +0,0 @@
-/**
- * Mistral 7B Instruct (Hugging Face)
- * Mistral AI's 7B model via Hugging Face Inference API
- *
- * Best for: Fast inference, balanced performance
- * Cost: FREE (serverless API, rate-limited)
- */
-import { createHuggingFaceModelConfig } from '../../configurators/HuggingFaceConfigurator.js';
-export const mistral7bInstructHF = createHuggingFaceModelConfig({
-    id: 'mistral-7b-instruct-hf',
-    displayName: 'Mistral 7B Instruct (HF)',
-    family: 'mistral',
-    huggingFaceModelId: 'mistralai/Mistral-7B-Instruct-v0.2',
-    contextWindow: 32768,
-    outputTokens: 4096,
-    supportsTools: false
-});
-//# sourceMappingURL=mistral-7b-instruct.js.map

package/dist/models/cards/huggingface/mistral-7b-instruct.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mistral-7b-instruct.js","sourceRoot":"","sources":["../../../../src/models/cards/huggingface/mistral-7b-instruct.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,gDAAgD,CAAC;AAG9F,MAAM,CAAC,MAAM,mBAAmB,GAAgB,4BAA4B,CAAC;IAC3E,EAAE,EAAE,wBAAwB;IAC5B,WAAW,EAAE,0BAA0B;IACvC,MAAM,EAAE,SAAS;IACjB,kBAAkB,EAAE,oCAAoC;IACxD,aAAa,EAAE,KAAK;IACpB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,KAAK;CACrB,CAAC,CAAC"}