@things-factory/ai-assistant 10.1.112 → 10.1.114

package/dist-server/service/data-read/read-target.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCategoryName = exports.screenToolName = exports.queryToolName = exports.READ_PAGE = exports.ROWS_FOR_MODEL = exports.MAX_READ_ROWS = void 0;
+exports.declareReadTarget = declareReadTarget;
+exports.readTargetOf = readTargetOf;
+exports.clearReadTargets = clearReadTargets;
+exports.readCriteria = readCriteria;
+exports.filtersOf = filtersOf;
+exports.rowOf = rowOf;
+exports.readRows = readRows;
+exports.sumsOf = sumsOf;
+exports.groupsOf = groupsOf;
+exports.screenAddress = screenAddress;
+/*
+ * AI 조회 - an application's list, read through its own query as the person (operato-application/design/ai/read-targets.md).
+ *
+ * The application declares what it lets the assistant read: its list query, the conditions the model may set and
+ * how each becomes one of the query's filters, the columns to show, and the screen that lists the same records.
+ * The framework reads the rows through that query with the person's request state - the same @privilege and
+ * domain as the screen - counts and sums them itself, and puts a long result on the AI 작업판 as the query returned
+ * it. The model is told the count, the sums and a few rows; it never copies a table.
+ *
+ * Pure but for the GraphQL runner, which comes in as an argument - the rules are tested without a server.
+ */
+const entry_target_js_1 = require("../data-entry/entry-target.js");
+/** At most this many rows are read - the AI 작업판 table's own limit (workspace-blocks MAX_TABLE_ROWS). */
+exports.MAX_READ_ROWS = 1000;
+/** Rows the model is shown; the rest stay on the card. */
+exports.ROWS_FOR_MODEL = 20;
+/** A page of the list query. */
+exports.READ_PAGE = 200;
+const registry = new Map();
+const pascalOf = (key) => key
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join('');
+const queryToolName = (key) => `query${pascalOf(key)}`;
+exports.queryToolName = queryToolName;
+const screenToolName = (key) => `open${pascalOf(key)}Screen`;
+exports.screenToolName = screenToolName;
+const readCategoryName = (key) => `data-read:${key}`;
+exports.readCategoryName = readCategoryName;
+function declareReadTarget(target) {
+    if (!/^[a-z0-9-]+\.[a-z0-9-]+$/.test(target.key))
+        throw new Error(`read target key '${target.key}' is not <app>.<record>`);
+    if (registry.has(target.key))
+        throw new Error(`read target '${target.key}' is declared twice`);
+    (0, entry_target_js_1.rootFieldOf)(target.query, 'query');
+    if (!target.columns.length)
+        throw new Error(`read target '${target.key}' shows no column`);
+    const names = new Set();
+    for (const criterion of target.criteria) {
+        if (criterion.name === 'id')
+            throw new Error(`read target '${target.key}' declares 'id' - every target takes it`);
+        if (criterion.name === 'text' && target.search)
+            throw new Error(`read target '${target.key}' declares 'text' and search - search is the text condition`);
+        if (names.has(criterion.name))
+            throw new Error(`read target '${target.key}' names the condition '${criterion.name}' twice`);
+        names.add(criterion.name);
+        if (criterion.type === 'enum' && !criterion.values?.length)
+            throw new Error(`condition '${criterion.name}' of '${target.key}' lists no values`);
+    }
+    if (target.search)
+        names.add('text');
+    for (const taken of target.screen?.takes ?? [])
+        if (!names.has(taken))
+            throw new Error(`the screen of '${target.key}' takes '${taken}', which is no condition`);
+    registry.set(target.key, target);
+}
+function readTargetOf(key) {
+    return key ? registry.get(key) : undefined;
+}
+function clearReadTargets() {
+    registry.clear();
+}
+/** The conditions the model set, read by their declared types; a value that does not fit is said, never guessed at. */
+function readCriteria(target, args) {
+    const criteria = {};
+    const refused = [];
+    /* One record by its id - every target takes it (the id a list answer or a find tool gave). */
+    if (typeof args?.id === 'string' && args.id.trim())
+        criteria.id = args.id.trim();
+    if (target.search && typeof args?.text === 'string' && args.text.trim())
+        criteria.text = args.text.trim();
+    for (const criterion of target.criteria) {
+        const value = args?.[criterion.name];
+        if (value === undefined || value === null || value === '')
+            continue;
+        const { read, code } = (0, entry_target_js_1.readFieldValue)(criterion, value);
+        if (read === undefined)
+            refused.push({ name: criterion.name, code: code ?? 'unreadable' });
+        else
+            criteria[criterion.name] = read;
+    }
+    return { criteria, refused };
+}
+function filtersOf(target, criteria) {
+    return [
+        ...(typeof criteria.id === 'string' ? [{ name: 'id', operator: 'eq', value: criteria.id }] : []),
+        ...target.criteria.flatMap(criterion => (criterion.name in criteria ? [criterion.filter(criteria[criterion.name])].flat() : []))
+    ];
+}
+const valueAt = (row, path) => path.split('.').reduce((at, part) => (at === null || at === undefined ? undefined : at[part]), row);
+/** One row as the columns say - a number column as a number, a missing value as null. */
+function rowOf(target, item) {
+    return Object.fromEntries([
+        /* The id names the record to the model - for one record's detail, a change, or its screen. */
+        ...(item?.id ? [['id', String(item.id)]] : []),
+        ...target.columns.map(column => {
+            const raw = valueAt(item, column.path ?? column.name);
+            if (raw === undefined || raw === null || raw === '')
+                return [column.name, null];
+            if (column.type === 'number') {
+                const number = Number(raw);
+                return [column.name, Number.isFinite(number) ? number : null];
+            }
+            return [column.name, String(raw)];
+        })
+    ]);
+}
+/**
+ * Reads the rows through the application's query, page by page, up to MAX_READ_ROWS. `complete` is false when the
+ * list holds more - a sum of the rows read is then not the sum of the list, and is never said as one.
+ */
+async function readRows(target, filters, run, search) {
+    const rows = [];
+    let total = 0;
+    for (let page = 1; rows.length < exports.MAX_READ_ROWS; page++) {
+        const answer = await run(target.query, {
+            filters,
+            ...(search ? { search } : {}),
+            pagination: { page, limit: exports.READ_PAGE },
+            ...(target.sortings ? { sortings: target.sortings } : {})
+        });
+        if (answer.errors?.length)
+            throw new Error(answer.errors.map(one => one.message).join('; '));
+        const read = target.rowsOf(answer.data);
+        total = Number(read?.total) || 0;
+        const items = read?.rows ?? [];
+        rows.push(...items.slice(0, exports.MAX_READ_ROWS - rows.length).map(item => rowOf(target, item)));
+        if (items.length < exports.READ_PAGE || rows.length >= total)
+            break;
+    }
+    return { rows, total, complete: rows.length >= total };
+}
+/** The sums of the number columns marked total - the server's, never the model's. */
+function sumsOf(target, rows) {
+    const sums = {};
+    for (const column of target.columns.filter(one => one.total && one.type === 'number')) {
+        sums[column.name] = Math.round(rows.reduce((sum, row) => sum + (typeof row[column.name] === 'number' ? row[column.name] : 0), 0) * 100) / 100;
+    }
+    return sums;
+}
+/** The rows grouped by one column - a date column by its month - each with its count and sums, largest first. */
+function groupsOf(target, rows, by) {
+    const column = target.columns.find(one => one.name === by);
+    if (!column)
+        return undefined;
+    const groups = new Map();
+    for (const row of rows) {
+        const value = row[by];
+        const key = value === null || value === undefined ? '' : column.type === 'date' ? String(value).slice(0, 7) : String(value);
+        groups.set(key, [...(groups.get(key) ?? []), row]);
+    }
+    const list = [...groups].map(([key, members]) => ({ key, count: members.length, sums: sumsOf(target, members) }));
+    const first = target.columns.find(one => one.total)?.name;
+    return column.type === 'date'
+        ? list.sort((a, b) => a.key.localeCompare(b.key))
+        : list.sort((a, b) => (first ? Math.abs(b.sums[first] ?? 0) - Math.abs(a.sums[first] ?? 0) : b.count - a.count));
+}
+/** The address of the target's list screen with the conditions it takes, and the conditions it does not. */
+function screenAddress(target, criteria) {
+    const screen = target.screen;
+    if (!screen)
+        return undefined;
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(screen.params(criteria)))
+        if (value !== undefined && value !== null && value !== '')
+            params.set(name, String(value));
+    const given = Object.keys(criteria);
+    const query = params.toString();
+    return {
+        href: query ? `${screen.route}?${query}` : screen.route,
+        applied: given.filter(name => screen.takes.includes(name)),
+        notApplied: given.filter(name => !screen.takes.includes(name))
+    };
+}
+//# sourceMappingURL=read-target.js.map

