@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/OntologyWorkspace/api.ts

@@ -0,0 +1,164 @@
+import type {
+  AlignmentRelation,
+  AlignmentSuggestion,
+  OntologyAlignment,
+  OntologyEntry,
+  OntologyHealthResponse,
+  ShaclGenerateResponse,
+  ShaclShapesResponse,
+  ShaclValidationResponse,
+} from "./types";
+
+export type OntologyGraphNode = {
+  id: string;
+  type: string;
+  // Required: /graph always classifies. Optional here would make a producer
+  // that forgets read as a graph of read-only nodes rather than a type error.
+  entity_type: string;
+  content?: string;
+  properties?: Record<string, unknown>;
+};
+
+export type OntologyGraphEdge = {
+  id?: string;
+  source: string;
+  target: string;
+  type: string;
+  weight?: number;
+  properties?: Record<string, unknown>;
+};
+
+export type OntologyGraphResponse = {
+  uri: string;
+  nodes: OntologyGraphNode[];
+  edges: OntologyGraphEdge[];
+};
+
+export type OntologyEntityOwner = {
+  // Optional on purpose, unlike OntologyGraphNode.entity_type. There, a missing
+  // field degrades to a read-only node — benign. Here it would be read as an
+  // authoritative "nothing owns this entity", which now suppresses selection
+  // outright, so presence has to be checked rather than assumed.
+  owning_ontology?: string | null;
+};
+
+async function parseResponse<T>(response: Response): Promise<T> {
+  if (!response.ok) {
+    let detail = `Request failed with status ${response.status}`;
+    try {
+      const body = await response.json();
+      detail = body.detail || detail;
+    } catch {
+      // Keep the generic HTTP detail.
+    }
+    throw new Error(detail);
+  }
+  const data = await response.json();
+  if (response.status === 207) {
+    console.warn("Partial Success:", data.message || "Warning: 207 Multi-Status");
+  }
+  return data as T;
+}
+
+export async function loadOntologyRegistry(): Promise<OntologyEntry[]> {
+  return parseResponse<OntologyEntry[]>(await fetch("/api/ontology/registry"));
+}
+
+export async function loadOntologyGraph(uri: string, signal?: AbortSignal): Promise<OntologyGraphResponse> {
+  return parseResponse<OntologyGraphResponse>(
+    await fetch(`/api/ontology/graph?uri=${encodeURIComponent(uri)}`, { signal }),
+  );
+}
+
+// Three-state verdict: a string names the owner, null is the backend's
+// authoritative "no known ontology owns this entity", and undefined means the
+// request failed so there is no verdict to act on.
+export type OntologyOwnerVerdict = string | null | undefined;
+
+export async function loadOntologyEntityOwner(uri: string): Promise<OntologyOwnerVerdict> {
+  const response = await fetch(`/api/ontology/entity/${encodeURIComponent(uri)}`);
+  if (!response.ok) return undefined;
+  const owner = await response.json() as OntologyEntityOwner | null;
+  // Only a field that is actually there carries the verdict. Coercing an absent
+  // field to null would assert the strongest available claim — "nothing owns
+  // this" — on the weakest possible evidence, and that claim now stops the
+  // editor selecting an ontology at all.
+  const verdict = owner?.owning_ontology;
+  return verdict === undefined ? undefined : verdict;
+}
+
+export async function loadAlignments(uri?: string): Promise<OntologyAlignment[]> {
+  const query = uri ? `?uri=${encodeURIComponent(uri)}` : "";
+  return parseResponse<OntologyAlignment[]>(await fetch(`/api/ontology/alignments${query}`));
+}
+
+export async function saveAlignment(payload: {
+  source_uri: string;
+  target_uri: string;
+  relation: AlignmentRelation;
+  confidence: number;
+  provenance?: string;
+  source?: string;
+  reviewer?: string;
+}): Promise<OntologyAlignment> {
+  return parseResponse<OntologyAlignment>(
+    await fetch("/api/ontology/alignments", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    }),
+  );
+}
+
+export async function removeAlignment(id: string): Promise<void> {
+  await parseResponse<{ status: string }>(
+    await fetch(`/api/ontology/alignments?id=${encodeURIComponent(id)}`, { method: "DELETE" }),
+  );
+}
+
+export async function suggestAlignments(payload: {
+  source_ontology_uri?: string;
+  target_ontology_uri?: string;
+  threshold: number;
+  limit: number;
+}): Promise<AlignmentSuggestion[]> {
+  return parseResponse<AlignmentSuggestion[]>(
+    await fetch("/api/ontology/suggest-alignments", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    }),
+  );
+}
+
+export async function loadOntologyHealth(uri: string): Promise<OntologyHealthResponse> {
+  return parseResponse<OntologyHealthResponse>(
+    await fetch(`/api/ontology/health?uri=${encodeURIComponent(uri)}`),
+  );
+}
+
+export async function generateShacl(uri: string, qualityTier: "standard" | "strict" = "strict"): Promise<ShaclGenerateResponse> {
+  return parseResponse<ShaclGenerateResponse>(
+    await fetch("/api/ontology/shacl/generate", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ uri, quality_tier: qualityTier }),
+    }),
+  );
+}
+
+export async function loadShaclShapes(uri: string): Promise<ShaclShapesResponse> {
+  return parseResponse<ShaclShapesResponse>(
+    await fetch(`/api/ontology/shacl/shapes?uri=${encodeURIComponent(uri)}`),
+  );
+}
+
+export async function validateShacl(uri: string, shaclTurtle: string): Promise<ShaclValidationResponse> {
+  return parseResponse<ShaclValidationResponse>(
+    await fetch("/api/ontology/shacl/validate", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ uri, shacl_turtle: shaclTurtle }),
+    }),
+  );
+}

