@promptev/context-engine 0.0.3 → 0.0.5

package/dist/{mcp-BKSmxayM.d.cts → mcp-uirRbluA.d.cts}

@@ -117,6 +117,10 @@ type Engine$1 = {
     getChunks?: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
     getDocuments?: (ids: string[], opts?: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
     mapReduce?: (instruction: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    spreadsheetSchema: (opts: Record<string, unknown>) => Promise<unknown[]>;
+    documentStructure: (opts: Record<string, unknown>) => Promise<Record<string, Record<string, unknown>>>;
+    documentTypes: (opts?: Record<string, unknown>) => Promise<unknown[]>;
+    fieldSummary: (opts?: Record<string, unknown>) => Promise<unknown[]>;
 };
 type KnowledgeToolArgs = {
     action: string;

package/dist/{mcp-BKSmxayM.d.ts → mcp-uirRbluA.d.ts}

@@ -117,6 +117,10 @@ type Engine$1 = {
     getChunks?: (id: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
     getDocuments?: (ids: string[], opts?: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
     mapReduce?: (instruction: string, opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    spreadsheetSchema: (opts: Record<string, unknown>) => Promise<unknown[]>;
+    documentStructure: (opts: Record<string, unknown>) => Promise<Record<string, Record<string, unknown>>>;
+    documentTypes: (opts?: Record<string, unknown>) => Promise<unknown[]>;
+    fieldSummary: (opts?: Record<string, unknown>) => Promise<unknown[]>;
 };
 type KnowledgeToolArgs = {
     action: string;

package/dist/mcp.cjs

@@ -409,7 +409,7 @@ var KNOWLEDGE_ACTIONS = [
   "get_neighbors",
   "community_summary"
 ];
-var KNOWLEDGE_TOOL_DESCRIPTION = "The knowledge base \u2014 the ingested documents and data files (PDF, Word, Excel, CSV and the rest) \u2014 as ONE tool with actions. Nothing is searched for you: use it before answering anything that should come from those documents, and do not use it for general knowledge. Call action 'discover' FIRST when you do not already know what is there: it lists the documents, says which are spreadsheets, and says which actions this deployment can run. Then match the action to the task. 'search' finds passages by meaning or keywords \u2014 for questions answered by reading text. Looking up an identifier (an ID, code, SKU or invoice number) is the exception: search the BARE identifier alone, e.g. '2525', never the whole question. Those are CONTENT identifiers \u2014 written inside a document \u2014 and they belong in a query; a document_id is a system id (a uuid) that only discover, list or a search hit can give you, so never search a uuid as text and never hand an invoice number to get_doc. 'get_doc' reads one whole document by id, 'get_docs' reads several at once, and 'get_chunks' walks one long document in order a piece at a time when you need more of it than an excerpt; 'list' browses the documents without searching. 'map_reduce' asks the SAME question of every document in scope and answers once per document \u2014 for 'which contracts mention X', where search would return a handful of passages and miss the rest. 'query_meta' filters and aggregates documents by their structured fields (dates, amounts, categories) \u2014 usually the right action for a question about spreadsheet data. 'compute' runs code over the spreadsheets for any figure DERIVED from them \u2014 a total, average, count, ranking, margin or comparison across rows \u2014 AND for finding the exact row matching one id or value. In a large table, search cannot reliably locate an individual row; compute can. When the question is about how things are CONNECTED rather than what a document says \u2014 who works with whom, what belongs to what, what a change touches \u2014 use the graph actions: 'get_neighbors' for what is one step from one thing, 'traverse' for everything within a few steps of it, 'find_related' for connections of a kind across the corpus, and 'community_summary' for the themes the corpus groups into. They are available only where a graph was built; discover says so. Searching with mode='graph' ranks passages by those same connections instead of by wording alone, which finds a passage that never repeats your words. Rules that decide answers: search returns EXCERPTS, and rows of a spreadsheet are not arithmetic \u2014 never add up, average or rank rows yourself from what search returned, and never say a figure is not available before computing over the sheet that holds it. A listing that says has_more has MORE: send its next_cursor back as 'cursor' for the next page, and never conclude a document is absent from a first page that was truncated. Search again with different words before saying a document is missing. A result may carry a next_action (or next_page): it is the call to make next, already filled in \u2014 follow it rather than guessing the next step. Cite document names.";
+var KNOWLEDGE_TOOL_DESCRIPTION = "The knowledge base \u2014 the ingested documents and data files (PDF, Word, Excel, CSV and the rest) \u2014 as ONE tool with actions. Nothing is searched for you: use it before answering anything that should come from those documents, and do not use it for general knowledge. Call action 'discover' FIRST when you do not already know what is there: it lists the documents and says what is INSIDE each one \u2014 a spreadsheet's sheet names, column headers and row counts; a document's section titles and last page; a JSON file's top-level keys \u2014 plus the extracted field names grouped by document type with each field's data type and how many documents carry it, a census of the whole corpus, and which actions this deployment can run. Use those names verbatim: they are what compute, query_meta and get_chunks match on, so one discover is enough and you never have to go looking for a column, a section or a field name. A long list is shortened there, with the rest reported as a count and, when it is worth the trip, the exact call that returns it in full \u2014 discover again with document_ids set to that one document, which answers whole. When it is not worth the trip the payload says so and says what to do instead: a sheet with hundreds of columns is one to compute over, never one to read back. Then match the action to the task. 'search' finds passages by meaning or keywords \u2014 for questions answered by reading text. Looking up an identifier (an ID, code, SKU or invoice number) is the exception: search the BARE identifier alone, e.g. '2525', never the whole question. Those are CONTENT identifiers \u2014 written inside a document \u2014 and they belong in a query; a document_id is a system id (a uuid) that only discover, list or a search hit can give you, so never search a uuid as text and never hand an invoice number to get_doc. 'get_doc' reads one whole document by id, 'get_docs' reads several at once, and 'get_chunks' walks one long document in order a piece at a time when you need more of it than an excerpt; 'list' browses the documents without searching. 'map_reduce' asks the SAME question of every document in scope and answers once per document \u2014 for 'which contracts mention X', where search would return a handful of passages and miss the rest. 'query_meta' filters and aggregates documents by their structured fields (dates, amounts, categories) \u2014 usually the right action for a question about spreadsheet data. 'compute' runs code over the spreadsheets for any figure DERIVED from them \u2014 a total, average, count, ranking, margin or comparison across rows \u2014 AND for finding the exact row matching one id or value. In a large table, search cannot reliably locate an individual row; compute can. When the question is about how things are CONNECTED rather than what a document says \u2014 who works with whom, what belongs to what, what a change touches \u2014 use the graph actions: 'get_neighbors' for what is one step from one thing, 'traverse' for everything within a few steps of it, 'find_related' for connections of a kind across the corpus, and 'community_summary' for the themes the corpus groups into. They are available only where a graph was built; discover says so. Searching with mode='graph' ranks passages by those same connections instead of by wording alone, which finds a passage that never repeats your words. Rules that decide answers: search returns EXCERPTS, and rows of a spreadsheet are not arithmetic \u2014 never add up, average or rank rows yourself from what search returned, and never say a figure is not available before computing over the sheet that holds it. A listing that says has_more has MORE: send its next_cursor back as 'cursor' for the next page, and never conclude a document is absent from a first page that was truncated. Search again with different words before saying a document is missing. A result may carry a next_action (or next_page): it is the call to make next, already filled in \u2014 follow it rather than guessing the next step. Cite document names.";
 var ACTION_PARAM_DESCRIPTION = "Match it to the task: reading questions -> search (a bare identifier for an ID or code); spreadsheet analysis, or the exact row for one id or value -> query_meta or compute; how things connect -> get_neighbors, traverse, find_related or community_summary; browse everything -> list; unsure what exists -> discover first.";
 var ACTION_HELP = {
   search: "passages by meaning or keywords; an ID, code or number as the BARE identifier",
@@ -432,7 +432,7 @@ var OFF = {
   graph: "the graph actions are off: this deployment has no graph configured, so nothing has been linked up. Use search, get_doc or list instead."
 };
 var GRAPH_ACTIONS = ["traverse", "find_related", "get_neighbors", "community_summary"];
-var DOCUMENT_ID_ACTIONS = ["search", "compute", "get_docs", "map_reduce"];
+var DOCUMENT_ID_ACTIONS = ["search", "compute", "get_docs", "map_reduce", "discover", "list"];
 var DEFAULT_GET_DOCS_CHARS = 2e5;
 var INPUT_PROPERTIES = {
   action: { type: "string", enum: [...KNOWLEDGE_ACTIONS], description: ACTION_PARAM_DESCRIPTION },
@@ -452,7 +452,7 @@ var INPUT_PROPERTIES = {
   document_ids: {
     type: "array",
     items: { type: "string" },
-    description: "Narrows to these documents, using ids from discover, list or a search hit. It INTERSECTS with source_ids, so a document outside the sources you named returns nothing. (for search, compute)"
+    description: "Narrows to these documents, using ids from discover, list or a search hit. It INTERSECTS with source_ids, so a document outside the sources you named returns nothing. On discover it also asks for those documents' structure IN FULL, past the shortening a whole-page discover applies. (for search, compute, get_docs, map_reduce, discover, list)"
   },
   entity: {
     type: "string",
@@ -568,11 +568,16 @@ function parseCursor(cursor) {
   }
   return parsed;
 }
-async function listPage(engine, sourceIds, principals, action, limit, cursor, ceiling, redaction) {
+async function listPage(engine, sourceIds, principals, action, limit, cursor, documentIds, ceiling, redaction) {
   const page = await engine.listDocuments({
     // `!= null`, NOT truthiness: an EMPTY array means "nothing is in scope"
     // and collapsing it to null would list the whole corpus.
     sourceIds: sourceIds != null ? [...new Set(sourceIds)] : null,
+    // Already intersected with the host's ceiling by `narrowToCeiling`, and
+    // filtered in SQL rather than after the page is built — three named
+    // documents sitting on page four must come back as themselves, not as an
+    // empty page.
+    documentIds: documentIds != null ? [...new Set(documentIds)] : null,
     principals,
     cursor,
     limit: Math.max(1, Math.min(limit, MAX_LIST_LIMIT)),
@@ -582,7 +587,9 @@ async function listPage(engine, sourceIds, principals, action, limit, cursor, ce
     id: String(raw.id),
     name: raw.name,
     source_id: raw.sourceId ?? raw.source_id,
-    kind: documentKind(raw)
+    kind: documentKind(raw),
+    document_type: raw.documentType ?? raw.document_type ?? null,
+    mode: raw.mode ?? null
   }));
   if (ceiling.documentIds != null) {
     const allowed = new Set(ceiling.documentIds);
@@ -635,30 +642,62 @@ async function callKnowledgeTool(engine, args) {
       action,
       args.limit ?? 50,
       parseCursor(args.cursor),
+      documentIds,
       ceiling,
       args.redaction
     );
     if (action === "list") return { success: true, ...page };
-    const spreadsheets = page.documents.filter((d) => d.kind === "spreadsheet").map((d) => d.name);
+    const structures = await engine.documentStructure({
+      documentIds: page.documents.map((d) => d.id),
+      sourceIds,
+      principals,
+      // The cap is for the call that did NOT name its documents. A caller
+      // that asked about specific documents asked for all of them, and the
+      // truncated payload tells it to make exactly this call — so answering
+      // it truncated again would be a loop.
+      bounded: !requestedDocumentIds?.length,
+      redaction: args.redaction
+    });
+    for (const doc of page.documents) doc.structure = structures[doc.id] ?? {};
+    const hasSpreadsheet = page.documents.some((d) => d.kind === "spreadsheet");
+    const fieldsByType = await engine.fieldSummary({
+      sourceIds,
+      documentIds,
+      principals,
+      redaction: args.redaction
+    });
+    const census = await engine.documentTypes({
+      sourceIds,
+      documentIds,
+      principals,
+      redaction: args.redaction
+    });
     const forAFact = { action: "search", query: "<bare identifier or key words>" };
     const nextAction = {};
-    if (spreadsheets.length && available.compute) {
+    if (hasSpreadsheet && available.compute) {
       nextAction["for a figure from a spreadsheet"] = {
         action: "compute",
-        query: "<what to compute, columns as named>"
+        query: "<what to compute, columns as named above>"
       };
     }
     nextAction["for a clause or a fact"] = forAFact;
+    if (fieldsByType.length && available.query_meta) {
+      nextAction["for documents by a field value"] = {
+        action: "query_meta",
+        query: "<a question naming a field from fields_by_type>"
+      };
+    }
     if (available.get_neighbors) {
       nextAction["for how things connect"] = {
         action: "get_neighbors",
         entity: "<a name that appears in the documents>"
       };
     }
-    return {
+    const discovered = {
       success: true,
       ...page,
-      spreadsheets,
+      document_types: census,
+      fields_by_type: fieldsByType,
       available_actions: Object.fromEntries(
         Object.keys(ACTION_HELP).map((name) => [
           name,
@@ -667,6 +706,7 @@ async function callKnowledgeTool(engine, args) {
       ),
       next_action: nextAction
     };
+    return discovered;
   }
   if (action === "search") {
     if (!text) return { success: false, error: "search needs a query" };