Tools
=====

Reusable ``@tool`` capabilities agents can invoke.

Basic
-----

Mathematical and date/time utilities:

.. automodule:: agency.tools.basic
   :members:
   :undoc-members:
   :show-inheritance:

Web
---

Web scraping and content extraction:

.. automodule:: agency.tools.web
   :members:
   :undoc-members:
   :show-inheritance:

Help / documentation
--------------------

Read the built Sphinx singlehtml manual (same source as the Help desktop app):

.. automodule:: agency.tools.help
   :members:
   :undoc-members:
   :show-inheritance:

Database
--------

Database query and schema tools:

.. automodule:: agency.tools.database
   :members:
   :undoc-members:
   :show-inheritance:

Agent
-----

Agent management tools:

.. automodule:: agency.tools.agent
   :members:
   :undoc-members:
   :show-inheritance:

Human
-----

HITL interrupt tool:

.. automodule:: agency.tools.human
   :members:
   :undoc-members:
   :show-inheritance:

Python interpreter
------------------

Python code execution tools:

.. automodule:: agency.tools.interpreter
   :members:
   :undoc-members:
   :show-inheritance:

Icons
-----

Local **ComfyUI** (Compose ``comfy``, SD 1.5) draws pixels on the GPU.
Ollama ``x/flux2-klein`` / ``x/z-image-turbo`` when the runtime supports
image gen; otherwise OpenAI Images or fal FLUX. The bitmap is keyed to a
128×128 white-on-transparent dock glyph. Optional ``tool_id`` is the catalog
id (``tools.agent.create_agent``) or a unique leaf (``create_agent``); a miss
still saves the PNG and lists closest rows. Each catalog leaf maps to a
concrete pictogram (clock, calculator) so SD 1.5 is not asked to draw Spanish
abstractions. The tool result echoes pictogram, SD prompt, negative and
checkpoint. ``list_catalog_tools`` (secretary) finds tools without an icon.

.. automodule:: agency.tools.icon
   :members:
   :undoc-members:
   :show-inheritance:

Pictures
--------

``generate_image`` is the color picture tool (256–1024, default 768).
Local ComfyUI first; pin ``model=fal-ai/flux-lora`` (or ``fal-ai/flux/schnell``)
when ``FAL_KEY`` is set. Saves to Photos. Call ``show_media`` with the photo id
so the operator Media player shows it. Optional ``display`` assigns the
kiosk. Do not use the icon tool for maps or posters.

``edit_image`` changes existing Photos rows (or whatever is on Media).
One picture: FAL FLUX ``/image-to-image`` first; ComfyUI LoadImage + ``denoise``
if FAL is down. Default ``strength`` 0.35. Source aspect is kept (long side
≤ 1024). Two or more ``photo_ids``: FLUX Kontext multi
(``fal-ai/flux-pro/kontext/max/multi``) with data-URI ``image_urls``. Needs
``FAL_KEY``; no Comfy fallback. Result is a new generated photo on Media.

.. automodule:: agency.tools.image
   :members:
   :undoc-members:
   :show-inheritance:

Secretary
---------

High-level operator tools bound to the secretary runtime (``user_id``,
``agent_id``, ``thread_id``). They never take ambient admin. Desktop chrome
uses Agency Bus: ``open_window`` / ``close_window`` publish
``desktop.<address>.visibility.changed``; ``show_media`` publishes
``desktop.media.now_playing.changed`` and opens the Media singleton. See
:doc:`../../veronica`.

.. automodule:: agency.tools.secretary
   :members:
   :undoc-members:
   :show-inheritance:

Display
-------

Kiosk operator tools. An agent inspects screens/views/scopes, publishes a View,
assigns it to **one named display**, and mutates Scope properties (the live slide).
Never fan-out to every kiosk. Protected (padlock) screens and views refuse agent
writes. ``show_image_on_display`` is the presentation shortcut (Media image +
``image_url``) for a single named screen. Compose templates with
``<agency-include namespace="display.example.clock">``. Resolve by name,
slug, or namespace — never Channels group names.

.. automodule:: agency.tools.display
   :members:
   :undoc-members:
   :show-inheritance: