Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

5.4 KB
Raw Blame
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 }),
    }),
  );
}