feat: simplify the workflow and search patterns

frontend/src/App.tsx

@@ -10,12 +10,13 @@ import KeywordMatcher from "./components/KeywordMatcher";
 import BatchAnalysis from "./components/BatchAnalysis";
 import SimilarWords from "./components/SimilarWords";
 import ContextAnalysis from "./components/ContextAnalysis";
-import EvaluationDashboard from "./components/EvaluationDashboard";
 import Word2VecPanel from "./components/Word2VecPanel";
+import Word2VecTools from "./components/Word2VecTools";
 import DatasetPanel from "./components/DatasetPanel";
+import MetricCard from "./components/MetricCard";
 import "./styles.css";
 
-type NavGroup = "data" | "training" | "analysis" | "evaluation";
+type NavGroup = "data" | "training" | "analysis";
 type TrainingTab = "model" | "w2v";
 type AnalysisTab = "context" | "words" | "search" | "compare" | "keyword" | "match" | "batch";
 
@@ -23,7 +24,6 @@ const STEPS: { id: NavGroup; label: string; needsIndex?: boolean }[] = [
   { id: "data", label: "Data & Setup" },
   { id: "training", label: "Training" },
   { id: "analysis", label: "Analysis", needsIndex: true },
-  { id: "evaluation", label: "Evaluation", needsIndex: true },
 ];
 
 const TRAINING_TABS: { id: TrainingTab; label: string }[] = [
@@ -48,14 +48,22 @@ export default function App() {
   const [stats, setStats] = useState<CorpusStats | null>(null);
   const [showManualSetup, setShowManualSetup] = useState(false);
   const [serverError, setServerError] = useState<string | null>(null);
+  const [w2vReady, setW2vReady] = useState(false);
+  const [w2vInfo, setW2vInfo] = useState<{ vocab_size: number; sentences: number; vector_size: number } | null>(null);
+  const [resetLoading, setResetLoading] = useState(false);
   const ready = stats !== null && stats.index_built;
 
   useEffect(() => {
     checkConnection().then((err) => {
       setServerError(err);
-      // If server is up, try to fetch stats (engine may have been auto-restored)
       if (!err) {
         api.getStats().then(setStats).catch(() => {});
+        api.w2vStatus().then(res => {
+          if (res.ready) {
+            setW2vReady(true);
+            setW2vInfo({ vocab_size: res.vocab_size!, sentences: res.sentences!, vector_size: res.vector_size! });
+          }
+        }).catch(() => {});
       }
     });
     const interval = setInterval(() => {
@@ -64,11 +72,99 @@ export default function App() {
     return () => clearInterval(interval);
   }, []);
 
+  function handleW2vReady(ready: boolean, info?: { vocab_size: number; sentences: number; vector_size: number }) {
+    setW2vReady(ready);
+    setW2vInfo(ready && info ? info : null);
+  }
+
+  async function handleReset() {
+    setResetLoading(true);
+    try {
+      await api.w2vReset();
+      setW2vReady(false);
+      setW2vInfo(null);
+    } catch {
+      // ignore
+    } finally {
+      setResetLoading(false);
+    }
+  }
+
   function handleStepClick(id: NavGroup, needsIndex?: boolean) {
     if (needsIndex && !ready) return;
     setGroup(id);
   }
 
+  // ── W2V trained: stats bar + analysis tabs, no stepper ──
+  if (w2vReady && w2vInfo) {
+    return (
+      <div className="app">
+        <header className="app-header">
+          <h1>Contextual Similarity Engine</h1>
+          {stats && (
+            <div className="header-stats">
+              <span className="badge">{stats.model_name}</span>
+              <span className="badge">{stats.total_documents} docs</span>
+              <span className="badge">{stats.total_chunks} chunks</span>
+            </div>
+          )}
+        </header>
+
+        {serverError && (
+          <div className="server-error-banner">
+            <strong>Server unavailable:</strong> {serverError}
+          </div>
+        )}
+
+        {/* W2V stats bar */}
+        <div className="content">
+          <div className="panel">
+            <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", flexWrap: "wrap", gap: 12 }}>
+              <h2 style={{ margin: 0 }}>Word2Vec Baseline</h2>
+              <button className="btn btn-secondary" onClick={handleReset} disabled={resetLoading}
+                style={{ fontSize: "0.85em" }}>
+                {resetLoading ? "Resetting..." : "Reset & Retrain"}
+              </button>
+            </div>
+            <div className="metric-grid" style={{ marginTop: 12 }}>
+              <MetricCard value={w2vInfo.vocab_size} label="Vocabulary" />
+              <MetricCard value={w2vInfo.sentences} label="Sentences" />
+              <MetricCard value={w2vInfo.vector_size} label="Dimensions" />
+            </div>
+          </div>
+
+          {/* W2V-specific tools: Similar Words, Compare, Semantic Search */}
+          <Word2VecTools />
+        </div>
+
+        {/* Transformer Analysis sub-tabs */}
+        <nav className="subtabs">
+          {ANALYSIS_TABS.map((t) => (
+            <button
+              key={t.id}
+              className={`subtab ${analysisTab === t.id ? "subtab-active" : ""}`}
+              onClick={() => setAnalysisTab(t.id)}
+            >
+              {t.label}
+            </button>
+          ))}
+        </nav>
+
+        {/* Analysis content */}
+        <main className="content">
+          {analysisTab === "context" && <ContextAnalysis />}
+          {analysisTab === "words" && <SimilarWords />}
+          {analysisTab === "search" && <SemanticSearch />}
+          {analysisTab === "compare" && <TextCompare />}
+          {analysisTab === "keyword" && <KeywordAnalysis />}
+          {analysisTab === "match" && <KeywordMatcher />}
+          {analysisTab === "batch" && <BatchAnalysis />}
+        </main>
+      </div>
+    );
+  }
+
+  // ── Normal stepper flow ──
   return (
     <div className="app">
       <header className="app-header">
@@ -91,7 +187,7 @@ export default function App() {
         </div>
       )}
 
-      {/* Progress Stepper (serves as main navigation) */}
+      {/* Progress Stepper */}
       <nav className="stepper">
         {STEPS.map((step, i) => {
           const disabled = step.needsIndex && !ready;
@@ -119,7 +215,7 @@ export default function App() {
         })}
       </nav>
 
-      {/* Sub-tabs for groups with multiple views */}
+      {/* Sub-tabs */}
       {group === "training" && (
         <nav className="subtabs">
           {TRAINING_TABS.map((t) => (
@@ -165,7 +261,7 @@ export default function App() {
         )}
 
         {group === "training" && trainingTab === "model" && <TrainingPanel />}
-        {group === "training" && trainingTab === "w2v" && <Word2VecPanel />}
+        {group === "training" && trainingTab === "w2v" && <Word2VecPanel onReady={handleW2vReady} />}
 
         {group === "analysis" && analysisTab === "context" && <ContextAnalysis />}
         {group === "analysis" && analysisTab === "words" && <SimilarWords />}
@@ -174,8 +270,6 @@ export default function App() {
         {group === "analysis" && analysisTab === "keyword" && <KeywordAnalysis />}
         {group === "analysis" && analysisTab === "match" && <KeywordMatcher />}
         {group === "analysis" && analysisTab === "batch" && <BatchAnalysis />}
-
-        {group === "evaluation" && <EvaluationDashboard />}
       </main>
     </div>
   );

frontend/src/api.ts

@@ -110,6 +110,9 @@ export const api = {
   getCorpusTexts: (maxDocs: number = 500) =>
     client.get<{ documents: { doc_id: string; text: string }[]; count: number }>(`/corpus/texts?max_docs=${maxDocs}`).then(r => r.data),
 
+  getDocument: (docId: string) =>
+    client.get<{ doc_id: string; text: string; num_chunks: number }>(`/documents/${encodeURIComponent(docId)}`).then(r => r.data),
+
   // ---- Engine persistence ----
   saveEngine: () =>
     client.post<{ status: string; chunks: number; documents: number }>("/engine/save").then(r => r.data),
@@ -131,6 +134,18 @@ export const api = {
   w2vInit: (data: { corpus_texts: string[]; vector_size: number; window: number; epochs: number }) =>
     client.post<W2VInitResponse>("/w2v/init", data, long).then(r => r.data),
 
+  w2vInitFromEngine: (params?: { vector_size?: number; window?: number; epochs?: number }) =>
+    client.post<W2VInitResponse & { documents_used: number }>(`/w2v/init-from-engine`, null, {
+      ...long,
+      params: { ...(_sign && { __sign: _sign }), ...params },
+    }).then(r => r.data),
+
+  w2vStatus: () =>
+    client.get<{ ready: boolean; vocab_size?: number; sentences?: number; vector_size?: number; has_saved_state?: boolean }>("/w2v/status").then(r => r.data),
+
+  w2vReset: () =>
+    client.post<{ status: string; message: string }>("/w2v/reset").then(r => r.data),
+
   w2vCompare: (data: { text_a: string; text_b: string }) =>
     client.post<CompareResponse>("/w2v/compare", data).then(r => r.data),
 

frontend/src/components/DocumentViewer.tsx

@@ -0,0 +1,84 @@
+import { useState, type ReactNode } from "react";
+import { api, getErrorMessage } from "../api";
+
+interface Props {
+  docId: string;
+  children: ReactNode;
+}
+
+export default function DocumentViewer({ docId, children }: Props) {
+  const [expanded, setExpanded] = useState(false);
+  const [fullText, setFullText] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  async function handleClick() {
+    if (expanded) {
+      setExpanded(false);
+      return;
+    }
+    if (fullText !== null) {
+      setExpanded(true);
+      return;
+    }
+    setLoading(true); setError("");
+    try {
+      const res = await api.getDocument(docId);
+      setFullText(res.text);
+      setExpanded(true);
+    } catch (err) {
+      setError(getErrorMessage(err));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <div onClick={handleClick}>
+        {children}
+      </div>
+      {loading && (
+        <div style={{ padding: "8px 12px", color: "var(--text-dim)", fontSize: "0.85rem" }}>
+          Loading document...
+        </div>
+      )}
+      {error && (
+        <div style={{ padding: "8px 12px", color: "var(--danger)", fontSize: "0.85rem" }}>
+          {error}
+        </div>
+      )}
+      {expanded && fullText !== null && (
+        <div style={{
+          background: "var(--bg-elevated, #0d1117)",
+          border: "1px solid var(--border)",
+          borderTop: "none",
+          borderRadius: "0 0 var(--radius) var(--radius)",
+          padding: "12px 16px",
+          marginTop: -4,
+          marginBottom: 8,
+          maxHeight: 400,
+          overflowY: "auto",
+          fontSize: "0.82rem",
+          lineHeight: 1.7,
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+          color: "var(--text)",
+        }}>
+          <div style={{ display: "flex", justifyContent: "space-between", marginBottom: 8 }}>
+            <span style={{ fontWeight: 600 }}>{docId}</span>
+            <button
+              onClick={(e) => { e.stopPropagation(); setExpanded(false); }}
+              style={{
+                background: "none", border: "none", color: "var(--text-dim)",
+                cursor: "pointer", fontSize: "0.8rem",
+              }}>
+              Close
+            </button>
+          </div>
+          {fullText}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/SemanticSearch.tsx

@@ -4,6 +4,7 @@ import type { QueryResultItem } from "../types";
 import { useApiCall } from "../hooks/useApiCall";
 import ScoreBar from "./ScoreBar";
 import StatusMessage from "./StatusMessage";
+import DocumentViewer from "./DocumentViewer";
 
 export default function SemanticSearch() {
   const [query, setQuery] = useState("");
@@ -51,17 +52,19 @@ export default function SemanticSearch() {
         <div className="panel">
           <h3>Results ({results.length})</h3>
           {results.map((r) => (
-            <div key={`${r.doc_id}-${r.chunk_index}`} className="result-card">
-              <div className="result-header">
-                <div>
-                  <span className="badge">#{r.rank}</span>{" "}
-                  <span className="badge">{r.doc_id}</span>{" "}
-                  <span className="tag">chunk {r.chunk_index}</span>
+            <DocumentViewer key={`${r.doc_id}-${r.chunk_index}`} docId={r.doc_id}>
+              <div className="result-card" style={{ cursor: "pointer" }}>
+                <div className="result-header">
+                  <div>
+                    <span className="badge">#{r.rank}</span>{" "}
+                    <span className="badge">{r.doc_id}</span>{" "}
+                    <span className="tag">chunk {r.chunk_index}</span>
+                  </div>
+                  <ScoreBar score={r.score} />
                 </div>
-                <ScoreBar score={r.score} />
+                <div className="result-text">{r.text}</div>
               </div>
-              <div className="result-text">{r.text}</div>
-            </div>
+            </DocumentViewer>
           ))}
         </div>
       )}

frontend/src/components/TrainingPanel.tsx

@@ -1,9 +1,7 @@
 import { useState } from "react";
 import { api, getErrorMessage } from "../api";
-import type { TrainResponse, QueryResultItem, CompareResponse } from "../types";
+import type { TrainResponse } from "../types";
 import { useCorpusLoader } from "../hooks/useCorpusLoader";
-import { scoreColor } from "../utils/colors";
-import ScoreBar from "./ScoreBar";
 import StatusMessage from "./StatusMessage";
 import MetricCard from "./MetricCard";
 import Toggle from "./Toggle";
@@ -12,11 +10,6 @@ import LogViewer from "./LogViewer";
 
 type Strategy = "unsupervised" | "contrastive" | "keywords";
 
-interface SimilarWord {
-  word: string;
-  score: number;
-}
-
 const STRATEGIES: { id: Strategy; label: string; desc: string }[] = [
   { id: "unsupervised", label: "Unsupervised", desc: "Soft-label domain adaptation. Samples random pairs and fine-tunes using the model's own similarity scores." },
   { id: "contrastive", label: "Contrastive", desc: "Adjacent sentences = positive pairs. Learns document structure with in-batch negatives and validation." },
@@ -42,26 +35,6 @@ export default function TrainingPanel() {
 
   const { corpusText, setCorpusText, loading: corpusLoading, error, setError, parseCorpus, loadFromEngine } = useCorpusLoader();
 
-  // Similar words
-  const [simWord, setSimWord] = useState("");
-  const [simTopK, setSimTopK] = useState(10);
-  const [simResults, setSimResults] = useState<SimilarWord[]>([]);
-  const [simLoading, setSimLoading] = useState(false);
-
-  // Compare
-  const [compTextA, setCompTextA] = useState("");
-  const [compTextB, setCompTextB] = useState("");
-  const [compResult, setCompResult] = useState<CompareResponse | null>(null);
-  const [compLoading, setCompLoading] = useState(false);
-
-  // Search
-  const [queryText, setQueryText] = useState("");
-  const [queryTopK, setQueryTopK] = useState(5);
-  const [queryResults, setQueryResults] = useState<QueryResultItem[]>([]);
-  const [queryLoading, setQueryLoading] = useState(false);
-
-  const ready = result !== null;
-
   async function handleTrain() {
     setTraining(true); setError(""); setResult(null);
     try {
@@ -87,42 +60,6 @@ export default function TrainingPanel() {
     }
   }
 
-  async function handleSimilarWords() {
-    setSimLoading(true); setError("");
-    try {
-      const res = await api.similarWords({ word: simWord, top_k: simTopK });
-      setSimResults(res.similar);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setSimLoading(false);
-    }
-  }
-
-  async function handleCompare() {
-    setCompLoading(true); setError("");
-    try {
-      const res = await api.compare({ text_a: compTextA, text_b: compTextB });
-      setCompResult(res);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setCompLoading(false);
-    }
-  }
-
-  async function handleQuery() {
-    setQueryLoading(true); setError("");
-    try {
-      const res = await api.query({ text: queryText, top_k: queryTopK });
-      setQueryResults(res.results);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setQueryLoading(false);
-    }
-  }
-
   return (
     <div>
       {/* 1. Training (strategy + config + corpus merged) */}
@@ -223,127 +160,9 @@ export default function TrainingPanel() {
             <MetricCard value={`${result.seconds}s`} label="Time" />
           </div>
           <StatusMessage type="ok"
-            message={`Model saved: ${result.model_path} — use this path in the Setup tab.`} />
+            message={`Model saved: ${result.model_path} — use this path in the Setup tab, then go to Analysis to explore results.`} />
         </div>
       )}
-
-      {/* 2. Similar Words */}
-      <div className="panel">
-        <h2>2. Similar Words</h2>
-        <p className="panel-desc">
-          Find words that appear in similar contexts using transformer embeddings.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Word</label>
-            <input value={simWord} onChange={e => setSimWord(e.target.value)}
-              onKeyDown={e => e.key === "Enter" && handleSimilarWords()}
-              placeholder="e.g. pizza" />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>Top K</label>
-            <input type="number" value={simTopK} onChange={e => setSimTopK(+e.target.value)} min={1} max={50} />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>&nbsp;</label>
-            <button className="btn btn-primary" onClick={handleSimilarWords}
-              disabled={simLoading || !simWord.trim()}>
-              {simLoading ? "Searching..." : "Find"}
-            </button>
-          </div>
-        </div>
-
-        {simResults.length > 0 && (
-          <table className="data-table" style={{ marginTop: 12 }}>
-            <thead>
-              <tr><th>Word</th><th>Similarity</th></tr>
-            </thead>
-            <tbody>
-              {simResults.map((r, i) => (
-                <tr key={i}>
-                  <td style={{ fontWeight: 600 }}>{r.word}</td>
-                  <td><ScoreBar score={r.score} /></td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-        )}
-      </div>
-
-      {/* 3. Compare Texts */}
-      <div className="panel">
-        <h2>3. Compare Texts</h2>
-        <p className="panel-desc">
-          Sentence similarity via transformer contextual embeddings.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Text A</label>
-            <input value={compTextA} onChange={e => setCompTextA(e.target.value)}
-              placeholder="pizza gives me homework" />
-          </div>
-          <div className="form-group">
-            <label>Text B</label>
-            <input value={compTextB} onChange={e => setCompTextB(e.target.value)}
-              placeholder="school gives me homework" />
-          </div>
-        </div>
-        <button className="btn btn-primary" onClick={handleCompare}
-          disabled={compLoading || !compTextA.trim() || !compTextB.trim()} style={{ marginTop: 8 }}>
-          {compLoading ? "Comparing..." : "Compare"}
-        </button>
-
-        {compResult && (
-          <div className="similarity-gauge" style={{ marginTop: 16 }}>
-            <div className="similarity-value"
-              style={{ color: scoreColor(compResult.similarity) }}>
-              {compResult.similarity.toFixed(4)}
-            </div>
-            <div className="similarity-label">Transformer Cosine Similarity</div>
-          </div>
-        )}
-      </div>
-
-      {/* 4. Semantic Search */}
-      <div className="panel">
-        <h2>4. Semantic Search</h2>
-        <p className="panel-desc">
-          Search your corpus using transformer embeddings.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Query</label>
-            <input value={queryText} onChange={e => setQueryText(e.target.value)}
-              onKeyDown={e => e.key === "Enter" && handleQuery()}
-              placeholder="a place where children learn" />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>Top K</label>
-            <input type="number" value={queryTopK} onChange={e => setQueryTopK(+e.target.value)} min={1} max={20} />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>&nbsp;</label>
-            <button className="btn btn-primary" onClick={handleQuery}
-              disabled={queryLoading || !queryText.trim()}>
-              {queryLoading ? "Searching..." : "Search"}
-            </button>
-          </div>
-        </div>
-
-        {queryResults.length > 0 && (
-          <div style={{ marginTop: 12 }}>
-            {queryResults.map((r, i) => (
-              <div key={i} className="result-card">
-                <div className="result-header">
-                  <span>#{r.rank} <span className="tag">{r.doc_id}</span></span>
-                  <ScoreBar score={r.score} />
-                </div>
-                <div className="result-text">{r.text}</div>
-              </div>
-            ))}
-          </div>
-        )}
-      </div>
     </div>
   );
 }

frontend/src/components/Word2VecPanel.tsx

@@ -1,54 +1,43 @@
-import { useState } from "react";
+import { useState, useEffect } from "react";
 import { api, getErrorMessage } from "../api";
-import type { W2VInitResponse, W2VQueryResult, W2VSimilarWord, CompareResponse } from "../types";
-import { useCorpusLoader } from "../hooks/useCorpusLoader";
-import { scoreColor } from "../utils/colors";
-import ScoreBar from "./ScoreBar";
+import type { W2VInitResponse } from "../types";
 import StatusMessage from "./StatusMessage";
 import LogViewer from "./LogViewer";
 import MetricCard from "./MetricCard";
 
-export default function Word2VecPanel() {
-  // Init
+interface Props {
+  onReady: (ready: boolean, info?: { vocab_size: number; sentences: number; vector_size: number }) => void;
+}
+
+export default function Word2VecPanel({ onReady }: Props) {
+  const [statusChecked, setStatusChecked] = useState(false);
+  const [trainResult, setTrainResult] = useState<W2VInitResponse | null>(null);
+
   const [vectorSize, setVectorSize] = useState(100);
   const [windowSize, setWindowSize] = useState(5);
   const [w2vEpochs, setW2vEpochs] = useState(50);
   const [showAdvanced, setShowAdvanced] = useState(false);
   const [initLoading, setInitLoading] = useState(false);
-  const [initResult, setInitResult] = useState<W2VInitResponse | null>(null);
-
-  const { corpusText, setCorpusText, loading: corpusLoading, error, setError, parseCorpus, loadFromEngine } = useCorpusLoader();
-
-  // Similar words
-  const [simWord, setSimWord] = useState("");
-  const [simTopK, setSimTopK] = useState(10);
-  const [simResults, setSimResults] = useState<W2VSimilarWord[]>([]);
-  const [simLoading, setSimLoading] = useState(false);
-
-  // Compare
-  const [compTextA, setCompTextA] = useState("");
-  const [compTextB, setCompTextB] = useState("");
-  const [compResult, setCompResult] = useState<CompareResponse | null>(null);
-  const [compLoading, setCompLoading] = useState(false);
-
-  // Query
-  const [queryText, setQueryText] = useState("");
-  const [queryTopK, setQueryTopK] = useState(5);
-  const [queryResults, setQueryResults] = useState<W2VQueryResult[]>([]);
-  const [queryLoading, setQueryLoading] = useState(false);
-
-  async function handleInit() {
-    setInitLoading(true); setError(""); setInitResult(null);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    api.w2vStatus().then(res => {
+      if (res.ready) {
+        onReady(true, { vocab_size: res.vocab_size!, sentences: res.sentences!, vector_size: res.vector_size! });
+      }
+      setStatusChecked(true);
+    }).catch(() => setStatusChecked(true));
+  }, []);
+
+  async function handleTrainFromEngine() {
+    setInitLoading(true); setError(""); setTrainResult(null);
     try {
-      const corpus = parseCorpus();
-      if (!corpus.length) { setError("Corpus is empty."); setInitLoading(false); return; }
-      const res = await api.w2vInit({
-        corpus_texts: corpus,
+      const res = await api.w2vInitFromEngine({
         vector_size: vectorSize,
         window: windowSize,
         epochs: w2vEpochs,
       });
-      setInitResult(res);
+      setTrainResult(res);
     } catch (err) {
       setError(getErrorMessage(err));
     } finally {
@@ -56,76 +45,44 @@ export default function Word2VecPanel() {
     }
   }
 
-  async function handleSimilarWords() {
-    setSimLoading(true); setError("");
-    try {
-      const res = await api.w2vSimilarWords({ word: simWord, top_k: simTopK });
-      setSimResults(res.similar);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setSimLoading(false);
-    }
+  if (!statusChecked) {
+    return <div className="panel"><p>Checking Word2Vec status...</p></div>;
   }
 
-  async function handleCompare() {
-    setCompLoading(true); setError("");
-    try {
-      const res = await api.w2vCompare({ text_a: compTextA, text_b: compTextB });
-      setCompResult(res);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setCompLoading(false);
-    }
-  }
+  // Training complete — show results + continue button
+  if (trainResult) {
+    return (
+      <div>
+        <div className="panel">
+          <h2>Training Complete</h2>
+          <div className="metric-grid">
+            <MetricCard value={trainResult.vocab_size} label="Vocabulary" />
+            <MetricCard value={trainResult.sentences} label="Sentences" />
+            <MetricCard value={trainResult.vector_size} label="Dimensions" />
+            <MetricCard value={`${trainResult.seconds}s`} label="Train Time" />
+          </div>
+          <StatusMessage type="ok" message="Word2Vec model trained and saved. It will persist across restarts." />
+          <button className="btn btn-primary" style={{ marginTop: 12 }}
+            onClick={() => onReady(true, { vocab_size: trainResult.vocab_size, sentences: trainResult.sentences, vector_size: trainResult.vector_size })}>
+            Continue to Analysis
+          </button>
+        </div>
 
-  async function handleQuery() {
-    setQueryLoading(true); setError("");
-    try {
-      const res = await api.w2vQuery({ text: queryText, top_k: queryTopK });
-      setQueryResults(res.results);
-    } catch (err) {
-      setError(getErrorMessage(err));
-    } finally {
-      setQueryLoading(false);
-    }
+        <LogViewer active={false} />
+      </div>
+    );
   }
 
-  const ready = initResult !== null;
-
+  // Training form
   return (
     <div>
-      {/* 1. Training */}
       <div className="panel">
-        <h2>1. Train Word2Vec (gensim)</h2>
+        <h2>Word2Vec Baseline (gensim)</h2>
         <p className="panel-desc">
           Static embeddings — one vector per word, no context awareness.
-          Useful as a baseline to compare against the transformer approach.
+          Train on all documents loaded in the engine to use as a baseline comparison.
         </p>
-        <div style={{ display: "flex", gap: 8, marginBottom: 10 }}>
-          <button className="btn btn-secondary" onClick={loadFromEngine}
-            disabled={corpusLoading}>
-            {corpusLoading ? "Loading..." : "Load from Engine"}
-          </button>
-          {corpusText && (
-            <button className="btn btn-secondary" onClick={() => setCorpusText("")}>
-              Clear
-            </button>
-          )}
-        </div>
-        <div className="form-group" style={{ marginBottom: 12 }}>
-          <label>
-            Corpus (separate documents with blank lines)
-            {corpusText && (
-              <span style={{ color: "var(--text-dim)", fontWeight: 400 }}>
-                {" "} — {parseCorpus().length} documents detected
-              </span>
-            )}
-          </label>
-          <textarea value={corpusText} onChange={e => setCorpusText(e.target.value)} rows={8}
-            placeholder="Document 1 text...\n\nDocument 2 text..." />
-        </div>
+
         <button className="advanced-toggle" onClick={() => setShowAdvanced(!showAdvanced)}>
           {showAdvanced ? "\u25be" : "\u25b8"} Advanced Settings
         </button>
@@ -149,145 +106,15 @@ export default function Word2VecPanel() {
           </div>
         )}
 
-        <button className="btn btn-primary" onClick={handleInit}
-          disabled={initLoading || !corpusText.trim()} style={{ marginTop: 8 }}>
-          {initLoading ? <><span className="spinner" /> Training...</> : "Train Word2Vec"}
+        <button className="btn btn-primary" onClick={handleTrainFromEngine}
+          disabled={initLoading} style={{ marginTop: 8 }}>
+          {initLoading ? <><span className="spinner" /> Training on all engine documents...</> : "Train Word2Vec"}
         </button>
 
         <LogViewer active={initLoading} />
       </div>
 
       {error && <StatusMessage type="err" message={error} />}
-
-      {initResult && (
-        <div className="panel">
-          <h2>Word2Vec Ready</h2>
-          <div className="metric-grid">
-            <MetricCard value={initResult.vocab_size} label="Vocabulary" />
-            <MetricCard value={initResult.sentences} label="Sentences" />
-            <MetricCard value={initResult.vector_size} label="Dimensions" />
-            <MetricCard value={`${initResult.seconds}s`} label="Time" />
-          </div>
-        </div>
-      )}
-
-      {/* 2. Similar Words */}
-      <div className="panel">
-        <h2>2. Similar Words</h2>
-        <p className="panel-desc">
-          Find words that appear in similar contexts using Word2Vec static embeddings.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Word</label>
-            <input value={simWord} onChange={e => setSimWord(e.target.value)}
-              onKeyDown={e => e.key === "Enter" && handleSimilarWords()}
-              placeholder="e.g. pizza" />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>Top K</label>
-            <input type="number" value={simTopK} onChange={e => setSimTopK(+e.target.value)} min={1} max={50} />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>&nbsp;</label>
-            <button className="btn btn-primary" onClick={handleSimilarWords}
-              disabled={simLoading || !ready || !simWord.trim()}>
-              {simLoading ? "Searching..." : "Find"}
-            </button>
-          </div>
-        </div>
-
-        {simResults.length > 0 && (
-          <table className="data-table" style={{ marginTop: 12 }}>
-            <thead>
-              <tr><th>Word</th><th>Similarity</th></tr>
-            </thead>
-            <tbody>
-              {simResults.map((r, i) => (
-                <tr key={i}>
-                  <td style={{ fontWeight: 600 }}>{r.word}</td>
-                  <td><ScoreBar score={r.score} /></td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-        )}
-      </div>
-
-      {/* 3. Compare Texts */}
-      <div className="panel">
-        <h2>3. Compare Texts</h2>
-        <p className="panel-desc">
-          Sentence similarity via averaged word vectors.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Text A</label>
-            <input value={compTextA} onChange={e => setCompTextA(e.target.value)}
-              placeholder="pizza gives me homework" />
-          </div>
-          <div className="form-group">
-            <label>Text B</label>
-            <input value={compTextB} onChange={e => setCompTextB(e.target.value)}
-              placeholder="school gives me homework" />
-          </div>
-        </div>
-        <button className="btn btn-primary" onClick={handleCompare}
-          disabled={compLoading || !ready || !compTextA.trim() || !compTextB.trim()} style={{ marginTop: 8 }}>
-          {compLoading ? "Comparing..." : "Compare"}
-        </button>
-
-        {compResult && (
-          <div className="similarity-gauge" style={{ marginTop: 16 }}>
-            <div className="similarity-value"
-              style={{ color: scoreColor(compResult.similarity) }}>
-              {compResult.similarity.toFixed(4)}
-            </div>
-            <div className="similarity-label">Word2Vec Cosine Similarity</div>
-          </div>
-        )}
-      </div>
-
-      {/* 4. Semantic Search */}
-      <div className="panel">
-        <h2>4. Semantic Search</h2>
-        <p className="panel-desc">
-          Search your corpus using averaged Word2Vec vectors.
-        </p>
-        <div className="form-row">
-          <div className="form-group">
-            <label>Query</label>
-            <input value={queryText} onChange={e => setQueryText(e.target.value)}
-              onKeyDown={e => e.key === "Enter" && handleQuery()}
-              placeholder="a place where children learn" />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>Top K</label>
-            <input type="number" value={queryTopK} onChange={e => setQueryTopK(+e.target.value)} min={1} max={20} />
-          </div>
-          <div className="form-group form-group-sm">
-            <label>&nbsp;</label>
-            <button className="btn btn-primary" onClick={handleQuery}
-              disabled={queryLoading || !ready || !queryText.trim()}>
-              {queryLoading ? "Searching..." : "Search"}
-            </button>
-          </div>
-        </div>
-
-        {queryResults.length > 0 && (
-          <div style={{ marginTop: 12 }}>
-            {queryResults.map((r, i) => (
-              <div key={i} className="result-card">
-                <div className="result-header">
-                  <span>#{r.rank} <span className="tag">{r.doc_id}</span></span>
-                  <ScoreBar score={r.score} />
-                </div>
-                <div className="result-text">{r.text}</div>
-              </div>
-            ))}
-          </div>
-        )}
-      </div>
     </div>
   );
 }

frontend/src/components/Word2VecTools.tsx

@@ -0,0 +1,193 @@
+import { useState } from "react";
+import { api, getErrorMessage } from "../api";
+import type { W2VQueryResult, W2VSimilarWord, CompareResponse } from "../types";
+import { scoreColor } from "../utils/colors";
+import ScoreBar from "./ScoreBar";
+import StatusMessage from "./StatusMessage";
+import DocumentViewer from "./DocumentViewer";
+
+export default function Word2VecTools() {
+  const [error, setError] = useState("");
+
+  // Similar words
+  const [simWord, setSimWord] = useState("");
+  const [simTopK, setSimTopK] = useState(10);
+  const [simResults, setSimResults] = useState<W2VSimilarWord[]>([]);
+  const [simLoading, setSimLoading] = useState(false);
+
+  // Compare
+  const [compTextA, setCompTextA] = useState("");
+  const [compTextB, setCompTextB] = useState("");
+  const [compResult, setCompResult] = useState<CompareResponse | null>(null);
+  const [compLoading, setCompLoading] = useState(false);
+
+  // Search
+  const [queryText, setQueryText] = useState("");
+  const [queryTopK, setQueryTopK] = useState(5);
+  const [queryResults, setQueryResults] = useState<W2VQueryResult[]>([]);
+  const [queryLoading, setQueryLoading] = useState(false);
+
+  async function handleSimilarWords() {
+    setSimLoading(true); setError("");
+    try {
+      const res = await api.w2vSimilarWords({ word: simWord, top_k: simTopK });
+      setSimResults(res.similar);
+    } catch (err) {
+      setError(getErrorMessage(err));
+    } finally {
+      setSimLoading(false);
+    }
+  }
+
+  async function handleCompare() {
+    setCompLoading(true); setError("");
+    try {
+      const res = await api.w2vCompare({ text_a: compTextA, text_b: compTextB });
+      setCompResult(res);
+    } catch (err) {
+      setError(getErrorMessage(err));
+    } finally {
+      setCompLoading(false);
+    }
+  }
+
+  async function handleQuery() {
+    setQueryLoading(true); setError("");
+    try {
+      const res = await api.w2vQuery({ text: queryText, top_k: queryTopK });
+      setQueryResults(res.results);
+    } catch (err) {
+      setError(getErrorMessage(err));
+    } finally {
+      setQueryLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      {error && <StatusMessage type="err" message={error} />}
+
+      <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 16 }}>
+        {/* Similar Words */}
+        <div className="panel">
+          <h3 style={{ marginTop: 0 }}>Similar Words</h3>
+          <p className="panel-desc">
+            Find words that appear in similar contexts using Word2Vec static embeddings.
+          </p>
+          <div className="form-row">
+            <div className="form-group">
+              <label>Word</label>
+              <input value={simWord} onChange={e => setSimWord(e.target.value)}
+                onKeyDown={e => e.key === "Enter" && handleSimilarWords()}
+                placeholder="e.g. pizza" />
+            </div>
+            <div className="form-group form-group-sm">
+              <label>Top K</label>
+              <input type="number" value={simTopK} onChange={e => setSimTopK(+e.target.value)}
+                min={1} max={50} style={{ width: 60 }} />
+            </div>
+            <div className="form-group form-group-sm">
+              <label>&nbsp;</label>
+              <button className="btn btn-primary" onClick={handleSimilarWords}
+                disabled={simLoading || !simWord.trim()}>
+                {simLoading ? "..." : "Find"}
+              </button>
+            </div>
+          </div>
+
+          {simResults.length > 0 && (
+            <table className="data-table" style={{ marginTop: 8 }}>
+              <thead>
+                <tr><th>Word</th><th>Similarity</th></tr>
+              </thead>
+              <tbody>
+                {simResults.map((r, i) => (
+                  <tr key={i}>
+                    <td style={{ fontWeight: 600 }}>{r.word}</td>
+                    <td><ScoreBar score={r.score} /></td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          )}
+        </div>
+
+        {/* Compare Texts */}
+        <div className="panel">
+          <h3 style={{ marginTop: 0 }}>Compare Texts</h3>
+          <p className="panel-desc">
+            Sentence similarity via averaged word vectors.
+          </p>
+          <div className="form-group" style={{ marginBottom: 8 }}>
+            <label>Text A</label>
+            <input value={compTextA} onChange={e => setCompTextA(e.target.value)}
+              placeholder="pizza gives me homework" />
+          </div>
+          <div className="form-group" style={{ marginBottom: 8 }}>
+            <label>Text B</label>
+            <input value={compTextB} onChange={e => setCompTextB(e.target.value)}
+              placeholder="school gives me homework" />
+          </div>
+          <button className="btn btn-primary" onClick={handleCompare}
+            disabled={compLoading || !compTextA.trim() || !compTextB.trim()}>
+            {compLoading ? "..." : "Compare"}
+          </button>
+
+          {compResult && (
+            <div className="similarity-gauge" style={{ marginTop: 12 }}>
+              <div className="similarity-value"
+                style={{ color: scoreColor(compResult.similarity) }}>
+                {compResult.similarity.toFixed(4)}
+              </div>
+              <div className="similarity-label">Word2Vec Cosine Similarity</div>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Semantic Search — full width */}
+      <div className="panel">
+        <h3 style={{ marginTop: 0 }}>Semantic Search</h3>
+        <p className="panel-desc">
+          Search your corpus using averaged Word2Vec vectors.
+        </p>
+        <div className="form-row">
+          <div className="form-group" style={{ flex: 1 }}>
+            <label>Query</label>
+            <input value={queryText} onChange={e => setQueryText(e.target.value)}
+              onKeyDown={e => e.key === "Enter" && handleQuery()}
+              placeholder="a place where children learn" />
+          </div>
+          <div className="form-group form-group-sm">
+            <label>Top K</label>
+            <input type="number" value={queryTopK} onChange={e => setQueryTopK(+e.target.value)}
+              min={1} max={20} style={{ width: 60 }} />
+          </div>
+          <div className="form-group form-group-sm">
+            <label>&nbsp;</label>
+            <button className="btn btn-primary" onClick={handleQuery}
+              disabled={queryLoading || !queryText.trim()}>
+              {queryLoading ? "Searching..." : "Search"}
+            </button>
+          </div>
+        </div>
+
+        {queryResults.length > 0 && (
+          <div style={{ marginTop: 8 }}>
+            {queryResults.map((r, i) => (
+              <DocumentViewer key={i} docId={r.doc_id}>
+                <div className="result-card" style={{ cursor: "pointer" }}>
+                  <div className="result-header">
+                    <span>#{r.rank} <span className="tag">{r.doc_id}</span></span>
+                    <ScoreBar score={r.score} />
+                  </div>
+                  <div className="result-text">{r.text}</div>
+                </div>
+              </DocumentViewer>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/app.tsx","./src/api.ts","./src/main.tsx","./src/types.ts","./src/vite-env.d.ts","./src/components/batchanalysis.tsx","./src/components/contextanalysis.tsx","./src/components/datasetpanel.tsx","./src/components/documentviewer.tsx","./src/components/enginesetup.tsx","./src/components/evaluationdashboard.tsx","./src/components/keywordanalysis.tsx","./src/components/keywordmatcher.tsx","./src/components/logviewer.tsx","./src/components/metriccard.tsx","./src/components/scorebar.tsx","./src/components/select.tsx","./src/components/semanticsearch.tsx","./src/components/similarwords.tsx","./src/components/statusmessage.tsx","./src/components/switch.tsx","./src/components/textcompare.tsx","./src/components/toggle.tsx","./src/components/trainingpanel.tsx","./src/components/word2vecpanel.tsx","./src/components/word2vectools.tsx","./src/hooks/useapicall.ts","./src/hooks/usecorpusloader.ts","./src/utils/colors.ts"],"version":"5.9.3"}

server.py

@@ -145,12 +145,13 @@ evaluator: Optional[Evaluator] = None
 w2v_engine: Optional[Word2VecEngine] = None
 
 ENGINE_SAVE_DIR = Path(os.environ.get("ENGINE_STATE_DIR", str(BASE_DIR / "engine_state")))
+W2V_SAVE_DIR = Path(os.environ.get("W2V_STATE_DIR", str(BASE_DIR / "w2v_state")))
 
 
 @app.on_event("startup")
 def _auto_restore():
-    """Restore engine state from disk if a previous save exists."""
-    global engine, evaluator
+    """Restore engine and W2V state from disk if previous saves exist."""
+    global engine, evaluator, w2v_engine
     if (ENGINE_SAVE_DIR / "meta.json").is_file():
         try:
             engine = ContextualSimilarityEngine.load(str(ENGINE_SAVE_DIR))
@@ -160,6 +161,13 @@ def _auto_restore():
                         len(engine.chunks), len(engine._doc_ids))
         except Exception:
             logger.exception("Failed to auto-restore engine state — starting fresh")
+    if Word2VecEngine.has_saved_state(str(W2V_SAVE_DIR)):
+        try:
+            w2v_engine = Word2VecEngine.load(str(W2V_SAVE_DIR))
+            logger.info("Auto-restored Word2Vec: %d sentences, %d vocab",
+                        len(w2v_engine.sentences), len(w2v_engine.model.wv))
+        except Exception:
+            logger.exception("Failed to auto-restore Word2Vec state — starting fresh")
 
 
 @app.get("/api/logs/stream")
@@ -572,6 +580,18 @@ def get_corpus_texts(max_docs: int = Query(default=500, ge=1, le=10_000)):
     return {"documents": result, "count": len(result)}
 
 
+@app.get("/api/documents/{doc_id}")
+def get_document(doc_id: str):
+    """Return the full text of a document by reconstructing its chunks."""
+    _ensure_engine()
+    chunks = [c for c in engine.chunks if c.doc_id == doc_id]
+    if not chunks:
+        raise HTTPException(404, f"Document '{doc_id}' not found.")
+    chunks.sort(key=lambda c: c.chunk_index)
+    full_text = "\n".join(c.text for c in chunks)
+    return {"doc_id": doc_id, "text": full_text, "num_chunks": len(chunks)}
+
+
 @app.post("/api/engine/save")
 def save_engine():
     """Save current engine state to disk for later restore."""
@@ -615,9 +635,53 @@ def w2v_init(req: W2VInitRequest):
     stats = w2v_engine.build_index()
     elapsed = round(time.time() - t0, 2)
     logger.info("Word2Vec ready: %s in %.2fs", stats, elapsed)
+    # Auto-save so data persists across restarts
+    try:
+        w2v_engine.save(str(W2V_SAVE_DIR))
+    except Exception:
+        logger.warning("Auto-save W2V after init failed", exc_info=True)
     return {**stats, "seconds": elapsed}
 
 
+@app.post("/api/w2v/init-from-engine")
+def w2v_init_from_engine(
+    vector_size: int = Query(default=100, ge=50, le=500),
+    window: int = Query(default=5, ge=1, le=20),
+    epochs: int = Query(default=50, ge=1, le=200),
+):
+    """Train Word2Vec directly from all documents already loaded in the engine.
+
+    This avoids the round-trip through the frontend and uses ALL engine docs.
+    """
+    global w2v_engine
+    _ensure_engine()
+    if not engine.chunks:
+        raise HTTPException(400, "No documents in the engine. Load a dataset first.")
+
+    # Group chunks by doc_id to reconstruct full documents
+    docs: dict[str, list[str]] = {}
+    for chunk in engine.chunks:
+        if chunk.doc_id not in docs:
+            docs[chunk.doc_id] = []
+        docs[chunk.doc_id].append(chunk.text)
+
+    logger.info("Word2Vec init from engine: %d documents, vector_size=%d, window=%d, epochs=%d",
+                len(docs), vector_size, window, epochs)
+    t0 = time.time()
+    w2v_engine = Word2VecEngine(vector_size=vector_size, window=window, epochs=epochs)
+    for doc_id, chunks_list in docs.items():
+        w2v_engine.add_document(doc_id, "\n".join(chunks_list))
+    stats = w2v_engine.build_index()
+    elapsed = round(time.time() - t0, 2)
+    logger.info("Word2Vec ready: %s in %.2fs", stats, elapsed)
+    # Auto-save
+    try:
+        w2v_engine.save(str(W2V_SAVE_DIR))
+    except Exception:
+        logger.warning("Auto-save W2V after init failed", exc_info=True)
+    return {**stats, "seconds": elapsed, "documents_used": len(docs)}
+
+
 @app.post("/api/w2v/compare")
 def w2v_compare(req: W2VCompareRequest):
     _ensure_w2v()
@@ -642,6 +706,32 @@ def w2v_similar_words(req: W2VWordRequest):
     return {"word": req.word, "similar": [{"word": w, "score": round(s, 4)} for w, s in similar]}
 
 
+@app.get("/api/w2v/status")
+def w2v_status():
+    """Check if Word2Vec is loaded (from training or restored from disk)."""
+    if w2v_engine is not None and w2v_engine.model is not None:
+        return {
+            "ready": True,
+            "vocab_size": len(w2v_engine.model.wv),
+            "sentences": len(w2v_engine.sentences),
+            "vector_size": w2v_engine.vector_size,
+        }
+    has_saved = Word2VecEngine.has_saved_state(str(W2V_SAVE_DIR))
+    return {"ready": False, "has_saved_state": has_saved}
+
+
+@app.post("/api/w2v/reset")
+def w2v_reset():
+    """Delete saved Word2Vec state and clear the in-memory model."""
+    global w2v_engine
+    w2v_engine = None
+    import shutil
+    if W2V_SAVE_DIR.is_dir():
+        shutil.rmtree(str(W2V_SAVE_DIR))
+        logger.info("Word2Vec state deleted from %s", W2V_SAVE_DIR)
+    return {"status": "ok", "message": "Word2Vec state cleared. You can retrain now."}
+
+
 # ------------------------------------------------------------------ #
 #  Dataset endpoints (HuggingFace Epstein Files)
 # ------------------------------------------------------------------ #

word2vec_baseline.py

@@ -16,9 +16,11 @@ Usage:
     score = w2v.compare_texts("pizza gives me homework", "school gives me homework")
 """
 
+import json
 import re
 import logging
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Optional
 
 import numpy as np
@@ -145,6 +147,76 @@ class Word2VecEngine:
             return 0.0
         return float(self.model.wv.similarity(a, b))
 
+    # ------------------------------------------------------------------ #
+    #  Persistence
+    # ------------------------------------------------------------------ #
+
+    def save(self, directory: str) -> dict:
+        """Save trained Word2Vec state to disk for later restore."""
+        save_dir = Path(directory)
+        save_dir.mkdir(parents=True, exist_ok=True)
+
+        if self.model is None:
+            raise RuntimeError("Cannot save: model has not been trained yet.")
+
+        self.model.save(str(save_dir / "w2v.model"))
+        np.save(save_dir / "sentence_vecs.npy", self.sentence_vecs)
+
+        meta = {
+            "vector_size": self.vector_size,
+            "window": self.window,
+            "min_count": self.min_count,
+            "epochs": self.epochs,
+            "sg": self.sg,
+            "num_sentences": len(self.sentences),
+            "vocab_size": len(self.model.wv),
+        }
+        with open(save_dir / "w2v_meta.json", "w") as f:
+            json.dump(meta, f, indent=2)
+
+        # Save sentences and their doc mappings
+        with open(save_dir / "w2v_sentences.json", "w") as f:
+            json.dump({"sentences": self.sentences, "sentence_docs": self.sentence_docs}, f)
+
+        logger.info("Word2Vec saved to %s: %d sentences, %d vocab",
+                     directory, len(self.sentences), len(self.model.wv))
+        return meta
+
+    @classmethod
+    def load(cls, directory: str) -> "Word2VecEngine":
+        """Load a previously saved Word2Vec state from disk."""
+        save_dir = Path(directory)
+        if not (save_dir / "w2v_meta.json").is_file():
+            raise FileNotFoundError(f"No saved Word2Vec state at {directory}")
+
+        with open(save_dir / "w2v_meta.json") as f:
+            meta = json.load(f)
+
+        engine = cls(
+            vector_size=meta["vector_size"],
+            window=meta["window"],
+            min_count=meta["min_count"],
+            epochs=meta["epochs"],
+            sg=meta["sg"],
+        )
+
+        engine.model = Word2Vec.load(str(save_dir / "w2v.model"))
+        engine.sentence_vecs = np.load(save_dir / "sentence_vecs.npy")
+
+        with open(save_dir / "w2v_sentences.json") as f:
+            data = json.load(f)
+            engine.sentences = data["sentences"]
+            engine.sentence_docs = data["sentence_docs"]
+
+        logger.info("Word2Vec loaded from %s: %d sentences, %d vocab",
+                     directory, len(engine.sentences), len(engine.model.wv))
+        return engine
+
+    @staticmethod
+    def has_saved_state(directory: str) -> bool:
+        """Check if a saved Word2Vec state exists at the given directory."""
+        return (Path(directory) / "w2v_meta.json").is_file()
+
     # ------------------------------------------------------------------ #
 
     def _sentence_vector(self, tokens: list[str]) -> np.ndarray: