@ltm-blueverse/alpha-semantic-hub 0.8.0 → 0.9.0

package/README.md

@@ -322,6 +322,41 @@ SDK is missing. Two patterns:
 Also available: Redshift, Cassandra, MongoDB, DuckDB, Elasticsearch, Kafka-style
 streams, email, RSS/Atom feeds, Airflow, Parquet/Arrow.
 
+### Connector catalog and the credential vault
+
+**26 connectors in 5 categories**, all selectable from the Studio's Source
+Ingestion tab:
+
+| Category | Connectors |
+|---|---|
+| Warehouses & Lakehouses | Databricks, Snowflake, BigQuery, Redshift |
+| Databases | SQL (Postgres/MySQL/SQLite), DuckDB, MongoDB, Cassandra, Elasticsearch |
+| Business SaaS | Salesforce, SAP (OData), ServiceNow, Power BI, SharePoint/OneDrive (Graph API) |
+| Files & Storage | File, Parquet, XML, Cloud Storage (S3/GCS/Azure), Google Drive |
+| Web & APIs | REST, Web page, RSS/Atom, Git repo, Email (IMAP/POP3), HuggingFace, MCP server |
+
+Connectors marked `dep` need an optional dependency (e.g. `lxml`, `boto3`,
+`pymongo`, `gitpython`, `duckdb`, `google-cloud-bigquery`); the Studio shows
+this before you run.
+
+**Credentials vault.** Secrets entered in the UI are encrypted and stored under
+`ASHUB_VAULT_DIR` (default `/data/vault`, mounted from `./data`). Saved
+credentials are reusable across ingestion runs and LLM calls.
+
+* `ASHUB_VAULT_KEY` — optional 32-byte master key (base64/hex). When unset, a
+  key file is generated at `<vault_dir>/vault.key` with `0600` permissions.
+* Records are encrypted with encrypt-then-MAC (HMAC-SHA256, HKDF-derived keys)
+  using only the standard library — no new dependencies in the hash-pinned
+  image. Tampered records fail closed rather than decrypting.
+* Secrets are never returned by the list API and are scrubbed from job/error
+  messages.
+
+**OpenAI-compatible LLM endpoints.** Besides the 8 built-in providers, the LLM
+Endpoints tab can add any `/v1`-style endpoint (vLLM, Ollama's OpenAI layer,
+OpenRouter, LiteLLM proxies, Azure gateways): enter a base URL + optional API
+key, **fetch the model list from the endpoint**, pick a model, save it to the
+vault, and set it as the platform default.
+
 ### Ingestion, MCP tools and LLM endpoints in the Studio
 
 The **Enrich** workspace has three tabs for this:

package/explorer/src/workspaces/IngestWorkspace/IngestWorkspace.tsx

@@ -1,33 +1,39 @@
 import { useEffect, useRef, useState } from "react";
 import {
   Database, Plug, CheckCircle2, AlertCircle, Loader2, FileText, Globe,
-  Boxes, Cloud, Server, Play,
+  Boxes, Cloud, Server, Play, ChevronDown, KeyRound, Save, Trash2, Lock,
 } from "lucide-react";
 
