Pro 9879 ai reference by BoDonkey · Pull Request #567 · apostrophecms/docs

BoDonkey · 2026-09-08T19:10:10Z

Please indicate which branch this PR should merge into:

Check one

main
latest
stable
Check if this PR will be resubmitted against another branch

Summary

Summarize the changes briefly, including which issue/ticket this resolves. If it closes an existing Github issue, include "Closes #[issue number]"
This PR adds the ai-adapter reference modules to the site. Closes pro-9879.

What are the specific steps to test this change?

For example:

Run the website and log in as an admin

Open a piece manager modal and select several pieces

Click the "Archive" button on the top left of the manager and confirm that it should proceed

Check that all pieces have been archived properly

What kind of change does this PR introduce?

(Check at least one)

Make sure the PR fulfills these requirements:

It includes a) the existing issue ID being resolved, b) a convincing reason for adding this feature, or c) a clear description of the bug it resolves
The changelog is updated
Related documentation has been updated
Related tests have been updated

If adding a new feature without an already open issue, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

linear · 2026-09-08T19:10:12Z

PRO-9879

myovchev · 2026-09-09T08:18:59Z

+|---|---|---|
+| `low` | `gemini-3.1-flash-lite` | — |
+| `medium` | `gemini-3.5-flash` | — |
+| `high` | `gemini-3.5-flash` | `high` |


I now realize we don't use Gemini Pro. But I guess is OK as a start. I didn't spent too much time on Gemini.

There isn't a Pro text encoder. I also noticed that 3.5 is a little stale. There is a 3.5-flash-lite now also.

myovchev · 2026-09-09T08:37:06Z

+
+**For OpenAI proper, prefer `openai`.** It speaks OpenAI's first-class Responses API and supports `reasoning` alongside `tools`.
+
+[`openai-compatible`](/reference/modules/ai-adapter-openai-compatible.md) speaks Chat Completions, the de facto wire standard of the whole ecosystem — that is what makes it the universal adapter. It works against `api.openai.com` too, but there a `tools` request drops `reasoning`, because the service rejects the combination in that dialect. Aliased entries describe other services, which accept it, and pass through untouched.


but there a toolsrequest dropsreasoning`` - this sounds odd, do we need the there part?

Clarified and language cleaned up.

myovchev

This was a long read (!) but I think overall is very clear and helpful. I spotted some minor problems. Some of my comments are only "thinking loud" stuff.

myovchev · 2026-09-09T08:41:30Z

+        }
+      }
+    },
+    'my-module': {}


Avoid using my-xxx, this is reserved apostrophe thing and can behave in unexpected ways.

myovchev · 2026-09-09T08:57:53Z

+| `pending` | `'refuse'` \| `'execute'` | What to do with a transcript ending in unanswered tool calls. See [Suspension](#suspension-asking-the-user-mid-run). |
+| `toolInput` | object | Answers for suspended tool calls, keyed by tool call id. Requires `pending: 'execute'`. |
+| `schema` | object | JSON Schema (object root) for structured output. |
+| `effort` | string | The routing level to resolve. Defaults to `effort.default`. |


Defaults to the value of `effort.default`

myovchev · 2026-09-09T09:08:43Z

+      { type: 'image', image: { url: 'https://example.com/photo.jpg' } }
+    ]
+  }
+]


Here the dev should also see the assistant entry (between the user queries), leaving them out is confusing.

myovchev · 2026-09-09T09:09:49Z

+| text | `{ type: 'text', text }` | `user`, `assistant` |
+| image | `{ type: 'image', image: { url } }` or `{ type: 'image', image: { data, mediaType } }` | `user`, `assistant` |
+| tool call | `{ type: 'toolCall', id, name, input }` | `assistant` |
+| tool result | `{ type: 'toolResult', toolCallId, output }` or `{ …, error }` | `tool` |


The table explains entries that are NOT in the example above

Updated and clarified.

myovchev · 2026-09-09T09:34:31Z

