@promptev/context-engine 0.0.1 → 0.0.3

package/README.md

@@ -147,6 +147,29 @@ trusted caller and returns the entire corpus. Use `[]` or `TRUSTED` explicitly.
 npx context-engine install-skill
 ```
 
+## Compute over tables
+
+`engine.compute()` turns the in-scope CSV/XLSX documents into row tables and has
+the LLM write code against them. `computeOverFrames()` is the same path for
+tables you already hold — an uploaded workbook, a connector's sheet, a query
+result — with no document to point at:
+
+```ts
+import { computeOverFrames } from "@promptev/context-engine";
+
+const out = await computeOverFrames(
+  { expenses: rows },             // { sheetName: Array<Record<string, unknown>> }
+  "total the amount column",
+  { config: engine.config },
+);
+out.result;
+```
+
+Both are **off by default** (`enableCodeExecution: true` turns them on — only
+behind real OS-level isolation) and both apply `config.redaction` before the LLM
+sees anything: every string cell *and* every column header is masked, and the
+returned object — generated code included — is swept on the way out.
+
 ## Serve
 
 ```ts
@@ -157,6 +180,63 @@ const router = createHonoRouter(engine, { auth: myAuth, principals: myPrincipals
 
 `auth` and `principals` are required. Identical routes exist for Express and Fastify.
 
+## The knowledge tool
+
+One tool with actions:
+
+| Action | What it is for |
+|---|---|
+| `discover` | what documents there are 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 |
+| `list` | browse the documents without searching |
+| `query_meta` | filter documents by their structured fields |
+| `compute` | a figure derived from the spreadsheets, over every row |
+| `map_reduce` | the same question asked of every document in scope |
+| `get_neighbors` / `traverse` | what is one step, or a few steps, from a named thing |
+| `find_related` | connections of a kind across the corpus |
+| `community_summary` | the themes the corpus groups into |
+
+One description carries the decision rules once and there is one name for a
+model to route through. An action this deployment cannot service is advertised
+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.
+
+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
+them. Naming `"hybrid"` or `"graph"` forces one.
+
+```ts
+import { UNSCOPED } from "@promptev/context-engine";
+
+const answer = await engine.searchKnowledgeBase({
+  action: "search",
+  query: "annual leave",
+  principals: caller,
+  scope: ["hr"],
+});
+```
+
+`createMcpApp` serves that same function, so an application driving its own
+agent loop needs no MCP and cannot get a different answer.
+`knowledgeToolDefinition()` exports the tool as data — name, description and
+input schema as JSON Schema — so a host never hand-writes it. `createMcpApp`
+also takes `redaction` (applied per call), and `compute` / `mapReduce`
+callables that REPLACE the built-in ones, which is where a host applies its own
+rules for permission, billing and approval.
+
+`scope` is REQUIRED on both: the ceiling of source ids (or a `Scope` with
+document ids) the tool may ever reach. It is host-supplied and resolved per
+call like `principals`, and never a tool argument — a model can name any
+source id, and a tool that believed it would let one caller read another's
+documents. Map your own word onto it: a project, a matter, a customer. A
+caller narrows within the ceiling and never past it; an id outside is dropped
+silently; a request left with nothing in scope returns nothing. A host with
+one shared corpus writes `scope: UNSCOPED` on purpose.
+
 ## Tools
 
 Register a governed tool — HTTP, SQL, MCP, or a plain function — and every call