@promptev/client 1.2.0 → 1.3.0

package/dist/cjs/index.cjs

@@ -12,7 +12,7 @@
  *   - `uploadDocument()`  — put files into the key's project corpus.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.InsufficientCreditsError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = exports.MAX_FILES_PER_RUN = exports.MAX_UPLOAD_BYTES = exports.MAX_FILES_PER_REQUEST = exports.MAX_MESSAGE_CHARS = exports.DEFAULT_BASE_URL = void 0;
+exports.PromptevClient = exports.NetworkError = exports.ServerError = exports.InsufficientCreditsError = exports.RateLimitError = exports.NotFoundError = exports.AuthenticationError = exports.ValidationError = exports.PromptevError = exports.KNOWLEDGE_ACTIONS = exports.MAX_FILES_PER_RUN = exports.MAX_UPLOAD_BYTES = exports.MAX_FILES_PER_REQUEST = exports.MAX_MESSAGE_CHARS = exports.DEFAULT_BASE_URL = void 0;
 // ── Configuration ───────────────────────────────────────
 /**
  * The default host. NOT `api.promptev.ai` — that host still serves the
@@ -39,6 +39,13 @@ exports.MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 /** Files ONE orchestration run may carry — the same ceiling a chat turn has.
  *  Server-side: `run_inputs.MAX_FILE_PARTS`. */
 exports.MAX_FILES_PER_RUN = 5;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+exports.KNOWLEDGE_ACTIONS = [
+    "discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks",
+    "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary",
+];
 // ── Errors ──────────────────────────────────────────────
 class PromptevError extends Error {
     constructor(message, statusCode, responseText, field) {
@@ -459,6 +466,43 @@ class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    async searchKnowledgeBase(action, fields = {}, options) {
+        if (typeof action !== "string" || !action.trim()) {
+            throw new ValidationError('Name the action, e.g. "search".', undefined, undefined, "action");
+        }
+        const body = { action: action.trim() };
+        for (const [key, value] of Object.entries(fields ?? {})) {
+            if (value !== undefined && value !== null)
+                body[key] = value;
+        }
+        const headers = this.authHeaders();
+        headers["Content-Type"] = "application/json";
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/api/v1/knowledge`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        return text ? JSON.parse(text) : {};
+    }
     async runOrchestration(slug, inputs = {}, options) {
         if (!slug || !slug.trim()) {
             throw new ValidationError("Name the orchestration to run.", undefined, undefined, "slug");

package/dist/esm/index.d.ts

@@ -35,6 +35,11 @@ export declare const MAX_UPLOAD_BYTES: number;
 /** Files ONE orchestration run may carry — the same ceiling a chat turn has.
  *  Server-side: `run_inputs.MAX_FILE_PARTS`. */
 export declare const MAX_FILES_PER_RUN = 5;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+export declare const KNOWLEDGE_ACTIONS: readonly ["discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks", "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary"];
+export type KnowledgeAction = (typeof KNOWLEDGE_ACTIONS)[number];
 export interface PromptevClientConfig {
     /**
      * Your Promptev API key — `fk_…`, minted in Settings → API keys of the
@@ -539,6 +544,25 @@ export declare class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    searchKnowledgeBase(action: KnowledgeAction | (string & {}), fields?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, any>>;
     runOrchestration(slug: string, inputs?: RunInputs, options?: RunOptions): Promise<StartedRun>;
     /**
      * What became of a run — poll this after {@link runOrchestration}.

package/dist/esm/index.js

@@ -36,6 +36,13 @@ export const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 /** Files ONE orchestration run may carry — the same ceiling a chat turn has.
  *  Server-side: `run_inputs.MAX_FILE_PARTS`. */
 export const MAX_FILES_PER_RUN = 5;
+/** The knowledge base's actions, as the project MCP's `search_knowledge_base`
+ *  offers them. Informational: the server decides, so an action added there
+ *  works here without a new SDK. */
+export const KNOWLEDGE_ACTIONS = [
+    "discover", "search", "get_doc", "list", "query_meta", "compute", "get_chunks",
+    "get_docs", "map_reduce", "traverse", "find_related", "get_neighbors", "community_summary",
+];
 // ── Errors ──────────────────────────────────────────────
 export class PromptevError extends Error {
     constructor(message, statusCode, responseText, field) {
@@ -448,6 +455,43 @@ export class PromptevClient {
      * );
      * ```
      */
+    /**
+     * Read the key's project knowledge base through the Context Engine: the
+     * same tool, with the same actions, as `search_knowledge_base` on the
+     * project's MCP server (`POST /api/v1/knowledge`).
+     *
+     * ```ts
+     * const overview = await client.searchKnowledgeBase("discover");
+     * const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+     * for (const hit of found.hits) console.log(hit.document_name, hit.chunk_text);
+     * const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+     * ```
+     *
+     * `fields` are that action's fields (`query`, `top_k`, `document_id`,
+     * `source_ids`, `mode`, `limit`, `cursor`, ...); undefined and null ones
+     * are not sent. Returns the knowledge base's answer as an object.
+     */
+    async searchKnowledgeBase(action, fields = {}, options) {
+        if (typeof action !== "string" || !action.trim()) {
+            throw new ValidationError('Name the action, e.g. "search".', undefined, undefined, "action");
+        }
+        const body = { action: action.trim() };
+        for (const [key, value] of Object.entries(fields ?? {})) {
+            if (value !== undefined && value !== null)
+                body[key] = value;
+        }
+        const headers = this.authHeaders();
+        headers["Content-Type"] = "application/json";
+        const resp = await this.fetchWithRetry(`${this.baseUrl}/api/v1/knowledge`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: options?.signal,
+        });
+        const text = await resp.text();
+        PromptevClient.raiseForStatus(resp.status, text, resp.headers);
+        return text ? JSON.parse(text) : {};
+    }
     async runOrchestration(slug, inputs = {}, options) {
         if (!slug || !slug.trim()) {
             throw new ValidationError("Name the orchestration to run.", undefined, undefined, "slug");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptev/client",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "JavaScript/TypeScript client for Promptev — stream your AI agents and upload documents with a workspace API key",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/readme.md

@@ -1,6 +1,6 @@
 # Promptev JavaScript client
 
-The official JavaScript/TypeScript client for [Promptev](https://promptev.ai) — stream your AI **agents** and upload documents to their knowledge base, from anywhere that has `fetch`.
+The official JavaScript/TypeScript client for [Promptev](https://promptev.ai) — stream your AI **agents**, put documents into the Context Engine and search it, from anywhere that has `fetch`.
 
 > In Promptev, an **agent** is your deployed AI assistant: instructions + model + tools (Jira, Slack, GitHub, your own APIs) + the documents it can retrieve, all configured in the app. This client runs those agents. Tools execute server-side, retrieval is governed server-side, and conversation memory is built in.
 
@@ -274,6 +274,25 @@ A per-file failure is *reported*, not thrown: every file gets a row in `results`
 
 > Ingestion is slow and the request does not return until every file is indexed. Raise `timeout` well above its 30-second default: `new PromptevClient({ apiKey, timeout: 300_000 })`.
 
+## `searchKnowledgeBase` — search the knowledge base
+
+```ts
+client.searchKnowledgeBase(action, fields?, options?): Promise<Record<string, any>>
+```
+
+Reads your key's project knowledge base through the Context Engine. It is the same tool, with the same actions, as `search_knowledge_base` on the project's MCP server. Start with `discover` to see what is there, then `search` for passages or `get_doc` for one document:
+
+```ts
+const overview = await client.searchKnowledgeBase("discover");
+
+const found = await client.searchKnowledgeBase("search", { query: "how many days do customers have to ask for a refund", top_k: 5 });
+for (const hit of found.hits) console.log(hit.document_name, hit.score, hit.chunk_text);
+
+const doc = await client.searchKnowledgeBase("get_doc", { document_id: found.hits[0].document_id });
+```
+
+The actions are exported as `KNOWLEDGE_ACTIONS`: `discover`, `search`, `get_doc`, `list`, `query_meta`, `compute`, `get_chunks`, `get_docs`, `map_reduce`, `traverse`, `find_related`, `get_neighbors` and `community_summary`. `fields` are that action's fields (`query`, `top_k`, `document_id`, `source_ids`, `mode`, `limit`, `cursor`, ...). The key reads only its own project.
+
 ## `runOrchestration` — run a team of agents
 
 An orchestration is a **team of agents** working one job. `chat` streams one agent's answer inline; an orchestration runs in a worker for as long as it takes, so `runOrchestration` hands back a run id straight away and `getRun` says what became of it.
@@ -394,9 +413,7 @@ All errors extend `PromptevError` and carry:
 ## What a call costs
 
 Promptev is pay as you go and this API is metered. The rates below are the
-managed ones; a workspace running on its own database and embedding provider
-(BYO) is charged a flat **1** per operation instead, because those bills are
-already yours.
+same for every workspace, including one on its own database or models.
 
 | what happens | credits |
 |---|---|
@@ -406,6 +423,7 @@ already yours.
 | retrieval | **1** per knowledge base searched |
 | retrieval in graph mode | **5** per knowledge base searched |
 | a document you upload | **1** per page, slide or MB (minimum 1) |
+| `searchKnowledgeBase` | the same as on the MCP server: **1** per call, **+1** for a search (**+5** when the graph is searched); no `api_call` charge |
 
 So an ordinary `chat` costs **2** — one for the request, one for the turn — and
 more if the agent calls tools or searches knowledge. The same conversation held