package/dist-server/service/data-read/read-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-target.js","sourceRoot":"","sources":["../../../server/service/data-read/read-target.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * AI 조회 - an application's list, read through its own query as the person (operato-application/design/ai/read-targets.md).\n *\n * The application declares what it lets the assistant read: its list query, the conditions the model may set and\n * how each becomes one of the query's filters, the columns to show, and the screen that lists the same records.\n * The framework reads the rows through that query with the person's request state - the same @privilege and\n * domain as the screen - counts and sums them itself, and puts a long result on the AI 작업판 as the query returned\n * it. The model is told the count, the sums and a few rows; it never copies a table.\n *\n * Pure but for the GraphQL runner, which comes in as an argument - the rules are tested without a server.\n */\nimport { readFieldValue, rootFieldOf, type EntryField } from '../data-entry/entry-target.js'\nimport type { GraphqlRunner } from '../data-entry/entry-update.js'\n\nexport interface ReadFilter {\n  name: string\n  operator: string\n  value: unknown\n}\n\n/** A condition the model may set - read with the entry fields' rules, turned into the query's filters by the application. */\nexport interface ReadCriterion extends Omit<EntryField, 'required' | 'reference' | 'total'> {\n  filter: (value: any) => ReadFilter | ReadFilter[]\n}\n\nexport interface ReadColumn {\n  /** The key in the workspace table. */\n  name: string\n  /** Where the value is in a row - a dotted path into the query's item (`account.name`). Defaults to `name`. */\n  path?: string\n  type: 'string' | 'number' | 'date'\n  labelKey?: string\n  /** A number column the server sums. */\n  total?: boolean\n}\n\nexport interface ReadScreen {\n  /** The application's route of the list screen (`cash-transaction-list`). */\n  route: string\n  /** The conditions the screen takes, as its address's query arguments. A condition left out is said on the card. */\n  params: (criteria: Record<string, any>) => Record<string, string | number | undefined>\n  /** The conditions `params` carries - the card names the others as not applied on the screen. */\n  takes: string[]\n  labelKey?: string\n}\n\nexport interface ReadTarget {\n  /** `<app>.<record>` - the tools are named after it. */\n  key: string\n  /** i18n key naming the records (「은행 입출금」). */\n  labelKey?: string\n  /** What the records are, for the model. */\n  description: string\n  /**\n   * The list query - takes `$filters: [Filter!]`, `$pagination: Pagination` and `$sortings: [Sorting!]`, and\n   * `$search: String` when `search` is declared.\n   */\n  query: string\n  /**\n   * The list takes ListParam's free-text term, matched by the resolver across its own searchable fields - the\n   * condition `text`. Say what it finds in, for the model.\n   */\n  search?: { description: string }\n  criteria: ReadCriterion[]\n  columns: ReadColumn[]\n  rowsOf: (data: any) => { rows: any[]; total: number }\n  /** Orders the rows; the query's own order when left out. */\n  sortings?: { name: string; desc?: boolean }[]\n  screen?: ReadScreen\n}\n\n/** At most this many rows are read - the AI 작업판 table's own limit (workspace-blocks MAX_TABLE_ROWS). */\nexport const MAX_READ_ROWS = 1000\n/** Rows the model is shown; the rest stay on the card. */\nexport const ROWS_FOR_MODEL = 20\n/** A page of the list query. */\nexport const READ_PAGE = 200\n\nconst registry = new Map<string, ReadTarget>()\n\nconst pascalOf = (key: string) =>\n  key\n    .split(/[^a-zA-Z0-9]+/)\n    .filter(Boolean)\n    .map(part => part[0].toUpperCase() + part.slice(1))\n    .join('')\n\nexport const queryToolName = (key: string) => `query${pascalOf(key)}`\nexport const screenToolName = (key: string) => `open${pascalOf(key)}Screen`\nexport const readCategoryName = (key: string) => `data-read:${key}`\n\nexport function declareReadTarget(target: ReadTarget): void {\n  if (!/^[a-z0-9-]+\\.[a-z0-9-]+$/.test(target.key)) throw new Error(`read target key '${target.key}' is not <app>.<record>`)\n  if (registry.has(target.key)) throw new Error(`read target '${target.key}' is declared twice`)\n  rootFieldOf(target.query, 'query')\n  if (!target.columns.length) throw new Error(`read target '${target.key}' shows no column`)\n  const names = new Set<string>()\n  for (const criterion of target.criteria) {\n    if (criterion.name === 'id') throw new Error(`read target '${target.key}' declares 'id' - every target takes it`)\n    if (criterion.name === 'text' && target.search) throw new Error(`read target '${target.key}' declares 'text' and search - search is the text condition`)\n    if (names.has(criterion.name)) throw new Error(`read target '${target.key}' names the condition '${criterion.name}' twice`)\n    names.add(criterion.name)\n    if (criterion.type === 'enum' && !criterion.values?.length) throw new Error(`condition '${criterion.name}' of '${target.key}' lists no values`)\n  }\n  if (target.search) names.add('text')\n  for (const taken of target.screen?.takes ?? []) if (!names.has(taken)) throw new Error(`the screen of '${target.key}' takes '${taken}', which is no condition`)\n  registry.set(target.key, target)\n}\n\nexport function readTargetOf(key: string | undefined): ReadTarget | undefined {\n  return key ? registry.get(key) : undefined\n}\n\nexport function clearReadTargets(): void {\n  registry.clear()\n}\n\n/** The conditions the model set, read by their declared types; a value that does not fit is said, never guessed at. */\nexport function readCriteria(target: ReadTarget, args: any): { criteria: Record<string, unknown>; refused: { name: string; code: string }[] } {\n  const criteria: Record<string, unknown> = {}\n  const refused: { name: string; code: string }[] = []\n  /* One record by its id - every target takes it (the id a list answer or a find tool gave). */\n  if (typeof args?.id === 'string' && args.id.trim()) criteria.id = args.id.trim()\n  if (target.search && typeof args?.text === 'string' && args.text.trim()) criteria.text = args.text.trim()\n  for (const criterion of target.criteria) {\n    const value = args?.[criterion.name]\n    if (value === undefined || value === null || value === '') continue\n    const { read, code } = readFieldValue(criterion as EntryField, value)\n    if (read === undefined) refused.push({ name: criterion.name, code: code ?? 'unreadable' })\n    else criteria[criterion.name] = read\n  }\n  return { criteria, refused }\n}\n\nexport function filtersOf(target: ReadTarget, criteria: Record<string, unknown>): ReadFilter[] {\n  return [\n    ...(typeof criteria.id === 'string' ? [{ name: 'id', operator: 'eq', value: criteria.id }] : []),\n    ...target.criteria.flatMap(criterion => (criterion.name in criteria ? [criterion.filter(criteria[criterion.name])].flat() : []))\n  ]\n}\n\nconst valueAt = (row: any, path: string) => path.split('.').reduce((at, part) => (at === null || at === undefined ? undefined : at[part]), row)\n\n/** One row as the columns say - a number column as a number, a missing value as null. */\nexport function rowOf(target: ReadTarget, item: any): Record<string, string | number | null> {\n  return Object.fromEntries([\n    /* The id names the record to the model - for one record's detail, a change, or its screen. */\n    ...(item?.id ? [['id', String(item.id)] as [string, string]] : []),\n    ...target.columns.map(column => {\n      const raw = valueAt(item, column.path ?? column.name)\n      if (raw === undefined || raw === null || raw === '') return [column.name, null]\n      if (column.type === 'number') {\n        const number = Number(raw)\n        return [column.name, Number.isFinite(number) ? number : null]\n      }\n      return [column.name, String(raw)]\n    })\n  ])\n}\n\n/**\n * Reads the rows through the application's query, page by page, up to MAX_READ_ROWS. `complete` is false when the\n * list holds more - a sum of the rows read is then not the sum of the list, and is never said as one.\n */\nexport async function readRows(target: ReadTarget, filters: ReadFilter[], run: GraphqlRunner, search?: string): Promise<{ rows: Record<string, any>[]; total: number; complete: boolean }> {\n  const rows: Record<string, any>[] = []\n  let total = 0\n  for (let page = 1; rows.length < MAX_READ_ROWS; page++) {\n    const answer = await run(target.query, {\n      filters,\n      ...(search ? { search } : {}),\n      pagination: { page, limit: READ_PAGE },\n      ...(target.sortings ? { sortings: target.sortings } : {})\n    })\n    if (answer.errors?.length) throw new Error(answer.errors.map(one => one.message).join('; '))\n    const read = target.rowsOf(answer.data)\n    total = Number(read?.total) || 0\n    const items = read?.rows ?? []\n    rows.push(...items.slice(0, MAX_READ_ROWS - rows.length).map(item => rowOf(target, item)))\n    if (items.length < READ_PAGE || rows.length >= total) break\n  }\n  return { rows, total, complete: rows.length >= total }\n}\n\nexport interface ReadGroup {\n  key: string\n  count: number\n  sums: Record<string, number>\n}\n\n/** The sums of the number columns marked total - the server's, never the model's. */\nexport function sumsOf(target: ReadTarget, rows: Record<string, any>[]): Record<string, number> {\n  const sums: Record<string, number> = {}\n  for (const column of target.columns.filter(one => one.total && one.type === 'number')) {\n    sums[column.name] = Math.round(rows.reduce((sum, row) => sum + (typeof row[column.name] === 'number' ? row[column.name] : 0), 0) * 100) / 100\n  }\n  return sums\n}\n\n/** The rows grouped by one column - a date column by its month - each with its count and sums, largest first. */\nexport function groupsOf(target: ReadTarget, rows: Record<string, any>[], by: string): ReadGroup[] | undefined {\n  const column = target.columns.find(one => one.name === by)\n  if (!column) return undefined\n  const groups = new Map<string, Record<string, any>[]>()\n  for (const row of rows) {\n    const value = row[by]\n    const key = value === null || value === undefined ? '' : column.type === 'date' ? String(value).slice(0, 7) : String(value)\n    groups.set(key, [...(groups.get(key) ?? []), row])\n  }\n  const list = [...groups].map(([key, members]) => ({ key, count: members.length, sums: sumsOf(target, members) }))\n  const first = target.columns.find(one => one.total)?.name\n  return column.type === 'date'\n    ? list.sort((a, b) => a.key.localeCompare(b.key))\n    : list.sort((a, b) => (first ? Math.abs(b.sums[first] ?? 0) - Math.abs(a.sums[first] ?? 0) : b.count - a.count))\n}\n\n/** The address of the target's list screen with the conditions it takes, and the conditions it does not. */\nexport function screenAddress(target: ReadTarget, criteria: Record<string, unknown>): { href: string; applied: string[]; notApplied: string[] } | undefined {\n  const screen = target.screen\n  if (!screen) return undefined\n  const params = new URLSearchParams()\n  for (const [name, value] of Object.entries(screen.params(criteria))) if (value !== undefined && value !== null && value !== '') params.set(name, String(value))\n  const given = Object.keys(criteria)\n  const query = params.toString()\n  return {\n    href: query ? `${screen.route}?${query}` : screen.route,\n    applied: given.filter(name => screen.takes.includes(name)),\n    notApplied: given.filter(name => !screen.takes.includes(name))\n  }\n}\n"]}

