@littlebigbrain/client 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @lbb/client
+
+TypeScript client for the [Little Big Brain](../../README.md) graph + hybrid search HTTP
+API. Request and response types are generated from the committed
+[`contracts/openapi.json`](../../contracts/openapi.json) (the single source of
+truth, derived from the Rust `lbb-api` types); the client itself is a thin,
+dependency-free wrapper over the platform `fetch`.
+
+```sh
+npm install @lbb/client
+```
+
+## Usage
+
+```ts
+import { LbbClient, LbbError } from "@lbb/client";
+
+const lbb = new LbbClient({
+  baseUrl: "https://db.eu.littlebigbrain.com",
+  apiKey: process.env.LBB_API_KEY, // lbb_sk_test_… or lbb_sk_live_…
+});
+
+await lbb.graph("main").facts.create({
+  triplets: [
+    {
+      source: { type: "SERVICE", name: "auth-service" },
+      relation: "WRITES_TO",
+      target: { type: "DATABASE", name: "user-db" },
+      confidence: 0.93,
+      evidence: "auth-service writes identity records to user-db",
+    },
+  ],
+}, {
+  idempotencyKey: "import-2026-06-13",
+});
+
+await lbb.indexes.run({ wait: true });
+
+const results = await lbb.search.hybrid("which systems store customer identity data", {
+  topK: 5,
+  source: "persisted",
+  consistency: "strong",
+  targets: ["entities", "assertions"],
+});
+for (const assertion of results.assertions ?? []) {
+  console.log(assertion.relation?.name, assertion.score);
+}
+```
+
+Use `client.graph("name")` to scope graph writes and `client.rawRequest(...)`
+when you need response metadata (`requestId`, `version`, headers). Every method
+returns parsed JSON and throws `LbbError` with `status`, `type`, `code`,
+`message`, `param`, `requestId`, and `docUrl` on a non-2xx response.
+
+## Methods
+
+| Area | Methods |
+| --- | --- |
+| Write | `graph("main").facts.create` |
+| Search | `search.hybrid`, `search.multi`, `search.fullText`, `search.vector` |
+| Search feedback (training data) | `searchFeedback` (grade results 3/1/0 → customer qrels), `searchFeedbackExport` |
+| Traversal | `traverse`, `semanticTraverse` |
+| Temporal / lineage / shapes | `currentState`, `history`, `why`, `shacl` |
+| SPARQL | `sparqlRows`, `sparql` (SELECT/ASK/aggregate; GROUP BY entity, property, or date bucket), `sparqlText`, `analytics` |
+| Ontology | `ontologyView` (add `{ counts: true }` for per-relation `edge_count`), `ontologySearch`, `ontologyResolve`, `ontologyDefine` |
+| Index lifecycle | `indexes.run`, `indexes.build`, `indexes.delta`, `indexes.gc`, `compact` |
+| Inspection | `entities.list`, `entities.filterByAttributes`, `status`, `metadata`, `summary` |
+| Schema activation | `schema.view`, `schema.preview`, `schema.publish`, `schema.audit` |
+| Database admin | `adminCreateStack`, `adminStack`, `adminRotateStackKey`, `adminDeleteStack` |
+
+Request/response shapes are exported as `Schemas["TypeName"]` (e.g.
+`Schemas["SemanticGraphSearchRequest"]`); the raw generated `components`,
+`paths`, and `operations` are exported too.
+
+## SPARQL
+
+`client.sparqlRows(...)` runs a SPARQL 1.1 text query (SELECT or ASK) and
+returns parsed results, so you never have to `JSON.parse` the results string or
+zip `head.vars` with binding values yourself:
+
+```ts
+const { vars, rows } = await client.sparqlRows({
+  query: `SELECT ?service ?db WHERE {
+            ?service <https://littlebigbrain.com/r/writes_to> ?db
+          } LIMIT 10`,
+  reason: true, // optional: fold in rule-derived edges
+});
+for (const row of rows) console.log(row.service, "->", row.db);
+
+const exists = (await client.sparqlRows({ query: "ASK { ?s ?p ?o }" })).boolean;
+```
+
+For app code that already has relation patterns but just needs typed attribute
+predicates, `client.entities.filterByAttributes(...)` builds the structured
+SPARQL filter body without exposing RDF property IRIs:
+
+```ts
+await client.entities.filterByAttributes({
+  patterns: [{ subject: { var: "service" }, predicate: "WRITES_TO", object: { var: "db" } }],
+  where: [{ field: "slo", op: "ge", value: 0.99 }, { var: "db", field: "tier", value: "prod" }],
+  select: ["service"],
+});
+```
+
+`sparqlRows` returns `{ vars, boolean, bindings, rows }`: `rows` is the bindings
+flattened to `{ variable: lexicalValue }`, `bindings` keeps the raw typed term
+objects, and `boolean` is the ASK answer (or `null` for a SELECT). `client.sparqlText(...)`
+returns the unparsed envelope, and the standalone `parseSparqlResults(response)`
+helper (also exported) parses it. For the structured BGP form use
+`client.sparql(body)` (`SparqlSelectRequest`).
+
+A standalone stack also serves the **native SPARQL 1.1 Protocol** at `/sparql`
+(`GET ?query=`, `POST` form or `application/sparql-query` body,
+`Accept`-negotiated JSON/XML/CSV/TSV) for off-the-shelf SPARQL clients (YASGUI,
+Protégé); `sparqlRows` returns parsed JSON rows for in-process use.
+
+## Develop
+
+```sh
+npm install
+npm run generate   # regenerate src/schema.ts from ../../contracts/openapi.json
+npm run build      # tsc -> dist/
+npm test           # build + node:test (mocked fetch)
+```
+
+`runtime`: any environment with a global `fetch` (Node 18+, browsers, edge
+workers), or pass your own via the `fetch` option.