@drewswiredin/backstage-plugin-assistants-backend-module-semantic-search 0.1.4 → 0.3.0

package/README.md

@@ -1,16 +1,24 @@
 # @drewswiredin/backstage-plugin-assistants-backend-module-semantic-search
 
-Knowledge index for AI Assistants for Backstage. It embeds every published
-TechDocs section and every catalog entity except `Location` into the assistants plugin's Postgres database and
-gives assistants a `search-knowledge` tool that finds them by meaning, by near
-spelling, and by exact words:
+Knowledge index for AI Assistants for Backstage. It copies everything your
+Backstage search indexes (TechDocs, the catalog, and any other source a
+collator brings in, such as Confluence or a wiki), embeds it into the
+assistants plugin's Postgres database, and gives assistants a
+`search-knowledge` tool that finds it by meaning, by near spelling, and by
+exact words:
 
 - "how do I fix errored-out messages" finds _Dead-letter handling › Replaying
   dead-lettered messages_.
 - "Pilon deployment" finds the _Pylon Gateway › Deployment runbook_.
 - "dlq-replay" finds the page that names the job.
 
-Results are filtered to entities the user can read in the catalog.
+It reads no source itself. Each time a search collator finishes a run, the
+module copies that run's documents, so the index follows your search schedule
+and a rate-limited source such as Confluence is read once, by search.
+
+Catalog and TechDocs results are filtered to entities the user can read in the
+catalog. Results from other sources are visible to every assistant user, as
+they are in Backstage search.
 
 Adds to the backend plugin
 [`@drewswiredin/backstage-plugin-assistants-backend`](https://www.npmjs.com/package/@drewswiredin/backstage-plugin-assistants-backend).
@@ -18,6 +26,8 @@ Adds to the backend plugin
 ## Requirements
 
 - The assistants backend plugin, with its database on Postgres 13 or later.
+- Backstage search (`@backstage/plugin-search-backend`) in the same backend,
+  with the collators for the sources you want: any search engine works.
 - The `vector` ([pgvector](https://github.com/pgvector/pgvector)) and
   `pg_trgm` extensions in the assistants plugin's database.
 - An embedding model from an `openai`, `azure`, or `openai-compatible`
@@ -34,6 +44,7 @@ yarn --cwd packages/backend add @drewswiredin/backstage-plugin-assistants-backen
 ```ts
 // packages/backend/src/index.ts
 backend.add(import('@drewswiredin/backstage-plugin-assistants-backend'));
+backend.add(import('@backstage/plugin-search-backend'));
 backend.add(
   import(
     '@drewswiredin/backstage-plugin-assistants-backend-module-semantic-search'
@@ -41,6 +52,13 @@ backend.add(
 );
 ```
 
+The one `backend.add` installs two modules: the index and `search-knowledge`
+under the `assistants` plugin, and a document decorator under the `search`
+plugin that copies what each search run collected. To add them separately,
+import `assistantsModuleSemanticSearch` and `searchModuleAssistantsKnowledge`
+by name. Without the search plugin the module logs a warning at startup and
+the index stays empty.
+
 ## Enable the extensions
 
 The module enables both extensions itself when its database role may. `pg_trgm`
@@ -82,14 +100,59 @@ assistants:
 On Azure OpenAI, deploy an embedding model and name the deployment:
 `embeddingModel: azure:<embedding-deployment>`.
 
-The first run embeds everything; later runs embed only new and changed
-sections and delete removed ones. Changing `embeddingModel` rebuilds the index.
+### Rank by source
+
+Every source shares one index, so a large one (thousands of tickets that all
+mention the same system) can crowd out the one runbook section that answers
+the question. Name the search document types to weigh them:
+
+```yaml
+assistants:
+  semanticSearch:
+    embeddingModel: openai:text-embedding-3-small
+    maxResults: 8
+    types:
+      software-catalog: { weight: 1.5 }
+      techdocs: { weight: 1.2 }
+      confluence: { weight: 1.0 }
+      jira:
+        weight: 0.5
+        maxResults: 2
+        description: ticket history, decisions and status
+```
+
+The keys are the type names Backstage search uses: `software-catalog`,
+`techdocs`, or a collator's own type. Types left out are copied and ranked
+with weight 1. Set `default: false` to make a source opt-in: the model then
+searches it only when it passes `types: ['jira']`, and the tool description
+says so. Set `enabled: false` to stop copying a source; its chunks are
+deleted on its next search run.
+
+The index fills as search runs: each document type arrives when its collator
+next runs, on the schedule you gave that collator. A source's first run embeds
+all of it; later runs embed only new and changed sections and delete removed
+ones. Changing `embeddingModel` empties the index, and each type refills on its
+next search run.
+
+A type added to `types` takes its name, weight, and metadata on its next run,
+keeping the embeddings it already has; 0.2.0 indexes upgrade the same way. To
+run a collator now rather than wait for its schedule, trigger its search task
+with a user or service token:
+
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  https://backstage.example.com/api/search/.backstage/scheduler/v1/tasks/search_index_jira/trigger
+```
+
+The task id is `search_index_<type>`; the backend logs `Knowledge index
+refreshed` with the type and counts when the copy finishes.
 
 ## Give an assistant the tool
 
 Add `search-knowledge` to the assistant's tools in the assistant editor. It
 pairs with `read-techdocs` (from `builtinActions: true`), which opens the full
-page behind a TechDocs result. Until the first index run finishes, the tool
+page behind a TechDocs result; other results carry a link. Until the first
+search run is copied, the tool
 answers with an error that points the model at keyword search: Backstage's
 `query` action when the assistant has it, otherwise `search-techdocs` and
 `search-catalog`.
@@ -113,17 +176,38 @@ backend:
 
 ## How it works
 
-**Indexing.** A scheduled task (one replica at a time) reads each published
-TechDocs site's MkDocs search index (the same source Backstage's TechDocs
-search uses) and every catalog entity except `Location`. Each TechDocs section
-becomes one or more chunks of up to ~1600 characters, titled with its heading
-path (`Site › Page › Section`) and embedded with that title. Each row stores
-the embedding, a generated full-text vector, and a trigram index over its text.
-The table is a rebuildable cache, not migrated data.
-
-**Retrieval.** `search-knowledge` takes the question and up to three alternative
-phrasings and builds one semantic list per phrasing, a keyword list, a rare-word
-list, and a fuzzy list:
+**Indexing.** A search decorator sits on every document type's pipeline. It
+passes each document on to the search engine unchanged and keeps it; when the
+collator finishes, it hands the run's documents to the index. A failed run
+hands over nothing, and a run with no documents changes nothing. Runs are
+copied one at a time, in the backend that ran the collator.
+
+Each document becomes one or more chunks of up to ~1600 characters, titled
+with its heading path (`Site › Page › Section` for TechDocs) and embedded with
+that title. The facts collators attach (entity ref, type, owner, lifecycle)
+join the text, so a catalog entity with no description is still found. A
+document gated by a catalog entity (its `authorization.resourceRef`) keeps that
+entity for the permission check; a document gated by any other kind of
+resource is skipped, since the index can only check entity read permission.
+
+Search never tells a decorator which document type it is decorating, so the
+module adds a pass-through decorator to each type named in `types`. Search
+builds a run's pipeline in one pass, so that decorator names the run's type.
+A named type's run is stored under its name; a run of any other type joins
+the stored collection that already holds most of its locations. Chunks the
+run no longer has are deleted. A collection no search run has refreshed in
+30 days (a source removed from search, or an unnamed one whose locations all
+changed at once) is dropped. Each row stores the embedding, a generated
+full-text vector, a trigram index over its text, its type, and the short
+fields its collator attached. The table is a rebuildable copy, not migrated
+data.
+
+**Retrieval.** `search-knowledge` takes the question, up to three alternative
+phrasings, and optionally the `types` to search (otherwise every type that is
+on by default, plus unnamed sources). It builds one semantic list per
+phrasing, a keyword list, a rare-word list, and a fuzzy list, each keeping
+its best 30 chunks of every type, so a large source cannot fill a list on its
+own:
 
 | List      | Matches                                       | Postgres                                                    |
 | --------- | --------------------------------------------- | ----------------------------------------------------------- |
@@ -135,18 +219,74 @@ list, and a fuzzy list:
 Query words include adjacent pairs written as one word, so "tally up" also
 matches "TallyUp". Reciprocal rank fusion merges the lists with one vote per
 method: the semantic lists share one vote, so extra phrasings broaden recall
-without outvoting an exact match. The rare-word list keeps a name or acronym
-mentioned once in a paragraph about something else from being outranked by
-sections that are only near the question in meaning. The top candidates'
-entities are fetched from the catalog as the user; results for entities the
-user cannot read are dropped, and repeated text is shown once.
+without outvoting an exact match. Each chunk's fused score is multiplied by
+its type's weight. The rare-word list keeps a name or acronym mentioned once
+in a paragraph about something else from being outranked by sections that
+are only near the question in meaning. The top candidates' entities are
+fetched from the catalog as the user; results for entities the user cannot
+read are dropped, results with no entity are kept, and repeated text is shown
+once. The ranker then picks the results: by default best first, with at most
+`maxResults` of a capped type while other types can fill the slots.
+
+Each result carries its title, location, type, excerpt, the entity ref for
+catalog and TechDocs results, and `metadata`: the short fields its collator
+attached (strings up to 200 characters, numbers, booleans), such as a
+ticket's status or a page's last update.
+
+## Custom ranking
+
+A backend module can replace the ranker, for example to favour recently
+updated tickets:
+
+```ts
+import { createBackendModule } from '@backstage/backend-plugin-api';
+import { knowledgeRankingExtensionPoint } from '@drewswiredin/backstage-plugin-assistants-backend-module-semantic-search/alpha';
+
+export default createBackendModule({
+  pluginId: 'assistants',
+  moduleId: 'knowledge-recency',
+  register(env) {
+    env.registerInit({
+      deps: { ranking: knowledgeRankingExtensionPoint },
+      async init({ ranking }) {
+        ranking.setRanker(({ candidates, maxResults }) =>
+          candidates
+            .map(candidate => {
+              const updated = Date.parse(String(candidate.metadata?.updated));
+              const ageDays = (Date.now() - updated) / 86_400_000;
+              const boost = ageDays < 90 ? 1.2 : 1;
+              return { candidate, score: candidate.score * boost };
+            })
+            .sort((a, b) => b.score - a.score)
+            .slice(0, maxResults)
+            .map(({ candidate }) => candidate),
+        );
+      },
+    });
+  },
+});
+```
+
+The ranker receives the query, its phrasings, the types searched, and up to
+60 candidates the caller may read. Each candidate has its fused score after
+weights, its rank in each retrieval list, its type, entity ref, and metadata.
+It runs after the permission check, so it cannot surface what the caller
+cannot read; results it returns that were not candidates are dropped.
 
 ## Reference
 
-| Key                                        | Default                                              | Meaning                                                                                       |
-| ------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `assistants.semanticSearch.embeddingModel` | (required)                                           | `<providerId>:<model>` from `assistants.providers`.                                           |
-| `assistants.semanticSearch.schedule`       | every 30 minutes, 1 hour timeout, 15 s initial delay | Backstage task schedule for refreshing the index; a configured schedule replaces the default. |
+| Key                                                  | Default    | Meaning                                                                       |
+| ---------------------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
+| `assistants.semanticSearch.embeddingModel`           | (required) | `<providerId>:<model>` from `assistants.providers`.                           |
+| `assistants.semanticSearch.maxResults`               | `8`        | Results per answer unless the model asks for a number (it may ask for 20).    |
+| `assistants.semanticSearch.types.<type>.weight`      | `1`        | Multiplies the type's fused score; `0` never returns it.                      |
+| `assistants.semanticSearch.types.<type>.default`     | `true`     | Searched when the model names no types; `false` makes the type opt-in.        |
+| `assistants.semanticSearch.types.<type>.maxResults`  |            | At most this many of the type's results while other types can fill the slots. |
+| `assistants.semanticSearch.types.<type>.enabled`     | `true`     | `false` stops copying the type and deletes its chunks on its next run.        |
+| `assistants.semanticSearch.types.<type>.description` |            | What the source holds, shown to the model in the tool description.            |
+
+The index refreshes when search does; set each collator's schedule in its own
+config.
 
 ## License
 

package/config.schema.json

@@ -12,167 +12,44 @@
               "type": "string",
               "description": "Embedding model in `<providerId>:<model>` format, resolved against `assistants.providers`, e.g. `openai:text-embedding-3-small`. The provider must be `openai`, `azure`, or `openai-compatible`. Changing it rebuilds the index."
             },
-            "schedule": {
+            "maxResults": {
+              "type": "number",
+              "description": "Results per `search-knowledge` answer unless the caller asks for a number. Defaults to 8."
+            },
+            "types": {
               "type": "object",
-              "properties": {
-                "frequency": {
-                  "anyOf": [
-                    {
-                      "type": "object",
-                      "properties": {
-                        "cron": {
-                          "type": "string",
-                          "description": "A crontab style string."
-                        }
-                      },
-                      "required": [
-                        "cron"
-                      ]
-                    },
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "years": {
-                          "type": "number"
-                        },
-                        "months": {
-                          "type": "number"
-                        },
-                        "weeks": {
-                          "type": "number"
-                        },
-                        "days": {
-                          "type": "number"
-                        },
-                        "hours": {
-                          "type": "number"
-                        },
-                        "minutes": {
-                          "type": "number"
-                        },
-                        "seconds": {
-                          "type": "number"
-                        },
-                        "milliseconds": {
-                          "type": "number"
-                        }
-                      },
-                      "description": "Human friendly durations object."
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "trigger": {
-                          "type": "string",
-                          "const": "manual"
-                        }
-                      },
-                      "required": [
-                        "trigger"
-                      ]
-                    }
-                  ],
-                  "description": "How often you want the task to run. The system does its best to avoid overlapping invocations."
-                },
-                "timeout": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "years": {
-                          "type": "number"
-                        },
-                        "months": {
-                          "type": "number"
-                        },
-                        "weeks": {
-                          "type": "number"
-                        },
-                        "days": {
-                          "type": "number"
-                        },
-                        "hours": {
-                          "type": "number"
-                        },
-                        "minutes": {
-                          "type": "number"
-                        },
-                        "seconds": {
-                          "type": "number"
-                        },
-                        "milliseconds": {
-                          "type": "number"
-                        }
-                      },
-                      "description": "Human friendly durations object."
-                    }
-                  ],
-                  "description": "The maximum amount of time that a single task invocation can take, before it's considered timed out and gets \"released\" such that a new invocation is permitted to take place (possibly, then, on a different worker)."
-                },
-                "initialDelay": {
-                  "anyOf": [
-                    {
-                      "type": "string"
-                    },
-                    {
-                      "type": "object",
-                      "properties": {
-                        "years": {
-                          "type": "number"
-                        },
-                        "months": {
-                          "type": "number"
-                        },
-                        "weeks": {
-                          "type": "number"
-                        },
-                        "days": {
-                          "type": "number"
-                        },
-                        "hours": {
-                          "type": "number"
-                        },
-                        "minutes": {
-                          "type": "number"
-                        },
-                        "seconds": {
-                          "type": "number"
-                        },
-                        "milliseconds": {
-                          "type": "number"
-                        }
-                      },
-                      "description": "Human friendly durations object."
-                    }
-                  ],
-                  "description": "The amount of time that should pass before the first invocation happens."
-                },
-                "scope": {
-                  "type": "string",
-                  "enum": [
-                    "global",
-                    "local"
-                  ],
-                  "description": "Sets the scope of concurrency control / locking to apply for invocations of this task."
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "weight": {
+                    "type": "number",
+                    "description": "Multiplies the type's fused score. Defaults to 1; 0 means its chunks are never returned."
+                  },
+                  "default": {
+                    "type": "boolean",
+                    "description": "Searched when the caller names no types. Defaults to true; false makes the type opt-in (the model passes it in `types`)."
+                  },
+                  "maxResults": {
+                    "type": "number",
+                    "description": "At most this many of the type's results in one answer."
+                  },
+                  "enabled": {
+                    "type": "boolean",
+                    "description": "Copied into the index. Defaults to true; false stops copying it and deletes its chunks on its next search run."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "What the source holds, shown to the model in the tool description, e.g. \"ticket history, decisions and status\"."
+                  }
                 }
               },
-              "required": [
-                "frequency",
-                "timeout"
-              ],
-              "description": "How often the index refreshes. Each run embeds only new and changed content. Default: every 30 minutes, 1 hour timeout, 15 s initial delay; a configured schedule replaces it."
+              "description": "Settings per Backstage search document type, keyed by the type name search uses (`software-catalog`, `techdocs`, or a collator's own type). Types left out are copied and ranked with the defaults."
             }
           },
           "required": [
             "embeddingModel"
           ],
-          "description": "The knowledge index: published TechDocs sections and catalog entities (except `Location`) embedded into the assistants plugin's Postgres database and served to assistants as the `search-knowledge` action. Requires the `vector` and `pg_trgm` extensions."
+          "description": "The knowledge index: a copy of everything Backstage search indexes (TechDocs, the catalog, and any other collator's documents), embedded into the assistants plugin's Postgres database as each search run finishes and served to assistants as the `search-knowledge` action. Requires the search plugin in the same backend, and the `vector` and `pg_trgm` extensions."
         }
       }
     }

package/dist/action.cjs.js

@@ -2,9 +2,11 @@
 
 var ai = require('ai');
 var rank = require('./rank.cjs.js');
+var ranking = require('./ranking.cjs.js');
 
 const CANDIDATES = 30;
-const FUSED = 40;
+const FUSED = 60;
+const MAX_LIMIT = 20;
 const EXCERPT_CHARS = 1500;
 const RARE_MAX_CHUNKS = 3;
 function registerSearchKnowledgeAction({
@@ -12,13 +14,17 @@ function registerSearchKnowledgeAction({
   store,
   catalog,
   auth,
-  embeddingModel
+  embeddingModel,
+  types,
+  maxResults,
+  ranker
 }) {
   actionsRegistry.register({
     name: "search-knowledge",
     title: "Search Knowledge",
     attributes: { destructive: false, readOnly: true, idempotent: true },
-    description: `Search the organization's TechDocs and software catalog by meaning, not only by exact words. Best for questions in the user's own words: it finds a page even when the question is worded differently from it ("fix errored messages" finds "Retry dead-letter messages") and tolerates misspelled names ("Pilon" finds "Pylon"). It returns the most relevant sections, not every match, and cannot filter by entity kind.
+    description: `Search everything the organization's Backstage search indexes (TechDocs, the software catalog, and any other source it collects, such as Confluence or wiki pages) by meaning, not only by exact words. Best for questions in the user's own words: it finds a page even when the question is worded differently from it ("fix errored messages" finds "Retry dead-letter messages") and tolerates misspelled names ("Pilon" finds "Pylon"). It returns the most relevant sections, not every match, and cannot filter by entity kind.
+${sourcesDescription(types)}
 
 How to search the organization's docs and catalog:
 1. Start here, with the user's question.
@@ -27,20 +33,27 @@ How to search the organization's docs and catalog:
 
 Pass the user's question as the "query" parameter. Pass up to three "alternatives": other phrasings, synonyms, or the internal terms the docs might use.
 
-Each result has a title (its heading path), an excerpt, and a location. For TechDocs results, pass the location to read-techdocs to read the full page. For catalog results, the location is the entity ref.`,
+Each result has a title (its heading path), an excerpt, a location, its source type, the fields the source attached (such as status, space, or last update: use them to judge how current it is), and, for catalog and TechDocs results, the entity ref. A location starting with /docs/ is a TechDocs page: pass it to read-techdocs to read the full page. Any other location is a link to the page or entity; cite it.`,
     schema: {
       input: (z) => z.object({
         query: z.string().min(1).describe("The question or topic to find"),
         alternatives: z.array(z.string()).max(3).optional().describe("Other phrasings or terms for the same thing"),
-        limit: z.number().int().min(1).max(20).optional().default(8).describe("Number of results to return")
+        types: z.array(z.string()).optional().describe(
+          "Search only these sources (search document types); omit to search the default ones"
+        ),
+        limit: z.number().int().min(1).max(Math.max(MAX_LIMIT, maxResults)).optional().default(maxResults).describe("Number of results to return")
       }),
       output: (z) => z.object({
         results: z.array(
           z.object({
-            source: z.enum(["techdocs", "catalog"]),
             title: z.string(),
             location: z.string(),
-            entityRef: z.string(),
+            type: z.string().optional(),
+            entityRef: z.string().optional(),
+            metadata: z.record(
+              z.string(),
+              z.union([z.string(), z.number(), z.boolean()])
+            ).optional(),
             excerpt: z.string()
           })
         )
@@ -52,12 +65,17 @@ Each result has a title (its heading path), an excerpt, and a location. For Tech
           "The knowledge index is still being built; meanwhile use keyword search: the query tool when it is available, otherwise search-techdocs and search-catalog."
         );
       }
+      const filter = ranking.selectTypes(types, await store.types(), input.types);
       const phrasings = [input.query, ...input.alternatives ?? []];
       const words = rank.queryWords(phrasings);
       const joined = rank.joinedWords(phrasings).filter((w) => !words.includes(w));
       const [{ embeddings }, frequencies] = await Promise.all([
         ai.embedMany({ model: embeddingModel, values: phrasings }),
-        store.documentFrequencies([...words, ...joined], RARE_MAX_CHUNKS + 1)
+        store.documentFrequencies(
+          [...words, ...joined],
+          RARE_MAX_CHUNKS + 1,
+          filter
+        )
       ]);
       const known = [...words, ...joined].filter(
         (w) => (frequencies.get(w) ?? 0) > 0
@@ -66,45 +84,80 @@ Each result has a title (its heading path), an excerpt, and a location. For Tech
       const unknown = words.filter((w) => frequencies.get(w) === 0);
       const lists = await Promise.all([
         ...embeddings.map(async (embedding) => ({
-          ids: await store.nearest(embedding, CANDIDATES),
+          name: "semantic",
+          hits: await store.nearest(embedding, CANDIDATES, filter),
           weight: 1 / embeddings.length
         })),
-        store.keyword(known, CANDIDATES).then((ids) => ({ ids, weight: 1 })),
-        store.keyword(rare, CANDIDATES).then((ids) => ({ ids, weight: 1 })),
-        store.fuzzy(unknown, CANDIDATES).then((ids) => ({ ids, weight: 1 }))
+        store.keyword(known, CANDIDATES, filter).then((hits) => ({ name: "keyword", hits, weight: 1 })),
+        store.keyword(rare, CANDIDATES, filter).then((hits) => ({ name: "rareWord", hits, weight: 1 })),
+        store.fuzzy(unknown, CANDIDATES, filter).then((hits) => ({ name: "fuzzy", hits, weight: 1 }))
       ]);
-      const ranked = rank.fuseRankings(lists).slice(0, FUSED);
+      const settingsOf = ranking.typeSettingsOf(types);
+      const fused = rank.fuseRankings(lists, (type) => settingsOf(type).weight).slice(
+        0,
+        FUSED
+      );
       const byId = new Map(
-        (await store.chunks(ranked)).map((chunk) => [chunk.id, chunk])
+        (await store.chunks(fused.map((hit) => hit.id))).map((chunk) => [
+          chunk.id,
+          chunk
+        ])
       );
-      const candidates = ranked.map((id) => byId.get(id)).filter((chunk) => Boolean(chunk));
+      const found = fused.flatMap((hit) => {
+        const chunk = byId.get(hit.id);
+        return chunk ? [{ hit, chunk }] : [];
+      });
       const readable = await readableEntityRefs(catalog, auth, credentials, [
-        ...new Set(candidates.map((chunk) => chunk.entityRef))
+        ...new Set(
+          found.flatMap(
+            ({ chunk }) => chunk.entityRef ? [chunk.entityRef] : []
+          )
+        )
       ]);
       const seen = /* @__PURE__ */ new Set();
-      const results = [];
-      for (const chunk of candidates) {
+      const candidates = [];
+      for (const { hit, chunk } of found) {
         const key = `${chunk.location}|${chunk.title}`;
-        if (!readable.has(chunk.entityRef) || seen.has(key) || seen.has(chunk.content)) {
+        if (chunk.entityRef && !readable.has(chunk.entityRef) || seen.has(key) || seen.has(chunk.content)) {
           continue;
         }
         seen.add(key);
         seen.add(chunk.content);
-        results.push({
-          source: chunk.source,
-          title: chunk.title,
-          location: chunk.location,
-          entityRef: chunk.entityRef,
-          excerpt: chunk.content.slice(0, EXCERPT_CHARS)
-        });
-        if (results.length === input.limit) {
-          break;
-        }
+        candidates.push({ ...chunk, score: hit.score, ranks: hit.ranks });
       }
+      const ids = new Set(candidates.map((candidate) => candidate.id));
+      const ranked = await ranker()({
+        query: input.query,
+        phrasings,
+        types: filter.types,
+        candidates,
+        maxResults: input.limit
+      });
+      const results = ranked.filter((candidate) => ids.delete(candidate.id)).slice(0, input.limit).map((candidate) => ({
+        title: candidate.title,
+        location: candidate.location,
+        ...candidate.type ? { type: candidate.type } : {},
+        ...candidate.entityRef ? { entityRef: candidate.entityRef } : {},
+        ...candidate.metadata ? { metadata: candidate.metadata } : {},
+        excerpt: candidate.content.slice(0, EXCERPT_CHARS)
+      }));
       return { output: { results } };
     }
   });
 }
+function sourcesDescription(types) {
+  const listed = [...types].filter(
+    ([, settings]) => settings.enabled && settings.weight > 0
+  );
+  const lines = listed.map(
+    ([type, settings]) => `- ${type}${settings.default ? "" : ' (only when named in "types")'}${settings.description ? `: ${settings.description}` : ""}`
+  );
+  return [
+    "",
+    `Sources: pass "types" to search only the named search document types; without it the search covers every source except those marked as searched only when named. An unknown name returns the list of types.`,
+    ...lines
+  ].join("\n");
+}
 async function readableEntityRefs(catalog, auth, credentials, entityRefs) {
   if (entityRefs.length === 0) {
     return /* @__PURE__ */ new Set();
@@ -121,4 +174,5 @@ async function readableEntityRefs(catalog, auth, credentials, entityRefs) {
 }
 
 exports.registerSearchKnowledgeAction = registerSearchKnowledgeAction;
+exports.sourcesDescription = sourcesDescription;
 //# sourceMappingURL=action.cjs.js.map