@johndimm/constellations 1.0.4 → 1.0.6

package/App.tsx

@@ -23,6 +23,53 @@ import { buildHandoffFromLiveState, type ConstellationsSessionHandoffV1 } from '
 
 const PeopleBrowserSidebar = lazy(() => import('./components/PeopleBrowserSidebar'));
 
+const WELCOME_EXAMPLES = ["Alan Turing", "The Godfather", "Iceman by Drake"];
+
+function WelcomeOverlay({ hideHeader, onSearch, onDismiss }: { hideHeader?: boolean; onSearch: (term: string) => void; onDismiss: () => void }) {
+    const [draft, setDraft] = useState('');
+    const submit = (term: string) => { const t = term.trim(); if (t) onSearch(t); };
+    return (
+        <div className="absolute inset-0 z-[150] bg-slate-950 flex flex-col items-center justify-center" style={{ paddingTop: hideHeader ? 0 : '3.5rem' }}>
+            <div className="text-center max-w-lg px-8 w-full">
+                <h1 className="text-4xl font-bold mb-3 bg-gradient-to-r from-indigo-400 via-purple-400 to-cyan-400 bg-clip-text text-transparent">
+                    Constellations
+                </h1>
+                <p className="text-slate-400 mb-8 text-base leading-relaxed">
+                    Start with anything. Follow the connections.
+                </p>
+                <form onSubmit={e => { e.preventDefault(); submit(draft); }} className="flex gap-2 mb-6">
+                    <input
+                        autoFocus
+                        type="text"
+                        value={draft}
+                        onChange={e => setDraft(e.target.value)}
+                        placeholder="Person, film, album, idea…"
+                        className="flex-1 bg-slate-800 border border-slate-700 rounded-xl px-4 py-2.5 text-sm text-white placeholder-slate-500 focus:outline-none focus:border-indigo-500/60 focus:ring-1 focus:ring-indigo-500/20"
+                    />
+                    <button
+                        type="submit"
+                        disabled={!draft.trim()}
+                        className="px-4 py-2.5 rounded-xl bg-indigo-600 hover:bg-indigo-500 disabled:opacity-40 disabled:cursor-not-allowed text-white text-sm font-medium transition-colors"
+                    >
+                        Go
+                    </button>
+                </form>
+                <div className="flex flex-wrap justify-center gap-2">
+                    {WELCOME_EXAMPLES.map(ex => (
+                        <button key={ex} onClick={() => submit(ex)}
+                            className="px-3 py-1.5 rounded-lg bg-slate-800 border border-slate-700 text-slate-300 hover:bg-slate-700 hover:text-white transition-all text-sm">
+                            {ex}
+                        </button>
+                    ))}
+                    <button onClick={onDismiss}
+                        className="px-3 py-1.5 rounded-lg bg-slate-800/50 border border-slate-700/50 text-slate-500 hover:bg-slate-800 hover:text-slate-300 transition-all text-sm">
+                        blank slate
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}
 
 type AppProps = {
     mode?: 'standalone' | 'extension';
@@ -36,7 +83,7 @@ type AppProps = {
      */
     showExtensionWhenPanelHidden?: boolean;
     hideSidebar?: boolean;
-    externalSearch?: { term: string; id: string | number } | null;
+    externalSearch?: { term: string; id: string | number; typeHint?: string } | null;
     onExternalSearchConsumed?: (id: string | number) => void;
     onNodeNavigate?: (node: GraphNode) => void;
     renderEvidencePopup?: (selectedLink: GraphLink | null, onClose: () => void) => React.ReactNode;
@@ -243,6 +290,7 @@ const App: React.FC<AppProps> = ({
     });
 
     const [showHelp, setShowHelp] = useState(false);
+    const [welcomeDismissed, setWelcomeDismissed] = useState(false);
 
     const {
         exploreTerm, setExploreTerm, pathStart, setPathStart, pathEnd, setPathEnd,
@@ -325,7 +373,7 @@ const App: React.FC<AppProps> = ({
     useEffect(() => {
         if (skipPlayerBootstrapRef.current) return;
         if (!externalSearch?.term) return;
-        handleStartSearchRef.current(externalSearch.term);
+        handleStartSearchRef.current(externalSearch.term, 0, externalSearch.typeHint);
         if (externalSearch?.id !== undefined) {
             onExternalSearchConsumedRef.current?.(externalSearch.id);
         }
@@ -756,6 +804,10 @@ const App: React.FC<AppProps> = ({
                 />
             </div>
 
+            {!embedded && nodes.length === 0 && !isProcessing && !welcomeDismissed && (
+                <WelcomeOverlay hideHeader={hideHeader} onSearch={handleStartSearch} onDismiss={() => setWelcomeDismissed(true)} />
+            )}
+
             <AppHeader
                 showHeader={!hideHeader}
                 panelCollapsed={panelCollapsed}

package/hooks/useSearchHandlers.ts

@@ -101,7 +101,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
         return nodeData;
     }, [cacheEnabled, cacheBaseUrl]);
 
-    const handleStartSearch = useCallback(async (term: string, recursiveDepth = 0) => {
+    const handleStartSearch = useCallback(async (term: string, recursiveDepth = 0, typeHint?: string) => {
         setIsProcessing(true);
         setError(null);
         const nextSearchId = searchIdRef.current + 1;
@@ -134,7 +134,7 @@ export function useSearchHandlers(options: UseSearchHandlersOptions) {
             // CRITICAL FIX: Only use kiosk domain context if the user hasn't provided a specific disambiguated term.
             // "Republic (Plato)" should NEVER get "Actors / Movies / TV" context.
             const hasDisambiguation = term.includes('(') && term.includes(')');
-            const wikiContext = (showControlPanel && !hasDisambiguation) ? selectedKioskDomain?.label : undefined;
+            const wikiContext = (showControlPanel && !hasDisambiguation) ? selectedKioskDomain?.label : typeHint;
 
             const wiki = await fetchWikipediaSummary(term, wikiContext);
             const canonicalTitle = (wiki.title || term).trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johndimm/constellations",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "type": "module",
   "main": "./index.tsx",
   "exports": {

package/services/aiUtils.ts

@@ -357,6 +357,7 @@ export function isRateLimitError(e: any): boolean {
 export type LlmProviderId = "gemini" | "deepseek" | "openai" | "anthropic";
 
 const BROWSER_LLM_KEY = "constellations_llm_provider";
+const BROWSER_LLM_MODEL_KEY = "constellations_llm_model";
 
 function isValidProvider(v: string): v is LlmProviderId {
   return v === "gemini" || v === "deepseek" || v === "openai" || v === "anthropic";
@@ -382,14 +383,42 @@ export function setBrowserLlmOverride(provider: LlmProviderId | null): void {
   } catch {}
 }
 
-// Server-side per-request override (Node.js module memory, set before each proxy call).
-// This is intentionally simple — dev server is single-user so concurrent-request races are fine.
+export function getBrowserLlmModel(): string | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage.getItem(BROWSER_LLM_MODEL_KEY)?.trim() || null;
+  } catch {}
+  return null;
+}
+
+export function setBrowserLlmModel(model: string | null): void {
+  if (typeof window === "undefined") return;
+  try {
+    if (!model) {
+      window.localStorage.removeItem(BROWSER_LLM_MODEL_KEY);
+    } else {
+      window.localStorage.setItem(BROWSER_LLM_MODEL_KEY, model);
+    }
+  } catch {}
+}
+
+// Server-side per-request overrides (Node.js module memory, set before each proxy call).
+// Intentionally simple — dev server is single-user so concurrent-request races are fine.
 let _serverLlmOverride: LlmProviderId | null = null;
+let _serverLlmModelOverride: string | null = null;
 
 export function setServerLlmOverride(provider: LlmProviderId | null): void {
   _serverLlmOverride = provider;
 }
 
+export function setServerLlmModelOverride(model: string | null): void {
+  _serverLlmModelOverride = model;
+}
+
+export function getServerLlmModelOverride(): string | null {
+  return _serverLlmModelOverride;
+}
+
 export function getLlmProvider(): LlmProviderId {
   if (_serverLlmOverride) return _serverLlmOverride;
   const browser = getBrowserLlmOverride();

package/services/debugLog.ts

@@ -0,0 +1,6 @@
+const isDebug = (): boolean =>
+  typeof window !== "undefined" && !!localStorage.getItem("constellations:debug");
+
+export const dlog = (...args: unknown[]): void => {
+  if (isDebug()) console.log(...args);
+};

package/services/deepseekService.ts

@@ -1,6 +1,6 @@
 "use client";
 import { GeminiResponse, PersonWorksResponse, PathResponse } from "../types";
-import { parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, readBundledEnv, getLlmProvider, looksLikePersonName } from "./aiUtils";
+import { parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, readBundledEnv, getLlmProvider, looksLikePersonName, getServerLlmModelOverride } from "./aiUtils";
 import type { LockedPair } from "./geminiService";
 
 export type { LockedPair };
@@ -61,9 +61,9 @@ async function callAltLlm(system: string, user: string, timeoutMs = TIMEOUT_MS):
   const baseUrl = isOpenAI
     ? (readBundledEnv("VITE_OPENAI_BASE_URL") || "https://api.openai.com/v1")
     : (readBundledEnv("VITE_DEEPSEEK_BASE_URL") || "https://api.deepseek.com/v1");
-  const model = isOpenAI
+  const model = getServerLlmModelOverride() || (isOpenAI
     ? (readBundledEnv("VITE_OPENAI_MODEL") || "gpt-4o-mini")
-    : (readBundledEnv("VITE_DEEPSEEK_MODEL") || "deepseek-chat");
+    : (readBundledEnv("VITE_DEEPSEEK_MODEL") || "deepseek-chat"));
   const key = isOpenAI
     ? readBundledEnv("VITE_OPENAI_API_KEY")
     : readBundledEnv("VITE_DEEPSEEK_API_KEY");

package/services/geminiService.ts

@@ -1,7 +1,7 @@
 "use client";
 import { GoogleGenAI, Type } from "@google/genai";
 import { GeminiResponse, PersonWorksResponse, PathResponse } from "../types";
-import { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify, sanitizeSearchTerm, looksLikePersonName, getLlmProvider } from "./aiUtils";
+import { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify, sanitizeSearchTerm, looksLikePersonName, getLlmProvider, getBrowserLlmModel, getServerLlmModelOverride } from "./aiUtils";
 
 export { getApiKey, getResponseText, cleanJson, parseJsonFromModelText, withTimeout, withRetry, getEnvCacheUrl, getEnvGeminiModel, getEnvGeminiModelClassify } from "./aiUtils";
 
@@ -74,8 +74,8 @@ const CLASSIFY_TIMEOUT_MS = 15000; // 15 seconds for classification
 // Model selection (configurable via Vite env vars)
 // - VITE_GEMINI_MODEL: used for expansions + pathfinding (default)
 // - VITE_GEMINI_MODEL_CLASSIFY: optional override for classification
-const getGeminiModel = getEnvGeminiModel;
-const getGeminiModelClassify = getEnvGeminiModelClassify;
+const getGeminiModel = () => getServerLlmModelOverride() || getEnvGeminiModel();
+const getGeminiModelClassify = () => getServerLlmModelOverride() || getEnvGeminiModelClassify();
 
 // Rejects YouTube channel names, streaming platforms, and other web junk.
 function isValidEntityName(name: string): boolean {
@@ -120,7 +120,7 @@ async function callAiProxy(endpoint: string, body: any) {
     const resp = await fetch(url, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ ...body, llmProvider: getLlmProvider() })
+      body: JSON.stringify({ ...body, llmProvider: getLlmProvider(), llmModel: getBrowserLlmModel() ?? undefined })
     });
 
     if (resp.status === 404 && endpoint === "/api/ai/classify-start") {
@@ -292,13 +292,7 @@ export const classifyStartPair = async (
     });
   }
   if (proxy) {
-    const proxyResult = await callAiProxy("/api/ai/classify-start", { term: rawTerm.trim(), wikiContext });
-    // Sanity check: if proxy says non-atomic but the term strongly looks like a person name, correct it.
-    if (!proxyResult.isAtomic && looksLikePersonName(rawTerm)) {
-      console.warn("[classifyStartPair] proxy returned isAtomic=false for apparent person name; overriding", rawTerm);
-      return { ...proxyResult, isAtomic: true, type: "Person" };
-    }
-    return proxyResult;
+    return await callAiProxy("/api/ai/classify-start", { term: rawTerm.trim(), wikiContext });
   }
 
   const needsMusic = rawTermNeedsMusicEntityExtract(rawTerm);

package/services/imageService.ts

@@ -10,19 +10,14 @@ export type ServerImageResult = {
 
 /**
  * Base URL for `GET /api/image` in the browser.
- * Prefer the current page (e.g. Next.js Soundings implements this route). The graph
- * cache server is for expansions / persistence; image lookup should not depend on it
- * when the host app can resolve Wikipedia images itself.
+ * Prefer the cache/proxy server when one is configured — it always implements /api/image.
+ * Fall back to window.location.origin for Next.js host apps that implement the route locally.
  */
 export const getImageApiBaseUrl = (cacheBaseUrl: string | undefined): string => {
-    if (typeof window !== 'undefined') {
-        return window.location.origin;
-    }
-    return (
-        (cacheBaseUrl && cacheBaseUrl.replace(/\/$/, '')) ||
-        getEffectiveCacheBaseUrl() ||
-        ''
-    );
+    const cacheBase = (cacheBaseUrl && cacheBaseUrl.replace(/\/$/, '')) || getEffectiveCacheBaseUrl();
+    if (cacheBase) return cacheBase;
+    if (typeof window !== 'undefined') return window.location.origin;
+    return '';
 };
 
 export const fetchServerImage = async (

package/services/modelsService.ts

@@ -0,0 +1,140 @@
+export interface ModelInfo {
+  provider: string;
+  id: string;
+  displayName: string;
+}
+
+interface CacheEntry {
+  models: ModelInfo[];
+  fetchedAt: number;
+}
+
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const cache = new Map<string, CacheEntry>();
+
+function cached(provider: string): ModelInfo[] | null {
+  const entry = cache.get(provider);
+  if (entry && Date.now() - entry.fetchedAt < CACHE_TTL_MS) return entry.models;
+  return null;
+}
+
+function store(provider: string, models: ModelInfo[]): ModelInfo[] {
+  cache.set(provider, { models, fetchedAt: Date.now() });
+  return models;
+}
+
+async function fetchGeminiModels(): Promise<ModelInfo[]> {
+  const key = process.env.GEMINI_API_KEY || process.env.VITE_API_KEY || process.env.VITE_GEMINI_API_KEY || "";
+  if (!key) return [];
+  const hit = cached("gemini");
+  if (hit) return hit;
+  try {
+    const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${key}&pageSize=100`);
+    if (!res.ok) return [];
+    const data = await res.json() as { models?: any[] };
+    const models = (data.models ?? [])
+      .filter((m: any) => Array.isArray(m.supportedGenerationMethods) && m.supportedGenerationMethods.includes("generateContent"))
+      .filter((m: any) => !/embedding|aqa|vision-001/i.test(m.name ?? ""))
+      .map((m: any) => ({
+        provider: "gemini",
+        id: String(m.name ?? "").replace(/^models\//, ""),
+        displayName: m.displayName || String(m.name ?? "").replace(/^models\//, ""),
+      }))
+      .sort((a: ModelInfo, b: ModelInfo) => a.id.localeCompare(b.id));
+    return store("gemini", models);
+  } catch {
+    return [];
+  }
+}
+
+async function fetchAnthropicModels(): Promise<ModelInfo[]> {
+  const key = process.env.VITE_ANTHROPIC_API_KEY || "";
+  if (!key) return [];
+  const hit = cached("anthropic");
+  if (hit) return hit;
+  try {
+    const res = await fetch("https://api.anthropic.com/v1/models", {
+      headers: { "x-api-key": key, "anthropic-version": "2023-06-01" },
+    });
+    if (!res.ok) return [];
+    const data = await res.json() as { data?: any[] };
+    const models = (data.data ?? [])
+      .filter((m: any) => String(m.id ?? "").startsWith("claude-"))
+      .map((m: any) => ({
+        provider: "anthropic",
+        id: String(m.id ?? ""),
+        displayName: m.display_name || m.id,
+      }))
+      .sort((a: ModelInfo, b: ModelInfo) => a.id.localeCompare(b.id));
+    return store("anthropic", models);
+  } catch {
+    return [];
+  }
+}
+
+async function fetchOpenAICompatibleModels(
+  provider: "openai" | "deepseek",
+  baseUrl: string,
+  key: string,
+  filter: (id: string) => boolean
+): Promise<ModelInfo[]> {
+  if (!key) return [];
+  const hit = cached(provider);
+  if (hit) return hit;
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/models`, {
+      headers: { Authorization: `Bearer ${key}` },
+    });
+    if (!res.ok) return [];
+    const data = await res.json() as { data?: any[] };
+    const models = (data.data ?? [])
+      .filter((m: any) => filter(String(m.id ?? "")))
+      .map((m: any) => ({
+        provider,
+        id: String(m.id ?? ""),
+        displayName: m.id,
+      }))
+      .sort((a: ModelInfo, b: ModelInfo) => a.id.localeCompare(b.id));
+    return store(provider, models);
+  } catch {
+    return [];
+  }
+}
+
+function isOpenAIChatModel(id: string): boolean {
+  if (!/^(gpt-|o\d|chatgpt-)/i.test(id)) return false;
+  if (/instruct|whisper|dall-e|tts|embed|search|realtime|audio|preview.*audio/i.test(id)) return false;
+  return true;
+}
+
+async function fetchDeepSeekModels(): Promise<ModelInfo[]> {
+  const key = process.env.VITE_DEEPSEEK_API_KEY || "";
+  const baseUrl = process.env.VITE_DEEPSEEK_BASE_URL || "https://api.deepseek.com/v1";
+  return fetchOpenAICompatibleModels("deepseek", baseUrl, key, () => true);
+}
+
+async function fetchOpenAIModels(): Promise<ModelInfo[]> {
+  const key = process.env.VITE_OPENAI_API_KEY || "";
+  const baseUrl = process.env.VITE_OPENAI_BASE_URL || "https://api.openai.com/v1";
+  return fetchOpenAICompatibleModels("openai", baseUrl, key, isOpenAIChatModel);
+}
+
+export async function fetchAllModels(): Promise<ModelInfo[]> {
+  const results = await Promise.allSettled([
+    fetchGeminiModels(),
+    fetchAnthropicModels(),
+    fetchDeepSeekModels(),
+    fetchOpenAIModels(),
+  ]);
+  return results.flatMap(r => r.status === "fulfilled" ? r.value : []);
+}
+
+export async function fetchModelsForProvider(provider: string): Promise<ModelInfo[]> {
+  switch (provider) {
+    case "gemini":    return fetchGeminiModels();
+    case "anthropic": return fetchAnthropicModels();
+    case "deepseek":  return fetchDeepSeekModels();
+    case "openai":    return fetchOpenAIModels();
+    default:          return [];
+  }
+}