-type SourceField = {
-  name: string;
-  label: string;
-  required: boolean;
-  secret?: boolean;
-  boolean?: boolean;
+type ConnField = {
+  name: string; label: string; required?: boolean;
+  secret?: boolean; boolean?: boolean;
 };
 
-type SourceDef = {
-  kind: string;
-  label: string;
-  fields: SourceField[];
-  hint: string;
+type Connector = {
+  kind: string; label: string; credential_hint: string | null;
+  env_fallback: string | null; source_label: string; source_placeholder: string;
+  optional_fields: ConnField[]; secret_fields: string[];
+  extra_dependency: string | null;
 };
 
+type Category = { category: string; connectors: Connector[] };
+type Credential = {
+  id: string; kind: string; label: string; metadata: Record<string, unknown>;
+  field_names: string[]; updated_at: number;
+};
 type Toast = { id: number; type: "success" | "error"; text: string };
+type FieldValues = Record<string, string | boolean>;
 
 const KIND_ICONS: Record<string, typeof Database> = {
-  file: FileText, databricks: Boxes, sap: Server, snowflake: Cloud,
-  salesforce: Cloud, rest: Plug, web: Globe,
+  databricks: Boxes, snowflake: Cloud, bigquery: Cloud, redshift: Cloud,
+  sql: Database, duckdb: Database, mongo: Database, cassandra: Database,
+  elastic: Database, salesforce: Cloud, sap: Server, servicenow: Server,
+  powerbi: Cloud, sharepoint: Cloud, file: FileText, parquet: FileText,
+  xml: FileText, cloudstorage: Cloud, gdrive: Cloud, rest: Plug,
+  web: Globe, feed: Globe, repo: Globe, email: Globe,
+  huggingface: Globe, mcp: Plug,
 };
 
-type FieldValues = Record<string, string | boolean>;
-
 function nestedSet(obj: Record<string, unknown>, path: string, value: unknown) {
   const parts = path.split(".");
   let cur = obj;
@@ -39,9 +45,14 @@ function nestedSet(obj: Record<string, unknown>, path: string, value: unknown) {
 }
 
 export function IngestWorkspace() {
-  const [sources, setSources] = useState<SourceDef[]>([]);
-  const [activeKind, setActiveKind] = useState<string | null>(null);
+  const [categories, setCategories] = useState<Category[]>([]);
+  const [active, setActive] = useState<Connector | null>(null);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const [credentials, setCredentials] = useState<Credential[]>([]);
+  const [credentialId, setCredentialId] = useState("");
   const [values, setValues] = useState<FieldValues>({});
+  const [saveToVault, setSaveToVault] = useState(true);
+  const [vaultName, setVaultName] = useState("");
   const [sourceRef, setSourceRef] = useState("");
   const [extract, setExtract] = useState(true);
   const [validating, setValidating] = useState(false);
@@ -51,28 +62,90 @@ export function IngestWorkspace() {
   const [toasts, setToasts] = useState<Toast[]>([]);
   const pollRef = useRef<number | null>(null);
 
-  useEffect(() => {
-    fetch("/api/ingest/sources").then((r) => r.json()).then((d) => {
-      setSources(d.sources ?? []);
-      if (d.sources?.length) setActiveKind((k) => k ?? d.sources[0].kind);
-    }).catch(() => {});
-    return () => { if (pollRef.current) window.clearInterval(pollRef.current); };
-  }, []);
-
-  const active = sources.find((s) => s.kind === activeKind) ?? null;
-
   function showToast(type: Toast["type"], text: string) {
     const id = Date.now();
     setToasts((p) => [...p, { id, type, text }]);
     setTimeout(() => setToasts((p) => p.filter((t) => t.id !== id)), 6000);
   }
 
-  function selectKind(kind: string) {
-    setActiveKind(kind);
+  async function loadCredentials() {
+    try {
+      const r = await fetch("/api/vault/credentials?kind=source");
+      const d = await r.json();
+      setCredentials(d.credentials ?? []);
+    } catch { /* ignore */ }
+  }
+
+  useEffect(() => {
+    fetch("/api/ingest/sources").then((r) => r.json()).then((d) => {
+      const cats: Category[] = d.categories ?? [];
+      setCategories(cats);
+      const first = cats[0]?.connectors[0];
+      if (first) setActive(first);
+    }).catch(() => {});
+    loadCredentials();
+    return () => { if (pollRef.current) window.clearInterval(pollRef.current); };
+  }, []);
+
+  function selectConnector(c: Connector) {
+    setActive(c);
+    setPickerOpen(false);
     setValues({});
     setSourceRef("");
     setValidation(null);
     setJob(null);
+    setCredentialId("");
+    setVaultName(`${c.kind}-credentials`);
+  }
+
+  function applyCredential(id: string) {
+    setCredentialId(id);
+    setValidation(null);
+  }
+
+  function buildOptions(): Record<string, unknown> {
+    const options: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(values)) {
+      if (v !== "" && v !== false && v !== undefined) nestedSet(options, k, v);
+    }
+    return options;
+  }
+
+  async function handleSaveCredential() {
+    if (!active) return;
+    const fields: Record<string, string> = {};
+    for (const [k, v] of Object.entries(values)) {
+      if (typeof v === "string" && v.trim()) fields[k] = v;
+    }
+    if (Object.keys(fields).length === 0) {
+      showToast("error", "Enter credential fields before saving");
+      return;
+    }
+    try {
+      const r = await fetch("/api/vault/credentials", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ id: vaultName.trim() || `${active.kind}-credentials`,
+                               kind: "source", label: `${active.label} credentials`, fields }),
+      });
+      if (!r.ok) throw new Error((await r.json()).detail ?? `HTTP ${r.status}`);
+      showToast("success", "Saved to vault");
+      await loadCredentials();
+      setCredentialId(vaultName.trim() || `${active.kind}-credentials`);
+    } catch (e) {
+      showToast("error", e instanceof Error ? e.message : "Save failed");
+    }
+  }
+
+  async function handleDeleteCredential(id: string) {
+    try {
+      const r = await fetch(`/api/vault/credentials/${encodeURIComponent(id)}`, { method: "DELETE" });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      showToast("success", "Credential deleted");
+      if (credentialId === id) setCredentialId("");
+      await loadCredentials();
+    } catch (e) {
+      showToast("error", e instanceof Error ? e.message : "Delete failed");
+    }
   }
 
   async function handleValidate() {
@@ -80,18 +153,12 @@ export function IngestWorkspace() {
     setValidating(true);
     setValidation(null);
     try {
-      const options: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(values)) {
-        if (v !== "" && v !== false) nestedSet(options, k, v);
-      }
-      if (active.kind === "sap" && options["service"] === undefined) delete options["service"];
       const res = await fetch("/api/ingest/validate", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ kind: active.kind, options }),
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ kind: active.kind, credential_id: credentialId || null, options: buildOptions() }),
       });
       const data = await res.json();
-      setValidation({ ok: !!data.ok, detail: data.detail ?? data.detail?.toString() ?? "Unknown response" });
+      setValidation({ ok: !!data.ok, detail: data.detail ?? "Unknown response" });
     } catch (e) {
       setValidation({ ok: false, detail: e instanceof Error ? e.message : "Validation failed" });
     } finally {
@@ -100,20 +167,26 @@ export function IngestWorkspace() {
   }
 
   async function handleRun() {
-    if (!active || !sourceRef.trim()) return;
+    if (!active) return;
+    if (saveToVault && credentialId === "") {
+      const fields: Record<string, string> = {};
+      for (const [k, v] of Object.entries(values)) {
+        if (typeof v === "string" && v.trim()) fields[k] = v;
+      }
+      if (Object.keys(fields).length > 0) await handleSaveCredential();
+    }
     setRunning(true);
     setJob({ status: "queued", stage: "queued", progress: 0, message: "Starting…" });
     try {
-      const options: Record<string, unknown> = {};
-      for (const [k, v] of Object.entries(values)) {
-        if (v !== "" && v !== false) nestedSet(options, k, v);
-      }
       const res = await fetch("/api/ingest/run", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ kind: active.kind, source: sourceRef.trim(), options, extract }),
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          kind: active.kind, source: sourceRef.trim(),
+          credential_id: credentialId || null,
+          options: buildOptions(), extract,
+        }),
       });
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      if (!res.ok) throw new Error((await res.json()).detail ?? `HTTP ${res.status}`);
       const { job_id } = await res.json();
       pollRef.current = window.setInterval(async () => {
         try {
@@ -121,27 +194,25 @@ export function IngestWorkspace() {
           if (!st.ok) return;
           const data = await st.json();
           setJob(data);
-          if (data.status === "done") {
-            window.clearInterval(pollRef.current!); pollRef.current = null;
-            setRunning(false);
-            showToast("success", data.message);
-          } else if (data.status === "error") {
+          if (data.status === "done" || data.status === "error") {
             window.clearInterval(pollRef.current!); pollRef.current = null;
             setRunning(false);
-            showToast("error", data.message);
+            showToast(data.status === "done" ? "success" : "error", data.message);
           }
         } catch { /* transient */ }
       }, 1000);
     } catch (e) {
-      setRunning(false);
-      setJob(null);
+      setRunning(false); setJob(null);
       showToast("error", e instanceof Error ? e.message : "Failed to start ingestion");
     }
   }
 
