@frontera-sdk/cli 1.52.39 → 1.52.41

package/src/commands/knowledge/index-commands.ts

@@ -1,7 +1,10 @@
 import { basename } from 'node:path'
 
-import { PlatformApi } from '../../api/platform-api'
+import { PlatformApi, type KnowledgeRetrieval } from '../../api/platform-api'
 import { CliError, UsageError } from '../../errors'
+import { DEFAULT_KNOWLEDGE_THRESHOLD, KEYLESS_KNOWLEDGE_THRESHOLD, KEYLESS_RETRIEVAL_NOTE, PLATFORM_DEFAULT_EMBEDDING, sameEmbedding, WIDENED_KNOWLEDGE_THRESHOLD } from '../../local/local-org-settings'
+import { localRuntimeAt } from '../../local/local-runtime-target'
+import { isLocalEmbeddings } from '../../local/local-seed'
 import { table } from '../../table'
 import { resolveAgentRef } from '../agent/resolve'
 import { flagString, type Command } from '../types'
@@ -124,9 +127,11 @@ const get: Command = {
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
     const base = await client.knowledgeBase(await resolveKnowledgeRef(client, ref))
+    // On the keyless local embeddings the threshold shown is the one set for them, and retrieval is approximate: said.
+    const local = (await keylessRetrieval(client, ctx.cwd, ctx.apiUrl)) ? { localRetrieval: keylessRetrievalInfo() } : {}
 
     return {
-      data: base,
+      data: { ...base, ...local },
       // Whatever the route returns, flattened. Naming the fields here would
       // print "?" for every one the service renames, and the embedding model
       // and chunker are exactly the fields a caller comes to this verb to read.
@@ -137,7 +142,7 @@ const get: Command = {
           v === null || v === undefined ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v),
         ]),
         [undefined, 70],
-      ),
+      ) + ('localRetrieval' in local ? `\n\nNote: ${KEYLESS_RETRIEVAL_NOTE}.` : ''),
     }
   },
 }
@@ -160,9 +165,13 @@ const search: Command = {
     ],
     flags: { 'top-k': 'string', threshold: 'string' },
     summary: 'Search a knowledge base and show the chunks that come back',
