@kortexya/reasoninglayer 5.0.0 → 5.1.0

package/dist/index.js

@@ -5,7 +5,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "5.0.0";
+var SDK_VERSION = "5.1.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -950,6 +950,8 @@ function toSnakeCase(input) {
 
 // src/http.ts
 var RAW_BODY_HEADER = "X-RL-Raw-Body";
+var BINARY_BODY_HEADER = "X-RL-Binary-Body";
+var BINARY_BODY_PART = "body";
 
 // src/utils/audit-headers.ts
 var AUDIT_CAUSAL_REQUEST_HEADERS = {
@@ -1178,6 +1180,18 @@ function buildAuthHeaders(config) {
 }
 function transformRequestInit(init) {
   if (!init) return init;
+  const binaryType = findHeader(init.headers, BINARY_BODY_HEADER_LOWER);
+  if (binaryType !== void 0) {
+    return {
+      ...init,
+      headers: withHeader(
+        withoutHeader(init.headers, BINARY_BODY_HEADER_LOWER),
+        "Content-Type",
+        binaryType
+      ),
+      body: binaryBody(init.body)
+    };
+  }
   if (hasRawBodyHeader(init.headers)) {
     return { ...init, headers: withoutRawBodyHeader(init.headers) };
   }
@@ -1190,6 +1204,31 @@ function transformRequestInit(init) {
     return init;
   }
 }
+var BINARY_BODY_HEADER_LOWER = BINARY_BODY_HEADER.toLowerCase();
+function binaryBody(body) {
+  if (body instanceof FormData) {
+    const parts = [];
+    body.forEach((value, name) => parts.push([name, value]));
+    const only = parts[0];
+    if (parts.length === 1 && only !== void 0 && only[0] === BINARY_BODY_PART) {
+      const value = only[1];
+      if (value instanceof Blob) return value;
+    }
+  }
+  throw new ValidationError(
+    `A ${BINARY_BODY_HEADER} request must carry exactly one Blob part named "${BINARY_BODY_PART}"`
+  );
+}
+function withHeader(headers, name, value) {
+  const lowerName = name.toLowerCase();
+  const rest = withoutHeader(headers, lowerName);
+  if (rest instanceof Headers) {
+    rest.set(name, value);
+    return rest;
+  }
+  if (Array.isArray(rest)) return [...rest, [name, value]];
+  return { ...rest, [name]: value };
+}
 var REQUEST_BUDGET_HEADER_LOWER = REQUEST_BUDGET_HEADER.toLowerCase();
 function readRequestBudget(headers) {
   const raw = findHeader(headers, REQUEST_BUDGET_HEADER_LOWER);
@@ -9354,11 +9393,11 @@ var Analysis = class {
     ...params
   });
   /**
-   * @description The exploration must be complete (no more questions) before calling this. Creates appropriateness sorts in the hierarchy from the Duquenne-Guigues basis.
+   * @description The exploration must be complete (no more questions) before calling this. Registration happens before the terminal commit and ignores existing names, so a retry after a lost commit is safe. The committed receipt is retained: completing again returns it unchanged. `rules_created` counts those sort registrations; no inference rule is installed.
    *
    * @tags analysis
    * @name CompleteExploration
-   * @summary Complete the exploration and create sort rules from confirmed implications.
+   * @summary Complete the exploration and register appropriateness sorts for its basis.
    * @request POST:/api/v1/analysis/attribute-exploration/{session_id}/complete
    */
   completeExploration = (sessionId, params = {}) => this.http.request({
@@ -9368,7 +9407,7 @@ var Analysis = class {
     ...params
   });
   /**
-   * @description The body names the question being confirmed. The check and the mutation run under one session write lock, so an answer is applied at most once.
+   * @description The body names the question being confirmed. The answer commits only on top of the session version it was checked against, so across every server sharing the repository an answer is applied at most once.
    *
    * @tags analysis
    * @name ConfirmImplication
@@ -39998,6 +40037,51 @@ function IngestAudioResponseFromApiToFront(dto) {
     translatedLang: dto.translated_lang ?? void 0
   };
 }
+function CreateRdfUploadRequestFromFrontToApi(request) {
+  return {
+    name: request.name,
+    size: request.size,
+    ...request.datasetScope !== void 0 && { dataset_scope: request.datasetScope }
+  };
+}
+function RdfUploadFromApiToFront(dto) {
+  return {
+    id: dto.id,
+    name: dto.name,
+    size: dto.size,
+    uploadedBytes: dto.uploaded_bytes,
+    chunkBytes: dto.chunk_bytes,
+    chunkSha256: dto.chunk_sha256,
+    sha256: dto.sha256,
+    engineBinarySha256: dto.engine_binary_sha256,
+    format: dto.format,
+    gzip: dto.gzip,
+    status: dto.status,
+    ownerId: dto.owner_id,
+    sessionId: dto.session_id,
+    documentId: dto.document_id,
+    datasetScope: dto.dataset_scope,
+    prefixBindings: definedRecord(dto.prefix_bindings ?? {}),
+    quadsCommitted: dto.quads_committed,
+    batchesCommitted: dto.batches_committed,
+    resourcesCreated: dto.resources_created,
+    sortsCreated: dto.sorts_created,
+    error: dto.error,
+    updatedAt: dto.updated_at
+  };
+}
+function RdfUploadChunkReceiptFromApiToFront(dto) {
+  return {
+    uploadedBytes: dto.uploaded_bytes,
+    sha256: dto.sha256
+  };
+}
+function RdfUploadPauseReceiptFromApiToFront(dto) {
+  return {
+    id: dto.id,
+    status: dto.status
+  };
+}
 
 // src/resources/ingestion-session.ts
 var IngestionFailedError = class extends ReasoningLayerError {
@@ -41283,6 +41367,208 @@ var IngestionClient = class {
     const response = await this.api.resumeAudioJob(jobId, toRequestParams(requestOptions));
     return decodeResponse(response, IngestAudioResponseFromApiToFront);
   }
+  /**
+   * Open a resumable upload of one original RDF file —
+   * `POST /api/v1/ingest/rdf/uploads`.
+   *
+   * @param request - The file name (its extension selects the format), its
+   *   exact size, and an optional shared N-Triples/N-Quads dataset scope.
+   * @param requestOptions - Per-call request options.
+   * @returns The new upload (HTTP 201), with `status: 'uploading'`,
+   *   `uploadedBytes: 0` and the `chunkBytes` every chunk must respect.
+   * @throws {BadRequestError} 400 when the name is empty, longer than 255
+   *   bytes or holds `/`, `\` or NUL; when the size is 0 or above 32 GiB; when
+   *   the extension names no RDF format; or when a dataset scope accompanies a
+   *   format other than N-Triples or N-Quads.
+   *
+   * @remarks
+   * Body is snake_case on the wire (`dataset_scope`). The engine keeps the
+   * uploaded bytes verbatim and parses them only when
+   * {@link IngestionClient.completeRdfUpload} starts the import. Send the
+   * bytes with {@link IngestionClient.uploadRdfChunk}.
+   *
+   * @example
+   * ```typescript
+   * const upload = await client.ingestion.createRdfUpload({
+   *   name: file.name,
+   *   size: file.size,
+   * });
+   * for (let offset = 0; offset < file.size; offset += upload.chunkBytes) {
+   *   await client.ingestion.uploadRdfChunk(
+   *     upload.id,
+   *     offset,
+   *     file.slice(offset, offset + upload.chunkBytes),
+   *   );
+   * }
+   * await client.ingestion.completeRdfUpload(upload.id);
+   * ```
+   */
+  async createRdfUpload(request, requestOptions) {
+    const response = await this.api.create(
+      CreateRdfUploadRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return decodeResponse(response, RdfUploadFromApiToFront);
+  }
+  /**
+   * List the tenant's original RDF uploads — `GET /api/v1/ingest/rdf/uploads`.
+   *
+   * @param requestOptions - Per-call request options.
+   * @returns Every RDF upload of the tenant, the most recently updated first.
+   *   Each `chunkSha256` is empty in this listing; read one upload with
+   *   {@link IngestionClient.getRdfUpload} for its chunk digests.
+   * @throws {ApiError} If the request fails.
+   *
+   * @remarks
+   * Response is snake_case on the wire. An import that reads `queued` or
+   * `processing` without a live worker is reported as `interrupted`.
+   *
+   * @example
+   * ```typescript
+   * const uploads = await client.ingestion.listRdfUploads();
+   * const interrupted = uploads.filter((u) => u.status === 'interrupted');
+   * ```
+   */
+  async listRdfUploads(requestOptions) {
+    const response = await this.api.list(toRequestParams(requestOptions));
+    return decodeResponse(response, (dto) => dto.map(RdfUploadFromApiToFront));
+  }
+  /**
+   * Read one RDF upload: its upload extent and its durable ingestion
+   * checkpoint — `GET /api/v1/ingest/rdf/uploads/{id}`.
+   *
+   * @param id - The upload id ({@link RdfUpload.id}).
+   * @param requestOptions - Per-call request options.
+   * @returns The upload, with the SHA-256 of every stored chunk.
+   * @throws {NotFoundError} 404 when the tenant has no RDF upload with this id.
+   *
+   * @remarks
+   * Response is snake_case on the wire. Use `uploadedBytes` to resume an
+   * interrupted upload at the right offset, and `status` to follow the
+   * import; `interrupted` means no worker runs it, and
+   * {@link IngestionClient.completeRdfUpload} resumes it.
+   *
+   * @example
+   * ```typescript
+   * const upload = await client.ingestion.getRdfUpload(id);
+   * const nextOffset = upload.uploadedBytes;
+   * ```
+   */
+  async getRdfUpload(id, requestOptions) {
+    const response = await this.api.get(id, toRequestParams(requestOptions));
+    return decodeResponse(response, RdfUploadFromApiToFront);
+  }
+  /**
+   * Store one chunk of an RDF upload durably —
+   * `PUT /api/v1/ingest/rdf/uploads/{id}?offset=…`.
+   *
+   * @param id - The upload id ({@link RdfUpload.id}).
+   * @param offset - The byte offset of the chunk in the file: a multiple of
+   *   {@link RdfUpload.chunkBytes}, equal to `uploadedBytes` for a new chunk.
+   * @param chunk - The chunk's bytes: exactly `chunkBytes` of them, except for
+   *   the last chunk of the file. A `File` slice (`file.slice(start, end)`) is
+   *   a `Blob`; wrap other bytes as `new Blob([bytes])`.
+   * @param requestOptions - Per-call request options.
+   * @returns The bytes stored so far and the SHA-256 of this chunk.
+   * @throws {BadRequestError} 400 when the upload no longer accepts bytes, when
+   *   the offset or chunk size breaks the rules above, when the offset skips
+   *   or precedes the stored extent, or when a resent chunk differs from the
+   *   bytes stored at that offset.
+   * @throws {ForbiddenError} 403 when the caller did not open the upload.
+   * @throws {NotFoundError} 404 when the tenant has no RDF upload with this id.
+   *
+   * @remarks
+   * The body is the raw bytes, sent as `application/octet-stream`; the
+   * response is snake_case on the wire. Resending a chunk the engine already
+   * stored, with the same bytes, answers the same receipt, so a retry after a
+   * lost response is safe.
+   *
+   * @example
+   * ```typescript
+   * const upload = await client.ingestion.getRdfUpload(id);
+   * const start = upload.uploadedBytes;
+   * const receipt = await client.ingestion.uploadRdfChunk(
+   *   id,
+   *   start,
+   *   file.slice(start, start + upload.chunkBytes),
+   * );
+   * console.log(receipt.uploadedBytes, receipt.sha256);
+   * ```
+   */
+  async uploadRdfChunk(id, offset, chunk, requestOptions) {
+    const body = new FormData();
+    body.append(BINARY_BODY_PART, chunk);
+    const response = await this.api.http.request({
+      ...mergeRequestParams(
+        { headers: { [BINARY_BODY_HEADER]: "application/octet-stream" } },
+        requestOptions
+      ),
+      path: `/api/v1/ingest/rdf/uploads/${encodeURIComponent(id)}`,
+      method: "PUT",
+      query: { offset },
+      body,
+      type: "multipart/form-data",
+      format: "json"
+    });
+    return decodeResponse(response, RdfUploadChunkReceiptFromApiToFront);
+  }
+  /**
+   * Start, or resume, the import of a fully uploaded RDF file —
+   * `POST /api/v1/ingest/rdf/uploads/{id}/complete`.
+   *
+   * @param id - The upload id ({@link RdfUpload.id}).
+   * @param requestOptions - Per-call request options.
+   * @returns The upload: queued or resumed (HTTP 202), or unchanged (HTTP 200)
+   *   when the import is already complete or already has a live worker.
+   * @throws {BadRequestError} 400 when bytes are still missing.
+   * @throws {ForbiddenError} 403 when the caller did not open the upload.
+   * @throws {NotFoundError} 404 when the tenant has no RDF upload with this id.
+   * @throws {ConstraintViolationError} 409 while a paused worker is still
+   *   finishing its pause; retry the call.
+   *
+   * @remarks
+   * The import runs in the background and commits in durable batches; a
+   * resumed import continues from the last committed batch. Follow it with
+   * {@link IngestionClient.getRdfUpload}. Response is snake_case on the wire.
+   *
+   * @example
+   * ```typescript
+   * const started = await client.ingestion.completeRdfUpload(id);
+   * console.log(started.status); // 'queued'
+   * ```
+   */
+  async completeRdfUpload(id, requestOptions) {
+    const response = await this.api.complete(id, toRequestParams(requestOptions));
+    return decodeResponse(response, RdfUploadFromApiToFront);
+  }
+  /**
+   * Pause a running RDF import at its next durable checkpoint —
+   * `POST /api/v1/ingest/rdf/uploads/{id}/pause`.
+   *
+   * @param id - The upload id ({@link RdfUpload.id}).
+   * @param requestOptions - Per-call request options.
+   * @returns The receipt, with `status: 'pausing'`.
+   * @throws {BadRequestError} 400 when the import is not `queued` or
+   *   `processing`.
+   * @throws {ForbiddenError} 403 when the caller did not open the upload.
+   * @throws {NotFoundError} 404 when the tenant has no RDF upload with this id.
+   *
+   * @remarks
+   * The import stops after its current batch commits; the upload then reads
+   * `paused`. {@link IngestionClient.completeRdfUpload} resumes it. Response
+   * is snake_case on the wire.
+   *
+   * @example
+   * ```typescript
+   * await client.ingestion.pauseRdfUpload(id);
+   * // later
+   * await client.ingestion.completeRdfUpload(id);
+   * ```
+   */
+  async pauseRdfUpload(id, requestOptions) {
+    const response = await this.api.pause(id, toRequestParams(requestOptions));
+    return decodeResponse(response, RdfUploadPauseReceiptFromApiToFront);
+  }
 };
 
 // src/normalizers/reviews.ts
@@ -53851,6 +54137,20 @@ function OsfqlFailureFromApiToFront(body) {
   }
   return failure;
 }
+function OsfqlTokenFromApiToFront(dto) {
+  return {
+    line: dto.line,
+    startChar: dto.start_char,
+    length: dto.length,
+    kind: dto.kind
+  };
+}
+function OsfqlTokensResponseFromApiToFront(dto) {
+  return {
+    encoding: dto.encoding,
+    tokens: dto.tokens.map(OsfqlTokenFromApiToFront)
+  };
+}
 
 // src/resources/osfql.ts
 var OsfqlClient = class {
@@ -54194,6 +54494,38 @@ var OsfqlClient = class {
     });
     return decodeResponse(response, (dto) => dto.map(OsfqlCatalogEntryFromApiToFront));
   }
+  /**
+   * Highlight OSFQL source with the engine's own classifier — the one the
+   * OSFQL language server uses.
+   *
+   * @param query - The source as authored, incomplete statements included. At
+   *   most 256 KiB of UTF-8.
+   * @param requestOptions - Per-call transport options (timeout, signal, headers).
+   * @returns The editor tokens, sorted by position, in UTF-16 coordinates.
+   * @throws {BadRequestError} 400 when the source exceeds 256 KiB.
+   *
+   * @remarks
+   * Sent to `POST /api/v1/osfql/tokens` as `{ "query": … }`; the response is
+   * mapped from snake_case (`start_char`) at the boundary. The engine parser
+   * classifies sorts, features, literals and required fields, with a lexical
+   * fallback for an incomplete document. Nothing runs and the knowledge base
+   * is not read. This is presentation data, not validation: a source with
+   * errors still receives tokens. Use {@link OsfqlClient.diagnose} for errors.
+   *
+   * @example
+   * ```typescript
+   * const source = 'MATCH person(name: ?N);';
+   * const { tokens } = await client.osfql.tokens(source);
+   * for (const t of tokens) {
+   *   const text = source.split('\n')[t.line]?.slice(t.startChar, t.startChar + t.length);
+   *   console.log(t.kind, text); // "keyword MATCH", "sort person", …
+   * }
+   * ```
+   */
+  async tokens(query, requestOptions) {
+    const response = await this.api.osfqlTokens({ query }, toRequestParams(requestOptions));
+    return decodeResponse(response, OsfqlTokensResponseFromApiToFront);
+  }
 };
 function rethrowOsfqlFailure(error) {
   if (error instanceof ApiError) {