@promptev/context-engine 0.0.1 → 0.0.3

package/dist/{router-Dsv3fv0R.d.cts → router-CiFwC-EN.d.cts}

@@ -1,4 +1,4 @@
-import { T as ToolEngine, a as ToolConfig } from './governance-D8g6Wyvb.cjs';
+import { T as ToolEngine, a as ToolConfig } from './governance-P9pRb4Ol.cjs';
 
 type ContextEngineLike = {
     ingest: (args: Record<string, unknown>) => Promise<unknown>;

package/dist/{router-B_DTkQgU.d.ts → router-D8gBzwLd.d.ts}

@@ -1,4 +1,4 @@
-import { T as ToolEngine, a as ToolConfig } from './governance-XFVgtEdV.js';
+import { T as ToolEngine, a as ToolConfig } from './governance-BLPK7NMe.js';
 
 type ContextEngineLike = {
     ingest: (args: Record<string, unknown>) => Promise<unknown>;

package/dist/skills/context-engine/SKILL.md

@@ -62,6 +62,31 @@ await engine.search(q, { principals: user.groups }); // scoped
   no default. If you hit a `TypeError`, supply real ones — do **not** silence
   it with `principals: () => null`, which disables access control on a public
   port. Anonymous is `() => []`. Trusted is `() => TRUSTED`.
+- **Search picks its own mode unless you name one.** `search({ mode: null })` (the
+  default) adds the graph leg when the deployment has a graph AND something in
+  scope was ingested with `mode: "graph"` — a model cannot know which documents
+  those are, so it is not asked. Pass `mode: "hybrid"` to force the old
+  behaviour. INGESTION is unchanged and stays explicit. An unreachable graph
+  database is skipped rather than waited on, and every graph failure degrades
+  to the hybrid legs instead of failing the search.
+- **The knowledge tool is one call with THIRTEEN actions** — `discover`,
+  `search`, `get_doc`, `get_docs`, `get_chunks`, `list`, `query_meta`,
+  `compute`, `map_reduce`, `get_neighbors`, `traverse`, `find_related`,
+  `community_summary`.
+  `engine.searchKnowledgeBase({ action, principals, scope })` is the
+  same function `createMcpApp` serves. `knowledgeToolDefinition()` gives
+  the name, description and JSON Schema if you are wiring it into your own
+  agent loop. `compute` and `mapReduce` accept a host callable that REPLACES
+  the built-in one — that is the seam for your own permission, billing and
+  approval rules, and supplying one makes the action available regardless of
+  the deployment's own gate.
+- **`scope` is REQUIRED on `createMcpApp`** and on
+  `engine.searchKnowledgeBase`: the ceiling of source ids the tool may ever
+  reach. Like `principals` it is host-supplied and NEVER a tool argument — a
+  model can name any source id, and a tool that believed it would cross
+  tenants. Pass `scope: UNSCOPED` only to mean the whole corpus on purpose. A
+  caller narrows within the ceiling; an id outside it is dropped silently, and
+  a request left with nothing returns nothing (never everything).
 - **`acl=null` on `updateDocument` UNRESTRICTS the document.** "Leave it
   alone" is expressed by omitting the argument (the `UNSET` sentinel), because
   `null` already means unrestricted and cannot also mean absent. Same for
@@ -70,7 +95,11 @@ await engine.search(q, { principals: user.groups }); // scoped
   silently loses recall — queries return fewer rows than match, or none, with
   no error. The library cannot compensate.
 - **`config.enableCodeExecution` is `false` on purpose.** `engine.compute()`
-  executes generated code. Turn it on only deliberately.
+  and `computeOverFrames()` execute generated code. Turn it on only
+  deliberately. `computeOverFrames({ sheet: rows }, instruction, { config:
+  engine.config })` is the same guarded path for tables the host already holds
+  (no document to point at); redaction masks every string cell AND every column
+  header before the LLM sees a schema, and sweeps the result.
 - Filing a document under an ACL the caller does not hold returns **403**, on
   ingest and on PATCH alike.
 
@@ -126,11 +155,14 @@ app.route(
 `createFastifyPlugin` (`@promptev/context-engine/fastify`) and
 `createMcpApp` (`@promptev/context-engine/mcp`) take the same two
 arguments. MCP has no request object: `principals` is a zero-argument
-callable resolved fresh on every tool call. The CLI `context-engine mcp`
+callable resolved fresh on every tool call, and `createMcpApp` also requires
+`scope` — the source-id ceiling, resolved the same way. The CLI `context-engine mcp`
 binds `127.0.0.1` and answers as anonymous (`principals=[]`).
 
 Not on a supported framework? Call `engine.search()` / `engine.ingest()`
-from your own handler — the routers are thin wrappers over the same core.
+from your own handler — the routers are thin wrappers over the same core. For
+an agent, `engine.searchKnowledgeBase({ action, principals, scope })` is the
+same one tool the MCP server serves, with no transport in the way.
 
 ## Lifecycle
 

package/dist/{storage-DU1JRno5.d.cts → storage-CJrKgJeJ.d.ts}

@@ -1,11 +1,14 @@
-import { b as EmbeddingConfig } from './config-CNnASw5X.cjs';
+import { b as EmbeddingConfig } from './config-BODDdXJ7.js';
 import { PoolClient, Pool } from 'pg';
 
 /**
  * Pluggable embeddings provider.
  *
  * openai / azure_openai / custom → OpenAI SDK (OpenAI-compatible, including TEI/vLLM).
- * gemini → lazy `@google/genai` (optional extra "gemini").
+ * gemini / vertex_ai → lazy `@google/genai` (optional extra "gemini"). One
+ * code path: same SDK and models, differing only in how the client
+ * authenticates (API key vs ADC against a GCP project) — see
+ * `providers/google.ts`.
  * voyage / cohere → fetch against their public REST APIs.
  *
  * `kind` is accepted everywhere but only voyage/cohere act on it.

package/dist/{storage-Dvt2ZxsV.d.ts → storage-Dvpq2xAC.d.cts}

@@ -1,11 +1,14 @@
-import { b as EmbeddingConfig } from './config-CdlSkKgV.js';
+import { b as EmbeddingConfig } from './config-C5RZ00W6.cjs';
 import { PoolClient, Pool } from 'pg';
 
 /**
  * Pluggable embeddings provider.
  *
  * openai / azure_openai / custom → OpenAI SDK (OpenAI-compatible, including TEI/vLLM).
- * gemini → lazy `@google/genai` (optional extra "gemini").
+ * gemini / vertex_ai → lazy `@google/genai` (optional extra "gemini"). One
+ * code path: same SDK and models, differing only in how the client
+ * authenticates (API key vs ADC against a GCP project) — see
+ * `providers/google.ts`.
  * voyage / cohere → fetch against their public REST APIs.
  *
  * `kind` is accepted everywhere but only voyage/cohere act on it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptev/context-engine",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Promptev Context Engine — language-agnostic ingestion + hybrid retrieval (TypeScript)",
   "license": "Apache-2.0",
   "author": "Promptev Inc",

package/src/skills/context-engine/SKILL.md

@@ -62,6 +62,31 @@ await engine.search(q, { principals: user.groups }); // scoped
   no default. If you hit a `TypeError`, supply real ones — do **not** silence
   it with `principals: () => null`, which disables access control on a public
   port. Anonymous is `() => []`. Trusted is `() => TRUSTED`.
+- **Search picks its own mode unless you name one.** `search({ mode: null })` (the
+  default) adds the graph leg when the deployment has a graph AND something in
+  scope was ingested with `mode: "graph"` — a model cannot know which documents
+  those are, so it is not asked. Pass `mode: "hybrid"` to force the old
+  behaviour. INGESTION is unchanged and stays explicit. An unreachable graph
+  database is skipped rather than waited on, and every graph failure degrades
+  to the hybrid legs instead of failing the search.
+- **The knowledge tool is one call with THIRTEEN actions** — `discover`,
+  `search`, `get_doc`, `get_docs`, `get_chunks`, `list`, `query_meta`,
+  `compute`, `map_reduce`, `get_neighbors`, `traverse`, `find_related`,
+  `community_summary`.
+  `engine.searchKnowledgeBase({ action, principals, scope })` is the
+  same function `createMcpApp` serves. `knowledgeToolDefinition()` gives
+  the name, description and JSON Schema if you are wiring it into your own
+  agent loop. `compute` and `mapReduce` accept a host callable that REPLACES
+  the built-in one — that is the seam for your own permission, billing and
+  approval rules, and supplying one makes the action available regardless of
+  the deployment's own gate.
+- **`scope` is REQUIRED on `createMcpApp`** and on
+  `engine.searchKnowledgeBase`: the ceiling of source ids the tool may ever
+  reach. Like `principals` it is host-supplied and NEVER a tool argument — a
+  model can name any source id, and a tool that believed it would cross
+  tenants. Pass `scope: UNSCOPED` only to mean the whole corpus on purpose. A
+  caller narrows within the ceiling; an id outside it is dropped silently, and
+  a request left with nothing returns nothing (never everything).
 - **`acl=null` on `updateDocument` UNRESTRICTS the document.** "Leave it
   alone" is expressed by omitting the argument (the `UNSET` sentinel), because
   `null` already means unrestricted and cannot also mean absent. Same for
@@ -70,7 +95,11 @@ await engine.search(q, { principals: user.groups }); // scoped
   silently loses recall — queries return fewer rows than match, or none, with
   no error. The library cannot compensate.
 - **`config.enableCodeExecution` is `false` on purpose.** `engine.compute()`
-  executes generated code. Turn it on only deliberately.
+  and `computeOverFrames()` execute generated code. Turn it on only
+  deliberately. `computeOverFrames({ sheet: rows }, instruction, { config:
+  engine.config })` is the same guarded path for tables the host already holds
+  (no document to point at); redaction masks every string cell AND every column
+  header before the LLM sees a schema, and sweeps the result.
 - Filing a document under an ACL the caller does not hold returns **403**, on
   ingest and on PATCH alike.
 
@@ -126,11 +155,14 @@ app.route(
 `createFastifyPlugin` (`@promptev/context-engine/fastify`) and
 `createMcpApp` (`@promptev/context-engine/mcp`) take the same two
 arguments. MCP has no request object: `principals` is a zero-argument
-callable resolved fresh on every tool call. The CLI `context-engine mcp`
+callable resolved fresh on every tool call, and `createMcpApp` also requires
+`scope` — the source-id ceiling, resolved the same way. The CLI `context-engine mcp`
 binds `127.0.0.1` and answers as anonymous (`principals=[]`).
 
 Not on a supported framework? Call `engine.search()` / `engine.ingest()`
-from your own handler — the routers are thin wrappers over the same core.
+from your own handler — the routers are thin wrappers over the same core. For
+an agent, `engine.searchKnowledgeBase({ action, principals, scope })` is the
+same one tool the MCP server serves, with no transport in the way.
 
 ## Lifecycle