@kortexya/reasoninglayer 1.17.0 → 1.18.0

package/dist/index.js

@@ -5,7 +5,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");
@@ -6377,7 +6377,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
@@ -11862,6 +11862,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") {
@@ -20809,8 +20835,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
@@ -20965,6 +20993,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.
    */
@@ -29300,7 +29335,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
   };
 }
 
@@ -36913,6 +36949,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. */
@@ -37099,6 +37210,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;
@@ -37416,6 +37529,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));
   }
 };
 
@@ -37699,6 +37813,9 @@ var speech_exports = {};
 // src/types/connectors.ts
 var connectors_exports = {};
 
+// src/types/embeddings.ts
+var embeddings_exports = {};
+
 // src/builders/value.ts
 var Value = {
   /**
@@ -38704,6 +38821,6 @@ var Flow = {
   }
 };
 
-export { ANY_ROLE, action_reviews_exports as ActionReviews, actions_exports as Actions, admin_exports as Admin, agui_exports as Agui, analysis_exports as Analysis, anonymization_exports as Anonymization, ApiError, AuthenticationError, authz_exports as Authz, BadRequestError, cdl_exports as CDL, causal_exports as Causal, chase_exports as Chase, cognitive_exports as Cognitive, coherence_exports as Coherence, collections_exports as Collections, communities_exports as Communities, compliance_exports as Compliance, compliance_markings_exports as ComplianceMarkings, conformal_exports as Conformal, conformance_exports as Conformance, connectors_exports as Connectors, Constraint, ConstraintViolationError, constraints_exports as Constraints, control_exports as Control, conversation_exports as Conversation, corpus_exports as Corpus, dl_exports as DL, demo_exports as Demo, discovery_exports as Discovery, document_check_exports as DocumentCheck, documents_exports as Documents, execution_exports as Execution, extract_exports as Extract, feasibility_exports as Feasibility, Flow, flow_networks_exports as FlowNetworks, ForbiddenError, forecast_exports as Forecast, functions_exports as Functions, fuzzy_exports as Fuzzy, FuzzyShape, generation_exports as Generation, guardrail_exports as Guardrail, health_exports as Health, homoiconic_exports as Homoiconic, ilp_exports as ILP, image_extraction_exports as ImageExtraction, inference_exports as Inference, ingestion_exports as Ingestion, IngestionFailedError, IngestionSession, InternalServerError, LP, ltn_exports as LTN, marketplace_exports as Marketplace, namespaces_exports as Namespaces, NetworkError, neuro_symbolic_exports as NeuroSymbolic, NotFoundError, ontology_exports as Ontology, ontology_alignment_exports as OntologyAlignment, ontology_bridge_exports as OntologyBridge, ontology_export_exports as OntologyExport, ontology_facade_exports as OntologyFacade, operations_exports as Operations, optimize_exports as Optimize, osf_diff_exports as OsfDiff, osfql_exports as Osfql, oversight_exports as Oversight, plain_values_exports as PlainValues, preferences_exports as Preferences, proof_engine_exports as ProofEngine, property_graph_exports as PropertyGraph, query_exports as Query, rag_exports as RAG, RateLimitError, reasoning_exports as Reasoning, ReasoningLayerClient, ReasoningLayerError, research_exports as Research, reviews_exports as Reviews, reward_exports as Reward, row_exports as Row, SDK_VERSION, sat_exports as Sat, scenarios_exports as Scenarios, scheduling_exports as Scheduling, smt_exports as Smt, solver_exports as Solver, SortBuilder, sorts_exports as Sorts, sources_exports as Sources, spaces_exports as Spaces, sparql_exports as Sparql, speakers_exports as Speakers, speech_exports as Speech, statistical_exports as Statistical, streaming_exports as Streaming, synthetic_exports as Synthetic, temporal_exports as Temporal, terms_exports as Terms, TimeoutError, translation_exports as Translation, ui_exports as UI, utilities_exports as Utilities, ValidationError, Value, values_exports as Values, verification_exports as Verification, vision_exports as Vision, visualization_exports as Visualization, WebSocketClient, WebSocketConnection, webhook_actions_exports as WebhookActions, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
+export { ANY_ROLE, action_reviews_exports as ActionReviews, actions_exports as Actions, admin_exports as Admin, agui_exports as Agui, analysis_exports as Analysis, anonymization_exports as Anonymization, ApiError, AuthenticationError, authz_exports as Authz, BadRequestError, cdl_exports as CDL, causal_exports as Causal, chase_exports as Chase, cognitive_exports as Cognitive, coherence_exports as Coherence, collections_exports as Collections, communities_exports as Communities, compliance_exports as Compliance, compliance_markings_exports as ComplianceMarkings, conformal_exports as Conformal, conformance_exports as Conformance, connectors_exports as Connectors, Constraint, ConstraintViolationError, constraints_exports as Constraints, control_exports as Control, conversation_exports as Conversation, corpus_exports as Corpus, dl_exports as DL, demo_exports as Demo, discovery_exports as Discovery, document_check_exports as DocumentCheck, documents_exports as Documents, embeddings_exports as Embeddings, execution_exports as Execution, extract_exports as Extract, feasibility_exports as Feasibility, Flow, flow_networks_exports as FlowNetworks, ForbiddenError, forecast_exports as Forecast, functions_exports as Functions, fuzzy_exports as Fuzzy, FuzzyShape, generation_exports as Generation, guardrail_exports as Guardrail, health_exports as Health, homoiconic_exports as Homoiconic, ilp_exports as ILP, image_extraction_exports as ImageExtraction, inference_exports as Inference, ingestion_exports as Ingestion, IngestionFailedError, IngestionSession, InternalServerError, LP, ltn_exports as LTN, marketplace_exports as Marketplace, namespaces_exports as Namespaces, NetworkError, neuro_symbolic_exports as NeuroSymbolic, NotFoundError, ontology_exports as Ontology, ontology_alignment_exports as OntologyAlignment, ontology_bridge_exports as OntologyBridge, ontology_export_exports as OntologyExport, ontology_facade_exports as OntologyFacade, operations_exports as Operations, optimize_exports as Optimize, osf_diff_exports as OsfDiff, osfql_exports as Osfql, oversight_exports as Oversight, plain_values_exports as PlainValues, preferences_exports as Preferences, proof_engine_exports as ProofEngine, property_graph_exports as PropertyGraph, query_exports as Query, rag_exports as RAG, RateLimitError, reasoning_exports as Reasoning, ReasoningLayerClient, ReasoningLayerError, research_exports as Research, reviews_exports as Reviews, reward_exports as Reward, row_exports as Row, SDK_VERSION, sat_exports as Sat, scenarios_exports as Scenarios, scheduling_exports as Scheduling, smt_exports as Smt, solver_exports as Solver, SortBuilder, sorts_exports as Sorts, sources_exports as Sources, spaces_exports as Spaces, sparql_exports as Sparql, speakers_exports as Speakers, speech_exports as Speech, statistical_exports as Statistical, streaming_exports as Streaming, synthetic_exports as Synthetic, temporal_exports as Temporal, terms_exports as Terms, TimeoutError, translation_exports as Translation, ui_exports as UI, utilities_exports as Utilities, ValidationError, Value, values_exports as Values, verification_exports as Verification, vision_exports as Vision, visualization_exports as Visualization, WebSocketClient, WebSocketConnection, webhook_actions_exports as WebhookActions, allen, constrained, discriminateFeatureValue, guard, isConstrainedPlainVar, isPsiTermInput, isTaggedValueDto, isUuid, psi, toTaggedFeatures, toTaggedValue, toTermInputDto, toUntaggedFeatures, toUntaggedValue };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map