+  const ActiveIcon = active ? (KIND_ICONS[active.kind] ?? Database) : Database;
+  const vaultForKind = credentials.filter((c) => c.id.startsWith(active?.kind ?? "___"));
+
   return (
     <div className="ws-page ws-scroll">
-      <div className="ws-padded" style={{ display: "flex", flexDirection: "column", gap: 24, maxWidth: 980, margin: "0 auto", width: "100%" }}>
+      <div className="ws-padded" style={{ display: "flex", flexDirection: "column", gap: 24, maxWidth: 1040, margin: "0 auto", width: "100%" }}>
         {/* Header */}
         <div style={{ display: "flex", alignItems: "center", gap: 14 }}>
           <div style={{ width: 42, height: 42, borderRadius: 13, background: "var(--ws-accent-soft)", border: "1px solid var(--ws-border-strong)", display: "grid", placeItems: "center", color: "var(--ws-accent)", flexShrink: 0 }}>
@@ -149,111 +220,214 @@ export function IngestWorkspace() {
           </div>
           <div>
             <h2 className="ws-title" style={{ fontSize: 18 }}>Ingest from Source Systems</h2>
-            <div className="ws-body" style={{ marginTop: 2 }}>Connect Databricks, SAP, Snowflake, Salesforce, REST APIs, web pages or files — extraction runs automatically and the graph loads into the Studio.</div>
+            <div className="ws-body" style={{ marginTop: 2 }}>
+              {categories.reduce((n, c) => n + c.connectors.length, 0)} connectors across{" "}
+              {categories.length} categories. Credentials save to the encrypted vault and can be reused.
+            </div>
           </div>
         </div>
 
-        <div style={{ display: "grid", gridTemplateColumns: "280px 1fr", gap: 18, alignItems: "start" }}>
-          {/* Source picker */}
-          <div className="ws-card" style={{ padding: 18, display: "flex", flexDirection: "column", gap: 8 }}>
-            <div className="ws-label">Source type</div>
-            {sources.map((s) => {
-              const Icon = KIND_ICONS[s.kind] ?? Database;
-              return (
-                <button key={s.kind} className="ws-btn" data-active={activeKind === s.kind}
-                  onClick={() => selectKind(s.kind)}
-                  style={{ justifyContent: "flex-start", fontSize: 13 }}>
-                  <Icon size={15} /> {s.label}
-                </button>
-              );
-            })}
-          </div>
+        {/* Connector picker */}
+        <div className="ws-card" style={{ padding: 18, position: "relative" }}>
+          <div className="ws-label">Connector</div>
+          <button className="ws-btn" onClick={() => setPickerOpen((v) => !v)}
+            style={{ width: "100%", justifyContent: "space-between", fontSize: 13 }}>
+            <span style={{ display: "flex", alignItems: "center", gap: 8 }}>
+              <ActiveIcon size={15} /> {active?.label ?? "Select a connector…"}
+            </span>
+            <ChevronDown size={15} />
+          </button>
 
-          {/* Connection form */}
-          <div className="ws-card" style={{ padding: 24, display: "flex", flexDirection: "column", gap: 16 }}>
-            {!active ? <div className="ws-body">Loading sources…</div> : (
-              <>
-                <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
-                  <Plug size={16} color="var(--ws-accent)" />
-                  <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>{active.label} connection</div>
+          {pickerOpen ? (
+            <div style={{
+              position: "absolute", top: "100%", left: 18, right: 18, zIndex: 50, marginTop: 6,
+              background: "#fff", border: "1px solid var(--ws-border)", borderRadius: "var(--ws-radius)",
+              boxShadow: "0 12px 32px rgba(0,0,0,0.18)", maxHeight: 420, overflowY: "auto", padding: 10,
+            }}>
+              {categories.map((cat) => (
+                <div key={cat.category} style={{ marginBottom: 8 }}>
+                  <div className="ws-label" style={{ padding: "6px 8px", margin: 0, opacity: 0.75 }}>{cat.category}</div>
+                  {cat.connectors.map((c) => {
+                    const Icon = KIND_ICONS[c.kind] ?? Database;
+                    return (
+                      <button key={c.kind} className="ws-btn" data-active={active?.kind === c.kind}
+                        onClick={() => selectConnector(c)}
+                        style={{ width: "100%", justifyContent: "flex-start", fontSize: 12.5, marginBottom: 2 }}>
+                        <Icon size={14} />
+                        <span style={{ flex: 1, textAlign: "left" }}>{c.label}</span>
+                        {c.extra_dependency ? (
+                          <span title={`Extra dependency: ${c.extra_dependency}`}
+                            style={{ fontSize: 10, opacity: 0.6, color: "#c9a227" }}>dep</span>
+                        ) : null}
+                      </button>
+                    );
+                  })}
                 </div>
-                <div className="ws-body" style={{ fontSize: 12 }}>{active.hint}</div>
+              ))}
+            </div>
+          ) : null}
 
-                <div>
-                  <label className="ws-label">{active.kind === "file" ? "File path" : active.kind === "web" || active.kind === "rest" ? "URL" : active.kind === "databricks" || active.kind === "snowflake" ? "Table (or SQL query)" : active.kind === "sap" ? "Entity set" : "SObject"}</label>
+          {active ? (
+            <div style={{ marginTop: 12, display: "flex", flexDirection: "column", gap: 4 }}>
+              {active.credential_hint ? (
+                <div className="ws-body" style={{ fontSize: 12 }}>
+                  <KeyRound size={12} style={{ verticalAlign: -2, marginRight: 6 }} />
+                  Credentials: {active.credential_hint}
+                </div>
+              ) : null}
+              {active.env_fallback ? (
+                <div className="ws-body" style={{ fontSize: 11, opacity: 0.75 }}>
+                  Env fallback: <code>{active.env_fallback}</code>
+                </div>
+              ) : null}
+              {active.extra_dependency ? (
+                <div style={{ fontSize: 11, color: "#a8791f" }}>
+                  Requires extra dependency: <code>{active.extra_dependency}</code>
+                </div>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+
+        {active ? (
+          <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 18, alignItems: "start" }}>
+            {/* Credentials card */}
+            <div className="ws-card" style={{ padding: 22, display: "flex", flexDirection: "column", gap: 14 }}>
+              <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+                <Lock size={16} color="var(--ws-accent)" />
+                <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Credentials</div>
+              </div>
+
+              <div>
+                <label className="ws-label">Saved credential (from vault)</label>
+                <select className="ws-input" style={{ width: "100%" }} value={credentialId}
+                  onChange={(e) => applyCredential(e.target.value)} disabled={running}>
+                  <option value="">— none (enter below / use env) —</option>
+                  {credentials.map((c) => (
+                    <option key={c.id} value={c.id}>{c.label} ({c.id})</option>
+                  ))}
+                </select>
+                {vaultForKind.length > 0 ? (
+                  <div className="ws-body" style={{ fontSize: 11, marginTop: 4 }}>
+                    {vaultForKind.length} credential(s) saved for {active.kind}
+                  </div>
+                ) : null}
+              </div>
+
+              {active.optional_fields.filter((f) => !["as_query", "include_subfolders", "download", "as_file", "respect_robots", "unread_only"].includes(f.name)).map((f) => (
+                <div key={f.name}>
+                  <label className="ws-label">{f.label}{f.required ? " *" : ""}</label>
                   <input className="ws-input" style={{ width: "100%" }}
-                    value={sourceRef}
-                    onChange={(e) => setSourceRef(e.target.value)}
-                    placeholder={active.kind === "file" ? "/data/documents/report.txt" : active.kind === "databricks" ? "catalog.schema.table" : active.kind === "snowflake" ? "DATABASE.SCHEMA.TABLE" : active.kind === "sap" ? "SalesOrderSet" : active.kind === "salesforce" ? "Account" : "https://…"}
+                    type={f.secret ? "password" : "text"}
+                    value={String(values[f.name] ?? "")}
+                    onChange={(e) => setValues((v) => ({ ...v, [f.name]: e.target.value }))}
                     disabled={running} />
                 </div>
+              ))}
 
-                {active.fields.filter((f) => f.name !== "source").map((f) => (
-                  <div key={f.name}>
-                    <label className="ws-label">{f.label}{f.required ? " *" : ""}</label>
-                    {f.boolean ? (
-                      <button className={`ws-btn ${values[f.name] ? "ws-btn--primary" : "ws-btn--ghost"}`}
-                        onClick={() => setValues((v) => ({ ...v, [f.name]: !v[f.name] }))}
-                        style={{ justifyContent: "center" }}>
-                        {values[f.name] ? "Yes" : "No"}
-                      </button>
-                    ) : (
-                      <input className="ws-input" style={{ width: "100%" }}
-                        type={f.secret ? "password" : "text"}
-                        value={String(values[f.name] ?? "")}
-                        onChange={(e) => setValues((v) => ({ ...v, [f.name]: e.target.value }))}
-                        disabled={running} />
-                    )}
-                  </div>
-                ))}
+              {active.optional_fields.filter((f) => f.boolean).length > 0 ? (
+                <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
+                  {active.optional_fields.filter((f) => f.boolean).map((f) => (
+                    <button key={f.name} className={`ws-btn ${values[f.name] ? "ws-btn--primary" : "ws-btn--ghost"}`}
+                      onClick={() => setValues((v) => ({ ...v, [f.name]: !v[f.name] }))}
+                      disabled={running} style={{ fontSize: 11.5 }}>
+                      {f.label}: {values[f.name] ? "Yes" : "No"}
+                    </button>
+                  ))}
+                </div>
+              ) : null}
 
-                {/* Extraction toggle */}
-                <button className={`ws-btn ${extract ? "ws-btn--primary" : "ws-btn--ghost"}`}
-                  onClick={() => setExtract((v) => !v)} disabled={running}
-                  style={{ justifyContent: "center" }}>
-                  {extract ? "Extraction ON — build entities & relations" : "Extraction OFF — documents only"}
+              <div style={{ display: "flex", gap: 8, alignItems: "flex-end" }}>
+                <div style={{ flex: 1 }}>
+                  <label className="ws-label">Save as (vault name)</label>
+                  <input className="ws-input" style={{ width: "100%" }} value={vaultName}
+                    onChange={(e) => setVaultName(e.target.value)} disabled={running} />
+                </div>
+                <button className="ws-btn ws-btn--ghost" onClick={handleSaveCredential}
+                  disabled={running} style={{ whiteSpace: "nowrap" }}>
+                  <Save size={14} /> Save
                 </button>
+              </div>
 
-                {/* Validation result */}
-                {validation ? (
-                  <div style={{ display: "flex", alignItems: "center", gap: 8, padding: "10px 14px", borderRadius: "var(--ws-radius-sm)", border: `1px solid ${validation.ok ? "rgba(76,195,138,0.4)" : "rgba(236,35,21,0.4)"}`, background: "rgba(255,255,255,0.6)" }}>
-                    {validation.ok ? <CheckCircle2 size={15} color="#1f9d5f" /> : <AlertCircle size={15} color="#ec2315" />}
-                    <span style={{ fontSize: 13, color: "var(--ws-text)" }}>{validation.detail}</span>
-                  </div>
-                ) : null}
-
-                {/* Progress */}
-                {job ? (
-                  <div style={{ display: "flex", flexDirection: "column", gap: 8, padding: "14px 16px", borderRadius: "var(--ws-radius-sm)", background: "rgba(0,0,0,0.16)", border: "1px solid var(--ws-border)" }}>
-                    <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
-                      {job.status === "running" || job.status === "queued" ? <Loader2 size={15} className="ws-spin" color="var(--ws-accent)" /> : job.status === "done" ? <CheckCircle2 size={15} color="#1f9d5f" /> : <AlertCircle size={15} color="#ec2315" />}
-                      <span style={{ fontSize: 13, color: "var(--ws-text)", fontWeight: 600 }}>{job.message}</span>
-                    </div>
-                    <div style={{ height: 6, borderRadius: 3, background: "rgba(0,0,0,0.25)", overflow: "hidden" }}>
-                      <div style={{ width: `${job.progress}%`, height: "100%", background: job.status === "error" ? "#ec2315" : "var(--ws-accent)", transition: "width 400ms ease" }} />
+              {credentials.length > 0 ? (
+                <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
+                  <div className="ws-label" style={{ marginBottom: 2 }}>Vault entries</div>
+                  {credentials.map((c) => (
+                    <div key={c.id} style={{ display: "flex", alignItems: "center", gap: 8, fontSize: 12 }}>
+                      <CheckCircle2 size={12} color="#1f9d5f" />
+                      <span style={{ flex: 1, color: "var(--ws-text)" }}>{c.label}</span>
+                      <button className="ws-btn ws-btn--ghost" style={{ padding: "2px 8px" }}
+                        onClick={() => handleDeleteCredential(c.id)} title="Delete">
+                        <Trash2 size={12} />
+                      </button>
                     </div>
-                    <div className="ws-body" style={{ fontSize: 11 }}>Stage: {job.stage}</div>
-                  </div>
-                ) : null}
+                  ))}
+                </div>
+              ) : null}
+            </div>
+
+            {/* Run card */}
+            <div className="ws-card" style={{ padding: 22, display: "flex", flexDirection: "column", gap: 14 }}>
+              <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+                <Play size={16} color="var(--ws-accent)" />
+                <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Run ingestion</div>
+              </div>
+
+              <div>
+                <label className="ws-label">{active.source_label}</label>
+                <input className="ws-input" style={{ width: "100%" }} value={sourceRef}
+                  onChange={(e) => setSourceRef(e.target.value)}
+                  placeholder={active.source_placeholder} disabled={running} />
+              </div>
+
+              <button className={`ws-btn ${extract ? "ws-btn--primary" : "ws-btn--ghost"}`}
+                onClick={() => setExtract((v) => !v)} disabled={running}
+                style={{ justifyContent: "center", fontSize: 12 }}>
+                {extract ? "Extraction ON — build entities & relations" : "Extraction OFF — documents only"}
+              </button>
 
-                <div style={{ display: "flex", gap: 10 }}>
-                  <button className="ws-btn ws-btn--ghost" onClick={handleValidate}
-                    disabled={validating || running || !sourceRef.trim()}
-                    style={{ flex: 1, justifyContent: "center" }}>
-                    {validating ? <Loader2 size={15} className="ws-spin" /> : <Plug size={15} />} Test connection
-                  </button>
-                  <button className="ws-btn" onClick={handleRun}
-                    disabled={running || validating || !sourceRef.trim()}
-                    style={{ flex: 2, justifyContent: "center", background: "var(--ws-accent-soft)", borderColor: "var(--ws-accent)", color: "var(--ws-accent)" }}>
-                    {running ? <><Loader2 size={15} className="ws-spin" />Ingesting…</> : <><Play size={15} />Run ingestion</>}
-                  </button>
+              <button className={`ws-btn ${saveToVault ? "ws-btn--primary" : "ws-btn--ghost"}`}
+                onClick={() => setSaveToVault((v) => !v)} disabled={running}
+                style={{ justifyContent: "center", fontSize: 12 }}>
+                <Lock size={13} /> {saveToVault ? "Auto-save credentials to vault" : "Don't save credentials"}
+              </button>
+
+              {validation ? (
+                <div style={{ display: "flex", alignItems: "center", gap: 8, padding: "10px 14px", borderRadius: "var(--ws-radius-sm)", border: `1px solid ${validation.ok ? "rgba(76,195,138,0.4)" : "rgba(236,35,21,0.4)"}`, background: "rgba(255,255,255,0.6)" }}>
+                  {validation.ok ? <CheckCircle2 size={15} color="#1f9d5f" /> : <AlertCircle size={15} color="#ec2315" />}
+                  <span style={{ fontSize: 12.5, color: "var(--ws-text)" }}>{validation.detail}</span>
+                </div>
+              ) : null}
+
+              {job ? (
+                <div style={{ display: "flex", flexDirection: "column", gap: 8, padding: "14px 16px", borderRadius: "var(--ws-radius-sm)", background: "rgba(0,0,0,0.16)", border: "1px solid var(--ws-border)" }}>
+                  <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+                    {job.status === "running" || job.status === "queued"
+                      ? <Loader2 size={15} className="ws-spin" color="var(--ws-accent)" />
+                      : job.status === "done" ? <CheckCircle2 size={15} color="#1f9d5f" /> : <AlertCircle size={15} color="#ec2315" />}
+                    <span style={{ fontSize: 12.5, color: "var(--ws-text)", fontWeight: 600 }}>{job.message}</span>
+                  </div>
+                  <div style={{ height: 6, borderRadius: 3, background: "rgba(0,0,0,0.25)", overflow: "hidden" }}>
+                    <div style={{ width: `${job.progress}%`, height: "100%", background: job.status === "error" ? "#ec2315" : "var(--ws-accent)", transition: "width 400ms ease" }} />
+                  </div>
+                  <div className="ws-body" style={{ fontSize: 11 }}>Stage: {job.stage}</div>
                 </div>
-              </>
-            )}
+              ) : null}
+
+              <div style={{ display: "flex", gap: 10 }}>
+                <button className="ws-btn ws-btn--ghost" onClick={handleValidate}
+                  disabled={validating || running} style={{ flex: 1, justifyContent: "center" }}>
+                  {validating ? <Loader2 size={15} className="ws-spin" /> : <Plug size={15} />} Test connection
+                </button>
+                <button className="ws-btn" onClick={handleRun} disabled={running || validating}
+                  style={{ flex: 2, justifyContent: "center", background: "var(--ws-accent-soft)", borderColor: "var(--ws-accent)", color: "var(--ws-accent)" }}>
+                  {running ? <><Loader2 size={15} className="ws-spin" />Ingesting…</> : <><Play size={15} />Run ingestion</>}
+                </button>
+              </div>
+            </div>
           </div>
-        </div>
+        ) : null}
 
-        {/* Toasts */}
         <div style={{ position: "fixed", bottom: 28, right: 28, display: "flex", flexDirection: "column", gap: 10, zIndex: 1000 }}>
           {toasts.map((t) => (
             <div key={t.id} className="ws-animate-in" style={{ display: "flex", alignItems: "center", gap: 10, padding: "13px 18px", borderRadius: "var(--ws-radius-sm)", background: "rgba(255,255,255,0.96)", border: `1px solid ${t.type === "success" ? "rgba(76,195,138,0.4)" : "rgba(255,123,114,0.4)"}`, boxShadow: "0 8px 24px rgba(0,0,0,0.5)", backdropFilter: "blur(12px)" }}>
@@ -265,4 +439,4 @@ export function IngestWorkspace() {
       </div>
     </div>
   );
-}
+}

package/explorer/src/workspaces/LlmSettingsWorkspace/LlmSettingsWorkspace.tsx

@@ -1,15 +1,15 @@
 import { useEffect, useState } from "react";
 import {
-  Sparkles, CheckCircle2, AlertCircle, Loader2, Send, Info,
+  Sparkles, CheckCircle2, AlertCircle, Loader2, Send, Info, Save, Plus, Trash2,
 } from "lucide-react";
 
 type Provider = {
   name: string; label: string; env_var: string | null;
   models: string[]; configured: boolean; env_value_hint: string | null;
+  type: "builtin" | "custom"; base_url?: string;
 };
 
 type UsageRow = { task: string; when: string; where: string };
-
 type Toast = { id: number; type: "success" | "error"; text: string };
 
 export function LlmSettingsWorkspace() {
@@ -17,18 +17,19 @@ export function LlmSettingsWorkspace() {
   const [usage, setUsage] = useState<UsageRow[]>([]);
   const [selected, setSelected] = useState<Provider | null>(null);
   const [model, setModel] = useState("");
+  const [fetchedModels, setFetchedModels] = useState<string[]>([]);
   const [testing, setTesting] = useState(false);
+  const [fetching, setFetching] = useState(false);
   const [result, setResult] = useState<{ ok: boolean; detail: string; model?: string } | null>(null);
-  const [toasts, setToasts] = useState<Toast[]>([]);
 
-  useEffect(() => {
-    fetch("/api/llm/status").then((r) => r.json()).then((d) => {
-      setProviders(d.providers ?? []);
-      setUsage(d.usage ?? []);
-      const first = (d.providers ?? []).find((p: Provider) => p.configured) ?? d.providers?.[0];
-      if (first) { setSelected(first); setModel(first.models[0] ?? ""); }
-    }).catch(() => {});
-  }, []);
+  // custom endpoint form
+  const [showAdd, setShowAdd] = useState(false);
+  const [epName, setEpName] = useState("");
+  const [epLabel, setEpLabel] = useState("");
+  const [epBaseUrl, setEpBaseUrl] = useState("");
+  const [epKey, setEpKey] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [toasts, setToasts] = useState<Toast[]>([]);
 
   function showToast(type: Toast["type"], text: string) {
     const id = Date.now();
@@ -36,30 +37,108 @@ export function LlmSettingsWorkspace() {
     setTimeout(() => setToasts((p) => p.filter((t) => t.id !== id)), 5000);
   }
 
+  async function loadStatus() {
+    try {
+      const r = await fetch("/api/llm/status");
+      const d = await r.json();
+      setProviders(d.providers ?? []);
+      setUsage(d.usage ?? []);
+      const first = (d.providers ?? []).find((p: Provider) => p.configured) ?? d.providers?.[0];
+      if (first) { setSelected((s) => s ?? first); setModel((m) => m || first.models[0] || ""); }
+    } catch { /* ignore */ }
+  }
+
+  useEffect(() => { loadStatus(); }, []);
+
+  function selectProvider(p: Provider) {
+    setSelected(p);
+    setResult(null);
+    setFetchedModels([]);
+    setModel(p.models[0] ?? "");
+  }
+
+  async function handleFetchModels() {
+    if (!selected) return;
+    setFetching(true);
+    try {
+      const body = selected.type === "custom"
+        ? { provider: "custom", credential_id: selected.name }
+        : { provider: selected.name };
+      const r = await fetch("/api/llm/fetch_models", {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+      });
+      const d = await r.json();
+      if (d.ok) {
+        setFetchedModels(d.models ?? []);
+        if (d.models?.length && !d.models.includes(model)) setModel(d.models[0]);
+        showToast("success", `Found ${d.models?.length ?? 0} models`);
+      } else {
+        showToast("error", d.detail ?? "Fetch failed");
+      }
+    } catch (e) {
+      showToast("error", e instanceof Error ? e.message : "Fetch failed");
+    } finally { setFetching(false); }
+  }
+
   async function handleTest() {
     if (!selected) return;
-    setTesting(true);
-    setResult(null);
+    setTesting(true); setResult(null);
     try {
-      const res = await fetch("/api/llm/test", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ provider: selected.name, model }),
+      const body = selected.type === "custom"
+        ? { provider: "custom", credential_id: selected.name, model }
+        : { provider: selected.name, model };
+      const r = await fetch("/api/llm/test", {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
       });
-      const data = await res.json();
-      setResult(data);
-      showToast(data.ok ? "success" : "error",
-        data.ok ? `${selected.label} responded` : `${selected.label}: unavailable`);
+      const d = await r.json();
+      setResult(d);
+      showToast(d.ok ? "success" : "error", d.ok ? `${selected.label} responded` : `${selected.label}: unavailable`);
     } catch (e) {
       setResult({ ok: false, detail: e instanceof Error ? e.message : "Test failed" });
-    } finally {
-      setTesting(false);
+    } finally { setTesting(false); }
+  }
+
+  async function handleSaveEndpoint() {
+    if (!epName.trim() || !epBaseUrl.trim()) {
+      showToast("error", "Name and base URL are required");
+      return;
+    }
+    setSaving(true);
+    try {
+      const r = await fetch("/api/llm/save", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name: epName.trim(), label: epLabel.trim() || epName.trim(),
+                               base_url: epBaseUrl.trim(), api_key: epKey,
+                               default_model: model }),
+      });
+      const d = await r.json();
+      if (!r.ok) throw new Error(d.detail ?? `HTTP ${r.status}`);
+      showToast("success", "Endpoint saved to vault");
+      setShowAdd(false); setEpName(""); setEpLabel(""); setEpBaseUrl(""); setEpKey("");
+      await loadStatus();
+    } catch (e) {
+      showToast("error", e instanceof Error ? e.message : "Save failed");
+    } finally { setSaving(false); }
+  }
+
+  async function handleDeleteProvider(p: Provider) {
+    if (p.type !== "custom") return;
+    try {
+      const r = await fetch(`/api/vault/credentials/${encodeURIComponent(p.name)}`, { method: "DELETE" });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      showToast("success", `${p.label} removed`);
+      if (selected?.name === p.name) setSelected(null);
+      await loadStatus();
+    } catch (e) {
+      showToast("error", e instanceof Error ? e.message : "Delete failed");
     }
   }
 
+  const modelChoices = fetchedModels.length > 0 ? fetchedModels : (selected?.models ?? []);
+
   return (
     <div className="ws-page ws-scroll">
-      <div className="ws-padded" style={{ display: "flex", flexDirection: "column", gap: 24, maxWidth: 980, margin: "0 auto", width: "100%" }}>
+      <div className="ws-padded" style={{ display: "flex", flexDirection: "column", gap: 24, maxWidth: 1020, margin: "0 auto", width: "100%" }}>
         {/* Header */}
         <div style={{ display: "flex", alignItems: "center", gap: 14 }}>
           <div style={{ width: 42, height: 42, borderRadius: 13, background: "var(--ws-accent-soft)", border: "1px solid var(--ws-border-strong)", display: "grid", placeItems: "center", color: "var(--ws-accent)", flexShrink: 0 }}>
@@ -68,12 +147,12 @@ export function LlmSettingsWorkspace() {
           <div>
             <h2 className="ws-title" style={{ fontSize: 18 }}>LLM Endpoints</h2>
             <div className="ws-body" style={{ marginTop: 2 }}>
-              Where the platform uses language models, which are configured in this deployment, and a live test for each.
+              Built-in providers, OpenAI-compatible <code>/v1</code> endpoints (vLLM, Ollama, OpenRouter, gateways), and where the platform uses LLMs.
             </div>
           </div>
         </div>
 
-        {/* Where LLMs are used — informational */}
+        {/* Where LLMs are used */}
         <div className="ws-card" style={{ padding: 24, display: "flex", flexDirection: "column", gap: 12 }}>
           <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
             <Info size={16} color="var(--ws-accent)" />
@@ -86,28 +165,66 @@ export function LlmSettingsWorkspace() {
               <div className="ws-body" style={{ fontSize: 11, marginTop: 2, fontFamily: "var(--ws-mono, monospace)", opacity: 0.7 }}>{u.where}</div>
             </div>
           ))}
-          <div className="ws-body" style={{ fontSize: 12 }}>
-            Credentials are read from environment variables when the Studio starts — set them in <code style={{ color: "var(--ws-accent)" }}>docker-compose.yml</code> (or <code style={{ color: "var(--ws-accent)" }}>.env</code>) and restart.
-          </div>
         </div>
 
-        {/* Provider grid */}
+        {/* Providers */}
         <div className="ws-card" style={{ padding: 24, display: "flex", flexDirection: "column", gap: 16 }}>
-          <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Configured providers</div>
-          <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(210px, 1fr))", gap: 12 }}>
+          <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+            <div style={{ color: "var(--ws-text)", fontWeight: 700, fontSize: 14 }}>Providers & endpoints</div>
+            <button className="ws-btn ws-btn--ghost" style={{ fontSize: 12 }} onClick={() => setShowAdd((v) => !v)}>
+              <Plus size={14} /> Add OpenAI-compatible endpoint
+            </button>
+          </div>
+
+          {showAdd ? (
+            <div style={{ padding: 16, borderRadius: "var(--ws-radius-sm)", border: "1px solid var(--ws-border-strong)", background: "rgba(0,0,0,0.16)", display: "flex", flexDirection: "column", gap: 10 }}>
+              <div className="ws-label" style={{ margin: 0 }}>New endpoint (stored encrypted in the vault)</div>
+              <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 10 }}>
+                <div>
+                  <label className="ws-label">Name *</label>
+                  <input className="ws-input" style={{ width: "100%" }} value={epName}
+                    onChange={(e) => setEpName(e.target.value)} placeholder="local-vllm" />
+                </div>
+                <div>
+                  <label className="ws-label">Display label</label>
+                  <input className="ws-input" style={{ width: "100%" }} value={epLabel}
+                    onChange={(e) => setEpLabel(e.target.value)} placeholder="Local vLLM" />
+                </div>
+              </div>
+              <div>
+                <label className="ws-label">Base URL (OpenAI-compatible /v1) *</label>
+                <input className="ws-input" style={{ width: "100%" }} value={epBaseUrl}
+                  onChange={(e) => setEpBaseUrl(e.target.value)} placeholder="http://localhost:8000/v1" />
+              </div>
+              <div>
+                <label className="ws-label">API key (optional — many local endpoints need none)</label>
+                <input className="ws-input" style={{ width: "100%" }} type="password" value={epKey}
+                  onChange={(e) => setEpKey(e.target.value)} placeholder="sk-…" />
+              </div>
+              <button className="ws-btn" onClick={handleSaveEndpoint} disabled={saving}
+                style={{ justifyContent: "center", background: "var(--ws-accent-soft)", borderColor: "var(--ws-accent)", color: "var(--ws-accent)" }}>
+                {saving ? <Loader2 size={15} className="ws-spin" /> : <Save size={15} />} Save to vault
+              </button>
+            </div>
+          ) : null}
+
+          <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(220px, 1fr))", gap: 12 }}>
             {providers.map((p) => (
               <button key={p.name} className="ws-btn" data-active={selected?.name === p.name}
-                onClick={() => { setSelected(p); setModel(p.models[0] ?? ""); setResult(null); }}
+                onClick={() => selectProvider(p)}
                 style={{ flexDirection: "column", alignItems: "flex-start", gap: 6, padding: 14 }}>
                 <div style={{ display: "flex", alignItems: "center", gap: 8, width: "100%" }}>
-                  {p.configured
-                    ? <CheckCircle2 size={14} color="#1f9d5f" />
-                    : <AlertCircle size={14} color="#c9a227" />}
+                  {p.configured ? <CheckCircle2 size={14} color="#1f9d5f" /> : <AlertCircle size={14} color="#c9a227" />}
                   <span style={{ fontSize: 13, fontWeight: 700, color: "var(--ws-text)" }}>{p.label}</span>
+                  {p.type === "custom" ? (
+                    <span style={{ fontSize: 10, padding: "1px 6px", borderRadius: 6, background: "var(--ws-accent-soft)", color: "var(--ws-accent)" }}>custom</span>
+                  ) : null}
                 </div>
-                <div className="ws-body" style={{ fontSize: 11, textAlign: "left" }}>
-                  {p.env_var ? <code>{p.env_var}</code> : "no key needed"}
-                  {p.configured && p.env_value_hint ? ` · set (${p.env_value_hint})` : p.env_var ? " · not set" : ""}
+                <div className="ws-body" style={{ fontSize: 11, textAlign: "left", wordBreak: "break-all" }}>
+                  {p.type === "custom"
+                    ? p.base_url
+                    : p.env_var ? <code>{p.env_var}</code> : "no key needed"}
+                  {p.configured && p.env_value_hint ? ` · set (${p.env_value_hint})` : p.env_var && !p.configured ? " · not set" : ""}
                 </div>
               </button>
             ))}
