@kognitivedev/cloud-knowledge-base 0.2.29

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+
+$ tsc

package/.turbo/turbo-test.log

@@ -0,0 +1,11 @@
+$ vitest run
+
+ RUN  v3.2.4 /Users/vserifsaglam/work/memory-experiment/packages/cloud-knowledge-base
+
+ ✓ src/__tests__/cloud-knowledge-base.test.ts (12 tests) 49ms
+
+ Test Files  1 passed (1)
+      Tests  12 passed (12)
+   Start at  17:30:10
+   Duration  942ms (transform 115ms, setup 0ms, collect 225ms, tests 49ms, environment 0ms, prepare 187ms)
+

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @kognitivedev/cloud-knowledge-base
+
+## 0.2.29
+
+### Patch Changes
+
+- release
+
+- Updated dependencies []:
+  - @kognitivedev/agents@0.2.29
+  - @kognitivedev/documents@0.2.29
+  - @kognitivedev/shared@0.2.29
+  - @kognitivedev/tools@0.2.29
+  - @kognitivedev/workflows@0.2.29

package/README.md

@@ -0,0 +1,88 @@
+# @kognitivedev/cloud-knowledge-base
+
+Managed cloud knowledge base SDK for Kognitive agents and workflows.
+
+This package targets managed cloud pipelines, which are also the dashboard knowledge-base resource. A pipeline ID is the knowledge-base ID across SDKs, dashboard, agents, and workflows.
+
+Managed knowledge bases are zero-config at the API level: documents are parsed into indexed artifacts and searched through Qdrant-native hybrid retrieval, using dense semantic vectors plus Qdrant BM25 sparse vectors.
+
+Backend requirements for managed KB indexing/search are `REDIS_URL`, `QDRANT_URL`, and `OPENROUTER_API_KEY`. `QDRANT_API_KEY` is optional depending on your Qdrant deployment. Pipeline sync is asynchronous, so clients should poll the pipeline run/status endpoints before relying on newly uploaded content in search.
+
+Every normalized hit includes citation metadata suitable for enterprise rendering and audit trails:
+
+- `sourceId`
+- `snippet`
+- `filename`
+- `mimeType`
+- `pageNumber`
+- `artifactType`
+- `parseDocumentId`
+
+## Search
+
+Create and sync the pipeline with `@kognitivedev/documents`, wait for the run to complete, then search it from this package:
+
+```ts
+import { KognitiveDocumentsClient } from "@kognitivedev/documents";
+import { searchCloudKnowledgeBase } from "@kognitivedev/cloud-knowledge-base";
+
+const documents = new KognitiveDocumentsClient({
+  baseUrl: process.env.KOGNITIVE_BASE_URL!,
+  apiKey: process.env.KOGNITIVE_API_KEY,
+});
+
+const pipeline = await documents.pipelines.create({ name: "Support KB" });
+const source = await documents.pipelines.addFile(pipeline.id, { fileId: "file-id" });
+const run = await documents.pipelines.sync(pipeline.id, { sourceId: String(source.id) });
+await documents.pipelines.getRun(pipeline.id, run.id);
+
+const result = await searchCloudKnowledgeBase({
+  baseUrl: process.env.KOGNITIVE_BASE_URL!,
+  apiKey: process.env.KOGNITIVE_API_KEY,
+  pipelineId: pipeline.id,
+  query: "What is the retention policy?",
+  topK: 5,
+  resourceId: { userId: "user_123" },
+});
+```
+
+## Agent Context Adapter
+
+```ts
+import { createAgent } from "@kognitivedev/agents";
+import { createCloudKnowledgeBaseContextAdapter } from "@kognitivedev/cloud-knowledge-base";
+
+const agent = createAgent({
+  name: "support-agent",
+  instructions: "Answer using the managed knowledge base when relevant.",
+  runtime,
+  contextAdapters: [
+    createCloudKnowledgeBaseContextAdapter({
+      baseUrl: process.env.KOGNITIVE_BASE_URL!,
+      apiKey: process.env.KOGNITIVE_API_KEY,
+      pipelineId: "pipe_123",
+      topK: 4,
+    }),
+  ],
+});
+```
+
+## Workflow Step
+
+```ts
+import { createWorkflow } from "@kognitivedev/workflows";
+import { createCloudKnowledgeBaseAnswerStep } from "@kognitivedev/cloud-knowledge-base";
+
+const workflow = createWorkflow<{ query: string }>({ name: "kb-answer" })
+  .then(createCloudKnowledgeBaseAnswerStep({
+    id: "answer",
+    agent,
+    baseUrl: process.env.KOGNITIVE_BASE_URL!,
+    apiKey: process.env.KOGNITIVE_API_KEY,
+    pipelineId: "pipe_123",
+    getQuery: (input) => input.query,
+  }))
+  .build();
+```
+
+There is also a lower-level `createCloudKnowledgeBaseSearchStep()` when you want retrieval without the answering stage.

