@b2y/ai-service 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,167 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { promises as fs } from "node:fs";
3
+ import { join, resolve, sep } from "node:path";
4
+ import { z } from "zod";
5
+ import { AiServiceError } from "../core/Errors.js";
6
+ import { ErrorCodes } from "../core/Errors.js";
7
+ import { summarizeZodError } from "../core/Errors.js";
8
+ import { buildSearchIndex } from "./Documents.js";
9
+ /** Used when an application passes no documentTypes of its own. */
10
+ const DEFAULT_DOCUMENT_TYPES = Object.freeze(["document", "guide", "reference", "other"]);
11
+
12
+ const DOCUMENT_TYPE = /^[a-z][a-z0-9_-]{0,19}$/;
13
+ const APPLICATION_ID = /^[a-z][a-z0-9-]{0,63}$/;
14
+ const DOCUMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
15
+ const MAX_DOCUMENTS = 200;
16
+
17
+ function documentSchemaFor(documentTypes) {
18
+ return z.strictObject({
19
+ title: z.string().trim().min(1).max(120),
20
+ type: z.enum(documentTypes),
21
+ text: z.string().trim().min(1).max(2_000_000),
22
+ fileName: z.string().trim().min(1).max(200).optional(),
23
+ });
24
+ }
25
+
26
+ /**
27
+ * @typedef {Object} DocumentStore
28
+ * @property {(applicationId: string, document: { title: string, type: string, text: string, fileName?: string }) => Promise<{ id: string, passages: number }>} addDocument
29
+ * @property {(applicationId: string, documentId: string) => Promise<boolean>} removeDocument
30
+ * @property {(applicationId: string) => Promise<{ id: string, title: string, type: string, fileName?: string, addedAt?: string, passages: number }[]>} listDocuments
31
+ * @property {(applicationId: string) => Promise<import("./Documents.js").SearchIndex | null>} loadIndex
32
+ * @property {readonly string[]} documentTypes - The kinds of document addDocument accepts.
33
+ */
34
+
35
+ /**
36
+ * Documents and their search index in one private folder per application:
37
+ * <root>/<applicationId>/documents/<id>.json title, type, file name and extracted text
38
+ * <root>/<applicationId>/index.json search index, rebuilt on every change
39
+ * Folders are created 0700 and files 0600; index writes are atomic. An application id is a plain
40
+ * lower-case name, so it can never point outside its own folder. The store does not decide which
41
+ * application a request belongs to: the document agent passes the trusted context's applicationId.
42
+ * A simple local store: one folder per application, no tenants. Multi-tenant consumers supply their own
43
+ * DocumentSource instead (see defineDocumentSource).
44
+ * @param {{ root: string, documentTypes?: readonly string[] }} options - documentTypes: the kinds addDocument
45
+ * accepts (default DEFAULT_DOCUMENT_TYPES).
46
+ * @returns {DocumentStore}
47
+ */
48
+ export function createFolderDocumentStore({ root, documentTypes = DEFAULT_DOCUMENT_TYPES }) {
49
+ if (typeof root !== "string" || root.trim() === "")
50
+ throw new AiServiceError(ErrorCodes.CONFIG_INVALID, "A documents root folder is required");
51
+ if (
52
+ !Array.isArray(documentTypes) ||
53
+ documentTypes.length === 0 ||
54
+ documentTypes.length > 50 ||
55
+ !documentTypes.every((type) => typeof type === "string" && DOCUMENT_TYPE.test(type)) ||
56
+ new Set(documentTypes).size !== documentTypes.length
57
+ ) {
58
+ throw new AiServiceError(ErrorCodes.CONFIG_INVALID, "documentTypes must be 1-50 unique lower-case names of up to 20 characters");
59
+ }
60
+ const types = Object.freeze([...documentTypes]);
61
+ const documentSchema = documentSchemaFor(types);
62
+ const base = resolve(root);
63
+ const cache = new Map();
64
+
65
+ function appFolder(applicationId) {
66
+ if (typeof applicationId !== "string" || !APPLICATION_ID.test(applicationId)) {
67
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "Invalid application id");
68
+ }
69
+ const folder = join(base, applicationId);
70
+ if (!folder.startsWith(base + sep)) throw new AiServiceError(ErrorCodes.INPUT_INVALID, "Invalid application id");
71
+ return folder;
72
+ }
73
+
74
+ async function writePrivate(file, contents) {
75
+ const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
76
+ await fs.writeFile(temporary, contents, { mode: 0o600, flag: "wx" });
77
+ await fs.rename(temporary, file);
78
+ }
79
+
80
+ async function readDocuments(folder) {
81
+ const directory = join(folder, "documents");
82
+ let names;
83
+ try {
84
+ names = (await fs.readdir(directory)).filter(
85
+ (name) => DOCUMENT_ID.test(name.replace(/\.json$/, "")) && name.endsWith(".json"),
86
+ );
87
+ } catch (error) {
88
+ if (error?.code === "ENOENT") return [];
89
+ throw error;
90
+ }
91
+ const documents = [];
92
+ for (const name of names.sort()) documents.push(JSON.parse(await fs.readFile(join(directory, name), "utf8")));
93
+ return documents.sort((a, b) => String(a.addedAt).localeCompare(String(b.addedAt)));
94
+ }
95
+
96
+ async function rebuild(folder) {
97
+ const index = buildSearchIndex(await readDocuments(folder));
98
+ await writePrivate(join(folder, "index.json"), JSON.stringify(index));
99
+ cache.delete(folder);
100
+ return index;
101
+ }
102
+
103
+ async function listDocuments(applicationId) {
104
+ const index = await loadIndex(applicationId);
105
+ return index ? index.documents.map((document) => ({ ...document })) : [];
106
+ }
107
+
108
+ async function loadIndex(applicationId) {
109
+ const folder = appFolder(applicationId);
110
+ const file = join(folder, "index.json");
111
+ let stat;
112
+ try {
113
+ stat = await fs.stat(file);
114
+ } catch (error) {
115
+ if (error?.code === "ENOENT") return null;
116
+ throw error;
117
+ }
118
+ const cached = cache.get(folder);
119
+ if (cached && cached.mtimeMs === stat.mtimeMs) return cached.index;
120
+ const index = JSON.parse(await fs.readFile(file, "utf8"));
121
+ cache.set(folder, { mtimeMs: stat.mtimeMs, index });
122
+ return index;
123
+ }
124
+
125
+ return Object.freeze({
126
+ async addDocument(applicationId, document) {
127
+ const folder = appFolder(applicationId);
128
+ const parsed = documentSchema.safeParse(document);
129
+ if (!parsed.success) {
130
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "Document is invalid", {
131
+ details: summarizeZodError(parsed.error, documentSchema),
132
+ });
133
+ }
134
+ await fs.mkdir(join(folder, "documents"), { recursive: true, mode: 0o700 });
135
+ if ((await readDocuments(folder)).length >= MAX_DOCUMENTS) {
136
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "Too many documents for this application", {
137
+ details: { limit: MAX_DOCUMENTS },
138
+ });
139
+ }
140
+ const id = randomUUID();
141
+ const record = { id, ...parsed.data, addedAt: new Date().toISOString() };
142
+ await writePrivate(join(folder, "documents", `${id}.json`), JSON.stringify(record));
143
+ const index = await rebuild(folder);
144
+ return { id, passages: index.documents.find((entry) => entry.id === id)?.passages ?? 0 };
145
+ },
146
+
147
+ async removeDocument(applicationId, documentId) {
148
+ const folder = appFolder(applicationId);
149
+ if (typeof documentId !== "string" || !DOCUMENT_ID.test(documentId))
150
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "Invalid document id");
151
+ try {
152
+ await fs.unlink(join(folder, "documents", `${documentId}.json`));
153
+ } catch (error) {
154
+ if (error?.code === "ENOENT") return false;
155
+ throw error;
156
+ }
157
+ await rebuild(folder);
158
+ return true;
159
+ },
160
+
161
+ listDocuments,
162
+
163
+ loadIndex,
164
+
165
+ documentTypes: types,
166
+ });
167
+ }
@@ -0,0 +1,50 @@
1
+ // PDF text extraction. Separate entry point ("@b2y/ai-service/documents/pdf") so the optional unpdf peer
2
+ // dependency is only loaded by applications that add PDF documents. Needs Node.js 22 or later.
3
+ import { extractText, getDocumentProxy } from "unpdf";
4
+ import { AiServiceError } from "../core/Errors.js";
5
+ import { ErrorCodes } from "../core/Errors.js";
6
+ import { MAX_PDF_BYTES, MAX_PDF_PAGES, MAX_PDF_TEXT_CHARS } from "../constants/DocumentConstants.js";
7
+ export { MAX_PDF_BYTES, MAX_PDF_PAGES, MAX_PDF_TEXT_CHARS } from "../constants/DocumentConstants.js";
8
+
9
+ /**
10
+ * Extracts the text of a PDF, page by page (pages separated by a blank line). Scanned PDFs without a text
11
+ * layer produce no text and are refused: they would need OCR.
12
+ * @param {Uint8Array | ArrayBuffer} data
13
+ * @returns {Promise<{ text: string, pages: number }>}
14
+ */
15
+ export async function extractPdfText(data, { maxBytes = MAX_PDF_BYTES, maxPages = MAX_PDF_PAGES } = {}) {
16
+ // A copy: the parser may transfer (detach) the buffer it is given.
17
+ const bytes = new Uint8Array(data);
18
+ if (bytes.byteLength === 0 || bytes.byteLength > maxBytes) {
19
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "PDF is empty or too large", { details: { limitBytes: maxBytes } });
20
+ }
21
+ // "%PDF-" header: refuse other files early instead of handing them to the parser.
22
+ if (String.fromCharCode(...bytes.subarray(0, 5)) !== "%PDF-") {
23
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "File is not a PDF");
24
+ }
25
+
26
+ let pdf;
27
+ try {
28
+ pdf = await getDocumentProxy(bytes);
29
+ } catch (error) {
30
+ // The parser's message can quote file content, so only a generic reason is kept.
31
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "PDF could not be read", { cause: error });
32
+ }
33
+ try {
34
+ if (pdf.numPages > maxPages) {
35
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "PDF has too many pages", { details: { limitPages: maxPages } });
36
+ }
37
+ const { text } = await extractText(pdf, { mergePages: false });
38
+ const pages = (Array.isArray(text) ? text : [text]).map((page) => String(page).trim()).filter((page) => page !== "");
39
+ const joined = pages.join("\n\n").slice(0, MAX_PDF_TEXT_CHARS);
40
+ if (joined.trim() === "") {
41
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "PDF has no text layer (scanned images need OCR)");
42
+ }
43
+ return { text: joined, pages: pdf.numPages };
44
+ } catch (error) {
45
+ if (error instanceof AiServiceError) throw error;
46
+ throw new AiServiceError(ErrorCodes.INPUT_INVALID, "PDF text could not be extracted", { cause: error });
47
+ } finally {
48
+ await pdf.destroy?.();
49
+ }
50
+ }
@@ -0,0 +1 @@
1
+ export const CHART_TYPES = ["bar", "horizontal_bar", "stacked_bar", "line", "area", "pie", "doughnut"];
@@ -0,0 +1,2 @@
1
+ /** Ordered from least to most sensitive. */
2
+ export const DATA_CLASSIFICATION = Object.freeze({ SYNTHETIC: "SYNTHETIC", INTERNAL: "INTERNAL", CONFIDENTIAL: "CONFIDENTIAL", RESTRICTED: "RESTRICTED" });
package/src/index.js ADDED
@@ -0,0 +1,53 @@
1
+ // Public API of @b2y/ai-service.
2
+
3
+ export { AI_PROVIDER_CONFIG, createAiService, createDefaultAiService } from "./core/AiService.js";
4
+ export { noopLogger } from "./core/AiService.js";
5
+ export { defineTask } from "./core/Tasks.js";
6
+ export { createTaskRegistry } from "./core/Tasks.js";
7
+
8
+ export { parseTrustedContext } from "./core/Context.js";
9
+ export { AI_ASSISTANT_PERMISSION, accessDenied, assertAuthorized, buildTrustedContext, hasFeature, hasPermission, permissionKey, resolveTenantId, rolePermissions } from "./core/Context.js";
10
+ export { ASSISTANT_NAME } from "./constants/AssistantConstants.js";
11
+ export { DATA_CLASSIFICATION } from "./enums/DataClassification.js";
12
+ export { RESPONSE_STATUS } from "./constants/ServerConstants.js";
13
+
14
+ export { AiServiceError, errorCategory } from "./core/Errors.js";
15
+ export { ErrorCategories, ErrorCodes } from "./core/Errors.js";
16
+ export { aiUserMessage, isRateLimited, rateLimitInfo } from "./core/Errors.js";
17
+
18
+ // Providers are internal: AI_PROVIDER_CONFIG (constants/ProviderConstants.js) is the one place that picks provider and model.
19
+
20
+ export {
21
+ defineSqlPolicy,
22
+ isSqlPolicy,
23
+ SQL_SAFE_FUNCTIONS,
24
+ SQL_SAFE_WINDOW_FUNCTIONS,
25
+ } from "./sql/SqlPolicy.js";
26
+ export { isValidatedQuery, SqlValidationCodes } from "./sql/SqlPolicy.js";
27
+ export { checkQueryResult } from "./sql/SqlPolicy.js";
28
+ export { buildSchemaContext, describePolicyRules } from "./sql/SqlPolicy.js";
29
+
30
+ export { defineAnalyticsCatalog, isAnalyticsCatalog } from "./analytics/Analytics.js";
31
+ export { ANALYTICS_PLAN_TASK } from "./analytics/Analytics.js";
32
+ export { createAnalyticsAssistant } from "./analytics/Analytics.js";
33
+ export { mergeSections, observeSection } from "./analytics/Results.js";
34
+ export { buildResultChart, CHART_TYPES, chartSpecSchema } from "./analytics/Results.js";
35
+
36
+ export { defineApplicationProfile, isApplicationProfile } from "./assistant/Assistant.js";
37
+
38
+ export { createIndexDocumentSource, defineDocumentSource, isDocumentSource } from "./documents/Documents.js";
39
+ export { buildSearchIndex, searchIndex, splitIntoPassages } from "./documents/Documents.js";
40
+ export { createDocumentQaAgent, DOCUMENT_ANSWER_TASK } from "./documents/Documents.js";
41
+
42
+ export { createAiAssistant } from "./assistant/Assistant.js";
43
+ export { CAPABILITY_KINDS, createAnalyticsCapability, createDocumentsCapability, defineCapability, isCapability } from "./assistant/Capabilities.js";
44
+ export { createSearchCapability, SEARCH_FILTERS_TASK } from "./assistant/Capabilities.js";
45
+ export { ASSISTANT_RESPOND_TASK, ASSISTANT_ROUTE_TASK } from "./assistant/Assistant.js";
46
+ export { analyticsReportToBlocks, responseBlocksSchema } from "./assistant/Capabilities.js";
47
+
48
+ export {
49
+ createConversationHistory,
50
+ defineConversationStore,
51
+ isConversationStore,
52
+ scheduleConversationCleanup,
53
+ } from "./conversations/ConversationHistory.js";