@mapomodule/mcp 1.0.0-beta.3 → 1.0.0-experimental.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.
Files changed (50) hide show
  1. package/README.md +26 -24
  2. package/dist/build.mjs +66 -4
  3. package/dist/cli.mjs +8 -1
  4. package/dist/knowledge/api.json +1 -1
  5. package/dist/knowledge/docs.json +1 -1
  6. package/dist/module.json +1 -1
  7. package/dist/runtime/core/ai-setup/catalog.d.ts +0 -0
  8. package/dist/runtime/core/ai-setup/catalog.js +411 -0
  9. package/dist/runtime/core/ai-setup/index.d.ts +0 -0
  10. package/dist/runtime/core/ai-setup/index.js +20 -0
  11. package/dist/runtime/core/ai-setup/plan.d.ts +0 -0
  12. package/dist/runtime/core/ai-setup/plan.js +640 -0
  13. package/dist/runtime/core/ai-setup/questions.d.ts +0 -0
  14. package/dist/runtime/core/ai-setup/questions.js +237 -0
  15. package/dist/runtime/core/indexer.js +10 -3
  16. package/dist/runtime/core/instructions.js +3 -2
  17. package/dist/runtime/core/prompts.js +25 -1
  18. package/dist/runtime/core/recipes.js +388 -3
  19. package/dist/runtime/core/search.js +2 -1
  20. package/dist/runtime/core/tools/ai.d.ts +0 -0
  21. package/dist/runtime/core/tools/ai.js +125 -0
  22. package/dist/runtime/core/tools/api.js +7 -1
  23. package/dist/runtime/mcp/handlers/mapo/prompts/ai-setup.js +3 -0
  24. package/dist/runtime/mcp/handlers/mapo/tools/ai-setup.js +3 -0
  25. package/package.json +1 -1
  26. package/src/__tests__/aiSetup.test.ts +330 -0
  27. package/src/__tests__/cli.test.ts +1 -0
  28. package/src/__tests__/composables.test.ts +95 -0
  29. package/src/__tests__/indexer.test.ts +19 -0
  30. package/src/__tests__/knowledge.test.ts +48 -0
  31. package/src/__tests__/overview.test.ts +11 -0
  32. package/src/__tests__/recipes.test.ts +67 -0
  33. package/src/__tests__/search.test.ts +16 -0
  34. package/src/__tests__/tools.test.ts +27 -1
  35. package/src/build/extract-components.ts +33 -5
  36. package/src/build/extract-composables.ts +65 -2
  37. package/src/cli.ts +8 -1
  38. package/src/runtime/core/ai-setup/catalog.ts +475 -0
  39. package/src/runtime/core/ai-setup/index.ts +29 -0
  40. package/src/runtime/core/ai-setup/plan.ts +706 -0
  41. package/src/runtime/core/ai-setup/questions.ts +290 -0
  42. package/src/runtime/core/indexer.ts +16 -4
  43. package/src/runtime/core/instructions.ts +3 -2
  44. package/src/runtime/core/prompts.ts +28 -0
  45. package/src/runtime/core/recipes.ts +408 -3
  46. package/src/runtime/core/search.ts +4 -1
  47. package/src/runtime/core/tools/ai.ts +209 -0
  48. package/src/runtime/core/tools/api.ts +8 -0
  49. package/src/runtime/mcp/handlers/mapo/prompts/ai-setup.ts +4 -0
  50. package/src/runtime/mcp/handlers/mapo/tools/ai-setup.ts +4 -0
@@ -15,7 +15,7 @@ import {
15
15
  getDocTool,
16
16
  searchDocsTool,
17
17
  } from "../runtime/core/tools/docs.js";
18
- import { makeContext, makeManifest } from "./fixtures.js";
18
+ import { makeApi, makeContext, makeManifest } from "./fixtures.js";
19
19
 
20
20
  const context = makeContext();
21
21
  const allTools = [...docsTools, ...apiTools, ...appTools];
@@ -104,6 +104,32 @@ describe("mapo_component_api", () => {
104
104
  expect(output).toContain("No Mapo component matches");
105
105
  expect(output).toContain("MapoList");
106
106
  });
