@promptev/context-engine 0.0.3 → 0.0.4

package/README.md

@@ -186,7 +186,7 @@ One tool with actions:
 
 | Action | What it is for |
 |---|---|
-| `discover` | what documents there are and what each action can do — call it first |
+| `discover` | what documents there are and what is inside each one — sheets and columns, sections and pages, or JSON keys — plus the extracted fields by document type, a census of the corpus, and what each action can do. Call it first |
 | `search` | passages by meaning or keywords |
 | `get_doc` / `get_docs` | one whole document by id, or several at once |
 | `get_chunks` | walk one long document in order, a piece at a time |
@@ -204,6 +204,30 @@ as off rather than hidden, and called anyway it answers `{ success: false,
 error }` the model can relay. A truncated answer carries the `next_page` call
 that reads the rest.
 
+`discover` answers with the SCHEMA, not an inventory, so one call is enough to
+write one correct `compute` or `query_meta` call instead of three exploratory
+ones. Every listed document carries `document_type`, `mode`, and a `structure`
+whose shape follows the type — `sheets` (name, column headers, row count) for
+a workbook, `sections` and `last_page` for a document with headings, `keys`
+for JSON, and `chunks` as the floor for anything else. Beside them,
+`fields_by_type` lists the extracted structured field names with each field's
+data type and how many in-scope documents carry it, and `document_types` is a
+census of the corpus. Both are keyed by `(kind, type)`: `kind` comes from the
+mime and is always known, while `document_type` is free text an LLM wrote and
+exists only where `extractStructured` was enabled — so a PDF invoice and a
+spreadsheet of invoice rows stay separate rather than merging under one label.
+
+Lists inside a `structure` are capped, with the remainder reported as
+`more_columns` / `more_sections` / `more_keys` / `more_sheets`, because
+`discover` is the first call of a conversation and an unbounded list lands in
+the model's context before it has asked anything. **The cap is for the call
+that did not name its documents:** `discover` and `list` take `document_ids`,
+and a `discover` scoped to specific documents answers their structure whole
+and narrows the field grouping and the census to them too. While the remainder
+is small enough to be worth fetching, the truncated structure carries that
+call already filled in; past that it says what to do instead, because a sheet
+with hundreds of columns is one to compute over rather than read back.
+
 Omit `mode` on a search and it is worked out from the documents in scope — the
 graph leg is added when the deployment has a graph and something in scope was
 ingested that way, and it runs beside the other legs rather than ahead of