+    details: [
+      'Without --threshold the base\'s own match threshold cuts the results, as an Agent\'s retrieval does. The cutoff is a maximum cosine distance from 0 to 2 (lower is stricter), while a score is higher-is-better: with vector scoring a score is 1 − distance / 2, so a 0.5 cutoff keeps scores above 0.75. The output says which cutoff applied.',
+    ],
     examples: [
       'frontera knowledge search product-docs "how do refunds work"',
       'frontera knowledge search product-docs "refund policy" --top-k 3 --json',
+      'frontera knowledge search product-docs "refund policy" --threshold 0.8',
     ],
   },
   async run(ctx) {
@@ -182,8 +191,9 @@ const search: Command = {
     }
     const thresholdRaw = flagString(ctx, 'threshold')
     const threshold = thresholdRaw === undefined ? undefined : Number(thresholdRaw)
-    if (threshold !== undefined && Number.isNaN(threshold)) {
-      throw new UsageError(`--threshold must be a number, not "${thresholdRaw}"`, 'try --threshold 0.7')
+    // A maximum cosine distance: 0 matches only identical text, 2 matches everything.
+    if (threshold !== undefined && (Number.isNaN(threshold) || threshold < 0 || threshold > 2)) {
+      throw new UsageError(`--threshold must be a cosine distance from 0 to 2, not "${thresholdRaw}"`, 'lower is stricter: try --threshold 0.8 to widen a search the base\'s own cutoff empties')
     }
 
     const client = new PlatformApi(ctx.apiUrl, ctx.token, ctx.workspaceId)
@@ -195,42 +205,104 @@ const search: Command = {
     })
 
     const chunks = result.results
+    const cutoff = cutoffLine(result.retrieval, threshold)
+    // On the keyless local embeddings: retrieval is approximate, said with what gives the platform's.
+    const keyless = await keylessRetrieval(client, ctx.cwd, ctx.apiUrl)
+    const keylessLine = keyless ? `\n  Note: ${KEYLESS_RETRIEVAL_NOTE}.` : ''
+    if (keyless) Object.assign(result, { localRetrieval: keylessRetrievalInfo() })
     if (chunks.length === 0) {
       // The overwhelmingly common cause, and the one a caller cannot see from
       // here: ingestion is asynchronous, so a base uploaded a minute ago is
       // empty rather than broken.
+      // How near the search came, when the service says: the threshold that would show it.
+      const nearest = result.retrieval?.nearestDistance
+      const max = typeof result.retrieval?.maxDistance === 'number' ? result.retrieval.maxDistance : threshold
+      if (typeof nearest === 'number') {
+        // Only asked when it could matter: a near miss the widened local threshold would keep.
+        const embedding = !keyless && nearMissOfWidening(nearest) ? await client.embeddingSetting().catch(() => null) : null
+        const widening = embeddingNote(nearest, embedding, isLoopbackApi(ctx.apiUrl))
+        return {
+          data: result,
+          text: `No chunks matched: the nearest chunk is at distance ${nearest}, past the cutoff${max === undefined ? '' : ` of ${max}`}. \`--threshold\` above ${nearest} (up to 2) shows it; setting the base's \`similarityThreshold\` there changes what an Agent's retrieval keeps.\n  ${cutoff}${widening ? `\n  ${widening}` : ''}${keylessLine}`,
+        }
+      }
+      if (nearest === null) {
+        return {
+          data: result,
+          text: `No chunks matched: ${ref} has nothing searchable yet. \`frontera knowledge sources ${ref}\` lists its documents: none, or still \`processing\`.`,
+        }
+      }
       return {
         data: result,
         text:
           'No chunks matched.\n'
           + `  If the upload was recent, check \`frontera knowledge sources ${ref}\` — a source\n`
           + '  still `processing` is not searchable yet.\n'
-          // Stated the right way round: --threshold is a distance cutoff, so a
-          // LOW value is the restrictive one and 0 can never match.
-          + (threshold !== undefined
-            ? `  --threshold ${threshold} is a maximum cosine distance — raise it to widen the search.\n`
-            : '  The default cutoff is 0.9; pass a higher --threshold to widen the search.\n')
-          + '  Otherwise the corpus may simply not cover this.',
+          + `  ${cutoff} Raise --threshold (up to 2) to widen the search.\n`
+          + '  Otherwise the corpus may simply not cover this.'
+          + keylessLine,
       }
     }
 
+    // A distance beside each score when the service gives one: it is what the cutoff compares.
+    const distances = chunks.some((c) => typeof c.distance === 'number')
     return {
       data: result,
       text: table(
-        ['score', 'source', 'chunk'],
+        ['score', ...(distances ? ['distance'] : []), 'source', 'chunk'],
         chunks.map((c) => [
           typeof c.score === 'number' ? c.score.toFixed(3) : String(c.score ?? ''),
+          ...(distances ? [typeof c.distance === 'number' ? c.distance.toFixed(3) : ''] : []),
           String(c.fileName ?? c.sourceId ?? ''),
           String(c.content ?? c.text ?? '').replace(/\s+/g, ' ').trim(),
         ]),
-        [8, 30, 90],
-      ),
+        distances ? [8, 9, 30, 90] : [8, 30, 90],
+      ) + `\n\n${cutoff}${keylessLine}`,
     }
   },
 }
 