package/dist-server/service/data-read/read-tools.d.ts

@@ -0,0 +1,228 @@
+import { type ToolCategory } from '@things-factory/ai-client-base';
+import type { GraphqlRunner } from '../data-entry/entry-update.js';
+import { type ReadTarget } from './read-target.js';
+export declare function queryRecords(target: ReadTarget, args: any, context: any, run: GraphqlRunner): Promise<{
+    rejected: boolean;
+    error: string;
+    refused: {
+        name: string;
+        code: string;
+    }[];
+    message: string;
+} | {
+    rejected: boolean;
+    error: string;
+    message: string;
+    refused?: undefined;
+} | {
+    record: any;
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    moreGroups?: number;
+    groupBy: any;
+    groups: import("./read-target.js").ReadGroup[];
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    record: any;
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    groupBy: any;
+    groupRefused: string;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    record: any;
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    moreGroups?: number;
+    groupBy: any;
+    groups: import("./read-target.js").ReadGroup[];
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    groupBy: any;
+    groupRefused: string;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    forScreen: {
+        workspace: import("../workspace/workspace-blocks.js").Workspace;
+        contents: Record<string, number>;
+    };
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    moreGroups?: number;
+    groupBy: any;
+    groups: import("./read-target.js").ReadGroup[];
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    proposed: boolean;
+    kind: string;
+    icon: string;
+    label: any;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    forScreen: {
+        workspace: import("../workspace/workspace-blocks.js").Workspace;
+        contents: Record<string, number>;
+    };
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    groupBy: any;
+    groupRefused: string;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    proposed: boolean;
+    kind: string;
+    icon: string;
+    label: any;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+} | {
+    forScreen: {
+        workspace: import("../workspace/workspace-blocks.js").Workspace;
+        contents: Record<string, number>;
+    };
+    message: string;
+    rowsNotShown?: number;
+    rows: any;
+    target: string;
+    criteria: Record<string, unknown>;
+    total: any;
+    read: any;
+    complete: any;
+    sums: Record<string, number>;
+    proposed: boolean;
+    kind: string;
+    icon: string;
+    label: any;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+}>;
+export declare function openScreen(target: ReadTarget, args: any, context: any): {
+    rejected: boolean;
+    error: string;
+    refused: {
+        name: string;
+        code: string;
+    }[];
+    message: string;
+    proposed?: undefined;
+    kind?: undefined;
+    icon?: undefined;
+    label?: undefined;
+    target?: undefined;
+    href?: undefined;
+    applied?: undefined;
+    notApplied?: undefined;
+    notAppliedLabels?: undefined;
+} | {
+    rejected: boolean;
+    error: string;
+    message: string;
+    refused?: undefined;
+    proposed?: undefined;
+    kind?: undefined;
+    icon?: undefined;
+    label?: undefined;
+    target?: undefined;
+    href?: undefined;
+    applied?: undefined;
+    notApplied?: undefined;
+    notAppliedLabels?: undefined;
+} | {
+    proposed: boolean;
+    kind: string;
+    icon: string;
+    label: string;
+    target: string;
+    href: string;
+    applied: string[];
+    notApplied: string[];
+    notAppliedLabels: string[];
+    message: string;
+    rejected?: undefined;
+    error?: undefined;
+    refused?: undefined;
+};
+export declare function readCategoryOf(target: ReadTarget, run?: (context: any) => GraphqlRunner): ToolCategory;
+/**
+ * What an application calls at boot to let the assistant read one of its lists. A mode opens it by naming the key
+ * in `readTargets`.
+ */
+export declare function registerReadTarget(target: ReadTarget): void;

