@littlebigbrain/client 0.1.0

package/dist/client.js

@@ -0,0 +1,878 @@
+/**
+ * Parse a {@link Schemas.SparqlTextResponse} (whose `results` field carries the
+ * SPARQL Results document as a JSON *string*) into typed bindings plus flat
+ * `{ variable: lexicalValue }` rows — the form most callers want, so they never
+ * have to `JSON.parse` and zip `head.vars` with binding values by hand.
+ */
+export function parseSparqlResults(response) {
+    const doc = JSON.parse(response.results);
+    const vars = doc.head?.vars ?? [];
+    if (typeof doc.boolean === "boolean") {
+        return { vars, boolean: doc.boolean, bindings: [], rows: [] };
+    }
+    const bindings = doc.results?.bindings ?? [];
+    const rows = bindings.map((binding) => Object.fromEntries(Object.entries(binding).map(([name, term]) => [name, term.value])));
+    return { vars, boolean: null, bindings, rows };
+}
+function firstPatternVariable(patterns) {
+    for (const pattern of patterns) {
+        if ("var" in pattern.subject)
+            return pattern.subject.var;
+        if ("var" in pattern.object)
+            return pattern.object.var;
+    }
+    return "entity";
+}
+function attributeFilterValue(value) {
+    if (typeof value === "boolean")
+        return { bool: value };
+    if (typeof value === "number")
+        return Number.isInteger(value) ? { i64: value } : { f64: value };
+    if (typeof value === "string")
+        return { str: value };
+    if ("dateTime" in value)
+        return { date_time: value.dateTime };
+    return { entity: value.entity };
+}
+function attributeFilter(filter, defaultVar) {
+    return {
+        compare: {
+            op: filter.op ?? "eq",
+            left: { property: { var: filter.var ?? defaultVar, field: filter.field } },
+            right: { value: attributeFilterValue(filter.value) },
+        },
+    };
+}
+/** Thrown when the server responds with a non-2xx status. */
+export class LbbError extends Error {
+    status;
+    body;
+    error;
+    type;
+    code;
+    param;
+    requestId;
+    docUrl;
+    constructor(status, body, error) {
+        super(error?.message ?? `Little Big Brain ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.error = error;
+        this.name = "LbbError";
+        this.type = error?.type;
+        this.code = error?.code;
+        this.param = error?.param;
+        this.requestId = error?.request_id;
+        this.docUrl = error?.doc_url;
+    }
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    const timer = globalThis
+        .setTimeout;
+    return new Promise((resolve) => {
+        if (timer) {
+            timer(resolve, ms);
+        }
+        else {
+            resolve();
+        }
+    });
+}
+function retryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function retryAllowed(method, idempotencyKey) {
+    const upper = method.toUpperCase();
+    return upper === "GET" || upper === "HEAD" || upper === "OPTIONS" || idempotencyKey !== undefined;
+}
+function parseLbbError(status, body, fallbackRequestId) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed.error) {
+            return new LbbError(status, body, {
+                ...parsed.error,
+                request_id: parsed.error.request_id ?? fallbackRequestId ?? null,
+            });
+        }
+    }
+    catch {
+        // Fall through to an unstructured error.
+    }
+    return new LbbError(status, body, {
+        type: "api_error",
+        code: "unstructured_error",
+        message: body || `Little Big Brain ${status}`,
+        request_id: fallbackRequestId ?? null,
+    });
+}
+/**
+ * A typed HTTP client for a Little Big Brain graph server. One instance is scoped to a
+ * single graph/branch; construct another for a different scope. All methods
+ * return the parsed JSON response and throw {@link LbbError} on failure.
+ */
+export class LbbClient {
+    baseUrl;
+    apiKey;
+    graphName;
+    branchName;
+    stack;
+    fetchImpl;
+    apiVersion;
+    maxRetries;
+    retryDelayMs;
+    search;
+    indexes;
+    entities;
+    schema;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.graphName = options.graph;
+        this.branchName = options.branch;
+        this.stack = options.stack;
+        this.apiVersion = options.apiVersion ?? "2026-06-22";
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryDelayMs = options.retryDelayMs ?? 100;
+        const fallback = globalThis.fetch;
+        const chosen = options.fetch ?? (fallback ? fallback.bind(globalThis) : undefined);
+        if (!chosen) {
+            throw new Error("no fetch implementation available; pass options.fetch");
+        }
+        this.fetchImpl = chosen;
+        this.search = new SearchNamespace(this);
+        this.indexes = new IndexNamespace(this);
+        this.entities = new EntityNamespace(this);
+        this.schema = new SchemaNamespace(this);
+    }
+    graph(name, opts = {}) {
+        return new GraphNamespace(this.withScope({
+            graph: name,
+            branch: opts.branch ?? this.branchName,
+            stack: opts.stack ?? this.stack,
+        }));
+    }
+    /**
+     * A new client for a different graph/branch on the same server and credential.
+     * Each instance is scoped to one graph/branch, so use this to target another
+     * scope (e.g. creating a fresh graph) without mutating the current client.
+     */
+    withScope(scope) {
+        return new LbbClient({
+            baseUrl: this.baseUrl,
+            apiKey: this.apiKey,
+            graph: scope.graph ?? this.graphName,
+            branch: scope.branch ?? this.branchName,
+            stack: scope.stack ?? this.stack,
+            fetch: this.fetchImpl,
+            apiVersion: this.apiVersion,
+            maxRetries: this.maxRetries,
+            retryDelayMs: this.retryDelayMs,
+        });
+    }
+    buildUrl(path, query) {
+        const params = [];
+        const push = (key, value) => params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        if (this.graphName !== undefined)
+            push("graph", this.graphName);
+        if (this.branchName !== undefined)
+            push("branch", this.branchName);
+        if (this.stack !== undefined)
+            push("stack", this.stack);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                push(key, value);
+        }
+        const qs = params.length > 0 ? `?${params.join("&")}` : "";
+        return `${this.baseUrl}${path}${qs}`;
+    }
+    async rawRequest(method, path, opts = {}) {
+        const headers = {
+            "content-type": opts.contentType ?? "application/json",
+            "lbb-version": this.apiVersion,
+        };
+        if (this.apiKey !== undefined)
+            headers["authorization"] = `Bearer ${this.apiKey}`;
+        if (opts.idempotencyKey !== undefined)
+            headers["idempotency-key"] = opts.idempotencyKey;
+        const canRetry = retryAllowed(method, opts.idempotencyKey);
+        const body = opts.rawBody !== undefined
+            ? opts.rawBody
+            : opts.body !== undefined
+                ? JSON.stringify(opts.body)
+                : undefined;
+        const init = {
+            method,
+            headers,
+            body,
+        };
+        let response;
+        let text = "";
+        for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+            try {
+                response = await this.fetchImpl(this.buildUrl(path, opts.query), init);
+                text = await response.text();
+            }
+            catch (error) {
+                if (canRetry && attempt < this.maxRetries) {
+                    await sleep(this.retryDelayMs * (attempt + 1));
+                    continue;
+                }
+                throw error;
+            }
+            if (response.ok || !retryableStatus(response.status) || attempt === this.maxRetries) {
+                break;
+            }
+            if (!canRetry) {
+                break;
+            }
+            await sleep(this.retryDelayMs * (attempt + 1));
+        }
+        if (response === undefined)
+            throw new Error("request did not produce a response");
+        const requestId = response.headers?.get("x-request-id") ?? undefined;
+        const version = response.headers?.get("lbb-version") ?? undefined;
+        if (!response.ok)
+            throw parseLbbError(response.status, text.trim(), requestId);
+        return {
+            data: (text ? JSON.parse(text) : undefined),
+            status: response.status,
+            requestId,
+            version,
+            headers: response.headers,
+        };
+    }
+    async request(method, path, opts = {}) {
+        const response = await this.rawRequest(method, path, opts);
+        return response.data;
+    }
+    mutationKey(prefix) {
+        const random = Math.random().toString(36).slice(2);
+        return `${prefix}:${Date.now()}:${random}`;
+    }
+    idempotencyKey(prefix = "request") {
+        return this.mutationKey(prefix);
+    }
+    // --- writes ---
+    /** Commit triplets and optional entity embeddings. Prefer `client.graph("main").facts.create(...)`. */
+    commit(body, opts = {}) {
+        return this.request("POST", "/v1/graph/commit", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("facts.create"),
+        });
+    }
+    /**
+     * Validate-only preflight: run the same ontology/schema validation a real
+     * commit would and report the would-be effect (`op_count`, `written_properties`,
+     * `schema_validation`) without writing. A rejected request fails exactly as a
+     * real commit would, so this is a safe check before mutating. No idempotency
+     * key needed — nothing is persisted.
+     */
+    commitDryRun(body) {
+        return this.request("POST", "/v1/graph/commit", {
+            body,
+            query: { dry_run: true },
+        });
+    }
+    /**
+     * Bulk-ingest a dataset as NDJSON. Each line is either a triplet or an
+     * `{type,name,properties}` entity-properties record; lines are batched into
+     * bounded internal commits server-side, so a whole dataset loads in one
+     * streamed request without a single oversized commit. Pass `lines` as an array
+     * (serialized to NDJSON here) or a pre-built NDJSON string.
+     */
+    import(lines, opts = {}) {
+        const ndjson = typeof lines === "string"
+            ? lines
+            : lines.map((line) => JSON.stringify(line)).join("\n");
+        return this.request("POST", "/v1/graph/import", {
+            rawBody: ndjson,
+            contentType: "application/x-ndjson",
+            query: { batch: opts.batch, strict: opts.strict, observed_at: opts.observedAt },
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /**
+     * Bulk-ingest N-Triples without client-side conversion. Resource-object
+     * triples become keyed Resource edges; literal-object triples become text
+     * properties on the subject Resource.
+     */
+    importRdf(ntriples, opts = {}) {
+        return this.request("POST", "/v1/graph/import/rdf", {
+            rawBody: ntriples,
+            contentType: "application/n-triples",
+            query: {
+                batch: opts.batch,
+                strict: opts.strict,
+                observed_at: opts.observedAt,
+                format: "ntriples",
+                resource_type: opts.resourceType,
+                edge_idempotency: opts.edgeIdempotency,
+            },
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /**
+     * Retract specific edges and/or every edge touching given entities. Appends
+     * superseding retract events rather than deleting — history stays visible in an
+     * `as_of` read before the retraction, but the edges drop out of current state.
+     * The surgical alternative to {@link deleteGraph}.
+     */
+    retract(body, opts = {}) {
+        return this.request("POST", "/v1/graph/retract", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? this.idempotencyKey("retract"),
+        });
+    }
+    /** Create the scoped graph/branch. Construct the client with the desired graph/branch first. */
+    createGraph() {
+        return this.request("POST", "/v1/graph/create");
+    }
+    /** Fork the scoped branch from an existing branch in the same graph. */
+    createBranch(body) {
+        return this.request("POST", "/v1/graph/branch", { body });
+    }
+    /**
+     * Delete every object under the scoped graph/branch — a destructive reset.
+     * `confirm` must equal the scoped graph id; the next commit re-initializes the
+     * graph. Branch-scoped: sibling branches are untouched.
+     */
+    deleteGraph(opts) {
+        return this.request("POST", "/v1/graph/delete", { query: { confirm: opts.confirm } });
+    }
+    // --- search ---
+    /** Full semantic hybrid search from a request body (`POST /v1/graph/search`). */
+    graphSearch(body) {
+        return this.request("POST", "/v1/graph/search", { body });
+    }
+    /** Reciprocal-rank-fusion across sub-queries. */
+    multiSearch(body) {
+        return this.request("POST", "/v1/search/multi", { body });
+    }
+    /**
+     * Append relevance labels for a set of search results — how Little Big Brain
+     * gathers customer-specific qrels. Grade results (3 ideal/good, 1 partial,
+     * 0 bad), referencing the search response's `search_id` so labels tie back to
+     * that ranking. Stored apart from customer facts and exported via
+     * {@link searchFeedbackExport} as training/eval data for embedding fine-tuning.
+     */
+    searchFeedback(body, opts = {}) {
+        return this.request("POST", "/v1/search/feedback", {
+            body,
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /** Export the stored relevance labels as qrels-style rows for training. */
+    searchFeedbackExport() {
+        return this.request("GET", "/v1/search/feedback/export");
+    }
+    /** BM25 search. */
+    fullTextSearch(body) {
+        return this.request("POST", "/v1/search/full-text", { body });
+    }
+    /** ANN/vector search. */
+    embeddingSearch(body) {
+        return this.request("POST", "/v1/search/embedding", { body });
+    }
+    // --- traversal ---
+    /** Bounded k-hop graph traversal. */
+    traverse(body) {
+        return this.request("POST", "/v1/graph/traverse", { body });
+    }
+    /** Resolve a query to seed entities, then return bounded paths. */
+    semanticTraverse(body) {
+        return this.request("POST", "/v1/graph/semantic-traverse", { body });
+    }
+    /** Ranked incoming/outgoing neighborhood for a graph entity. */
+    entityNeighborhood(opts) {
+        return this.request("GET", "/v1/graph/entity/neighborhood", {
+            query: {
+                id: opts.id,
+                type: opts.type,
+                name: opts.name,
+                relations: opts.relations?.join(","),
+                as_of: opts.asOf,
+            },
+        });
+    }
+    /** Stored entity object-ref status and index-coverage metadata (no
+     * attributes — read those from `entityDetail`'s top-level `attributes`). */
+    entityMetadata(opts) {
+        return this.request("GET", "/v1/graph/entity/metadata", {
+            query: {
+                id: opts.id,
+                type: opts.type,
+                name: opts.name,
+                as_of: opts.asOf,
+            },
+        });
+    }
+    /**
+     * Entity detail: metadata, attributes, current state, edge history, and
+     * observations. Pass `asOf` / `asOfCommitSeq` to reproduce the node as of a
+     * past instant / commit (the state, edges, and history are pinned to it).
+     */
+    entityDetail(opts) {
+        return this.request("GET", "/v1/graph/entity", {
+            query: {
+                id: opts.id,
+                type: opts.type,
+                name: opts.name,
+                as_of: opts.asOf,
+                as_of_commit_seq: opts.asOfCommitSeq,
+            },
+        });
+    }
+    /**
+     * Paged edge listing. Scope to one node with `id` (or `type`+`name`) and a
+     * `direction` (`out`/`in`/`both`) to walk **every** edge of a high-degree node
+     * — `entityDetail` returns the full set but is awkward to page; this carries
+     * `offset`/`limit` and reports `total_count`. Optional `relation`/`q` filters
+     * and an `asOf`/`asOfCommitSeq` snapshot pin. Each row carries `valid_time`, so
+     * the page is enough to reconstruct a per-edge timeline.
+     */
+    graphEdges(opts = {}) {
+        return this.request("GET", "/v1/graph/edges", {
+            query: {
+                id: opts.id,
+                type: opts.type,
+                name: opts.name,
+                direction: opts.direction,
+                relation: opts.relation,
+                q: opts.q,
+                limit: opts.limit,
+                cursor: opts.cursor,
+                offset: opts.offset,
+                as_of: opts.asOf,
+                as_of_commit_seq: opts.asOfCommitSeq,
+            },
+        });
+    }
+    /**
+     * Page through every row of a list endpoint, following `next_cursor` until
+     * exhausted. Pass a fetcher that takes a cursor and returns a
+     * {@link ListResponse}:
+     * ```ts
+     * for await (const e of client.listAll((cursor) =>
+     *   client.entities.list({ cursor, fields: "title" }))) { … }
+     * ```
+     */
+    async *listAll(fetchPage) {
+        let cursor;
+        for (;;) {
+            const page = await fetchPage(cursor);
+            for (const row of page.data)
+                yield row;
+            if (!page.has_more || page.next_cursor == null)
+                return;
+            cursor = page.next_cursor;
+        }
+    }
+    // --- temporal / lineage / shapes ---
+    /** Current state of an entity's relations, optionally as-of a timestamp. */
+    currentState(body) {
+        return this.request("POST", "/v1/query/state", { body });
+    }
+    /** Full edge-event history for a relationship. */
+    history(body) {
+        return this.request("POST", "/v1/query/history", { body });
+    }
+    /** Ordered state-transition log for an entity's relation, with dwell time. */
+    transitions(body) {
+        return this.request("POST", "/v1/query/transitions", { body });
+    }
+    /** Lineage and evidence for a single edge. */
+    why(body) {
+        return this.request("POST", "/v1/query/why", { body });
+    }
+    /** SHACL-style shape/pattern query. */
+    shacl(body) {
+        return this.request("POST", "/v1/query/shacl", { body });
+    }
+    /**
+     * SPARQL-subset SELECT/ASK/aggregate query (FILTER, HAVING, ORDER BY, ASK,
+     * COUNT/SUM/AVG/MIN/MAX). GROUP BY is not limited to entity identity:
+     * `group_by` keys on a variable's entity, and `group_keys` adds typed scalar
+     * keys — a `property` value, or a `date_bucket` calendar truncation
+     * (`year`/`month`/`week`/`day`/`hour`) of a datetime property — so a
+     * per-category breakdown or a time series is one server-side query. Scalar
+     * keys come back per group in `groups[].value_keys[<as>]`, entity keys in
+     * `groups[].keys`.
+     */
+    sparql(body) {
+        return this.request("POST", "/v1/query/sparql", { body });
+    }
+    /** SPARQL 1.1 query from text (SELECT/ASK) over the live graph; `results` is SPARQL 1.1 Query Results JSON. */
+    sparqlText(body) {
+        return this.request("POST", "/v1/query/sparql-text", { body });
+    }
+    /**
+     * Run a SPARQL 1.1 text query and return parsed results — the ergonomic
+     * complement to {@link sparqlText} (which hands back the raw results string).
+     * Returns `{ vars, boolean, bindings, rows }` via {@link parseSparqlResults}:
+     * `rows` is the bindings flattened to `{ variable: lexicalValue }`, `boolean`
+     * is the ASK answer (or `null` for a SELECT).
+     */
+    async sparqlRows(body) {
+        return parseSparqlResults(await this.sparqlText(body));
+    }
+    /**
+     * Basic-graph-pattern query with group-graph-pattern combinators
+     * (UNION / OPTIONAL / MINUS / EXISTS / NOT EXISTS) folded over the base
+     * patterns. The complement to {@link sparql}: this route carries the
+     * combinators (but not FILTER/aggregation), so use it when a query needs an
+     * optional/union/negated leg rather than a grouped aggregate.
+     */
+    analytics(body) {
+        return this.request("POST", "/v1/query/analytics", { body });
+    }
+    /**
+     * Run inference rules (SHACL-AF `sh:TripleRule` shape) to a bounded fixpoint
+     * and return the derived edges as a **preview** — derived facts are never
+     * written to the asserted graph. Each rule is a BGP `body`/`where` plus a
+     * `head` triple template instantiated per binding.
+     */
+    infer(body) {
+        return this.request("POST", "/v1/inference/run", { body });
+    }
+    /**
+     * Define (replace) the versioned rule set stored on the scoped graph branch.
+     * The stored set is what SHACL `include_derived` and `infer` use when a
+     * request carries no inline rules. Returns the new `rules_version`.
+     */
+    defineRules(body) {
+        return this.request("POST", "/v1/inference/rules", { body });
+    }
+    /** The rule set stored on the scoped graph branch (version + rules). */
+    graphRules() {
+        return this.request("GET", "/v1/inference/rules");
+    }
+    /**
+     * Stage G — derive edges from calibrated retrieval matches (preview): each
+     * candidate scored `P >= threshold` becomes a derived edge `(anchor, relation,
+     * matched)` with a typed `Retrieval` provenance leaf. Pass either explicit
+     * `candidates` or a `query` the server runs as BM25 entity retrieval.
+     */
+    retrievalPremises(body) {
+        return this.request("POST", "/v1/inference/retrieval-premises", { body });
+    }
+    // --- ontology ---
+    /**
+     * The active ontology (entity types and relations) for the scoped graph.
+     * Pass `{ counts: true }` to include a per-relation current-edge count
+     * (`OntologyRelationView.edge_count`) so a caller can see which declared
+     * relations are actually populated — at the cost of a snapshot load.
+     */
+    ontologyView(opts = {}) {
+        return this.request("GET", "/v1/ontology", {
+            query: opts.counts ? { counts: true } : undefined,
+        });
+    }
+    /**
+     * Audit the current snapshot against the ontology's *implied* constraints —
+     * capped `cardinality` derived as `sh:maxCount` — returning a SHACL-shaped
+     * report. Whole-snapshot and never blocks a write. Unlike
+     * {@link SchemaNamespace.audit}, this needs no published shape bundle: the
+     * shapes come from the ontology itself. See the `decoration_status` catalog on
+     * {@link ontologyView} for which decorations are enforced.
+     */
+    ontologyConformance() {
+        return this.request("GET", "/v1/ontology/conformance");
+    }
+    /** Discover ontology concepts, terms, and relations. */
+    ontologySearch(body) {
+        return this.request("POST", "/v1/ontology/search", { body });
+    }
+    /** Resolve mentions to concepts/entities. */
+    ontologyResolve(body) {
+        return this.request("POST", "/v1/ontology/resolve", { body });
+    }
+    /** Define the active ontology before the scoped graph's first commit. */
+    ontologyDefine(body) {
+        return this.request("POST", "/v1/ontology/define", { body });
+    }
+    /**
+     * Additively evolve the active ontology of an existing graph: widen relation
+     * domains/ranges and declare new entity types (all by name), bumping the
+     * ontology version. Additive-only — every existing record stays valid, so no
+     * migration is needed — and a request that changes nothing is a no-op.
+     */
+    evolveOntology(body) {
+        return this.request("POST", "/v1/ontology/evolve", { body });
+    }
+    // --- index lifecycle ---
+    /**
+     * Build default ANN + BM25 indexes. With `{ background: true }` the build
+     * runs detached on the server and the call returns immediately — use it for
+     * large corpora whose synchronous build would exceed a fronting gateway's
+     * timeout (a 504), then poll `metadata()` for completion.
+     */
+    indexBuild(opts = {}) {
+        return this.request("POST", "/v1/index/build", { query: { background: opts.background || undefined } });
+    }
+    /**
+     * Build BM25, ANN/vector, and adjacency index families. With
+     * `{ background: true }` the build runs detached on the server and the call
+     * returns immediately — use it for large corpora whose synchronous build would
+     * exceed a fronting gateway's timeout, then poll `metadata()` for completion.
+     */
+    indexRun(opts = {}) {
+        return this.request("POST", "/v1/index/run", { query: { background: opts.background || undefined } });
+    }
+    /** Append a BM25 delta segment for the unindexed WAL tail. */
+    indexDelta() {
+        return this.request("POST", "/v1/index/delta");
+    }
+    /** Preview or delete superseded persisted index runs. */
+    indexGc(opts = {}) {
+        return this.request("POST", "/v1/index/gc", {
+            query: { keep_runs: opts.keepRuns, dry_run: opts.dryRun },
+        });
+    }
+    /** Fold the WAL tail into snapshot segments. */
+    compact(opts = {}) {
+        return this.request("POST", "/v1/graph/compact", {
+            query: { min_tail_commits: opts.minTailCommits, max_segments: opts.maxSegments },
+        });
+    }
+    // --- inspection ---
+    /** Server, graph, and persisted-index status. */
+    status() {
+        return this.request("GET", "/v1/status");
+    }
+    /** Graph footprint, WAL tail, and index coverage. */
+    metadata() {
+        return this.request("GET", "/v1/graph/metadata");
+    }
+    /** Graph counts and type/relation buckets. */
+    summary() {
+        return this.request("GET", "/v1/graph/summary");
+    }
+    /** List the graphs (and branches) under the scoped tenant. */
+    listGraphs() {
+        return this.request("GET", "/v1/graphs");
+    }
+    // --- database admin ---
+    /** Create a database stack and return its one-time stack API key. */
+    adminCreateStack(body) {
+        return this.request("POST", "/api/admin/stacks", { body });
+    }
+    /** Inspect a database stack without returning secret key material. */
+    adminStack(slug) {
+        return this.request("GET", "/api/admin/stacks", { query: { stack: slug } });
+    }
+    /** Rotate a database stack key and return the new one-time API key. */
+    adminRotateStackKey(slug) {
+        return this.request("POST", "/api/admin/stacks/rotate-key", { query: { stack: slug } });
+    }
+    /** Delete a database stack after confirming the slug. */
+    adminDeleteStack(slug) {
+        return this.request("DELETE", "/api/admin/stacks", { query: { stack: slug, confirm: slug } });
+    }
+    /**
+     * Mint a short-lived `lbb_ses_…` session token for an account. A trusted
+     * co-located service uses it (with `?stack=<slug>`) to call the data plane on
+     * the account's behalf without handling the stack's mode-bearing stack key.
+     */
+    adminMintSession(accountId) {
+        return this.request("POST", "/api/admin/sessions", { body: { account_id: accountId } });
+    }
+    /** Customer-visible activity for one database stack. */
+    adminStackActivity(slug, window = "24h") {
+        return this.request("GET", "/api/admin/stacks/activity", { query: { stack: slug, window } });
+    }
+    /** Activity for the stack selected by the bearer stack key or session. */
+    stackActivity(window = "24h") {
+        return this.request("GET", "/v1/stack/activity", { query: { window } });
+    }
+}
+export class GraphNamespace {
+    client;
+    facts;
+    constructor(client) {
+        this.client = client;
+        this.facts = new FactsNamespace(client);
+    }
+    branch(name) {
+        return new GraphNamespace(this.client.withScope({ branch: name }));
+    }
+    create() {
+        return this.client.createGraph();
+    }
+    delete(opts) {
+        return this.client.deleteGraph(opts);
+    }
+    /** Retract edges/entities from the scoped graph. See {@link LbbClient.retract}. */
+    retract(body, opts = {}) {
+        return this.client.retract(body, opts);
+    }
+}
+export class FactsNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    create(body, opts = {}) {
+        return this.client.request("POST", "/v1/graph/commit", {
+            body,
+            idempotencyKey: opts.idempotencyKey ?? this.client.idempotencyKey("facts.create"),
+        });
+    }
+    /** Bulk-load a dataset as NDJSON. See {@link LbbClient.import}. */
+    import(lines, opts = {}) {
+        return this.client.import(lines, opts);
+    }
+    /**
+     * Bulk-load N-Triples through the native RDF import endpoint.
+     *
+     * Statements are committed through the fixed RDF_TRIPLE relation; source RDF
+     * predicates and literal term details are preserved as edge metadata.
+     */
+    importRdf(ntriples, opts = {}) {
+        return this.client.importRdf(ntriples, opts);
+    }
+}
+export class SearchNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    hybrid(input, opts = {}) {
+        if (typeof input !== "string") {
+            return this.client.request("POST", "/v1/graph/search", { body: input });
+        }
+        return this.client.request("GET", "/v1/search", {
+            query: {
+                query: input,
+                top_k: opts.topK,
+                source: opts.source,
+                consistency: opts.consistency,
+                lexical: opts.lexical,
+                bm25: opts.bm25,
+                vector: opts.vector,
+                targets: opts.targets?.join(","),
+                profile: opts.profile,
+                log_impression: opts.logImpression,
+            },
+        });
+    }
+    multi(body) {
+        return this.client.multiSearch(body);
+    }
+    feedback(body, opts = {}) {
+        return this.client.searchFeedback(body, opts);
+    }
+    feedbackExport() {
+        return this.client.searchFeedbackExport();
+    }
+    fullText(body) {
+        return this.client.fullTextSearch(body);
+    }
+    vector(body) {
+        return this.client.embeddingSearch(body);
+    }
+}
+export class SchemaNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Active graph schema bundle: ontology plus activated SHACL shapes. */
+    view(opts = {}) {
+        return this.client.request("GET", "/v1/schema", {
+            query: { audit: opts.audit || undefined },
+        });
+    }
+    /** Preview a proposed RDF/SHACL schema bundle and audit current data. */
+    preview(body) {
+        return this.client.request("POST", "/v1/schema/preview", { body });
+    }
+    /** Activate a previewed SHACL schema bundle for this graph branch. */
+    publish(body) {
+        return this.client.request("POST", "/v1/schema/publish", { body });
+    }
+    /** Audit current data against the active SHACL schema bundle. */
+    audit() {
+        return this.client.request("POST", "/v1/schema/audit");
+    }
+}
+export class IndexNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    run(opts = {}) {
+        const background = opts.background ?? (opts.wait === false ? true : undefined);
+        return this.client.request("POST", "/v1/index/run", {
+            query: { background },
+            body: opts.body,
+        });
+    }
+    build() {
+        return this.client.indexBuild();
+    }
+    delta() {
+        return this.client.indexDelta();
+    }
+    gc(opts = {}) {
+        return this.client.indexGc(opts);
+    }
+}
+export class EntityNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Browse entities as the unified list envelope. Pass `fields` (names or `*`)
+     * to inline each row's typed attributes as native JSON (under `attributes`) —
+     * "list entities and their titles" in one call instead of a list plus N point
+     * lookups — or `ids`
+     * to fetch a specific set. Page with `cursor` from the previous `next_cursor`.
+     */
+    list(opts = {}) {
+        const csv = (v) => Array.isArray(v) ? v.join(",") : v;
+        return this.client.request("GET", "/v1/graph/entities", {
+            query: {
+                type: opts.type,
+                limit: opts.limit,
+                cursor: opts.cursor,
+                offset: opts.offset,
+                q: opts.query,
+                fields: csv(opts.fields),
+                ids: csv(opts.ids),
+            },
+        });
+    }
+    get(opts) {
+        return this.client.entityMetadata(opts);
+    }
+    detail(opts) {
+        return this.client.entityDetail(opts);
+    }
+    /**
+     * Filter entities already bound by relation patterns using typed attributes,
+     * without writing RDF property IRIs by hand. This is a convenience wrapper over
+     * the structured SPARQL route: relation `patterns` bind variables, and `where`
+     * compares ontology property fields on those bound variables.
+     */
+    filterByAttributes(opts) {
+        const defaultVar = firstPatternVariable(opts.patterns);
+        const where = Array.isArray(opts.where) ? opts.where : [opts.where];
+        return this.client.sparql({
+            patterns: opts.patterns,
+            filters: [...(opts.filters ?? []), ...where.map((filter) => attributeFilter(filter, defaultVar))],
+            select: opts.select,
+            limit: opts.limit,
+            offset: opts.offset,
+            as_of_valid_time: opts.asOfValidTime,
+            as_of_commit_seq: opts.asOfCommitSeq,
+            order_by: opts.orderBy,
+            reason: opts.reason,
+            max_solutions: opts.maxSolutions,
+            max_object_reads: opts.maxObjectReads,
+            max_fetched_bytes: opts.maxFetchedBytes,
+        });
+    }
+}