+/** Whether the nearest distance sits between the default threshold and the one a local runtime widens to. */
+function nearMissOfWidening(nearest: number): boolean {
+  return nearest > DEFAULT_KNOWLEDGE_THRESHOLD && nearest <= WIDENED_KNOWLEDGE_THRESHOLD
+}
+
 /**
- * Re-run ingestion for a source that failed.
+ * Why a near miss may be the embedding model rather than the corpus: the
+ * default threshold is tuned for the platform's default embedding model, and
+ * another model ranks on-topic passages a little further away. A local
+ * runtime widens such a base's threshold when `frontera local dev` applies
+ * it, and this says so. Null when the miss is not in that band, or the model
+ * is the default or not known.
+ */
+export function embeddingNote(nearest: number, embedding: { provider: string | null; model: string | null } | null, local = true): string | null {
+  if (!nearMissOfWidening(nearest)) return null
+  if (!embedding?.provider || !embedding.model || sameEmbedding(embedding, PLATFORM_DEFAULT_EMBEDDING)) return null
+  // A hosted workspace hears only what it can act on: its own model, and the base's Match threshold.
+  if (!local) return `This organization embeds with ${embedding.provider} / ${embedding.model}, not the model the default threshold of ${DEFAULT_KNOWLEDGE_THRESHOLD} is tuned for, so on-topic passages sit further away: if relevant passages are cut off, raise the base's Match threshold.`
+  return `This organization embeds with ${embedding.provider} / ${embedding.model}, not the platform's default (${PLATFORM_DEFAULT_EMBEDDING.provider} / ${PLATFORM_DEFAULT_EMBEDDING.model}) the default threshold of ${DEFAULT_KNOWLEDGE_THRESHOLD} is tuned for, so on-topic passages sit further away. A local runtime widens a base's threshold to ${WIDENED_KNOWLEDGE_THRESHOLD} when \`frontera local dev\` applies it, if its file sets none or ${DEFAULT_KNOWLEDGE_THRESHOLD}.`
+}
+
+/**
+ * Which cutoff the search applied, on the scale `score` is read on: the
+ * base's own match threshold unless `--threshold` named one (that is what an
+ * Agent's retrieval uses), a maximum cosine distance, so a 0.5 cutoff keeps
+ * similarity scores above 0.75 and a 0.70 score is outside it.
+ */
+export function cutoffLine(retrieval: KnowledgeRetrieval | undefined, threshold: number | undefined): string {
+  const max = typeof retrieval?.maxDistance === 'number' ? retrieval.maxDistance : threshold
+  const from = retrieval?.thresholdFrom === 'request' || (!retrieval && threshold !== undefined) ? '--threshold' : 'the base\'s own match threshold, as an Agent\'s retrieval uses it'
+  if (max === undefined) return 'Cutoff: the base\'s own match threshold, as an Agent\'s retrieval uses it (a maximum cosine distance from 0 to 2; lower is stricter).'
+  if (retrieval?.scoring === 'fusion' || retrieval?.scoring === 'rerank') {
+    return `Cutoff: a maximum cosine distance of ${max}, from ${from}. Scores here are the ${retrieval.scoring === 'rerank' ? 'reranker\'s' : 'keyword and vector fusion\'s'}, so a score isn't comparable to the cutoff.`
+  }
+  const minScore = typeof retrieval?.minScore === 'number' ? retrieval.minScore : Math.max(0, 1 - max / 2)
+  return `Cutoff: a maximum cosine distance of ${max}, from ${from}: scores ≥ ${Number(minScore.toFixed(3))} (score = 1 − distance / 2).`
+}
+
+/**
+ * Re-run ingestion for a source that failed, or that is stuck pending or
+ * processing with no ingestion behind it (`local status` names one).
  *
  * `upload` exits 0 on a partial batch by design — one unreadable file does not
  * end the run — so a failed source is normal and recovery has to be normal
@@ -246,7 +318,7 @@ const retry: Command = {
       { name: 'source', required: true, description: 'source id, from `frontera knowledge sources`' },
     ],
     flags: {},
-    summary: 'Re-run ingestion for one source that failed',
+    summary: 'Re-run ingestion for one source that failed or is stuck processing',
     examples: ['frontera knowledge retry product-docs <sourceId>'],
   },
   async run(ctx) {
@@ -511,12 +583,15 @@ const agents: Command = {
         rows.length === 0
           ? `No agent can read ${ref} — attach one with \`frontera knowledge attach ${ref} <agent>\`.`
           : table(
-              ['agent', 'id'],
+              ['agent', 'id', 'attached in'],
               rows.map((r) => {
                 const id = String(r.agentId ?? '')
-                // An agent still in `configuring` is absent from `agent list`,
-                // so print the id rather than a "?" that reads as corruption.
-                return [slugs.get(id) ?? id, id]
+                // The row names the Agent's slug; an older platform's does not, and an agent still in
+                // `configuring` is absent from `agent list`, so print the id rather than a "?".
+                const slug = typeof r.agentSlug === 'string' && r.agentSlug ? r.agentSlug : slugs.get(id) ?? id
+                // Published, staged in its draft, or both; an older platform lists only published ones.
+                const where = r.published === false ? 'draft' : r.staged === false ? 'published (its draft drops it)' : r.staged === true ? 'published and draft' : 'published'
+                return [slug, id, where]
               }),
             ),
     }
@@ -563,3 +638,30 @@ export const knowledgeCommands: Command[] = [
   agents,
   ...reserved,
 ]
+
+/** Whether the command talks to a runtime on this machine (a local runtime is always on a loopback address). */
+/**
+ * Whether this runs on the keyless local embeddings: only against the
+ * project's own local runtime (`isLocalEmbeddings` reads this computer's
+ * keys), read from the organization's embedding setting. False when it
+ * can't say, and anywhere else.
+ */
+async function keylessRetrieval(client: PlatformApi, cwd: string, apiUrl: string): Promise<boolean> {
+  if (!localRuntimeAt(cwd, apiUrl)) return false
+  const embedding = await client.embeddingSetting().catch(() => null)
+  return !!embedding && isLocalEmbeddings(embedding)
+}
+
+/** What `--json` carries beside a base or a search on the keyless local embeddings. */
+export function keylessRetrievalInfo() {
+  return { embeddings: 'keyless-local', approximate: true, threshold: KEYLESS_KNOWLEDGE_THRESHOLD, note: KEYLESS_RETRIEVAL_NOTE } as const
+}
+
+function isLoopbackApi(apiUrl: string): boolean {
+  try {
+    const host = new URL(apiUrl).hostname
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1' || host.endsWith('.localhost')
+  } catch {
+    return false
+  }
+}