@vxil/sdk 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -741,7 +741,14 @@ export interface SearchHit {
     chunk_id: string;
     doc_id: string;
     text: string;
+    /** the fused RANK value (reciprocal-rank fusion: ≈ 1/61 for the first hit at
+     *  the default rrf_k) — it orders the hits; it is NOT a similarity, so never
+     *  threshold on it. */
     score: number;
+    /** cosine similarity of the hit to the query (−1…1, higher = closer) — the
+     *  value to threshold on. null when the query used no vector (mode
+     *  'keyword', or a bring-your-own-vectors collection queried by text only). */
+    similarity: number | null;
     /** provider relevance score — present only when the hit went through the
      *  configured BYO reranker (`reranked: true` on the result set). */
     rerank_score?: number;
@@ -1499,6 +1506,9 @@ export interface RagSearchHit {
     text: string;
     /** the raw retrieval score (RRF, or rerank relevance when reranked). */
     score: number;
+    /** cosine similarity of the hit to the query, passed through from
+     *  vector-search (−1…1; null when retrieval used no query vector). */
+    similarity?: number | null;
     /** the effective post-boost score results are RANKED by — present only when
      *  metadata boosts applied (rag.md §2f). */
     boosted_score?: number;
@@ -4031,11 +4041,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             hook_reconcile?: {
                 created: number;
                 updated: number;
+                unchanged?: number;
                 deleted: number;
                 failed: number;
             };
             cron_schedules?: {
                 created: number;
+                unchanged?: number;
                 deleted: number;
                 failed: number;
             };
@@ -5149,7 +5161,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }) => Promise<RagStreamHandle>;
         /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
-         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config. */
+         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
+         *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
+         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
         search: (input: {
             query: string;
             collection?: string;

package/dist/index.js

@@ -1905,7 +1905,10 @@ export class Vxil {
         stream: async (input) => (await this.call('POST', '/v1/rag/answer', { ...input, stream: true })).data,
         /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
-         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config. */
+         *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
+         *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
+         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
         search: async (input) => (await this.call('POST', '/v1/rag/search', input)).data,
         /** Ingest into the backing vector-search collection (chunk → embed → index). */
         ingest: async (collection, input) => (await this.call('POST', `/v1/rag/ingest/${encodeURIComponent(collection)}`, input)).data,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",