package/dist/context-adapter.d.ts

@@ -0,0 +1,2 @@
+import type { CloudKnowledgeBaseContextAdapter, CloudKnowledgeBaseContextAdapterOptions } from "./types";
+export declare function createCloudKnowledgeBaseContextAdapter(options: CloudKnowledgeBaseContextAdapterOptions): CloudKnowledgeBaseContextAdapter;

package/dist/context-adapter.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCloudKnowledgeBaseContextAdapter = createCloudKnowledgeBaseContextAdapter;
+const shared_1 = require("./shared");
+const search_1 = require("./search");
+const tool_1 = require("./tool");
+function createInheritedSearchTool(options, input) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
+    if (options.autoRegisterSearchTool === false) {
+        return null;
+    }
+    return (0, tool_1.createCloudKnowledgeBaseSearchTool)(Object.assign(Object.assign(Object.assign({}, options), options.searchTool), { client: (_b = (_a = options.searchTool) === null || _a === void 0 ? void 0 : _a.client) !== null && _b !== void 0 ? _b : options.client, baseUrl: (_e = (_d = (_c = options.searchTool) === null || _c === void 0 ? void 0 : _c.baseUrl) !== null && _d !== void 0 ? _d : options.baseUrl) !== null && _e !== void 0 ? _e : input.baseUrl, apiKey: (_h = (_g = (_f = options.searchTool) === null || _f === void 0 ? void 0 : _f.apiKey) !== null && _g !== void 0 ? _g : options.apiKey) !== null && _h !== void 0 ? _h : input.apiKey, fetch: (_k = (_j = options.searchTool) === null || _j === void 0 ? void 0 : _j.fetch) !== null && _k !== void 0 ? _k : options.fetch, timeout: (_m = (_l = options.searchTool) === null || _l === void 0 ? void 0 : _l.timeout) !== null && _m !== void 0 ? _m : options.timeout, logLevel: (_p = (_o = options.searchTool) === null || _o === void 0 ? void 0 : _o.logLevel) !== null && _p !== void 0 ? _p : options.logLevel, pipelineId: (_r = (_q = options.searchTool) === null || _q === void 0 ? void 0 : _q.pipelineId) !== null && _r !== void 0 ? _r : options.pipelineId, resolvePipelineId: (_t = (_s = options.searchTool) === null || _s === void 0 ? void 0 : _s.resolvePipelineId) !== null && _t !== void 0 ? _t : options.resolvePipelineId }));
+}
+function createCloudKnowledgeBaseContextAdapter(options) {
+    return {
+        async resolve(input) {
+            var _a, _b;
+            const resolvedInput = input;
+            const searchTool = createInheritedSearchTool(options, resolvedInput);
+            const query = (options.buildQuery
+                ? await options.buildQuery(resolvedInput)
+                : (0, shared_1.extractLastUserText)(resolvedInput.messages))
+                .trim();
+            if (!query) {
+                return searchTool ? { tools: [searchTool] } : {};
+            }
+            const search = await (0, search_1.searchCloudKnowledgeBase)(Object.assign(Object.assign({}, options), { query, resourceId: resolvedInput.resourceId, messages: resolvedInput.messages, metadata: resolvedInput.metadata, abortSignal: resolvedInput.abortSignal, apiKey: (_a = options.apiKey) !== null && _a !== void 0 ? _a : resolvedInput.apiKey, baseUrl: (_b = options.baseUrl) !== null && _b !== void 0 ? _b : resolvedInput.baseUrl }));
+            return Object.assign({ systemBlock: (0, shared_1.buildSystemBlock)(search, {
+                    maxHits: options.maxContextHits,
+                    maxCharacters: options.maxContextCharacters,
+                    emptyStateMessage: options.emptyStateMessage,
+                }) }, (searchTool ? { tools: [searchTool] } : {}));
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { searchCloudKnowledgeBase } from "./search";
+export { createCloudKnowledgeBaseSearchTool } from "./tool";
+export { createCloudKnowledgeBaseContextAdapter } from "./context-adapter";
+export { createCloudKnowledgeBaseSearchStep, createCloudKnowledgeBaseAnswerStep, } from "./workflow";
+export { createKnowledgeBaseSearchStep, createKnowledgeBaseAnswerStep, DEFAULT_KNOWLEDGE_BASE_ANSWER_SCHEMA, } from "@kognitivedev/workflows";
+export type { CloudKnowledgeBaseCitation, CloudKnowledgeBaseHit, CloudKnowledgeBaseSearchResponse, CloudKnowledgeBaseAnswer, CloudKnowledgeBaseResolverInput, CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions, CloudKnowledgeBaseSearchOptions, CloudKnowledgeBaseSearchToolOptions, CloudKnowledgeBaseContextAdapterOptions, CloudKnowledgeBaseContextAdapter, CloudKnowledgeBaseSearchStepOptions, CloudKnowledgeBaseAnswerStepOptions, } from "./types";

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_KNOWLEDGE_BASE_ANSWER_SCHEMA = exports.createKnowledgeBaseAnswerStep = exports.createKnowledgeBaseSearchStep = exports.createCloudKnowledgeBaseAnswerStep = exports.createCloudKnowledgeBaseSearchStep = exports.createCloudKnowledgeBaseContextAdapter = exports.createCloudKnowledgeBaseSearchTool = exports.searchCloudKnowledgeBase = void 0;
+var search_1 = require("./search");
+Object.defineProperty(exports, "searchCloudKnowledgeBase", { enumerable: true, get: function () { return search_1.searchCloudKnowledgeBase; } });
+var tool_1 = require("./tool");
+Object.defineProperty(exports, "createCloudKnowledgeBaseSearchTool", { enumerable: true, get: function () { return tool_1.createCloudKnowledgeBaseSearchTool; } });
+var context_adapter_1 = require("./context-adapter");
+Object.defineProperty(exports, "createCloudKnowledgeBaseContextAdapter", { enumerable: true, get: function () { return context_adapter_1.createCloudKnowledgeBaseContextAdapter; } });
+var workflow_1 = require("./workflow");
+Object.defineProperty(exports, "createCloudKnowledgeBaseSearchStep", { enumerable: true, get: function () { return workflow_1.createCloudKnowledgeBaseSearchStep; } });
+Object.defineProperty(exports, "createCloudKnowledgeBaseAnswerStep", { enumerable: true, get: function () { return workflow_1.createCloudKnowledgeBaseAnswerStep; } });
+var workflows_1 = require("@kognitivedev/workflows");
+Object.defineProperty(exports, "createKnowledgeBaseSearchStep", { enumerable: true, get: function () { return workflows_1.createKnowledgeBaseSearchStep; } });
+Object.defineProperty(exports, "createKnowledgeBaseAnswerStep", { enumerable: true, get: function () { return workflows_1.createKnowledgeBaseAnswerStep; } });
+Object.defineProperty(exports, "DEFAULT_KNOWLEDGE_BASE_ANSWER_SCHEMA", { enumerable: true, get: function () { return workflows_1.DEFAULT_KNOWLEDGE_BASE_ANSWER_SCHEMA; } });

package/dist/search.d.ts

@@ -0,0 +1,2 @@
+import type { CloudKnowledgeBaseSearchOptions, CloudKnowledgeBaseSearchResponse } from "./types";
+export declare function searchCloudKnowledgeBase(options: CloudKnowledgeBaseSearchOptions): Promise<CloudKnowledgeBaseSearchResponse>;

package/dist/search.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchCloudKnowledgeBase = searchCloudKnowledgeBase;
+const shared_1 = require("./shared");
+async function searchCloudKnowledgeBase(options) {
+    const query = options.query.trim();
+    if (!query) {
+        throw new Error("Cloud knowledge base search requires a non-empty query.");
+    }
+    const { client, pipelineId } = await (0, shared_1.resolveSearchConfig)(options, {
+        resourceId: options.resourceId,
+        messages: options.messages,
+        metadata: options.metadata,
+        abortSignal: options.abortSignal,
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+    });
+    try {
+        const results = await client.pipelines.search(pipelineId, {
+            query,
+            topK: options.topK,
+            retrievalMode: options.retrievalMode,
+        });
+        const hits = results.map((result) => (0, shared_1.normalizeSearchResult)(result, options.snippetMaxLength));
+        return {
+            pipelineId,
+            query,
+            hits,
+            citations: hits.map((hit) => hit.citation),
+        };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        const wrapped = new Error(`Cloud knowledge base search failed for pipeline "${pipelineId}": ${reason}`);
+        wrapped.cause = error;
+        throw wrapped;
+    }
+}

package/dist/shared.d.ts

@@ -0,0 +1,23 @@
+import { KognitiveDocumentsClient, type PipelineSearchResult } from "@kognitivedev/documents";
+import type { CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions, CloudKnowledgeBaseResolverInput, CloudKnowledgeBaseSearchResponse, ResolvedCloudKnowledgeBaseSearchConfig } from "./types";
+export declare function createSnippet(content: string, maxLength?: number): string;
+export declare function createModelSummary(response: CloudKnowledgeBaseSearchResponse, options?: {
+    maxHits?: number;
+    maxCharacters?: number;
+}): string;
+export declare function buildSystemBlock(response: CloudKnowledgeBaseSearchResponse, options?: {
+    maxHits?: number;
+    maxCharacters?: number;
+    emptyStateMessage?: string;
+}): string;
+export declare function createDocumentsClient(options: CloudKnowledgeBaseClientOptions): KognitiveDocumentsClient;
+export declare function resolveClientOptions(options: CloudKnowledgeBaseClientOptions, inherited?: Pick<CloudKnowledgeBaseResolverInput, "apiKey" | "baseUrl">): CloudKnowledgeBaseClientOptions;
+export declare function resolveSearchConfig(options: CloudKnowledgeBaseClientOptions & CloudKnowledgeBasePipelineOptions, input: CloudKnowledgeBaseResolverInput): Promise<ResolvedCloudKnowledgeBaseSearchConfig>;
+export declare function normalizeSearchResult(result: PipelineSearchResult, snippetMaxLength?: number): {
+    metadata?: Record<string, unknown> | undefined;
+    sourceId: string;
+    content: string;
+    score: number;
+    citation: import("packages/workflows/dist").KnowledgeBaseCitation;
+};
+export declare function extractLastUserText(messages: unknown[] | undefined): string;

package/dist/shared.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSnippet = createSnippet;
+exports.createModelSummary = createModelSummary;
+exports.buildSystemBlock = buildSystemBlock;
+exports.createDocumentsClient = createDocumentsClient;
+exports.resolveClientOptions = resolveClientOptions;
+exports.resolveSearchConfig = resolveSearchConfig;
+exports.normalizeSearchResult = normalizeSearchResult;
+exports.extractLastUserText = extractLastUserText;
+const documents_1 = require("@kognitivedev/documents");
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function normalizeText(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function normalizeNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function createSnippet(content, maxLength = 240) {
+    const normalized = content.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+function createModelSummary(response, options = {}) {
+    var _a, _b, _c, _d;
+    const maxHits = (_a = options.maxHits) !== null && _a !== void 0 ? _a : 4;
+    const maxCharacters = (_b = options.maxCharacters) !== null && _b !== void 0 ? _b : 320;
+    const lines = [
+        `Knowledge base search results for "${response.query}" in pipeline ${response.pipelineId}:`,
+    ];
+    for (const [index, hit] of response.hits.slice(0, maxHits).entries()) {
+        const citation = hit.citation;
+        const source = [
+            (_c = citation.filename) !== null && _c !== void 0 ? _c : hit.sourceId,
+            typeof citation.pageNumber === "number" ? `page ${citation.pageNumber}` : null,
+            citation.sectionTitle ? `section ${citation.sectionTitle}` : null,
+            citation.sheetName ? `sheet ${citation.sheetName}` : null,
+            typeof citation.rowNumber === "number" ? `row ${citation.rowNumber}` : null,
+            citation.cellRange ? `range ${citation.cellRange}` : null,
+            (_d = citation.artifactType) !== null && _d !== void 0 ? _d : null,
+        ].filter(Boolean).join(" | ");
+        lines.push(`[${index + 1}] score=${hit.score.toFixed(3)} source=${source}`, createSnippet(hit.content || citation.snippet, maxCharacters), `citation=${JSON.stringify(citation)}`);
+    }
+    if (response.hits.length > maxHits) {
+        lines.push(`Additional hits omitted: ${response.hits.length - maxHits}`);
+    }
+    return lines.join("\n");
+}
+function buildSystemBlock(response, options = {}) {
+    var _a;
+    if (response.hits.length === 0) {
+        return [
+            "<CloudKnowledgeBaseContext>",
+            (_a = options.emptyStateMessage) !== null && _a !== void 0 ? _a : `No relevant cloud knowledge base hits were found for query "${response.query}".`,
+            "</CloudKnowledgeBaseContext>",
+        ].join("\n");
+    }
+    return [
+        "<CloudKnowledgeBaseContext>",
+        `Pipeline: ${response.pipelineId}`,
+        `Query: ${response.query}`,
+        createModelSummary(response, {
+            maxHits: options.maxHits,
+            maxCharacters: options.maxCharacters,
+        }),
+        "Use these results as authoritative managed knowledge base context and cite matching sources when answering.",
+        "</CloudKnowledgeBaseContext>",
+    ].join("\n");
+}
+function createDocumentsClient(options) {
+    if (options.client) {
+        return options.client;
+    }
+    if (!options.baseUrl) {
+        throw new Error("Cloud knowledge base backend configuration is missing. Provide a documents client or a baseUrl.");
+    }
+    return new documents_1.KognitiveDocumentsClient({
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        fetch: options.fetch,
+        timeout: options.timeout,
+        logLevel: options.logLevel,
+    });
+}
+function resolveClientOptions(options, inherited) {
+    var _a, _b;
+    if (options.client) {
+        return options;
+    }
+    const baseUrl = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : inherited === null || inherited === void 0 ? void 0 : inherited.baseUrl;
+    if (!baseUrl) {
+        throw new Error("Cloud knowledge base backend configuration is missing. Provide a documents client or a baseUrl, or inherit them from the host agent/workflow.");
+    }
+    return Object.assign(Object.assign({}, options), { baseUrl, apiKey: (_b = options.apiKey) !== null && _b !== void 0 ? _b : inherited === null || inherited === void 0 ? void 0 : inherited.apiKey });
+}
+async function resolveSearchConfig(options, input) {
+    const hasPipelineId = typeof options.pipelineId === "string" && options.pipelineId.trim().length > 0;
+    const hasResolver = typeof options.resolvePipelineId === "function";
+    if (hasPipelineId === hasResolver) {
+        throw new Error("Configure exactly one of pipelineId or resolvePipelineId for the cloud knowledge base.");
+    }
+    const pipelineId = hasPipelineId
+        ? options.pipelineId.trim()
+        : await options.resolvePipelineId({
+            resourceId: input.resourceId,
+            messages: input.messages,
+            metadata: input.metadata,
+            abortSignal: input.abortSignal,
+            apiKey: input.apiKey,
+            baseUrl: input.baseUrl,
+        });
+    if (typeof pipelineId !== "string" || pipelineId.trim().length === 0) {
+        throw new Error("Cloud knowledge base pipeline resolution returned an empty pipeline id.");
+    }
+    return {
+        client: createDocumentsClient(resolveClientOptions(options, input)),
+        pipelineId: pipelineId.trim(),
+    };
+}
+function normalizeSearchResult(result, snippetMaxLength = 240) {
+    var _a, _b, _c, _d;
+    const metadata = isRecord(result.metadata) ? result.metadata : undefined;
+    const content = (_a = normalizeText(result.content)) !== null && _a !== void 0 ? _a : "";
+    const citation = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sourceId: result.id, snippet: (_b = normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.snippet)) !== null && _b !== void 0 ? _b : createSnippet(content, snippetMaxLength) }, (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.filename) ? { filename: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.filename) } : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.mimeType) ? { mimeType: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.mimeType) } : {})), (normalizeNumber(metadata === null || metadata === void 0 ? void 0 : metadata.pageNumber) !== undefined ? { pageNumber: normalizeNumber(metadata === null || metadata === void 0 ? void 0 : metadata.pageNumber) } : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.artifactType) || normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.blockType) || normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.kind)
+        ? { artifactType: (_d = (_c = normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.artifactType)) !== null && _c !== void 0 ? _c : normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.blockType)) !== null && _d !== void 0 ? _d : normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.kind) }
+        : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.parseDocumentId) ? { parseDocumentId: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.parseDocumentId) } : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.sectionTitle) ? { sectionTitle: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.sectionTitle) } : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.sheetName) ? { sheetName: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.sheetName) } : {})), (normalizeNumber(metadata === null || metadata === void 0 ? void 0 : metadata.rowNumber) !== undefined ? { rowNumber: normalizeNumber(metadata === null || metadata === void 0 ? void 0 : metadata.rowNumber) } : {})), (normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.cellRange) ? { cellRange: normalizeText(metadata === null || metadata === void 0 ? void 0 : metadata.cellRange) } : {}));
+    return Object.assign({ sourceId: result.id, content, score: typeof result.score === "number" ? result.score : 0, citation }, (metadata ? { metadata } : {}));
+}
+function extractLastUserText(messages) {
+    if (!Array.isArray(messages))
+        return "";
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!isRecord(message) || message.role !== "user")
+            continue;
+        const parts = Array.isArray(message.parts)
+            ? message.parts
+            : Array.isArray(message.content)
+                ? message.content
+                : [message.content];
+        const text = parts
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (isRecord(part) && typeof part.text === "string")
+                return part.text;
+            return "";
+        })
+            .join("\n")
+            .trim();
+        if (text) {
+            return text;
+        }
+    }
+    return "";
+}