package/explorer/src/workspaces/OntologyWorkspace/index.tsx

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useState } from "react";
+import {
+  BookMarked,
+  GitMerge,
+  HeartPulse,
+  Layers,
+  Shield,
+  Sliders,
+} from "lucide-react";
+import { AlignmentsTab } from "./AlignmentsTab";
+import { HealthTab } from "./HealthTab";
+import { OntologyManager } from "./OntologyManager";
+import { OntologyEditor } from "./OntologyEditor";
+import { ShaclStudio } from "./ShaclStudio";
+import { VersionsTab } from "./VersionsTab";
+import { readOntologyUrlState, writeEntitySelection, writeTab } from "./ontologyUrlState";
+
+export type OntologyHubTab =
+  | "registry"
+  | "editor"
+  | "versions"
+  | "alignments"
+  | "health"
+  | "shacl";
+
+const TABS: { id: OntologyHubTab; label: string; icon: typeof GitMerge }[] = [
+  { id: "registry", label: "Registry", icon: BookMarked },
+  { id: "editor", label: "Editor", icon: Sliders },
+  { id: "versions", label: "Versions", icon: Layers },
+  { id: "alignments", label: "Alignments", icon: GitMerge },
+  { id: "health", label: "Health", icon: HeartPulse },
+  { id: "shacl", label: "SHACL", icon: Shield },
+];
+
+function readInitialTab(): OntologyHubTab {
+  const { tab, entityUri } = readOntologyUrlState();
+  const requested = TABS.find((candidate) => candidate.id === tab);
+  if (requested) return requested.id;
+  if (entityUri) return "editor";
+  return "registry";
+}
+
+interface OntologyWorkspaceProps {
+  onJumpToGraphNode?: (nodeId: string) => void;
+}
+
+export function OntologyWorkspace({ onJumpToGraphNode }: OntologyWorkspaceProps) {
+  const [activeTab, setActiveTab] = useState<OntologyHubTab>(readInitialTab);
+
+  useEffect(() => {
+    writeTab(activeTab);
+  }, [activeTab]);
+
+  const handleTabChange = useCallback((tab: OntologyHubTab) => {
+    setActiveTab(tab);
+  }, []);
+
+  const handleFixInEditor = useCallback((entityUri: string) => {
+    writeEntitySelection(entityUri);
+    setActiveTab("editor");
+  }, []);
+
+  const renderTab = () => {
+    switch (activeTab) {
+      case "registry":
+        return <OntologyManager />;
+      case "editor":
+        return <OntologyEditor />;
+      case "versions":
+        return <VersionsTab />;
+      case "alignments":
+        return <AlignmentsTab />;
+      case "health":
+        return <HealthTab onFixInEditor={handleFixInEditor} />;
+      case "shacl":
+        return <ShaclStudio onJumpToNode={onJumpToGraphNode} />;
+    }
+  };
+
+  return (
+    <div className="ws-page">
+      {/* Internal sub-tab bar */}
+      <div style={{ display: "flex", gap: 4, padding: "8px 16px", borderBottom: "1px solid var(--ws-border)", background: "rgba(0,0,0,0.18)", flexShrink: 0, flexWrap: "wrap" }}>
+        {TABS.map(({ id, label, icon: Icon }) => {
+          const active = activeTab === id;
+          return (
+            <button
+              key={id}
+              onClick={() => handleTabChange(id)}
+              style={{ display: "inline-flex", alignItems: "center", gap: 6, padding: "6px 13px", borderRadius: 999, border: `1px solid ${active ? "var(--ws-border-strong)" : "transparent"}`, background: active ? "var(--ws-accent-soft)" : "transparent", color: active ? "var(--ws-text)" : "var(--ws-text-muted)", fontSize: 12, fontWeight: 600, cursor: "pointer", transition: "160ms ease" }}
+            >
+              <Icon size={13} />
+              {label}
+            </button>
+          );
+        })}
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: "hidden" }}>{renderTab()}</div>
+    </div>
+  );
+}