+// }
+```
+
+`active` answers "is AI usable"; `modelCatalog` answers "what is configured". Under mock mode with no providers, `active` is `true` and the catalog is empty.


We have (probably forgot to document it) apos.ai.mockMode boolean as well, so it's possible to check that too.

apos.ai.mockmode is documented, but worth adding here. (see lines 523 and 1539)

myovchev · 2026-09-09T09:37:55Z

+
+### `can(req, action, docOrType, [mode])`
+
+The AI permission seam. Same signature and semantics as `apos.permission.can` — see [Permissions and workflow](/guide/permissions-and-workflow.md) — but it is **not** a plain proxy: it applies AI-specific policy first, and can only ever be as restrictive as `apos.permission.can`, never looser.


Meant to be used with tools or anything AI executed on behalf of the current user - probably worth mentioning.

Clarified and updated.

myovchev · 2026-09-09T09:40:15Z

+
+## Tools
+
+Tools are how a model does things: read content, search, write a draft, publish. The engine owns the loop; you own the handlers.


Do not mention publish here - it's not clear the approach we take in the future.

Removed here and several other places.

myovchev · 2026-09-09T09:47:11Z

+
+`input` is a JSON Schema describing the arguments the model may pass. This tool takes none, so `{ type: 'object' }` — an object with nothing in it — is the whole schema. The handler returns an object, and that object is what the model reads.
+
+`kind: 'query'` says the tool only reads. Queries the model asks for together run in parallel; without it a tool defaults to `'action'` and runs serially, one after another. Tag your read-only tools and a model that asks for six of them at once gets its answer in the time of the slowest, not the sum. See [Kinds and scheduling](#kinds-and-scheduling).


We never state what is the return type requirements - it's has to be ALWAYS an object, even when no schema is configured.

This was clearly stated elsewhere, but it is also needed here.

myovchev · 2026-09-09T09:50:15Z

+
+  // Instead of an inline function: a method on any module, resolved at
+  // startup. Handy when the handler is long or already exists
+  handler: 'page-tools:findPages'


I'm not sure we should encourage anon functions as handlers. I'd say remove the last sentence. It depends on projects standards and architecture design raised by the dev providing the tools.

myovchev · 2026-09-09T10:09:01Z

+
+### Errors in handlers
+
+There are exactly two outcomes for a failure, and the error code alone decides which.


There are 3 - aiInput, described above in the "Suspend" details. It even got an AI tool throw example that showcases how it works.

BoDonkey added 2 commits September 8, 2026 15:08

Initial reference pages

55fa0cc

Readability and linking

cc28dad

BoDonkey requested a review from myovchev September 8, 2026 19:10

myovchev reviewed Sep 9, 2026

View reviewed changes

myovchev requested changes Sep 9, 2026

View reviewed changes

Responses to first comments

332a9a7

BoDonkey requested a review from myovchev September 9, 2026 14:34

myovchev approved these changes Sep 10, 2026

View reviewed changes


		For OpenAI proper, prefer `openai`. It speaks OpenAI's first-class Responses API and supports `reasoning` alongside `tools`.

		[`openai-compatible`](/reference/modules/ai-adapter-openai-compatible.md) speaks Chat Completions, the de facto wire standard of the whole ecosystem — that is what makes it the universal adapter. It works against `api.openai.com` too, but there a `tools` request drops `reasoning`, because the service rejects the combination in that dialect. Aliased entries describe other services, which accept it, and pass through untouched.


		### `can(req, action, docOrType, [mode])`

		The AI permission seam. Same signature and semantics as `apos.permission.can` — see [Permissions and workflow](/guide/permissions-and-workflow.md) — but it is not a plain proxy: it applies AI-specific policy first, and can only ever be as restrictive as `apos.permission.can`, never looser.


		## Tools

		Tools are how a model does things: read content, search, write a draft, publish. The engine owns the loop; you own the handlers.


		`input` is a JSON Schema describing the arguments the model may pass. This tool takes none, so `{ type: 'object' }` — an object with nothing in it — is the whole schema. The handler returns an object, and that object is what the model reads.

		`kind: 'query'` says the tool only reads. Queries the model asks for together run in parallel; without it a tool defaults to `'action'` and runs serially, one after another. Tag your read-only tools and a model that asks for six of them at once gets its answer in the time of the slowest, not the sum. See [Kinds and scheduling](#kinds-and-scheduling).


		### Errors in handlers

		There are exactly two outcomes for a failure, and the error code alone decides which.

Uh oh!

Conversation

BoDonkey commented Sep 8, 2026

Please indicate which branch this PR should merge into:

Summary

What are the specific steps to test this change?

What kind of change does this PR introduce?

Make sure the PR fulfills these requirements:

Uh oh!

linear Bot commented Sep 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myovchev Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BoDonkey Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

myovchev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

myovchev Sep 9, 2026 •

edited

Loading

BoDonkey Sep 9, 2026 •

edited

Loading