@littlebigbrain/client 0.13.1 → 0.13.2

package/README.md

@@ -1,129 +1,144 @@
 # @littlebigbrain/client
 
-The typed TypeScript client for [Little Big Brain](https://littlebigbrain.com) — write graph facts and query one immutable published snapshot. Request and response types are generated from the API contract, so every call is fully typed. Runs anywhere there's a global `fetch`: Node 18+, browsers, and edge workers.
+TypeScript client for [little big brain](https://littlebigbrain.com), a search
+platform for AI applications such as chatbots, search tools, and agents.
+Load facts, query their relationships, and keep the data version behind an answer
+so you can check it later.
+
+The client has no runtime dependencies and includes generated request and response
+types. It uses `fetch` and supports Node.js 18+, browsers, and edge workers.
+Keep stack API keys on your server or local machine, outside browser bundles.
+
+[Documentation](https://docs.littlebigbrain.com/sdks/typescript/) ·
+[Quickstart](https://docs.littlebigbrain.com/start/quickstart/) ·
+[Issues](https://github.com/littlebigbrains/lbb-typescript/issues)
+
+## Install
 
 ```sh
 npm install @littlebigbrain/client
 ```
 
-## Quickstart
+## Load facts and run a query
+
+Create a stack in the [console](https://cloud.littlebigbrain.com) and open
+**Connect**. Copy its complete endpoint and a stack API key:
+
+```sh
+export LBB_URL="https://<your-complete-stack-host>"
+export LBB_API_KEY="<your-stack-api-key>"
+```
+
+This example creates a graph named `quickstart` on its first write. It stores
+three facts: a service writes to a database, and each has a label. The data uses
+Resource Description Framework (RDF), where each line names a subject, a
+relationship, and a value or another record. SPARQL is the query language for
+those facts.
+
+Save as `quickstart.mts`, then run `npx tsx quickstart.mts`:
 
 ```ts
 import { LbbClient } from "@littlebigbrain/client";
 
 const lbb = new LbbClient({
-  baseUrl: "https://0abc1def--production.db.eu.littlebigbrain.com",
-  apiKey: process.env.LBB_API_KEY, // lbb_sk_live_… — keep it server-side
+  baseUrl: process.env.LBB_URL!,
+  apiKey: process.env.LBB_API_KEY!,
+  graph: "quickstart",
 });
-const graph = lbb.graph("main");
-
-// 1. Write a fact.
-await graph.facts.create(
-  {
-    triplets: [
-      {
-        source: { type: "CONCEPT", name: "policy-42" },
-        relation: "RELATED_TO",
-        target: { type: "CONCEPT", name: "seven-year retention" },
-        evidence: "Customer records are retained for seven years.",
-      },
-    ],
-  },
-  { idempotencyKey: "policy-42-v1" },
-);
 
-// 2. Publication is automatic. Inspect one coherent watermark when needed.
-const published = await lbb.readSnapshot();
-console.log(published.snapshot.served_at_seq, published.query_lag_commits);
+const facts = `
+<https://example.org/auth-service> <https://example.org/writesTo> <https://example.org/user-db> .
+<https://example.org/auth-service> <http://www.w3.org/2000/01/rdf-schema#label> "Auth Service" .
+<https://example.org/user-db> <http://www.w3.org/2000/01/rdf-schema#label> "User Database" .
+`;
 
-// 3. Query the snapshot with SPARQL.
-const rows = await lbb.sparqlRows({
-  query: "SELECT ?s ?o WHERE { ?s <policy:retention> ?o } LIMIT 10",
+const imported = await lbb.graph("quickstart").facts.importRdf(facts, {
+  format: "ntriples",
+  idempotencyKey: "sdk-quickstart-v1",
 });
-```
-
-For hosted use, `baseUrl` is required and must be the exact `endpoint_url`
-shown on the stack's Connect page. Graph and branch remain client scope
-parameters; they are not encoded in the hostname.
-
-## Examples
-
-**Bulk import.** Load an array of records (or an NDJSON string) in one call:
-
-```ts
-await graph.facts.import(
-  [
-    { source: { type: "DOC", name: "handbook", key: "doc:42" }, relation: "HAS_PASSAGE", target: { type: "PASSAGE", name: "leave-policy", key: "p:42:1" } },
-    // …one record per line
-  ],
-  { idempotencyKey: "handbook-batch-1" },
+const commitSeq = imported.committed_commit_seq;
+if (commitSeq == null) throw new Error("The import did not return a commit sequence.");
+
+const query = `
+  SELECT ?service ?database WHERE {
+    ?s <https://example.org/writesTo> ?db .
+    ?s <http://www.w3.org/2000/01/rdf-schema#label> ?service .
+    ?db <http://www.w3.org/2000/01/rdf-schema#label> ?database .
+  } ORDER BY ?service ?database LIMIT 10
+`;
+
+const { rows } = await lbb.sparqlRows(
+  { query },
+  { consistency: "strong", minIndexedSeq: commitSeq },
 );
+
+for (const row of rows) console.log(`${row.service} -> ${row.database}`);
 ```
 
-For large or long-running loads, stream records to a durable job instead:
+On a fresh graph, this prints:
 
-```ts
-const accepted = await lbb.submitImport(records(), {
-  idempotencyKey: "hubspot:portal-42:run-2026-07-29",
-});
-const completed = await lbb.waitForImportJob(accepted.job_id);
-console.log(completed.state, completed.committed_commit_seq);
+```text
+Auth Service -> User Database
 ```
 
-`records()` may be an iterable or async iterable. Success means every grouped
-commit is durable and immediately queryable by a strong SPARQL read. The same
-commits advance the graph's coalesced RDF reconciliation fence; waiting for base
-compaction is optional. An empty iterable is rejected locally before an import
-POST is sent.
+The query follows the stored relationship between the service and database.
+`consistency: "strong"` makes the new facts available to this read without
+waiting for a background index job. Reads default to eventual consistency, so
+omit this option only when an earlier version is acceptable.
+
+The idempotency key makes repeating the same import safe. Use a new key if you
+change the data.
 
-For several RDF documents, `facts.importRdfMany(...)` automatically defers
-intermediate reconciliation and triggers it on the last document. Call
-`graph.waitForPublished(result.finalSequence)` only when the caller needs the
-immutable base itself to cover the import; strong reads need no waiter.
+## Read the same version again
 
-**Time-travel read.** Pin a SPARQL read to a past instant — results reflect the graph as it was then:
+Run the query at the commit returned by the import:
 
 ```ts
-const asOf = await lbb.sparqlRows({
-  query: "SELECT ?s ?o WHERE { ?s <policy:retention> ?o }",
-  as_of_valid_time: "2026-01-01T00:00:00Z",
+const replay = await lbb.sparqlRows({
+  query,
+  as_of_commit_seq: commitSeq,
 });
+console.log(replay.rows);
 ```
 
-**SPARQL.** `sparqlRows` runs a SPARQL 1.1 SELECT/ASK and returns parsed rows:
+Save the query, its options, and the commit sequence with any answer you need to
+check later. See [history and replay](https://docs.littlebigbrain.com/guides/time-travel-audit/)
+for retention and evidence handling.
 
-```ts
-const { rows } = await lbb.sparqlRows({
-  query: `SELECT ?doc WHERE { ?doc ?p ?o } LIMIT 10`,
-});
-```
+## Next steps
+
+- [Search by meaning](https://docs.littlebigbrain.com/guides/search-by-meaning/): choose which facts to embed and find records from a text description.
+- [Load your own RDF](https://docs.littlebigbrain.com/guides/load-rdf/): import Turtle, N-Triples, N-Quads, or TriG.
+- [Work with JSON records](https://docs.littlebigbrain.com/guides/without-rdf/): define a schema and write records without writing RDF.
+- [Validate writes](https://docs.littlebigbrain.com/guides/sparql-and-shacl/): define constraints with the Shapes Constraint Language (SHACL).
 
-## Errors & retries
+The RDF and JSON guides use different write workflows. Choose one when creating
+a graph; a graph first written through RDF import does not accept
+`facts.create` or JSON record imports.
 
-Methods return parsed JSON and throw `LbbError` (with `status`, `code`, `message`, `param`, `requestId`, `docUrl`) on any non-2xx response. Safe reads and idempotency-keyed writes retry `429`/`5xx` and network failures with full-jitter backoff, bounded by a retry budget (`retryBudgetMs`, default 60s) rather than a fixed count, and honor `Retry-After` — a terminal error the server marks non-retryable surfaces immediately. Use `rawRequest()` for response headers, request id, and retry/timing metadata.
-`waitForPublished(...)` is an optional, deadline-bounded maintenance poller for
-workflows that want the immutable RDF base itself to cover a commit. Strong
-SPARQL does not need it: acknowledged commits are queryable immediately from
-the branch head's base-plus-delta lineage.
+## Errors and retries
 
-## More
+Failed HTTP requests throw `LbbError`, with a status, error code, message, and
+request ID. Use `rawRequest()` when you also need response headers or timing.
 
-The `graph(...)` scope exposes `facts`, `entities`, `ontology`, `query`,
-`search` (feedback surfaces), and `schema` namespaces. `query` runs SPARQL,
-the one query language on the API; `schema`
-reads or atomically publishes the active ontology/shapes bundle. Writes enqueue
-published-generation maintenance automatically. Every generated shape is
-available as `Schemas["TypeName"]`. Retired request-time JSON SHACL DTOs are
-intentionally absent: publish RDF shapes with `schema.publish`, then read
-`ontology.conformance`.
+Safe reads and writes with an idempotency key retry rate limits, retryable server
+errors, and network failures. Retries respect `Retry-After` and use a 60-second
+budget by default. See the [client reference](https://docs.littlebigbrain.com/sdks/typescript/)
+for timeout and retry options.
 
-Full reference and guides: [docs.littlebigbrain.com/sdks/typescript](https://docs.littlebigbrain.com/sdks/typescript/).
+## Development
 
-## Develop
+From a clone of this repository:
 
 ```sh
-npm install
-npm run generate    # regenerate types from contracts/openapi.json
+npm ci
 npm run typecheck
 npm test
 ```
+
+The request and response types are generated from the API contract. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for changes to generated types.
+
+## License
+
+[Apache-2.0](LICENSE).

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { DurableImportSource, ImportLine, LbbClientOptions, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults } from "./types.js";
 import { type CallOptions, type RequestOptions } from "./transport.js";
-import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace } from "./namespaces.js";
+import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, EvalsNamespace, EmbeddingsNamespace } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export type { AttributeFilter, AttributeFilterOp, AttributeFilterValue, EntityAttributeFilterOptions, EntityPropertiesLine, DurableImportLine, DurableImportSource, FetchLike, FlatProperties, ImportLine, LbbClientOptions, LbbRequestEvent, LbbResponseEvent, LbbRetryEvent, LbbErrorPayload, ListResponse, RawLbbResponse, ReadConsistencyOptions, RdfImportDocument, RdfImportManyResult, RdfImportOptions, Schemas, SearchConsistency, SparqlResults, SparqlResultsJson, SparqlTerm, CommitRequest, CommitResponse, Entity, EntitySelector, GraphMetadata, GraphSummary, SchemaView, Snapshot, } from "./types.js";
 export { LbbCapabilityError, LbbError } from "./transport.js";
@@ -34,6 +34,8 @@ export declare class LbbClient {
     readonly schema: SchemaNamespace;
     readonly ontology: OntologyNamespace;
     readonly query: QueryNamespace;
+    readonly evals: EvalsNamespace;
+    readonly embeddings: EmbeddingsNamespace;
     constructor(options: LbbClientOptions);
     graph(name: string, opts?: {
         branch?: string;
@@ -467,6 +469,9 @@ export declare class LbbClient {
     }): Promise<Schemas["GraphMetadataResponse"]>;
     /** Automatic publication lifecycle, available before the first generation exists. */
     publicationStatus(): Promise<Schemas["PublicationStatusResponse"]>;
+    /** The managed models the platform uses per role (embedding, judge,
+     * rewriter): the operator's catalog, or the compiled defaults. */
+    managedModels(): Promise<Schemas["ManagedModelsResponse"]>;
     /** Wait until background reconciliation folds `targetSeq` into the RDF base. */
     waitForPublished(targetSeq: number, opts?: {
         timeoutMs?: number;

package/dist/client.js

@@ -1,7 +1,7 @@
 import { parseSparqlResults } from "./types.js";
 import { bodyMarksTerminal, errorCodeFromBody, fullJitterBackoffMs, parseLbbError, parseResponseJson, retryAllowed, retryableStatus, retryDelayMs, sleep, } from "./transport.js";
 import { LbbCapabilityError } from "./transport.js";
-import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
+import { EntityNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, EvalsNamespace, EmbeddingsNamespace, } from "./namespaces.js";
 export { parseSparqlResults } from "./types.js";
 export { LbbCapabilityError, LbbError } from "./transport.js";
 export { EntityNamespace, FactsNamespace, GraphNamespace, OntologyNamespace, QueryNamespace, SchemaNamespace, SearchNamespace, } from "./namespaces.js";
@@ -110,6 +110,8 @@ export class LbbClient {
     schema;
     ontology;
     query;
+    evals;
+    embeddings;
     constructor(options) {
         const baseUrl = options.baseUrl?.trim();
         if (!baseUrl) {
@@ -152,6 +154,8 @@ export class LbbClient {
         this.schema = new SchemaNamespace(this);
         this.ontology = new OntologyNamespace(this);
         this.query = new QueryNamespace(this);
+        this.evals = new EvalsNamespace(this);
+        this.embeddings = new EmbeddingsNamespace(this);
     }
     graph(name, opts = {}) {
         return new GraphNamespace(this.withScope({
@@ -1069,6 +1073,11 @@ export class LbbClient {
     publicationStatus() {
         return this.request("GET", "/v1/graph/publication-status");
     }
+    /** The managed models the platform uses per role (embedding, judge,
+     * rewriter): the operator's catalog, or the compiled defaults. */
+    managedModels() {
+        return this.request("GET", "/v1/managed-models");
+    }
     /** Wait until background reconciliation folds `targetSeq` into the RDF base. */
     async waitForPublished(targetSeq, opts = {}) {
         if (!Number.isSafeInteger(targetSeq) || targetSeq < 0) {

package/dist/namespaces.d.ts

@@ -9,6 +9,8 @@ export declare class GraphNamespace {
     readonly query: QueryNamespace;
     readonly schema: SchemaNamespace;
     readonly search: SearchNamespace;
+    readonly evals: EvalsNamespace;
+    readonly embeddings: EmbeddingsNamespace;
     constructor(client: LbbClient);
     branch(name: string): GraphNamespace;
     /** Publication lifecycle for this graph/branch, including pre-first-publish state. */
@@ -51,7 +53,7 @@ export declare class FactsNamespace {
 }
 /**
  * Relevance-label storage. The query surfaces this namespace once fronted were
- * removed with their routes; SPARQL is the only query path now.
+ * removed with their routes; search by meaning is `embeddings.search`.
  */
 export declare class SearchNamespace {
     private readonly client;
@@ -86,6 +88,88 @@ export declare class EntityNamespace {
      */
     filterByAttributes(opts: EntityAttributeFilterOptions): Promise<Schemas["SparqlSelectResponse"]>;
 }
+/**
+ * Search: embeddings declared on classes of the graph. The platform keeps the
+ * vectors in step with the published graph; a search checks every hit against
+ * one graph snapshot.
+ */
+export declare class EmbeddingsNamespace {
+    private readonly client;
+    constructor(client: LbbClient);
+    /** Every embedding of the branch with its status. */
+    list(opts?: CallOptions): Promise<Schemas["EmbeddingListResponse"]>;
+    /** One embedding: serving and building version, backfill, lag, recall. */
+    get(name: string, opts?: CallOptions): Promise<Schemas["EmbeddingStatus"]>;
+    /**
+     * Declare or change the embedding of a class. Without `from` the server
+     * picks the fields (the label, frequent text, the names of linked
+     * entities). A new recipe builds as a new version while the old one serves.
+     */
+    declare(body: Schemas["EmbeddingDeclareRequest"], opts?: CallOptions): Promise<Schemas["EmbeddingStatus"]>;
+    /**
+     * What a declaration would embed: the fields, every candidate fact of the
+     * class with its coverage and examples, and sample texts. Calls no model.
+     */
+    preview(body: Schemas["EmbeddingPreviewRequest"], opts?: CallOptions): Promise<Schemas["EmbeddingPreviewResponse"]>;
+    /**
+     * Move every embedding of the graph to another model (one model per
+     * graph). Each builds a new version; the graph switches at once when
+     * every embedding has it ready, so a search never mixes two models.
+     */
+    setModel(body: Schemas["EmbeddingModelRequest"], opts?: CallOptions): Promise<Schemas["EmbeddingListResponse"]>;
+    /** Run one bounded step of the embed job now. */
+    refresh(name: string, opts?: CallOptions): Promise<Schemas["EmbeddingRefreshResponse"]>;
+    /** Remove an embedding. */
+    delete(name: string, opts?: CallOptions): Promise<unknown>;
+    /**
+     * Search by meaning over every searchable class of the graph (or one
+     * `embedding`). `filter` lists the conditions every hit must meet:
+     * `{ class: iri }` (or a list; subclasses too) and
+     * `{ via: "calls", to: "payment-service", direction?: "in" }` (`to` an IRI
+     * or a name). Every hit carries its class and is checked against one
+     * graph snapshot; `include: ["text"]` returns the embedded text of each
+     * hit; `explain: true` plans without running.
+     */
+    search(body: Schemas["SearchRequest"], opts?: CallOptions): Promise<Schemas["SearchResponse"]>;
+}
+/** Managed evals: traces, labels (thumbs up or down), goldens, and runs. */
+export declare class EvalsNamespace {
+    private readonly client;
+    constructor(client: LbbClient);
+    /** Settings, golden counts, unlabeled traces, the latest run, and the score by commit. */
+    summary(opts?: CallOptions): Promise<Schemas["EvalSummaryResponse"]>;
+    /** Recent traces, newest first. */
+    traces(options?: {
+        limit?: number;
+        unlabeled?: boolean;
+    } & CallOptions): Promise<Schemas["EvalTraceListResponse"]>;
+    /** One trace: the request, its query, its results (one item per hit or
+     * row), and their labels. */
+    trace(id: string, opts?: CallOptions): Promise<Schemas["EvalTrace"]>;
+    /** Thumbs up or down on results of a trace: one result as `item` +
+     * `valid`, or several in `items`. The labels become the golden's ground
+     * truth. */
+    label(traceId: string, body: Schemas["EvalLabelRequest"], opts?: CallOptions): Promise<Schemas["EvalLabelResponse"]>;
+    /** Let the managed judge label the results of one trace, or of a batch of
+     * traces with unlabeled results. */
+    judge(options?: {
+        traceId?: string;
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EvalJudgeResponse"]>;
+    goldens(opts?: CallOptions): Promise<Schemas["GoldenSuite"]>;
+    /** Freeze a query: every result it returns now is relevant. */
+    createGolden(body: Schemas["GoldenCreateRequest"], opts?: CallOptions): Promise<Schemas["GoldenResponse"]>;
+    /** Accept the results a golden returns now as its reference. */
+    acceptGolden(id: string, opts?: CallOptions & Pick<ReadConsistencyOptions, "consistency">): Promise<Schemas["GoldenResponse"]>;
+    deleteGolden(id: string, opts?: CallOptions): Promise<Schemas["GoldenDeleteResponse"]>;
+    /** Replay every golden at the current commit. */
+    run(opts?: CallOptions & Pick<ReadConsistencyOptions, "consistency">): Promise<Schemas["EvalRunResponse"]>;
+    results(options?: {
+        limit?: number;
+    } & CallOptions): Promise<Schemas["EvalResultsListResponse"]>;
+    settings(opts?: CallOptions): Promise<Schemas["EvalSettings"]>;
+    setSettings(body: Schemas["EvalSettings"], opts?: CallOptions): Promise<Schemas["EvalSettings"]>;
+}
 /** Active ontology/SHACL bundle metadata and atomic publication. */
 export declare class SchemaNamespace {
     private readonly client;

package/dist/namespaces.js

@@ -1,6 +1,7 @@
 import { attributeFilter, firstPatternVariable, parseSparqlResults, } from "./types.js";
-// SPARQL is the only query surface. The search, embedding, decode,
-// groundability, and analytics operations were removed with their routes.
+// SPARQL is the query language. Search by meaning is `embeddings.search`
+// (`POST /v1/search`); the older search, embedding, decode, groundability,
+// and analytics operations were removed with their routes.
 /** A5: fold read-consistency options into a request body's `consistency` /
  * `min_indexed_seq` fields; a per-call value wins over the client default. */
 function withReadConsistency(client, body, opts) {
@@ -23,6 +24,8 @@ export class GraphNamespace {
     query;
     schema;
     search;
+    evals;
+    embeddings;
     constructor(client) {
         this.client = client;
         this.facts = new FactsNamespace(client);
@@ -31,6 +34,8 @@ export class GraphNamespace {
         this.query = client.query;
         this.schema = client.schema;
         this.search = client.search;
+        this.evals = client.evals;
+        this.embeddings = client.embeddings;
     }
     branch(name) {
         return new GraphNamespace(this.client.withScope({ branch: name }));
@@ -135,7 +140,7 @@ export class FactsNamespace {
 }
 /**
  * Relevance-label storage. The query surfaces this namespace once fronted were
- * removed with their routes; SPARQL is the only query path now.
+ * removed with their routes; search by meaning is `embeddings.search`.
  */
 export class SearchNamespace {
     client;
@@ -199,6 +204,173 @@ export class EntityNamespace {
         });
     }
 }
+/**
+ * Search: embeddings declared on classes of the graph. The platform keeps the
+ * vectors in step with the published graph; a search checks every hit against
+ * one graph snapshot.
+ */
+export class EmbeddingsNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Every embedding of the branch with its status. */
+    list(opts = {}) {
+        return this.client.request("GET", "/v1/embeddings", opts);
+    }
+    /** One embedding: serving and building version, backfill, lag, recall. */
+    get(name, opts = {}) {
+        return this.client.request("GET", "/v1/embeddings", {
+            ...opts,
+            query: { name },
+        });
+    }
+    /**
+     * Declare or change the embedding of a class. Without `from` the server
+     * picks the fields (the label, frequent text, the names of linked
+     * entities). A new recipe builds as a new version while the old one serves.
+     */
+    declare(body, opts = {}) {
+        return this.client.request("PUT", "/v1/embeddings", { ...opts, body });
+    }
+    /**
+     * What a declaration would embed: the fields, every candidate fact of the
+     * class with its coverage and examples, and sample texts. Calls no model.
+     */
+    preview(body, opts = {}) {
+        return this.client.request("POST", "/v1/embeddings/preview", {
+            ...opts,
+            body,
+        });
+    }
+    /**
+     * Move every embedding of the graph to another model (one model per
+     * graph). Each builds a new version; the graph switches at once when
+     * every embedding has it ready, so a search never mixes two models.
+     */
+    setModel(body, opts = {}) {
+        return this.client.request("PUT", "/v1/embeddings/model", {
+            ...opts,
+            body,
+        });
+    }
+    /** Run one bounded step of the embed job now. */
+    refresh(name, opts = {}) {
+        return this.client.request("POST", "/v1/embeddings/refresh", {
+            ...opts,
+            query: { name },
+        });
+    }
+    /** Remove an embedding. */
+    delete(name, opts = {}) {
+        return this.client.request("DELETE", "/v1/embeddings", {
+            ...opts,
+            query: { name, confirm: name },
+        });
+    }
+    /**
+     * Search by meaning over every searchable class of the graph (or one
+     * `embedding`). `filter` lists the conditions every hit must meet:
+     * `{ class: iri }` (or a list; subclasses too) and
+     * `{ via: "calls", to: "payment-service", direction?: "in" }` (`to` an IRI
+     * or a name). Every hit carries its class and is checked against one
+     * graph snapshot; `include: ["text"]` returns the embedded text of each
+     * hit; `explain: true` plans without running.
+     */
+    search(body, opts = {}) {
+        return this.client.request("POST", "/v1/search", {
+            ...opts,
+            retry: opts.retry ?? true,
+            body,
+        });
+    }
+}
+/** Managed evals: traces, labels (thumbs up or down), goldens, and runs. */
+export class EvalsNamespace {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Settings, golden counts, unlabeled traces, the latest run, and the score by commit. */
+    summary(opts = {}) {
+        return this.client.request("GET", "/v1/evals", opts);
+    }
+    /** Recent traces, newest first. */
+    traces(options = {}) {
+        const { limit, unlabeled, ...opts } = options;
+        return this.client.request("GET", "/v1/evals/traces", {
+            ...opts,
+            query: { limit, unlabeled: unlabeled ? "true" : undefined },
+        });
+    }
+    /** One trace: the request, its query, its results (one item per hit or
+     * row), and their labels. */
+    trace(id, opts = {}) {
+        return this.client.request("GET", "/v1/evals/trace", {
+            ...opts,
+            query: { id },
+        });
+    }
+    /** Thumbs up or down on results of a trace: one result as `item` +
+     * `valid`, or several in `items`. The labels become the golden's ground
+     * truth. */
+    label(traceId, body, opts = {}) {
+        return this.client.request("POST", "/v1/evals/label", {
+            ...opts,
+            query: { trace: traceId },
+            body,
+        });
+    }
+    /** Let the managed judge label the results of one trace, or of a batch of
+     * traces with unlabeled results. */
+    judge(options = {}) {
+        const { traceId, limit, ...opts } = options;
+        return this.client.request("POST", "/v1/evals/judge", {
+            ...opts,
+            query: { trace: traceId, limit },
+        });
+    }
+    goldens(opts = {}) {
+        return this.client.request("GET", "/v1/evals/goldens", opts);
+    }
+    /** Freeze a query: every result it returns now is relevant. */
+    createGolden(body, opts = {}) {
+        return this.client.request("POST", "/v1/evals/goldens", { ...opts, body });
+    }
+    /** Accept the results a golden returns now as its reference. */
+    acceptGolden(id, opts = {}) {
+        return this.client.request("POST", "/v1/evals/goldens/accept", {
+            ...opts,
+            query: { id, consistency: opts.consistency },
+        });
+    }
+    deleteGolden(id, opts = {}) {
+        return this.client.request("DELETE", "/v1/evals/goldens", {
+            ...opts,
+            query: { id },
+        });
+    }
+    /** Replay every golden at the current commit. */
+    run(opts = {}) {
+        return this.client.request("POST", "/v1/evals/run", {
+            ...opts,
+            query: { consistency: opts.consistency },
+        });
+    }
+    results(options = {}) {
+        const { limit, ...opts } = options;
+        return this.client.request("GET", "/v1/evals/results", {
+            ...opts,
+            query: { limit },
+        });
+    }
+    settings(opts = {}) {
+        return this.client.request("GET", "/v1/evals/settings", opts);
+    }
+    setSettings(body, opts = {}) {
+        return this.client.request("PUT", "/v1/evals/settings", { ...opts, body });
+    }
+}
 /** Active ontology/SHACL bundle metadata and atomic publication. */
 export class SchemaNamespace {
     client;