107
+
108
+ it("says that a component of an opt-in package needs it turned on", async () => {
109
+ const api = makeApi();
110
+ api.components.push({
111
+ name: "MapoAiMagicFillBanner",
112
+ pkg: "@mapomodule/ai",
113
+ file: "packages/@mapomodule/ai/src/runtime/components/MapoAiMagicFillBanner.vue",
114
+ props: [
115
+ { name: "detail", type: "MapoAiMagicFillDetail", required: true },
116
+ ],
117
+ events: [],
118
+ slots: [],
119
+ exposed: [],
120
+ docs: [],
121
+ });
122
+ const withAi = makeContext(undefined, undefined, { api: () => api });
123
+
124
+ const banner = await componentApiTool.run(
125
+ { name: "MapoAiMagicFillBanner" },
126
+ withAi,
127
+ );
128
+ const list = await componentApiTool.run({ name: "MapoList" }, withAi);
129
+
130
+ expect(banner).toContain("it exists only in an app that sets `mapo.ai`");
131
+ expect(list).not.toContain("mapo.ai");
132
+ });
107
133
  });
108
134
 
109
135
  describe("mapo_list_field_types", () => {
@@ -11,10 +11,30 @@ import { join, relative } from "node:path";
11
11
  import { createChecker } from "vue-component-meta";
12
12
  import type { ApiMember, ComponentApi } from "../runtime/core/types.js";
13
13
 
14
- /** Packages whose `runtime/components` tree is scanned. */
15
- const COMPONENT_PACKAGES = [
14
+ /**
15
+ * Packages whose `runtime/components` tree is scanned. `only` lists the
16
+ * components a package registers for apps, when it has internal ones too:
17
+ * `@mapomodule/ai` registers the settings page and Magic Fill's four parts
18
+ * (its `module.ts`), the parts of the settings page stay inside it.
19
+ */
20
+ const COMPONENT_PACKAGES: {
21
+ pkg: string;
22
+ dir: string;
23
+ only?: readonly string[];
24
+ }[] = [
16
25
  { pkg: "@mapomodule/uikit", dir: "packages/@mapomodule/uikit" },
17
26
  { pkg: "@mapomodule/form", dir: "packages/@mapomodule/form" },
27
+ {
28
+ pkg: "@mapomodule/ai",
29
+ dir: "packages/@mapomodule/ai",
30
+ only: [
31
+ "MapoAiSettings",
32
+ "MapoAiMagicFillAction",
33
+ "MapoAiMagicFillBanner",
34
+ "MapoAiMagicFillPanel",
35
+ "MapoAiMagicFillPreview",
36
+ ],
37
+ },
18
38
  ];
19
39
 
20
40
  /** Union types can be enormous; keep them readable in a tool response. */
@@ -85,12 +105,20 @@ export function extractComponents(
85
105
  ): ComponentApi[] {
86
106
  const components: ComponentApi[] = [];
87
107
 
88
- for (const { pkg, dir } of COMPONENT_PACKAGES) {
108
+ for (const { pkg, dir, only } of COMPONENT_PACKAGES) {
89
109
  const packageRoot = join(repoRoot, dir);
90
110
  const tsconfig = join(packageRoot, "tsconfig.json");
91
111
  const componentsRoot = join(packageRoot, "src", "runtime", "components");
92
- const files = collectVueFiles(componentsRoot).filter((file) =>
93
- /\/Mapo[A-Z][^/]*\.vue$/.test(file),
112
+ const isListed = (file: string) =>
113
+ !only ||
114
+ only.includes(
115
+ file
116
+ .split("/")
117
+ .pop()!
118
+ .replace(/\.vue$/, ""),
119
+ );
120
+ const files = collectVueFiles(componentsRoot).filter(
121
+ (file) => /\/Mapo[A-Z][^/]*\.vue$/.test(file) && isListed(file),
94
122
  );
95
123
  if (!files.length || !existsSync(tsconfig)) continue;
96
124
 
@@ -3,7 +3,9 @@
3
3
  *
4
4
  * The module's `addImports([...])` calls are the authoritative list of what an
5
5
  * app can call without importing anything — exactly what an assistant needs to
6
- * know, and what it cannot infer from `node_modules`.
6
+ * know, and what it cannot infer from `node_modules`. Only those calls are
7
+ * read: `addServerImports([...])` names what the app's server code imports,
8
+ * which is no composable of the app.
7
9
  */
8
10
  import { existsSync, readFileSync, readdirSync } from "node:fs";
9
11
  import { join, relative } from "node:path";
@@ -30,6 +32,64 @@ interface Candidate {
30
32
  file: string;
31
33
  }
32
34
 
35
+ /**
36
+ * The text between the parentheses of each `addImports(...)` call of a
37
+ * module, so the entries of other calls, such as `addServerImports`, are
38
+ * never read as the app's composables.
39
+ */
40
+ function addImportsArguments(source: string): string[] {
41
+ const calls: string[] = [];
42
+ for (const match of source.matchAll(/\baddImports\s*\(/g)) {
43
+ const start = (match.index ?? 0) + match[0].length;
44
+ calls.push(source.slice(start, closingParenthesis(source, start)));
45
+ }
46
+ return calls;
47
+ }
48
+
49
+ /**
50
+ * Where the parenthesis opened just before `from` closes. Strings and
51
+ * comments are skipped: a parenthesis in them counts for nothing.
52
+ */
53
+ function closingParenthesis(source: string, from: number): number {
54
+ let depth = 1;
55
+ let at = from;
56
+ while (at < source.length) {
57
+ const char = source[at];
58
+ const next = source[at + 1];
59
+ if (char === '"' || char === "'" || char === "`") {
60
+ at = afterString(source, at, char);
61
+ continue;
62
+ }
63
+ if (char === "/" && next === "/") {
64
+ const end = source.indexOf("\n", at);
65
+ at = end === -1 ? source.length : end;
66
+ continue;
67
+ }
68
+ if (char === "/" && next === "*") {
69
+ const end = source.indexOf("*/", at + 2);
70
+ at = end === -1 ? source.length : end + 2;
71
+ continue;
72
+ }
73
+ if (char === "(") depth++;
74
+ if (char === ")") depth--;
75
+ if (depth === 0) return at;
76
+ at++;
77
+ }
78
+ return source.length;
79
+ }
80
+
81
+ /** Where the string that opens at `at` with `quote` ends. */
82
+ function afterString(source: string, at: number, quote: string): number {
83
+ let index = at + 1;
84
+ while (index < source.length) {
85
+ const char = source[index];
86
+ if (char === "\\") index += 2;
87
+ else if (char === quote) return index + 1;
88
+ else index++;
89
+ }
90
+ return source.length;
91
+ }
92
+
33
93
  /** Reads every `addImports` entry declared by the Mapo modules. */
34
94
  function collectCandidates(repoRoot: string): Candidate[] {
35
95
  const packagesDir = join(repoRoot, PACKAGES_ROOT);
@@ -46,7 +106,10 @@ function collectCandidates(repoRoot: string): Candidate[] {
46
106
  const source = readFileSync(moduleFile, "utf-8");
47
107
  const packageRoot = join(packagesDir, entry.name);
48
108
 
49
- for (const match of source.matchAll(ADD_IMPORT_ENTRY)) {
109
+ const entries = addImportsArguments(source).flatMap((call) => [
110
+ ...call.matchAll(ADD_IMPORT_ENTRY),
111
+ ]);
112
+ for (const match of entries) {
50
113
  const [, name, from] = match;
51
114
  if (!name || !from) continue;
52
115
 
package/src/cli.ts CHANGED
@@ -35,6 +35,7 @@ import { appTools } from "./runtime/core/tools/app.js";
35
35
  import { docsTools } from "./runtime/core/tools/docs.js";
36
36
  import { scaffoldTools } from "./runtime/core/tools/scaffold.js";
37
37
  import { backendTools } from "./runtime/core/tools/backend.js";
38
+ import { aiTools } from "./runtime/core/tools/ai.js";
38
39
  import { PROMPTS } from "./runtime/core/prompts.js";
39
40
  import {
40
41
  loadApiKnowledge,
@@ -63,7 +64,13 @@ export const DEFAULT_APP_URL = mcpEndpointUrl("http://localhost:3000");
63
64
 
64
65
  /** All tools that run without the Nuxt dev server. */
65
66
  function staticTools(): AnyMapoToolSpec[] {
66
- return [...docsTools, ...apiTools, ...scaffoldTools, ...backendTools];
67
+ return [
68
+ ...docsTools,
69
+ ...apiTools,
70
+ ...scaffoldTools,
71
+ ...backendTools,
72
+ ...aiTools,
73
+ ];
67
74
  }
68
75
 
69
76
  function createToolContext(
@@ -0,0 +1,475 @@
1
+ /**
2
+ * What `@mapomodule/ai` offers, as `mapo_ai_setup` tells a developer: the
3
+ * topics they may turn on, each pointing at the page and the section that
4
+ * document it, and the needs they may bring, each with what the module
5
+ * answers today.
6
+ *
7
+ * The docs stay the source: a topic made from a recipe reads its task from
8
+ * `recipes.ts`, every other topic names a page and a heading of the docs,
9
+ * and `knowledge.test.ts` checks them all against the real knowledge base.
10
+ * A need says what the module does about it and points at those topics, so
11
+ * a renamed page or heading fails the tests instead of a developer.
12
+ */
13
+ import { RECIPES } from "../recipes.js";
14
+
15
+ /** The groups the catalog lists its topics in. */
16
+ export const AI_AREAS = [
17
+ "Magic Fill",
18
+ "Filling from code",
19
+ "Sources",
20
+ "Providers and models",
21
+ "Keys and tokens",
22
+ "People and rules",
23
+ "Costs and limits",
24
+ "Production",
25
+ ] as const;
26
+
27
+ export type AiArea = (typeof AI_AREAS)[number];
28
+
29
+ /** Something the module does, and where the docs explain it. */
30
+ export interface AiTopic {
31
+ id: string;
32
+ area: AiArea;
33
+ /** What it lets an app do, in one line. */
34
+ title: string;
35
+ /** Docs path, relative to the docs root. */
36
+ doc: string;
37
+ /** The section of `doc`, as its heading reads. */
38
+ heading?: string;
39
+ }
40
+
41
+ /** A topic made from an AI recipe: its task, page and section. */
42
+ function fromRecipe(id: string, area: AiArea): AiTopic {
43
+ const recipe = RECIPES.find((one) => one.id === id);
44
+ if (!recipe) throw new Error(`No recipe "${id}" for the AI catalog`);
45
+ return {
46
+ id,
47
+ area,
48
+ title: recipe.task,
49
+ doc: recipe.doc,
50
+ ...(recipe.heading ? { heading: recipe.heading } : {}),
51
+ };
52
+ }
53
+
54
+ const AI_DOC = "modules/ai.md";
55
+ const MAGIC_FILL_DOC = "howto/magic-fill.md";
56
+
57
+ export const AI_TOPICS: AiTopic[] = [
58
+ fromRecipe("ai-magic-fill", "Magic Fill"),
59
+ {
60
+ id: "prepare-fields",
61
+ area: "Magic Fill",
62
+ title:
63
+ "Prepare the fields: a hint for the model, a field kept from the AI, a relation never listed",
64
+ doc: MAGIC_FILL_DOC,
65
+ heading: "3. Prepare the fields",
66
+ },
67
+ {
68
+ id: "turn-off",
69
+ area: "Magic Fill",
70
+ title: "Turn Magic Fill off on a page, or in the whole app",
71
+ doc: MAGIC_FILL_DOC,
72
+ heading: "4. Turn it off",
73
+ },
74
+ {
75
+ id: "no-quotes",
76
+ area: "Magic Fill",
77
+ title: "Ask the AI for no quotes on a page: every value then waits",
78
+ doc: MAGIC_FILL_DOC,
79
+ heading: "Ask for no quotes",
80
+ },
81
+ {
82
+ id: "errors",
83
+ area: "Magic Fill",
84
+ title: "What each error means, and what the operator does about it",
85
+ doc: MAGIC_FILL_DOC,
86
+ heading: "5. When something goes wrong",
87
+ },
88
+ {
89
+ id: "accessibility",
90
+ area: "Magic Fill",
91
+ title: "Keyboard, screen readers and reduced motion",
92
+ doc: MAGIC_FILL_DOC,
93
+ heading: "7. Accessibility",
94
+ },
95
+ {
96
+ id: "customize",
97
+ area: "Magic Fill",
98
+ title: "Replace a part of Magic Fill, or build a panel of your own",
99
+ doc: MAGIC_FILL_DOC,
100
+ heading: "8. Customize it",
101
+ },
102
+ fromRecipe("ai-fill", "Filling from code"),
103
+ fromRecipe("ai-run", "Filling from code"),
104
+ fromRecipe("ai-field-options", "Filling from code"),
105
+ {
106
+ id: "related-records",
107
+ area: "Filling from code",
108
+ title:
109
+ "Find related records: a few listed for the AI, the others searched by name",
110
+ doc: AI_DOC,
111
+ heading: "Related records",
112
+ },
113
+ fromRecipe("ai-read-files", "Sources"),
114
+ fromRecipe("ai-readers", "Sources"),
115
+ fromRecipe("ai-providers", "Providers and models"),
116
+ {
117
+ id: "mock",
118
+ area: "Providers and models",
119
+ title: "Develop and test with the mock: no key, no network, no cost",
120
+ doc: AI_DOC,
121
+ heading: "The mock",
122
+ },
123
+ fromRecipe("ai-cloud-models", "Providers and models"),
124
+ fromRecipe("ai-local-models", "Providers and models"),
125
+ {
126
+ id: "own-provider",
127
+ area: "Providers and models",
128
+ title: "Call another AI service, with a provider of the app's own",
129
+ doc: AI_DOC,
130
+ heading: "Your own provider",
131
+ },
132
+ fromRecipe("ai-keys", "Keys and tokens"),
133
+ {
134
+ id: "personal-tokens",
135
+ area: "Keys and tokens",
136
+ title: "Let users save their own token, where an assignment allows it",
137
+ doc: AI_DOC,
138
+ heading: "Personal tokens",
139
+ },
140
+ {
141
+ id: "secret",
142
+ area: "Keys and tokens",
143
+ title: "Seal the keys, tokens and settings with NUXT_MAPO_AI_SECRET",
144
+ doc: AI_DOC,
145
+ heading: "Set the secret",
146
+ },
147
+ {
148
+ id: "restrict-users",
149
+ area: "People and rules",
150
+ title:
151
+ "Choose who may use the AI: groups, permissions, or a rule of the backend",
152
+ doc: AI_DOC,
153
+ heading: "Restrict who uses the AI",
154
+ },
155
+ {
156
+ id: "admins",
157
+ area: "People and rules",
158
+ title: "Choose who administers the AI",
159
+ doc: AI_DOC,
160
+ heading: "Admins",
161
+ },
162
+ {
163
+ id: "app-rules",
164
+ area: "People and rules",
165
+ title: "Give the AI the app's rules, in every prompt or by entity",
166
+ doc: AI_DOC,
167
+ heading: "Add the app's rules",
168
+ },
169
+ fromRecipe("ai-settings", "People and rules"),
170
+ fromRecipe("ai-admin-settings", "People and rules"),
171
+ {
172
+ id: "verification",
173
+ area: "People and rules",
174
+ title: "Decide what a quote must hold for a value to count as verified",
175
+ doc: AI_DOC,
176
+ heading: "Verification",
177
+ },
178
+ fromRecipe("ai-usage", "Costs and limits"),
179
+ {
180
+ id: "limits",
181
+ area: "Costs and limits",
182
+ title:
183
+ "Limit the calls per user and minute, the source's length and the files' size",
184
+ doc: AI_DOC,
185
+ heading: "Limits",
186
+ },
187
+ {
188
+ id: "prompt-cache",
189
+ area: "Costs and limits",
190
+ title: "Pay less for the part of the prompt that repeats, with the cache",
191
+ doc: AI_DOC,
192
+ heading: "The prompt cache",
193
+ },
194
+ {
195
+ id: "enable",
196
+ area: "Production",
197
+ title: "Turn the module on with `mapo.ai`",
198
+ doc: AI_DOC,
199
+ heading: "Enable the module",
200
+ },
201
+ {
202
+ id: "storage",
203
+ area: "Production",
204
+ title:
205
+ "Keep the AI's sealed state: one disk, a shared store for several instances",
206
+ doc: AI_DOC,
207
+ heading: "Where the state is kept",
208
+ },
209
+ {
210
+ id: "audit",
211
+ area: "Production",
212
+ title: "An audit of every call, metadata only, never the source",
213
+ doc: AI_DOC,
214
+ heading: "The audit",
215
+ },
216
+ ];
217
+
218
+ /** How the module answers a need. */
219
+ export type AiVerdict = "ready" | "app-code" | "not-yet" | "no";
220
+
221
+ export const AI_VERDICTS: Record<AiVerdict, string> = {
222
+ ready: "Yes, out of the box",
223
+ "app-code": "Yes, with code of the app",
224
+ "not-yet": "Not yet",
225
+ no: "No",
226
+ };
227
+
228
+ /** The needs a developer may bring, by id: what `wants` takes. */
229
+ export const AI_NEED_IDS = [
230
+ "fill-record",
231
+ "extract-records",
232
+ "files",
233
+ "pdf-images",
234
+ "own-format",
235
+ "related-records",
236
+ "private-relations",
237
+ "exclude-fields",
238
+ "hints",
239
+ "translations",
240
+ "lists",
241
+ "review",
242
+ "save-without-review",
243
+ "generate-content",
244
+ "chat",
245
+ "custom-panel",
246
+ "cloud",
247
+ "local-only",
248
+ "own-provider",
249
+ "team-keys",
250
+ "personal-tokens",
251
+ "costs",
252
+ "limits",
253
+ "restrict-users",
254
+ "app-rules",
255
+ "admin-settings",
256
+ "audit",
257
+ ] as const;
258
+
259
+ export type AiNeedId = (typeof AI_NEED_IDS)[number];
260
+
261
+ /** A need, and what the module answers about it. */
262
+ export interface AiNeed {
263
+ id: AiNeedId;
264
+ /** The need, as a developer puts it. */
265
+ need: string;
266
+ verdict: AiVerdict;
267
+ /** How the module meets it, or why it does not. */
268
+ how: string;
269
+ /** The topics that document it. */
270
+ topics: string[];
271
+ }
272
+
273
+ export const AI_NEEDS: AiNeed[] = [
274
+ {
275
+ id: "fill-record",
276
+ need: "Fill the record an operator is editing from a text or files",
277
+ verdict: "ready",
278
+ how: "Magic Fill, on every `MapoDetail` of an app with uikit: a button in the sidebar card, a panel for the source, a banner that previews every value. A value goes into an empty field by itself only when a quote of the source proves it; every other value waits for the operator.",
279
+ topics: ["ai-magic-fill", "ai-fill"],
280
+ },
281
+ {
282
+ id: "extract-records",
283
+ need: "Create several records from one source, such as a programme or a sheet",
284
+ verdict: "app-code",
285
+ how: 'A page of the app calls `POST /_mapo/ai/run` with `task: "extract"` and the fields from `mapoAiFieldsSchema(fields)`, shows what came back, and creates the records the operator ticks and confirms. Mapo has no import page of its own yet: Import AI is planned.',
286
+ topics: ["ai-run", "ai-field-options"],
287
+ },
288
+ {
289
+ id: "files",
290
+ need: "Start from web pages, Markdown, CSV, Excel or JSON files",
291
+ verdict: "ready",
292
+ how: "The gateway's `read` turns a file into text with Mapo's readers; Magic Fill's panel takes files, and `useMapoAiRead()` does it in a component of the app.",
293
+ topics: ["ai-read-files"],
294
+ },
295
+ {
296
+ id: "pdf-images",
297
+ need: "Start from PDFs, scans or images",
298
+ verdict: "not-yet",
299
+ how: "Mapo does not read them yet. Meanwhile a reader of the app (`registerMapoAiReader()`) can turn them into text with a library the app installs: the AI takes text only.",
300
+ topics: ["ai-readers"],
301
+ },
302
+ {
303
+ id: "own-format",
304
+ need: "Start from a format of the app's own, such as a calendar or an export",
305
+ verdict: "app-code",
306
+ how: "`registerMapoAiReader()` in a Nitro plugin adds a format, or replaces one of Mapo's; the `mapo-ai:read` hook touches up what any reader read, and `mapo.ai.readers` turns a format off.",
307
+ topics: ["ai-readers"],
308
+ },
309
+ {
310
+ id: "related-records",
311
+ need: "Pick related records: categories, tags, authors",
312
+ verdict: "ready",
313
+ how: "A relation with up to 50 records is listed for the AI, which picks one; a larger one is searched by the name the AI writes, with the endpoint's `?search=`. Several matches wait on the field's mark, with candidates to pick.",
314
+ topics: ["related-records"],
315
+ },
316
+ {
317
+ id: "private-relations",
318
+ need: "Keep the names of related records, such as people's emails, from the provider",
319
+ verdict: "ready",
320
+ how: "`ai: { list: false }` on the field: its records are never listed for the AI, which writes what it reads; Magic Fill searches it afterwards, in the browser.",
321
+ topics: ["ai-field-options", "prepare-fields"],
322
+ },
323
+ {
324
+ id: "exclude-fields",
325
+ need: "Keep some fields away from the AI",
326
+ verdict: "ready",
327
+ how: "`ai: { exclude: true }` on the field, or `x-mapo-ai` in the backend's schema. Fields named as secrets (Mapo's words, `mapo.ai.secretWords`, the admins' own), read-only fields and media are left out by themselves.",
328
+ topics: ["ai-field-options", "prepare-fields"],
329
+ },
330
+ {
331
+ id: "hints",
332
+ need: "Tell the AI how to fill a field",
333
+ verdict: "ready",
334
+ how: "`ai: { hint }` on the field: the model reads it as the field's description, in the schema of its answer.",
335
+ topics: ["ai-field-options", "prepare-fields"],
336
+ },
337
+ {
338
+ id: "translations",
339
+ need: "Fill the languages of translatable fields",
340
+ verdict: "ready",
341
+ how: "Magic Fill fills the language the form shows; a `synci18n` value goes into every language. Each language is one extraction.",
342
+ topics: ["ai-magic-fill"],
343
+ },
344
+ {
345
+ id: "lists",
346
+ need: "Fill repeaters, blocks and lists of items",
347
+ verdict: "ready",
348
+ how: "The items the AI finds are ticked one by one in the preview, and go after the record's own; an item the record holds is never added twice.",
349
+ topics: ["ai-magic-fill"],
350
+ },
351
+ {
352
+ id: "review",
353
+ need: "Let the operator check every value before saving",
354
+ verdict: "ready",
355
+ how: "By design: each value shows the words of the source that prove it; a value without proof, or one that would replace the record's, waits for the operator's tick. Undo all puts the form back, and nothing is saved until Save.",
356
+ topics: ["ai-magic-fill"],
357
+ },
358
+ {
359
+ id: "save-without-review",
360
+ need: "Save the AI's values without an operator",
361
+ verdict: "no",
362
+ how: "By design: the gateway never writes to the backend, and Magic Fill fills the form, never saves it. An app that creates records from an extraction does it after the operator confirms.",
363
+ topics: ["ai-magic-fill"],
364
+ },
365
+ {
366
+ id: "generate-content",
367
+ need: "Write content the source does not hold, such as copy or SEO texts from nothing",
368
+ verdict: "no",
369
+ how: "Magic Fill takes values from a source: a value no quote proves waits as a proposal without proof, never goes in by itself. Writing new text is not its job.",
370
+ topics: ["verification"],
371
+ },
372
+ {
373
+ id: "chat",
374
+ need: "A conversational assistant, or an agent that acts in the backoffice",
375
+ verdict: "no",
376
+ how: "The module fills forms from sources; it has no chat and no agent.",
377
+ topics: ["ai-magic-fill"],
378
+ },
379
+ {
380
+ id: "custom-panel",
381
+ need: "A panel or a flow of the app's own",
382
+ verdict: "app-code",
383
+ how: "`useMapoAiFill()` and `useMapoAiRead()` in a detail extension do what Magic Fill does, with the app's interface; or one part of Magic Fill is replaced with MapoOverride.",
384
+ topics: ["customize", "ai-fill"],
385
+ },
386
+ {
387
+ id: "cloud",
388
+ need: "Use OpenAI or Anthropic (Claude) models",
389
+ verdict: "ready",
390
+ how: "The `openai` and `anthropic` providers, with a key in the server's environment or assigned by the AI's admins.",
391
+ topics: ["ai-cloud-models"],
392
+ },
393
+ {
394
+ id: "local-only",
395
+ need: "Keep every source on the company's own servers",
396
+ verdict: "ready",
397
+ how: "The `ollama` and `openai-compatible` providers call models on the app's own servers (Ollama, LM Studio, vLLM, llama.cpp), at the address the app sets; no key, no cost per token.",
398
+ topics: ["ai-local-models"],
399
+ },
400
+ {
401
+ id: "own-provider",
402
+ need: "Use another AI service",
403
+ verdict: "app-code",
404
+ how: "`registerMapoAiProvider()` in a Nitro plugin, enabled in `mapo.ai.providers`; its key comes from the environment like Mapo's providers.",
405
+ topics: ["own-provider", "ai-providers"],
406
+ },
407
+ {
408
+ id: "team-keys",
409
+ need: "Give teams their own keys and models",
410
+ verdict: "ready",
411
+ how: "On the AI settings page the AI's admins assign a key and the models to everyone, a group or a user, in an order of the groups; no deploy, and the keys are sealed in the storage.",
412
+ topics: ["ai-keys", "ai-settings"],
413
+ },
414
+ {
415
+ id: "personal-tokens",
416
+ need: "Let operators bring their own key",
417
+ verdict: "ready",
418
+ how: "An assignment of the admins allows personal tokens; each user saves theirs on the AI settings page, and their calls use it first.",
419
+ topics: ["personal-tokens", "ai-keys"],
420
+ },
421
+ {
422
+ id: "costs",
423
+ need: "Know how much the AI is used and what it costs",
424
+ verdict: "ready",
425
+ how: "The usage, read from the audit, by user, model and day, in tokens, and in money where `mapo.ai.prices` prices the models. The admins read everyone's, each user their own.",
426
+ topics: ["ai-usage"],
427
+ },
428
+ {
429
+ id: "limits",
430
+ need: "Cap how much a user can call the AI",
431
+ verdict: "ready",
432
+ how: "`mapo.ai.limits`: calls per user and minute (counted by each server process), the source's characters, the files' bytes. There is no spending cap per month yet.",
433
+ topics: ["limits"],
434
+ },
435
+ {
436
+ id: "restrict-users",
437
+ need: "Choose who may use the AI",
438
+ verdict: "ready",
439
+ how: "`mapo.ai.users` by groups or permissions; the `mapo-ai:user` hook for a rule of the backend, such as internal accounts only.",
440
+ topics: ["restrict-users"],
441
+ },
442
+ {
443
+ id: "app-rules",
444
+ need: "Rules the AI follows in every prompt",
445
+ verdict: "ready",
446
+ how: "`mapo.ai.instructions` (for every task, for fill, for extract), the `mapo-ai:prompt` hook for rules by entity or user, and the admins' instructions on the AI settings page.",
447
+ topics: ["app-rules", "ai-admin-settings"],
448
+ },
449
+ {
450
+ id: "admin-settings",
451
+ need: "Change how the AI works without a deploy",
452
+ verdict: "ready",
453
+ how: "The AI's admins change the instructions, the rules of verification, the secret words, the prompt cache, Anthropic's fallbacks and the models added, within what the app allows.",
454
+ topics: ["ai-admin-settings"],
455
+ },
456
+ {
457
+ id: "audit",
458
+ need: "Know who called the AI, and when",
459
+ verdict: "ready",
460
+ how: "Every call is audited in the sealed storage: who, which model, the tokens, the outcome; never the source, the instructions or the values.",
461
+ topics: ["audit"],
462
+ },
463
+ ];
464
+
465
+ /** The topic of an id, or `undefined`. */
466
+ export function aiTopic(id: string): AiTopic | undefined {
467
+ return AI_TOPICS.find((topic) => topic.id === id);
468
+ }
469
+
470
+ /** Where a topic is documented, as `mapo_get_doc` takes it. */
471
+ export function topicLink(topic: AiTopic): string {
472
+ return topic.heading
473
+ ? `\`${topic.doc}\` › ${topic.heading}`
474
+ : `\`${topic.doc}\``;
475
+ }