The words of this tutorial, step by step. The text lives in src/smappy/tutorial/topics/; the directions it follows are in src/smappy/tutorial/STYLE.md.
1. card: An AI assistant: asking SMAPpy in plain words
An AI assistant such as Claude or Codex can work with SMAPpy. You ask in plain words; it reads the help pages, tries plugins on a copy of your data and looks at the results.
It runs in its own program, with your own account. SMAPpy has no AI of its own.
spoken: An AI assistant can work with SMAPpy: you ask in plain words, and it uses SMAPpy's plugins for you.
2. card: Help in three ways
Tell it what you need, as you would tell a colleague. It helps in one of three ways, as you ask:
- It explains how to do it in SMAPpy: which plugin, which settings, and what the numbers mean.
- It suggests the plugin with its settings, and shows you where in the picture. You open it and press Run.
- It does it for you, step by step, when you let it.
spoken: It helps in three ways: it explains how, it suggests the plugin and its settings, or it does it for you.
3. Assistant, Start assistant, or Ctrl+Shift+A, starts it beside the picture, already connected.
4. The first time it asks two things: which assistant, and the folder it works in. Keep that folder the same: its conversations go with it. That is all there is to set up.
5. card: Its own window
The assistant opens in a terminal beside the picture. If it is not installed yet, the terminal offers to install it: press Enter.
The first time, it asks you to sign in with your account. Then you type your questions there.
spoken: It opens in a window of its own. If it is not installed yet, that window offers to install it.
6. The button in the picture's toolbar says that an assistant is connected, and that it may only suggest.
7. card: It explains
Ask how something is done, and it answers like a colleague who has read every help page: which plugin, which settings, and why.
Nothing changes. You do it yourself, and learn where it is.
spoken: Ask how something is done, and it explains: which plugin, which settings, and why.
8. card: Ask in plain words
You type a question in the assistant's window. It looks up which plugins measure that, reads their help pages and tries them on a copy of the data.
It answers in its window, and shows you in SMAPpy what it found.
spoken: Ask for an answer, and it tries plugins on a copy of the data, and suggests what to run.
9. It can move the view to show you what it means. That changes no data, so it does it at once.
10. What it would change waits here, under the button, with its reason. You decide.
11. There are two: the arrows step from one to the other.
12. The dash folds the list away, to see the whole picture. The button stays highlighted while something waits.
13. Open shows the plugin with the settings it proposes.
14. Nothing has run yet. Check the settings, change them if you like, and press Run.
15. Your Run carries it out, and the assistant reads the result. The next proposal takes its place.
16. The cross dismisses a proposal. The assistant sees what became of each one.
17. Under the list: suggest, where every change waits for you, and act.
18. In act mode the assistant changes the data itself. Each change can be undone with Edit, Undo. Only you can switch.
19. Settings: which assistant starts, the only folder it may write into, and the mode it starts in.
20. An assistant you start yourself: SMAPpy only listens, and copy command gives the line that connects it, smappy-mcp --attach.
21. card: SMAPpy without the window
The assistant can also use SMAPpy's functions directly, with no window open: on your own files, a whole analysis from the raw localizations to the numbers, step by step.
Connect it once with one line. Then start it in the folder of your data and ask.
spoken: Without the window, the assistant uses SMAPpy's functions directly, on your own files.
22. card: A whole analysis
It opens the file, corrects the drift, finds the pores and fits the labelling efficiency to them. It reads each step's numbers and figures before going on, as you would.
Labelling efficiency 60.2 ± 1.7 %, from 167 pores. Simulated with 60 %.
spoken: It runs the whole analysis, and reads every step's numbers and figures before going on.
23. card: Ending in a chain
What it did, it keeps as a chain of plugins, when you agree. The chain runs again on the next file, or over all of them with smappy-batch.
spoken: It keeps what it did as a chain, to run again on the next file or over all of them.
24. The chain is a plugin like any other, here under Plugins, User.
25. Its window shows the steps. Run it on the next file, and look at the numbers yourself.
26. card: And what no plugin does
Asked whether the molecules are dimmer at the edge of the field, it writes a few lines of Python that call SMAPpy's functions, and runs them. What they printed:
0 to 2 um: median 1297 photons2 to 4 um: median 1295 photons4 to 8 um: median 1263 photons
spoken: For what no plugin does, it writes a few lines of Python with SMAPpy's functions, and runs them.
27. The assistant can also write a plugin for you. Plugins, New plugin starts one; Show my plugin folder opens where yours live.
28. card: Describe it
Your plugin folder holds a file for the assistant, AGENTS.md, that says how a SMAPpy plugin is written.
Start the assistant in that folder and describe what to measure. Its plugin appears under Plugins, User, with no restart.
The tutorial on your own plugins shows it step by step.
spoken: Start the assistant in your plugin folder and describe what to measure: it writes the plugin.
29. card: What to remember
- Assistant, Start assistant: your assistant, beside the picture.
- Tell it what you need: it explains, suggests or does it.
- What it would change waits under its button: Open, then your Run, or the cross.
- suggest or act: only you switch.
- Without the window, with smappy-mcp: a whole analysis of your files, kept as a chain.
- In your plugin folder, for plugins of your own.
- The help page Assistant has the details.
spoken: That is the assistant: ask in plain words, and decide what it may change.