cograph 0.1.25 → 0.1.27

package/dist/chunk-PE2EOIGT.js

@@ -0,0 +1,978 @@
+#!/usr/bin/env node
+import {
+  readConfig
+} from "./chunk-7VVBEUZQ.js";
+
+// src/client.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import { extname } from "path";
+var CographError = class extends Error {
+  status;
+  body;
+  constructor(message, opts) {
+    super(message);
+    this.name = "CographError";
+    this.status = opts?.status;
+    this.body = opts?.body;
+  }
+};
+var SCHEMA_SAMPLE_CAP = 5e3;
+function stridedSample(rows, cap = SCHEMA_SAMPLE_CAP) {
+  if (rows.length <= cap) return rows;
+  const out = [];
+  for (let i = 0; i < cap; i++) out.push(rows[Math.floor(i * rows.length / cap)]);
+  return out;
+}
+function envVar(name, fallback) {
+  return process.env[`COGRAPH_${name}`] || process.env[`OMNIX_${name}`] || fallback;
+}
+var EXT_FORMAT = {
+  ".csv": "csv",
+  ".json": "json",
+  ".jsonl": "json",
+  ".txt": "text"
+};
+function parseCsv(content) {
+  const rows = [];
+  let cur = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (content[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += ch;
+      }
+    } else {
+      if (ch === '"') {
+        inQuotes = true;
+      } else if (ch === ",") {
+        cur.push(field);
+        field = "";
+      } else if (ch === "\n") {
+        cur.push(field);
+        rows.push(cur);
+        cur = [];
+        field = "";
+      } else if (ch === "\r") {
+        if (content[i + 1] !== "\n") {
+          cur.push(field);
+          rows.push(cur);
+          cur = [];
+          field = "";
+        }
+      } else {
+        field += ch;
+      }
+    }
+  }
+  if (field.length > 0 || cur.length > 0) {
+    cur.push(field);
+    rows.push(cur);
+  }
+  if (rows.length === 0) return [];
+  const headers = rows[0].map((h) => h.trim());
+  const out = [];
+  for (let r = 1; r < rows.length; r++) {
+    const row = rows[r];
+    if (row.length === 1 && row[0] === "") continue;
+    const obj = {};
+    for (let c = 0; c < headers.length; c++) {
+      obj[headers[c]] = row[c] ?? "";
+    }
+    out.push(obj);
+  }
+  return out;
+}
+var Client = class {
+  apiKey;
+  baseUrl;
+  tenant;
+  /**
+   * Raw / passthrough API — one method per canonical backend operation, with
+   * the path encoded inside the SDK. Each method returns the backend
+   * {@link Response} VERBATIM: it does NOT throw on non-2xx and does NOT reshape
+   * the body. This is the seam the webapp's proxy layer adopts so per-operation
+   * paths live in one place (here) instead of being hand-rolled at each call
+   * site. See {@link RawApi}. The typed methods on this class (which throw on
+   * non-2xx and reshape some payloads) are left unchanged — this is additive.
+   */
+  raw;
+  constructor(opts = {}) {
+    const cfg = readConfig();
+    this.apiKey = opts.apiKey ?? envVar("API_KEY") ?? cfg.apiKey;
+    const url = opts.baseUrl ?? envVar("API_URL") ?? cfg.apiUrl ?? "https://api.cograph.cloud";
+    this.baseUrl = url.replace(/\/+$/, "");
+    this.tenant = opts.tenant ?? envVar("TENANT") ?? cfg.tenant ?? "demo-tenant";
+    this.raw = new RawApi(this);
+  }
+  headers() {
+    const h = { "Content-Type": "application/json" };
+    if (this.apiKey) h["X-API-Key"] = this.apiKey;
+    return h;
+  }
+  base() {
+    return `${this.baseUrl}/graphs/${this.tenant}`;
+  }
+  // --- Path builders -------------------------------------------------------- #
+  // SINGLE source of truth for every canonical backend path. Both the raw API
+  // and the new typed parsed methods build URLs through these, so a path lives
+  // in exactly one place. Tenant-scoped paths hang off `base()`
+  // (`{baseUrl}/graphs/{tenant}`); the handful of account-level paths
+  // (e.g. tenant CRUD) hang off `baseUrl` directly.
+  //
+  // These are marked `@internal` (not part of the public SDK surface) but are
+  // not `private`, so the sibling {@link RawApi} can build the same canonical
+  // paths without duplicating them.
+  /** @internal */
+  pAgent() {
+    return `${this.base()}/agent`;
+  }
+  /** @internal */
+  pAsk() {
+    return `${this.base()}/ask`;
+  }
+  /** @internal */
+  pIngest() {
+    return `${this.base()}/ingest`;
+  }
+  /** @internal */
+  pIngestCsvSchema() {
+    return `${this.base()}/ingest/csv/schema`;
+  }
+  /** @internal */
+  pIngestCsvRows() {
+    return `${this.base()}/ingest/csv/rows`;
+  }
+  /** @internal */
+  pEnrichJobs() {
+    return `${this.base()}/enrich/jobs`;
+  }
+  /** @internal */
+  pEnrichJob(jobId) {
+    return `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}`;
+  }
+  /** @internal */
+  pEnrichJobConflicts(jobId) {
+    return `${this.pEnrichJob(jobId)}/conflicts`;
+  }
+  /** @internal */
+  pEnrichJobApply(jobId) {
+    return `${this.pEnrichJob(jobId)}/apply`;
+  }
+  /** @internal */
+  pOntologyTypes() {
+    return `${this.base()}/ontology/types`;
+  }
+  /** @internal */
+  pOntologyResolve() {
+    return `${this.base()}/ontology/resolve`;
+  }
+  /** @internal Targets the premium ontology-recommender route, mounted only on
+   *  deployments with the proprietary layer — 404s on bare OSS. */
+  pOntologyRecommend() {
+    return `${this.base()}/ontology/recommend`;
+  }
+  /** @internal */
+  pOntologyApply() {
+    return `${this.base()}/ontology/apply`;
+  }
+  /** @internal */
+  pKgs() {
+    return `${this.base()}/kgs`;
+  }
+  /** @internal */
+  pKg(name) {
+    return `${this.base()}/kgs/${encodeURIComponent(name)}`;
+  }
+  /** @internal */
+  pTypeCounts(kg) {
+    return `${this.pKg(kg)}/type-counts`;
+  }
+  /** @internal */
+  pExploreSummary(kg, typeName) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/summary`;
+  }
+  /** @internal */
+  pExploreRecords(kg, typeName, query) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/records${query ?? ""}`;
+  }
+  /** @internal */
+  pExploreTypeEdges(kg) {
+    return `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/type-edges`;
+  }
+  /** @internal */
+  pExploreSearch(query) {
+    return `${this.base()}/explore/search${query}`;
+  }
+  /** @internal */
+  pNormalizeSuggest(query) {
+    return `${this.base()}/normalize/suggest${query}`;
+  }
+  /** @internal */
+  pNormalizeRules(query) {
+    return `${this.base()}/normalize/rules${query ?? ""}`;
+  }
+  /** @internal */
+  pNormalizeRule(ruleId, action) {
+    return `${this.base()}/normalize/rules/${encodeURIComponent(ruleId)}/${action}`;
+  }
+  /** @internal */
+  pTenants() {
+    return `${this.baseUrl}/v1/me/tenants`;
+  }
+  /** @internal */
+  pTenant(tenantId) {
+    return `${this.baseUrl}/v1/me/tenants/${encodeURIComponent(tenantId)}`;
+  }
+  /**
+   * Low-level passthrough request. Centralizes the absolute URL (already built
+   * by a path-builder, so it carries the base URL + `/graphs/{tenant}` prefix),
+   * the `X-API-Key` header, JSON content-type, body stringification, and a
+   * timeout/abort — then returns the backend {@link Response} UNCHANGED.
+   *
+   * Unlike {@link request}, this does NOT inspect `res.ok` and does NOT parse or
+   * reshape the body. A 4xx/5xx comes back as a resolved `Response` (the caller
+   * reads `.status`/`.headers`/`.body`), NOT a thrown {@link CographError}. The
+   * only rejection paths are a genuine network failure or a timeout abort —
+   * exactly the cases where there is no HTTP response to hand back.
+   *
+   * `init.headers` is merged last so a caller can add/override headers; `init.body`,
+   * when a non-string is passed, is JSON-stringified for convenience.
+   */
+  async requestRaw(method, path, init = {}) {
+    const timeoutMs = init.timeoutMs ?? 12e4;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let body;
+    if (init.body !== void 0) {
+      body = typeof init.body === "string" ? init.body : JSON.stringify(init.body);
+    }
+    try {
+      return await fetch(path, {
+        method,
+        headers: { ...this.headers(), ...init.headers ?? {} },
+        body,
+        signal: controller.signal
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new CographError(`Request to ${path} timed out after ${timeoutMs}ms`);
+      }
+      throw new CographError(
+        `Network error contacting ${path}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * Probe the backend to determine reachability and whether endpoints
+   * require an X-API-Key header. Used at shell startup to distinguish
+   * cloud (auth required) from self-hosted open-access deployments.
+   */
+  async healthCheck() {
+    const healthUrl = `${this.baseUrl}/health`;
+    try {
+      const res = await fetch(healthUrl, {
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) return { ok: false, requiresAuth: false, url: this.baseUrl };
+    } catch {
+      return { ok: false, requiresAuth: false, url: this.baseUrl };
+    }
+    try {
+      const res = await fetch(`${this.base()}/kgs`, {
+        headers: { "Content-Type": "application/json" },
+        signal: AbortSignal.timeout(5e3)
+      });
+      return {
+        ok: true,
+        requiresAuth: res.status === 401,
+        url: this.baseUrl
+      };
+    } catch {
+      return { ok: true, requiresAuth: true, url: this.baseUrl };
+    }
+  }
+  async request(method, url, body, timeoutMs = 12e4) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers: this.headers(),
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new CographError(`Request to ${url} timed out after ${timeoutMs}ms`);
+      }
+      throw new CographError(
+        `Network error contacting ${url}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    clearTimeout(timer);
+    if (!res.ok) {
+      let text2 = "";
+      try {
+        text2 = await res.text();
+      } catch {
+      }
+      throw new CographError(`HTTP ${res.status}: ${text2}`, {
+        status: res.status,
+        body: text2
+      });
+    }
+    if (res.status === 204) return void 0;
+    const ct = res.headers.get("content-type") ?? "";
+    if (ct.includes("application/json")) {
+      return await res.json();
+    }
+    const text = await res.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  /**
+   * Ingest a file path or raw text into a knowledge graph.
+   *
+   * If `pathOrText` points to an existing file, its contents are read and the
+   * format is inferred from the extension (.csv, .json, .txt) unless
+   * `contentType` is given. CSV files use the two-step schema-inference + row
+   * mapping flow.
+   */
+  async ingest(pathOrText, opts = {}) {
+    let content;
+    let fmt;
+    let isFile = false;
+    try {
+      isFile = existsSync(pathOrText) && statSync(pathOrText).isFile();
+    } catch {
+      isFile = false;
+    }
+    if (isFile) {
+      const ext = extname(pathOrText).toLowerCase();
+      if (ext === ".pdf") {
+        throw new CographError(
+          "PDF ingest not yet supported in the Node CLI; use the Python CLI or POST raw bytes to the API."
+        );
+      }
+      content = readFileSync(pathOrText, "utf-8");
+      fmt = opts.contentType ?? EXT_FORMAT[ext] ?? "text";
+      if (fmt === "csv") {
+        return this.ingestCsv(content, opts);
+      }
+    } else {
+      content = pathOrText;
+      fmt = opts.contentType ?? "text";
+    }
+    const body = {
+      content,
+      content_type: fmt,
+      source: "client"
+    };
+    if (opts.kg) body.kg_name = opts.kg;
+    return this.request("POST", `${this.base()}/ingest`, body, 12e4);
+  }
+  async ingestCsv(content, opts) {
+    const kgName = opts.kg;
+    const batchSize = opts.batchSize ?? 200;
+    const concurrency = opts.concurrency ?? 4;
+    const rows = parseCsv(content);
+    if (rows.length === 0) throw new CographError("CSV is empty");
+    const headers = Object.keys(rows[0]);
+    const sampleRows = stridedSample(rows);
+    const schemaBody = {
+      headers,
+      sample_rows: sampleRows,
+      total_rows: rows.length
+    };
+    const mapping = await this.request(
+      "POST",
+      `${this.base()}/ingest/csv/schema`,
+      schemaBody,
+      3e5
+    );
+    let mappingToPost = mapping;
+    if (opts.onSchemaInferred) {
+      const reviewed = await opts.onSchemaInferred(mapping, {
+        totalRows: rows.length,
+        rowsProfiled: sampleRows.length
+      });
+      if (reviewed == null) {
+        return { cancelled: true, message: "Ingest cancelled before any rows were written." };
+      }
+      mappingToPost = reviewed;
+    }
+    const batches = [];
+    for (let i = 0; i < rows.length; i += batchSize) {
+      batches.push(rows.slice(i, i + batchSize));
+    }
+    let totalEntities = 0;
+    let totalTriples = 0;
+    let rowsProcessed = 0;
+    let nextBatch = 0;
+    const postBatch = async (batch) => {
+      const body = {
+        mapping: mappingToPost,
+        rows: batch,
+        source: "client"
+      };
+      if (kgName) body.kg_name = kgName;
+      const result = await this.request("POST", `${this.base()}/ingest/csv/rows`, body, 3e5);
+      return {
+        entities: result.entities_resolved ?? 0,
+        triples: result.triples_inserted ?? 0,
+        size: batch.length
+      };
+    };
+    const worker = async () => {
+      while (true) {
+        const idx = nextBatch++;
+        if (idx >= batches.length) return;
+        const r = await postBatch(batches[idx]);
+        totalEntities += r.entities;
+        totalTriples += r.triples;
+        rowsProcessed += r.size;
+        opts.onProgress?.({
+          rowsProcessed,
+          totalRows: rows.length,
+          entitiesResolved: totalEntities,
+          triplesInserted: totalTriples
+        });
+      }
+    };
+    const workers = [];
+    for (let i = 0; i < Math.min(concurrency, batches.length); i++) {
+      workers.push(worker());
+    }
+    await Promise.all(workers);
+    if (kgName) {
+      try {
+        await this.request(
+          "POST",
+          `${this.base()}/explore/kgs/${encodeURIComponent(kgName)}/recompute-stats`,
+          {},
+          15e3
+        );
+      } catch {
+      }
+    }
+    return {
+      entities_resolved: totalEntities,
+      triples_inserted: totalTriples,
+      mapping
+    };
+  }
+  /** Ask a natural language question and return the parsed response. */
+  async ask(question, opts = {}) {
+    const body = { question };
+    if (opts.kg) body.kg_name = opts.kg;
+    if (opts.model) body.model = opts.model;
+    return this.request("POST", `${this.base()}/ask`, body, 6e4);
+  }
+  /**
+   * One turn of the unified Ask-AI agent — the SINGLE conversational surface
+   * (`POST /graphs/{tenant}/agent`, COG-118). Mirrors the HTTP contract exactly:
+   *
+   *  - `confirmPlanId` set → the server runs `execute_plan` (the only mutating
+   *    path) and returns `{kind:"result", steps}`.
+   *  - otherwise → the server runs `planner.handle(message)` and returns one of
+   *    `{kind:"answer"}` / `{kind:"clarify"}` / `{kind:"plan"}`.
+   *
+   * The agent classifies intent server-side and drives the underlying engines
+   * through its capability registry — the client never talks to `/ask`,
+   * `/enrich/*` etc. for an agent turn. ENTITLEMENT for any paid step a plan
+   * contains is enforced server-side at execute time (the same authorization the
+   * direct paid routes apply), so confirming a plan here cannot bypass a gate the
+   * direct path enforces — the gate lives behind the endpoint, not in this client.
+   */
+  async agent(opts) {
+    const body = {
+      message: opts.message ?? "",
+      context: {
+        kg_name: opts.kgName ?? "",
+        type_name: opts.typeName ?? null
+      }
+    };
+    if (opts.sessionId) body.session_id = opts.sessionId;
+    if (opts.confirmPlanId) body.confirm = { plan_id: opts.confirmPlanId };
+    return this.request(
+      "POST",
+      `${this.base()}/agent`,
+      body,
+      // Generous: a confirmed plan can kick off enrichment/dedup work, and a
+      // question turn runs an LLM round-trip server-side.
+      12e4
+    );
+  }
+  /** List the tenants the authenticated user can access (GET /v1/me/tenants).
+   *  Keyed by the API key (X-API-Key → user), so it's independent of the active
+   *  tenant. Throws CographError with status 501 on deployments without a tenant
+   *  provider (e.g. OSS-only). */
+  async listTenants() {
+    return this.request(
+      "GET",
+      `${this.baseUrl}/v1/me/tenants`,
+      void 0,
+      15e3
+    );
+  }
+  /** List all knowledge graphs for the current tenant. */
+  async listKgs() {
+    const data = await this.request(
+      "GET",
+      `${this.base()}/kgs`,
+      void 0,
+      15e3
+    );
+    if (Array.isArray(data)) return data;
+    if (data && typeof data === "object" && "kgs" in data) {
+      const kgs = data.kgs;
+      if (Array.isArray(kgs)) return kgs;
+    }
+    return [];
+  }
+  /** Create a knowledge graph. */
+  async createKg(name, description) {
+    const body = { name };
+    if (description) body.description = description;
+    return this.request("POST", `${this.base()}/kgs`, body, 15e3);
+  }
+  /** Delete a knowledge graph by name. */
+  async deleteKg(name) {
+    return this.request(
+      "DELETE",
+      `${this.base()}/kgs/${encodeURIComponent(name)}`,
+      void 0,
+      3e4
+    );
+  }
+  /** List ontology types. */
+  async ontologyTypes() {
+    const data = await this.request(
+      "GET",
+      `${this.base()}/ontology/types`,
+      void 0,
+      15e3
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /**
+   * Resolve a natural-language ontology change against the existing ontology.
+   * The caller does not need to know exact type/attribute/relationship names —
+   * the server matches the plain-language `ask` to the current schema and
+   * returns auto-applied changes plus proposals that need confirmation.
+   */
+  async ontologyResolve(ask, opts = {}) {
+    const body = { ask };
+    if (opts.knowledge_graph) body.knowledge_graph = opts.knowledge_graph;
+    return this.request(
+      "POST",
+      `${this.base()}/ontology/resolve`,
+      body,
+      6e4
+    );
+  }
+  /**
+   * Apply a single resolved ontology change — one of the `proposals` returned
+   * by {@link ontologyResolve}. Pass the proposal object through unchanged.
+   */
+  async ontologyApply(proposal) {
+    return this.request(
+      "POST",
+      `${this.base()}/ontology/apply`,
+      proposal,
+      6e4
+    );
+  }
+  /**
+   * Second-pass entity resolution: re-run ER over an already-ingested KG to
+   * collapse intra-batch fragments. Synchronous on the server; returns a
+   * per-type before/after report. Generous timeout — it rewrites triples.
+   */
+  async erRebuild(kg) {
+    return this.request(
+      "POST",
+      `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/er-rebuild`,
+      {},
+      3e5
+    );
+  }
+  /** Per-KG type counts: every type with ≥1 instance, sorted desc. */
+  async typeCounts(kg) {
+    const data = await this.request(
+      "GET",
+      `${this.base()}/kgs/${encodeURIComponent(kg)}/type-counts`,
+      void 0,
+      3e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Plan + run an enrichment job. Returns immediately with the job id. */
+  async enrichRun(req) {
+    return this.request(
+      "POST",
+      `${this.base()}/enrich/jobs`,
+      req,
+      3e4
+    );
+  }
+  /** List recent enrichment jobs for the current tenant. */
+  async enrichJobs() {
+    const data = await this.request(
+      "GET",
+      `${this.base()}/enrich/jobs`,
+      void 0,
+      15e3
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Fetch a single enrichment job (with truncated results). */
+  async enrichJob(jobId) {
+    return this.request(
+      "GET",
+      `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}`,
+      void 0,
+      15e3
+    );
+  }
+  /** Fetch the conflict review queue for a job. */
+  async enrichConflicts(jobId) {
+    const data = await this.request(
+      "GET",
+      `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}/conflicts`,
+      void 0,
+      3e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Apply a set of conflict review decisions to a job. */
+  async enrichApply(jobId, decisions) {
+    return this.request(
+      "POST",
+      `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}/apply`,
+      { decisions },
+      6e4
+    );
+  }
+  /** Cancel an enrichment job. */
+  async enrichCancel(jobId) {
+    await this.request(
+      "DELETE",
+      `${this.base()}/enrich/jobs/${encodeURIComponent(jobId)}`,
+      void 0,
+      15e3
+    );
+  }
+  /** Per-type breakdown for one type in one KG: definition + counts + samples.
+   *
+   * System predicates (rdfs:label, ingested_at, source) are hidden by default
+   * — they're attached to every entity at 100% and drown out the columns the
+   * user cares about. Pass `includeSystem: true` to see them. */
+  async typeUsage(kg, typeName, opts = {}) {
+    const qs = opts.includeSystem ? "?include_system=true" : "";
+    return this.request(
+      "GET",
+      `${this.base()}/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/usage${qs}`,
+      void 0,
+      3e4
+    );
+  }
+  /** Explorer summary for a type — like typeUsage but adds coverage_pct + avg_degree. */
+  async typeSummary(kg, typeName) {
+    return this.request(
+      "GET",
+      `${this.base()}/explore/kgs/${encodeURIComponent(kg)}/types/${encodeURIComponent(typeName)}/summary`,
+      void 0,
+      3e4
+    );
+  }
+  /** Search types or attributes by name substring within a KG. */
+  async exploreSearch(kg, q, kind = "type") {
+    const qs = new URLSearchParams({ kg, q, kind }).toString();
+    const data = await this.request(
+      "GET",
+      this.pExploreSearch(`?${qs}`),
+      void 0,
+      15e3
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  // --- New typed methods (COG-128) ------------------------------------------ #
+  // Parsed/throwing variants of the previously-MISSING ops, sharing the same
+  // path-builders as the raw API. These follow the existing typed-method
+  // contract (throw on non-2xx, light reshape) — the raw equivalents under
+  // `client.raw.*` are the non-throwing, non-reshaping passthrough versions.
+  /**
+   * One page of entity instances of a type for the Explorer Data table
+   * (`GET /explore/kgs/{kg}/types/{type}/records`). Keyset-paginated by entity
+   * URI: pass the previous page's `next_cursor` as `cursor`. `limit` is clamped
+   * server-side to 1..200 (default 50).
+   */
+  async exploreRecords(kg, typeName, opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.limit != null) qs.set("limit", String(opts.limit));
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request(
+      "GET",
+      this.pExploreRecords(kg, typeName, query),
+      void 0,
+      3e4
+    );
+  }
+  /** Undirected type→type edges for the Explorer overview graph
+   *  (`GET /explore/kgs/{kg}/type-edges`). Returns `[{source, target, weight}]`. */
+  async exploreTypeEdges(kg) {
+    const data = await this.request(
+      "GET",
+      this.pExploreTypeEdges(kg),
+      void 0,
+      3e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Infer + persist normalization rules for a type's predicates, returned ranked
+   *  by confidence desc (`POST /normalize/suggest?kg&type`). */
+  async normalizeSuggest(kg, type) {
+    const qs = new URLSearchParams({ kg, type }).toString();
+    const data = await this.request(
+      "POST",
+      this.pNormalizeSuggest(`?${qs}`),
+      void 0,
+      6e4
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** List stored normalization rules, optionally filtered by KG and/or status
+   *  (`GET /normalize/rules?kg&status`). */
+  async normalizeRules(opts = {}) {
+    const qs = new URLSearchParams();
+    if (opts.kg) qs.set("kg", opts.kg);
+    if (opts.status) qs.set("status", opts.status);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    const data = await this.request(
+      "GET",
+      this.pNormalizeRules(query),
+      void 0,
+      15e3
+    );
+    return Array.isArray(data) ? data : [];
+  }
+  /** Confirm a suggested normalization rule (`POST /normalize/rules/{id}/confirm`). */
+  async normalizeConfirmRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "confirm"),
+      void 0,
+      15e3
+    );
+  }
+  /** Reject a suggested normalization rule (`POST /normalize/rules/{id}/reject`). */
+  async normalizeRejectRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "reject"),
+      void 0,
+      15e3
+    );
+  }
+  /** Apply a confirmed normalization rule in the background; the server acks 202
+   *  (`POST /normalize/rules/{id}/apply`). */
+  async normalizeApplyRule(ruleId) {
+    return this.request(
+      "POST",
+      this.pNormalizeRule(ruleId, "apply"),
+      {},
+      6e4
+    );
+  }
+  /** Recommend ontology relationships/changes for the active KG
+   *  (`POST /ontology/recommend`). Body shape is passed through unchanged.
+   *
+   *  NOTE: this targets the *premium* ontology-recommender route, which is only
+   *  mounted on deployments carrying the proprietary layer. It 404s on a bare
+   *  OSS deployment. */
+  async ontologyRecommend(body = {}) {
+    return this.request(
+      "POST",
+      this.pOntologyRecommend(),
+      body,
+      6e4
+    );
+  }
+};
+var RawApi = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  // -- agent / ask --------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/agent` — one turn of the unified Ask-AI agent. */
+  agent(body, init) {
+    return this.client.requestRaw("POST", this.client.pAgent(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ask` — natural-language question. */
+  ask(body, init) {
+    return this.client.requestRaw("POST", this.client.pAsk(), { body, ...init });
+  }
+  // -- ingest -------------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/ingest` — ingest text/json (or csv) content. */
+  ingest(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngest(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ingest/csv/schema` — infer a CSV schema mapping. */
+  ingestCsvSchema(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngestCsvSchema(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ingest/csv/rows` — write a batch of mapped rows. */
+  ingestCsvRows(body, init) {
+    return this.client.requestRaw("POST", this.client.pIngestCsvRows(), { body, ...init });
+  }
+  // -- enrich jobs --------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/enrich/jobs` — plan + run an enrichment job. */
+  enrichCreateJob(body, init) {
+    return this.client.requestRaw("POST", this.client.pEnrichJobs(), { body, ...init });
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs` — list recent enrichment jobs. */
+  enrichJobs(init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJobs(), init);
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs/{id}` — fetch a single job. */
+  enrichJob(jobId, init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJob(jobId), init);
+  }
+  /** `GET /graphs/{tenant}/enrich/jobs/{id}/conflicts` — conflict review queue. */
+  enrichConflicts(jobId, init) {
+    return this.client.requestRaw("GET", this.client.pEnrichJobConflicts(jobId), init);
+  }
+  /** `POST /graphs/{tenant}/enrich/jobs/{id}/apply` — apply review decisions. */
+  enrichApply(jobId, body, init) {
+    return this.client.requestRaw("POST", this.client.pEnrichJobApply(jobId), { body, ...init });
+  }
+  /** `DELETE /graphs/{tenant}/enrich/jobs/{id}` — cancel a job. */
+  enrichCancel(jobId, init) {
+    return this.client.requestRaw("DELETE", this.client.pEnrichJob(jobId), init);
+  }
+  // -- ontology ------------------------------------------------------------ #
+  /** `GET /graphs/{tenant}/ontology/types` — list ontology types. */
+  ontologyTypes(init) {
+    return this.client.requestRaw("GET", this.client.pOntologyTypes(), init);
+  }
+  /** `POST /graphs/{tenant}/ontology/resolve` — resolve an NL ontology change. */
+  ontologyResolve(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyResolve(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ontology/recommend` — recommend ontology changes.
+   *  Premium route: only mounted on deployments with the proprietary layer,
+   *  404s on bare OSS. */
+  ontologyRecommend(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyRecommend(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/ontology/apply` — apply one resolved change. */
+  ontologyApply(body, init) {
+    return this.client.requestRaw("POST", this.client.pOntologyApply(), { body, ...init });
+  }
+  // -- knowledge graphs ---------------------------------------------------- #
+  /** `GET /graphs/{tenant}/kgs` — list knowledge graphs. */
+  kgs(init) {
+    return this.client.requestRaw("GET", this.client.pKgs(), init);
+  }
+  /** `POST /graphs/{tenant}/kgs` — create a knowledge graph. */
+  createKg(body, init) {
+    return this.client.requestRaw("POST", this.client.pKgs(), { body, ...init });
+  }
+  /** `DELETE /graphs/{tenant}/kgs/{name}` — delete a knowledge graph. */
+  deleteKg(name, init) {
+    return this.client.requestRaw("DELETE", this.client.pKg(name), init);
+  }
+  // -- explore ------------------------------------------------------------- #
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/summary`. */
+  exploreSummary(kg, typeName, init) {
+    return this.client.requestRaw("GET", this.client.pExploreSummary(kg, typeName), init);
+  }
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/types/{type}/records?limit&cursor`. */
+  exploreRecords(kg, typeName, opts = {}, init) {
+    const qs = new URLSearchParams();
+    if (opts.limit != null) qs.set("limit", String(opts.limit));
+    if (opts.cursor) qs.set("cursor", opts.cursor);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.client.requestRaw("GET", this.client.pExploreRecords(kg, typeName, query), init);
+  }
+  /** `GET /graphs/{tenant}/explore/kgs/{kg}/type-edges`. */
+  exploreTypeEdges(kg, init) {
+    return this.client.requestRaw("GET", this.client.pExploreTypeEdges(kg), init);
+  }
+  /** `GET /graphs/{tenant}/kgs/{kg}/type-counts`. */
+  typeCounts(kg, init) {
+    return this.client.requestRaw("GET", this.client.pTypeCounts(kg), init);
+  }
+  /** `GET /graphs/{tenant}/explore/search?kg&q&kind`. */
+  exploreSearch(kg, q, kind = "type", init) {
+    const qs = new URLSearchParams({ kg, q, kind }).toString();
+    return this.client.requestRaw("GET", this.client.pExploreSearch(`?${qs}`), init);
+  }
+  // -- normalize ----------------------------------------------------------- #
+  /** `POST /graphs/{tenant}/normalize/suggest?kg&type` — infer + persist rules. */
+  normalizeSuggest(kg, type, init) {
+    const qs = new URLSearchParams({ kg, type }).toString();
+    return this.client.requestRaw("POST", this.client.pNormalizeSuggest(`?${qs}`), init);
+  }
+  /** `GET /graphs/{tenant}/normalize/rules?kg&status` — list stored rules. */
+  normalizeRules(opts = {}, init) {
+    const qs = new URLSearchParams();
+    if (opts.kg) qs.set("kg", opts.kg);
+    if (opts.status) qs.set("status", opts.status);
+    const query = qs.toString() ? `?${qs.toString()}` : "";
+    return this.client.requestRaw("GET", this.client.pNormalizeRules(query), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules` — create a user-authored rule. */
+  normalizeCreateRule(body, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRules(), { body, ...init });
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/confirm`. */
+  normalizeConfirmRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "confirm"), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/reject`. */
+  normalizeRejectRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "reject"), init);
+  }
+  /** `POST /graphs/{tenant}/normalize/rules/{id}/apply`. */
+  normalizeApplyRule(ruleId, init) {
+    return this.client.requestRaw("POST", this.client.pNormalizeRule(ruleId, "apply"), init);
+  }
+  // -- tenants (account-level, NOT tenant-scoped) -------------------------- #
+  /** `POST /v1/me/tenants` — create/grant a tenant for the authed user. */
+  createTenant(body, init) {
+    return this.client.requestRaw("POST", this.client.pTenants(), { body, ...init });
+  }
+  /** `DELETE /v1/me/tenants/{id}` — remove a tenant grant. */
+  deleteTenant(tenantId, init) {
+    return this.client.requestRaw("DELETE", this.client.pTenant(tenantId), init);
+  }
+  /** `GET /v1/me/tenants` — list tenants the authed user can access. */
+  tenants(init) {
+    return this.client.requestRaw("GET", this.client.pTenants(), init);
+  }
+};
+
+export {
+  CographError,
+  Client
+};
+//# sourceMappingURL=chunk-PE2EOIGT.js.map