package/dist-server/service/data-read/read-tools.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryRecords = queryRecords;
+exports.openScreen = openScreen;
+exports.readCategoryOf = readCategoryOf;
+exports.registerReadTarget = registerReadTarget;
+/*
+ * The tools of an AI 조회 target (operato-application/design/ai/read-targets.md §4, §5).
+ *
+ * query<X> reads the rows through the application's list query as the person, and tells the model the count, the
+ * sums, the groups and a few rows. A longer result goes on the AI 작업판 as a proposal the server builds from the rows
+ * themselves - the table is never written by the model. open<X>Screen reads nothing: it hands the card the address
+ * of the application's list screen with the conditions it takes.
+ */
+const ai_client_base_1 = require("@things-factory/ai-client-base");
+const entry_target_js_1 = require("../data-entry/entry-target.js");
+const entry_tools_js_1 = require("../data-entry/entry-tools.js");
+const workspace_blocks_js_1 = require("../workspace/workspace-blocks.js");
+const read_target_js_1 = require("./read-target.js");
+/** The reader's words for a key - the key's own default when the translator has none. */
+const wordsOf = (context) => (key, fallback) => {
+    if (!key || typeof context?.t !== 'function')
+        return fallback;
+    try {
+        const said = context.t(key);
+        return said && said !== key ? String(said) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+};
+function criterionSchema(criterion) {
+    /* One type per field - Gemini's function schema refuses a list of types (2026-10-01). */
+    const type = criterion.type === 'number' ? 'number' : criterion.type === 'integer' ? 'integer' : criterion.type === 'boolean' ? 'boolean' : 'string';
+    const said = [criterion.description, criterion.type === 'date' ? 'YYYY-MM-DD' : undefined, criterion.type === 'enum' ? `one of: ${criterion.values.join(', ')}` : undefined]
+        .filter(Boolean)
+        .join('. ');
+    return { type, ...(said ? { description: said } : {}) };
+}
+async function queryRecords(target, args, context, run) {
+    const { criteria, refused } = (0, read_target_js_1.readCriteria)(target, args);
+    if (refused.length) {
+        return { rejected: true, error: 'condition-unreadable', refused, message: `these conditions do not fit their type: ${refused.map(one => `${one.name} (${one.code})`).join(', ')}. Fix them and call again.` };
+    }
+    let read;
+    try {
+        read = await (0, read_target_js_1.readRows)(target, (0, read_target_js_1.filtersOf)(target, criteria), run, typeof criteria.text === 'string' && target.search ? criteria.text : undefined);
+    }
+    catch (error) {
+        return { rejected: true, error: 'query-failed', message: `the list could not be read: ${error?.message ?? error}` };
+    }
+    const { rows, total, complete } = read;
+    const sums = (0, read_target_js_1.sumsOf)(target, rows);
+    const groupBy = typeof args?.groupBy === 'string' && args.groupBy ? args.groupBy : undefined;
+    const groups = groupBy ? (0, read_target_js_1.groupsOf)(target, rows, groupBy) : undefined;
+    const words = wordsOf(context);
+    const label = words(target.labelKey, target.key);
+    const said = {
+        target: target.key,
+        criteria,
+        total,
+        read: rows.length,
+        complete,
+        sums,
+        ...(groupBy ? (groups ? { groupBy, groups: groups.slice(0, 50), ...(groups.length > 50 ? { moreGroups: groups.length - 50 } : {}) } : { groupBy, groupRefused: 'no such column' }) : {}),
+        rows: rows.slice(0, read_target_js_1.ROWS_FOR_MODEL),
+        ...(rows.length > read_target_js_1.ROWS_FOR_MODEL ? { rowsNotShown: rows.length - read_target_js_1.ROWS_FOR_MODEL } : {})
+    };
+    const incomplete = complete
+        ? ''
+        : ` Only ${rows.length} of ${total} rows were read; the sums and groups are of those rows, not of the list - say so, and ask the person to narrow the conditions.`;
+    if (rows.length === 1 && args?.show !== 'workspace') {
+        return { ...said, record: rows[0], message: 'one record - answer from its fields; say a field it does not have as not recorded.' };
+    }
+    if (rows.length <= read_target_js_1.ROWS_FOR_MODEL && args?.show !== 'workspace') {
+        return { ...said, message: `${rows.length} rows of ${total}.${incomplete} Answer from these rows; every number you say comes from them.` };
+    }
+    /* The workspace is built here from the rows as read - the model never copies the table. */
+    const columns = target.columns.map(column => ({ name: column.name, label: words(column.labelKey, column.name), type: column.type }));
+    const totalColumns = target.columns.filter(one => one.total);
+    const title = typeof args?.title === 'string' && args.title.trim() ? args.title.trim() : `${label} · ${rows.length}`;
+    const { workspace } = (0, workspace_blocks_js_1.normalizeWorkspace)({
+        name: typeof args?.name === 'string' && args.name ? args.name : target.key.replace(/\./g, '-'),
+        title,
+        ...(complete ? {} : { summary: `${total} / ${rows.length}` }),
+        blocks: [
+            {
+                kind: 'metrics',
+                items: [{ label: words('ai-assistant.read.count', 'rows'), value: String(rows.length), ...(complete ? {} : { note: `/ ${total}` }) }, ...totalColumns.map(column => ({ label: words(column.labelKey, column.name), value: String(sums[column.name]) }))]
+            },
+            ...(groups
+                ? [
+                    {
+                        kind: 'table',
+                        caption: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy),
+                        columns: [{ name: 'key', label: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy), type: 'string' }, { name: 'count', label: words('ai-assistant.read.count', 'rows'), type: 'number' }, ...totalColumns.map(column => ({ name: column.name, label: words(column.labelKey, column.name), type: 'number' }))],
+                        rows: groups.map(group => ({ key: group.key, count: group.count, ...group.sums }))
+                    }
+                ]
+                : []),
+            { kind: 'table', caption: label, columns, rows }
+        ]
+    });
+    return {
+        proposed: true,
+        kind: 'workspace',
+        icon: 'table_view',
+        label: title,
+        ...said,
+        forScreen: { workspace, contents: (0, workspace_blocks_js_1.workspaceContents)(workspace) },
+        message: `${rows.length} rows of ${total} are on the AI 작업판 as read - the person opens it from the card.${incomplete} Say the point in one or two lines from the sums, groups and rows above; do not write the table out.`
+    };
+}
+function openScreen(target, args, context) {
+    const { criteria, refused } = (0, read_target_js_1.readCriteria)(target, args);
+    if (refused.length)
+        return { rejected: true, error: 'condition-unreadable', refused, message: 'fix the conditions and call again.' };
+    const address = (0, read_target_js_1.screenAddress)(target, criteria);
+    if (!address)
+        return { rejected: true, error: 'no-screen', message: 'this list has no screen to open.' };
+    const words = wordsOf(context);
+    return {
+        proposed: true,
+        kind: 'open-page',
+        icon: 'open_in_new',
+        label: words(target.screen.labelKey ?? target.labelKey, target.key),
+        target: target.key,
+        href: address.href,
+        applied: address.applied,
+        notApplied: address.notApplied,
+        /* The card says them in the reader's words. */
+        notAppliedLabels: address.notApplied.map(name => words(target.criteria.find(one => one.name === name)?.labelKey ?? (name === 'text' || name === 'id' ? `ai-assistant.read.${name}` : undefined), name)),
+        message: 'the card opens the screen when the person presses it.' +
+            (address.notApplied.length ? ` The screen does not take ${address.notApplied.join(', ')} - say so.` : '')
+    };
+}
+function readCategoryOf(target, run = entry_tools_js_1.runAsCaller) {
+    const door = (0, entry_target_js_1.rootFieldOf)(target.query, 'query');
+    const conditions = {
+        ...Object.fromEntries(target.criteria.map(criterion => [criterion.name, criterionSchema(criterion)])),
+        ...(target.search ? { text: { type: 'string', description: `words to find - ${target.search.description}` } } : {})
+    };
+    const specs = [
+        {
+            kind: 'read',
+            name: (0, read_target_js_1.queryToolName)(target.key),
+            /* The person must be able to read the list on its screen - the tool is not a second way in. */
+            doors: [door],
+            description: `Read ${target.description} Set the conditions the question names. Returns the count, the sums, ` +
+                `groups when groupBy is given (a date column groups by month) and the first ${read_target_js_1.ROWS_FOR_MODEL} rows; more rows go on the AI 작업판 as read.`,
+            schema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'One record by its id, from an earlier answer - its detail.' },
+                    ...conditions,
+                    groupBy: { type: 'string', description: `One column to group by: ${target.columns.map(one => one.name).join(', ')}.` },
+                    show: { type: 'string', enum: ['answer', 'workspace'], description: 'workspace to put even a short result on the AI 작업판.' },
+                    title: { type: 'string', description: 'The workspace title, in the person\'s language.' },
+                    name: { type: 'string', description: 'The workspace key; the same key again makes a new version.' }
+                }
+            },
+            builder: (args, context) => queryRecords(target, args, context, run(context))
+        },
+        ...(target.screen
+            ? [
+                {
+                    kind: 'read',
+                    name: (0, read_target_js_1.screenToolName)(target.key),
+                    doors: [door],
+                    description: `Offer the person the screen that lists ${target.description} with these conditions. Reads nothing. The screen takes: ${target.screen.takes.join(', ')}.`,
+                    schema: { type: 'object', properties: conditions },
+                    builder: (args, context) => openScreen(target, args, context)
+                }
+            ]
+            : [])
+    ];
+    return {
+        name: (0, read_target_js_1.readCategoryName)(target.key),
+        description: `data read: ${target.key}`,
+        guidance: [
+            `- To answer from ${target.key} records - a list, or one record found by its name, code or id - call ${(0, read_target_js_1.queryToolName)(target.key)} with the conditions the question names. Every number you say comes from its result - never add up rows yourself; use its sums and groups.`,
+            `- A list, a summary by item or month, or a comparison: call it with groupBy, and let a long result go on the AI 작업판 - then answer in one or two lines.`,
+            `- When the result says complete: false, say how many of how many were read and ask to narrow - never call partial sums the total.`,
+            ...(target.screen ? [`- When the person wants to work on the records themselves (edit, sort, export), call ${(0, read_target_js_1.screenToolName)(target.key)}; say which conditions the screen does not take.`] : [])
+        ].join('\n'),
+        specs
+    };
+}
+/**
+ * What an application calls at boot to let the assistant read one of its lists. A mode opens it by naming the key
+ * in `readTargets`.
+ */
+function registerReadTarget(target) {
+    (0, read_target_js_1.declareReadTarget)(target);
+    (0, ai_client_base_1.registerToolCategory)(readCategoryOf(target));
+}
+//# sourceMappingURL=read-tools.js.map