@xpert-ai/plugin-analytics-files 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # File Analytics
 
+The Live Dashboard Agent generates this provider’s Definition through `analytics_definition_connections` → `analytics_definition_inspect` → `analytics_definition_register`. Existing toolset/Integration credentials stay in their original configuration entries. Settings → Analytics is for viewing, correction and version management; users do not fill internal IDs. See [the authoring guide](../../../../docs/analytics-providers.md#automatic-definition-generation).
 `@xpert-ai/plugin-analytics-files` provides `file.table`: declarative CSV, JSON and XLSX queries over platform-authorized Workspace files. Standard charts and HTML dashboards consume the same Dataset/Binding results.
 
-Administrators configure a `workspace-files` data source with approved file references, explicit format/read options, column types and business descriptions. Agent discovery returns the exact query contract and a bounded real preview; no new Agent middleware is required. File parsing, aggregation and format dependencies remain in this plugin. The platform owns file permissions, data-source authorization and Artifact lifecycle.
 
 - [Overview](docs/index.mdx) / [中文概览](docs/zh-Hans/index.mdx)
 - [Configuration and query contract](docs/configuration.mdx) / [中文配置](docs/zh-Hans/configuration.mdx)

package/dist/index.js

@@ -5,7 +5,7 @@ const node_path_1 = require("node:path");
 const plugin_1 = require("./lib/plugin");
 const metadata = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '../package.json'), 'utf8'));
 const plugin = {
-    meta: { name: metadata.name, version: metadata.version, category: 'database', displayName: 'File Analytics',
+    meta: { name: metadata.name, version: metadata.version, category: 'tools', displayName: 'File Analytics',
         description: 'Declarative CSV, JSON and XLSX queries over authorized Workspace files', author: 'XpertAI',
         level: metadata.xpert.plugin.level, artifactNamespace: metadata.xpert.plugin.artifactNamespace },
     register: () => ({ module: plugin_1.AnalyticsFilesPlugin })

package/dist/lib/authoring.d.ts

@@ -0,0 +1,2 @@
+import { type AnalyticsDefinitionAuthoring } from '@xpert-ai/plugin-sdk';
+export declare const fileAuthoring: AnalyticsDefinitionAuthoring;

package/dist/lib/authoring.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileAuthoring = void 0;
+const node_crypto_1 = require("node:crypto");
+const v3_1 = require("zod/v3");
+const schema_1 = require("./schema");
+const worker_client_1 = require("./worker-client");
+const inspectSchema = v3_1.z.object({ path: v3_1.z.string().min(1).max(1024).optional() }).strict();
+const definitionSchema = schema_1.datasetSchema.innerType().omit({ id: true, revision: true, file: true }).extend({ path: v3_1.z.string().min(1).max(1024) }).strict();
+async function resolve(path, context) {
+    if (context.connection.kind !== 'workspace-files')
+        throw new Error('ANALYTICS_CONNECTION_INVALID');
+    const reference = await context.files.resolveRuntimeReference(path);
+    const base = { catalog: reference.catalog, filePath: reference.filePath };
+    const file = schema_1.fileSchema.parse(reference.catalog === 'projects' ? { ...base, projectId: reference.projectId }
+        : reference.catalog === 'users' ? { ...base, userId: reference.userId }
+            : reference.catalog === 'user-xperts' ? { ...base, xpertId: reference.xpertId, userId: reference.userId }
+                : { ...base, xpertId: reference.xpertId });
+    const metadata = await context.files.resolveFile(reference);
+    if (!metadata.size || metadata.size > schema_1.MAX_BYTES)
+        throw new Error('FILE_DATASET_SIZE_LIMIT');
+    context.signal.throwIfAborted();
+    return { reference, file, size: metadata.size };
+}
+exports.fileAuthoring = {
+    inspectSchema: (0, schema_1.jsonSchema)(inspectSchema), definitionSchema: (0, schema_1.jsonSchema)(definitionSchema),
+    instructions: 'Use SandboxFile tools to list/read the current authorized workspace files. Select the exact runtime path, inspect CSV headers/JSON rows/XLSX sheet and documented business semantics, then generate reader and columns. Do not ask the user for internal file scope or IDs. Register validates the real file and mapping. Do not infer business meanings without evidence.',
+    async inspect(original, context) {
+        const input = inspectSchema.parse(original);
+        if (!input.path)
+            return { next: 'List/read authorized files with SandboxFile tools, then inspect with {path}.' };
+        const resolved = await resolve(input.path, context);
+        return { path: input.path, size: resolved.size, formats: ['csv', 'json', 'xlsx'] };
+    },
+    async prepare(original, context) {
+        const { path, ...input } = definitionSchema.parse(original);
+        const resolved = await resolve(path, context);
+        const options = schema_1.optionsSchema.parse({ datasets: [{ ...input, id: 'dataset', revision: 'initial', file: resolved.file }] });
+        const dataset = options.datasets[0], { buffer } = await context.files.readBuffer(resolved.reference);
+        if (!buffer.length || buffer.length > schema_1.MAX_BYTES)
+            throw new Error('FILE_DATASET_SIZE_LIMIT');
+        const payload = schema_1.payloadSchema.parse({ datasetId: dataset.id, revision: dataset.revision, contractHash: (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(dataset)).digest('hex'), select: dataset.columns.map(column => column.key) });
+        await (0, worker_client_1.queryWorker)(buffer, dataset, payload, {}, 5, context.signal, context.deadlineAt);
+        await resolve(path, context);
+        return options;
+    }
+};

package/dist/lib/provider.d.ts

@@ -5,6 +5,62 @@ export declare const contractHash: (dataset: FileDataset) => string;
 export declare class FileAnalyticsProvider implements AnalyticsQueryProvider {
     private readonly runtime;
     readonly descriptor: AnalyticsProviderDescriptor;
+    readonly authoring: import("@xpert-ai/plugin-sdk").AnalyticsDefinitionAuthoring;
+    readonly configuration: {
+        kind: "definition";
+        connection: "workspace-files";
+        schema: Record<string, JSONValue>;
+    };
+    validateConfiguration(options: Record<string, JSONValue>): {
+        datasets: {
+            description: string;
+            id: string;
+            revision: string;
+            name: string;
+            file: {
+                catalog: "xperts";
+                xpertId: string;
+                filePath: string;
+            } | {
+                catalog: "user-xperts";
+                xpertId: string;
+                filePath: string;
+                userId: string;
+            } | {
+                catalog: "users";
+                filePath: string;
+                userId: string;
+            } | {
+                catalog: "projects";
+                filePath: string;
+                projectId: string;
+            };
+            reader: {
+                format: "csv";
+                delimiter: "," | ";" | "\t";
+                headerRow: number;
+            } | {
+                format: "json";
+                rowsPath: string[];
+            } | {
+                format: "xlsx";
+                headerRow: number;
+                sheet: string;
+                formulaPolicy: "reject" | "cached";
+            };
+            columns: {
+                path: string[];
+                key: string;
+                label: string;
+                description: string;
+                logicalType: "string" | "boolean" | "date" | "int64" | "decimal" | "float64" | "timestamp";
+                nullable: boolean;
+                role: "dimension" | "measure" | "time" | "identifier";
+                nullValues: string[];
+                unit?: string | undefined;
+            }[];
+        }[];
+    };
     constructor(runtime: RuntimeCapabilityRegistry);
     private check;
     private file;

package/dist/lib/provider.js

@@ -13,6 +13,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileAnalyticsProvider = exports.contractHash = void 0;
+const authoring_1 = require("./authoring");
 const common_1 = require("@nestjs/common");
 const node_crypto_1 = require("node:crypto");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
@@ -26,13 +27,15 @@ const instructions = `Use an inspected dataset's bindingPayload and columns. Nev
 const queryContract = { operation: 'query', contractVersion: 1,
     payloadSchema: (0, schema_1.jsonSchema)(schema_1.payloadSchema), instructions: instructions + ' metadata.binding is a complete canonical Binding; bindingPayload alone is only its payload, not a Binding. Start from metadata.binding and preserve its envelope. Raw rows do not promise uniqueness; keep grain:[] unless verified, or group first and declare the grouping field IDs as grain.' };
 let FileAnalyticsProvider = class FileAnalyticsProvider {
+    validateConfiguration(options) { return schema_1.optionsSchema.parse(options); }
     constructor(runtime) {
         this.runtime = runtime;
         this.descriptor = {
-            id: schema_1.PROVIDER, name: 'Workspace files (CSV / JSON / XLSX)', dataSourceTypes: ['workspace-files'],
-            operations: [{ name: 'query', contractVersion: 1, readOnly: true }],
-            connectionType: { type: 'workspace-files', name: 'Workspace files', configuration: (0, schema_1.jsonSchema)(schema_1.optionsSchema) }
+            id: schema_1.PROVIDER, name: 'Workspace files (CSV / JSON / XLSX)', sourceKinds: ['definition'],
+            operations: [{ name: 'query', contractVersion: 1, readOnly: true }]
         };
+        this.authoring = authoring_1.fileAuthoring;
+        this.configuration = { kind: 'definition', connection: 'workspace-files', schema: (0, schema_1.jsonSchema)(schema_1.optionsSchema) };
     }
     check(context) {
         context.signal.throwIfAborted();
@@ -101,7 +104,7 @@ let FileAnalyticsProvider = class FileAnalyticsProvider {
                     const read = await this.read(definition, context);
                     const preview = await (0, worker_client_1.queryWorker)(read.buffer, definition, payload, {}, 5, context.signal, context.deadlineAt);
                     await this.file(definition, context);
-                    const binding = { schemaVersion: 1, id: definition.id, dataSourceId: context.dataSourceId,
+                    const binding = { source: context.source, id: definition.id,
                         providerId: schema_1.PROVIDER, operation: 'query', contractVersion: 1, payload: JSON.parse(JSON.stringify(payload)), parameters: [],
                         output: { datasetId: definition.id, grain: [], fields: definition.columns.map(({ key, path, description, nullValues, ...field }) => ({ ...field, id: key, sourceField: key })) } };
                     const previewFits = Buffer.byteLength(JSON.stringify(preview.rows)) <= 32000;
@@ -115,7 +118,7 @@ let FileAnalyticsProvider = class FileAnalyticsProvider {
                 }
                 items.push({ id: definition.id, name: definition.name, description: definition.description, kind: 'dataset', inspectRequest: { datasetId: definition.id }, metadata });
             }
-            return { schemaVersion: 1, queryContract, items,
+            return { queryContract, items,
                 ...(!input.datasetId && input.page * 20 < datasets.length ? { nextRequest: { page: input.page + 1 } } : {}) };
         });
     }

package/dist/lib/query.d.ts

@@ -2,7 +2,7 @@ import type { AnalyticsBinding, AnalyticsValue } from '@xpert-ai/contracts';
 import type { Column, FileDataset, FileQuery } from './schema';
 export type Row = Record<string, AnalyticsValue>;
 export declare function outputColumns(definition: FileDataset, query: FileQuery): Column[];
-export declare function validateOutput(binding: AnalyticsBinding, columns: Column[]): void;
+export declare function validateOutput(binding: Pick<AnalyticsBinding, 'output'>, columns: Column[]): void;
 export declare function executeQuery(rows: Row[], definition: FileDataset, query: FileQuery, parameters: Row, maxRows: number): {
     columns: {
         key: string;

package/dist/lib/schema.js

@@ -45,7 +45,7 @@ exports.datasetSchema = v3_1.z.object({
     if (Buffer.byteLength(JSON.stringify(dataset)) > 48000)
         ctx.addIssue({ code: 'custom', message: 'Dataset exceeds discovery metadata budget' });
 });
-exports.optionsSchema = v3_1.z.object({ datasets: v3_1.z.array(exports.datasetSchema).min(1).max(100) }).strict()
+exports.optionsSchema = v3_1.z.object({ datasets: v3_1.z.array(exports.datasetSchema).length(1) }).strict()
     .refine(value => new Set(value.datasets.map(d => d.id)).size === value.datasets.length, 'Duplicate dataset ID');
 const operand = v3_1.z.discriminatedUnion('type', [
     v3_1.z.object({ type: v3_1.z.literal('literal'), value: exports.scalar }).strict(),

package/docs/configuration.mdx

@@ -3,7 +3,7 @@ title: 'Configuration and queries'
 description: 'Approved files, explicit column semantics and declarative queries.'
 ---
 
-Create a platform data source of type `workspace-files`. Configure `datasets` using the packaged `examples/sales.json` catalog. Replace the example Assistant ID with a published Assistant you can access. Upload the file through the platform Files UI/API. Paths are Volume-relative, never local host paths.
+Open Settings → Analytics → Workspace files and create a Definition with exactly one dataset. Configure `datasets` using the packaged `examples/sales.json` catalog. Replace the example Assistant ID with a published Assistant you can access. Upload the file through the platform Files UI/API. Paths are Volume-relative, never local host paths.
 
 Each dataset has `id`, `revision`, `name`, `description`, `file`, `reader` and `columns`.
 

package/docs/zh-Hans/configuration.mdx

@@ -3,7 +3,7 @@ title: '配置与查询'
 description: '受控文件目录、字段口径和声明式查询。'
 ---
 
-安装插件后创建类型为 `workspace-files` 的平台数据源，按包内 `examples/sales.json` 配置 `datasets`。示例 Assistant ID 需要替换为有权访问的已发布 Assistant；通过平台 Files 上传源文件。路径为 Volume 内相对路径，不能使用本机绝对路径。
+安装插件后在「设置 → 分析定义 → Workspace files」创建 Definition，每个定义配置一个数据集，按包内 `examples/sales.json` 配置 `datasets`。示例 Assistant ID 需要替换为有权访问的已发布 Assistant；通过平台 Files 上传源文件。路径为 Volume 内相对路径，不能使用本机绝对路径。
 
 每个数据集包含 `id/revision/name/description/file/reader/columns`。`file.catalog` 支持共享 Assistant `xperts`、用户隔离 Assistant `user-xperts`、用户文件 `users` 和项目 `projects`。用户目录必须匹配当前访问者；项目需要有效成员权限，Assistant 文件检查准确的已发布 Assistant 授权。租户和组织由平台提供。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-analytics-files",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Declarative CSV, JSON and XLSX analytics over authorized Workspace files",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -28,15 +28,15 @@
     }
   },
   "peerDependencies": {
-    "@xpert-ai/plugin-sdk": "^3.25.0",
-    "@xpert-ai/contracts": "^3.25.0",
+    "@xpert-ai/plugin-sdk": "^3.26.1",
+    "@xpert-ai/contracts": "^3.26.1",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
     "zod": "3.25.67"
   },
   "devDependencies": {
-    "@xpert-ai/plugin-sdk": "3.25.0",
-    "@xpert-ai/contracts": "3.25.0",
+    "@xpert-ai/plugin-sdk": "3.26.1",
+    "@xpert-ai/contracts": "3.26.1",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
     "zod": "3.25.67",