package/dist/tool.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { Tool } from "@kognitivedev/tools";
+import type { CloudKnowledgeBaseSearchResponse, CloudKnowledgeBaseSearchToolOptions } from "./types";
+declare const SearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+    retrievalMode: z.ZodOptional<z.ZodEnum<["chunks", "files_via_metadata", "files_via_content", "auto_routed"]>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    topK?: number | undefined;
+    retrievalMode?: "chunks" | "files_via_metadata" | "files_via_content" | "auto_routed" | undefined;
+}, {
+    query: string;
+    topK?: number | undefined;
+    retrievalMode?: "chunks" | "files_via_metadata" | "files_via_content" | "auto_routed" | undefined;
+}>;
+export declare function createCloudKnowledgeBaseSearchTool(options: CloudKnowledgeBaseSearchToolOptions): Tool<z.infer<typeof SearchInputSchema>, CloudKnowledgeBaseSearchResponse>;
+export {};

package/dist/tool.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCloudKnowledgeBaseSearchTool = createCloudKnowledgeBaseSearchTool;
+const zod_1 = require("zod");
+const tools_1 = require("@kognitivedev/tools");
+const search_1 = require("./search");
+const shared_1 = require("./shared");
+const SearchInputSchema = zod_1.z.object({
+    query: zod_1.z.string().min(1).describe("Natural-language query to run against the managed cloud knowledge base."),
+    topK: zod_1.z.number().int().min(1).max(50).optional().describe("Maximum number of results to return."),
+    retrievalMode: zod_1.z.enum(["chunks", "files_via_metadata", "files_via_content", "auto_routed"]).optional()
+        .describe("Pipeline retrieval mode override."),
+});
+const CitationSchema = zod_1.z.object({
+    sourceId: zod_1.z.string(),
+    snippet: zod_1.z.string(),
+    filename: zod_1.z.string().optional(),
+    mimeType: zod_1.z.string().optional(),
+    pageNumber: zod_1.z.number().optional(),
+    artifactType: zod_1.z.string().optional(),
+    parseDocumentId: zod_1.z.string().optional(),
+    sectionTitle: zod_1.z.string().optional(),
+    sheetName: zod_1.z.string().optional(),
+    rowNumber: zod_1.z.number().optional(),
+    cellRange: zod_1.z.string().optional(),
+});
+const HitSchema = zod_1.z.object({
+    sourceId: zod_1.z.string(),
+    content: zod_1.z.string(),
+    score: zod_1.z.number(),
+    citation: CitationSchema,
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+});
+const SearchOutputSchema = zod_1.z.object({
+    pipelineId: zod_1.z.string(),
+    query: zod_1.z.string(),
+    hits: zod_1.z.array(HitSchema),
+    citations: zod_1.z.array(CitationSchema),
+});
+function createCloudKnowledgeBaseSearchTool(options) {
+    var _a, _b;
+    return (0, tools_1.createTool)({
+        id: (_a = options.id) !== null && _a !== void 0 ? _a : "search-cloud-knowledge-base",
+        description: (_b = options.description) !== null && _b !== void 0 ? _b : "Search a managed cloud knowledge base pipeline and return normalized hits with enterprise-grade citations.",
+        inputSchema: SearchInputSchema,
+        outputSchema: SearchOutputSchema,
+        execute: async (input, context) => {
+            var _a, _b;
+            return (0, search_1.searchCloudKnowledgeBase)(Object.assign(Object.assign({}, options), { query: input.query, topK: (_a = input.topK) !== null && _a !== void 0 ? _a : options.topK, retrievalMode: (_b = input.retrievalMode) !== null && _b !== void 0 ? _b : options.retrievalMode, resourceId: context.resourceId, metadata: context.metadata, abortSignal: context.abortSignal }));
+        },
+        toModelOutput: (output) => (0, shared_1.createModelSummary)(output, {
+            maxHits: options.modelSummaryMaxHits,
+            maxCharacters: options.modelSummaryMaxCharacters,
+        }),
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+import type { AgentContextAdapter } from "@kognitivedev/agents";
+import type { DocumentsClientConfig, KognitiveDocumentsClient, LogLevel, PipelineRetrievalMode } from "@kognitivedev/documents";
+import type { KognitiveMessage, Metadata, ResourceId } from "@kognitivedev/shared";
+import type { KnowledgeBaseAnswer, KnowledgeBaseCitation, KnowledgeBaseHit, KnowledgeBaseSearchResponse } from "@kognitivedev/workflows";
+export type CloudKnowledgeBaseCitation = KnowledgeBaseCitation;
+export type CloudKnowledgeBaseHit = KnowledgeBaseHit;
+export type CloudKnowledgeBaseSearchResponse = KnowledgeBaseSearchResponse;
+export type CloudKnowledgeBaseAnswer = KnowledgeBaseAnswer;
+export interface CloudKnowledgeBaseResolverInput {
+    resourceId: ResourceId;
+    messages?: KognitiveMessage[];
+    metadata?: Metadata;
+    abortSignal?: AbortSignal;
+    apiKey?: string;
+    baseUrl?: string;
+}
+export interface CloudKnowledgeBaseClientOptions {
+    client?: KognitiveDocumentsClient;
+    baseUrl?: string;
+    apiKey?: string;
+    fetch?: DocumentsClientConfig["fetch"];
+    timeout?: number;
+    logLevel?: LogLevel;
+}
+export interface CloudKnowledgeBasePipelineOptions {
+    pipelineId?: string;
+    resolvePipelineId?: (input: CloudKnowledgeBaseResolverInput) => Promise<string> | string;
+}
+export interface CloudKnowledgeBaseSearchOptions extends CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions {
+    query: string;
+    topK?: number;
+    retrievalMode?: PipelineRetrievalMode;
+    resourceId: ResourceId;
+    messages?: KognitiveMessage[];
+    metadata?: Metadata;
+    abortSignal?: AbortSignal;
+    snippetMaxLength?: number;
+}
+export interface CloudKnowledgeBaseSearchToolOptions extends CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions {
+    id?: string;
+    description?: string;
+    topK?: number;
+    retrievalMode?: PipelineRetrievalMode;
+    snippetMaxLength?: number;
+    modelSummaryMaxHits?: number;
+    modelSummaryMaxCharacters?: number;
+}
+export interface CloudKnowledgeBaseContextAdapterOptions extends CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions {
+    topK?: number;
+    retrievalMode?: PipelineRetrievalMode;
+    snippetMaxLength?: number;
+    maxContextHits?: number;
+    maxContextCharacters?: number;
+    autoRegisterSearchTool?: boolean;
+    searchTool?: CloudKnowledgeBaseSearchToolOptions;
+    buildQuery?: (input: CloudKnowledgeBaseResolverInput) => Promise<string> | string;
+    emptyStateMessage?: string;
+}
+export interface CloudKnowledgeBaseSearchStepOptions<TInput, TOutput = CloudKnowledgeBaseSearchResponse> extends CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions {
+    id: string;
+    description?: string;
+    getQuery: (input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<string> | string;
+    topK?: number | ((input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<number | undefined> | number | undefined);
+    retrievalMode?: PipelineRetrievalMode | ((input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<PipelineRetrievalMode | undefined> | PipelineRetrievalMode | undefined);
+    snippetMaxLength?: number;
+    extractOutput?: (result: CloudKnowledgeBaseSearchResponse) => TOutput;
+}
+export interface CloudKnowledgeBaseAnswerStepOptions<TInput, TOutput = CloudKnowledgeBaseAnswer> extends CloudKnowledgeBaseClientOptions, CloudKnowledgeBasePipelineOptions {
+    id: string;
+    description?: string;
+    agent: {
+        generateObject(options: {
+            messages: any[];
+            resourceId: ResourceId;
+            abortSignal?: AbortSignal;
+            structuredOutput: any;
+            temperature?: number;
+            maxOutputTokens?: number;
+        }): Promise<any>;
+    };
+    getQuery: (input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<string> | string;
+    topK?: number | ((input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<number | undefined> | number | undefined);
+    retrievalMode?: PipelineRetrievalMode | ((input: TInput, context: {
+        resourceId: ResourceId;
+        abortSignal: AbortSignal;
+    }) => Promise<PipelineRetrievalMode | undefined> | PipelineRetrievalMode | undefined);
+    snippetMaxLength?: number;
+    buildMessages?: (input: TInput, search: CloudKnowledgeBaseSearchResponse) => any[];
+    temperature?: number;
+    maxOutputTokens?: number;
+    emptyResultAnswer?: string;
+    extractOutput?: (result: {
+        answer: CloudKnowledgeBaseAnswer;
+        search: CloudKnowledgeBaseSearchResponse;
+        agentResult?: any;
+    }) => TOutput;
+}
+export interface ResolvedCloudKnowledgeBaseSearchConfig {
+    client: KognitiveDocumentsClient;
+    pipelineId: string;
+}
+export interface CloudKnowledgeBaseContextAdapter extends AgentContextAdapter {
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/workflow.d.ts

@@ -0,0 +1,4 @@
+import { type StepDefinition } from "@kognitivedev/workflows";
+import type { CloudKnowledgeBaseAnswer, CloudKnowledgeBaseAnswerStepOptions, CloudKnowledgeBaseSearchResponse, CloudKnowledgeBaseSearchStepOptions } from "./types";
+export declare function createCloudKnowledgeBaseSearchStep<TInput, TOutput = CloudKnowledgeBaseSearchResponse>(options: CloudKnowledgeBaseSearchStepOptions<TInput, TOutput>): StepDefinition<TInput, TOutput>;
+export declare function createCloudKnowledgeBaseAnswerStep<TInput, TOutput = CloudKnowledgeBaseAnswer>(options: CloudKnowledgeBaseAnswerStepOptions<TInput, TOutput>): StepDefinition<TInput, TOutput>;