@@ -116,11 +233,23 @@ export function LlmSettingsWorkspace() {
           {selected ? (
             <>
               <div>
-                <label className="ws-label">Model</label>
-                <select className="ws-input" style={{ width: "100%" }} value={model}
-                  onChange={(e) => setModel(e.target.value)}>
-                  {selected.models.map((m) => <option key={m} value={m}>{m}</option>)}
-                </select>
+                <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between" }}>
+                  <label className="ws-label">Model</label>
+                  <button className="ws-btn ws-btn--ghost" style={{ fontSize: 11, padding: "3px 10px" }}
+                    onClick={handleFetchModels} disabled={fetching || selected.type !== "custom"}>
+                    {fetching ? <Loader2 size={12} className="ws-spin" /> : null}
+                    {selected.type === "custom" ? "Fetch models from endpoint" : "Model list (built-in)"}
+                  </button>
+                </div>
+                {modelChoices.length > 0 ? (
+                  <select className="ws-input" style={{ width: "100%" }} value={model}
+                    onChange={(e) => setModel(e.target.value)}>
+                    {modelChoices.map((m) => <option key={m} value={m}>{m}</option>)}
+                  </select>
+                ) : (
+                  <input className="ws-input" style={{ width: "100%" }} value={model}
+                    onChange={(e) => setModel(e.target.value)} placeholder="model id" />
+                )}
               </div>
 
               <button className="ws-btn" onClick={handleTest} disabled={testing}
@@ -139,6 +268,13 @@ export function LlmSettingsWorkspace() {
                   <div className="ws-body" style={{ fontSize: 12, marginTop: 6, whiteSpace: "pre-wrap", fontFamily: "var(--ws-mono, monospace)" }}>{result.detail}</div>
                 </div>
               ) : null}
+
+              {selected.type === "custom" ? (
+                <button className="ws-btn ws-btn--ghost" style={{ fontSize: 12, color: "#a33" }}
+                  onClick={() => handleDeleteProvider(selected)}>
+                  <Trash2 size={13} /> Remove this endpoint
+                </button>
+              ) : null}
             </>
           ) : null}
         </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ltm-blueverse/alpha-semantic-hub",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Alpha Semantic Hub \u2014 Graph-Native Infrastructure for Context and Accountable AI Systems",
   "keywords": [
     "alpha-semantic-hub",