TXMBot — AI Agent

LLM chat assistant embedded in PyStream that can read live beamline state through a tool catalog and, with an explicit Yes/No confirmation, run allowlisted IOC-restart scripts. Appears as AI in the bl32ID toolbar.

The agent speaks to a Gateway using either the Anthropic Messages API or the OpenAI Chat Completions protocol. The user picks protocol, fills in the Gateway URL and API key, clicks Connect / refresh models, picks a model, then chats.

What the agent can do

  • Read EPICS PVs, motors, and detector image stats.

  • Diagnose stuck PVs, motors, or frozen detector streams.

  • Read markdown notes, PV aliases, and per-plugin settings from ~/.pystream/.

  • Fetch registered web docs and live status pages.

  • List recent XANES2D HDF5 master files and read their metadata.

  • Restart an IOC by running a user-registered script — gated by a Yes/No dialog that the model cannot bypass.

Every tool call shows up in the transcript so you can audit what produced any number the agent quotes.

User-editable files

All under ~/.pystream/ (auto-created on first launch, never overwritten):

File

Purpose

docs/*.md

Reference notes the agent can read/search

pv_aliases.json

Friendly PV names + $(P)$(M) macros

doc_urls.json

Static reference URLs

status_pages.json

Live status page URLs

ioc_scripts.json

IOC restart allowlist — empty by default

bl32ID_settings.json

Gateway URL, API key, model, system prompt

The security boundary for write actions is ioc_scripts.json. Only IOCs listed there can be restarted, and each restart still pops a confirmation dialog.

Adding a new tool

Edit src/pystream/beamlines/bl32ID/agent_tools.py:

  1. Write a function tool_my_thing(...) -> dict that returns a dict (and catches its own exceptions, returning {"error": ...}).

  2. Append an entry to the TOOLS list at the bottom with name, description, JSON schema, and func.

  3. If the tool mutates state, also add its name to WRITE_TOOLS so it goes through the confirmation gate.

Both protocol dispatchers pick up new entries automatically.