package/explorer/src/workspaces/OntologyWorkspace/ontologyEditorModel.ts

@@ -0,0 +1,87 @@
+export type EditorEntityType = "ontology" | "class" | "property" | "external";
+
+export type RegistryEntry = {
+  uri: string;
+  name: string;
+};
+
+export const ONTOLOGY_MINIMAP_THEME = {
+  bgColor: "#0b1625",
+  maskColor: "rgba(11, 5, 8, 0.72)",
+  maskStrokeColor: "#5faeff",
+  maskStrokeWidth: 2,
+  nodeColor: "#2d7fd3",
+  nodeStrokeColor: "#9acbff",
+  nodeStrokeWidth: 1,
+  style: {
+    border: "1px solid #29435c",
+    borderRadius: 6,
+    boxShadow: "0 4px 16px rgba(0, 0, 0, 0.32)",
+  },
+} as const;
+
+// Last-resort guess, reached only when the backend gave no verdict: it has no
+// notion of nested vocabularies, so it can name a parent that does not contain
+// the entity. Authority is owning_ontology from /api/ontology/entity
+// (_resolve_owning_ontology in alphasemantichub/explorer/routes/ontology.py).
+function ownsByNamespace(entityUri: string, ontologyUri: string): boolean {
+  const stem = ontologyUri.replace(/[/#]+$/, "");
+  return entityUri === ontologyUri
+    || entityUri.startsWith(`${stem}#`)
+    || entityUri.startsWith(`${stem}/`);
+}
+
+/**
+ * Three outcomes, deliberately not collapsed into `string | undefined`.
+ *
+ * `unowned` and `unresolved` both yield "no ontology to open", but they must
+ * not be treated alike: a caller that writes `resolve(...) || entries[0]` turns
+ * the backend's authoritative "nothing owns this entity" into "open an
+ * arbitrary ontology", which reintroduces the parent-selection bug this whole
+ * verdict exists to prevent. The union makes that collapse a type error.
+ */
+export type EditorOntologyResolution =
+  | { status: "resolved"; uri: string }
+  | { status: "unowned"; entityUri: string }
+  | { status: "unresolved" };
+
+// Picks the registered ontology to open for a deep-linked entity. A null
+// verdict is the backend's authoritative "nothing owns this entity": the
+// namespace guess must stay suppressed, or an unregistered nested namespace
+// would select its registered parent again. Only an unavailable verdict
+// (undefined) may fall back to inference.
+export function resolveEditorOntology(
+  entries: RegistryEntry[],
+  entityUri: string,
+  ownerVerdict: string | null | undefined,
+): EditorOntologyResolution {
+  if (ownerVerdict === null) {
+    return { status: "unowned", entityUri };
+  }
+  const uri = inferOntologyUri(entries, entityUri, ownerVerdict);
+  return uri === undefined ? { status: "unresolved" } : { status: "resolved", uri };
+}
+
+// Picks the registered ontology to open for an entity: the backend-resolved
+// explicitOwner wins outright, the namespace guess is only the fallback.
+export function inferOntologyUri(
+  entries: RegistryEntry[],
+  entityUri: string,
+  explicitOwner?: string,
+): string | undefined {
+  // Trusted even when the registry does not list it. Falling through to the
+  // namespace guess here would answer a question nobody asked — the backend
+  // named this entity's owner, and silently opening a *different* ontology is
+  // worse than opening one the registry has not been told about yet, which
+  // surfaces as an explicit error from /api/ontology/graph.
+  if (explicitOwner) {
+    return explicitOwner;
+  }
+  return [...entries]
+    .filter((entry) => ownsByNamespace(entityUri, entry.uri))
+    .sort((left, right) => right.uri.length - left.uri.length)[0]?.uri;
+}
+
+export function isEditableEntityType(entityType?: EditorEntityType): boolean {
+  return entityType === "class" || entityType === "property";
+}

package/explorer/src/workspaces/OntologyWorkspace/ontologyUrlState.ts

@@ -0,0 +1,94 @@
+// Sole owner of the Ontology Hub deep-link query parameters: the names below must not be
+// spelled out anywhere else, so that the protocol can change in one place.
+const TAB_PARAM = "ontologyTab";
+const ENTITY_PARAM = "ontologyEntity";
+const EDITOR_TAB = "editor";
+
+export interface OntologyUrlState {
+  /** Raw parameter value; the set of legal tab ids belongs to the workspace, not this module. */
+  tab?: string;
+  entityUri?: string;
+}
+
+/** `undefined` means the parameter is absent; an empty string means it is present but blank. */
+export function parseOntologyUrlState(search: string): OntologyUrlState {
+  const params = new URLSearchParams(search);
+  return {
+    tab: params.get(TAB_PARAM) ?? undefined,
+    entityUri: params.get(ENTITY_PARAM) ?? undefined,
+  };
+}
+
+export function applyTab(search: string, tab: string): string {
+  const params = new URLSearchParams(search);
+  params.set(TAB_PARAM, tab);
+  return `?${params.toString()}`;
+}
+
+// A selected entity is only addressable from the editor, so the tab moves with it.
+export function applyEntitySelection(search: string, entityUri: string): string {
+  const params = new URLSearchParams(search);
+  params.set(TAB_PARAM, EDITOR_TAB);
+  params.set(ENTITY_PARAM, entityUri);
+  return `?${params.toString()}`;
+}
+
+// Pairs with applyEntitySelection: an entity URI is resolved back to its owning ontology on
+// load, so leaving a stale one behind when the active ontology changes reopens the old ontology.
+export function removeEntitySelection(search: string): string {
+  const params = new URLSearchParams(search);
+  params.delete(ENTITY_PARAM);
+  return `?${params.toString()}`;
+}
+
+/**
+ * Deliberately dual-role, and the argument is what selects the role: given a
+ * `search` string this is pure and total, delegating straight to
+ * `parseOntologyUrlState`; called with no argument it reads live `window`
+ * state and yields empty state if the URL is unreadable. Callers in render or
+ * effect paths use the no-argument form; tests and any caller that already
+ * holds a search string pass it, which is the only form that is testable.
+ */
+export function readOntologyUrlState(search?: string): OntologyUrlState {
+  if (search !== undefined) {
+    return parseOntologyUrlState(search);
+  }
+  try {
+    return parseOntologyUrlState(window.location.search);
+  } catch {
+    return {};
+  }
+}
+
+/** True when the URL addresses the Ontology Hub at all, even with blank parameter values. */
+export function hasOntologyUrlState(search?: string): boolean {
+  const { tab, entityUri } = readOntologyUrlState(search);
+  return tab !== undefined || entityUri !== undefined;
+}
+
+// The transform returns a query string only, so the fragment has to be carried
+// across explicitly: replaceState with a bare "?..." drops it. This is the one
+// place that knows how the URL is written, so it is the only place that can.
+function updateSearch(transform: (search: string) => string): void {
+  try {
+    window.history.replaceState(
+      null,
+      "",
+      `${transform(window.location.search)}${window.location.hash}`,
+    );
+  } catch {
+    // Deep-link state is a convenience; every caller stays correct without it.
+  }
+}
+
+export function writeTab(tab: string): void {
+  updateSearch((search) => applyTab(search, tab));
+}
+
+export function writeEntitySelection(entityUri: string): void {
+  updateSearch((search) => applyEntitySelection(search, entityUri));
+}
+
+export function clearEntitySelection(): void {
+  updateSearch(removeEntitySelection);
+}

package/explorer/src/workspaces/OntologyWorkspace/types.ts

@@ -0,0 +1,119 @@
+export interface OntologyEntry {
+  uri: string;
+  name: string;
+  description?: string;
+  format: string;
+  status: "published" | "draft" | "external";
+  source_url?: string;
+  version?: string;
+  class_count: number;
+  concept_count: number;
+  property_count: number;
+  loaded_at: string;
+  enabled: boolean;
+  tags: string[];
+}
+
+export type AlignmentRelation =
+  | "owl:equivalentClass"
+  | "owl:equivalentProperty"
+  | "skos:exactMatch"
+  | "skos:closeMatch"
+  | "skos:broadMatch"
+  | "skos:narrowMatch"
+  | "skos:relatedMatch";
+
+export interface OntologyAlignment {
+  id: string;
+  source_uri: string;
+  source_label: string;
+  target_uri: string;
+  target_label: string;
+  relation: AlignmentRelation;
+  predicate_uri: string;
+  confidence: number;
+  provenance?: string;
+  source?: string;
+  reviewer?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface AlignmentSuggestion {
+  source_uri: string;
+  source_label: string;
+  target_uri: string;
+  target_label: string;
+  relation: AlignmentRelation;
+  score: number;
+  label_similarity: number;
+  embedding_similarity?: number | null;
+  reason: string;
+}
+
+export interface HealthDimension {
+  key: string;
+  label: string;
+  score: number;
+  status: "ok" | "warning" | "critical" | "unavailable";
+  detail: string;
+}
+
+export interface HealthIssue {
+  id: string;
+  severity: "info" | "warning" | "critical";
+  category: string;
+  entity_uri?: string;
+  entity_label?: string;
+  message: string;
+  action?: string;
+}
+
+export interface OntologyHealthResponse {
+  uri: string;
+  name: string;
+  total_score: number;
+  dimensions: HealthDimension[];
+  issues: HealthIssue[];
+  generated_at: string;
+}
+
+export interface ShaclShapeSummary {
+  id: string;
+  target_class?: string;
+  constraint_count: number;
+  constraints: string[];
+  violation_count: number;
+}
+
+export interface ShaclViolation {
+  node?: string;
+  path?: string;
+  severity: string;
+  message: string;
+  focus_node?: string;
+  source_shape?: string;
+}
+
+export interface ShaclGenerateResponse {
+  uri: string;
+  shacl_turtle: string;
+  shape_count: number;
+  generated_at: string;
+}
+
+export interface ShaclShapesResponse {
+  uri: string;
+  shapes: ShaclShapeSummary[];
+  shacl_turtle: string;
+  generated_at: string;
+}
+
+export interface ShaclValidationResponse {
+  uri?: string;
+  conforms: boolean;
+  status: "success" | "unavailable" | "error";
+  message: string;
+  violations: ShaclViolation[];
+  report_text?: string;
+}