@kortexya/reasoninglayer 1.17.0 → 1.18.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.17.0";
+var SDK_VERSION = "1.18.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -6379,7 +6379,7 @@ var Query = class {
     this.http = http;
   }
   /**
-   * @description Returns all terms with the specified sort OR any of its subtypes. This implements proper OSF polymorphic query semantics where querying a parent sort returns all instances of that sort and its descendants.
+   * @description Returns all terms with the specified sort OR any of its subtypes. This implements proper OSF polymorphic query semantics where querying a parent sort returns all instances of that sort and its descendants. ## Resolving `sort_name` A name can denote more than one id (see `sort_name_candidates`), and no cheap probe tells which of them the query can actually answer from: on the production adapter `get_sort` and `get_sort_ids_by_names` are bare reads of an in-memory cache with no persistence fallback, while the query's own `get_compatible_sorts` does fall back to Postgres. Confirming a candidate with `get_sort` would therefore 404 every tenant sort created before the last restart — a guard strictly stricter than the thing it guards. So the candidates are **tried** against the real query, in order, and the first that answers wins; only `SortNotFound` moves on to the next, every other failure is returned as-is. When the first candidate answers — the common case — the route runs exactly one term query, as it always did. A phantom id (minted into the tenant lattice by ingestion and never persisted, #138) cannot be returned: the query authority refuses it and the loop skips past it. When no candidate answers, the sort is not queryable and the honest reply is 404 naming the sort the CALLER asked for — never a 400 leaking an internal `SortId` the caller never supplied.
    *
    * @tags query
    * @name FindBySort
@@ -11864,6 +11864,32 @@ var OntologyExport = class {
   });
 };
 
+// src/api-spec/generated/Embeddings.ts
+var Embeddings = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * @description POST /api/v1/embeddings/rank
+   *
+   * @tags embeddings
+   * @name RankEmbeddings
+   * @summary Score every candidate against the query by embedding cosine similarity.
+   * @request POST:/api/v1/embeddings/rank
+   * @secure
+   */
+  rankEmbeddings = (data, params = {}) => this.http.request({
+    path: `/api/v1/embeddings/rank`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json" /* Json */,
+    format: "json",
+    ...params
+  });
+};
+
 // src/normalizers/sorts.ts
 function ConstraintDtoFromApiToFront(dto) {
   if (dto.type === "FuzzyPathSimilarity") {
@@ -20811,8 +20837,10 @@ function EvidenceAssessmentRequestFromFrontToApi(model) {
   };
 }
 function EvidenceItemDtoFromApiToFront(dto) {
+  const wireDescription = dto.description;
   return {
     contribution: dto.contribution,
+    description: wireDescription ?? null,
     qualityWeight: dto.quality_weight,
     supports: dto.supports,
     termId: dto.term_id
@@ -20967,6 +20995,13 @@ var ReasoningClient = class {
   /**
    * Assess the truthfulness/validity of a subject based on related evidence.
    *
+   * @remarks
+   * Each item in the supporting/contradicting breakdown carries a
+   * `description` — the evidence term's own sentence,
+   * e.g. `"Aspirin reduces_risk_of Cancer"` — so evidence can be rendered
+   * without a second lookup by `termId`. It is `null` against a backend that
+   * predates the field.
+   *
    * @param request - Evidence assessment request.
    * @returns Assessment result with truthfulness score, label, and evidence breakdown.
    */
@@ -29302,7 +29337,8 @@ function IngestPaperRequestFromFrontToApi(model) {
 function VerifyClaimRequestFromFrontToApi(model) {
   return {
     claim_term_id: model.claimTermId,
-    evidence_sort_id: model.evidenceSortId
+    evidence_sort_id: model.evidenceSortId,
+    session_id: model.sessionId
   };
 }
 
@@ -36915,6 +36951,81 @@ var ConnectorsClient = class {
   }
 };
 
+// src/normalizers/embeddings.ts
+function EmbeddingRankRequestFromFrontToApi(model) {
+  return {
+    candidates: model.candidates ?? [],
+    query: model.query
+  };
+}
+function EmbeddingRankResponseFromApiToFront(dto) {
+  return {
+    scores: dto.scores ?? []
+  };
+}
+
+// src/resources/embeddings.ts
+var EmbeddingsClient = class {
+  /** @internal */
+  api;
+  /** @internal */
+  constructor(api) {
+    this.api = api;
+  }
+  /**
+   * Score every candidate against the query by embedding cosine similarity.
+   *
+   * @param request - The query and the candidate texts to score against it.
+   * @returns `scores` — one cosine similarity in `[-1, 1]` per candidate,
+   *   **index-aligned with `request.candidates`** (index `i` scores
+   *   `candidates[i]`) and the same length, so the scores can be zipped straight
+   *   back onto whatever was retrieved. Higher is more similar; a candidate
+   *   whose text is blank scores `0`.
+   * @throws {BadRequestError} `400` — the query is blank, the candidate list is
+   *   over the backend's 512-candidate cap, or the query / a candidate is over
+   *   8192 characters.
+   * @throws {ApiError} `503` when the deployment has **no embedding backend
+   *   configured** (or its embedder is unreachable / misconfigured). The SDK
+   *   surfaces every 5xx as an `InternalServerError`; read its `status` to tell
+   *   `503` (no embedder) from `500` (ranking failed).
+   *
+   * @remarks
+   * Distinguish "no embedder" from "no similarity": a deployment without an
+   * embedding backend answers `503` rather than a fabricated score, precisely so
+   * a caller cannot mistake it for "everything scored 0" and silently rank by
+   * noise. The documented fallback on a `503` is to keep the source order.
+   *
+   * An empty `candidates` list is valid, not an error: it answers `200` with an
+   * empty `scores` array, so a caller that retrieved nothing still gets a
+   * well-formed, index-aligned response.
+   *
+   * A `0` score is absence of signal, not evidence of dissimilarity — it is also
+   * what an orthogonal candidate and a blank candidate both receive.
+   *
+   * @example
+   * ```typescript
+   * const retrieved = [
+   *   { id: 'doc-1', text: 'Chaperones assist protein folding in the cytosol.' },
+   *   { id: 'doc-2', text: 'Quarterly revenue rose 12% year over year.' },
+   * ];
+   *
+   * const { scores } = await client.embeddings.rank({
+   *   query: 'how proteins fold',
+   *   candidates: retrieved.map((doc) => doc.text),
+   * });
+   *
+   * // Scores are index-aligned — zip them back onto what was retrieved.
+   * const ranked = retrieved
+   *   .map((doc, i) => ({ doc, score: scores[i] }))
+   *   .sort((a, b) => b.score - a.score);
+   * ```
+   */
+  async rank(request) {
+    const response = await this.api.rankEmbeddings(EmbeddingRankRequestFromFrontToApi(request));
+    return EmbeddingRankResponseFromApiToFront(response.data);
+  }
+};
+
 // src/client.ts
 var ReasoningLayerClient = class {
   /** Sort (type hierarchy) operations. */
@@ -37101,6 +37212,8 @@ var ReasoningLayerClient = class {
   speech;
   /** External data connectors — register / list / remove / connect / disconnect + OAuth callback. */
   connectors;
+  /** Embedding-space ranking — cosine score per candidate against a query, index-aligned. */
+  embeddings;
   // ─── Group Caches ─────────────────────────────────────────────────
   _core;
   _ai;
@@ -37418,6 +37531,7 @@ var ReasoningLayerClient = class {
     this.speakers = new SpeakersClient(new Speakers(generatedHttp));
     this.speech = new SpeechClient(new Speech(generatedHttp));
     this.connectors = new ConnectorsClient(new Connectors(generatedHttp));
+    this.embeddings = new EmbeddingsClient(new Embeddings(generatedHttp));
   }
 };
 
@@ -37701,6 +37815,9 @@ var speech_exports = {};
 // src/types/connectors.ts
 var connectors_exports = {};
 
+// src/types/embeddings.ts
+var embeddings_exports = {};
+
 // src/builders/value.ts
 var Value = {
   /**
@@ -38740,6 +38857,7 @@ exports.Demo = demo_exports;
 exports.Discovery = discovery_exports;
 exports.DocumentCheck = document_check_exports;
 exports.Documents = documents_exports;
+exports.Embeddings = embeddings_exports;
 exports.Execution = execution_exports;
 exports.Extract = extract_exports;
 exports.Feasibility = feasibility_exports;