collective.aitools 1.0.0__py3-none-any.whl

collective/aitools/AGENTS.md

@@ -0,0 +1,289 @@
+# AGENTS.md — collective.aitools package source
+
+Notes for the add-on source itself. Read [`../../../AGENTS.md`](../../../AGENTS.md)
+(backend) and the repo root `AGENTS.md` first. **Update this file whenever you
+add or change code under `src/collective/aitools/`** — that is the maintenance
+rule from the backend guide, applied here.
+
+## The AI tools framework
+
+The product's features are **AI tools**: each is a named utility providing
+[`IAITool`](interfaces.py), enabled/configured from the "AI Tools" control
+panel, and reaching a model through the `collective.aisettings` `IAIService`
+utility (never an LLM SDK directly). When no model is configured the tool
+passes `model=None` so aisettings resolves one by capability.
+
+> Don't confuse our `collective.aitools.interfaces.IAITool` (a high-level
+> editor/visitor feature) with `collective.aisettings`'s `IAITool` (a
+> pydantic-ai function-calling tool offered to an agent mid-run). Different
+> concept, same short name, different package.
+
+### Anatomy of a tool
+
+```
+tools/
+├── base.py            ← AITool base class + get_tool / get_tools / get_tools_settings
+├── recognize_image.py ← RecognizeImageTool (vision → IAIService.analyze_image)
+├── help_me_write.py   ← HelpMeWriteTool (completion → IAIService.chat)
+├── summarize.py       ← SummarizeTool (completion → IAIService.chat)
+├── suggest_tags.py    ← SuggestTagsTool (completion, vocabulary-aware)
+├── assistant.py       ← AssistantTool (agentic chat: IAIService.tool_call loop) — see below
+└── configure.zcml     ← one <utility provides=IAITool name=...> per tool
+```
+
+Most tools do a single model call. **`assistant`** is different: it runs a
+tool-calling *loop* and dispatches to **capabilities** (`capabilities/`) — see
+the "The Assistant (agentic chat) + capabilities" section below.
+
+`AITool` (in [`tools/base.py`](tools/base.py)) reads the registry via the
+`<name>_enabled` / `<name>_model` convention, exposes `is_enabled()`,
+`get_model()`, `available_for(context)`, and `self.service` (the
+`IAIService` utility). Subclasses set `name` / `title` / `description` and
+implement `run(context, **kwargs)`. The public `run` should early-return via
+`self._skip_if_disabled()`.
+
+How tools are *invoked* (event subscriber, action/menu item, async cron) is
+deliberately undecided — tools only expose `run`.
+
+### Adding a new tool — checklist
+
+1. Create `tools/<name>.py` with a subclass of `AITool` (set `name` to match
+   the utility name; implement `run`).
+2. Register it in [`tools/configure.zcml`](tools/configure.zcml) as a
+   `<utility ... provides="collective.aitools.interfaces.IAITool"
+   name="<name>" />`.
+3. Add `<name>_enabled` (Bool) and, if it uses a model, `<name>_model`
+   (TextLine) to [`IAIToolsSettings`](interfaces.py) — plus any extra config
+   fields the tool needs (e.g. `recognize_image_prompt`).
+4. The control panel ([`controlpanels/ai_tools.py`](controlpanels/ai_tools.py))
+   renders the new fields automatically (it's bound to the whole schema). No
+   change needed there.
+5. The registry records are created by `<records interface=...IAIToolsSettings />`
+   in [`profiles/default/registry/main.xml`](profiles/default/registry/main.xml) —
+   already wired, but **bump the profile version in
+   `profiles/default/metadata.xml` and add an upgrade step under `upgrades/`**
+   so existing sites get the new records.
+6. Add tests under `backend/tests/tools/` (registration, enable/disable,
+   model resolution, and a `run` test with the `fake_service` fixture pattern).
+7. Update this file.
+
+## The Assistant (agentic chat) + capabilities
+
+The `assistant` tool ([`tools/assistant.py`](tools/assistant.py)) is a chat
+assistant for authenticated users. Unlike the other tools it is **agentic**: it
+hands the model a set of *capabilities* (function/tool-calling schemas), runs
+whichever the model asks for, feeds the results back, and repeats until the
+model produces a final answer (capped at `MAX_STEPS`). It reaches the model
+through `IAIService.tool_call(messages, tools, …)` — the OpenAI-style
+tool-calling surface — never an SDK directly.
+
+### Capabilities
+
+A **capability** is the assistant's equivalent of a tool, but exposed *to the
+model* as a callable function. Each is a named utility providing
+[`IAIAssistantCapability`](interfaces.py), under `capabilities/`:
+
+```
+capabilities/
+├── base.py          ← AICapability base + get_capability / get_capabilities / manifest_for
+├── search_site.py   ← search_site   (permission View; read-only catalog search)
+├── where_to_add.py  ← where_to_add  (permission cmf.ModifyPortalContent; suggest folders)
+├── propose_draft.py ← propose_draft (permission cmf.ModifyPortalContent; AI-drafts, proposes only)
+├── types.py         ← resolve_portal_type + IContentTypeSynonyms extension point
+└── configure.zcml   ← one <utility provides=IAIAssistantCapability name=...> per capability
+```
+
+`AICapability` ([`capabilities/base.py`](capabilities/base.py)) sets `name`,
+`description` (sent to the model), `parameters` (a JSON Schema for the call
+args), and `permission` (a Zope permission). It exposes `allowed_for(context)`
+(a real `checkPermission`), `tool_schema()` (the OpenAI function definition),
+and `run(context, request, **kwargs)` returning a JSON-serializable result.
+
+### Security model — read this before adding a capability
+
+- **The manifest is a filter; `run` is the enforcement.** `manifest_for(context)`
+  only offers the model the capabilities the current user is allowed to use, but
+  `AssistantTool._run_capability` **re-checks `allowed_for` before every call**
+  and returns an error payload (not a raise) if it fails. A hallucinated or
+  malicious tool call can never do something the user can't.
+- **No writes inside the loop.** A capability that would change content must
+  only *propose* it. `propose_draft` validates + generates but creates nothing;
+  the proposal bubbles up (`result["proposal"]`) to the widget as a confirm
+  card. The actual write happens in a separate, explicit, permission-gated
+  endpoint (`@aitools-assistant-apply`) that **re-validates server-side** — the
+  client's proposal is untrusted, so tampering can't escalate.
+
+### Content-type synonyms (extensible)
+
+`resolve_portal_type(value)` ([`capabilities/types.py`](capabilities/types.py))
+lets the model/editor use loose type names. Precedence: exact id →
+case-insensitive id → type title → synonyms; it only ever returns a type that
+exists on the site. Synonyms come from the built-in `TYPE_SYNONYMS` **plus**
+every registered [`IContentTypeSynonyms`](interfaces.py) utility, merged by
+`collect_synonyms()` (add-on entries override built-ins on conflict).
+Add-ons that ship content types register their own provider (subclass
+`SynonymProvider`, set `synonyms`, register a `<utility>`) to teach the
+assistant friendly names — no change to this package.
+
+### Adding a new capability — checklist
+
+1. Create `capabilities/<name>.py` subclassing `AICapability`; set `name`,
+   `description`, `parameters` (JSON Schema), `permission`; implement `run`.
+2. Register it in [`capabilities/configure.zcml`](capabilities/configure.zcml)
+   as `<utility ... provides="collective.aitools.interfaces.IAIAssistantCapability"
+   name="<name>" />`.
+3. Read-only? Safe to run in the loop. Does it write? Return a `proposal`
+   instead and add a handler to `AssistantApply` (`services/assistant.py`) that
+   re-validates and performs the write.
+4. Add tests; update this file.
+
+### REST endpoints
+
+- `@aitools-assistant` (POST, permission `zope2.View`) — drives the `assistant`
+  tool over the client's `{messages}` history; returns `{reply, steps,
+  proposals}`. History is sanitized/clamped server-side; the system prompt and
+  tool turns are added by the tool, never taken from the client.
+- `@aitools-assistant-apply` (POST, permission `cmf.ModifyPortalContent`) —
+  applies a user-confirmed `{proposal}`. Implements `create_draft` (re-validates
+  via `propose_draft.validate_draft`, creates a private draft, sets the body
+  only on types that have a `text` RichText field). Add more proposal types
+  here.
+
+> The chat endpoint is gated at `View` (so the authenticated members the viewlet
+> targets can chat; capabilities self-gate). Anonymous rate-limiting is **not**
+> done yet — see [What's deferred](#whats-deferred).
+
+### Classic-UI chat widget
+
+A floating chat widget, separate from the edit-form tools:
+
+- **Viewlet** ([`browser/assistant.py`](browser/assistant.py)) — renders the
+  trigger in `IPortalFooter` when the tool is enabled and the user is
+  **authenticated** (`not api.user.is_anonymous()` — deliberately *not* a
+  permission check, since the viewlet runs on the root where editor perms may be
+  absent). Emits config incl. both endpoints, translated labels, and a
+  `plone.protect` CSRF `token` (`createToken()`).
+- **Pattern** ([`resources/js/assistant.pattern.js`](../../../resources/js/assistant.pattern.js))
+  — a launcher + toggleable panel with chat bubbles, proposal confirm cards, and
+  a "Start new chat" (↻) button. The transcript and open/closed state persist in
+  **sessionStorage**, so navigating (a full reload) keeps the conversation and
+  re-opens the widget. Assistant replies render through the safe Markdown helper
+  [`resources/js/lib/markdown.js`](../../../resources/js/lib/markdown.js)
+  (HTML-escaped first, then links/emphasis; link hrefs scheme-checked).
+- **CSRF** — writes (the apply request) require the token; the pattern sends it
+  via the `X-CSRF-TOKEN` header (`postJSON`'s `extraHeaders` arg). `postJSON`
+  lives in [`lib/ui.js`](../../../resources/js/lib/ui.js).
+
+## The AI Tools control panel
+
+[`controlpanels/ai_tools.py`](controlpanels/ai_tools.py) mirrors the
+`collective.aisettings` "AI Settings" panel exactly: a `RegistryEditForm`
+(`IAIToolsSettings`) wrapped with `layout.wrap_form` for classic Plone, plus a
+`RegistryConfigletPanel` adapter named `ai-tools` for the Volto REST surface
+(`@controlpanels/ai-tools`). The Volto widget itself is not built yet — that's
+the deferred frontend work.
+
+## Classic-UI edit-form integration (editor tools)
+
+Editor-facing UI is built as **Patternslib patterns** bundled with webpack (the
+same setup other ESP packages use, e.g. `collective.alerts`). Each tool is a
+REST endpoint + a viewlet that emits a Patternslib *trigger element* + a pattern
+in the bundle. There are four edit-form tools:
+
+| Tool | Endpoint | Button fills |
+| --- | --- | --- |
+| Help me write | `@aitools-help-me-write` | TinyMCE body (draft / rewrite) |
+| Get image details | `@aitools-recognize-image` | Title / Description / Tags from an image |
+| Summarize | `@aitools-summarize` | Description from the body text |
+| Suggest tags | `@aitools-suggest-tags` | Tags from the body text (vocabulary-aware) |
+
+- **REST endpoints** — `services/*.py`, all `for="*"`, permission
+  `cmf.ModifyPortalContent`; each just drives its tool and returns `{result}` /
+  `{error}`. Model choice / prompts / the enabled gate stay server-side. The
+  text tools take the current form text in the body (`{text}`) since the content
+  may be unsaved; recognize-image takes the chosen `{image}` data-URI.
+- **Viewlets** — `browser/*.py` render (in `IPortalFooter`, only on edit/add
+  forms and only when the tool is enabled) a hidden `<div class="pat-aitools-…">`
+  whose `data-pat-aitools-…` attribute carries the JSON config (endpoint,
+  translated labels, …). No script/CSS is injected by the viewlet — the bundle
+  is loaded globally by the resource registry.
+- **Patterns** (bundle source under [`resources/`](../../../resources), *not*
+  `browser/static`): `help-me-write.pattern.js` hooks the global `window.tinymce`
+  registry; `recognize-image.pattern.js` attaches a button per image file field;
+  `summarize.pattern.js` / `suggest-tags.pattern.js` are built from the shared
+  `lib/content-tool.js` factory (read body text via `lib/fields.getBodyText` →
+  POST → fill one empty field). Shared field/widget logic (locating widgets,
+  fill-if-empty, the select2 tags API) lives in `lib/fields.js`; the button+status
+  UI in `lib/ui.js`. All tools fill target fields **only when empty**. SCSS is
+  imported by the patterns.
+
+### Shared backend helpers
+
+- `tools/text.py` — `get_body_text(context)` (title + description + every
+  RichText field, HTML-stripped, capped) and `clean_tags()` (trim / de-dupe /
+  clamp), reused by the tools and the CLI scripts.
+- `backfill.py` — `setup_admin` / `resolve_site` / `run_backfill(site,
+  process_item, …)`: the catalog-walk + tally + periodic-commit loop behind every
+  `scripts/*.py` backfill (recognize-images, summarize-content, suggest-tags).
+
+### Building the bundle
+
+Source is ES6 in `backend/resources/`; webpack (via `@patternslib/dev`) compiles
+it to `browser/static/aitools-remote.min.js` (module-federation remote entry).
+That output **is committed** and ships in the wheel.
+
+```sh
+make install-npm       # npm install (first time)
+make build-resources   # npm run build  → browser/static/aitools-*.min.js
+make watch-resources   # rebuild on change
+make check-resources   # CI: build + fail if the committed bundle is stale
+```
+
+Wiring: `resources/index.js` → `resources/aitools-config.js` imports the
+patterns and calls `registry.init()`. The bundle is registered as
+`plone.bundles/aitools` in
+[`profiles/default/registry/resources.xml`](profiles/default/registry/resources.xml)
+pointing at `++plone++collective.aitools/aitools-remote.min.js`; the
+`++plone++collective.aitools` static directory is declared with `<plone:static>`
+in [`browser/configure.zcml`](browser/configure.zcml).
+
+When you add another edit-form tool, follow the same endpoint + viewlet-trigger
++ pattern trio. The TinyMCE selection/replacement helpers and the field-fill
+helpers in the patterns are the reusable parts.
+
+Registry records use **no prefix** (keyed
+`collective.aitools.interfaces.IAIToolsSettings.<field>`), matching aisettings.
+
+## collective.aisettings coupling
+
+- [`dependencies.zcml`](dependencies.zcml) `<include>`s `collective.aisettings`
+  so its `IAIService` utility is registered (it also auto-includes in a real
+  site via `plone.autoinclude`; the explicit include is what makes it load in
+  the test layer).
+- [`profiles/default/metadata.xml`](profiles/default/metadata.xml) depends on
+  `profile-collective.aisettings:default` so installing this add-on installs
+  aisettings too.
+- Both this package's and aisettings' `setuphandlers/initial.py` import
+  `plone.exportimport` (Plone 6.1 core, for example-content import). The dev
+  venv must have it; if a fresh `make install` lacks it, install
+  `plone.exportimport` (matching aisettings' pin, 2.0.1).
+
+## What's deferred
+
+- **Embeddings tool** — intentionally not implemented yet (vector
+  storage/proximity-search backend undecided; `collective.vectorsearch`
+  exists but computes embeddings locally via FastEmbed rather than through
+  aisettings). Once available, `search_site` should rank semantically.
+- **Volto counterparts** of these tools, the assistant widget, and the
+  control-panel widget.
+- **Assistant hardening** — anonymous access + rate-limiting/abuse controls for
+  the chat endpoint (today it's authenticated-only by viewlet, `View` by
+  endpoint); streaming replies; more `apply` proposal types beyond
+  `create_draft`; showing `steps` in the widget.
+
+## Tests
+
+`backend/tests/tools/test_tools.py` and
+`backend/tests/controlpanels/test_ai_tools.py`. The `fake_service` fixture
+swaps the global `IAIService` for a recorder so `run` can be asserted without
+a network/model. Run with `make test` from `backend/`.

collective/aitools/__init__.py

@@ -0,0 +1,14 @@
+"""Init and utils."""
+
+from zope.i18nmessageid import MessageFactory
+
+import logging
+
+
+__version__ = "1.0.0"
+
+PACKAGE_NAME = "collective.aitools"
+
+_ = MessageFactory(PACKAGE_NAME)
+
+logger = logging.getLogger(PACKAGE_NAME)

collective/aitools/backfill.py

@@ -0,0 +1,110 @@
+"""Shared catalog-walk helper for the CLI backfill scripts.
+
+The ``scripts/*.py`` entry points (run via ``zconsole run``) bind the admin
+user, resolve the Plone site and then hand a per-item callable to
+:func:`run_backfill`, which walks the catalog subtree, tallies outcomes and
+commits periodically. Keeping the walk here (rather than in each script) means
+the scripts stay tiny and the logic is import-testable.
+"""
+
+from AccessControl.SecurityManagement import newSecurityManager
+
+import transaction
+
+
+def setup_admin(app):
+    """Bind the Zope ``admin`` user as the acting user. Returns the user."""
+    admin = app.acl_users.getUserById("admin")
+    if admin is None:
+        raise SystemExit("No 'admin' user found; cannot run.")
+    newSecurityManager(None, admin.__of__(app.acl_users))
+    return admin
+
+
+def resolve_site(app, site_id):
+    """Return the Plone site object, setting it as the active local site."""
+    from zope.component.hooks import setSite
+
+    site = app.get(site_id)
+    if site is None:
+        raise SystemExit(f"Plone site {site_id!r} not found under the app root.")
+    setSite(site)
+    return site
+
+
+def resolve_path(site, path):
+    """Turn a user-supplied ``--path`` into an absolute catalog path.
+
+    Accepts an absolute path ("/Plone/news") or one relative to the site
+    ("news"); an empty path means the whole site.
+    """
+    site_path = "/".join(site.getPhysicalPath())
+    if not path:
+        return site_path
+    if not path.startswith("/"):
+        path = "/" + path
+    if path == site_path or path.startswith(site_path + "/"):
+        return path
+    return site_path + path
+
+
+def run_backfill(
+    site,
+    process_item,
+    *,
+    path="",
+    dry_run=False,
+    commit_every=10,
+    limit=0,
+):
+    """Walk the catalog subtree and apply ``process_item`` to each object.
+
+    ``process_item(obj)`` must return one of ``"updated"``, ``"skipped"`` or
+    ``"failed"`` and is responsible for its own field logic (it should not
+    commit). Returns a tally dict with keys ``processed``, ``updated``,
+    ``skipped`` and ``failed``.
+    """
+    catalog = site.portal_catalog
+    target_path = resolve_path(site, path)
+    print(f"Scanning {target_path!r} ...")
+
+    tally = {"processed": 0, "updated": 0, "skipped": 0, "failed": 0}
+    for brain in catalog(path={"query": target_path}):
+        try:
+            obj = brain.getObject()
+        except Exception as exc:
+            print(f"  ! {brain.getPath()}: could not load ({exc})")
+            tally["failed"] += 1
+            continue
+
+        try:
+            outcome = process_item(obj)
+        except Exception as exc:
+            print(f"  ! {obj.absolute_url()}: failed ({exc})")
+            tally["failed"] += 1
+            continue
+
+        if outcome is None:
+            continue  # not applicable to this item; don't count it
+
+        tally["processed"] += 1
+        tally[outcome] += 1
+        due = commit_every and tally["updated"] % commit_every == 0
+        if outcome == "updated" and not dry_run and due:
+            transaction.commit()
+
+        if limit and tally["processed"] >= limit:
+            print(f"Reached --limit {limit}; stopping.")
+            break
+
+    if dry_run:
+        transaction.abort()
+    else:
+        transaction.commit()
+
+    print(
+        "Done. processed={processed} updated={updated} "
+        "skipped={skipped} failed={failed}".format(**tally)
+        + (" (dry-run, nothing written)" if dry_run else "")
+    )
+    return tally

collective/aitools/browser/assistant.py

@@ -0,0 +1,66 @@
+"""Viewlet that mounts the classic-UI chat "Assistant" widget.
+
+Renders (site-wide, in ``IPortalFooter``) the Patternslib trigger for the chat
+widget when the ``assistant`` tool is enabled and the visitor is *authenticated*
+(anonymous visitors don't get the widget in this first, editor-focused slice).
+We deliberately gate on "logged in or not" rather than a permission, because
+the viewlet is rendered on the portal root where an editor permission may not
+be granted; the individual capabilities enforce their own permissions.
+"""
+
+from collective.aitools import _
+from collective.aitools.tools import get_tool
+from plone import api
+from plone.app.layout.viewlets.common import ViewletBase
+from plone.protect.authenticator import createToken
+from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
+from zope.i18n import translate
+
+import json
+
+
+class AssistantViewlet(ViewletBase):
+    index = ViewPageTemplateFile("templates/assistant_viewlet.pt")
+
+    def available(self) -> bool:
+        tool = get_tool("assistant")
+        if tool is None or not tool.is_enabled():
+            return False
+        # Show only to authenticated users (not anonymous). No permission check:
+        # the viewlet renders on the root, where editor perms may be absent.
+        return not api.user.is_anonymous()
+
+    def render(self):
+        if not self.available():
+            return ""
+        return self.index()
+
+    def endpoint_url(self) -> str:
+        return f"{self.context.absolute_url()}/@aitools-assistant"
+
+    def apply_url(self) -> str:
+        return f"{self.context.absolute_url()}/@aitools-assistant-apply"
+
+    def config_json(self) -> str:
+        t = lambda msg: translate(msg, context=self.request)
+        return json.dumps({
+            "endpoint": self.endpoint_url(),
+            "applyEndpoint": self.apply_url(),
+            # CSRF token for the write (apply) request; plone.protect accepts
+            # it via the X-CSRF-TOKEN header. Freshly minted per page render.
+            "token": createToken(),
+            "labels": {
+                "title": t(_("Assistant")),
+                "open": t(_("Open the assistant")),
+                "close": t(_("Close")),
+                "new_chat": t(_("Start new chat")),
+                "placeholder": t(_("Ask me anything about this site…")),
+                "send": t(_("Send")),
+                "loading": t(_("Thinking…")),
+                "error": t(_("Something went wrong. Please try again.")),
+                "create": t(_("Create draft")),
+                "creating": t(_("Creating…")),
+                "created": t(_("Draft created:")),
+                "open_item": t(_("Open")),
+            },
+        })

collective/aitools/browser/configure.zcml

@@ -0,0 +1,57 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:browser="http://namespaces.zope.org/browser"
+    xmlns:plone="http://namespaces.plone.org/plone"
+    i18n_domain="collective.aitools"
+    >
+
+  <!-- Webpack build output (Patternslib bundle) served under
+       ++plone++collective.aitools, registered as a Plone bundle in
+       profiles/default/registry/resources.xml. -->
+  <plone:static
+      directory="static"
+      name="collective.aitools"
+      type="plone"
+      />
+
+  <browser:viewlet
+      name="collective.aitools.help_me_write"
+      manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
+      class=".help_me_write.HelpMeWriteViewlet"
+      permission="zope2.View"
+      layer="..interfaces.IBrowserLayer"
+      />
+
+  <browser:viewlet
+      name="collective.aitools.recognize_image"
+      manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
+      class=".recognize_image.RecognizeImageViewlet"
+      permission="zope2.View"
+      layer="..interfaces.IBrowserLayer"
+      />
+
+  <browser:viewlet
+      name="collective.aitools.summarize"
+      manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
+      class=".summarize.SummarizeViewlet"
+      permission="zope2.View"
+      layer="..interfaces.IBrowserLayer"
+      />
+
+  <browser:viewlet
+      name="collective.aitools.suggest_tags"
+      manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
+      class=".suggest_tags.SuggestTagsViewlet"
+      permission="zope2.View"
+      layer="..interfaces.IBrowserLayer"
+      />
+
+  <browser:viewlet
+      name="collective.aitools.assistant"
+      manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
+      class=".assistant.AssistantViewlet"
+      permission="zope2.View"
+      layer="..interfaces.IBrowserLayer"
+      />
+
+</configure>

collective/aitools/browser/help_me_write.py

@@ -0,0 +1,70 @@
+"""Viewlet that emits the classic-UI "Help me write" Patternslib trigger.
+
+Only renders when the ``help_me_write`` tool is enabled and the current view
+is an edit or add form. It emits a hidden element carrying a small JSON config
+(endpoint URL, the operations with their labels and whether they need typed
+input, and the translated UI strings) in its ``data-pat-aitools-help-me-write``
+attribute. The ``aitools`` bundle (built from ``resources/``) picks that up and
+builds the TinyMCE button. The bundle itself is loaded globally through the
+resource registry, so the viewlet no longer injects any script/CSS.
+"""
+
+from collective.aitools import _
+from collective.aitools.tools import get_tool
+from collective.aitools.tools.help_me_write import OPERATION_TITLES
+from collective.aitools.tools.help_me_write import OPERATIONS_REQUIRING_INPUT
+from plone.app.layout.viewlets.common import ViewletBase
+from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
+from zope.i18n import translate
+
+import json
+
+
+class HelpMeWriteViewlet(ViewletBase):
+    index = ViewPageTemplateFile("templates/help_me_write_viewlet.pt")
+
+    def _is_form_view(self) -> bool:
+        url = (self.request.get("ACTUAL_URL", "") or self.request.getURL()).rstrip("/")
+        last = url.rsplit("/", 1)[-1]
+        return last in ("edit",) or "++add++" in url
+
+    def available(self) -> bool:
+        tool = get_tool("help_me_write")
+        if tool is None or not tool.is_enabled():
+            return False
+        return self._is_form_view()
+
+    def render(self):
+        if not self.available():
+            return ""
+        return self.index()
+
+    # -- template helpers --
+
+    def endpoint_url(self) -> str:
+        return f"{self.context.absolute_url()}/@aitools-help-me-write"
+
+    def _operations(self):
+        return [
+            {
+                "id": op_id,
+                "label": translate(title, context=self.request),
+                "needsInput": op_id in OPERATIONS_REQUIRING_INPUT,
+            }
+            for op_id, title in OPERATION_TITLES.items()
+        ]
+
+    def config_json(self) -> str:
+        t = lambda msg: translate(msg, context=self.request)
+        return json.dumps({
+            "endpoint": self.endpoint_url(),
+            "operations": self._operations(),
+            "labels": {
+                "button": t(_("Help me write")),
+                "send": t(_("Send")),
+                "loading": t(_("Generating...")),
+                "error": t(_("Something went wrong. Please try again.")),
+                "noText": t(_("Select or enter some text first.")),
+                "draftPlaceholder": t(_("What do you want to write about?")),
+            },
+        })

collective/aitools/browser/recognize_image.py

@@ -0,0 +1,57 @@
+"""Viewlet that emits the classic-UI "Get image details" Patternslib trigger.
+
+Only renders when the ``recognize_image`` tool is enabled and the current view
+is an edit or add form. It emits a hidden element carrying a small JSON config
+(endpoint URL and the translated UI strings) in its
+``data-pat-aitools-recognize-image`` attribute. The ``aitools`` bundle (built
+from ``resources/``) picks that up and adds a "Get image details" button next
+to each image file field. The bundle itself is loaded globally through the
+resource registry, so the viewlet no longer injects any script/CSS.
+"""
+
+from collective.aitools import _
+from collective.aitools.tools import get_tool
+from plone.app.layout.viewlets.common import ViewletBase
+from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
+from zope.i18n import translate
+
+import json
+
+
+class RecognizeImageViewlet(ViewletBase):
+    index = ViewPageTemplateFile("templates/recognize_image_viewlet.pt")
+
+    def _is_form_view(self) -> bool:
+        url = (self.request.get("ACTUAL_URL", "") or self.request.getURL()).rstrip("/")
+        last = url.rsplit("/", 1)[-1]
+        return last in ("edit",) or "++add++" in url
+
+    def available(self) -> bool:
+        tool = get_tool("recognize_image")
+        if tool is None or not tool.is_enabled():
+            return False
+        return self._is_form_view()
+
+    def render(self):
+        if not self.available():
+            return ""
+        return self.index()
+
+    # -- template helpers --
+
+    def endpoint_url(self) -> str:
+        return f"{self.context.absolute_url()}/@aitools-recognize-image"
+
+    def config_json(self) -> str:
+        t = lambda msg: translate(msg, context=self.request)
+        return json.dumps({
+            "endpoint": self.endpoint_url(),
+            "labels": {
+                "button": t(_("Get image details")),
+                "loading": t(_("Analyzing image...")),
+                "error": t(_("Something went wrong. Please try again.")),
+                "noImage": t(_("Choose an image first.")),
+                "done": t(_("Filled in the empty fields.")),
+                "readError": t(_("Could not read the selected image.")),
+            },
+        })